Autogenerate api docs

.github/workflows/process.yml

@@ -178,7 +178,6 @@ jobs:
         uses: Fusion-Power-Plant-Framework/fppf-actions/setup-hatch@main
         with:
           python-version: ${{ env.python-version }}
-      - run: hatch run python scripts/vardes.py
       - run: git config --global --add safe.directory '*'
       - name: Download STF_TF.json files
         uses: actions/download-artifact@v4

.gitignore

@@ -46,7 +46,6 @@ process/io/python_fortran_dicts.json
 fortran.py
 .coverage
 dist/*
-documentation/io/vardes.md
 lcov_results/
 env/
 .venv

documentation/scripts/gen_api_ref.py

@@ -0,0 +1,42 @@
+# SPDX-FileCopyrightText: 2023-present The Bluemira Developers <https://github.com/Fusion-Power-Plant-Framework/bluemira>
+#
+# SPDX-License-Identifier: LGPL-2.1-or-later
+"""Generate the API reference pages and navigation."""
+
+from pathlib import Path
+
+import mkdocs_gen_files
+from mkdocs_gen_files.nav import Nav
+
+nav = Nav()
+
+root = Path(__file__).parent.parent.parent
+package_name = "process"
+src = root / package_name
+reference = Path("source", "reference")
+
+for path in sorted(src.rglob("*.py")):
+    module_path = path.relative_to(root).with_suffix("")
+    doc_path = path.relative_to(root).with_suffix(".md")
+    full_doc_path = Path(reference, doc_path)
+
+    parts = tuple(module_path.parts)
+
+    # if is_init:= (parts[-1] =="__init__"):
+    #     parts = parts[:-1]
+    #     if len(parts) > 1:
+    #         continue
+    if parts[-1] in {"__init__", "__main__", "_version"}:
+        continue
+
+    p = ".".join(parts)
+    # parts = (*parts, p) if is_init else parts
+    nav[parts] = doc_path.as_posix()
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        fd.write(f"::: {p}")
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, path.relative_to(root))
+
+with mkdocs_gen_files.open(Path(reference, "overview.md"), "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())

documentation/scripts/plotting_scripts/menard_beta_norm_plot.py

@@ -11,13 +11,13 @@
     y_range=(2, 8),
     width=400,
     height=400,
-    title="Menard Normalized Beta Limit",
+    title="Menard Normalised Beta Limit",
 )
 plot.xaxis.axis_label = r"Aspect ratio, \  $$[A]$$"
-plot.yaxis.axis_label = r"Normalized beta limit, \  $$[\beta_N]$$"
+plot.yaxis.axis_label = r"Normalised beta limit, \  $$[\beta_N]$$"
 
 plot.line("x", "y", source=source, line_width=3, line_alpha=0.6)
 
 # Save the plot as HTML
-output_file("menard_beta_norm.html", title="Menard Normalized Beta Limit")
+output_file("menard_beta_norm.html", title="Menard Normalised Beta Limit")
 save(plot)

documentation/scripts/plotting_scripts/original_beta_norm_plot.py

@@ -11,13 +11,13 @@
     y_range=(2, 15),
     width=400,
     height=400,
-    title="Original Normalized Beta Limit",
+    title="Original Normalised Beta Limit",
 )
 plot.xaxis.axis_label = r"Aspect ratio, \  $$[A]$$"
-plot.yaxis.axis_label = r"Normalized beta limit, \  $$[\beta_N]$$"
+plot.yaxis.axis_label = r"Normalised beta limit, \  $$[\beta_N]$$"
 
 plot.line("x", "y", source=source, line_width=3, line_alpha=0.6)
 
 # Save the plot as HTML
-output_file("original_beta_norm.html", title="Original Normalized Beta Limit")
+output_file("original_beta_norm.html", title="Original Normalised Beta Limit")
 save(plot)

documentation/scripts/plotting_scripts/profile_hastie_current.py

@@ -16,7 +16,7 @@
     height=400,
     title="PROCESS vs Hastie Current Profile",
 )
-plot.xaxis.axis_label = "Normalized Plasma Radius"
+plot.xaxis.axis_label = "Normalised Plasma Radius"
 plot.yaxis.axis_label = "Current Density, J"
 
 plot.line(

documentation/scripts/plotting_scripts/profile_parabolic_plot.py

@@ -15,7 +15,7 @@
     height=400,
     title="Parabolic Profile | L-mode",
 )
-plot.xaxis.axis_label = r"Normalized Radius, $$ \rho $$"
+plot.xaxis.axis_label = r"Normalised Radius, $$ \rho $$"
 plot.yaxis.axis_label = r"Density, $$n_e$$"
 
 plot.line("x", "y", source=source, line_width=3, line_alpha=0.6)

documentation/scripts/plotting_scripts/profile_pedestal_plot.py

@@ -29,7 +29,7 @@
     height=400,
     title="Pedestal Profile | H-mode",
 )
-plot.xaxis.axis_label = r"Normalized Radius, $$ \rho $$"
+plot.xaxis.axis_label = r"Normalised Radius, $$ \rho $$"
 plot.yaxis.axis_label = r"Density, $$n_e$$"
 
 plot.line("x", "y", source=source, line_width=3, line_alpha=0.6)

documentation/cost-models/cost-models.md → documentation/source/cost-models/cost-models.md

@@ -4,7 +4,7 @@ Two cost models are available, determined by the switch `cost_model`.
 
 ## 1990 cost model (`cost_model = 0`)
 
-This combines methods[^1] used in the TETRA code [^2] and the Generomak[^3] scheme. The costs are split into accounting categories[^4]. The best references for the algorithms used are[^5], and source file `costs.f90` in the code itself. The majority of the costed items have a unit cost associated with them. These values scale with (for example) power output, volume, component mass etc., and many are avaiable to be changed via the input file. All costs and their algorithms correspond to 1990 dollars.
+This combines methods[^1] used in the TETRA code [^2] and the Generomak[^3] scheme. The costs are split into accounting categories[^4]. The best references for the algorithms used are[^5], and source file `costs.f90` in the code itself. The majority of the costed items have a unit cost associated with them. These values scale with (for example) power output, volume, component mass etc., and many are available to be changed via the input file. All costs and their algorithms correspond to 1990 dollars.
 
 The unit costs of the components of the fusion power core are relevant to "first-of-a-kind" items. That is to say, the items are assumed to be relatively expensive to build as they are effectively prototypes and specialised tools and machines have perhaps been made specially to create them. However, if a "production line" has been set up, and R & D progress has allowed more experience to be gained in constructing the power core components, the cost will be reduced as a result. Variable `fkind` may be used to multiply the raw unit costs of the fusion power core items (by a factor less than one) to simulate this cost reduction for an *N<sup>th</sup>*-of-a-kind device. In other systems studies of fusion power plants[^6], values for this multiplier have ranged from 0.5 to 0.8.
 
@@ -14,7 +14,7 @@ The first wall, blanket, divertor, centrepost (if present) and current drive sys
 
 If the switch `ireactor = 0`, no cost of electricity calculation is performed. If `ireactor = 1`, then the cost of electricity is evaluated, with the value quoted in units of $/MWh.
 
-The net electric power is calculated in routine `POWER` It is possible that the net electric power can become negative due to a high recirculating power. Switch `ipnet` determines whether the net electric power is scaled to always reamin positive (`ipnet = 0`, or whether it is allowed to become negative (`ipnet = 1`), in which case no cost of electricity calculation is performed.
+The net electric power is calculated in routine `POWER` It is possible that the net electric power can become negative due to a high recirculating power. Switch `ipnet` determines whether the net electric power is scaled to always remain positive (`ipnet = 0`, or whether it is allowed to become negative (`ipnet = 1`), in which case no cost of electricity calculation is performed.
 
 ## 2015 Kovari model (`cost_model = 1`)
 

documentation/development/add-vars.md → documentation/source/development/add-vars.md

@@ -58,7 +58,7 @@ To add a `PROCESS` iteration variable please follow the steps below, in addition
 1. The parameter `ipnvars` in module `numerics` of `numerics.f90` will normally be greater than the actual number of iteration variables, and does not need to be changed.
 2. Append a new iteration number key to the end of the `ITERATION_VARIABLES` dictionary  in `iteration_variables.py`. The associated variable is the corresponding key value.
 3. Set the variable origin file and then the associated lower and upper bounds
-4. Update the `lablxc` derscription in `numerics.f90`.
+4. Update the `lablxc` description in `numerics.f90`.
 
 It should be noted that iteration variables must not be reset elsewhere in the
 code. That is, they may only be assigned new values when originally
@@ -110,7 +110,7 @@ After following the instruction to add an input variable, you can make the varia
 
 2. Add a short description of the new scanning variable in the `nsweep` comment in `scan_variables.py`, alongside its identification number.
 
-3. Update the `SCAN_VARIABLES` dictionary in the `scan.py` file by adding a new case statement connecting the variable to the scan integer switch, the variable name and a short description. 
+3. Update the `ScanVariables` enum in the `scan.py` file by adding a new case statement connecting the variable to the scan integer switch, the variable name and a short description.
 
 4. Add a comment in the corresponding variable file in the data_structure directory, eg, `data_structure/[XX]_variables.py`, to add the variable description indicating the scan switch number.
 
@@ -130,12 +130,12 @@ After following the instruction to add an input variable, you can make the varia
 `SCAN_VARIABLES` case example:
 
 ```python
-  SCAN_VARIABLES = {
-    1: ScanVariable("aspect", "Aspect_ratio"),
-    2: ScanVariable("pflux_div_heat_load_max_mw", "Div_heat_limit_(MW/m2)"),
+  class ScanVariables(Enum):
+    aspect: ScanVariable("aspect", "Aspect_ratio", 1),
+    pflux_div_heat_load_max_mw: ScanVariable("pflux_div_heat_load_max_mw", "Div_heat_limit_(MW/m2)", 2),
     ...
-    54: ScanVariable("Bc2(0K)", "GL_NbTi Bc2(0K)"),
-    55: ScanVariable("dr_shld_inboard", "Inboard neutronic shield"),
+    Bc2_0K: ScanVariable("Bc2(0K)", "GL_NbTi Bc2(0K)", 54),
+    dr_shld_inboard : ScanVariable("dr_shld_inboard", "Inboard neutronic shield", 55),
 ```
 
 ---------------
@@ -170,4 +170,4 @@ def my_constraint_function():
   value = ...
   error = ...
   return ConstraintResult(normalised_residual, value, error)
-```
+```

documentation/development/debugging.md → documentation/source/development/debugging.md

@@ -3,7 +3,7 @@
 Debugging allows you stop a program mid-execution (called 'breaking') and explore the current state (e.g. print the current value of variables or attributes). In Python, this is done using `pdb` which comes as-standard with Python. 
 
 First, you must decide where in the code you would like to break. When debugging, a useful way to 
-decide is to look at the terminal for where the error may have occured and break there. To insert a 
+decide is to look at the terminal for where the error may have occurred and break there. To insert a 
 breakpoint in the code, insert the following code where you want the code to break:
 
 ```python

documentation/development/standards.md → documentation/source/development/standards.md

@@ -8,7 +8,7 @@ You can check if your code meets the `ruff` standards by running:
 2. `pre-commit run --all-files`
 
 !!! Info "ruff automatic fixes"
-    Many problems that `ruff` can detect it can also safely fix. Simply run `ruff check --fix` and it will try and automatically fix the mistakes, rewritting your source code. 
+    Many problems that `ruff` can detect it can also safely fix. Simply run `ruff check --fix` and it will try and automatically fix the mistakes, rewriting your source code. 
 
 
 --------------------
@@ -601,7 +601,7 @@ ii
 | `b_t_onaxis`  | Toroidal field on-axis | T |
 | `b_t_max`     | Max toroidal field | T |
 | `nd_electron_vol` | Volume average electron density | m-3 |
-| `temp_electron_vol_eV` | Volume avgerage electron temperature | eV |
+| `temp_electron_vol_eV` | Volume average electron temperature | eV |
 | `m_steel` | Mass of steel | kg |
 | `m_steel_tonne` | Mass of steel | tonne |
 | `e_neutron_eV` | Energy of neutron | eV |

documentation/eng-models/blanket_overview.md → documentation/source/eng-models/blanket_overview.md

@@ -48,7 +48,7 @@ Using the Reynolds number we calculate the Darcy friction factor using the Haala
 
 For the radius of the pipe bend we assume it to be 3 times the radius of the coolant channel.
 
-The elbow coefficients for the 90 and 180 degree bends $\left(f_{\text{90,elbow}}, f_{\text{180,elbow}}\right)$ are clalculated via [`elbow_coeff()`](#pipe-bend-elbow-coefficient--elbow_coeff).
+The elbow coefficients for the 90 and 180 degree bends $\left(f_{\text{90,elbow}}, f_{\text{180,elbow}}\right)$ are calculated via [`elbow_coeff()`](#pipe-bend-elbow-coefficient--elbow_coeff).
 
 The pressure drop for the straights along the entire pipe length is the same as above:
 

documentation/eng-models/central-solenoid.md → documentation/source/eng-models/central-solenoid.md

@@ -80,7 +80,7 @@ $$
 
 where $\alpha = \frac{r_{\text{CS,outer}}}{r_{\text{CS,inner}}}$, is the ratio of the outer and inner radii of the solenoid and $\beta = \frac{z_{\text{CS,half}}}{r_{\text{CS,outer}}}$, is the ratio of the solenoid half height to its inboard radius.
 
-The peak field at the bore of the central solenoid will not be the same as that felt by the conductors inside the structures. We require to know the peak field on the conductor if we are to design a superconducting central solenoid that has enough margin. Fits to data[^1] for different ranges of $\beta$ have been calulated as follows:
+The peak field at the bore of the central solenoid will not be the same as that felt by the conductors inside the structures. We require to know the peak field on the conductor if we are to design a superconducting central solenoid that has enough margin. Fits to data[^1] for different ranges of $\beta$ have been calculated as follows:
 
 - $\beta > 3.0$
 

documentation/eng-models/divertor.md → documentation/source/eng-models/divertor.md

@@ -95,7 +95,7 @@ $$
 
     The main assumption of the Peng gaseous divertor model is that the power radiated to the divertor is equally radiated in the divertor box across all three surfaces. This may not truly be the case in reality.
 
-The interactive graph below can be used to investigate how changing the key prameters changes the divertor configuration. The grey box represents the first wall, the far right red line represents the right hand edge of the divertor region ($r_{\text{outer}}$), the far left red line represents the left hand edge of the divertor region ($r_{\text{inner}}$) and the blue line represents the bottom of the divertor region ($\Delta z_{\text{plasma,div}}$).
+The interactive graph below can be used to investigate how changing the key parameters changes the divertor configuration. The grey box represents the first wall, the far right red line represents the right hand edge of the divertor region ($r_{\text{outer}}$), the far left red line represents the left hand edge of the divertor region ($r_{\text{inner}}$) and the blue line represents the bottom of the divertor region ($\Delta z_{\text{plasma,div}}$).
 
 -------------
 

documentation/eng-models/fw-blanket.md → documentation/source/eng-models/fw-blanket.md

@@ -269,22 +269,22 @@ $$
 ### Model Switches
 
 There are three blanket model options, chosen by the user to match their selected blanket design using the switch 'i_blkt_dual_coolant' (default=0):
-    0.   Solid breeder - nuclear heating in the blanket is exctrated by the primary coolant.
+    0.   Solid breeder - nuclear heating in the blanket is extracted by the primary coolant.
     1.   Liquid metal breeder, single-coolant 
-        - nuclear heating in the blanket is exctrated by the primary coolant.
+        - nuclear heating in the blanket is extracted by the primary coolant.
         - liquid metal is circulated for tritium extraction, specified by number of circulations/day.
     2.   Liquid metal breeder, dual-coolant
         - nuclear heating in the liquid breeder/coolant is extracted by the liquid breeder/coolant.
         - nuclear heating in the blanket structure is extracted by the primary coolant
 
 The default assuption for all blanket models is that the first wall and breeding blanket have the same coolant (flow = FW inlet -> FW outlet -> BB inlet-> BB outlet). 
-It is possible to choose a different coolant for the FW and breeding blanket, in which case the mechanical pumping powers for the FW and BB are calculated seperately. 
+It is possible to choose a different coolant for the FW and breeding blanket, in which case the mechanical pumping powers for the FW and BB are calculated separately. 
 The model has three mechanical pumping power options, chosen by the user to match their selected blanket design using the switch 'i_fw_blkt_shared_coolant' (default=0): 
     0.   Same coolant for FW and BB ('i_fw_coolant_type`=`i_blkt_coolant_type`)
     1.   Different coolant for FW and BB ('i_fw_coolant_type`/=`i_blkt_coolant_type`) 
 
 !!! Note "Note" 
-    For the dual-coolant blanket the 'i_fw_blkt_shared_coolant' switch is relavent for the blanket structure coolant and not the liquid metal breeder/coolant choice.  
+    For the dual-coolant blanket the 'i_fw_blkt_shared_coolant' switch is relevant for the blanket structure coolant and not the liquid metal breeder/coolant choice.  
 
 The user can select the number poloidal and toroidal modules for the IB and OB BB. The 'i_blkt_module_segmentation' switch can be set to 1 for a single-module-segment blanket (default=0):
     0. Multi-module segment 

documentation/eng-models/heating_and_current_drive/NBI/nbi_overview.md → documentation/source/eng-models/heating_and_current_drive/NBI/nbi_overview.md

@@ -100,7 +100,7 @@ It is recommended that <b>only one</b> of these two constraint equations is used
 | $\mathtt{rnfe}$      | Iron density /$n_{\text{e}}$   |
 
 
-Both the [ITER](./iter_nb.md) and [Culham](culham_nb.md) NBI models both use the `sigbeam` method to calculate the stopping cross section[^1]. It finds a suitable analytic epressing for $\sigma_s^{(Z)}(E,n_{\text{e}},T_{\text{e}},Z_{\text{eff}})$ for fitting $\sigma_s$ data for a single impurity $(\text{Z)}$ plasma:
+Both the [ITER](./iter_nb.md) and [Culham](culham_nb.md) NBI models both use the `sigbeam` method to calculate the stopping cross section[^1]. It finds a suitable analytic expression for $\sigma_s^{(Z)}(E,n_{\text{e}},T_{\text{e}},Z_{\text{eff}})$ for fitting $\sigma_s$ data for a single impurity $(\text{Z)}$ plasma:
 
 
 

documentation/eng-models/heating_and_current_drive/RF/culham_lower_hybrid.md → documentation/source/eng-models/heating_and_current_drive/RF/culham_lower_hybrid.md

@@ -14,10 +14,10 @@ AEA FUS 172: Physics Assessment for the European Reactor Study[^1]
 5. Calculate the local toroidal magnetic field, `blocal`, using the formula `b_plasma_toroidal_on_axis * rmajor / (rmajor - rpenet)`. Here, `b_plasma_toroidal_on_axis` is the toroidal magnetic field at the magnetic axis, and `rmajor` is the major radius of the plasma.
 6. Calculate the parallel refractive index, `nplacc`, which is needed for plasma access. It uses the local density `dlocal` and the local magnetic field `blocal` to calculate a fraction `frac`. `nplacc` is then obtained by adding `frac` to the square root of `1.0 + frac * frac`.
 7. Calculate the local inverse aspect ratio, `epslh`, by dividing `rpenet` by `rmajor`.
-8. Calculate the LH normalized efficiency, `x`, using the formula `24.0 / (nplacc * sqrt(tlocal))`.
+8. Calculate the LH normalised efficiency, `x`, using the formula `24.0 / (nplacc * sqrt(tlocal))`.
 9. Calculate several intermediate terms, `term01`, `term02`, `term03`, and `term04`, using different formulas involving `nplacc`, `physics_variables.zeff`, `tlocal`, `epslh`, and `x`.
 10. Calculate the current drive efficiency, `gamlh`, using the formula `term01 * term02 * (1.0e0 - term03 / term04)`.
-11. Return the current drive efficiency normalized by the product of `0.1e0 * dlocal` and `physics_variables.rmajor`.
+11. Return the current drive efficiency normalised by the product of `0.1e0 * dlocal` and `physics_variables.rmajor`.
 
 [^1]: T. C. Hender, M. K. Bevir, M. Cox, R. J. Hastie, P. J. Knight, C. N. Lashmore-Davies, B. Lloyd, G. P. Maddison, A. W. Morris, M. R. O'Brien, M.F. Turner abd H. R. Wilson, *"Physics Assessment for the European Reactor Study"*, AEA Fusion Report AEA FUS 172 (1992)