sim-plugin-fluent 0.2.0__py3-none-any.whl

sim_plugin_fluent/__init__.py

@@ -0,0 +1,22 @@
+"""PyFluent driver plugin for sim.
+
+Distributed as an out-of-tree plugin; discovered by sim via the
+``sim.drivers`` entry-point group. Bundled skill files (under ``_skills/``)
+are exposed via the ``sim.skills`` entry-point group.
+"""
+from importlib.resources import files
+
+from .driver import PyFluentDriver
+
+skills_dir = files(__name__) / "_skills"
+
+
+plugin_info = {
+    "name": "fluent",
+    "summary": "Ansys Fluent driver and bundled skill for sim.",
+    "homepage": "https://github.com/svd-ai-lab/sim-plugin-fluent",
+    "license_class": "commercial",
+    "solver_name": "fluent",
+}
+
+__all__ = ["PyFluentDriver", "skills_dir", "plugin_info"]

sim_plugin_fluent/_skills/fluent/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: fluent-sim
+description: Use when working with Ansys Fluent through live sim sessions, direct PyFluent scripts, or file-side artifact review.
+---
+
+# fluent-sim
+
+This skill is the Fluent-specific operating guide. Choose the control path
+that fits the task, then load only the references needed for that path.
+
+## Choose The Control Path
+
+| Path | Best for | Starting point |
+|---|---|---|
+| Live sim session | Stateful edits, GUI observation, incremental solver work, remote Windows diagnostics, version probes, and inspecting a running Fluent session | `sim connect --solver fluent --mode <solver|meshing> --ui-mode <gui|no_gui>` |
+| Direct PyFluent script | Deterministic batch runs, reproducible examples, CI-friendly smoke scripts, and workflows that can own their process lifecycle | `from ansys.fluent.core import launch_fluent` in a normal Python script |
+| File-side artifact review | Case/data/mesh inventory, transcript tails, CSV/PNG/PDF outputs, and offline checks that do not need a live solver | Use Python file readers, text inspection, and Fluent artifact helpers before opening a session |
+
+Use sim when the task needs a persistent runtime or live observation. Use a
+direct PyFluent script when a one-shot batch program is clearer. Use file-side
+helpers when the question is about artifacts already on disk.
+
+## Live Sim Session
+
+After connecting, inspect:
+
+```bash
+sim inspect session.versions
+sim inspect session.health
+sim inspect session.summary
+```
+
+The `session.versions` payload selects the active overlays. Always read
+`base/`, then the active `sdk/<active_sdk_layer>/`, then the active
+`solver/<active_solver_layer>/` when present. Later layers override earlier
+files with the same name.
+
+Expected SDK layer directories are:
+
+- `sdk/0.38/` for PyFluent 0.38.x
+- `sdk/0.37/` for PyFluent 0.37.x
+
+Useful live inspect targets:
+
+- `session.summary`
+- `session.health`
+- `session.versions`
+- `last.result`
+- `workflow.summary`
+- `field.catalog` / `fluent.field.catalog`
+- `fluent.models.summary`
+- `fluent.boundaries.summary`
+- `fluent.case.summary`
+- `fluent.mesh.summary`
+- `fluent.files`
+
+Use `sim exec` snippets with the injected `session`, `solver`, or `meshing`
+object. Keep snippets small enough that `last.result` can prove the current
+state before the next step.
+
+## Direct PyFluent Script
+
+For direct scripts, own the launch and teardown explicitly:
+
+```python
+from ansys.fluent.core import launch_fluent
+
+solver = launch_fluent(mode="solver", ui_mode="no_gui", precision="double")
+try:
+    solver.settings.file.read_case(file_name="case.cas.h5")
+    solver.solution.initialization.hybrid_initialize()
+    solver.solution.run_calculation.iterate(iter_count=10)
+finally:
+    solver.exit()
+```
+
+This path is a good fit when the result can be produced in one deterministic
+program and you do not need a live agent-visible session between steps.
+
+For direct PyFluent scripts, launch the session normally with PyFluent and do
+not rely on sim-injected variables.
+
+## File-Side Artifact Review
+
+Before launching Fluent, inventory what is already present:
+
+- `.cas` / `.cas.h5`: case setup
+- `.dat` / `.dat.h5`: solution data
+- `.msh` / `.msh.h5`: mesh input
+- `.trn` / `.jou`: transcript and journal evidence
+- `.pdf` / `.fla`: flamelet and PDF table artifacts
+- `.csv` / `.png` / `.json`: exported reports, figures, and structured output
+
+Use this path for quick triage, output extraction, and deciding whether a live
+session is necessary.
+
+## Layered References
+
+| Path | Use |
+|---|---|
+| `base/reference/task_templates.md` | Required inputs and workflow step order |
+| `base/reference/runtime_patterns.md` | Fluent dependency chains and state ordering |
+| `base/reference/acceptance_checklists.md` | Completion checks for bundled workflows |
+| `base/reference/api_discovery.md` | `dir()` and `child_names` patterns for renamed APIs |
+| `base/reference/tui_vs_settings.md` | When to prefer Settings API or TUI |
+| `base/reference/pyfluent_overview.md` | Quick PyFluent orientation |
+| `base/snippets/` | Reusable live-session snippets |
+| `base/workflows/` | Longer workflow examples |
+| `sdk/0.38/` | PyFluent 0.38.x docs and examples |
+| `sdk/0.37/` | PyFluent 0.37.x compatibility notes |
+| `solver/25.2/` | Fluent 25.2-specific notes |
+| `doc-search/` | Local Fluent documentation search helper |
+
+For PyFluent API questions, start with the active `sdk/` overlay. For Fluent
+physics, meshing, UDF, or solver-model questions, use `doc-search/` against the
+local Ansys documentation tree rather than guessing names or defaults.
+
+## Live Sim Session Constraints
+
+These constraints apply only after sim has already created a live Fluent
+session:
+
+1. Do not call `pyfluent.launch_fluent()` inside a `sim exec` snippet. Use the
+   injected `session`, `solver`, or `meshing` object.
+2. Do not switch between meshing and solver mode by assumption. The mode is
+   selected at connect time unless a Fluent workflow explicitly returns a
+   solver object.
+3. Confirm each stateful step before sending the next dependent step. Fluent
+   meshing and solver workflows are order-sensitive.
+4. Use GUI actuation only for surfaces the SDK cannot reach. Prefer
+   `solver.settings.*`, `session.tui.*`, and `meshing.workflow.*` for
+   reproducible work.
+
+## Flamelet And PDF Table Workflows
+
+For partially premixed steady-diffusion flamelet workflows, load:
+
+- `base/reference/task_templates.md` - Template 5
+- `base/reference/runtime_patterns.md` - staged flamelet/PDF dependency chain
+- `base/reference/acceptance_checklists.md` - Checklist 5
+- `base/snippets/setup_partially_premixed_flamelet.py`
+- `base/snippets/write_pdf_table.py`
+- `base/snippets/read_case_pdf_data.py`
+- `base/snippets/inspect_reacting_bc_scalars.py`
+
+Short version: import CHEMKIN as `flamelet-mixture`, generate flamelets and the
+PDF table, persist the table with `write_pdf_cmd(...)`, and restart or
+postprocess with `read_case -> read_pdf -> read_data`.

sim_plugin_fluent/_skills/fluent/base/reference/acceptance_checklists.md

@@ -0,0 +1,185 @@
+# Acceptance Checklists — fluent-sim v0
+
+> These checklists define what "task complete" means for each workflow type.
+> A task is complete when ALL applicable items pass — not when the last script exits 0.
+
+---
+
+## Pre-Execution Gate — Acceptance Criteria Must Be Defined
+
+Before executing the first state-changing Fluent step, verify that **at least one outcome-based acceptance criterion** exists for this task.
+
+An outcome-based criterion specifies what the simulation must produce or demonstrate — not just that it runs:
+
+- ✅ "outlet average temperature between 28°C and 35°C"
+- ✅ "150 iterations complete, then extract mass flow rate at outlet"
+- ✅ "volume mesh generated with no negative volumes, cell count > 0"
+- ❌ "跑完就好" — describes an operation, not an outcome
+- ❌ "just run it" — same
+- ❌ "run and see" — same
+
+If no valid criterion exists, treat it as a missing Category A input (see SKILL.md §5.1) and ask the user before proceeding:
+> "What result do you want to extract? How will you judge whether this simulation was successful?"
+
+Do not proceed on the assumption that "successful execution = task complete."
+
+---
+
+## How to Use These Checklists
+
+After the final step of a workflow, the agent must:
+
+1. Inspect the final live-session state or direct-script outputs
+2. Work through the relevant checklist below
+3. Mark each item as PASS / FAIL / N/A with the actual observed value
+4. If all REQUIRED items pass → report COMPLETE
+5. If any REQUIRED item fails → report INCOMPLETE with specific failures
+
+Checklist items marked **[REQUIRED]** must pass for any completion claim.
+Items marked **[RECOMMENDED]** are best practice but may be waived with user consent.
+Items marked **[OPTIONAL]** are only applicable if the user requested that output.
+
+---
+
+## Checklist 1 — Watertight Meshing Completion
+
+### Session State
+- **[REQUIRED]** `session.summary.connected = true`
+- **[REQUIRED]** `session.summary.mode = "meshing"`
+- **[REQUIRED]** `session.summary.run_count` = expected number of executed steps (verify against actual steps sent)
+
+### Last Result
+- **[REQUIRED]** `last.result.ok = true`
+- **[REQUIRED]** `last.result.label = "switch-to-solver"` (if switch was requested) OR `"volume-mesh"` (if not)
+- **[REQUIRED]** `last.result.result.volume_mesh_done = true`
+- **[REQUIRED]** `last.result.result.workflow = "watertight-geometry"`
+
+### Switch to Solver (if requested)
+- **[REQUIRED if switch requested]** `last.result.result.switch_to_solver_done = true`
+- **[RECOMMENDED]** `last.result.result.solver_type` is non-empty (confirms solver object was returned)
+
+### Mesh Quality (observational)
+- **[RECOMMENDED]** Cell count extracted from stdout of volume-mesh step and reported to user
+- **[RECOMMENDED]** No negative volume warnings in mesh-check stdout
+- **[OPTIONAL]** Surface mesh statistics (face count, min/max size)
+
+### What "task complete" does NOT mean here:
+- The workflow task list showed no errors (Fluent GUI task list is informational only)
+- The Python snippet printed "OK"
+- The process exited 0 without verifying `result` fields
+
+---
+
+## Checklist 2 — Fault-Tolerant Meshing Completion
+
+### Session State
+- **[REQUIRED]** `session.summary.connected = true`
+- **[REQUIRED]** `session.summary.mode = "meshing"`
+- **[REQUIRED]** `session.summary.run_count` matches expected step count
+
+### Last Result
+- **[REQUIRED]** `last.result.ok = true`
+- **[REQUIRED]** `last.result.result.volume_mesh_done = true`
+- **[REQUIRED]** `last.result.result.workflow = "fault-tolerant-meshing"`
+
+### Known Version Compatibility
+- **[REQUIRED]** No unhandled `LookupError` in any step's `stderr`
+  (The `DefaultObjectSetting` issue is expected in some Fluent versions; it must be caught, not crash the step)
+
+### Mesh Quality (observational)
+- **[RECOMMENDED]** Total cell count extracted and reported
+- **[RECOMMENDED]** No `negative volume` or `high skewness` warnings in stdout
+
+---
+
+## Checklist 3 — Solver Run Completion
+
+### Session State
+- **[REQUIRED]** `session.summary.connected = true`
+- **[REQUIRED]** `session.summary.mode = "solver"`
+- **[REQUIRED]** `session.summary.run_count = 3` (read-case-data + mesh-check + run-iterations)
+  or higher if additional extraction steps were run
+
+### Last Result (after iterations step)
+- **[REQUIRED]** `last.result.ok = true`
+- **[REQUIRED]** `last.result.result.iterations_run = N` (matches requested iteration count)
+- **[REQUIRED]** `last.result.result.status = "complete"`
+
+### Result Extraction (if requested)
+- **[REQUIRED if extraction requested]** Extracted quantity present in `last.result.result` with a non-null value
+- **[REQUIRED if extraction requested]** Quantity value is numeric or explicitly labeled as "see stdout" with stdout reproduced
+- **[RECOMMENDED]** Report the sign convention (e.g., negative mass flow rate = outflow)
+
+### Convergence (observational)
+- **[OPTIONAL]** Residual values at final iteration extracted from stdout and reported
+- **[OPTIONAL]** Confirm whether convergence was achieved (residuals below threshold) or only N iterations were run
+
+### What "task complete" does NOT mean here:
+- N iterations were scheduled (`iterate(iter_count=N)` was called)
+- Fluent did not crash
+- The `_result` dict was set
+
+---
+
+## Checklist 4 — Smoke / Connectivity Test Completion
+
+### Session State
+- **[REQUIRED]** `session.summary.connected = true` after connect
+- **[REQUIRED]** `session.summary.run_count = 1` after smoke snippet
+
+### Last Result
+- **[REQUIRED]** `last.result.ok = true`
+- **[REQUIRED]** `last.result.result.status = "ok"`
+
+### Disconnect
+- **[REQUIRED]** The live session or direct PyFluent process exits cleanly
+
+### Log Files
+- **[RECOMMENDED]** `.sim/runs/` contains at least 1 JSON log file for live sim sessions
+- **[RECOMMENDED]** The final log or direct-script result reports `ok = true`
+
+---
+
+## Checklist 5 — Partially Premixed Flamelet/PDF Table Completion
+
+### Session and Launch State
+- **[REQUIRED]** `session.summary.connected = true`
+- **[REQUIRED]** `session.summary.mode` or `solver_kind = "solver"`
+- **[REQUIRED]** Launch options or session metadata reports the intended Fluent `dimension`, `precision`, processor count, and working directory
+
+### Flamelet and Table Generation
+- **[REQUIRED]** CHEMKIN import used material name `flamelet-mixture`
+- **[REQUIRED]** `setup-partially-premixed-flamelet` completed with `flamelets_generated = true`
+- **[REQUIRED]** `setup-partially-premixed-flamelet` completed with `pdf_table_generated = true`
+- **[REQUIRED]** No undocumented internal Scheme procedure was used to generate flamelets
+
+### Persistence and Readback
+- **[REQUIRED]** `.pdf` table file exists and `write-pdf-table` reports `pdf_written = true`
+- **[REQUIRED]** Case and data files exist after the solve step
+- **[REQUIRED]** Fresh-session readback succeeds in this order: `read_case -> read_pdf -> read_data`
+- **[REQUIRED]** Readback does not report `PDF data has not been loaded`
+
+### Physical Output
+- **[REQUIRED]** At least one physical output is extracted and reported with values or artifact paths
+- **[RECOMMENDED]** Scalar ranges, profile CSV, or figure artifacts are produced for reacting scalars
+- **[RECOMMENDED]** Any table clipping warnings, such as enthalpy bounds exceeded, are quoted in the report
+
+### What "task complete" does NOT mean here:
+- `calc_pdf()` returned without saving the PDF table
+- Case/data files were written but not reopened in a fresh session
+- Fluent residuals decreased without any physical output extraction
+- A GUI workflow worked once but was not converted to a reproducible Settings/TUI/PyFluent snippet
+
+---
+
+## General Rules for Completion Claims
+
+1. **Never claim complete based on exit code alone.** Exit code 0 means the CLI sent the snippet; it does not mean the simulation step produced correct results.
+
+2. **Never claim complete based on print output alone.** `print("done")` in a snippet proves nothing about session state.
+
+3. **Always quote the actual value** when reporting an extracted quantity. "Mass flow rate was computed" is insufficient; "mass flow rate = −0.0939 kg/s at outlet" is acceptable.
+
+4. **Partial completion is a valid outcome.** If steps 1–5 passed and step 6 failed, report "5/6 steps completed; task incomplete due to [reason]". Do not claim full completion.
+
+5. **run_count mismatch is a red flag.** If `run_count` is lower than expected, one or more steps silently did not execute. Investigate before claiming completion.

sim_plugin_fluent/_skills/fluent/base/reference/api_discovery.md

@@ -0,0 +1,135 @@
+# PyFluent API Discovery Patterns
+
+When a PyFluent settings API call fails (usually `AttributeError` after a version change), use these introspection patterns to find the correct path instead of hardcoding version branches.
+
+## Pattern 1: Find renamed attributes with `dir()`
+
+```python
+# Expected: die.source_terms  →  AttributeError
+# Discover what's actually there:
+obj = solver.settings.setup.cell_zone_conditions.solid["zone-name"]
+attrs = [a for a in dir(obj) if not a.startswith("_")]
+# Found: 'sources' instead of 'source_terms'
+```
+
+## Pattern 2: Navigate settings tree with `.child_names`
+
+```python
+# Drill into an unfamiliar object:
+obj.child_names   # → ['enable', 'terms']
+obj.get_state()   # → full state dict, shows current values
+obj.print_state() # → human-readable state dump
+```
+
+## Pattern 3: Cell zone vs surface names
+
+`fields.reduction` and `report_definitions.surface_names` only accept **surface names**, not cell zone names. If you get `ValueError: Invalid location input`, create a surface from the cell zone first:
+
+```python
+# TUI approach (stable across versions):
+solver.tui.surface.zone_surface("my_surface", "cell-zone-name")
+
+# Settings API approach (pyfluent 0.38+):
+solver.settings.results.surfaces.zone_surface["my_surface"] = {
+    "zone_name": "cell-zone-name"
+}
+
+# Then use the surface name in reduction/reports:
+solver.fields.reduction.maximum(expression="Temperature", locations=["my_surface"])
+```
+
+## Pattern 4: Named expressions
+
+Some case files reference named expressions that aren't yet defined. Check for warnings like `Setup contains invalid expression` after reading a case.
+
+```python
+# List existing named expressions:
+ne = solver.settings.setup.named_expressions
+print(list(ne.keys()))
+
+# Define a missing one:
+ne["Power"] = {"definition": "1 [W]"}
+```
+
+## Pattern 5: Report definitions for data extraction
+
+When `fields.reduction` doesn't work for a location, use report definitions:
+
+```python
+rd = solver.settings.solution.report_definitions
+
+rd.surface["my_report"] = {}
+rd.surface["my_report"].report_type = "surface-areaavg"  # or surface-facetmax
+rd.surface["my_report"].field = "temperature"
+rd.surface["my_report"].surface_names = ["surface-name"]  # must be a surface, not cell zone
+
+rd.compute(report_defs=["my_report"])
+# Values printed to stdout
+```
+
+## Pattern 6: Allowed values from error messages
+
+PyFluent often includes allowed values in error messages:
+
+```
+ValueError: 'surface_names' has no attribute '['bad-name']'.
+The allowed values are: ['pcb_top', 'die_sides', ...]
+```
+
+Parse these to discover valid surface/zone names without a separate query.
+
+## Pattern 7: Version detection
+
+```python
+import ansys.fluent.core as pyfluent
+version = pyfluent.__version__  # e.g. "0.38.1"
+major_minor = ".".join(version.split(".")[:2])  # "0.38"
+```
+
+Use this to log which version is active, not to branch code paths. If an API call fails, introspect the object rather than checking the version string.
+
+## Pattern 8: Discover the physics workflow before automating it
+
+For complex physics models, API discovery alone is not enough. First
+identify the solver workflow in the Fluent User's Guide and Theory Guide,
+then map each documented step to Settings API, TUI, journal, or GUI
+automation.
+
+Use this pattern for models whose setup depends on generated/imported
+auxiliary data, staged dialogs, or hidden state, including combustion,
+radiation, multiphase, acoustics, and reacting-flow chemistry.
+
+Recommended sequence:
+
+1. Search the local Fluent docs for the model name and 2-3 workflow terms,
+   such as `non-premixed pdf`, `flamelet table`, `radiation do`, or
+   `species mechanism`.
+2. Read the User's Guide workflow before writing code. Identify whether
+   required data is generated in Fluent, imported from a file, or produced
+   by a separate utility.
+3. Read the Theory Guide for model assumptions and required transported
+   scalars. Do not infer these from PyFluent object names alone.
+4. Only then map the workflow to `solver.settings.*` or `solver.tui.*`.
+   Treat inactive Settings objects as evidence that a prior documented
+   workflow step is missing, not as an invitation to call internal Scheme.
+5. If the Settings API exposes an object but not the full workflow, capture
+   a short journal or TUI transcript once, then convert it into a stable
+   scripted sequence.
+
+Lookup-table models deserve extra caution. Commands named like `read_*`,
+`write_*`, and `calc_*` may operate on an already-created table rather than
+creating all prerequisites. Confirm from the docs whether the table must be
+generated, imported, or read during model activation before using the
+command in automation.
+
+Do not call undocumented internal Scheme procedures with guessed arguments.
+If a public Settings/TUI path is not available, isolate probes in a fresh
+small session and record the missing public workflow step.
+
+## When to use TUI instead
+
+If introspection reveals the settings API path is complex or unreliable for a specific operation, use TUI directly. Common cases where TUI is simpler:
+
+- Creating surfaces from cell zones (`surface/zone-surface`)
+- Complex zone selection patterns
+- Operations that would require multiple settings API calls but one TUI command

sim_plugin_fluent/_skills/fluent/base/reference/pyfluent_overview.md

@@ -0,0 +1,20 @@
+# PyFluent Reference Docs
+
+Versioned snapshots of PyFluent API documentation. Used by the agent skill for fast lookup.
+
+**Live docs:** https://fluent.docs.pyansys.com/version/stable/index.html
+
+When docs disagree with the live session, trust the session. Use `sim exec "print(dir(...))"` to introspect.
+
+## Versions
+
+| Version | Status | Fluent compatibility |
+|---|---|---|
+| [0.38](0.38/) | Current | Fluent 2025 R2 (v252) |
+
+## Adding a new version
+
+1. Copy the current version folder: `cp -r 0.38 0.39`
+2. Update changed API paths
+3. Run integration tests to verify
+4. See `driver-upgrade` skill for the full process

sim_plugin_fluent/_skills/fluent/base/reference/runtime_patterns.md

@@ -0,0 +1,120 @@
+# Fluent-specific runtime dependencies
+
+This file covers Fluent-specific dependency rules that apply whether you
+are using a live sim session or a direct PyFluent script. When you choose
+the live sim path, combine these rules with the sim runtime lifecycle and
+inspect commands surfaced by the active session.
+
+---
+
+## Pattern 7 — Multi-step dependency ordering
+
+**Rule**: never send step N+1 before step N is confirmed successful.
+This is a Fluent rule because the meshing and solver task lists are
+stateful — an out-of-order call mutates session state in ways that are
+hard to undo.
+
+### Meshing (watertight)
+
+```
+InitializeWorkflow → ImportGeometry → LocalSizing → SurfaceMesh
+→ DescribeGeometry → UpdateBoundaries → UpdateRegions
+→ BoundaryLayers → VolumeMesh → SwitchToSolver
+```
+
+### Meshing (fault-tolerant)
+
+```
+InitializeWorkflow → ImportCAD → CreateRegions → LocalSizing
+→ GenerateSurfaceMesh → UpdateBoundaries → CreateVolumeMesh
+→ SwitchToSolver
+```
+
+### Solver
+
+```
+ReadCase → ReadData → MeshCheck → Iterate → ExtractResults
+```
+
+### Partially premixed flamelet/PDF
+
+```
+ReadMeshOrCase → SetDimension/Axisymmetric → Energy/Turbulence
+→ PartiallyPremixedModel → CHEMKINImportAsFlameletMixture
+→ SetFuelOxidizerStreams → CalcFlamelets → CalcPDFTable
+→ WritePDFTable → InspectBoundaryScalars → SetCFDBoundaries
+→ InitializeOrRestart → Iterate → WriteCaseData
+→ FreshSessionReadCase → ReadPDFTable → ReadData → ExtractResults
+```
+
+If a step is skippable (e.g. `LocalSizing` defaults are acceptable),
+explicitly note in the report that it was skipped and why. Do not
+silently drop steps.
+
+---
+
+## Pattern 8 — Mode-specific flag rules
+
+`--mode meshing` and `--mode solver` are not interchangeable. Which
+snippets are valid depends on the mode:
+
+| Mode | Valid snippet families |
+|---|---|
+| `meshing` | Watertight / fault-tolerant meshing snippets (`base/snippets/01_*` through pre-switch) |
+| `solver` | Post-`SwitchToSolver` snippets (`05a_setup_bcs_*` onward) |
+
+Running a solver snippet in meshing mode (or vice versa) fails with
+`AttributeError` on a missing module — there is no informative runtime
+check, so the agent must respect the mode.
+
+---
+
+## Pattern 9 — Settings vs TUI selection
+
+See `tui_vs_settings.md`. Short version: prefer the Settings API for
+new workflows; fall back to TUI commands only for features the Settings
+API has not yet surfaced (named expression tagging in 0.37, some
+solution-controls knobs). The Settings API is the durable interface.
+
+---
+
+## Pattern 10 — Reacting PDF/flamelet runs need staged physical state
+
+Lookup-table and transported-PDF combustion models are not just model
+toggles. They often require imported/generated chemistry data, boundary
+composition setup, and a physically developed initial solution before
+the production solve.
+
+For partially premixed steady-diffusion flamelet/PDF table workflows:
+
+1. Set `species.model.option = "partially-premixed-combustion"` first.
+2. Set the chemistry state relation and energy treatment before importing
+   CHEMKIN.
+3. Import CHEMKIN with the material name `"flamelet-mixture"`, followed by
+   the mechanism and thermo file paths.
+4. Set fuel/oxidizer stream composition in
+   `partially_premixed_model_options.boundary`.
+5. Generate flamelets with `root.flamelet.parameters.calc_fla()`.
+6. Generate the PDF table with `root.table.calc_pdf()`.
+7. Persist the table separately with `root.table.write_pdf_cmd(...)`.
+8. On restart or postprocessing, read in the order
+   `read_case -> read_pdf -> read_data`.
+
+For Composition PDF Transport in particular:
+
+1. Import the CHEMKIN mechanism and thermodynamic data first.
+2. Enable the PDF transport model and verify the selected mixture
+   material and number of volumetric species.
+3. Set only the explicitly listed inlet species mass fractions; the
+   final species may be a balance species that cannot be created as a
+   boundary entry.
+4. Prefer restarting from a developed finite-rate, EDC, non-premixed, or
+   partially-premixed solution instead of cold-starting from a mesh.
+5. Treat particle tracking and residual decrease as necessary but not
+   sufficient. Monitor temperature/species profiles, outlet composition,
+   and heat balance until the composition statistics stop moving.
+
+If a short cold-start run produces ambient downstream profiles, do not
+spend more iterations blindly. Confirm that the model has a valid
+reacting initial field and that boundary compositions survived the model
+switch.