Improving the Fluent Settings API: Structure, Naming, Documentation, and Discoverability

[seanpearsonuk]

Improving the Fluent Settings API: Structure, Naming, Documentation, and Discoverability

Based on a brief study using the as yet unreleased Ansys Fluent 2026R1, this discussion outlines some of the key issues currently affecting the usability and discoverability of the Fluent Solver Settings API, especially within PyFluent. It also proposes a set of clear objectives and remedies to guide API cleanup, documentation improvements, and long-term standardisation.

Although the API has improved significantly, too many sections remain confusing, inconsistent, or undocumented. These issues collectively represent a significant barrier to usability, suggesting that PyFluent may not yet be ready for a stable 1.x release until addressed.

---

1. Guiding Principle: Usability Comes From Intuitive APIs and Good Documentation

We all value usability. For APIs, this comes from two sources:

1. Clean, logical design
2. Clear, high-value documentation

Some parts of the API already get this right. Others are far from intuitive and depend heavily on documentation that doesn’t exist yet.

---

2. Example of a Good Section: results

The results section demonstrates what “good” looks like:

• It has concise but informative top-level help text.
• It contains clear, well-named child categories.
• Each category has coherent help text.
• The patterns repeat consistently all the way to the leaves.
• Its abstractions are consistent (e.g., graphics object creation + display).
• Even without documentation, much of it remains usable because the API is fundamentally self-documenting.

This is what we want for all sections.

---

3. Harder API Domains Need Better Documentation

For this discussion, I’m using the models section as a representative example of a more complex part of the API. (But see the appendix below for full study notes, which also covers a few other API sections.) Physics-related model configuration naturally involves specialised knowledge and multi-step workflows, so these areas can never be fully self-documenting.

Because of their inherent complexity, they require stronger naming conventions, clearer structure, and especially higher-level guidance in the help text. Good API design alone cannot compensate for missing or unclear documentation.

Therefore, “excellent documentation” is not optional. Every physics model should provide:

1. Well-chosen, descriptive names

2. A logical hierarchical structure

3. High-quality help text that goes beyond names/types

4. A top-level workflow explanation, e.g.

   • What the model does
   • Typical steps users must follow
   • What becomes active/inactive based on choices

5. Clarity around obscure or non-standard operations, e.g.

   • The unintuitive virtual_blade_model.apply() (which appears to apply settings without clear prerequisites or workflow guidance)
   • What must be set before calling it
   • What workflow it belongs to

Without top-level guidance, running dir() on a physics model is overwhelming and unhelpful.

---

4. General Design and Documentation Issues

Across the API we see:

• Missing help text
• Useless help text (e.g., “Help”, “Main object”, “Toplevel object”)
• Misleading help text
• Random capitalisation, formatting errors, punctuation errors
• Inconsistent naming patterns
• Repeated names along the path
• Jargon and developer-only notes leaking into help strings
• Undocumented abbreviations

We need:

• Consistent design strategy
• Consistent naming conventions
• Consistent help-text conventions
• Templates for common patterns

We should template help text for:

• Boolean enabled parameters as in energy
• Selection parameters like viscous.model
• Group objects (…_settings, …_options, …_parameters)
• Physics-model top-level help text
• Attributes that accept enumerated values
• Abbreviations (must always be defined)

We should template common API patterns:

• enabled: boolean, never enable
• Consistent naming for group containers
• Consistent patterns for activation/deactivation of submodels
• Server-side generation of repeated boilerplate fields and documentation

---

5. Examples of Good vs. Problematic API Sections

Good / Acceptable

These sections show clean structure, reasonable naming, and decent documentation:

• /setup/models/energy
• /setup/models/viscous (although abbreviations should be defined)
• /setup/models/multiphase (mostly good; needs consistent help text)
• /setup/models/structure

These can serve as reference models (after minor cleanup).

Poor / Needs Significant Work

These sections have structural issues, naming confusion, undocumented abbreviations, missing or misleading help text, or inconsistent patterns:

• /setup/models/discrete_phase
• /setup/models/acoustics
• /setup/models/radiation
• /setup/models/species
• /setup/models/virtual_blade_model (worst usability: unclear workflow + mysterious apply())
• /setup/models/dsmc
• /setup/models/echemistry (especially electrolysis; heavy repetition, unclear abbreviations, inconsistent grouping, doc that reads like internal notes)

A detailed breakdown of these issues is in the attached notes.

---

6. Missing Feature Across All Physics Models: A Top-Level Workflow Description

Every physics model should start with a short help-text template like:

“This group configures the physics model.
To begin, choose a model type using the model field. Available values are listed in the help for that field.
Selecting a model activates only the settings relevant to that choice; other sub-groups remain inactive.
After selecting the model, adjust the active settings to configure behaviour such as …
Refer to external literature when choosing a model and parameters appropriate for your physics.”

Right now no physics model provides this sort of high-level guidance.

---

7. Required Improvements

7.1 API Design Cleanup

• Reduce top-level clutter
• Fix confusing structure
• Remove suffix noise (…_settings, …_options) or standardise it
• Avoid leaking GUI concepts (…_gui, UI-only naming)
• Avoid mysterious operations (e.g., virtual_blade_model.apply)
• Rationalise attributes that repeat the parent name

7.2 Documentation Overhaul

Implement:

• A uniform help-string style
• Proper definitions of abbreviations
• Clear value constraints (static or dynamic)
• Removal of dev-only notes from help text
• Removal of misleading or placeholder text
• Top-level help for every physics model
• Help text for enabling/disabling
• Help text for selection parameters

7.3 Testing Team Action

Tests should validate documented interfaces.
If documentation is insufficient to determine expected behaviour, tests should fail the API. This creates upward pressure to fix documentation before changes ship.

---

8. Recommendations for API Team

Now

• Fix problematic sections (at least virtual_blade_model, acoustics, echemistry, radiation, discrete_phase, species, electrolysis, optics, dsmc)
• Standardise enabling/selection patterns
• Add top-level help text for all physics models
• Remove misleading help text
• Define all abbreviations in every help string
• Introduce consistent naming and grouping
• Expand documentation to include workflows & examples
• Document parameter constraints

Longer Term

• Introduce templating at the API-generation layer
• Enforce naming and help-text standards programmatically

---

9. What Does “Beta Quality” and “Stable Release Quality” Actually Mean for the Settings API?

To make progress predictable and to give the development team clear acceptance criteria, we should explicitly define two quality gates that every exposed API section must pass.

9.1 Beta-quality threshold (minimum bar for public exposure from 2026 R2 onward)

An API section reaches beta quality if the answer to this single question is yes:

Can a typical CFD engineer without Fluent experience and only basic Python knowledge open a PyFluent session, navigate to this section, and — using only help(), dir(), and the object names themselves — successfully figure out and execute the mainstream intended workflow of that section without external documentation or guessing?

Concrete checklist (all must be satisfied):

• No critically misleading, missing, or placeholder help text (e.g., “Help”, “Main object”, “Toplevel object”)
• No severe structural anti-patterns (deeply redundant naming, leaking GUI concepts, mysterious parameter-less methods like apply() with no explanation)

If any of the above is false and blocks the mainstream workflow, the section is not yet beta-ready and should be hidden or clearly marked as experimental.

9.2 Stable-release quality threshold (required for 1.0 and for public exposure from 2027 R1 onward)

Everything from beta quality, plus:

• Full compliance with the upcoming PyFluent Settings API Style Guide (naming conventions, grouping rules, suffix policy, etc.)
• All abbreviations used in object names are defined in the corresponding help text
• Boolean enablement uses the attribute name enabled (not enable, is_enabled, etc.)
• The top-level object has a short but meaningful description (not just “the viscous model”)
• Consistent, templated help text for common patterns (enabled flags, model selectors, option groups, enumerated values)
• All static allowed values or ranges are explicitly documented directly in the help text (or auto-generated from scheme constraints)
• No remaining developer-only notes, internal jargon, or formatting errors in help strings
• The section has been used successfully in at least one non-trivial real-world script contributed or reviewed by the community (optional but strongly encouraged)

Only when an API section clears the stable-release bar should it be considered part of the supported, versioned public API for a 1.x release.

---

10. Actions for PyFluent Team

1. For 2026R2: Following a short transition period, any API section that does not reach a clear beta-quality threshold—in structure, naming, and documentation—will be withdrawn from exposure. These sections can return once they achieve that level of readiness. Any still below beta quality at dev-complete will be excluded from the release.

2. For 2027R1: The same process will apply, but the requirement will be full release quality. Only sections that meet this standard will be exposed in the public API.

---

11. Conclusion

PyFluent has many strong API sections, but too many remain confusing, undocumented, misnamed, or structurally inconsistent.
Based on a brief study, improvements to the physics models section is urgently needed.

A push toward consistency, clarity, standardisation, and high-quality help text will dramatically improve discoverability and reduce user frustration—closing the gap needed for a stable 1.x release.

---

Appendix — Detailed Study Notes

The following notes capture the raw findings from my walkthrough of the API.
They are intentionally exhaustive and path-specific, and are included here to support the high-level points made above.

Items by path:

/ {root}

• too many items (~2x) at this level. many items need to be merged. Already long time reported at the Fluent level.
• capitalizations in some help texts
• design is not an obvious name. The help text does not clarify it. E.g. ansys public website gives this information: The shape optimization process can often be time-consuming, requiring substantial manual inputs and multiple design iterations.
  Adjoint Solver — a free add-on module available with Ansys Fluent — enables shape optimization in a smart and automatic way with minimal turnaround time. Using its unique sensitivity-based algorithm, Adjoint Solver helps optimize your existing design and export the morphed geometry.
  This information can be used to form the basis of help text.

/file
/file/export and /file/import

• The help texts are just Export files and Import files respectively. But these are groups and not methods, so the text is misleading.

/file/export/sc_def_file_settings
/file/export/settings

• These two groups are odd. There is a settings group which would appear to ought to contain
  all types of export settings, so why is there a separate sc_def_file_settings? That's incorrect structuring.
  But then settings actually contains only settings specific to cgns, which means that settings has the wrong name.
  An alternative structure might have /file/export/settings/cgns and /file/export/settings/sc_def (ignoring the poor naming of sc_def for now).
  All of the settings currently under settings are prefixed cgns_ which would be dropped, given this restructure.
  The settings object that contains these cgns settings has the help text "The export settings object" which is misleading.
• The CGNS settings names contain abbreviations. Abbreviations in names have been actively discouraged, but if used with some justification
  (i.e. the abbreviation is widely known, accepted and unambiguous) then the help text is the opportunity to clarify.
  An abbreviation must be defined in the help text everywhere an abbreviation is used. The help texts in this section of the API carry no such qualifications.
• The help texts for these settings includde what look like type or variable names from internal code or other technical jargon, giving the documentation
  a feel of being notes for internal developers rather than help for external users (zone_t, ZoneBC_t, NGON_n, FamilySpecified)
• in parameter cgns_familyname, the last part should be split: family_name
• (cgns) settings has the incorrect help text, "The export settings object"
• sc_def_file_settings has the help text "File object" which is incorrect
• sc_def_file_settings actually contains a method write_sc_file(). This points to the unsuitability of the name sc_def_file_settings, paricularly the settings suffix.
• enable_auto_creation_of_scp_file is inside the sc_def_file_settings group. Both contain the sc abbreviation but neither has a help text that defines that abbreviation.
• write_sc_file contains capitalizations in the help text.

/file/export

• Although it's a group, export is commonly used as a verb. It contains many methods, each of which is a noun. Although it is unconventional, we can accept this design,
  but it only works if it is clearly documented. However this is not the case. The main reason, as stated above, is that export itself lacks a proper, explanatory help text.
• The /file/export/ascii method's help text only states that the output is ASCII without mentioning anything specific about the content or structure of the file.
• The /file/export/visualize_output and /file/export/visualize_write have identical help texts. Also, those help texts state that those methods have something
  to do with Fluids One. Should these be in a separate section? But more importantly, can't they be written a way that doesn't have to tie them to a single client?
• Under export there is also a cgns method so that cgns export is fragmented between settings and cgns

/file/cffio_options

• an example where things are well structured, named and documented

/server

• an example where things are well structured, named and documented

/setup/models

/setup/models/multiphase

• structure, naming, and documentation all look good
• A few points follow. Note that not every section has been looked at
• vof_ item name prefixes are fine, but the help text should define it.
• items inside vof_parameters have names laos begining vof_ which is redundant.
• inconsistent help text formats: vof, VOF. Also random capitalizations.
• Inside /setup/models/multiphase/vof_sub_models all help texts are "Help".
• sub model is not two separate words, as given in the help text.
• anti diffusion is not two separate words, as given in the help text.

/setup/models/
Each model has a very basic, top-level help text like "the viscous model". It should be something more like,
viscous: "A group for setting up the viscous physics model so that you can . To begin,
select an appropriate model via the model parameter which is an immediate child, and the allowed values can
be obtained from the model parameter itself. Your choice of model value determines which specific model
settings become active. Settings inappropriate to your model setting will be inactive. Edit the active settings in order
to set the model up according to your preferences." In this way, we are trying to tell the user what the basic
workflow should like--information that is otherwise absent.

/setup/models/energy

• structure, naming, and documentation all look good

/setup/models/viscous

• structure, naming, and documentation all look good
• capitalize abbreviations in help text (e.g. rng) and define (in basic terms) the abbreviation for completeness (RNG, RANS, LES, etc...)

/setup/models/discrete_phase

• It feels like this is completely missing help text
• Help text for /setup/models/discrete_phase itself is Toplevel object. Should be consistent with the other model groups. Also, toplevel is not a word.
• Inside dpm almost everything is a "Main object" (help text)
• Two attributes start dpm_ (redundant)
• dpm_level_* attributes are mysterious. I cannot decypher the help texts. They each refer to user interface/experience.
  They require strings to be set but what are those strings?
• typo: reletated in unsteady_tracking help text
• model is well documented lower down, the high levels are badly lacking
• ? at end of create_particles_at help text

/setup/models/acoustics

• Help text for /setup/models/acoustics/model is "An acoustics model" but it is the currently selected acoustics model.
  This is not the only place where this is an issue but this one is worse because of the particular phrasing. As stated in notes
  we should have standard templates to avoid this.
• The other two items have Entering object and Entering ... object as their help texts which is inappropriate.
• fwh_options contains an obscure abbreviation, not even clarified in the help text
• FWH is mentioned in the sources method's help text but undefined
• fwh_options group contains help texts that introduce undefined abbreviations.
• fwh_options/convection's help text is Entering object.
• fwh_options/auto_prune and fwh_options/convection/convective_effects are enablement parameters which should be standardised
• fwh_options/convection has freestream_velocity and freestream_direction. Why is this two separate parameters? Even if they are kept separate,
  note that freestream_velocity only contains a magnitude so is apparently misnamed and if so has incorrect help text too.

/setup/models/radiation

• /setup/models/radiation/model's help text is "Activate a radiation model", so it looks like it might be a boolean but it's actually a string,
  so this can easily become confusing. Needs the standardisation.
• Each model (discrete_ordinates, monte_carlo, s2s each has the help text, "Enable/disable the ". But those are actually
  groups, containing the detailed settings. Coupled with the help text for /setup/models/radiation/model, the level of confusion is severe.
• solar_calculator and solar_calculator_gui have identical state. The _gui object seems redundant, plus we shouldn't have _gui objects in the API.

/setup/models/species

• lots of abbreviations in the names
• help text does not define them, just repeats them
• random capitalizations in help texts
• help texts are bland, doesn't teach you anything at all about what those things are.
• /setup/models/species/edc_options/pasr_options/edc_pasr_options note the multiple repetitions
• N.b. pasr_options has ranges for mixing_constant & fractal_dimension which is unusual. Could auto-insert those based on static attributes(?)

/setup/models/virtual_blade_model

• help text just calls it vbm, wrongly and it's also lower case, should be caps.
  User types help(virtual_blade_model) in Python and the help text is less useful than the object name!!
• enabled help text starts with a verb ("Enable/disabled") -> "Whether ... is enabled. If enabled..."
• Model contains a few attributes, none are properly documented plus one mysterious method, apply ("read and apply VBM setting" reads like dev notes).
  apply has no arguments. How does the user know how to use this? This API section is a complete fail--the worst of all.
  I just go into virtual_blade_model and call apply() and that reads whatever from wherever??? Doc tells me NOTHING. What are the prereq's for calling apply?
  What is the overall workflow? The top-level VBM object should clarify the overall workflow.

/setup/models/optics

• unhelpful help texts: report is a boolean but has help, "Write ...reports..." as if it's a method. Should be "whether..."
• unhelpful help texts: index_of_refraction is just the refractive index (a real) but has help text, "The model parameters of..."
• verbosity is an int (range?)
• beams_child has the obscure ap_face_zone (ap is aperture here)
• help text in the optics model refer to aero optics. An instance is in the enabling parameter, so is this the optics aero model
  or optics model? It seems that this model should be called aero_optics for clarity.
• Q: should index_of_refraction help text say what volume it refers to
• optics has a method, statistics_controls (plural noun). All its arguments contain abbreviations. What is this even a method?
  It looks like just a setter method, so this should be handled via ordinary settings.
• meanwhile reset_statistics (verb) is an attribute

/setup/models/structure

• has a more comprehensive help text
• model has a good help text. Allowed values would help the API doc (could automate it through attrs in the API code?) (n.b. we must ramp up on our pyFluent enums).
• each help text is quite strong at top level. Even qualifies abbreviations.
• nice

/setup/models/dsmc

• Should avoid abbreviations in high-level objects.
• all help text just repeat dsmc, but incorrect format (lower case). No definition offered.
• group objects (even the top-level dsmc object has help text "Enable/disable..." which is misleading
• help text: "number of particle"
• string parameters miss static option lists in help text

/setup/models/echemistry

• unnecessarily obscure name
• help looks like rough notes for dev
• echemistry runs through all the help text instead of trying to help user all the way from the model's top level
• naming confusion between li (for lithium ion) and just lithium in other places, even where lithium ion was intended
• similar mixture between li and lithium in the help text
• random use of caps in help text

/setup/models/echemistry/electrolysis/parameters

• loads of obscure abbreviations (and elsewhere in this model
• missed chance to categorize? Separate groups seem to exist at the same level.
• mixtures of unit strings formats in help text. Other settings elsewhere do not mention units in help strings.
• random use of caps in help text
• formatting in help text (missing spaces before opening brackets)

/setup/models/echemistry/electrolysis/cathode (etc)

• cathode is repeated in names of each attribute here. These repetitions lead to salient terms being abbreviated (to save space?)
• i.e. structure is built into names instead of into the data model.
• Then inside cathode/cathode_cc_zone etc we again have all attributes called cathode_* yet again!
• parameters (mentioned above has some implicit categorization of anode v cathode etc and then here we
  actually categorize them explicitly

/setup/models/echemistry/electrolysis/advanced

• has an attribute called contact_resis where it means resistance!
• Its help text capitalizes each word

/setup/models/echemistry/electrolysis/advanced/membrane_diffusion

• has an attribute setup whose help text is "Membrance species diffusivity". The item name is bland compared with this
  text. If the text is accurate in saying that this is diffusivity then that should be the name, whereupon the current text
  would be rendered redundant (self-documenting API)
• the internals of setup are obscure. E.g., value: "Value in thread-real-pair object" which is just dev notes. Similarly,
  species_name: "Species name in species-real-pair object." What?
• has an attribute enable. Should be enabled for an attribute

[seanpearsonuk]

@mainakk @prmukherj @hpohekar @mkundu1 @mayankansys
@raph-luc @h-krishnan @dnwillia-work @lagacep-ans @gyeole @ansjschuetz
@cj-hodgson @millerj97 @Gobot1234
@PyPablo @sravanansys @abhishekchitwar @rploconnor @MohammedAnsys @PySRG