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

chris-ashe · 2026-06-29T12:32:35Z

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.

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.

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.

🎨 Output additions

Expanded and added more values for rates to the fusion reaction summary page:

Added a fuelling summary page that shows the contour graphs of the fuelling solutions, along with burnup data:

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.

…ng to be used to solve the fuelling and burnup equations

…riton, needed to know the indvidual fuel production and removal rates

…ude the equations for main fuel species flow and thermal alpha flow

…PlasmaFuelling model

…Physics class run workflow

…euterium, helium-3, and alpha particles

… for the burnup and fuelling rate now being calculated implicitly

…to previous functions and tests

…ass. Add details for some fusion reactions also

…ay in summary file

j-a-foster

Just a couple of notes, otherwise happy with the changes.

j-a-foster · 2026-06-29T14:42:21Z

+        f"Plasma power: {mfile.get('p_plasma_alpha_mw', scan=scan):.4f} MW\n"
+        f"Beam power: {mfile.get('p_beam_alpha_mw', scan=scan):.4f} MW\n\n"
+        f"Rate density total: {mfile.get('fusden_alpha_total', scan=scan):.4e} particles/m$^3$/sec\n"
+        f"Rate density, plasma: {mfile.get('fusden_plasma_alpha', scan=scan):.4e} particles/m$^3$/sec\n\n"


Why are these /sec and not /s?

j-a-foster · 2026-06-29T14:55:44Z

+        linewidths=2,
+    )
+
+    # Plot star for mfile values


Is it worth adding a note or legend that explains what the star means in the PDF?

jonmaddock

Please sort out the PR description: I think it's too verbose and misses/buries the key point which is that you're introducing constraints to enforce density equilibrium of individual ion species. Why are you making this PR?
Have you removed the original molflow_plasma_fuelling_required as an output? I might have missed that
I counted 6 new optimisation parameters and 5 new constraints: as per our conversation, can you describe how this might work in solution mode, i.e. when we require a determined system?
Some plots to demonstrate these changes would be useful: for example how the constraints are accommodated with increasing te or ne, for example. How does this change the current large tokamak solution?
Please don't rebase until the PR is approved, so we can track comments
How does this compare to the existing burnup calculation? Has it been removed?
The created docs were excellent
I'd like this PR to include what equations and parameters should be included in optimisation and solution scenarios. If the solution system is under-determined, how useful is it?
I'm not sure about the fuelling composition constraint and total fuelling rate. Would individual species rates reduce the dimensionality?
Should the recycling fraction and fuelling efficiency be optimisation parameters? (I realise we've discussed this, but I think it should be made clear why these can be used to solve the constraints).

Thanks for the fixed-up commits, this was much easier to review.

jonmaddock · 2026-06-30T13:54:40Z

+
+
+class PlasmaFuelling(Model):
+    """Class to hold plasma fuelling calculations for plasma processing."""


Plasma processing? Could you be a bit more descriptive here?

jonmaddock · 2026-06-30T13:59:11Z

+        Returns
+        -------
+        float
+            Alpha particle flow rate in the plasma exhaust (particles/s).


Isn't this the wrong way around? It's the flow rate into the plasma (for a positive returned value), not the exhaust?

jonmaddock · 2026-06-30T14:00:12Z

+        nd_plasma_alphas_vol_avg: float,
+        vol_plasma: float,
+    ) -> float:
+        """Calculate the alpha particle flow rate in the plasma exhaust.


Shouldn't these be in the exhaust model?

The comment has been ammended, since it works the exact same as the other fuel models and returns the source rate, I think it is best to leave it with the group.

jonmaddock · 2026-06-30T14:02:11Z

+
+        self.data.physics.fusrat_dt_total = (
+            self.data.physics.p_dt_total_mw * 1e6 / (constants.D_T_ENERGY)
+        )


Are all of these not already calculated elsewhere?

No, I had to add them. We have values for the powers but all of the actual rates were done in situ before. There is changes to the fusion power summary page which I will add to the PR overview also

jonmaddock · 2026-06-30T14:05:06Z

+
+        Notes
+        -----
+        The fusion rate is multiplied by two to convert from nucleus pairs to particles,


Not multiplied by 2 here.

jonmaddock · 2026-06-30T14:39:24Z

+        * data.physics.vol_plasma
+        * data.physics.f_plasma_fuel_helium3
+    ) / (
+        data.physics.t_energy_confinement


Does He3 follow the energy confinement time rather than the tau_alpha / tau_E = 5 relation?

This is a point we should discuss, I dont see why we wouldn't treat it the same as 4He

jonmaddock · 2026-06-30T15:14:26Z

+\tau_{\alpha} = f_{\alpha}\tau_{\text{E}}\frac{R}{1-R}\tau_{\text{ne}}
+$$
+
+This is the model currently in METIS[^2] and is found in [^3]


But this isn't used in Process?

jonmaddock · 2026-06-30T15:16:03Z

+
+--------------
+
+### Tritium Flow Rate | `calculate_plasma_tritium_flow_rate()`


Not sure about "flow rate": it's the density derivative in the plasma.

I left it as flow rate as the functions returns the net particle flow in the plasma, so not necessarily the density

jonmaddock · 2026-06-30T15:20:52Z

+f_{\text{fuelling,D}} + f_{\text{fuelling,T}} + f_{\text{fuelling,3He}} = 1.0
+$$
+
+**It is recommended to have this constraint on as it is a plasma consistency model**


I think you need to be more explicit about the system of equations (i.e. all of the above constraints) and the solution parameters (i.e. optimisation parameters) used to solve them. What's should the user do to enforce all of these constraints in their optimisation problem?

jonmaddock · 2026-06-30T15:22:16Z

+    )
+
+    plot_fuelling_info(pages["fuelling"], m_file, scan)
+


Can I see these plots in the PR please?

chris-ashe · 2026-07-01T07:44:11Z

@timothy-nunn If I try and use the functions in fuelling.py instead of re-writing the equations explicitly in constraint.py I get an inf error on the first iteration, would you be able to look at this as we had problems before about the constraint value

…resents

chris-ashe added 16 commits June 29, 2026 11:11

Add new input and iteration variables for plasma fuelling and recycli…

66a0493

…ng to be used to solve the fuelling and burnup equations

Add Avogadro's number constant with reference documentation

695eae7

Add fusion rate density calculations for D-3He, D-D Helion, and D-D T…

06d07be

…riton, needed to know the indvidual fuel production and removal rates

Add PlasmaFuelling model class and integrate into Physics class. Incl…

abca001

…ude the equations for main fuel species flow and thermal alpha flow

Add fusion rate calculations for D-T and D-D reactions in Physics model

f6b88ef

Add burnup fraction calculations for fuel, tritium, and deuterium in …

68d053d

…PlasmaFuelling model

Implement run method for PlasmFuelling class and implement into main …

f5f6c38

…Physics class run workflow

Add PlasmaFuelling model integration into Models class

cf59d4f

Add particle balance consistency equations constraints for tritium, d…

9a8af49

…euterium, helium-3, and alpha particles

Refactor phyaux method and related calculations in Physics to account…

58a0b65

… for the burnup and fuelling rate now being calculated implicitly

Remove now obsolete variables for phyaux and implement new variables …

65d6a0e

…to previous functions and tests

Add output method for fuelling info and refactor output in Physics cl…

e244024

…ass. Add details for some fusion reactions also

Calculate plasma fuel burnup fraction in Stellarator model

4b7250c

Add plasma fuelling documentation and update navigation in mkdocs

798f6bd

Add fuelling flow contour plots and update fuelling information displ…

e29c891

…ay in summary file

Add new constraints to large_tokamak input and fix some runtime bugs

7b6a5d3

chris-ashe added Physics Relating to the physics models Variable rename Input/Output Files Issues related to the input and output data files Documentation Improvements or additions to documentation Plotting labels Jun 29, 2026

chris-ashe assigned jonmaddock Jun 29, 2026

chris-ashe requested review from grmtrkngtn, j-a-foster, jonmaddock and timothy-nunn June 29, 2026 12:35

chris-ashe mentioned this pull request Jun 29, 2026

Particle balance constraint #4139

Closed

6 tasks

chris-ashe marked this pull request as ready for review June 29, 2026 12:36

chris-ashe requested a review from a team as a code owner June 29, 2026 12:36

j-a-foster requested changes Jun 29, 2026

View reviewed changes

jonmaddock requested changes Jun 30, 2026

View reviewed changes

Add more descriptive notes to each function about what the output rep…

029d901

…resents



		class PlasmaFuelling(Model):
		"""Class to hold plasma fuelling calculations for plasma processing."""


		--------------

		### Tritium Flow Rate \| `calculate_plasma_tritium_flow_rate()`

Uh oh!

Conversation

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

Uh oh!

Checklist

Uh oh!

j-a-foster 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!

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!

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!

chris-ashe commented Jul 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

chris-ashe commented Jun 29, 2026 •

edited

Loading