Inconsistent and unclear use of iter_count across PyFluent examples (converged vs demonstrative runs)
- Dominant language
- Python
- Stars
- 497
- Forks
- 77
- Avg merge
- 22h 37m
- Merged PRs (30d)
- 45
Description
### Description
Across the PyFluent example scripts, the choice of `iter_count` is highly inconsistent and is generally not justified or explained. Values range from very small numbers (e.g. `2`, `19`, `25`) up to `1000`, usually without any indication of whether the intent is:
* a **physically converged calculation**, or
* a **non-converged run intended purely to demonstrate workflow or API usage**.
This lack of clarity makes it difficult for users to understand what level of physical fidelity they should expect from a given example and undermines confidence in the examples as authoritative guidance.
---
### Observed issues
1. **Wide variation with no explanation**
`iter_count` varies arbitrarily across examples, usually without any comment explaining why a particular value was chosen or what outcome is expected (e.g. convergence vs demonstration).
2. **Ambiguous or misleading comments where explanations do exist**
A small number of examples contain comments such as:
* “Solve for 19 iterations. 99 iterations is recommended by the tutorial, but is reduced to 19 for this example for demonstration purposes.”
These comments raise two problems:
* The term *“the tutorial”* refers to an external or legacy source. For PyFluent users, **the Python examples themselves are the tutorials**. Referencing external guidance in this way introduces doubt and confusion rather than clarity.
* Even when “demonstration purposes” is mentioned, this is not applied consistently across examples and appears only sporadically.
3. **No explicit distinction between converged and unconverged examples**
Currently, examples appear to be a mixture of:
* runs intended to reach convergence (often implied but not stated), and
* intentionally short, unconverged runs intended to demonstrate setup or post-processing.
This distinction is not made explicit, either in comments or in a consistent documentation pattern.
---
### Why this matters
* Example scripts set user expectations. If an example runs only a small number of iterations without explanation, users may incorrectly assume that the resulting fields are “good enough” or physically meaningful.
* Inconsistent guidance erodes trust and makes it harder for new users to learn best practices.
* Referring to external “tutorials” weakens PyFluent’s position as a first-class, self-contained API and documentation set.
---
### Proposed direction
This issue should be addressed systematically across the examples, rather than piecemeal. Possible improvements include:
* Clearly stating, for each example, whether the calculation is intended to be:
* **converged**, or
* **demonstrative / workflow-focused**.
* Avoiding references to external or legacy tutorials in example comments.
* Where iteration counts are specified, either:
* relate them explicitly to convergence criteria (e.g. residuals), or
* state clearly that the iteration count is intentionally limited for demonstration purposes.
* Optionally defining a simple, consistent comment pattern that can be reused across examples.
---
### Scope
This issue is **not specific to a single PR** and affects multiple existing PyFluent examples. Any fix should aim for consistency and clarity across the repository.
---
### Original context
> @MohammedAnsys This is a very pertinent comment.
> In practice, iter_count varies widely across our PyFluent examples (from very small values up to 1000), and in most cases there’s little or no explanation for why a particular value was chosen. Where comments do exist, they’re sometimes ambiguous; for example, references to “the tutorial”, when for our users these Python scripts are the tutorials. That kind of wording can create uncertainty rather than clarity.
> More broadly, our examples appear to be a mixture of fully converged calculations and intentionally unconverged, demonstration-style runs, but this distinction isn’t made explicit or applied consistently. That makes it hard for users to know what level of physical validity to expect from a given example.
> This goes beyond this PR, so I’ll raise a GitHub issue to address it systematically. For this example specifically, I’d prefer either a clear statement of intent (converged vs demonstrative) or a more general reference to convergence criteria rather than a hard justification of a specific iteration count.
_Originally posted by @seanpearsonuk in [#4833](https://github.com/ansys/pyfluent/pull/4833/changes#r2712076837)_
Contributor guide
Assessment
This issue has not been assessed yet.