Managing unstable solver settings API sections in PyFluent from Fluent 2026R1 onwards

## Background / Context

Fluent 2026R1 is about to be released. A recent review of the solver settings API exposed through PyFluent shows that several sections do not yet meet PyFluent’s usability and discoverability standards, particularly in terms of workflow coherence, help text, and API structure.

These limitations are well understood to be transitional in nature. However, they arrive at a sensitive point in PyFluent’s lifecycle: the project is moving toward its first stable (1.0) release, where users reasonably expect a clear signal about API stability and support level.

Given the timing:

* Fluent 2026R1 will ship with this API in its current form.
* Removing or restructuring the solver settings API before the next release would:

* Break existing user workflows.
* Create instability and testing churn internally.
* Be inconsistent with responsible deprecation and migration practices.

We therefore need a deliberate, transparent strategy for how PyFluent should behave **when used against Fluent 2026R1**, during the long run-up to the next release.

---

## Problem Statement

Currently, PyFluent exposes all solver settings API paths uniformly, regardless of maturity. As a result:

* Users receive no signal that certain API sections are provisional or subject to change.
* Users may unintentionally build production workflows on interfaces that are expected to evolve in the next release.
* PyFluent implicitly presents these API sections as equally stable, which does not reflect reality and harms user trust.

This issue proposes a controlled, backward-compatible mechanism to make API maturity explicit without removing functionality in 2026R1.

---

## Proposed Approach

### 1. Explicit Registry of Unstable API Paths

Within PyFluent, maintain an explicit, centralized list of solver settings API paths that are considered **unstable for Fluent 2026R1**.

Characteristics:

* Paths are identified intentionally (not heuristically).
* The list is version-scoped (e.g. applies when connected to Fluent 2026R1).
* This registry is used only for runtime behavior and user messaging, not for removal.

This provides a single authoritative source for managing transitional API sections.

---

### 2. Runtime Signalling on First Access (Initial Phase)

When a user first accesses an unstable API path within a PyFluent session, emit a **one-time warning**.

Example warning text:

> `"models.virtual_blade_model" exposes an unstable solver settings interface in Fluent 2026R1. This interface is not yet fully released in PyFluent. It is required by PyFluent to evolve in a future Fluent release (targeted for the next release).`

Key properties:

* Triggered lazily (only if the user accesses the path).
* Emitted once per session per path.
* Framed as API maturity and release timing, not user error.

This ensures transparency while preserving backward compatibility and avoiding unnecessary noise.

---

### 3. Optional Opt-In Visibility Controls (Follow-Up Phase)

As a follow-on (potentially closer to PyFluent 1.0), consider allowing unstable API paths to be **hidden from default discovery**, with explicit user opt-in.

Proposed behaviour:

* By default, unstable paths may be omitted from discovery mechanisms (e.g. tab completion, `dir()`).
* Users can explicitly enable them either:

* Globally, or
* Selectively per API path.

Illustrative examples:

```python
pyfluent.enable_unstable_api_sections()
pyfluent.enable_api_path("models.virtual_blade_model")
```

This approach:

* Protects new users from unintentionally relying on unstable interfaces.
* Preserves access for advanced users and internal workflows.
* Creates a clear migration path toward API cleanup in the next Fluent release.

This step is explicitly *not* required for the initial rollout and can be phased in if needed.

---

## Non-Goals

* This issue does **not** propose removing solver settings API sections in Fluent 2026R1.
* This issue does **not** define the final shape of the solver settings API sections in the next Fluent release.
* This issue does **not** attempt to retroactively “fix” Fluent 2026R1.

The goal is controlled exposure and honest signalling, not immediate redesign.

---

## Benefits

* Makes API maturity explicit and user-visible.
* Reduces accidental reliance on unstable interfaces.
* Improves user trust ahead of PyFluent 1.0.
* Allows PyFluent to evolve independently of Fluent’s release cadence.
* Establishes a reusable mechanism for future API transitions.

---

## Open Questions

* Should warnings be enabled by default or configurable?
* Should internal Ansys usage automatically enable unstable API sections?
* How should this mechanism be reflected in documentation and release notes?
* Should this evolve into a more formal “API maturity” concept long-term?

No implementation files or tests are named; start by locating the solver settings API access and discovery entry points, along with Fluent-version handling. Define how a version-scoped unstable-path registry and per-session, per-path warning would work for Fluent 2026R1; done means affected paths remain accessible while first access produces the specified warning only once.

Written by the indexing model from the issue text.