Update `add-vars.md` by timothy-nunn · Pull Request #4332 · ukaea/PROCESS

timothy-nunn · 2026-06-17T16:18:12Z

Updated the guide for adding variables, inputs, scan vars, figures of merit, and iteration vars. They needed a refresh due to changes in the Python conversion, recent data structure changes, and enumification.

I have also reduced the need for users to manually increment some variables (was not possible for the scan variables due to circular imports).

codecov-commenter · 2026-06-17T16:26:58Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 48.64%. Comparing base (6af8115) to head (e919aa6).
⚠️ Report is 12 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4332      +/-   ##
==========================================
- Coverage   48.86%   48.64%   -0.23%     
==========================================
  Files         151      151              
  Lines       29417    29675     +258     
==========================================
+ Hits        14374    14434      +60     
- Misses      15043    15241     +198

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

timothy-nunn · 2026-06-18T08:33:02Z

Requesting a couple of reviews to ensure these docs make sense and are sufficiently detailed

clmould

All minor things, mostly suggested changes, but otherwise happy with the content

clmould · 2026-07-08T17:57:23Z

+my_new_blanket_variable = 1.0
+```

+-----------------


Do we need a bit here about how the value of an input variable is unchanged throughout a run ?

This point is made at least twice in the document, I think that should be enough

Just read through the whole page again and this point isn't made until the 'add an iteration variable' section - I think it'd be better to include it in the 'add an input ' section and then can shorten or delete the sentence in the iteration variable section

At the top of the page:

It is advised that a variable is either used to define a particular PROCESS run (input variable, iteration variable, or scan variable) or mutated within a PROCESS run (output variable or intermediate variable). Mixing the two classes of variable (e.g. having a variable that can be input but is also mutated within a model) will lead to confusing, dangerous, and incorrect results.

clmould · 2026-07-08T18:01:34Z

 ## Add a constraint equation

-Constraint equations are added to *PROCESS* in the `process/core/solver/constraints.py` file. They are registered with the `ConstraintManager` whenever the application is run. Each equation has a unique name that is currently an integer, however upgrades to the input file format in the future will allow arbitrary hashable constraint names. 
+Constraint equations are added to PROCESS in the `process/core/solver/constraints.py` file. They are registered with the `ConstraintManager` whenever the application is run. Each equation has a unique name that is currently an integer, however upgrades to the input file format in the future will allow arbitrary hashable constraint names.


Will updates to the input file format mean changes for more things in this page other than just constraints? If so, probably worth a general note at the start of this page? Might not though, just thought I'd ask!

Tbh that information is probably not necessary and I will remove it

…variables

Co-authored-by: clmould <86794332+clmould@users.noreply.github.com> Co-authored-by: Christopher Ashe <91618944+chris-ashe@users.noreply.github.com>

Co-authored-by: clmould <86794332+clmould@users.noreply.github.com>

clmould · 2026-07-09T15:22:02Z

@@ -153,20 +174,26 @@ The arguments to the `register_constraint` function are:

 - Name (again, currently an integer)
 - Unit (for output reporting purposes)
- Symbol (e.g. =, >=, <=. Again, for output reporting purposes)
+- Symbol (e.g. `=`, `>=`, `<=`. Again, for output reporting purposes)


Suggested change

- Symbol (e.g. `=`, `>=`, `<=`. Again, for output reporting purposes)

think github might've messed up my suggestion ! not sure why it added it instead of overwriting !

chris-ashe

@clmould comments have covered my comments

clmould

1 q and 1 small reordering request/suggestion, but otherwise happy with this !

clmould · 2026-07-15T16:53:18Z

+my_new_blanket_variable = 1.0
+```

+-----------------


Just read through the whole page again and this point isn't made until the 'add an iteration variable' section - I think it'd be better to include it in the 'add an input ' section and then can shorten or delete the sentence in the iteration variable section

clmould · 2026-07-15T16:54:26Z

+```
+my_new_blanket_variable = 1.0
+```



Suggested change

Note you can omit the line specifying the initial value for an input variable, and then the initial value would just be whatever that variable's default value is: in this example we could omit the `my_new_blanket_variable = 1.0` line, and `my_new_blanket_variable` would take its initial value as the default of `0.0` that we assigned [earlier](#add-a-new-variable).

clmould · 2026-07-15T17:06:25Z

+my_new_blanket_variable = 0.5
+```
+
+Note you can omit the line specifying the initial value for an iteration variable, and then the initial value would just be whatever that variable's default value is: in this example we could omit the `my_new_blanket_variable = 0.5` line, and `my_new_blanket_variable` would take its initial value as the default of `0.0` that we assigned [earlier](#add-a-new-variable).


Suggested change

Note you can omit the line specifying the initial value for an iteration variable, and then the initial value would just be whatever that variable's default value is: in this example we could omit the `my_new_blanket_variable = 0.5` line, and `my_new_blanket_variable` would take its initial value as the default of `0.0` that we assigned [earlier](#add-a-new-variable).

Again, note that omitting the line specifying the initial value for an iteration variable means the initial value would be set to that variable's default value.

This sentence could instead be deleted, but suggested a change in line with my other here in case you want to keep it, idm either way!

clmould

small change but happy otherwise

Co-authored-by: clmould <86794332+clmould@users.noreply.github.com>

* Update docs for adding variables, inputs, scans, FoMs, and iteration variables * Remove need to increment numerics IP variables * Correct bullet list formatting * Ensure ipeqns is maximum constraint ID * Fix cyclic import * Fix spelling/grammar errors Co-authored-by: clmould <86794332+clmould@users.noreply.github.com> Co-authored-by: Christopher Ashe <91618944+chris-ashe@users.noreply.github.com> * Clarify sections of add-vars.md * Rewording docs Co-authored-by: clmould <86794332+clmould@users.noreply.github.com> * Further clarifications * Lingering bullet * Remove duplication * Clarify default values being used * Spelling mistake Co-authored-by: clmould <86794332+clmould@users.noreply.github.com> --------- Co-authored-by: clmould <86794332+clmould@users.noreply.github.com> Co-authored-by: Christopher Ashe <91618944+chris-ashe@users.noreply.github.com>

timothy-nunn linked an issue Jun 17, 2026 that may be closed by this pull request

Update add-vars.md #3664

Closed

timothy-nunn requested review from chris-ashe and clmould June 18, 2026 08:32

timothy-nunn marked this pull request as ready for review June 18, 2026 08:32

timothy-nunn requested a review from a team as a code owner June 18, 2026 08:32

timothy-nunn force-pushed the 3664-update-add-varsmd branch from 0aba1cf to d1dd370 Compare June 18, 2026 14:55

clmould requested changes Jun 18, 2026

View reviewed changes

clmould self-assigned this Jun 18, 2026

chris-ashe requested changes Jun 19, 2026

View reviewed changes

Comment thread documentation/source/development/add-vars.md Outdated

Comment thread documentation/source/development/add-vars.md

Comment thread documentation/source/development/add-vars.md Outdated

Comment thread documentation/source/development/add-vars.md Outdated

timothy-nunn requested review from chris-ashe and clmould June 23, 2026 13:32

chris-ashe reviewed Jul 9, 2026

View reviewed changes

Comment thread documentation/source/development/add-vars.md

clmould requested changes Jul 9, 2026

View reviewed changes

timothy-nunn requested a review from clmould July 9, 2026 14:30

timothy-nunn and others added 9 commits July 9, 2026 16:09

Update docs for adding variables, inputs, scans, FoMs, and iteration …

62bacaf

…variables

Remove need to increment numerics IP variables

6e16114

Correct bullet list formatting

adcb0fb

Ensure ipeqns is maximum constraint ID

d7c7f65

Fix cyclic import

83c779e

Fix spelling/grammar errors

51ca011

Co-authored-by: clmould <86794332+clmould@users.noreply.github.com> Co-authored-by: Christopher Ashe <91618944+chris-ashe@users.noreply.github.com>

Clarify sections of add-vars.md

4bc6805

Rewording docs

7945d26

Co-authored-by: clmould <86794332+clmould@users.noreply.github.com>

Further clarifications

3af3782

timothy-nunn force-pushed the 3664-update-add-varsmd branch from a18ef77 to 3af3782 Compare July 9, 2026 15:11

clmould requested changes Jul 9, 2026

View reviewed changes

chris-ashe approved these changes Jul 10, 2026

View reviewed changes

Lingering bullet

76ce08f

timothy-nunn requested a review from clmould July 15, 2026 10:45

Remove duplication

36ffd74

clmould requested changes Jul 15, 2026

View reviewed changes

Clarify default values being used

3117e07

clmould requested changes Jul 16, 2026

View reviewed changes

Comment thread documentation/source/development/add-vars.md Outdated

Spelling mistake

e919aa6

Co-authored-by: clmould <86794332+clmould@users.noreply.github.com>

timothy-nunn requested a review from clmould July 16, 2026 12:04

clmould approved these changes Jul 16, 2026

View reviewed changes

clmould merged commit 3de7ef7 into main Jul 16, 2026
10 of 11 checks passed

clmould deleted the 3664-update-add-varsmd branch July 16, 2026 12:30



	Note you can omit the line specifying the initial value for an input variable, and then the initial value would just be whatever that variable's default value is: in this example we could omit the `my_new_blanket_variable = 1.0` line, and `my_new_blanket_variable` would take its initial value as the default of `0.0` that we assigned [earlier](#add-a-new-variable).

	Note you can omit the line specifying the initial value for an iteration variable, and then the initial value would just be whatever that variable's default value is: in this example we could omit the `my_new_blanket_variable = 0.5` line, and `my_new_blanket_variable` would take its initial value as the default of `0.0` that we assigned [earlier](#add-a-new-variable).
	Again, note that omitting the line specifying the initial value for an iteration variable means the initial value would be set to that variable's default value.

Uh oh!

Conversation

timothy-nunn commented Jun 17, 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!

timothy-nunn commented Jun 18, 2026

Uh oh!

clmould left a comment • 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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chris-ashe left a comment

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

clmould left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

timothy-nunn commented Jun 17, 2026 •

edited

Loading

codecov-commenter commented Jun 17, 2026 •

edited

Loading

clmould left a comment •

edited

Loading