Release-readiness assessment of the radiation model API

[seanpearsonuk]

Release-Readiness Review: setup/models/radiation

Scope: PyFluent Settings API – Radiation model configuration
Audience: PyFluent API maintainers and reviewers
Goal: Assess readiness against the agreed beta-quality threshold for public exposure

---

1. Executive summary

Status: ❌ Not beta-ready

The /setup/models/radiation section is conceptually rich but structurally and semantically confusing in its current form. While individual sub-models (DO, Monte Carlo, S2S, Solar) are recognisable to experienced Fluent users, the API does not allow a typical CFD engineer without Fluent experience to discover the intended workflow using only help(), object names, and structure.

The primary blockers are model-selection ambiguity, misleading help text, GUI leakage, and poor separation between “selecting a model” and “configuring a model.”

---

2. Beta-quality gate assessment

Beta question

Can a typical CFD engineer, without Fluent experience and using only introspection (help(), dir()), figure out how to enable and configure a radiation model correctly?

Answer: No

---

3. Major beta-blocking issues

3.1 Ambiguous and misleading model selection

radiation.model

• Type: String
• Help text: “Activate a radiation model.”

Problems:

• Reads like a boolean enable flag, but is actually a model selector.
• Does not document:
  • allowed values,
  • which sub-trees become active,
  • whether it is mandatory.

This creates immediate confusion when combined with the presence of discrete_ordinates, monte_carlo, and s2s groups.

Impact: Users cannot determine:

• whether setting model is sufficient,
• whether they must also “enable” a sub-group,
• or how the solver decides which radiation model is active.

---

3.2 Sub-model groups pretend to be enable flags

Examples:

• discrete_ordinates: Group # Enable/disable the discrete ordinates radiation model.
• monte_carlo: Group # Enable/disable the Monte Carlo radiation model.
• s2s: Group # Enable/disable the Surface to Surface radiation model.

Problems:

• These are configuration groups, not booleans.
• No enabled attribute exists at the group level.
• Help text directly contradicts the actual API shape.

Impact: Severe semantic mismatch between help text and structure. Users are left guessing:

• Do I set radiation.model = "do"?
• Do I “enable” DO by touching this group?
• Are multiple models allowed simultaneously?

This violates the beta requirement of no misleading help text.

---

3.3 No discoverable mainstream workflow

The API does not encode a clear story such as:

“Select a radiation model → configure that model → control solution frequency.”

Instead, the tree exposes all models and all options simultaneously, with no guidance on:

• which groups are mutually exclusive,
• which settings are ignored depending on the chosen model,
• which settings are mandatory vs optional.

A new user cannot infer:

• the minimum viable configuration,
• or even the order of operations.

---

3.4 GUI and duplication leakage

solar_calculator vs solar_calculator_gui

• These groups expose identical state.
• The _gui suffix explicitly leaks GUI implementation details.
• Both appear equally authoritative in the API.

Problems:

• _gui objects should not appear in a public, headless Python API.
• Users cannot know which one is “real”.
• Risk of divergent state or undefined precedence.

This is a hard beta-blocker under the “no internal machinations” rule.

---

3.5 Inconsistent enablement patterns

Across the section:

• Some features use enable_*
• Others use enabled
• Others imply enablement via presence or model selection

Examples:

• do_energy_coupling.enable
• enable_clustering
• enable_ambient_radiation
• solar_on_adjacent_fluid

This inconsistency:

• increases cognitive load,
• makes scripting error-prone,
• violates the emerging Settings API conventions.

---

3.6 Placeholder or missing documentation

Examples:

• direct_solar_irradiation: Group # (no documentation available)
• diffuse_solar_irradiation: Group # (no documentation available)

These are non-optional physics features with zero explanatory help.

This alone disqualifies the section from beta exposure.

---

4. Secondary (but still serious) issues

4.1 Overexposed expert-level controls

Large parts of:

• S2S clustering,
• view-factor computation,
• GPU acceleration,
• solver iteration control,

are exposed without:

• clear “advanced” labeling,
• usage guidance,
• or indication of when defaults are sufficient.

For beta quality, advanced sections must at least be clearly signposted.

---

4.2 Commands without lifecycle context

Commands such as:

• compute_write_vf
• compute_vf_only
• solar_on_demand

lack clarity on:

• when they are required,
• whether they modify persistent state,
• whether they are optional or mandatory steps.

---

4.3 Minor quality issues

• Inconsistent capitalization and phrasing
• Slight grammatical errors (“Enabled/disable”)
• Mixed terminology (“activate”, “enable”, “model”)

Individually minor, but collectively they reduce trust in the API.

---

5. Summary of beta-blocking failures

Criterion	Status
Clear, non-misleading help text	❌
Discoverable mainstream workflow	❌
Clean separation of model selection vs configuration	❌
No GUI or internal leakage	❌
Consistent enablement patterns	❌
No undocumented nodes	❌

---

6. Recommended gating decision

Do not expose /setup/models/radiation as beta in its current form.

Before beta exposure, the section requires:

1. Explicit, documented model selection
   • radiation.model must list allowed values and semantics.
2. Corrected help text for sub-model groups
   • Groups must describe what they configure, not pretend to be enable flags.
3. Removal or hiding of _gui objects
4. Clear delineation of advanced vs mainstream settings
5. No undocumented groups or parameters

These changes are primarily structural and documentation-focused, not solver-logic changes, and are therefore realistic pre-beta remediation tasks.

---

7. Relative assessment

Compared to other reviewed sections:

• Better than discrete_phase (less UI control leakage)
• Comparable to or slightly worse than acoustics in terms of workflow ambiguity
• High user-impact due to common use of radiation models

This makes /setup/models/radiation a high-priority candidate for cleanup before public beta exposure.