Particle balance constraint by chris-ashe · Pull Request #4139 · ukaea/PROCESS

chris-ashe · 2026-03-23T15:44:41Z

This pull request introduces a comprehensive plasma fuelling model to the codebase, including new physical variables, input parameters, constraints, and documentation. The main focus is to enable detailed particle balance and burnup fraction calculations for deuterium, tritium, and helium-3 in the plasma, and to ensure consistency through new constraint equations. Several new variables and iteration parameters are added to support these models, and the documentation is expanded to explain the physical basis and equations.

Key changes:

1. Plasma fuelling and particle balance model:

Added a detailed plasma fuelling model and particle balance equations for deuterium, tritium, helium-3, and alpha particles to the documentation (plasma_fuelling.md). This includes explanations of fuelling efficiency, recycling, and burnup fractions.
Added new physics variables in PhysicsData for burnup fractions and detailed fusion reaction rates, enabling more granular tracking of fuel species and reactions. [1] [2]

2. New input and iteration variables:

Introduced new input parameters in input.py for fuelling efficiency, injected fuel rates, and fuelling fractions for each species.
Added corresponding iteration variables for these new inputs, allowing them to be varied during optimization and scans.

3. Particle balance and consistency constraints:

Implemented new constraint equations (93–97) in constraints.py to enforce particle balance for tritium, deuterium, helium-3, alpha particles, and to ensure fuelling fractions sum to unity. These constraints help maintain physical consistency in the plasma model.
Updated numerics to include these new constraints, increasing the total number of constraints and variables. [1] [2] [3]

4. Documentation and navigation updates:

Added the new plasma fuelling documentation page to the navigation in mkdocs.yml, making the new model easily accessible in the documentation site.

5. Miscellaneous improvements:

Added Avogadro's number to the constants module for use in physical calculations.
Improved output reporting for constraint errors in scan.py.

These changes collectively provide a robust framework for modeling plasma fuelling, tracking individual fuel species, and ensuring physical consistency in fusion plasma simulations.

Checklist

I confirm that I have completed the following checks:

My changes follow the PROCESS style guide
I have justified any large differences in the regression tests caused by this pull request in the comments.
I have added new tests where appropriate for the changes I have made.
If I have had to change any existing unit or integration tests, I have justified this change in the pull request comments.
If I have made documentation changes, I have checked they render correctly.
I have added documentation for my change, if appropriate.

chris-ashe · 2026-03-31T09:29:11Z

Opening this up now just to get the ball rolling with the review. @jonmaddock a discussion should be had about how we implement this into the regression tests, e.g is the 4 balance constraints always on as default

jonmaddock · 2026-04-20T15:11:17Z

As this is contingent on the wider "solution mode" work going in (which I am currently working on), I am converting this to a draft until that is merged.

Edit: I'm wrong about this: this can go in without waiting for the above work.

codecov-commenter · 2026-06-17T13:08:01Z

Codecov Report

❌ Patch coverage is 32.65993% with 200 lines in your changes missing coverage. Please review.
✅ Project coverage is 48.81%. Comparing base (d84e9dd) to head (3e5c5fd).
⚠️ Report is 18 commits behind head on main.

Files with missing lines	Patch %	Lines
process/core/io/plot/summary.py	4.13%	139 Missing ⚠️
process/models/physics/fuelling.py	43.54%	35 Missing ⚠️
process/models/physics/physics.py	5.55%	17 Missing ⚠️
process/core/solver/constraints.py	82.60%	4 Missing ⚠️
process/models/physics/fusion_reactions.py	0.00%	3 Missing ⚠️
process/core/scan.py	0.00%	1 Missing ⚠️
process/models/stellarator/stellarator.py	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4139      +/-   ##
==========================================
- Coverage   48.86%   48.81%   -0.06%     
==========================================
  Files         151      152       +1     
  Lines       29461    29671     +210     
==========================================
+ Hits        14397    14484      +87     
- Misses      15064    15187     +123

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

…lotting

…flow contours

…tium, and helium-3

… rate parameters, and update plotting functions for alpha particle flow rate and fusion DT rate.

…ple files and update related calculations and tests

…iles and update related calculations and tests

…ated plotting functions for tritium, deuterium, and alpha particle flow rates

…nd add fuelling information display

…uel burnup fraction computation across models

…y constraints for consistency models

…ing class and update plotting function calls for consistency

… cleanup

…ables

…uelling_required' and update references to 'molflow_plasma_fuelling_vv_injected' across models and tests

… the PlasmaFuelling class

… with improved color mapping and titles

…onal figures

…ficiency and recycling coefficient, and introduce METIS Alpha Confinement model

…ss and update parameter descriptions

… for tritium, deuterium, helium-3, and alpha particle balances

…clarify recycling coefficient, and introduce fuel burnup fraction equations

…s and add particle balance equations

jonmaddock

Please fixup these commits to reduce churn and provide more descriptive commit messages: it's a bit hard to review at the moment.

jonmaddock · 2026-06-25T10:33:05Z

+        return self._description_
+
+
+ipnvars: int = 180


I don't think this belongs in this PR: it should be separate.

jonmaddock · 2026-06-25T10:36:34Z

+
+
+@ConstraintManager.register_constraint(93, "particles/s", "=")
+def constraint_equation_93():


This appears to be a copy of the previous constraint.

jonmaddock · 2026-06-25T10:37:24Z

+    ),
+    "molflow_plasma_fuelling_vv_injected": InputVariable(
+        data_structure.physics_variables, float, range=(0.0, 1e24)
+    ),


Please fixup into previous commit where these were created.

jonmaddock · 2026-06-25T10:38:50Z


 @ConstraintManager.register_constraint(93, "particles/s", "=")
-def constraint_equation_93():
+def constraint_equation_93(constraint_registration):


Please fixup the original commit where this constraint was added with this commit to reduce churn for the reviewer.

jonmaddock · 2026-06-25T10:40:32Z

        )
    )

+    return leq(numerator, 1e10, constraint_registration)


jonmaddock · 2026-06-25T10:43:45Z

+
+
+@ConstraintManager.register_constraint(94, "particles/s", "<=")
+def constraint_equation_94(constraint_registration):


Please re-write the commit message to describe why this constraint is being added: "update" is not descriptive for the reviewer. Three constraints have been modified here in a single commit.

jonmaddock · 2026-06-25T10:46:32Z

+    )

-    return leq(numerator, 1e10, constraint_registration)
+    return eq(numerator / 1e20, 1e-8, constraint_registration)


There's a bit too much churn here: please fixup commits and write descriptive commit messages to help me review!

jonmaddock · 2026-06-25T10:53:12Z

-            / (1 - data_structure.physics_variables.f_plasma_particles_lcfs_recycled)
-        )
+    )
+    denominator = (


Can't understand what the change is as commit message not descriptive: why are you making this change?

chris-ashe added Physics Relating to the physics models Plotting labels Mar 23, 2026

chris-ashe force-pushed the particle_balance_constraint branch 2 times, most recently from 1397135 to 7687c7b Compare March 31, 2026 09:25

chris-ashe marked this pull request as ready for review March 31, 2026 09:27

chris-ashe requested a review from a team as a code owner March 31, 2026 09:28

chris-ashe requested a review from jonmaddock March 31, 2026 09:28

timothy-nunn assigned jonmaddock Apr 1, 2026

jonmaddock marked this pull request as draft April 20, 2026 15:11

chris-ashe force-pushed the particle_balance_constraint branch 3 times, most recently from 1dd8c7f to 49236ad Compare June 2, 2026 09:39

chris-ashe force-pushed the particle_balance_constraint branch 2 times, most recently from 40ad502 to b37ac1f Compare June 17, 2026 12:58

chris-ashe force-pushed the particle_balance_constraint branch 2 times, most recently from 0d49bab to 43e8f8c Compare June 17, 2026 13:15

chris-ashe requested review from grmtrkngtn and timothy-nunn June 17, 2026 14:49

chris-ashe added Variable rename Input/Output Files Issues related to the input and output data files labels Jun 17, 2026

chris-ashe marked this pull request as ready for review June 17, 2026 14:50

chris-ashe requested a review from j-a-foster June 17, 2026 15:02

chris-ashe force-pushed the particle_balance_constraint branch 2 times, most recently from 90086ef to 37c5d94 Compare June 17, 2026 15:36

chris-ashe added 3 commits June 17, 2026 16:36

Add new plasma physics variables and update iteration variable count

9210e9a

Add particle balance constraint equation and update constraint count

9081e52

Add new plasma physics input variables for recycling and fuelling

b28ffda

chris-ashe added 28 commits June 17, 2026 16:36

Add deuterium and alpha particle flow rate calculations and contour p…

8cd99b6

…lotting

Add plotting of fuelling efficiency and recycling fraction in plasma …

0c821db

…flow contours

Add plasma fuelling equations and documentation

d259c03

Add D-3He fusion rate and neutron production rate calculations

54db27a

Add fuelling composition variables and constraints for deuterium, tri…

9e9aa5e

…tium, and helium-3

Enhance plasma flow calculations by adding tritium and deuterium flow…

d78757c

… rate parameters, and update plotting functions for alpha particle flow rate and fusion DT rate.

Rename burn-up fraction variable to f_plasma_fuel_burnup across multi…

1b903ed

…ple files and update related calculations and tests

Refactor fuel burn-up rate variable to fusrat_total across multiple f…

55d08f1

…iles and update related calculations and tests

Refactor plasma exhaust calculations to plasma fuelling, updating rel…

e06b0a9

…ated plotting functions for tritium, deuterium, and alpha particle flow rates

Refactor plasma fuelling plotting functions to improve organization a…

3ebde65

…nd add fuelling information display

Integrate PlasmaFuelling class into physics calculations and update f…

d8aec4d

…uel burnup fraction computation across models

Enhance plasma fuelling documentation with flow rate equations and ke…

c88c865

…y constraints for consistency models

Refactor fuelling output logic to use dedicated method in PlasmaFuell…

6772cea

…ing class and update plotting function calls for consistency

🔥 Remove tauratio variable from input variables and related tests for…

32961f2

… cleanup

Add tritium and deuterium burnup calculations and update physics vari…

659fb1b

…ables

🔥 Refactor plasma fuelling variables: remove unused 'molflow_plasma_f…

0760176

…uelling_required' and update references to 'molflow_plasma_fuelling_vv_injected' across models and tests

Add Avogadro's number constant with reference documentation

3a91922

Add plasma fuelling loss calculations and update related variables in…

ebc45c1

… the PlasmaFuelling class

Add helium-3 flow contour plotting and enhance existing contour plots…

6aed3e6

… with improved color mapping and titles

Refactor plotting indices in main_plot function to accommodate additi…

b26a3e1

…onal figures

Enhance plasma fuelling documentation: add definitions for exhaust ef…

d594337

…ficiency and recycling coefficient, and introduce METIS Alpha Confinement model

Refactor Physics model and unit tests to integrate PlasmaFuelling cla…

694d95b

…ss and update parameter descriptions

Post rebase fixes

6004cfb

post rebase fixes

4789875

Enhance plasma fuelling documentation and update constraint equations…

af1ecc7

… for tritium, deuterium, helium-3, and alpha particle balances

Enhance plasma fuelling documentation: add particle balance section, …

74eac1c

…clarify recycling coefficient, and introduce fuel burnup fraction equations

Update large tokamak input file: adjust number of equality constraint…

6b5fa2c

…s and add particle balance equations

Fix bug in output caused by rebase

3e5c5fd

chris-ashe force-pushed the particle_balance_constraint branch from 37c5d94 to 3e5c5fd Compare June 17, 2026 15:36

jonmaddock requested changes Jun 25, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Particle balance constraint#4139

Particle balance constraint#4139
chris-ashe wants to merge 42 commits into
mainfrom
particle_balance_constraint

chris-ashe commented Mar 23, 2026 •

edited

Loading

Uh oh!

chris-ashe commented Mar 31, 2026

Uh oh!

jonmaddock commented Apr 20, 2026 •

edited

Loading

Uh oh!

codecov-commenter commented Jun 17, 2026 •

edited

Loading

Uh oh!

jonmaddock left a comment

Uh oh!

jonmaddock Jun 25, 2026

Uh oh!

jonmaddock Jun 25, 2026

Uh oh!

jonmaddock Jun 25, 2026

Uh oh!

jonmaddock Jun 25, 2026

Uh oh!

jonmaddock Jun 25, 2026

Uh oh!

jonmaddock Jun 25, 2026

Uh oh!

jonmaddock Jun 25, 2026

Uh oh!

jonmaddock Jun 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants



		@ConstraintManager.register_constraint(93, "particles/s", "=")
		def constraint_equation_93():



		@ConstraintManager.register_constraint(94, "particles/s", "<=")
		def constraint_equation_94(constraint_registration):

Uh oh!

Conversation

chris-ashe commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

Uh oh!

chris-ashe commented Mar 31, 2026

Uh oh!

jonmaddock commented Apr 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov-commenter commented Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

jonmaddock 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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

chris-ashe commented Mar 23, 2026 •

edited

Loading

jonmaddock commented Apr 20, 2026 •

edited

Loading

codecov-commenter commented Jun 17, 2026 •

edited

Loading