Update add-vars.md#4332
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #4332 +/- ##
=======================================
Coverage 48.79% 48.80%
=======================================
Files 151 151
Lines 29383 29387 +4
=======================================
+ Hits 14337 14341 +4
Misses 15046 15046 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
|
Requesting a couple of reviews to ensure these docs make sense and are sufficiently detailed |
timothy-nunn
force-pushed
the
3664-update-add-varsmd
branch
from
0aba1cf to
d1dd370
Compare
| ----------------- | ||
|
|
||
| ## Add a new variable | ||
| You may need to add a variable to PROCESS when changing or creating models. In most cases, you will want to add your variable to an existing data structure. Creating an entierly new data structure is beyond the scope of this guide, so please seek support from the PROCESS maintainers. |
There was a problem hiding this comment.
| You may need to add a variable to PROCESS when changing or creating models. In most cases, you will want to add your variable to an existing data structure. Creating an entierly new data structure is beyond the scope of this guide, so please seek support from the PROCESS maintainers. | |
| You may need to add a variable to PROCESS when changing or creating models. In most cases, you will want to add your variable to an existing data structure. Creating an entirely new data structure is beyond the scope of this guide, so please seek support from the PROCESS maintainers. |
| INPUT_VARIABLES = { | ||
| ... | ||
| "rho_tf_joints": InputVariable("tfcoil", float, range=(0.0, 0.01)), | ||
| "my_new_blanket_variable": InputVariable("blanket", str), |
There was a problem hiding this comment.
| "my_new_blanket_variable": InputVariable("blanket", str), | |
| "my_new_blanket_variable": InputVariable("blanket", float), |
| Continuing with the example from the previous section: | ||
| ```python | ||
| INPUT_VARIABLES = { | ||
| INPUT_VARIABLES = { |
There was a problem hiding this comment.
Around here can you make a note about choices, ranges and array=True that people may need to know about
| - `0.1` is the default lower bound of the variable. | ||
| - `1.0` is the default upper bound of the variable. | ||
|
|
||
| You will often want to add a variable as an input if it is an iteration variable. That way, you can specify the initial value of the iteration variable. |
There was a problem hiding this comment.
| You will often want to add a variable as an input if it is an iteration variable. That way, you can specify the initial value of the iteration variable. | |
| You will often want to add a variable to the input file if it is an iteration variable. That way, you can specify the initial value of the iteration variable. |
Think this might be clearer, so as not to be confused with setting it as an InputVariable
Also why might someone have an iteration variable they don't add to the input file? Would it just take a default initial value in this case? I think the 'you will often want to add ' might need rewording ?
| ``` | ||
| ixc = 123 | ||
|
|
||
| my_new_blanket_variable = 0.5 * initial value (optional) |
There was a problem hiding this comment.
Would it help to specify here that * is a comment in the .DAT file, or is the user assumed to know this already? Or perhaps just removing this inline comment
| ----------------- | ||
| In general, a variable within a data structure could act as an: | ||
|
|
||
| - Input variable: is specified by the user in an `IN.DAT`/has a default value and is not changed once PROCESS is running. |
There was a problem hiding this comment.
| - Input variable: is specified by the user in an `IN.DAT`/has a default value and is not changed once PROCESS is running. | |
| - Input variable: is specified by the user in an `IN.DAT` and its value is not changed once PROCESS is running. |
And think adding a note (either in this list, or after it) to say something like 'already available input variables can be found in input.py - these will take their default values unless otherwise specified in the IN.DAT, and will remain unchanged during a PROCESS run'
| - Iteration variable: is modified by the solver to try and optimise for some figure of merit. | ||
| - Scan variable: is sequentially modified by the `Scan` class to some `IN.DAT`-defined values. | ||
| - Intermediate variable: is calculated within a model and then used within other models. | ||
| - Output variable: is calculated within a model and then written out the `MFILE.DAT`. |
There was a problem hiding this comment.
| - Output variable: is calculated within a model and then written out the `MFILE.DAT`. | |
| - Output variable: is calculated within a model and then written out to the `MFILE.DAT`. |
|
|
||
| IPEQNS = 92 | ||
| """number of constraint equations available""" | ||
| IPEQNS = 500 |
There was a problem hiding this comment.
How/why is this 500? Is it just an arbitrary upper limit?
Also would it be worth renaming it to reflect its updated definition?
| """maximum number of constraint equations available""" | ||
|
|
||
| IPNFOMS = 19 | ||
| IPNFOMS = len(FiguresOfMerit) |
There was a problem hiding this comment.
I'm not sure this is being used anywhere any more? Or at least if I search for it it just comes up once? (Might've been missed in my numerics dataclass pr tbh, whoops!)
| @ConstraintManager.register_constraint(1234, "m", "=") | ||
| def my_constraint_function(constraint_registration): | ||
| return geq(value, bound, constraint_registration) | ||
| return geq(value, bound, constraint_registration) |
There was a problem hiding this comment.
| return geq(value, bound, constraint_registration) | |
| return eq(value, bound, constraint_registration) |
| !! TF joints surfacic resistivity [ohm.m] | ||
| !! Feldmetal joints assumed. | ||
| my_new_blanket_variable: float = 0.0 | ||
| """my variable description""" |
There was a problem hiding this comment.
Would it be worth saying here to add the units in [] at the end?
| ... | ||
| another_variable = self.data.blanket.my_new_blanket_variable / 2.0 | ||
| ``` | ||
|
|
There was a problem hiding this comment.
Missing ------------ delimiter between sections
| ... | ||
| BLANKET_FIGURE_MERIT = (20, "my FOM description") | ||
| ``` | ||
| Here `20` will be the identifier of the figure of merit, and must be unique. |
There was a problem hiding this comment.
| Here `20` will be the identifier of the figure of merit, and must be unique. | |
| Here `20` will be the identifier of the figure of merit, and **must** be unique. |
|
|
||
| ## 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. |
There was a problem hiding this comment.
| 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. |
4 participants
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).