docs: Added example on the battery cell simulation. #4361

MohammedAnsys · 2025-08-08T09:09:09Z

Added End to End PyFluent example on Single Cell Battery Simulation based on Ansys Fluent documentation.

Please review the same!

Thanks!

doc/source/conf.py

hpohekar · 2025-08-08T09:55:12Z

Title should be as follows:

docs: Added example on the battery cell simulation.

This will avoid commit style failure.

hpohekar · 2025-08-08T10:01:38Z

@MohammedAnsys

Please refer workflow file and add similar section on the following line:

https://github.com/ansys/pyfluent/blob/main/.github/workflows/execute-examples-weekly.yml#L153

- name: Execute single_battery_cell_workflow.py
   run: |
      python examples/00-fluent/single_battery_cell_workflow.py

This will help to run this example weekly in the GitHub.

examples/00-fluent/single_battery_cell_workflow.py

prmukherj · 2025-08-08T10:06:00Z

Looks, good. You can try using ansys-fluent-visualization for rendering graphics as well from your side and provide your views on how it works: https://github.com/ansys/pyfluent-visualization

MohammedAnsys · 2025-08-08T10:39:34Z

Looks, good. You can try using ansys-fluent-visualization for rendering graphics as well from your side and provide your views on how it works: https://github.com/ansys/pyfluent-visualization

Hi @prmukherj, Thanks for reviewing the PR.
Surely will add visualization example on the repo.

…mulation

…hub.com/ansys/pyfluent into docs/example_on_battery_cell_simulation

.github/workflows/execute-examples-weekly.yml

hpohekar · 2025-08-08T11:12:58Z

src/ansys/fluent/core/utils/file_transfer_service.py

            else:
                raise FileNotFoundError("Remote file does not exist.")

-    def download(self, file_name: list[str] | str, local_directory: str | None = None):
+    def download(self, file_name: list[str] | str, local_directory: str | None = "."):


@MohammedAnsys The changes in this file are not relevant to this PR. These are old changes. This should be resolved before merging the PR. You can pull latest changes from main branch to resolve this.

@MohammedAnsys This is not resolved properly. Unresolving again.

Not relevant to this PR, since deleting it.

abhishekchitwar

Looks good!

hpohekar

@abhishekchitwar src/ansys/fluent/core/utils/file_transfer_service.py has been deleted. This should be resolved properly.

cc: @seanpearsonuk

seanpearsonuk · 2025-08-11T10:36:26Z

examples/00-fluent/single_battery_cell_workflow.py

+    "pyfluent/battery_thermal_simulation",
+    save_path=os.getcwd(),
+)
+


I’ve noticed that comments in this PR are written in the passive voice, which differs from the active style used in other PyFluent examples. The active style is preferred for consistency and readability.

We should also aim for economy in comments—only add them when they communicate something genuinely useful to the reader. Redundant or overly literal comments can slow readers down and may indicate that the script or API itself could be clearer. If many comments feel necessary, that might be a sign the underlying flow or naming could be improved.

seanpearsonuk · 2025-08-11T10:48:03Z

examples/00-fluent/single_battery_cell_workflow.py

+mesh["mesh-1"].surfaces_list = surfaces
+mesh["mesh-1"].options.edges = True
+mesh["mesh-1"].display()


create() already returns the new object, so you can store it directly and avoid repeatedly indexing mesh["mesh-1"]. This makes the code cleaner and more object-oriented.

Setting each property in separate calls is relatively inefficient, especially when each call triggers back-end processing and interprocess communication (which may be remote). Where possible, group property assignments into a single update.

In cases where repeated access is unavoidable, aliasing (mesh_1 = mesh["mesh-1"]) helps reduce duplication and improves readability.

seanpearsonuk · 2025-08-11T10:50:17Z

examples/00-fluent/single_battery_cell_workflow.py

+graphics.views.restore_view(view_name="isometric")
+
+graphics.picture.save_picture(
+    file_name="Single_Battery_Cell_Mesh.png",
+)


Does this work for all Fluent run modes?

Aside: I have concerns about our examples being dominated by Fluent graphics usage which is not a first class part of the API and can easily be rendered unusable in a clean headless mode. We need to think about structuring the examples so that users can learn about the full range of alternatives.

seanpearsonuk · 2025-08-11T10:55:20Z

examples/00-fluent/single_battery_cell_workflow.py

+battery.zone_assignment.passive_zone = ["tab_nzone", "tab_pzone"]
+battery.zone_assignment.negative_tab = ["tab_n"]
+battery.zone_assignment.positive_tab = ["tab_p"]
+battery.zone_assignment.print_battery_connection()


This appears to print directly to the console, which makes it more of a debugging or inspection utility than a proper API method. Such functions generally shouldn’t be part of the public API, and we should avoid using them in examples. Examples should demonstrate supported, programmatic workflows that return data rather than only printing it.

seanpearsonuk · 2025-08-11T10:58:36Z

examples/00-fluent/single_battery_cell_workflow.py

+# By enabling the Battery Model, Fluent activates the physics and equations needed
+# to simulate how the battery behaves electrically, chemically, and thermally.
+#
+# Select NTGK/DCIR Model:
+# This is a simplified but accurate model (based on experimental data) for simulating
+# how voltage and heat change during discharge.
+# NTGK stands for Newman, Tiedemann, Gu, and Kim, who developed this model.
+#
+# Set Nominal Cell Capacity (14.6 Ah):
+# Defines the total amount of charge the battery can store,
+# based on the actual battery specs.
+#
+# Enable Joule Heat in Passive Zones:
+# Includes heat generated in non-active parts like tabs and connectors. This makes the
+# thermal results more accurate.
+#
+# Specify C-Rate (1C):
+# Sets how fast the battery discharges. A 1C rate means the battery will fully discharge
+# in 1 hour. Higher C-rates mean faster discharge.
+#
+# Minimum Stop Voltage (3 V):
+# Fluent will stop the simulation if the battery voltage drops
+# below this. It's a safety cutoff, just like in real batteries.
+#
+# Assign Zones under Conductive Zones:
+# You're telling Fluent which parts are the active battery
+# region (electrochemical zone) and which are conductive parts like tabs or connectors.
+#
+# Assign External Connectors:
+# Defines where the current enters and leaves the battery. These are the positive and
+# negative terminals.
+#
+# Print Battery System Connection Info:
+# This checks if Fluent understood your setup and shows how everything is connected.
+#


Is a lot of this just telling the reader what the defaults are or is it all actioned somewhere in the script? The comments should make this clearer.

seanpearsonuk · 2025-08-11T10:59:36Z

examples/00-fluent/single_battery_cell_workflow.py

+#
+# How well each material conducts electricity
+#
+# This helps fluent calculate voltage, current, and heat correctly during the simulation


Fluent should always be capitalised, "Fluent".

Also, the list is inconsistently formatted: what, How, This.

seanpearsonuk · 2025-08-11T11:02:10Z

examples/00-fluent/single_battery_cell_workflow.py

+        "density": 8978,
+        "specific_heat": 381,
+        "thermal_conductivity": 387.6,
+    },


The chemical_formula values here ("e", "pmat", "nmat") are placeholders, not actual chemical formulas. We should either use realistic values to avoid confusion, or make it clear in a comment that these are arbitrary identifiers for demonstration purposes only.

seanpearsonuk · 2025-08-11T11:10:19Z

examples/00-fluent/single_battery_cell_workflow.py

+    },
+]
+
+solids = solver.settings.setup.materials.solid


We should aim for direct assignment. The existence of the following code in an example script would only imply that the API is difficult to use.

seanpearsonuk · 2025-08-11T11:11:45Z

examples/00-fluent/single_battery_cell_workflow.py

+        "density": 2092,
+        "specific_heat": 678,
+        "thermal_conductivity": 18.2,
+        "uds_diffusivity": {


Are we missing a definition for UDS Diffusivity?

seanpearsonuk · 2025-08-11T11:21:22Z

examples/00-fluent/single_battery_cell_workflow.py

+wall["wall_active"].thermal.heat_transfer_coeff.value = 5
+
+solver.settings.setup.boundary_conditions.copy(
+    from_="wall_active", to=["wall_n", "wall_p"], verbosity=True


Since it's unobvious what the implication of verbosity=True is, that should be commented here, or preferably the argument should be omitted.

Reason: We need to report the API design in this instance, as once again, this does not belong in the API: verbosity: "Copy boundary conditions: Print more information." in other words, the verbosity=True argument makes this method print directly to the console, which is undesirable for API calls shown in examples (or in general).

Aside: verbose=True and verbosity=1|2|3 would make more sense.

seanpearsonuk · 2025-08-11T11:23:13Z

examples/00-fluent/single_battery_cell_workflow.py

+# Specifying solution settings
+# =====================================================================================
+# Since the simulation models a solid battery without fluid flow,
+# flow and turbulence equations are disabled, and residual criteria are set to none:


For none write "none" to clearly disambiguate from Python None.

seanpearsonuk · 2025-08-11T11:25:05Z

examples/00-fluent/single_battery_cell_workflow.py

+#
+# No flow = No need to solve equations for velocity or pressure.
+#
+# No turbulence = No air or liquid movement that could become chaotic.


It isn't made sufficiently clear how this correlates with the following code. The issue is partly due to API design.

seanpearsonuk · 2025-08-11T11:26:04Z

examples/00-fluent/single_battery_cell_workflow.py

+
+# Surface report for voltage
+surface_reports = solver.settings.solution.report_definitions.surface
+surface_reports.create("voltage_vp")


Avoid obscure abbreviations.

seanpearsonuk · 2025-08-11T11:34:13Z

examples/00-fluent/single_battery_cell_workflow.py

+graphics.picture.save_picture(file_name="Single_Battery_Cell_5.png")
+
+# Save case file
+solver.settings.file.write(file_name="unit_battery.cas.h5", file_type="case")


I realise that the API contains such general methods as read() and write() as well as the specific versions. I have a preference for the latter, especially while file_type is a string argument.

Added example on the battery cell simulation.

5ed713e

MohammedAnsys requested a review from abhishekchitwar August 8, 2025 09:09

MohammedAnsys requested review from mkundu1, seanpearsonuk, prmukherj and hpohekar as code owners August 8, 2025 09:09

Merge branch 'main' into docs/example_on_battery_cell_simulation

5dd6af9

github-actions bot added documentation Documentation related (improving, adding, etc) examples Publishing PyFluent examples labels Aug 8, 2025

hpohekar reviewed Aug 8, 2025

View reviewed changes

doc/source/conf.py Show resolved Hide resolved

hpohekar changed the title ~~Added example on the battery cell simulation.~~ docs: Added example on the battery cell simulation. Aug 8, 2025

chore: adding changelog file 4361.documentation.md [dependabot-skip]

322e51b

prmukherj reviewed Aug 8, 2025

View reviewed changes

examples/00-fluent/single_battery_cell_workflow.py Outdated Show resolved Hide resolved

MohammedAnsys added 3 commits August 8, 2025 16:24

Merge changes from branch 'main' into docs/example_on_battery_cell_si…

025e0f5

…mulation

Merge branch 'docs/example_on_battery_cell_simulation' of https://git…

f053e79

…hub.com/ansys/pyfluent into docs/example_on_battery_cell_simulation

Updated changes as per review comments

b76fcbb

github-actions bot added maintenance General maintenance of the repo (libraries, cicd, etc) CI/CD Related to CI/CD labels Aug 8, 2025

MohammedAnsys requested review from hpohekar and prmukherj August 8, 2025 10:59

MohammedAnsys self-assigned this Aug 8, 2025

hpohekar reviewed Aug 8, 2025

View reviewed changes

.github/workflows/execute-examples-weekly.yml Show resolved Hide resolved

hpohekar approved these changes Aug 8, 2025

View reviewed changes

hpohekar reviewed Aug 8, 2025

View reviewed changes

hpohekar self-requested a review August 8, 2025 11:13

Delete src/ansys/fluent/core/utils/file_transfer_service.py

4853b00

Not relevant to this PR, since deleting it.

abhishekchitwar approved these changes Aug 11, 2025

View reviewed changes

Merge branch 'main' into docs/example_on_battery_cell_simulation

ab743ce

MohammedAnsys requested a review from abhishekchitwar August 11, 2025 08:49

abhishekchitwar approved these changes Aug 11, 2025

View reviewed changes

hpohekar requested changes Aug 11, 2025

View reviewed changes

seanpearsonuk reviewed Aug 11, 2025

View reviewed changes

docs: Added example on the battery cell simulation. #4361

Are you sure you want to change the base?

docs: Added example on the battery cell simulation. #4361

Uh oh!

Conversation

MohammedAnsys commented Aug 8, 2025

Uh oh!

Uh oh!

hpohekar commented Aug 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hpohekar commented Aug 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

prmukherj commented Aug 8, 2025

Uh oh!

MohammedAnsys commented Aug 8, 2025

Uh oh!

Uh oh!

hpohekar Aug 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hpohekar Aug 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

abhishekchitwar left a comment

Choose a reason for hiding this comment

Uh oh!

hpohekar left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

seanpearsonuk Aug 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

seanpearsonuk Aug 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

seanpearsonuk Aug 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

hpohekar commented Aug 8, 2025 •

edited

Loading

hpohekar commented Aug 8, 2025 •

edited

Loading

hpohekar Aug 8, 2025 •

edited

Loading

hpohekar Aug 11, 2025 •

edited

Loading

seanpearsonuk Aug 11, 2025 •

edited

Loading

seanpearsonuk Aug 11, 2025 •

edited

Loading

seanpearsonuk Aug 11, 2025 •

edited

Loading