⏲️ Update confinement time docs

[chris-ashe]

Description

A new file called confinement_time.py has been created to store all of the confinement time scalings as seperate functions instead of being privately stored in the pcond() function.

⚠️ The manual inputting of the confinement time has now been moved to i_confinement_time == 0

Namespace changes

Functions

• pcond() -> calculate_confinement_time()
• igmarcal -> output_confinement_comparison(): Plotting the confinement time scaling comparison table is now a callable function that shows all scalings.
• fhfac() -> find_other_h_factors(): The function fhz() has now been placed inside as an internal function as it is only called by find_other_h_factors().

---

Variables

kappaa_IPB -> kappa_ipb
taup -> t_alpha_confinement
tauei -> t_ion_energy_confinement
tauee -> t_electron_energy_confinement
t_alpha_confinement/taueff -> f_alpha_energy_confinement
taueff -> t_energy_confinement
taulimit -> f_alpha_energy_confinement_min
dntau -> ntau

• 🔥 iinvqd: Removed as source cannot be found
• 🔥 kappaa: Removed as variable is no longer used due to not checking legacy docs
• ipnlaws -> n_confinement_scalings
• tauscl -> labels_confinement_scalings
• total_energy_conf_tim -> t_energy_confinement_beta : This variable describes the confinement time calculated intrinsically from the total thermal energy and the chosen loss power.
• ptripv -> `pden_ion_transport_loss_mw
• ptrepv -> pden_electron_transport_loss_mw
• ftaulimit -> falpha_energy_confinement
• ptrimw -> p_ion_transport_loss_mw
• ptremw -> p_electron_transport_loss_mw
• powerht -> p_plasma_loss_mw
• isc -> i_confinement_scaling

---

✨ New additions

• f_alpha_energy_confinement: Created as a new variable instead of being calculated as a fraction in outplas(). Is now calculated and set in the phyaux() function

• nTtau: New variable to properly represent the Lawson triple product as a calculated variable in phyaux() function.

New expanded scaling output that now shows all scalings:

---

🧪 Tests

• A new test_confinement_time.py file has been created in tests/unit to test all of the scaling for the case where all the scaling inputs are equal to one. This should catch if any of the scaling exponents or variable definitions are changed

---

🐛 Bugs

• kappaa_IPB was being called as kappaa_ipb
• The Murari scaling was using the old IPB98 definition of $\kappa$ instead of the updated definition from the paper corrections. This caused some changes to the regression tests as follows:

expected_ptrepv=0.081359821043062386, -> expected_ptrepv=0.08399287091443618,
expected_ptripv=0.072209244483967094,  -> expected_ptripv=0.07454615402313478,
expected_tauee=3.2718670722507683, ->  expected_tauee=3.169298972363837,
expected_tauei=3.2718670722507683,  -> expected_tauei=3.169298972363837,
expected_taueff=3.2718670722507692,  -> expected_taueff=3.169298972363837,

• Same bug as above for the Petty scaling

expected_ptrepv=0.081513009259203975, -> expected_ptrepv=0.0831039731066564,
expected_ptripv=0.072345203550858064, -> expected_ptripv=0.07375723096135396,
expected_tauee=3.2657182196344126, -> expected_tauee=3.203198469625145,
expected_tauei=3.2657182196344126, -> expected_tauei=3.203198469625145,
expected_taueff=3.2657182196344126, -> expected_taueff=3.203198469625145,

• Same bug as above for the Petty08 component of the Menard NSTX-Petty08 hybrid

expected_ptrepv=0.070108167457759038, -> expected_ptrepv=0.07147653259174333
expected_ptripv=0.062223069561580698, -> expected_ptripv=0.06343753403847416
expected_tauee=3.7969687288631331, -> expected_tauee=3.7242785823911264
expected_tauei=3.7969687288631331, -> expected_tauei=3.7242785823911264
expected_taueff=3.7969687288631335, ->  expected_taueff=3.7242785823911264

• Coefficiecnt value for the ITER93-H scaling form ELM-free had the wrong coefficient of 0.053 when the literature says 0.036

• Calculating the ion and electron ransport losses has raw constants floats instead of using constants.f90. This caused the calculate_confinement_time() tests to fail. Though only by a difference at the 5th decimal place

Old

ptripv = 2.403e-22 * nd_ions_total * tin / t_ion_confinement
ptrepv = 2.403e-22 * dene * ten / t_electron_confinement

New

ptripv = (
            (3 / 2)
            * (constants.electron_charge / 1e3)
            * nd_ions_total
            * tin
            / t_ion_confinement
        )
        ptrepv = (
            (3 / 2)
            * (constants.electron_charge / 1e3)
            * dene
            * ten
            / t_electron_confinement
        )

---

• A loose calculation for the confinement time can be found at the top of calculate_confinement_time() beofre applying any of the scalings and is of the form:

eps2 = eps / 2.0e0
        str5 = 2.0e0 / (1.0e0 + (kappa**2))
        ck2 = (0.66e0 + (1.88e0 * (np.sqrt(eps2))) - (1.54e0 * eps2)) * (
            1.0e0 + (1.5e0 * (eps2**2))
        )
        chii = (
            (6.5e-22)
            * ck2
            * zeff
            * (aspect**1.5e0)
            * dene
            * (q**2)
            * str5
            / ((np.sqrt(tin)) * (bt**2))
        )
        str2 = 2.0e0 * (kappa**2) / (1.0e0 + (kappa**2))
        t_ion_energy_confinement = 0.375e0 * rminor**2 / chii * str2

However at the bottom of the file it is simpky re-written as equal to the electron confinement time such as:

  # Ion energy confinement time
        # N.B. Overwrites earlier calculation above
        t_ion_energy_confinement = t_electron_energy_confinement

This has been in the code from the old GitLab version and the Git blame can always see this there. It has therefore been removed.

Checklist

I confirm that I have completed the following checks:

• My changes follow the PROCESS style guide
• 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

❌ Patch coverage is 66.11842% with 103 lines in your changes missing coverage. Please review.
✅ Project coverage is 31.20%. Comparing base (c8f147c) to head (9788212).
⚠️ Report is 491 commits behind head on main.

Files with missing lines	Patch %	Lines
process/physics.py	48.08%	95 Missing ⚠️
process/power.py	0.00%	3 Missing ⚠️
process/stellarator.py	0.00%	3 Missing ⚠️
process/confinement_time.py	99.11%	1 Missing ⚠️
process/init.py	50.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3493      +/-   ##
==========================================
+ Coverage   30.84%   31.20%   +0.36%     
==========================================
  Files          80       81       +1     
  Lines       19327    19440     +113     
==========================================
+ Hits         5961     6066     +105     
- Misses      13366    13374       +8     

☔ View full report in Codecov by Sentry.
📢 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.

[chris-ashe]

@j-a-foster Dont forget to add the doc page

[j-a-foster]

Some minor comments, otherwise happy with the docs.

[j-a-foster]

Caveat that not all scalings listed contain all of these parameters e.g. epsilon

[j-a-foster]

The exponent in the 1+e in the denominator could be substituted for e.g. X and then underneath, define X = -9.403(n/Bt)^-1.365, just to tidy up the formula a bit. Not absolutely needed, will leave up to you to decide.

[timothy-nunn]

Happy with code changes, thanks for writing tests for each one. Please fix the conflicts.

[timothy-nunn]

The old variables do not appear to have been added to obsolete variables

[j-a-foster]

Happy with the docs - okay to be merged.