The PR #196 review surfaced an obvious contradiction between two docstrings (map_forcing_to_eigenmodes vs ForcingMode), which has been reconciled in-PR. But a deeper question is unresolved: across the PerturbedEquilibrium pipeline, do the docstrings, code comments, and Fortran NetCDF unit attributes (e.g. Phi_x="Wb", Phi_xe="T") actually agree with the SI units produced by the literal calculation at each step?
We should do an end-to-end dimensional audit by tracing each quantity from raw SI inputs (B in T, lengths in m, currents in A) and checking what the operations actually multiply together — not by trusting any annotation along the way.
Scope, at minimum:
ForcingMode.amplitude and the full coil → Biot-Savart → project_normal_flux! → fourier_decompose_bn chain- ASCII / HDF5 forcing file conventions and
convert_forcing_normalization! (normal_field_T, sfl_flux_Wb → unit-norm)
Phi_x vs Phi_xe (and the ftop energy-norm transformation between them)Phi_res / resonant_flux, delta_prime, island_half_width, Chirikov- Permeability and inductance matrices (
Lambda, L, P, reluctance)
- PE energies (
plasma_energy, vacuum_energy, total_energy)
For each quantity, confirm SI units from the calculation and either correct the documented unit or correct the calculation as appropriate. Suggested deliverable: a unit-convention table in docs/src/perturbed_equilibrium.md that is authoritative for the codebase.
Context: discussed during the review of PR #196.
The PR #196 review surfaced an obvious contradiction between two docstrings (
map_forcing_to_eigenmodesvsForcingMode), which has been reconciled in-PR. But a deeper question is unresolved: across the PerturbedEquilibrium pipeline, do the docstrings, code comments, and Fortran NetCDF unit attributes (e.g.Phi_x="Wb",Phi_xe="T") actually agree with the SI units produced by the literal calculation at each step?We should do an end-to-end dimensional audit by tracing each quantity from raw SI inputs (B in T, lengths in m, currents in A) and checking what the operations actually multiply together — not by trusting any annotation along the way.
Scope, at minimum:
ForcingMode.amplitudeand the full coil → Biot-Savart →project_normal_flux!→fourier_decompose_bnchainconvert_forcing_normalization!(normal_field_T,sfl_flux_Wb→ unit-norm)Phi_xvsPhi_xe(and theftopenergy-norm transformation between them)Phi_res/ resonant_flux,delta_prime,island_half_width,ChirikovLambda,L,P, reluctance)plasma_energy,vacuum_energy,total_energy)For each quantity, confirm SI units from the calculation and either correct the documented unit or correct the calculation as appropriate. Suggested deliverable: a unit-convention table in
docs/src/perturbed_equilibrium.mdthat is authoritative for the codebase.Context: discussed during the review of PR #196.