:3260 update the fusion reactions section of the plasma docs to full …

…account for all models and details (#3345)

* refactor: Update Fusion Reactions navigation structure

* Fix some variable names for clairty

* Convert physics functions to Python

* Add new duterium_branching() function from Bosch-Hale to calculate the difference in D-D reactions

* Update electron mass constant to use the more accurate value

The commit updates the electron mass constant in multiple files to use the more accurate value provided by the NIST. This ensures that calculations involving the electron mass are more precise. Explicitly written float values has now also been set to this variable

* Update proton mass constant to use the more accurate value

The commit updates the proton mass constant in multiple files to use the more accurate value provided by the NIST. This ensures that calculations involving the electron mass are more precise. Variable name has been changed from pmass to PROTON_MASS

* Add new constants for the deuteron, triton, neutron, alpha particle and helion mass. Fix broken links for the electron and proton mass

* Revert variable names back to lowercase due to parsing issue with f2py

* Update electron mass constant to use the more accurate value. Add new variable for electron_volt
The commit updates the electron mass constant in multiple files to use the more accurate value provided by the NIST. This ensures that calculations involving the electron mass are more precise. Variable name has been changed from emass to electron_mass

* Add new constants for the speed of light, D-T reaction energy, D-3He reaction energy and both D-D reactions

* Refactor bosch_hale function to use more descriptive name and update function signature

* Add new constants for fusion reaction energy fractions

This commit adds new constants for the energy fractions carried by neutrons and protons in various fusion reactions. These constants are used to calculate the energy released in fusion reactions involving deuterium, tritium, helium-3, and protons. The energy fractions are calculated assuming a non-relativistic center of mass frame.

The following constants have been added:
- dt_neutron_energy_fraction: Energy fraction carried by neutron in deuterium-tritium reaction
- dd_neutron_energy_fraction: Energy fraction carried by neutron in deuterium-deuterium (helium-3 producing) reaction
- dd_proton_energy_fraction: Energy fraction carried by proton in deuterium-deuterium (triton producing) reaction
- dhelium_proton_energy_fraction: Energy fraction carried by proton in deuterium-helion (helium-3) reaction

These constants will be used in further calculations related to fusion reactions.

* Refactor fint() into fusion_rate_integral() to be more descriptive and make function more explicit

* Refactor variable name palppv to alpha_power_density for clarity and consistency

* Refactor variable name palppv to alpha_power_density for clarity and consistency

* Refactor variable name pneutpv to neutron_power_density for clarity and consistency

* Refactor variable names for fusion reactions in physics calculations

* Refactor variable names fusionrate to fusion_rate_density

* Refactor variable names for alpha particle production rate

- Renamed `alpharate` variable to `alpha_rate_density` for clarity and consistency.

* Refactor variable names for proton rate density in physics calculations

* Refactor variable name pdd to dd_power_density for clarity and consistency

* Refactor variable name pdtpv to dt_power_density for clarity and consistency

* Refactor variable names for helium-3 power density in physics calculations

* Refactor variable name sigvdt to sigmav_dt_average for clarity and consistency

* Refactor sum_fusion_rates() to be more explicit and pythonic

* Refactor set_physics_variables() to update global and module variables with fusion power densities and reaction rates

* Refactor the fusion reaction function. Docstring and type hints added with internal variables renamed for clarity

* Refactor the fusion reaction function. Docstring and type hints added with internal variables renamed for clarity

* Implement the new reaction energies and product  particle fractions from constants.f90

* Rename pdt to dt_power to be more explicit

* Rename pdhe3 to dhe3_power to be more descriptive

* Rename pdd to dd_power for more clarity

* Rename "vol" to "plasma_volume" in multiple files to improve code readability and maintain consistency with other variable names.

* Add type hints and expand docstring to palph2()

* Add new variable alpha_power_plasma that represents the alpha power produced just by reactions in the plasma. Has been added to output to show the breakdown of the total alpha power from the plasma and NBI contribution.

* Rename palpnb to alpha_power_beams for more clarity and consistency

* Rename "palpmw" to "alpha_power_total" for clarity and consistency

* Add new variable neutron_power_plasma that represents the neutron power produced just by reactions in the plasma. Has been added to output to show the breakdown of the total alpha power from the plasma and NBI contribution.

* Rename pneutmw to neutron_power_total for more clarity and consistency

* Add new variable to output called neutron_power_beams to show the breakdown of total fusion power

* Rename pchargemw to non_alpha_charged_power for clarity

* Add charged_particle_power as a new physics variable and add it to the output

* Rename powfmw to fusion_power for clarity

* Rename palpipv to alpha_power_ion_density for clarity

* Rename palpepv to alpha_power_electron_density for clarity

* Add alpha_power_electron_density and alpha_power_electron_density to output

* Add main bulk of FusionReaction class documentation descriptions

* Update BoschHale docs section

* Update variable name for charged particle power in stellarator.py and physics_variables.f90

* Remove ealphadt variable for the alpha particle energy in D-T reactions. New constant dt_alpha_energy is now called from the constants file in functions

* Update the variable name falpha to f_alpha_plasma for clarity and consistency

* Add new atomic mass unit and kilo electron volt constant. Rename palphabm() to alpha_power_beam(). Replace use of the proton mass instead of the amu unit

* Update atomic mass units for deuterium and tritium and change multiplied constant form proton mass to amu mass

* Add NBI beam fusion sections to new beam_reactions.md file. Rename xbrak() to beam_energy_to_ions(). Update beam energy to ions docs

* Update beam_reactions.md with NBI beam fusion sections and function name changes

* Rename sgvhot() to beam_reaction_rate()

* Rename _sigbmfus() to _beam_fusion_cross_section() and add to docs

* Refactor the _hot_beam_fusion_reaction_rate_integrand() function to improve readability and clarity. Update the function to use more descriptive variable names and add comments for better understanding.

* Refactor output.f90 format strings for improved spacing and readability

* Refactor palph2() to set_fusion_powers() and update naming of variables and test names

* Rename beamfus() to beam_fusion() and re-arrange beam fusion docs page

* Rename cnbeam to beam_current

* Rename enbeam to beam_energy

* Rename ftritbm to f_tritium_beam

* Rename beam_energy_to_ions() to _fast_ion_pressure_integral(). Add about derivations for beamcalc()

* Updated references to `dnbeam2` to `beam_density_out` in relevant files

* Rename betanb to beta_beam for consistency

* Beam reactions doc page structure refactor

* Rename falpe to f_alpha_electron and falpi to f_alpha_ion

* Refactor variable names for fuel ion fractions

* Remove the fast alpha beta contribution from set_fusion_powers() and put it into fast_alpha_beta(). neutron and alpha power densities are now split into separate plasma only and total variables.

* Add image showing the deuterium branching ratio and add discussion about plasma fuelling and add warning about reactions not covered

* Refactor bosch hale reactivity and replace electron with ion density

* Update the dt_power, alpha_rate_density, fusion_rate_density to now has distinct total and plasma only variants

* Add variables to obsolete variables dictionary and fix unit tests

* Add constraint equations to docs and tidy

* Revoke new outfile spacing and append fusion_power to pass integration tests

* pre-commit file fix

* Update Bosch-Hale documentation for clarity and consistency

* Revert deni to dene to prevent profile normalisation errors

* Add f_dd_branching_trit attribute and update fusion reaction calculations

---------

Co-authored-by: Timothy Nunn <[email protected]>

documentation/proc-pages/development/add-vars.md

@@ -247,15 +247,15 @@ Constraint equations are added to *PROCESS* in the following way:
       !! Logic change during pre-factoring: err, symbol, units will be assigned only if present.
       !! ffuspow : input real : f-value for maximum fusion power
       !! powfmax : input real : maximum fusion power (MW)
-      !! powfmw : input real : fusion power (MW)
+      !! fusion_power : input real : fusion power (MW)
       use constraint_variables, only: ffuspow, powfmax
-      use physics_variables, only: powfmw
+      use physics_variables, only: fusion_power
       implicit none
       type (constraint_args_type), intent(out) :: args
 
-      args%cc =  1.0D0 - ffuspow * powfmax/powfmw
+      args%cc =  1.0D0 - ffuspow * powfmax/fusion_power
       args%con = powfmax * (1.0D0 - args%cc)
-      args%err = powfmw * args%cc
+      args%err = fusion_power * args%cc
       args%symbol = '<'
       args%units = 'MW'
 

documentation/proc-pages/development/standards.md

@@ -259,7 +259,7 @@ real(kind(1.0D0)) :: alphan = 0.25D0
 real(kind(1.0D0)) :: alphap = 0.0D0
 !! Pressure profile index
 
-real(kind(1.0D0)) :: alpharate = 0.0D0
+real(kind(1.0D0)) :: alpha_rate_density = 0.0D0
 !! Alpha particle production rate (particles/m3/sec)
 ```
 
@@ -306,16 +306,16 @@ subroutine constraint_eqn_001(args)
   !! - \( T_i \) -- density weighted average ion temperature [keV]
   !! - \( B_{tot} \) -- total toroidal + poloidal field [T]
 
-  use physics_variables, only: betaft, betanb, dene, ten, dnitot, tin, btot, beta
-  use constants, only: echarge,rmu0
+  use physics_variables, only: betaft, beta_beam, dene, ten, dnitot, tin, btot, beta
+  use constants, only: electron_charge,rmu0
 
   implicit none
 
   type(constraint_args_type), intent(out) :: args
   !! constraint derived type
 
-    args%cc = 1.0D0 - (betaft + betanb + &
-      2.0D3*rmu0*echarge * (dene*ten + dnitot*tin)/btot**2 )/beta
+    args%cc = 1.0D0 - (betaft + beta_beam + &
+      2.0D3*rmu0*electron_charge * (dene*ten + dnitot*tin)/btot**2 )/beta
     args%con = beta * (1.0D0 - args%cc)
     args%err = beta * args%cc
     args%symbol = '='

documentation/proc-pages/eng-models/heating_and_current_drive/NBI/culham_nb.md

@@ -49,11 +49,11 @@ $$
 Deuterium and tritium beam densities
 
 $$
-\mathtt{dend} = n_{\text{ion}} \times (1-\mathtt{ftritbm})
+\mathtt{dend} = n_{\text{ion}} \times (1-\mathtt{f_tritium_beam})
 $$
 
 $$
-\mathtt{dent} = n_{\text{ion}} \times \mathtt{ftritbm}
+\mathtt{dent} = n_{\text{ion}} \times \mathtt{f_tritium_beam}
 $$
 
 Power split to the ions and electrons is clauclated with the $\mathtt{cfnbi()}$ method found [here](../NBI/nbi_overview.md/#ion-coupled-power-cfnbi) and outputs $\mathtt{fpion}$
@@ -72,7 +72,7 @@ plus correction terms outlined in Culham Report AEA FUS 172.
 |  $\mathtt{aspect}$, $A$      |   aspect ratio                            |
 |  $\mathtt{dene}$, $n_{\text{e}}$     |    volume averaged electron density $(\text{m}^{-3})$                           |
 |  $\mathtt{dnla}$, $n_{\text{e,0}}$      |    line averaged electron density $(\text{m}^{-3})$                           |
-|  $\mathtt{enbeam}$      |  neutral beam energy $(\text{keV})$                             |
+|  $\mathtt{beam_energy}$      |  neutral beam energy $(\text{keV})$                             |
 |  $\mathtt{frbeam}$      |   R_tangent / R_major for neutral beam injection                            |
 |  $\mathtt{fshine}$      |  shine-through fraction of beam                             |
 |  $\mathtt{rmajor}$, $R$      |  plasma major radius $(\text{m})$                              |
@@ -114,7 +114,7 @@ $$
 Beam energy in MeV
 
 $$
-\mathtt{ebmev} = \frac{\mathtt{enbeam}}{10^3}
+\mathtt{ebmev} = \frac{\mathtt{beam_energy}}{10^3}
 $$
 
 x and y coefficients of function J0(x,y) (IPDG89)

documentation/proc-pages/eng-models/heating_and_current_drive/NBI/iter_nb.md

@@ -39,11 +39,11 @@ $$
 
 Deuterium and tritium beam densities:
 $$
-n_D = n_i * (1.0 - \mathtt{ftritbm}) 
+n_D = n_i * (1.0 - \mathtt{f_tritium_beam}) 
 $$
 
 $$
-n_T = n_i * \mathtt{ftritbm}
+n_T = n_i * \mathtt{f_tritium_beam}
 $$
 
 Power split to ions / electrons is calculated via the the `cfnbi` method described [here](nbi_overview.md)

documentation/proc-pages/eng-models/heating_and_current_drive/RF/ec_overview.md

@@ -33,7 +33,7 @@ The answer ECGAM is the normalised efficiency $n_{\text{e}}IR/P$ with $n_{\text{
 
 
 $$
-\mathtt{mcsq} = 9.1095\times10^{-31} \frac{c^2}{1  \text{keV}}
+\mathtt{mcsq} = m_{\text{e}} \frac{c^2}{1  \text{keV}}
 $$
 
 $$

documentation/proc-pages/eng-models/power-conversion-and-heat-dissipation-systems.md

@@ -11,7 +11,7 @@ turbines. Figure 1 shows the power flow.
 
 ## Divertor
 
-All of the charged particle transport power leaving the plasma (excluding the `1-falpha` portion of 
+All of the charged particle transport power leaving the plasma (excluding the `1-f_alpha_plasma` portion of 
 the alpha power that escapes directly to the first wall) is assumed to be absorbed in the divertor, 
 along with a proportion `fdiv` of the radiation power and the neutron power.
 

documentation/proc-pages/physics-models/error.txt

@@ -207,7 +207,7 @@ deuterium-tritium reaction:
 \]
 
 20\% of the energy produced is given to the alpha particles (\(^4\)He),
-a fraction of which remain (c.f. \texttt{falpha}) within the plasma and
+a fraction of which remain (c.f. \texttt{f_alpha_plasma}) within the plasma and
 thermalise (slow down) due to collisions, thus heating the plasma. The
 remaining 80\% is carried away by the neutrons, which deposit their
 energy within the blanket and shield.
@@ -254,17 +254,17 @@ integrated over the plasma profiles (correctly, with or without
 pedestals).
 
 The fractional composition of the `fuel' ions (D, T and \(^3\)He) is
-controlled using the three variables \texttt{fdeut}, \texttt{ftrit} and
-\texttt{fhe3}, respectively:
+controlled using the three variables \texttt{f_deuterium}, \texttt{f_tritium} and
+\texttt{f_helium3}, respectively:
 
 \[\begin{aligned}
 n_{\mbox{fuel}}  & = n_D + n_T + n_{\mathrm{^{3}He}}  \;\;\; \mbox{particles/m$^3$} \\
-n_D  & = \mathtt{fdeut} \, n_{\mbox{fuel}} \\
-n_T  & = \mathtt{ftrit} \, n_{\mbox{fuel}} \\
-n_{\mathrm{^{3}He}} & = \mathtt{fhe3} \, n_{\mbox{fuel}}
+n_D  & = \mathtt{f_deuterium} \, n_{\mbox{fuel}} \\
+n_T  & = \mathtt{f_tritium} \, n_{\mbox{fuel}} \\
+n_{\mathrm{^{3}He}} & = \mathtt{f_helium3} \, n_{\mbox{fuel}}
 \end{aligned}\]
 
-PROCESS checks that \(fdeut + ftrit + fhe3 = 1.0\), and stops with an
+PROCESS checks that \(f_deuterium + f_tritium + f_helium3 = 1.0\), and stops with an
 error message otherwise.
 
 \subsection{Plasma Profiles}\label{plasma-profiles}
@@ -499,8 +499,8 @@ model. The available impurities are as follows:
 As stated above, the number density fractions for hydrogen (all
 isotopes) and helium need not be set, as they are calculated by the code
 to ensure that plasma quasi-neutrality is maintained, and taking into
-account the fuel ratios \texttt{fdeut}, \texttt{ftrit} and
-\texttt{fhe3}, and the alpha particle fraction \texttt{ralpne} which may
+account the fuel ratios \texttt{f_deuterium}, \texttt{f_tritium} and
+\texttt{f_helium3}, and the alpha particle fraction \texttt{ralpne} which may
 be input by the user.
 
 The impurity fraction of one of the elements listed in array
@@ -994,18 +994,18 @@ is derived directly from the energy confinement scaling law.
 \texttt{iradloss\ =\ 0} -- Total power lost is scaling power plus
 radiation
 
-\texttt{pscaling\ +\ pradpv\ =\ falpha*palppv\ +\ pchargepv\ +\ pohmpv\ +\ pinjmw/vol}
+\texttt{pscaling\ +\ pradpv\ =\ f_alpha_plasma*alpha_power_density\ +\ charged_power_density\ +\ pohmpv\ +\ pinjmw/plasma_volume}
 
 \texttt{iradloss\ =\ 1} -- Total power lost is scaling power plus core
 radiation only
 
-\texttt{pscaling\ +\ pcoreradpv\ =\ falpha*palppv\ +\ pchargepv\ +\ pohmpv\ +\ pinjmw/vol}
+\texttt{pscaling\ +\ pcoreradpv\ =\ f_alpha_plasma*alpha_power_density\ +\ charged_power_density\ +\ pohmpv\ +\ pinjmw/plasma_volume}
 
 \texttt{iradloss\ =\ 2} -- Total power lost is scaling power only, with
 no additional allowance for radiation. This is not recommended for power
 plant models.
 
-\texttt{pscaling\ =\ falpha*palppv\ +\ pchargepv\ +\ pohmpv\ +\ pinjmw/vol}
+\texttt{pscaling\ =\ f_alpha_plasma*alpha_power_density\ +\ charged_power_density\ +\ pohmpv\ +\ pinjmw/plasma_volume}
 
 \subsection{Plasma Core Power Balance}\label{plasma-core-power-balance}
 
@@ -1027,7 +1027,7 @@ The primary sources of power are the fusion reactions themselves, ohmic
 power due to resistive heating within the plasma, and any auxiliary
 power provided for heating and current drive. The power carried by the
 fusion-generated neutrons is lost from the plasma, but is deposited in
-the surrounding material. A fraction \texttt{falpha} of the alpha
+the surrounding material. A fraction \texttt{f_alpha_plasma} of the alpha
 particle power is assumed to stay within the plasma core to contribute
 to the plasma power balance. The sum of this core alpha power, any power
 carried by non-alpha charged particles, the ohmic power and any injected