🚧 3260 update the fusion reactions section of the plasma docs to full account for all models and details

[chris-ashe]

This pull request includes multiple changes across various documentation files and source code to improve the clarity and accuracy of the fusion reaction models and related constants. The most important changes include renaming variables for consistency, adding detailed documentation for fusion reaction methods, and updating references to reflect these changes.

Documentation Enhancements:

• documentation/proc-pages/physics-models/fusion_reactions/beam_reactions.md: Added detailed sections on NBI Fusion, including derivations and equations for beam fusion cross-section, reaction rates, and power.
• documentation/proc-pages/physics-models/fusion_reactions/plasma_reactions.md: Added detailed documentation for fusion reactions, including initialization, calculation methods, and attributes.
• documentation/proc-pages/physics-models/fusion_reactions/plasma_bosch_hale.md: Added new documentation for Bosch-Hale methods and constants used in fusion reaction calculations.

Navigation and Organization:

• mkdocs.yml: Updated the navigation structure to include a more detailed breakdown of fusion reactions, separating the overview and Bosch-Hale methods.

Bugs 🐛

• The value for the mass of deuterium (ATOMIC_MASS_DEUTERIUM) and tritium (ATOMIC_MASS_TRITIUM) in atomic mass units was in correctly given and then multiplied by the mass of the proton instead of the atomic mass unit value in physics_functions.py.

• One of the term values in beam_energy_to_ions() used an approximate value which is now calculated directly

• The _hot_beam_fusion_reaction_rate_integrand() was using proton mass instead of atomic mass unit

New features

The fusion energies and reaction product energy branching ratios have been enhanced with more precise variables and are calculated implicitly

Code cleanup and test updates ♻️ :

• Many functions and classes now have expanded docstrings and type hints. Along with renaming internal variables to be explicitly descriptive.
• OUT.DAT and variable name widths have been widened to allow for more variable name space and labels

Namespace changes

Constants

• Several constants in constants.f90 have been made more verbose. Sadly they have not been able to be put into all uppercase form to be more Pythonic (PEP8).This is due to a parsing problem with f2py. The values have also been made more precise by taking values from NIST (https://physics.nist.gov/cuu/Constants/index.html). Comments are now also above the constants with link references to their values.
  Some changes below are:

  • Name: emass -> electron_mass; Value: 9.10938370D-31 -> 9.1093837139D-31. This new value has been applied to explicitly written floats in cfnbi() and eccdef(). This has been updated in the docs also
  • Name: pmass -> proton_mass; Value: 1.6726231D-27 -> 1.67262192595D-27.
  • Name: echarge -> electron_charge; Value 1.60217733D-19 -> 1.602176634D-19.

New additions:

• deuteron_mass, triton_mass, neutron_mass, alpha_mass, helion_mass. speed_light

• electron_volt: This new value has been applied to explicitly written floats in eccdef(), acc2272(). This has been updated in the docs also. This has been added to be more syntactically correct when working with energy units instead of just calling

• kiloelectron_volt: This has been added as a lot of conversions would previously multiply by 1000.0 across the code. This should increase readability.

• atomic_mass_unit: Lots of functions are calling different fundamental mass values that are close but not technically correct, this is added to correct these errors.

• electron_charge

• d_t_energy, d_helium_energy, dd_helium_energy, dd_triton_energy. These are the reaction energy constants and are calculated implicitly from the mass differences of products and reactants

• dt_alpha_energy. This is created to compliment the removal of ealphadt from the variables list

• dt_neutron_energy_fraction, dd_neutron_energy_fraction, dd_proton_energy_fraction, dhelium_proton_energy_fraction. These are the calculated fractions my mass difference of the shared reaction energy between the fusion products.

• alpha_power_plasma: This is a new output file variable to differentiate between the alpha power from the plasma and that from beams.

• neutron_power_plasma: This is a new output file variable to differentiate between the neutron power from the plasma and that from beams.

• neutron_power_beams: This is a new output file variable to differentiate between the neutron power from the plasma and that from beams.

Functions

Re-named to be more descriptive about what the function does

• bosch_hale() -> bosch_hale_reactivity()
• fint() -> fusion_rate_integral()
• dt() -> dt_reaction()
• dhe3() -> dhe3_reaction()
• dd1() -> dd_helion_reaction()
• dd2() -> dd_triton_reaction()
• palphabm() -> alpha_power_plasma()
• xbrak() -> beam_energy_to_ions()
• sgvhot() -> beam_reaction_rate()
• _sigbmfus() -> _beam_fusion_cross_section()
• palph2() -> set_fusion_powers()
• beamfus() -> beam_fusion()`

Variables

A handful of variables are not quite descriptive/explicit enough in their naming and tend to lead to misinterpretation if it presents a per unit volume or a total value. Thus the following internal variables have been changed:

• palppv -> alpha_power_density

• pchargepv ->charged_power_density

• pneutpv -> neutron_power_density

• fusionrate -> fusion_rate_density

• alpharate -> alpha_rate_density

• protonrate -> proton_rate_density

• pddpv -> dd_power_density

• pdtpv -> dt_power_density

• pdhepv -> dhe3_power_density

• sigvdt -> sigmav_dt_average

• pdt -> dt_power

• pdhe3 -> dhe3_power

• pdd -> dd_power

• palpnb -> alpha_power_beams

• palpmw -> alpha_power_total

• pneutmw -> neutron_power_total

• pchargemw -> non_alpha_charged_power. This was a misleading name as it doesn't account for alphas so was re-named

• pfuscmw -> charged_particle_power: This is a new output file variable which is now added to physics_variables.f90 It was output by palph2() but was never written to output. It now is.

• palpipv -> alpha_power_ion_density`. This variable has now also been added to the output

• palpepv -> alpha_power_electron_density`. This variable has now also been added to the output

• cnbeam -> beam_current

• enbeam -> beam_energy

• ftritbm -> f_tritium_beam

• vol -> plasma_volume. This was changed due to conflicting understanding depending on the context of the module and to make it easier to search and find.

• powfmw -> fusion_power

• falpha -> f_alpha_plasma. Docs section created showing origin of default value.

Removals

• ealphadt. Removed as it was a constants value, though down as an input variable. Replaced by dt_alpha_energy constant.

Checklist

I confirm that I have completed the following checks:

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

[codecov-commenter]

Codecov Report

Attention: Patch coverage is 49.00000% with 153 lines in your changes missing coverage. Please review.

Project coverage is 27.01%. Comparing base (032399f) to head (3efd055).
Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
process/physics_functions.py	61.11%	84 Missing ⚠️
process/physics.py	23.33%	46 Missing ⚠️
process/stellarator.py	7.14%	13 Missing ⚠️
process/io/plot_proc.py	0.00%	4 Missing ⚠️
process/current_drive.py	0.00%	3 Missing ⚠️
process/plasma_geometry.py	0.00%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3345      +/-   ##
==========================================
+ Coverage   26.65%   27.01%   +0.36%     
==========================================
  Files          76       76              
  Lines       17610    17812     +202     
==========================================
+ Hits         4694     4812     +118     
- Misses      12916    13000      +84     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.