How to improve PyFluent’s solver UX by shifting focus from solver to user

[seanpearsonuk]

Context and intent

This discussion is intended as a design reflection, not a call to action.

We have recently opened several GitHub Issues that propose pragmatic, incremental improvements to parts of the PyFluent API (help text, selective renaming, hiding low-value commands, etc.). Those issues are deliberately scoped to “small wins”.

Here, the goal is different.

This discussion is an attempt to step back and articulate what these concrete problems are symptoms of, using a few representative API sections as examples. The hope is to build a shared vocabulary and mental model around why certain parts of the API feel difficult to use, even for experienced Fluent users, and what general design directions might improve solver UX over time.

This is based on only a cursory review of selected API areas. It is almost certain that many relevant examples have been missed, and that the patterns discussed here are more widespread than the specific sections mentioned.

---

A working hypothesis

A useful way to frame the current PyFluent Solver API is:

The API is a near-direct exposure of Fluent’s internal solver configuration schema, rather than a user-facing conceptual model.

This is not presented as a criticism of Fluent’s internals — which are necessarily complex — but as an observation about where the abstraction boundary currently sits.

Much of the API appears to be structured primarily around:

• solver subsystems,
• internal data ownership,
• and historical GUI or journal structures,

rather than around:

• the questions users are trying to answer,
• the physical concepts they are configuring,
• or the workflows they are following.

The sections below unpack what this looks like in practice.

---

Example: velocity_inlet.momentum as a guiding case

The velocity_inlet.momentum subtree is a useful guiding example, not because it is uniquely problematic, but because it compactly exhibits several recurring patterns.

At first glance, “momentum” sounds like a coherent concept. In practice, the section contains:

• Core velocity specification (magnitude, components, direction)
• Reference frames and coordinate systems
• Acoustic and wave-related models
• Multiphase velocity inputs
• Moving-object velocity settings
• Various specialized solver hooks

From a solver implementation perspective, this grouping is understandable: these settings all touch the momentum equations somewhere downstream.

From a user cognition perspective, however, this creates friction:

• unrelated physical models are colocated,
• conditional settings are interleaved with unconditional ones,
• and there is little semantic guidance about when or why a setting is relevant.

The result is not merely verbosity, but cognitive overload: users must first reverse-engineer the solver’s internal structure before they can confidently use the API.

---

Is deep nesting itself a problem?

One question that naturally arises is whether deeply nested objects are themselves an issue.

The short answer: not inherently.

Deep nesting becomes problematic when it coincides with:

• weak or generic help text,
• naming that reflects implementation rather than meaning,
• and groupings that mix conceptually orthogonal concerns.

In other words, depth amplifies confusion when semantic guidance is missing.

In the current API, “minimal semantic guidance” is not due to a single factor, but to a combination of:

• repetitive or misleading help strings,
• prefixes and acronyms that encode internal history rather than meaning,
• and structural groupings that do not align with user mental models.

---

Static API surface vs. meaningful runtime surface

Another recurring pattern is the gap between:

• the statically discoverable API surface (what inspection shows), and
• the meaningful runtime surface (what is actually relevant for a given model setup).

Because most objects and parameters are always visible:

• users cannot easily tell what is active, conditional, or mutually exclusive,
• cross-dependencies between settings are opaque,
• and documentation alone struggles to compensate.

This is not purely a documentation problem.

Better help text is necessary, but not sufficient. Structural cues — such as grouping, naming, and conditional visibility — play a large role in making an API self-documenting.

---

Solver-oriented structure vs. user-oriented structure

A recurring theme across reviewed sections (velocity_inlet, species, icing, discrete_phase, virtual_blade_model, etc.) is that structure tends to follow:

“Which solver subsystem does this belong to?”

rather than:

“What conceptual decision is the user making?”

This explains patterns such as:

• turbulence settings nested under momentum,
• acoustics appearing alongside basic velocity specification,
• extensive prefixing (fensapice_*, geom_*) inside already-scoped groups,
• and long flat lists of parameters that are only loosely related.

From a user perspective, this makes the API feel less like a model of physics and more like a configuration dump.

---

Progressive disclosure as a design lens

One concept that seems particularly relevant is progressive disclosure.

In this context, it does not simply mean “basic vs. advanced”, but rather:

• exposing concepts in an order that matches user intent,
• delaying specialized or conditional complexity until it is needed,
• and making conceptual boundaries visible even if internal boundaries remain unchanged.

For example, a user-centric mental model of a velocity inlet might distinguish between:

• core flow specification,
• turbulence quantities,
• thermal and species data,
• and specialized models (icing, acoustics, multiphase).

Even if the underlying solver schema cannot be restructured, the way it is presented and described can still move in this direction.

---

What this discussion is not

• It is not a proposal to redesign the entire API.
• It is not a request for breaking changes.
• It is not a claim that Fluent’s internal architecture is “wrong”.

Instead, it is an attempt to articulate why many parts of the API feel harder to use than they need to be, and why incremental improvements (help text, naming, hiding low-value commands) are valuable but incomplete on their own.

---

Why have this discussion?

The value of this discussion is not in producing immediate action items — those already exist elsewhere — but in:

• making implicit design tradeoffs explicit,
• aligning on what “good solver UX” might mean in a Python context,
• and providing a shared frame of reference for future improvements, however small.

If PyFluent is to feel increasingly “Pythonic” and user-oriented over time, these questions of abstraction boundaries and mental models will likely matter just as much as individual fixes.

Comments, alternative perspectives, and counter-examples are very welcome.