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 !

[seanpearsonuk]

I'm paraphrasing/adapting his content:
10. Make your end goal clear up front what's in the example.
9. Simple language, concise language. Aim for a low reading level so that people can read quickly, and non-native English speakers can read too.
8. Inclusive language. Always using second persion ("you") avoids genedered pronouns. Don't use slang. Avoid words that make people doubt their skills. Avoid saying that things are "simple" or "easy".
7. Avoid jargon.
6. Define ALL acronyms/abbreviation. Write out the full name when you introduce the acronym. Perhaps have a glossary.
5. Avoid idioms.
4. Meaningful code samples and variable names.
3. Avoid making your readers leave your docs. Avoid providing links to other sites--keep them focused on our site!!
2. make your content scannable. Make it easy for your reader to find a single piece of information. Experienced users scan for what they need. Use subheadings to break up content. Use a TOC. Use consistent style, develop a consistent voice (feels a bit like a separate point).

1. Verify your doc by testing (we automate this).

[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.

[seanpearsonuk]

Version 2 incorporates input from Mason Egger's video.

Best Practices for PyFluent Examples

Purpose. This document captures the canonical style and content rules for PyFluent examples with the goal of producing examples that are readable, discoverable, runnable, maintainable, and suitable as training data for AI models.

---

High-level principles

• Make the goal explicit up front. Start each example with a short, precise statement of what the example does and why a reader would use it. Add a one-line expected outcome and a short prerequisites list (packages, solver mode, required files).

• Readable, concise, and scannable. Use plain language and short sentences. Structure pages so a reader can quickly scan to the information they need (TOC, subheadings, short sections, Key steps summary). Aim for low reading level and remove unnecessary words.

• Self-contained and platform independent. Examples should run copy/paste with minimal setup on Windows and Linux (and in cloud/headless modes). Prefer examples that return programmatically useful objects rather than only printing to stdout.

• Complete and educational. An example must stand on its own: include context, short explanation of why steps are taken, and small realistic data/workflows. Keep references to external docs to a minimum and place them in a "Further reading" section.

• Explain choices and annotate parameters. For every non-obvious parameter (e.g. uds_diffusivity, turb_intensity), annotate meaning, units, expected ranges, and why the chosen value was selected.

• Avoid brittle/legacy patterns. Do not use TUI commands, Scheme, RPVars, or other legacy internals. Prefer the modern public API surfaces that will be stable going forward.

• Safe and reproducible. Avoid code-injection patterns (read_journal(<uploaded-arbitrary-code>)) and other constructs that break reproducibility or make examples unsafe to run in automated contexts.

• Return useful data structures. Examples should produce returnable, inspectable objects that are friendly to programmatic testing and cloud workflows (avoid examples that only print results).

• Optimized for AI/LLM usage. Use clear naming, typed objects, and predictable structure so examples become high-quality training data (and so LLMs produce better completions).

---

Language, clarity and terminology (consolidated guidance)

• Simple and concise language. Short sentences, active voice, and single idea per sentence. Remove filler words.

• Inclusive, direct voice. Use second person (you) where appropriate. Avoid gendered pronouns, slang, idioms, and words that can undermine user confidence (e.g. avoid repeatedly saying something is "simple" or "trivial").

• Avoid jargon and idioms. If a domain term is required, define it where first used. Avoid idioms and cultural references that non-native speakers or international readers may not understand.

• Define acronyms at first use. Write out full names the first time an acronym appears (e.g. Reynolds-Averaged Navier–Stokes (RANS)). Consider maintaining a small glossary for recurring acronyms.

• Readable names, not mysterious variables. Use descriptive variable names and avoid single-letter or overloaded names. When a numeric literal appears, explain its units, valid range, and physical meaning.

• Inclusive wording. Use ‘you’ to address the reader, avoid words that imply judgment of skill, and keep tone neutral and encouraging.

---

Structure and scannability

• Top summary. Each example should begin with a one-paragraph summary and a Key steps bullet list or numbered steps.

• Subheadings and TOC. Break content into short sections with clear subheadings. Use an authoring TOC when examples are longer than 2–3 screens.

• Code-first, annotated. Provide a runnable code block followed by short, targeted commentary explaining why the code does what it does. Keep comments in code focused on how and docstrings / nearby prose focused on why.

• Minimal external navigation. Keep the essential flow inside the example. If external links are necessary, place them in a "Further reading" or "References" area and mark them clearly.

---

Code design and style principles

• Meaningful code samples and variable names. Choose names that convey intent; prefer inlet_temperature_c over t0.

• Prefer bulk state-setting over piecemeal updates. When configuring objects, prefer a single settings.update({...}) style rather than multiple setter calls when the API supports it.

• Use modern, discoverable APIs. Favor Viscous() / VelocityInlet("hot-inlet") style direct constructors and typed objects (Enums, Quantity, VariableCatalog) so readers can rely on IDE autocomplete.

• Session scoping. Use context managers (with using(solver): ...) to make session-specific state explicit and avoid dangling state.

• Avoid remote-inappropriate calls. Do not rely on side-effect-only functions or reporting calls that return nothing. Examples must be usable in headless and cloud contexts.

---

Testing, verification and CI

• Verify examples by running them. Every example must be runnable and verified in CI or automated tests. Tests should check that examples complete without error and return expected types or summary metrics.

• Determinism and reproducibility. Include seeds or deterministic settings where randomness is involved and keep required data files minimal and bundled or programmatically generated for tests.

• Cross-mode testing. Where practical, test examples across server modes (GUI local, headless batch, cloud-hosted) that are intended as mainstream examples.

---

Categorisation: mainstream vs niche examples

• Mainstream examples — portable, runnable in all supported server modes, avoid solver.settings.results, use modern APIs and return programmatic objects.

• Niche / advanced examples — allowed to use Fluent postprocessing or other specialized features, but these must be clearly marked, grouped separately, and not mixed into the mainstream workflow set.

---

Quick author checklist

Before publishing an example, verify each item below:

1. Goal & expected outcome stated at the top.
2. Key steps summary present.
3. Example is runnable copy/paste with minimal setup.
4. Short, scannable sections and TOC when long.
5. Plain, concise language and second-person voice where appropriate.
6. Acronyms defined at first use; glossary entry if reused.
7. No idioms, slang, or culturally-specific phrasing.
8. Meaningful variable names and no mystery numbers (units & ranges annotated).
9. Uses modern public API (no TUI/Scheme/RPVars).
10. No unsafe code-injection patterns.
11. Returns programmatically useful objects (not just prints).
12. Automated test or CI job confirms the example runs.
13. Niche examples are clearly labelled and separated.

---

Caveats and exceptions

Specialized or advanced examples may deliberately violate one or more guidelines (for example, a deep dive into Fluent postprocessing). These are acceptable only when they are clearly separated and clearly labelled as advanced/niche so they do not pollute the mainstream example set.

---

Timeline

Begin adopting these best practices immediately with the goal of full alignment alongside the 26R1 release.

---

[ansjschuetz]

[like] Jochen Schuetze reacted to your message:

…

________________________________ From: Sean Pearson ***@***.***> Sent: Wednesday, September 10, 2025 5:24:35 PM To: ansys/pyfluent ***@***.***> Cc: Subscribed ***@***.***> Subject: Re: [ansys/pyfluent] Best Practices for PyFluent Examples (Discussion #4378) [External Sender] Version 2 incorporates input from Mason Egger's video. Best Practices for PyFluent Examples (Fluent 26R1 Onwards) Purpose. This document captures the canonical style and content rules for PyFluent examples with the goal of producing examples that are readable, discoverable, runnable, maintainable, and suitable as training data for AI models.

________________________________ High-level principles * Make the goal explicit up front. Start each example with a short, precise statement of what the example does and why a reader would use it. Add a one-line expected outcome and a short prerequisites list (packages, solver mode, required files). * Readable, concise, and scannable. Use plain language and short sentences. Structure pages so a reader can quickly scan to the information they need (TOC, subheadings, short sections, Key steps summary). Aim for low reading level and remove unnecessary words. * Inclusive, direct voice. Use second person (you) where appropriate. Avoid gendered pronouns, slang, idioms, and words that can undermine user confidence (e.g. avoid repeatedly saying something is "simple" or "trivial"). * Self-contained and platform independent. Examples should run copy/paste with minimal setup on Windows and Linux (and in cloud/headless modes). Prefer examples that return programmatically useful objects rather than only printing to stdout. * Complete and educational. An example must stand on its own: include context, short explanation of why steps are taken, and small realistic data/workflows. Keep references to external docs to a minimum and place them in a "Further reading" section. * Explain choices and annotate parameters. For every non-obvious parameter (e.g. uds_diffusivity, turb_intensity), annotate meaning, units, expected ranges, and why the chosen value was selected. * Avoid brittle/legacy patterns. Do not use TUI commands, Scheme, RPVars, or other legacy internals. Prefer the modern public API surfaces that will be stable going forward. * Safe and reproducible. Avoid code-injection patterns (read_journal(<uploaded-arbitrary-code>)) and other constructs that break reproducibility or make examples unsafe to run in automated contexts. * Return useful data structures. Examples should produce returnable, inspectable objects that are friendly to programmatic testing and cloud workflows (avoid examples that only print results). * Optimized for AI/LLM usage. Use clear naming, typed objects, and predictable structure so examples become high-quality training data (and so LLMs produce better completions).

________________________________ Language, clarity and terminology (consolidated guidance) * Simple and concise language. Short sentences, active voice, and single idea per sentence. Remove filler words. * Avoid jargon and idioms. If a domain term is required, define it where first used. Avoid idioms and cultural references that non-native speakers or international readers may not understand. * Define acronyms at first use. Write out full names the first time an acronym appears (e.g. Reynolds-Averaged Navier–Stokes (RANS)). Consider maintaining a small glossary for recurring acronyms. * Readable names, not mysterious variables. Use descriptive variable names and avoid single-letter or overloaded names. When a numeric literal appears, explain its units, valid range, and physical meaning. * Inclusive wording. Use ‘you’ to address the reader, avoid words that imply judgment of skill, and keep tone neutral and encouraging.

________________________________ Structure and scannability * Top summary. Each example should begin with a one-paragraph summary and a Key steps bullet list or numbered steps. * Subheadings and TOC. Break content into short sections with clear subheadings. Use an authoring TOC when examples are longer than 2–3 screens. * Code-first, annotated. Provide a runnable code block followed by short, targeted commentary explaining why the code does what it does. Keep comments in code focused on how and docstrings / nearby prose focused on why. * Minimal external navigation. Keep the essential flow inside the example. If external links are necessary, place them in a "Further reading" or "References" area and mark them clearly.

________________________________ Code design and style principles * Meaningful code samples and variable names. Choose names that convey intent; prefer inlet_temperature_c over t0. * Prefer bulk state-setting over piecemeal updates. When configuring objects, prefer a single settings.update({...}) style rather than multiple setter calls when the API supports it. * Use modern, discoverable APIs. Favor Viscous() / VelocityInlet("hot-inlet") style direct constructors and typed objects (Enums, Quantity, VariableCatalog) so readers can rely on IDE autocomplete. * Session scoping. Use context managers (with using(solver): ...) to make session-specific state explicit and avoid dangling state. * Avoid remote-inappropriate calls. Do not rely on side-effect-only functions or reporting calls that return nothing. Examples must be usable in headless and cloud contexts.

________________________________ Testing, verification and CI * Verify examples by running them. Every example must be runnable and verified in CI or automated tests. Tests should check that examples complete without error and return expected types or summary metrics. * Determinism and reproducibility. Include seeds or deterministic settings where randomness is involved and keep required data files minimal and bundled or programmatically generated for tests. * Cross-mode testing. Where practical, test examples across server modes (GUI local, headless batch, cloud-hosted) that are intended as mainstream examples.

________________________________ Categorisation: mainstream vs niche examples * Mainstream examples — portable, runnable in all supported server modes, avoid solver.settings.results, use modern APIs and return programmatic objects. * Niche / advanced examples — allowed to use Fluent postprocessing or other specialized features, but these must be clearly marked, grouped separately, and not mixed into the mainstream workflow set.

________________________________ Quick author checklist Before publishing an example, verify each item below: 1. Goal & expected outcome stated at the top. 2. Key steps summary present. 3. Example is runnable copy/paste with minimal setup. 4. Short, scannable sections and TOC when long. 5. Plain, concise language and second-person voice where appropriate. 6. Acronyms defined at first use; glossary entry if reused. 7. No idioms, slang, or culturally-specific phrasing. 8. Meaningful variable names and no mystery numbers (units & ranges annotated). 9. Uses modern public API (no TUI/Scheme/RPVars). 10. No unsafe code-injection patterns. 11. Returns programmatically useful objects (not just prints). 12. Automated test or CI job confirms the example runs. 13. Niche examples are clearly labelled and separated.

________________________________ Caveats and exceptions Specialized or advanced examples may deliberately violate one or more guidelines (for example, a deep dive into Fluent postprocessing). These are acceptable only when they are clearly separated and clearly labelled as advanced/niche so they do not pollute the mainstream example set.

________________________________ Timeline Begin adopting these best practices immediately with the goal of full alignment alongside the 26R1 release.

________________________________ — Reply to this email directly, view it on GitHub<#4378 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/BEGQ7PGJ5NAQCM7D7QDPPGT3SBNFHAVCNFSM6AAAAACDV7US3WVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTIMZWGU3DGNY>. You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>