Add canonical orbit frequency APIs#489
Merged
Merged
Conversation
krystophny
added
tier/T3
An orbit that reaches the outer radial boundary during compute_canonical_frequencies ended with SYMPLECTIC_STEP_BOUNDARY, which the status mapping lumped into FREQ_INTEGRATOR_ERROR. A particle leaving the plasma edge is a physical loss, so it now reports FREQ_ORBIT_LOST like the outside-domain stop; only genuinely numerical failures remain integrator errors. This is what a default 3.5 MeV alpha does on the circular-tokamak benchmark chart map, where the intended case is a 5 keV deuteron. pysimple.init() now also accepts namelist-cased parameter names such as facE_al, matching simple.in, and python/README.md documents the species/energy overrides needed for non-alpha frequency calculations.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Risk tier
Correctness contract
Intended behavior change
Add a side-effect-free Fortran API and a Python API that compute canonical bounce/transit and mean toroidal angular frequencies for trapped and passing guiding-centre orbits. Support one or multiple completed poloidal cycles, return cycle spreads and explicit status metadata, and expose interpolated tip/toroidal cut tracing through Python.
Behavior that must not change
Existing orbit tracing, classification, NetCDF output, and golden-record results are unchanged. The core frequency routine copies the caller's tracer and does no file I/O.
Coordinate / unit conventions
The source-level Fortran routine accepts SIMPLE integration coordinates. The flat/Python boundary accepts
[s, theta, phi, v/v0, lambda]in public reference coordinates and performsref_to_integ. Angles and displacements are radians, periods are seconds, and frequencies are angular frequencies in rad/s.omega_bis positive;omega_phiis signed.Numerical invariants
Trapped periods use successive negative-to-positive parallel-velocity crossings. Passing periods use successive signed
2*piadvances of unwrapped poloidal angle. Event time and toroidal displacement are interpolated within the crossing step. Multi-cycle results report means and sample standard deviations.Tests added
Golden-record impact
Failure modes considered
Invalid options, orbit loss, integrator errors, and maximum-step exhaustion return distinct statuses. Unknown orbit class remains explicit. The cut wrapper rejects unsupported cut types and non-symplectic integration.
Manual validation
Validated trapped and passing VMEC seeds through the native API; validated the Python frequency and cut interfaces against the compiled f90wrap backend.
Verification
make test TEST=^test_orbit_frequencies$ CONFIG=Fast VERBOSE=0make test TEST=^test_simple_api$ CONFIG=Fast VERBOSE=0(24 API cases pass)test_orbit_macrofailure is pre-existing: it accessespysimple._backend, which currentmaindoes not export.git diff --check