Best Practices for PyFluent Examples

[seanpearsonuk]

Best Practices for PyFluent Examples

• Readable, intuitive, and concise — examples should be pleasant to read and easy to follow. If the script looks cluttered or cryptic, people won’t learn from it. Concise, elegant code also reduces noise for large language models (LLMs) and documentation tooling.

• Self-commenting code with clear naming — a descriptive variable name is often more useful than a comment. Comments or docstrings should add value by explaining why something is done, not merely repeating the code in words.

• Accessible to all users — avoid assuming too much background knowledge. Many readers will be students, new users, or engineers exploring a new solver. If an example explains the context up front, it becomes usable by a broader range of people without intimidation.

• Complete and educational — every example should stand on its own. A user should be able to copy, paste, and understand it without digging through Fluent documentation. References to docs can be added for deeper study, but examples should be self-contained.

• Explain choices — always describe what the example is doing and why. This helps users connect the dots, and it avoids “cargo cult” coding where people copy settings without understanding them.

• Clarify specialized parameters — parameters like "uds_diffusivity" or "turb_intensity" are not universally understood. Annotating their meaning ensures that both non-experts and experts new to a given solver can follow along.

• Avoid “mystery numbers” — whenever you use a raw value, explain its units, valid ranges, or physical meaning. Otherwise readers may assume the number is arbitrary or copy it incorrectly.

• Engaging and realistic — small, realistic workflows are more memorable than disconnected snippets. They mirror how engineers actually work, making it easier for readers to adapt examples to their own cases.

• Optimized for LLM training — PyFluent examples are increasingly used as training data for AI models. Clean, well-structured examples reduce the risk of noise, redundancy, and confusion in model-generated responses.

• No legacy Fluent APIs — avoid TUI commands, Scheme functions, and internal variables like RPVars. These are brittle, undocumented, and tied to old workflows. Using only modern APIs makes examples more stable and future-proof.

• Avoid remote-inappropriate API calls — calls that only print data but return nothing (e.g., certain reporting functions) are unhelpful in remote/cloud contexts. Examples should always return usable data structures that can be programmatically inspected.

• No code injection — patterns like read_journal(<uploaded-arbitrary-code-file>) are unsafe and unpredictable. They make examples harder to validate and break reproducibility.

• Platform independent — avoid OS-specific branching (e.g., if Windows: … else:). Examples should run identically on Windows and Linux without modification. This keeps the code portable, testable, and easier to maintain.

• Avoid piecemeal updates — favour setting an object's state once via a dictionary rather than making several calls. That will be much more efficient overall.

• Future-proof meshing workflows — for meshing, always use the new workflow API (currently unreleased). This avoids teaching users APIs that will soon be deprecated, and reduces churn in the docs.

• Mainstream examples — these must work in all server modes (local with GUI, headless batch, cloud-hosted). They should not depend on solver.settings.results, which is often misused for data inspection. Instead, use proper API data extraction and Python visualization tools like PyFluent Visualization.

• Niche examples — these may use Fluent postprocessing or results, but should be few, clearly marked, and kept separate from mainstream workflows. This prevents confusion about what is “standard practice.”

• Style principles — examples should model the modern PyFluent interface:

  • Direct access to settings classes (Viscous(), VelocityInlet("hot-inlet")) instead of long navigation chains. This makes code shorter and easier to discover.
  • Use session scoping with context managers (with using(solver): …) to keep examples clean and intentional. This avoids “dangling” state and clarifies scope.
  • Replace raw strings with typed objects (Enums, Quantity, VariableCatalog, location objects). This makes code safer and easier to autocomplete in IDEs.
  • APIs should be fully discoverable, so readers can rely on autocomplete rather than memorizing strings.
  • Consistency across APIs means fewer surprises — predictable defaults and strong typing help reduce errors and improve the learning curve.

---

Caveats and Exceptions

Some specialized or advanced examples may deliberately violate one or more of these guidelines — for example, postprocessing with Fluent results. These are acceptable only if they are grouped and presented separately so they are clearly distinguished from the mainstream examples.

Timeline

We should begin adopting these best practices immediately, with the goal of achieving full alignment alongside the 26R1 release.

[jgd10]

Mason Egger gave a really great talk about this sort of stuff at PyCon a couple of years ago:

https://www.youtube.com/watch?v=9WobKoE9OPI

A lot of his tips are covered here, though some might not be and could be worth including. Well worth a watch!

[seanpearsonuk]

Thanks @jgd10 !

[dnwillia-work]

Very nice list Sean, Are you going to roll this up into the documentation somewhere. eg: Contributing guide?

[seanpearsonuk]

Thanks, @dnwillia-work. Yes, I wanted to get feedback here (such as the useful input from @jgd10) before finalizing.