diff --git a/README.md b/README.md index 808e15a7..5da67298 100644 --- a/README.md +++ b/README.md @@ -303,6 +303,546 @@ command if it is missing. | [`simple_examples`](examples/simple_examples) | Coils from near-axis or BOOZ_XFORM, perturbed coils, combined fields, MGRID | | [`paper`](examples/paper) | Integrator, gradient and Poincare figures | +## Native forward orbit solvers + +`Tracing(..., integrator="essos_rk45")` selects Dormand–Prince 5(4); +`integrator="essos_dopri8"` selects Prince–Dormand 8(7). The existing +`GuidingCenter`/`FullOrbit` models select fixed steps; their `Adaptative` +variants select adaptive steps. The default remains Diffrax. Native defaults +are I control and `rtol=atol=1e-9`; PI is available with +`native_controller="pi"`, `native_pcoeff=.4`, `native_icoeff=.3`. + +All native stepping, GPU execution and private field adapters live in +[`essos/rk.py`](essos/rk.py). + +Native VMEC CUDA tracing automatically uses one warp per particle for spectra +padded to at most 128 modes, and four for larger spectra. The shared stage loop +evaluates the initial derivative once and retains it after a rejected trial, +avoiding a second compiled RHS body. These are the standard native CUDA defaults +for the existing field adapters and Dopri5/8 methods. + +Both native methods share the same stepping driver, FSAL reuse, standard +dense output, bounded retries and root-found stopping events. Their standard +interpolants match the corresponding Diffrax methods. Saves do not constrain +adaptive steps. Solver results include accepted/rejected counts and explicit +failure statuses; `solve_rk(..., record_steps=True)` retains accepted times for diagnostics. + +The physical embedded error is the maximum of the position and velocity +block errors, divided by their reference length/birth speed and by +`atol+rtol`. VMEC position errors are measured in Cartesian coordinates; +Boozer uses flux-radius, toroidal-radian and birth-speed blocks. These are +local normalized estimates, **not global trajectory-error guarantees**. +`native_error_control="standard"` selects the usual componentwise RMS budget. + +`essos.rk.prepare_solver(..., execution="cuda")` exposes the +independent GPU loops for fixed-field Biot–Savart GC/Lorentz and VMEC GC; +it returns a scalar solver for `jax.jit(jax.vmap(solve))`. Cartesian states +are `(x,y,z,vpar)` or `(x,y,z,vx,vy,vz)`; VMEC uses ESSOS's existing +five-component axis-regular chart. This low-level path uses zero electric +field, standard dense output and I control, and stops VMEC orbits at the LCFS. +`execution="jax"` uses the portable path. `Tracing` uses the portable driver +and retains its existing electric-field, stopping and exterior-continuation +interfaces. The generic `essos.rk.solve_rk` also accepts an arbitrary array RHS. + +For Boozer, use `trace_boozer(..., integrator="essos_dopri8", +native_execution="cuda")`. Its CUDA adapter supports fixed cosine Fourier +fields with K=0; the portable path also supports sine spectra, angle tables +and PI. GPU arrays are private solver views of the original field data; +the public field classes are unchanged. This addition is forward-only: +split collisions and accepted-step reverse AD belong to separate changes. + +### Forward comparison + +64 particles, RTX 5060 Laptop GPU, JAX 0.11.2, eight saves, three interleaved +blocked warm samples. VMEC/Boozer rows were rerun on 2026-10-26 with the shared +VMEC defaults; coil rows retain their 2026-10-24 measurements. Native and Diffrax +use Dopri8 and the same physical/chart embedded error and I coefficients; +controller details and rounding can change adaptive counts. Fixed pairs use +identical timesteps. Native CUDA includes the private field adapters; Diffrax +uses public field evaluation. Gains describe the complete forward implementation. +Coils use the unscaled QA coils at 4 keV, 20 us for GC and 2 us for Lorentz; +VMEC/Boozer use reactor-scale QA at 4 keV and 20 us. Compare backends within rows. + +| Field / model | Stepping | Native / Diffrax warm ms | Native / Diffrax buffers MiB | Measured | +|---|---|---:|---:|---| +| boozer / gc | adaptive | 1.659 / 3.769 | 0.026 / 0.151 | 2026-10-26 | +| boozer / gc | fixed | 18.201 / 50.142 | 0.026 / 0.154 | 2026-10-26 | +| coils / gc | adaptive | 84.426 / 160.362 | 0.026 / 5.980 | 2026-10-24 | +| coils / gc | fixed | 419.872 / 676.766 | 0.026 / 5.970 | 2026-10-24 | +| coils / lorentz | adaptive | 29.429 / 70.426 | 0.070 / 0.731 | 2026-10-24 | +| coils / lorentz | fixed | 782.063 / 1891.586 | 0.070 / 0.721 | 2026-10-24 | +| vmec / gc | adaptive | 4.836 / 7.171 | 0.066 / 0.965 | 2026-10-26 | +| vmec / gc | fixed | 88.169 / 161.807 | 0.066 / 0.965 | 2026-10-26 | + +Buffers are compiler estimates of arguments + outputs + temporaries minus aliases, +excluding resident field data/executable constants; they are not peak VRAM. +Position errors are Cartesian metres for coils/VMEC and flux-chart units for +Boozer; velocity errors include both absolute and birth-speed-normalized values +against a tighter Diffrax reference. The measured gains include the private +field adapters and describe the complete forward implementation. + +Generate all eight comparison workloads and their files on a CUDA machine: + +```sh +python -m examples.benchmarks.benchmark_native_orbits --suite \ + --execution cuda --output output/native_forward +``` + +Choose a fresh output folder. The script creates per-workload `comparison.json` +and `comparison.csv`, plus aggregate `forward.csv` and `forward.md`. Generated +results are kept under `output/` and are not versioned. Three blocked warm +samples alternate backend order after startup; setup, compilation and the tighter +reference are excluded. Compilation may use a persistent cache and is not +reported as a cold measurement. Reports include inputs, source hashes, step +counts, failures, error metrics and compiler buffers. + +Defaults reproduce the table's 64 particles, 4 keV, seed 42, eight saves, +rtol=atol=1e-9 and 20 us GC workloads. Fixed VMEC/Boozer use 160 steps, coil GC +224, and coil Lorentz 1792 over 2 us. For one workload, omit `--suite` and select +`--field vmec`, `--field boozer` or `--field coils --model gc/lorentz`, with +`--stepping adaptive/fixed`. A matching Boozer transform can be supplied with +`--field-cache`; otherwise the optional `essos[booz]` dependency computes it. + +### QA Boozer alpha workload + +Previously recorded full workload: 8192 alphas, 3.52 MeV, birth s=0.3, +seed 42, 20 ms, 101 saves, 16 direct Fourier modes. The preceding profiling +run identified an A100/JAX 0.7.2; the full console logs identify a CUDA device. +Compilation and warm execution are separated. This is a CATAPULT-sized +workload, not a new measurement against CATAPULT. + +| Method | Control | Compile s | Warm s | Accepted / rejected | Lost / failed | +|---|---|---:|---:|---:|---:| +| Native Dopri5 | I, rtol=atol=1e-10 | 4.247 | 21.554 | 895113025 / 63143676 | 110 / 0 | +| Native Dopri8 | I, rtol=atol=1e-10 | 5.069 | 18.448 | 351025279 / 62226975 | 111 / 0 | +| Native Dopri8 | I, rtol=atol=1e-8 | 4.985 | 9.223 | 189259503 / 7909253 | 106 / 0 | +| Existing RK4 | Fixed dt=1.25e-7 s | 2.728 | 20.244 | 1310720000 grid slots / 0 | 108 / 0 | + +These full-workload measurements predate the current extraction and have not +been rerun after the VMEC and initialization updates. RK4 checks loss at endpoints; +native adaptive methods refine the LCFS crossing. The differing loss counts are +not an accuracy proof. Regenerate the workload with the script below when ready. + +Run on the machine's normal JAX backend (the alpha example selects CUDA +execution automatically when available): + +```sh +python -m examples.benchmarks.benchmark_native_boozer_alpha \ + --integrator essos_dopri8 --particles 8192 --horizon .02 \ + --rtol 1e-10 --atol 1e-10 --output output/native_boozer_alpha +``` + +The example saves its Boozer transform, births, trajectories, statistics, +timings and a diagnostic plot. Reuse its `boozer_inputs.npz` with +`--field-cache`; select `essos_rk45` or `rk4` for the corresponding baseline. + +## Native split orbit and collisions + +`essos.split.trace_split` advances a native Dopri8 orbit, then applies the +nonrelativistic collision map. Defaults are the moment predictor +(`moment_tolerance=0.005`), native collision tolerance `0.001`, and separate +orbit `rtol`/`atol`. These local controls do not bound global statistical error. +`execution="independent"` selects the specialized GPU loop with the same +predictor and retained Brownian rejection memory; `"shared"` uses shared JAX. + +GC includes perpendicular spatial diffusion with three Wiener components +independent of speed/pitch noise. VMEC uses its existing Cartesian geometry; +Boozer additionally requires geometric Fourier tables from the same transform: + +```python +from essos.split import trace_split, BoozerGeometry +result = trace_split(field, particles, species, tmax=tmax, timestep=dt, + spatial_geometry=BoozerGeometry.from_booz_xform(booz)) +``` + +The solver applies Cartesian spatial kicks and inverts the regular coordinate +map, retaining its nonlinear drift. Missing geometry or failed inversion raises +or reports failure. Lorentz uses its three-component velocity collision map. +Public field classes are unchanged. + +### Timings and compilation + +```sh +python -m examples.benchmarks.benchmark_split_orbits \ + --field coils --model gc --case native_independent --stepping adaptive \ + --particles 64 --repeats 3 --output output/native_split_gc_gpu +``` + +Select `--model lorentz`, `--stepping fixed` or `--case native_shared` for the +other native cases. Reports separate compilation, synchronized warm execution, +orbit/collision counts, compiler buffers and allocator peaks. The legacy Diffrax +GC baseline omits spatial diffusion; use the explicitly labelled diagnostic +`--no-spatial-diffusion` for that comparison. + +Observed lowering plus compilation for the corrected adaptive 64-particle +adapter checks (local GPU, 2026-10-28): + +| Field / model | Shared JAX, s | Independent GPU, s | +|---|---:|---:| +| Biot–Savart / GC | 12.93 | 63.51 | +| Biot–Savart / Lorentz | 8.49 | 81.50 | +| VMEC / GC | 9.49 | 369.99 | +| Boozer / GC | 12.23 | 209.41 | + +Both paths use the GPU: 5 keV protons, moment budget .01, collision tolerance +.001, orbit `rtol=atol=1e-9`, .4 ns horizon, GC spatial diffusion enabled. +All four shared/GPU adapter pairs passed agreement and repeatability checks. +Caching was allowed; these are single startup observations, not cold averages +or independent QA physics validation. The [compilation report](examples/benchmarks/results/native_split_20261025/compilation_20261027.md) +retains the separate cold measurements and `--cold-compile` reproduction. + +### Physical benchmarks + +The following figures use 2,000 particles, hot non-Maxwellian births and a +1 keV proton bath without a source. Black curves are independent references; +shading shows sampling uncertainty, not particle variance or timestep error. +The [benchmark guide](examples/benchmarks/results/native_split_20261025/README.md) +documents the physical models, reference refinements, controller comparisons +and unresolved discrepancies. Generated reports stay in ignored `output/`; +only these PNGs are retained with their reproduction scripts. + +Thermalization checks speed/pitch moments and distributions. First passage +checks the first crossing from `5 T` to `<=2 T`, with boundary resolution +controlled separately from collision accuracy: + +```sh +python -m examples.benchmarks.validate_beam_relaxation \ + --particles 2000 --batch-size 2000 --coefficient-model impact \ + --methods conservative --settings fine --output output/thermalization.json +python -m examples.benchmarks.validate_production_tolerance \ + --particles 2000 --batch-size 2000 --output output/first_passage.json +``` + +![GC thermalization: means and standard deviations](docs/readme_split_thermalization.png) +![Lorentz thermalization: means and standard deviations](docs/readme_split_thermalization_lorentz.png) +![Speed and pitch distributions](docs/readme_split_distributions.png) +![First-passage distribution](docs/readme_split_first_stopping_distribution.png) + +Presentation figures use bold labels, 320-dpi PNGs and vector PDF exports. +Evolution panels show means above standard deviations, with 95% sampling bands. +Histograms show counts with the independent black theory drawn on top; dashed +blue lines mark the birth speed and pitch. First stopping shows only the +histogram and black reference for the tight adaptive run. Figure files can be +regenerated from saved reports with the scripts' --plot-only option. + +Uniform-field spatial and velocity statistics use moment budget .01, collision +tolerance .001 and orbit `rtol=atol=1e-10`. GC uses explicit spatial kicks; +Lorentz includes finite gyromotion. The GC chart curves overlap because they +express the same prescribed field, not distinct MHD equilibria. + +```sh +python -m examples.benchmarks.benchmark_split_coordinate_physics \ + --study diffusion --models gc lorentz --charts cartesian --particles 2000 \ + --tolerance .01 --save-points 201 --output output/uniform +python -m examples.benchmarks.benchmark_split_coordinate_physics \ + --study diffusion --models gc lorentz --charts cartesian --particles 2000 \ + --tolerance .01 --seed 8706 --output output/uniform_seed8706 +``` + +The earlier six-save run with seed 7706 found spatial spreading within sampling intervals, but +speed-variance gaps `+9.19 +/- 7.23%` (GC) and `-11.32 +/- 5.46%` (Lorentz) +remain recorded. The independent seed 8706 gives `-1.00 +/- 6.30%` and +`-2.50 +/- 6.14%`; it does not make the original population pass. + +![Uniform field, GC](docs/readme_split_coordinate_diffusion.png) +![Uniform field, Lorentz](docs/readme_split_coordinate_diffusion_lorentz.png) + +The refreshed primary uniform/helix figures retain 2,000 particles and budget +.01, with 201 actual saved times instead of six; no particle-curve smoothing +is used. A changed save grid can change the realized Brownian paths. +The earlier [independent-seed uniform comparison](docs/readme_split_coordinate_diffusion_seed8706.png) +remains a separate sampling diagnostic. Velocities use the thermal scale +sigma_T = sqrt(T/m) and time uses t*nu0. + +Mirror and helix cases test coupled orbit/collision moments at budget .01. +VMEC/Boozer labels below denote manufactured coordinate charts of prescribed +fields; real equilibrium adapter checks are separate. GC axial references omit +perpendicular spatial kicks and represent the strong-magnetization limit. +Lorentz uses independent full-Lorentz numerical references with orbit/collision +refinement checks; speed retains independent radial theory. Grey and blue +bands show separate reference and production sampling intervals. + +```sh +python -m examples.benchmarks.benchmark_split_coordinate_physics \ + --study coupled --fields helix --models gc lorentz --charts cartesian \ + --particles 2000 --tolerance .01 --save-points 201 \ + --output output/coupled_moments +``` + +This generates both references. To reuse a full-Lorentz reference, generate it +with `python -m examples.benchmarks.lorentz_collision_reference --particles 2000 +--steps 400 --phase .1 --output output/lorentz_reference.json` and pass +`--lorentz-reference output/lorentz_reference.json` to the coupled command. +Mean position/pitch agree within combined sampling intervals in the corrected +Lorentz comparison, but some early helix variance/covariance gaps still exceed +pointwise intervals. These figures do not establish 1% accuracy for all moments. + +![GC mirror moments](docs/readme_split_coordinate_mirror_moments.png) +![GC helix moments](docs/readme_split_coordinate_helix_moments.png) +![Lorentz mirror moments](docs/readme_split_coordinate_mirror_lorentz_moments.png) +![Lorentz helix moments](docs/readme_split_coordinate_helix_lorentz_moments.png) + +Fixed/adaptive multirate convergence and paired Brownian refinement remain +available separately. The latter compares budgets .01/.005 on 64 common paths +for the axial GC model without perpendicular kicks: + +```sh +python -m examples.benchmarks.benchmark_split_multirate \ + --particles 2000 --models gc lorentz --output output/multirate +python -m examples.benchmarks.benchmark_split_path_convergence \ + --control moments --particles 64 --tolerances .01 .005 \ + --refinements 8 16 32 --max-steps 2000 --max-roots 4096 \ + --output output/paired_convergence +``` + +![GC spatial diffusion convergence](docs/readme_split_multirate_gc.png) +![Lorentz spatial diffusion convergence](docs/readme_split_multirate.png) +![Paired numerical convergence](docs/readme_split_moment_numerical_convergence.png) + +## Accepted-map native reverse AD + +This branch builds on `feat/native_split_collisions`. Reverse AD is opt-in: +`solve_rk(..., adjoint="accepted")` handles Dopri5/Dopri8 orbits, and +`trace_split(..., adjoint="accepted")` handles the full orbit/collision map. +The implementation is consolidated in [essos/native_ad.py](essos/native_ad.py). + +The forward solver selects accepted intervals and retains its Wiener increments. +Reverse freezes those intervals, random increments, rejection decisions and +event fractions. It differentiates RK stages, dense saves, collision +coefficients, pitch deflection, speed diffusion and GC spatial kicks. +Coordinate kicks use the derivative of the converged Cartesian inverse; +Newton iteration decisions are excluded. This does not differentiate the +motion of a first-hit time or the adaptive mesh. + +| Field / model | Independent GPU forward with AD recording | Reverse execution | +|---|---|---| +| Direct Biot–Savart / GC | Includes the moment predictor and spatial kicks | Persistent GPU for uniform alpha cases; otherwise checkpointed JAX | +| Direct Biot–Savart / Lorentz | Includes the moment predictor and velocity collisions | Persistent GPU for uniform alpha cases; otherwise checkpointed JAX | +| VMEC / GC | Includes coordinate spatial kicks | Checkpointed JAX on the selected device | +| Boozer / GC | Requires `spatial_geometry=BoozerGeometry.from_booz_xform(transform)` | Checkpointed JAX on the selected device | + +Set `execution="independent"` for the GPU forward loop and +`reverse_execution="auto"` to select the available reverse implementation. +`"shared"` explicitly selects JAX reverse; `"independent"` requires the +specialized direct-coil reverse. Field classes and their storage are unchanged. +The coordinate benchmark differentiates birth controls with a fixed equilibrium; +it does not regenerate VMEC/Boozer equilibria from boundary coefficients. + +One-particle GPU kernel audits (float64, RTX 5060 Laptop, JAX 0.11.2) give the +following directional derivatives. Both columns use the same accepted times +and Wiener increments. Coil audits perturb pitch, energy and one coil DOF; +coordinate audits perturb pitch, energy and birth radius. + +| Case | Reverse | Frozen-path JVP | +|---|---:|---:| +| Direct coils / GC, fixed | 0.0395485633371120 | 0.0395485633371120 | +| Direct coils / Lorentz, fixed | -0.205256475887027 | -0.205256475887028 | +| QA VMEC / GC, adaptive | 0.458124210711454 | 0.458124210711437 | +| Manufactured Boozer spectrum/geometry / GC, adaptive | 0.459437117932997 | 0.459437117932998 | + +These are two-interval derivative fixtures, not physical ensemble studies or +long-horizon performance measurements. Reproduce them with the benchmark's +`--kernel-audit` option, for example: + +```sh +python -m examples.benchmarks.benchmark_native_ad --kernel-audit \ + --field coils --model gc --stepping fixed --output output/native_ad/audit_gc.json +``` + +Use `--model lorentz` for the second row, or `--field vmec`/`--field boozer` +with `--model gc --stepping adaptive` for the coordinate rows. Coordinate cold +compilation is substantially heavier than these tiny execution workloads; +these GPU audits are outside the fast CI suite. + +Checkpoint segments default to 16 accepted orbit steps. Set +`adjoint_orbit_checkpoint_steps` to trade live replay workspace for stored +checkpoints. `adjoint_max_accepted_steps` and `adjoint_max_orbit_steps` bound +outer intervals and total accepted inner steps separately. Insufficient +capacity raises an error during reverse; it never returns a truncated gradient. +There is no particle chunking. + +The benchmark below checks reverse directional derivatives against JVPs through +an independent replay of the same accepted schedule and Wiener increments. +Its diagnostic scalar exercises position and velocity sensitivities; it is +not an optimization objective. Ordinary finite differences that rerun adaptation +measure a different map. + +```sh +python -m examples.benchmarks.benchmark_native_ad \ + --field coils --model gc --stepping adaptive --particles 64 \ + --output output/native_ad/coils_gc_adaptive.json +``` + +Repeat with `--model lorentz`, `--field vmec`, or `--field boozer` (GC), and +`--stepping fixed` for fixed orbit/collision intervals. The default honors the +selected JAX backend; it chooses the independent forward loop on GPU and shared +execution on CPU. Boozer setup requires the optional `booz_xform_jax` package. +Coil runs differentiate coil Fourier/current parameters and three birth +controls; coordinate runs differentiate the three birth controls. + +Each case records compilation, first execution, blocked warm medians, compiled +buffer sizes, allocator counters, accepted steps and gradient agreement. Run +each case in a fresh process for allocator peaks. AD is measured first; the +later forward counters are cumulative. Repeat with `--forward-only` in another +process for an isolated forward peak. `--cold-compile` disables the persistent +compilation cache. Complete value-and-gradient +time includes forward recording and reverse replay; it is distinct from a +reverse-only time. Compilation/setup are excluded from warm timings. Reports +are generated under ignored `output/`; generated JSON/CSV/SVG/profile files +are not retained in this branch. The physics figures above remain reproducible +with their existing scripts. + +Fast AD regressions run with `pytest tests/test_native_ad.py`. Large physical +ensembles and timing benchmarks are separate from CI. + +The recovered coil-optimization examples retain final-radius/classifier +objectives, length/curvature/B·n penalties, axis-field targets, fixed births, +toroidal targets, safety stops and PNG trajectory plots. GC and full-orbit +reference parameters remain editable inside their entry scripts: + +```sh +python -m examples.coil_optimization.optimize_coils_particle_confinement_guidingcenter_native --help +python -m examples.coil_optimization.optimize_coils_particle_confinement_fullorbit_native --help +``` + +Use `--collisions` for the full accepted split adjoint. Collisionless examples +use `Tracing(..., native_adjoint="accepted")`. Array loss-fraction, loss-location +and heat objectives are retained in `essos/particle_losses.py`; their jax_9/10 +provenance and units are documented there. Runtime optimization reports and +plots are written under ignored `output/`. + +### QI coil ALM examples recovered from the JAX branches + +Three GC examples recover the classic `en/jax_13` setups (commit `638916d`), +also compared with `jax_9`, `jax_10` and `jax_12`. The original QI coils +and matching surface are retained in `examples/input_files/`: the coil JSON +is required physical input, rather than a generated benchmark report. +VMEC supplies the fixed classifier and birth geometry; particles follow +the direct Biot--Savart coil field. Only coil Fourier/current DOFs vary. + +```sh +python -m examples.coil_optimization.optimize_coils_native_gc_alm_loss_fraction +python -m examples.coil_optimization.optimize_coils_native_gc_alm_distance +python -m examples.coil_optimization.optimize_coils_native_gc_alm_heat_flux +``` + +Each entry has an editable `PARAMETERS` dictionary; shared defaults are in +`examples/coil_optimization/native_gc_alm.py`, and CLI flags override them. +Defaults retain 20 fixed-seed 3.52 MeV alphas born at 70% of the local +axis-to-boundary distance, 5.7 T mean field on the original magnetic axis, +1e-4 s horizon, ten saves, 45 m length and 1/m curvature upper limits. +The loaded file contains five independent coils; limits apply to all five. +All three cases default to collisional GC tracing with a uniform +electron/deuterium bath. Both orbit and collision steps are adaptive, using +native Dopri8 with collision tolerance `0.001`, moment-predictor tolerance +`0.01` (`--moment-tolerance`) and orbit `rtol=atol=1e-7`. +`--no-collisions` selects collisionless native GC. +No example selects a JAX backend or chunks particles. +Current DOFs are normalized after the 5.7 T rescaling; `--max-change` bounds +dimensionless changes in the public coil DOFs, including the currents. +With `--execution auto` (default), collisional examples select the specialized +native forward/reverse kernels on GPU and shared JAX on CPU. Use +`--execution shared` to select the portable implementation explicitly. +Uniform multispecies rates are summed before stepping. The ALM outer GPU JIT +disables CUDA command-buffer capture for the guarded persistent reverse; +computation remains on the selected GPU. + +Native preparation evaluates the same coil Fourier series and its derivatives +with basis contractions, retaining the public DOFs, scaling and symmetries. +The length/curvature constraints use these derivatives; B.n/|B| uses the native +direct-coil field evaluator at the original surface points. Values and gradients +are checked against the existing formulas. Public field/coil classes are unchanged. +The one-particle, two-step GPU smoke with twenty physical coils, two background +species and the real classifier passes both recorded forward/reverse and the +heat-flux ALM initialization. Its solver directional derivative is +`8.350803831323357e-7`, versus frozen accepted-step JVP `8.350803831323323e-7`. + +The fixed classifier uses direct cell indexing on regular grids and the same +eight-corner trilinear interpolation for stopping and all three particle losses. +Nonuniform grids retain a bounded cell search. This native adapter preserves +the original table, periodic angle, outside fill and position derivatives; +it does not change the surface or the sigmoid loss. Its value and gradient +are checked against the original interpolator, including the periodic seam. + +The particle metric is an ALM equality constraint targeting zero, alongside +the axis-field equality and coil upper bounds. Distance reproduces the classic +per-save escape-centroid distance to the infinite boundary tangent line at +theta=3*pi/2, phi=pi; it is not a first-hit distance to a curved boundary line. +Heat reproduces the first-loss-weighted, birth-normalized `E_total*v_perp` +proxy, not a surface power density. The heat case also enables the historical +smooth B.n/|B| constraint; `--bdotn-weight 0` disables it. + +The current ESSOS ALM uses bounded Optimistix L-BFGS internally, replacing the +older JAXopt wrapper and perturbation weighting. Native Dopri8 uses adaptive +I control and checkpointed accepted-map reverse for every particle constraint. +The axis constraint now uses the same fixed QI axis as the initial current +normalization, rather than the old circle inferred from coil centre radii. +The experimental historical custom VJPs that held trajectories fixed are not +used. A separate safety surface 0.2 m outside the soft classifier stops escapes; +`--safety-margin` adjusts it without moving the soft confinement target. + +For a short run, append `--maxiter 10 --inner-maxiter 10`. `--evaluate-only` +performs the initial ALM value/gradient without optimizer updates. Initialization +and the full inner L-BFGS update are separate JIT programs: the first update has +its own cold compilation. The script announces each inner solve before starting; +the next cost/checkpoint appears after that complete outer update. Each fresh +output directory receives `history.csv`, `summary.json`, optimized coil input, +trajectory/DOF arrays and a PNG comparing up to ten initial/final trajectories +and coils with their R-Z projections. These outputs are ignored by Git. +With plots enabled, all three examples also save coil overlays, saved-time loss +fractions, heat-proxy histograms and matched initial/final loss-location maps in +`comparison_plots/`, using the already saved trajectories. +Iteration zero and every completed outer ALM iteration also write +`iterations/000000.npz`, `000001.npz`, etc., containing public `coil_dofs`, +optimizer `parameters` and the iteration number matching `history.csv`. +`initial_coils.json` preserves the coil definition and scaling for reconstruction: + +```python +import numpy as np +from essos.coils import Coils +with np.load("output/native_gc_alm_heat_flux/iterations/000005.npz") as data: + coils = Coils.from_json("output/native_gc_alm_heat_flux/initial_coils.json").with_dofs(data["coil_dofs"]) +``` + +These per-iteration checkpoints save coil DOFs only, with no extra particle +solves. Particle trajectories remain saved for the initial and final configurations. + +Reproduce coil overlays, saved-time loss fractions, and lost-particle heat-proxy +maps from a completed or downloaded run without tracing again: + +```sh +python -m examples.coil_optimization.plot_native_gc_alm /path/to/run1 /path/to/run2 +``` + +The PNGs are written under each run's `comparison_plots/`. The original QI +equilibrium is resolved from the saved settings or bundled inputs; `--wout` +selects its local copy. Losses use the first saved point outside the unshifted +classifier, so their positions and times are limited by the save spacing. +Colours show `E_total*v_perp` in W m, a heat proxy rather than heat flux per unit +area. These counts are distinct from the differentiable classifier loss score. + +All three ALM scripts accept `--optimizer scipy`. This retains the existing +constraint definitions, multiplier updates, scaled coil DOFs and native split +AD, while running inner L-BFGS-B and its line search on the host. One compiled +native value/gradient executable is reused across evaluations and outer updates; +the full inner optimizer is not traced into XLA. Compilation and first execution +are timed separately, with inner progress and solver termination messages. +The native value/gradient itself can still have substantial compilation cost. +SciPy enforces the same scaled `[-1, 1]` box directly (Optimistix uses a tanh +parameterization); its inner `gtol` is `--omega-tol`, and `--scipy-ftol` defaults +to `1e-12`. These are different inner optimizers, so iteration paths can differ. +The 500-particle A100 compilation reduction has not yet been measured. +Diagnostic retracing now also uses dynamic JIT coil inputs. Logged and retraced +particle costs are printed together and stored under `cost_retrace` in the run +summary; they must be checked before interpreting small optimization gains. + +```sh +python -m examples.coil_optimization.optimize_coils_native_gc_alm_loss_fraction \ + --optimizer scipy --particles 20 --horizon 1e-4 \ + --collision-tolerance 0.001 --moment-tolerance 0.01 \ + --maxiter 10 --inner-maxiter 10 --output output/qi_loss_scipy +``` + ## Testing ```sh diff --git a/docs/readme_split_coordinate_diffusion.png b/docs/readme_split_coordinate_diffusion.png new file mode 100644 index 00000000..99f10703 Binary files /dev/null and b/docs/readme_split_coordinate_diffusion.png differ diff --git a/docs/readme_split_coordinate_diffusion_lorentz.png b/docs/readme_split_coordinate_diffusion_lorentz.png new file mode 100644 index 00000000..891919b6 Binary files /dev/null and b/docs/readme_split_coordinate_diffusion_lorentz.png differ diff --git a/docs/readme_split_coordinate_diffusion_seed8706.png b/docs/readme_split_coordinate_diffusion_seed8706.png new file mode 100644 index 00000000..3f11b036 Binary files /dev/null and b/docs/readme_split_coordinate_diffusion_seed8706.png differ diff --git a/docs/readme_split_coordinate_helix_lorentz_moments.png b/docs/readme_split_coordinate_helix_lorentz_moments.png new file mode 100644 index 00000000..6498ae3f Binary files /dev/null and b/docs/readme_split_coordinate_helix_lorentz_moments.png differ diff --git a/docs/readme_split_coordinate_helix_moments.png b/docs/readme_split_coordinate_helix_moments.png new file mode 100644 index 00000000..fde5f618 Binary files /dev/null and b/docs/readme_split_coordinate_helix_moments.png differ diff --git a/docs/readme_split_coordinate_mirror_lorentz_moments.png b/docs/readme_split_coordinate_mirror_lorentz_moments.png new file mode 100644 index 00000000..1e29484d Binary files /dev/null and b/docs/readme_split_coordinate_mirror_lorentz_moments.png differ diff --git a/docs/readme_split_coordinate_mirror_moments.png b/docs/readme_split_coordinate_mirror_moments.png new file mode 100644 index 00000000..801c9415 Binary files /dev/null and b/docs/readme_split_coordinate_mirror_moments.png differ diff --git a/docs/readme_split_distributions.png b/docs/readme_split_distributions.png new file mode 100644 index 00000000..1af008d9 Binary files /dev/null and b/docs/readme_split_distributions.png differ diff --git a/docs/readme_split_first_stopping_distribution.png b/docs/readme_split_first_stopping_distribution.png new file mode 100644 index 00000000..f2380aa8 Binary files /dev/null and b/docs/readme_split_first_stopping_distribution.png differ diff --git a/docs/readme_split_first_stopping_moments.png b/docs/readme_split_first_stopping_moments.png new file mode 100644 index 00000000..22f2b154 Binary files /dev/null and b/docs/readme_split_first_stopping_moments.png differ diff --git a/docs/readme_split_moment_numerical_convergence.png b/docs/readme_split_moment_numerical_convergence.png new file mode 100644 index 00000000..0a54cfbf Binary files /dev/null and b/docs/readme_split_moment_numerical_convergence.png differ diff --git a/docs/readme_split_multirate.png b/docs/readme_split_multirate.png new file mode 100644 index 00000000..d6f64790 Binary files /dev/null and b/docs/readme_split_multirate.png differ diff --git a/docs/readme_split_multirate_gc.png b/docs/readme_split_multirate_gc.png new file mode 100644 index 00000000..ced92eae Binary files /dev/null and b/docs/readme_split_multirate_gc.png differ diff --git a/docs/readme_split_thermalization.png b/docs/readme_split_thermalization.png new file mode 100644 index 00000000..f2c98d8e Binary files /dev/null and b/docs/readme_split_thermalization.png differ diff --git a/docs/readme_split_thermalization_lorentz.png b/docs/readme_split_thermalization_lorentz.png new file mode 100644 index 00000000..e38ff4ce Binary files /dev/null and b/docs/readme_split_thermalization_lorentz.png differ diff --git a/essos/background_species.py b/essos/background_species.py index 4ccb831d..a95683c7 100644 --- a/essos/background_species.py +++ b/essos/background_species.py @@ -5,7 +5,7 @@ # to use higher precision config.update("jax_enable_x64", True) from jax import jit -from essos.constants import ELEMENTARY_CHARGE, EPSILON_0, PROTON_MASS, SPEED_OF_LIGHT +from essos.constants import ELEMENTARY_CHARGE, EPSILON_0, PROTON_MASS, SPEED_OF_LIGHT, HBAR @@ -21,8 +21,23 @@ class BackgroundSpecies(): first coordinate of the traced points (``s`` for a VMEC field), shape ``(number_species, len(radial_grid))``. Profiles are interpolated linearly and held constant beyond the ends of the grid. + + ``coulomb_log_model="nrl"`` preserves the original pairwise NRL formulas. + ``"impact"`` selects smooth Landau--Spitzer cutoffs at the RMS relative + speed, with static Debye screening (see :func:`impact_coulomb_logarithm`). Screening + uses these background species unless ``screening_species`` supplies a + separate BackgroundSpecies, e.g. electrons which screen without adding + electron collisions. No screening electron population is inferred for + the impact model. Both tracers and both time solvers use this selection. """ - def __init__(self, number_species, mass_array, charge_array, n_array, T_array, radial_grid=None): + def __init__(self, number_species, mass_array, charge_array, n_array, T_array, radial_grid=None, + *, coulomb_log_model="nrl", screening_species=None): + if coulomb_log_model not in ("nrl", "impact"): + raise ValueError("coulomb_log_model must be 'nrl' or 'impact'") + if screening_species is not None and coulomb_log_model != "impact": + raise ValueError("screening_species is only used by the impact Coulomb-log model") + self.coulomb_log_model = coulomb_log_model + self.screening_species = screening_species self.number_species = number_species self.species_indeces = jnp.arange(number_species) self.temperature = T_array @@ -61,7 +76,8 @@ def gamma_ab(ma: float, ea: float, species_b: int,v: float, points, species: Bac def dlog_coulomb_dv(ma, ea, species_b, v, points, species): """d(ln lnLambda)/dv: the Coulomb logarithm depends on the test-particle speed.""" ln, slope = jax.jvp(lambda u: coulomb_logarithm(ma, ea, species_b, u, points, species), (v,), (jnp.ones_like(v),)) - return slope/ln + # The impact model returns zero in a vacuum, where all rates vanish. + return slope/jnp.where(ln == 0, 1., ln) @partial(jit, static_argnames=['species']) @@ -115,8 +131,72 @@ def nu_s_ab(ma: float, ea: float,species_b: int,v:float, points,species: Backgro gamma_ab(ma,ea, species_b, v, points,species)* nb * (ma+mb)/Tb * chandrasekhar(v / vtb) /v )*(ma/(ma+mb)) + +# Smooth Landau-Spitzer GMS-1 (ls_min_interp) impact cutoffs. +# RMS relative speed squared v**2+3*T_b/m_b approximates a Maxwellian average. +# Screening uses the supplied species; dynamic screening is excluded. +# Temperatures are in eV; masses, charges, densities and speeds use SI. +# https://docs.plasmapy.org/en/stable/api/plasmapy.formulary.collisions.coulomb.Coulomb_logarithm.html + +def debye_inverse_squared(density, temperature, charge): + """Sum n_s q_s**2/(epsilon_0 T_s) over explicitly supplied screeners. + + Absent species contribute zero, including an absent species with T=0. + Invalid occupied temperatures or negative densities propagate NaN. + """ + density, temperature, charge = map(jnp.asarray, (density, temperature, charge)) + active = (density != 0) & (charge != 0) + energy = jnp.where(active, temperature, 1.)*ELEMENTARY_CHARGE + terms = jnp.where(active, density*charge**2/(EPSILON_0*energy), 0.) + valid = (density >= 0) & (~active | (temperature > 0)) + return jnp.sum(jnp.where(valid, terms, jnp.nan)) + + +def impact_parameters(mass_a, charge_a, mass_b, charge_b, speed, temperature_b, + screening_length): + """Return (b_min, b_max), using reduced mass and smooth quantum crossover. + + ``screening_length`` is specified independently of test-particle speed. + The charge product is |q_a q_b|, including unlike charge magnitudes. + """ + reduced_mass = mass_a*(mass_b/(mass_a+mass_b)) + relative_speed_squared = speed**2+3*temperature_b*ELEMENTARY_CHARGE/mass_b + b90 = jnp.abs(charge_a*charge_b)/(4*jnp.pi*EPSILON_0*reduced_mass*relative_speed_squared) + quantum = HBAR/(2*reduced_mass*jnp.sqrt(relative_speed_squared)) + return jnp.hypot(b90, quantum), screening_length + + +def impact_coulomb_logarithm(mass_a, charge_a, mass_b, charge_b, speed, + temperature_b, density, temperature, charge): + """Smooth effective-speed Landau--Spitzer log for a specified background. + + A vacuum has zero collision contribution and returns zero. A nonpositive + occupied-background log returns NaN rather than silently clipping an + invalid weak-coupling model into a positive collision frequency. + """ + inverse_squared = debye_inverse_squared(density, temperature, charge) + # Use a finite inactive value so vacuum derivatives do not contain 0*inf. + length = 1/jnp.sqrt(jnp.where(inverse_squared == 0, 1., inverse_squared)) + bmin, bmax = impact_parameters(mass_a, charge_a, mass_b, charge_b, speed, + temperature_b, length) + logarithm = jnp.log(bmax)-jnp.log(bmin) + occupied = jnp.where(logarithm > 0, logarithm, jnp.nan) + return jnp.where(inverse_squared == 0, 0., occupied) + + @partial(jit, static_argnames=['species']) def coulomb_logarithm(ma:float, ea: float, species_b: int, v: float, points, species: BackgroundSpecies) -> float: + """Selected pairwise Coulomb logarithm; NRL remains the default.""" + if species.coulomb_log_model == "impact": + screening = species if species.screening_species is None else species.screening_species + n = jnp.stack([screening.get_density(i, points) for i in range(screening.number_species)]) + T = jnp.stack([screening.get_temperature(i, points) for i in range(screening.number_species)]) + return impact_coulomb_logarithm(ma, ea, species.mass[species_b], species.charge[species_b], + v, species.get_temperature(species_b, points), n, T, screening.charge) + return nrl_coulomb_logarithm(ma, ea, species_b, v, points, species) + + +def nrl_coulomb_logarithm(ma:float, ea: float, species_b: int, v: float, points, species: BackgroundSpecies) -> float: """NRL Plasma Formulary (2019, p. 34) Coulomb logarithm of a test particle (mass ``ma``, charge ``ea``, speed ``v``) on background species ``species_b``. diff --git a/essos/boozer.py b/essos/boozer.py index fed90fb4..aa0f10df 100644 --- a/essos/boozer.py +++ b/essos/boozer.py @@ -1,4 +1,4 @@ -"""Fixed-step K=0 Boozer guiding-centre tracing (White, 2014). +"""K=0 Boozer guiding-centre tracing (White, 2014). Interpolate the |B| spectrum in sqrt(s), with m>=1 coefficients divided by sqrt(s) for axis regularity; interpolate iota, G and I in s. Explicit RK runs in @@ -309,6 +309,9 @@ class BoozerTrace: its end point and energy error are kept apart in ``terminal_states`` (``(particles, 5)``, as ``states``) and ``terminal_energy_error``; both are NaN for particles that were not lost and neither is a physical diagnostic. + Native runs also return ``step_stats`` (trials, accepted, rejected) and + ``solver_status`` (``essos.rk.RKStatus``), each per particle. + Their terminal extrapolation fields remain None: native events stop at the root. """ times: np.ndarray @@ -319,6 +322,8 @@ class BoozerTrace: failed_times: np.ndarray | None = None terminal_states: np.ndarray | None = None terminal_energy_error: np.ndarray | None = None + step_stats: np.ndarray | None = None # native only: (particles, 3), trials/accepted/rejected + solver_status: np.ndarray | None = None # native RKStatus per particle @property def lost(self): @@ -486,7 +491,10 @@ def interval(carry, i): def trace_boozer(field, s, theta, zeta, pitch, *, speed, mass, charge, tmax, timestep=None, n_save=100, species=None, seed=0, thermal_cutoff=1.5, devices=None, - progress=True, compact=True, method="dopri8", tolerance=1e-8): + progress=True, compact=True, method=None, tolerance=1e-8, + integrator=None, adaptive=True, rtol=1e-9, atol=1e-9, + native_controller="i", native_pcoeff=.4, native_icoeff=.3, + native_execution="jax", max_steps=MAX_ATTEMPTS): """Trace guiding centres from Boozer ``(s, theta, zeta)`` with pitch ``v_par/v``. The default ``timestep`` is ``R0 / (2 nfp speed)``, with ``R0 = |G| / |B|`` on the @@ -511,8 +519,37 @@ def trace_boozer(field, s, theta, zeta, pitch, *, speed, mass, charge, tmax, tim ``"adaptive"`` (Dopri5) and ``"adaptive8"`` (Dopri8) control each particle's step so the embedded error stays below ``tolerance`` (in ``sqrt(s)`` and ``zeta`` units and relative to the speed for ``v_par``); ``timestep`` is then only the first trial step. + + For the shared native orbit driver, select ``integrator="essos_rk45"`` or + ``"essos_dopri8"`` and omit ``method``. ``adaptive=True`` (default) uses + the I-controller with ``rtol=atol=1e-9``; ``adaptive=False`` uses ``timestep`` + directly, clipping only at tmax. Native controller/PI coefficients and + standard dense output match the options in ``Tracing``. + Saves use dense output and do not constrain the orbit steps. The native + error budget is ``max(norm(du,dw), abs(dzeta), abs(dv_par)/speed)/(rtol+atol)``: + unit flux radius, radians and birth speed, rather than Cartesian metres. + The drift and field representation are unchanged. Native mode currently + supports collisionless orbits only. It solves the whole horizon, so legacy + interval compaction is unused and progress reports completion. Native + ``step_stats`` and ``solver_status`` are returned on ``BoozerTrace``; + energy error is measured at saved and terminal states. LCFS events are + root-found and subsequent saves hold that state; failures are reported. """ - if method not in ("rk4", "dopri5", "dopri8", "adaptive", "adaptive8"): + if integrator not in (None, "essos_rk45", "essos_dopri8"): + raise ValueError("integrator must be None, 'essos_rk45' or 'essos_dopri8'") + if integrator is not None: + if method is not None: + raise ValueError("method selects a legacy Boozer stepper; omit it for a native integrator") + if species is not None: + raise ValueError("native Boozer integrators currently support collisionless orbits only") + if not isinstance(adaptive, (bool, np.bool_)): + raise ValueError("adaptive must be boolean") + for name, value, positive in (("rtol", rtol, False), ("atol", atol, True)): + if np.ndim(value) or not np.isfinite(value) or (value <= 0 if positive else value < 0): + raise ValueError(f"{name} must be finite and {'positive' if positive else 'nonnegative'}") + else: + method = "dopri8" if method is None else method + if integrator is None and method not in ("rk4", "dopri5", "dopri8", "adaptive", "adaptive8"): raise ValueError("method must be 'rk4', 'dopri5', 'dopri8', 'adaptive' or 'adaptive8'") if not (np.isfinite(tolerance) and tolerance > 0): raise ValueError("tolerance must be positive and finite") @@ -560,6 +597,17 @@ def trace_boozer(field, s, theta, zeta, pitch, *, speed, mass, charge, tmax, tim sharding = NamedSharding(Mesh(np.asarray(devices[:ndev]), ("p",)), PartitionSpec("p")) args = [jax.device_put(a, sharding) for a in args] y0, mu0, keys = args + if integrator is not None: + times = np.linspace(0., float(tmax), n_int + 1) + from essos.rk import trace_boozer_orbits as native_orbits + result = native_orbits(field, y0, mu0, mass, charge, speed[0], jnp.asarray(times), + float(timestep), rtol, atol, "dopri5" if integrator == "essos_rk45" else "dopri8", + bool(adaptive), native_controller, native_pcoeff, native_icoeff, max_steps, execution=native_execution) + states, t_loss, t_fail, err, stats, status = (np.asarray(a)[:n] for a in result) + if progress is not None: + progress(n_int, n_int) + return BoozerTrace(times, states, t_loss, np.full(n, -1.), err, t_fail, + step_stats=stats, solver_status=status) carry, first = _start(field, y0, mu0) chunk = n_int if progress is None and not compact else -(-n_int // 10) states = np.empty((n, n_int + 1, 5), dtype=np.asarray(first).dtype) diff --git a/essos/dynamics.py b/essos/dynamics.py index 385f0697..177e5877 100644 --- a/essos/dynamics.py +++ b/essos/dynamics.py @@ -1050,10 +1050,22 @@ def _batch_solver(tracing, place): class Tracing(): def __init__(self, trajectories_input=None, initial_conditions=None, times_to_trace=None, field=None, electric_field=None,model=None, maxtime: float = 1e-7, timestep: int = 1.e-8, - rtol= 1.e-7, atol = 1e-7, particles=None, condition=None,species=None,tag_gc=1.,boundary=None,rejected_steps=None, + rtol=None, atol=None, particles=None, condition=None,species=None,tag_gc=1.,boundary=None,rejected_steps=None, solver=None, stopping_criteria=None, progress=True, devices=None, max_steps=1_000_000, exterior_field=None, wall=None, max_returns=16, reentry_depth=None, - particle_batch_size=None, adjoint=None): + particle_batch_size=None, integrator="diffrax", native_error_control="physics", + orbit_length_scale=1., orbit_speed_scale=None, + native_controller="i", native_pcoeff=.4, native_icoeff=.3, + native_adjoint="none", native_adjoint_checkpoint_steps=16, + native_adjoint_max_accepted_steps=None, native_adjoint_parameter_accumulation="segment", adjoint=None): + + self.native_adjoint, self.native_adjoint_checkpoint_steps = native_adjoint, native_adjoint_checkpoint_steps + self.native_adjoint_max_accepted_steps = native_adjoint_max_accepted_steps + self.native_adjoint_parameter_accumulation = native_adjoint_parameter_accumulation + + from essos.rk import _configure_tracing as configure + configure(self, integrator, model, solver, native_error_control, orbit_length_scale, + orbit_speed_scale, native_controller, native_pcoeff, native_icoeff) if condition is not None and stopping_criteria is not None: raise ValueError("Pass condition or stopping_criteria, not both") @@ -1089,8 +1101,9 @@ def __init__(self, trajectories_input=None, initial_conditions=None, times_to_tr self.times_to_trace = times_to_trace self.maxtime = maxtime self.timestep = timestep - self.rtol = rtol - self.atol = atol + default_tolerance = 1e-7 if integrator == "diffrax" else 1e-9 + self.rtol = default_tolerance if rtol is None else rtol + self.atol = default_tolerance if atol is None else atol self._trajectories = trajectories_input self.particles = particles self.species=species @@ -1384,9 +1397,11 @@ def _adaptive_tolerances(self, flag=False): return rtol.at[indices].set(0), atol def _terms(self, key, flag=False, events=()): - """Diffrax terms, solver and step-size controller of self.model (with _with_failure_flag if ``flag``).""" + """Terms and stepping configuration, with a failure flag for VMEC segments.""" flagged = (lambda f, drift=True: _with_failure_flag(f, drift)) if flag else (lambda f, drift=True: f) dt0, model = self.timestep, self.model + if self.integrator != "diffrax": + return flagged(self.ODE_term.vector_field), None, model in _ADAPTIVE_MODELS if model in _SDE_MODELS: drift, diffusion, solver, dim = _SDE_MODELS[model] # With flag (segments), a vmapped solve of an orbit that starts at maxtime evaluates the path @@ -1412,8 +1427,11 @@ def _terms(self, key, flag=False, events=()): dtmin=dt0 if model == 'FullOrbitCollisions' else None, events=events) return terms, solver, controller - def _solve(self, terms, solver, controller, t0, y0, args, event, throw=False): - """diffeqsolve from t0 to maxtime, saving at self.times (clipped to t0) and at the end.""" + def _solve(self, terms, solver, controller, t0, y0, args, event, throw=False, *, exterior=False, flag=False): + """Integrate to maxtime, saving at self.times (clipped to t0) and at the end.""" + if self.integrator != "diffrax": + from essos.rk import _solve_tracing as solve_trace + return solve_trace(self, terms, controller, t0, y0, args, event, throw, exterior, flag) import warnings warnings.simplefilter("ignore", category=FutureWarning) # see https://github.com/patrick-kidger/diffrax/issues/445 return diffeqsolve(terms, solver, t0=t0, t1=self.maxtime, dt0=self.timestep, y0=y0, args=args, @@ -1450,9 +1468,16 @@ def _vmec_orbit(self, y0, key): if ext is not None: wall = self.wall if self.wall is not None else (lambda x: jnp.ones(())) depth = lambda y: self.field.boundary_distance(y[:3]) - self.reentry_depth - outside = (ODETerm(_with_failure_flag(lambda t, y, args: self._masked(GuidingCenterMu, t, y, args))), self.solver if self.solver is not None else - diffrax.Dopri8(), _EventSteps(pcoeff=0.4, icoeff=0.3, dcoeff=0, rtol=self.rtol, atol=self.atol, - events=(lambda y: wall(y[:3]), depth)), + if self.integrator != "diffrax": + exterior_terms = (_with_failure_flag(GuidingCenterMu), None, True) + else: + exterior_terms = ( + ODETerm(_with_failure_flag(lambda t, y, args: self._masked(GuidingCenterMu, t, y, args))), + self.solver if self.solver is not None else diffrax.Dopri8(), + _EventSteps(pcoeff=0.4, icoeff=0.3, dcoeff=0, rtol=self.rtol, atol=self.atol, + events=(lambda y: wall(y[:3]), depth)), + ) + outside = (*exterior_terms, (ext, self.particles, Electric_field_zero()), Event((lambda t, y, args, **kwargs: wall(y[:3]), lambda t, y, args, **kwargs: depth(y), _failed_event), root_finder=_EVENT_ROOT_FINDER)) @@ -1464,7 +1489,8 @@ def segment(o, run, spec, y, code, to_flux=lambda y: y): # A non-finite start fails at once; it is replaced by a finite one so that no NaN enters the derivative. ok = jnp.isfinite(y).all() run, bad, y = run & ok, run & ~ok, jnp.where(ok, y, 0.5) - solution = self._solve(*spec[:3], jnp.where(run, o["t"], T * (1 - 1e-9)), jnp.append(y, 0.0), *spec[3:]) + solution = self._solve(*spec[:3], jnp.where(run, o["t"], T * (1 - 1e-9)), jnp.append(y, 0.0), *spec[3:], + exterior=code != 0, flag=True) saves, end = vmap(to_flux)(solution.ys[0][:, :-1]), to_flux(solution.ys[1][-1, :-1]) failed = bad | run & (solution.event_mask[-1] | ~((solution.result == diffrax.RESULTS.successful) | (solution.result == diffrax.RESULTS.event_occurred) diff --git a/essos/fields.py b/essos/fields.py index c9510cd6..5a0d0a2d 100644 --- a/essos/fields.py +++ b/essos/fields.py @@ -296,6 +296,25 @@ def B(self, points): def to_xyz(self, points): return points +def _vmec_radial_slopes(scaled): + """Nodal slopes with a linear first interval and a parabolic last one.""" + n, step = len(scaled), jnp.diff(scaled, axis=0) + interior = np.r_[0, 0, np.ones(n - 3), 1.0] + return lax.linalg.tridiagonal_solve( + interior, np.r_[1, 1, 4 * np.ones(n - 3), 1], np.r_[interior[:-1], 0], + jnp.concatenate([step[:1], step[:1], 3 * (scaled[3:] - scaled[1:-2]), 2 * step[-1:]]), + ) + + +def _vmec_radial_segment(u, a, b, da, db): + """Evaluate a cubic segment with matching value, slope and curvature past its end.""" + t = jnp.minimum(u, 1.0) + over = jnp.maximum(u - 1.0, 0.0) + beyond = over * db + 0.5 * over**2 * (6 * (a - b) + 2 * da + 4 * db) + return ((1 + 2 * t) * (1 - t)**2 * a + t * (1 - t)**2 * da + + t * t * (3 - 2 * t) * b + t * t * (t - 1) * db + beyond) + + def _radial_interp(s, grid, table, xm, covariant_s=False, half_grid=False, axis_m1=None): """Interpolate every Fourier mode of a wout table at ``s``. @@ -329,27 +348,15 @@ def _radial_interp(s, grid, table, xm, covariant_s=False, half_grid=False, axis_ scaled = scaled.at[0].set(jnp.where(m > 0, 2 * scaled[1] - scaled[2], scaled[0])) if axis_m1 is not None: scaled = scaled.at[0].set(jnp.where(m == 1, axis_m1, scaled[0])) - # Nodal slopes (per grid interval) of the C2 cubic spline: the first interval keeps the linear form that the - # axis rows above are extrapolated with, the last one is a parabola. - n, step = len(grid), jnp.diff(scaled, axis=0) - interior = np.r_[0, 0, np.ones(n - 3), 1.0] - slope = lax.linalg.tridiagonal_solve( - interior, np.r_[1, 1, 4 * np.ones(n - 3), 1], np.r_[interior[:-1], 0], - jnp.concatenate([step[:1], step[:1], 3 * (scaled[3:] - scaled[1:-2]), 2 * step[-1:]])) + slope = _vmec_radial_slopes(scaled) ds = grid[1] - grid[0] i = jnp.clip(jnp.floor((s - grid[0]) / ds).astype(int), 0, len(grid) - 2) u = (s - grid[i]) / ds - t = jnp.minimum(u, 1.0) q = jnp.sqrt(jnp.maximum(s, jnp.finfo(jnp.result_type(s, float)).tiny)) powers = jnp.stack([1 / q, jnp.ones_like(q), q, q * q, q * q * q]) # q**(2 p) for 2 p = -1..3 - h = jnp.stack([(1 + 2 * t) * (1 - t)**2, t * (1 - t)**2, t * t * (3 - 2 * t), t * t * (t - 1)]) - # Past the last grid point (the half grid ends at s = 1 - ds/2) continue with a parabola that has the end - # value, slope and curvature of the cubic, so the interpolant stays C2 up to the LCFS (a kink in the second - # derivative gives the adaptive integrator an uncontrolled tangent error) instead of freezing there. - over = jnp.maximum(u - 1.0, 0.0) - beyond = over * slope[i + 1] + 0.5 * over**2 * (6 * (scaled[i] - scaled[i + 1]) + 2 * slope[i] + 4 * slope[i + 1]) - return (powers @ (k == np.arange(-1, 4)[:, None])) * (h[0] * scaled[i] + h[1] * slope[i] - + h[2] * scaled[i + 1] + h[3] * slope[i + 1] + beyond) + return (powers @ (k == np.arange(-1, 4)[:, None])) * _vmec_radial_segment( + u, scaled[i], scaled[i + 1], slope[i], slope[i + 1], + ) VMEC_WOUT_ARRAYS = ('bmnc', 'xm', 'xn', 'rmnc', 'zmns', 'bsubsmns', 'bsubumnc', 'bsubvmnc', 'bsupumnc', 'bsupvmnc', 'gmnc', 'xm_nyq', 'xn_nyq', 'Aminor_p') diff --git a/essos/native_ad.py b/essos/native_ad.py new file mode 100644 index 00000000..09f17da4 --- /dev/null +++ b/essos/native_ad.py @@ -0,0 +1,1657 @@ +"""Checkpointed reverse AD of accepted native orbit and collision maps. + +Controllers, rejected trials, event fractions and recorded Wiener increments +are frozen. Stage physics, collision coefficients and spatial kicks remain +differentiable. Only one checkpoint segment's stage residuals is live. +""" +from typing import NamedTuple +import equinox as eqx +import jax +import jax.numpy as jnp +import numpy as np +from jax import lax, tree_util, ad_checkpoint +from jax._src.interpreters import partial_eval +from jax.extend.core import Literal +from jax.custom_derivatives import SymbolicZero, custom_vjp_primal_tree_values +from .rk import (solve_rk, _trial_step, _trial_unrolled, _C, _A, _ERROR, + _C8, _A8, _ERROR8, _rk45_dense, _dopri8_dense, _RKTrial, RKStatus, + _evaluate_inline, _bind_primitive) +from .split import solve_split, SplitStatus + +def gpu_jit_options(): + """Compile guarded GPU reverse without CUDA command-buffer capture. + + Apply to the outer JIT; the solver and its replay remain on the GPU. + """ + return ({'compiler_options':{'xla_gpu_enable_command_buffer':''}} + if jax.default_backend()=='gpu' else {}) + +def _select_trial_step(execution): + return _trial_unrolled if execution == 'unrolled' else _trial_step + +def _contains_custom_rule(graph): + """Find opaque derivative rules, including calls nested in control flow.""" + for equation in graph.eqns: + if equation.primitive.name.startswith("custom_"): + return True + for value in tree_util.tree_leaves(equation.params): + nested = getattr(value, "jaxpr", value) + if hasattr(nested, "eqns") and _contains_custom_rule(nested): + return True + return False + + +def _partition_graph(graph, unknowns): + # Partial evaluation can replace a nested custom-JVP call by its primal + # graph. In that case only partition whole primitive calls by dependency; + # never transform their bodies. Parameter-only calls still move to setup, + # avoiding pullbacks of fixed discretization data inside the stage VJP. + if _contains_custom_rule(graph.jaxpr): + from jax.extend.core import ClosedJaxpr, Literal + if not all(unknowns): + raise ValueError("opaque RHS partition expects state/time inputs") + examples = [jax.ShapeDtypeStruct(var.aval.shape, var.aval.dtype) for var in graph.jaxpr.invars] + original = graph + graph = jax.make_jaxpr(lambda *values: _evaluate_inline( + original.jaxpr, original.consts, *values))(*examples) + body = graph.jaxpr + unknown = set(body.invars) + setup_equations, stage_equations = [], [] + for equation in body.eqns: + dependent = bool(equation.effects) or any( + not isinstance(var, Literal) and var in unknown for var in equation.invars) + (stage_equations if dependent else setup_equations).append(equation) + if dependent: + unknown.update(equation.outvars) + residuals, seen = [], set() + for var in [var for equation in stage_equations for var in equation.invars]+list(body.outvars): + if not isinstance(var, Literal) and var not in unknown and var not in seen: + residuals.append(var) + seen.add(var) + setup = body.replace(invars=[], outvars=residuals, eqns=setup_equations, + effects=set().union(*(eq.effects for eq in setup_equations))) + stage = body.replace(constvars=[], invars=residuals+list(body.invars), + eqns=stage_equations, effects=set().union(*(eq.effects for eq in stage_equations))) + return ClosedJaxpr(setup, graph.consts), ClosedJaxpr(stage, ()) + setup, stage, _, _ = partial_eval.partial_eval_jaxpr_nounits( + graph, unknowns, instantiate=True) + return setup, stage + + +def _partition_rhs(rhs, t0, y0, args): + """Split solve-invariant setup from time/state-dependent stage arithmetic.""" + graph = jax.make_jaxpr(lambda t, y: rhs(t, y, args))(t0, y0) + return _partition_graph(graph, [True, True]) + + +class _RKCheckpointTape(NamedTuple): + """Accepted step sizes and segment starts; no per-step state/save tape.""" + step_sizes: jax.Array + times: jax.Array + states: jax.Array + derivatives: jax.Array + fraction: jax.Array + final_time: jax.Array + initial_saves: jax.Array + count: jax.Array + status: jax.Array + + +class _RKSchedule(NamedTuple): + """Accepted schedule and optional sparse checkpoints for a containing split solve.""" + times: jax.Array + fraction: jax.Array + count: jax.Array + states: object = None + derivatives: object = None + + +def _geometry_pullback(values,seed): + """Transpose every prepared input, including independent tangent aliases. + + The original setup pullback combines the tangent views and handles coil + symmetry/current scaling. Diagonal placeholders retain their own bars. + Coordinate-wise matrix products fuse with the geometry operations here. + """ + point,gamma,ly,lz,lx,weights,z0,tangent,z1,z2 = values + u,matrix = seed + r = (point-gamma).T + cross_tangent = jnp.stack([lx,ly,lz]) + radius = jnp.linalg.norm(r,axis=0) + inverse3 = 1./radius**3 + inverse5 = inverse3/radius**2 + inverse7 = inverse5/radius**2 + cross = jnp.cross(cross_tangent,r,axisa=0,axisb=0,axisc=0) + mr = jnp.stack([matrix[i,0]*r[0]+matrix[i,1]*r[1]+matrix[i,2]*r[2] for i in range(3)]) + mtc = jnp.stack([matrix[0,i]*cross[0]+matrix[1,i]*cross[1]+matrix[2,i]*cross[2] for i in range(3)]) + skew = jnp.array([matrix[2,1]-matrix[1,2],matrix[0,2]-matrix[2,0],matrix[1,0]-matrix[0,1]])[:,None,None] + u = u[:,None,None] + k = jnp.sum(u*cross+skew*tangent,axis=0) + d = jnp.sum(cross*mr,axis=0) + dr = (jnp.cross(u,cross_tangent,axisa=0,axisb=0,axisc=0)*inverse3 + -3*(k*r+jnp.cross(mr,cross_tangent,axisa=0,axisb=0,axisc=0)+mtc)*inverse5 + +15*d*r*inverse7) + dl = (jnp.cross(r,u,axisa=0,axisb=0,axisc=0)*inverse3 + -3*jnp.cross(r,mr,axisa=0,axisb=0,axisc=0)*inverse5) + factor = weights/gamma.shape[1] + dr,dl = dr*factor,dl*factor + bars = (jnp.sum(dr,axis=(1,2)),-dr.T,dl[1],dl[2],dl[0], + jnp.sum(k*inverse3-3*d*inverse5,axis=0)/gamma.shape[1], + matrix[0,0].reshape((1,)),skew*inverse3*factor, + matrix[1,1].reshape((1,)),matrix[2,2].reshape((1,))) + return tuple(bar.astype(value.dtype) for bar,value in zip(bars,values)) + + +def _supported_field(closed, jacobian): + from .fields import BiotSavart + body = closed.jaxpr + name = "B_and_dB_by_dX" if jacobian else "B" + original = getattr(getattr(BiotSavart, name, None), "__wrapped__", None) + if original is None: + return False + source = original.__code__ + expected = f"{name} at {source.co_filename}:{source.co_firstlineno}" + if (getattr(getattr(body,"debug_info",None),"func_src_info",None) != expected + or body.effects or len(body.invars) != (10 if jacobian else 6)): + return False + shapes = [var.aval.shape for var in body.invars] + if len(shapes[1]) != 3 or shapes[1][-1] != 3: + return False + coils,nodes,_ = shapes[1] + if coils < 1 or nodes < 1: + return False + expected_shapes = [(3,),(coils,nodes,3),(nodes,coils),(nodes,coils),(nodes,coils),(coils,)] + if jacobian: + expected_shapes += [(1,),(3,nodes,coils),(1,),(1,)] + if shapes != expected_shapes or [var.aval.shape for var in body.outvars] != ([(3,),(3,3)] if jacobian else [(3,)]): + return False + if any(var.aval.dtype != jnp.dtype('float64') for var in body.invars): + return False + cross = [eq for eq in body.eqns if eq.primitive.name == 'jit' and eq.params.get('name') == 'cross'] + return len(cross) == 1 and list(cross[0].invars[1:]) == list(body.invars[2:5]) + + +def _B_pullback(values, seed): + """Exact field-only transpose, retaining all six independent input bars. + + Coordinate products expose the small cross products to fusion. The setup + pullback still combines tangent views and maps geometry/current weights to + the original coil DOFs; no physical inputs are frozen here. + """ + point, gamma, ly, lz, lx, weights = values + r = (point-gamma).T + inverse3 = 1./jnp.linalg.norm(r, axis=0)**3 + inverse5 = inverse3/jnp.sum(r*r, axis=0) + factor = weights/gamma.shape[1] + u = seed[0][:, None, None] + c0, c1, c2 = ly*r[2]-lz*r[1], lz*r[0]-lx*r[2], lx*r[1]-ly*r[0] + k = u[0]*c0+u[1]*c1+u[2]*c2 + dr = jnp.stack(( + factor*((u[1]*lz-u[2]*ly)*inverse3-3*k*r[0]*inverse5), + factor*((u[2]*lx-u[0]*lz)*inverse3-3*k*r[1]*inverse5), + factor*((u[0]*ly-u[1]*lx)*inverse3-3*k*r[2]*inverse5))) + dl = jnp.stack((r[1]*u[2]-r[2]*u[1], r[2]*u[0]-r[0]*u[2], + r[0]*u[1]-r[1]*u[0]))*inverse3*factor + bars = (jnp.sum(dr, axis=(1, 2)), -dr.T, dl[1], dl[2], dl[0], + jnp.sum(k*inverse3, axis=0)/gamma.shape[1]) + return tuple(bar.astype(value.dtype) for bar, value in zip(bars, values)) + + +def has_prepared_biot_savart(graph): + """Recognize ordinary JIT calls without entering custom/control-flow bodies.""" + for equation in graph.eqns: + if equation.primitive.name == "jit": + nested = equation.params["jaxpr"] + name = equation.params.get("name") + if name in ("B", "B_and_dB_by_dX") and _supported_field(nested, name != "B"): + return True + if has_prepared_biot_savart(nested.jaxpr): + return True + return False + + +def _field_call(closed, values, jacobian=True): + """Keep original values and use the exact transpose to define a JVP. + + Transposing the linear pullback supplies the tangent without freezing its + geometry coefficients. Ordinary JAX AD still provides higher derivatives. + """ + pullback = _geometry_pullback if jacobian else _B_pullback + @jax.custom_jvp + def evaluate(*values): + return tuple(jax.core.eval_jaxpr(closed.jaxpr,closed.consts,*values)) + @evaluate.defjvp + def tangent(primals,tangents): + value = evaluate(*primals) + seed_shape = tree_util.tree_map(jnp.zeros_like,value) + transpose = jax.linear_transpose(lambda seed:pullback(primals,seed),seed_shape) + return value,transpose(tangents)[0] + # Expose only the small field outputs to the outer checkpoint policy. + # A custom JVP otherwise hides its internal field reductions from it. + return tuple(ad_checkpoint.checkpoint_name(value, "native_biot_savart_output") + for value in evaluate(*values)) + + +def _rewrite(graph,constants,*arguments): + env = dict(zip(graph.constvars,constants)) + env.update(zip(graph.invars,arguments)) + def read(var): + return var.val if isinstance(var,Literal) else env[var] + for eq in graph.eqns: + values = [read(var) for var in eq.invars] + with eq.ctx.manager: + if eq.primitive.name == 'jit': + closed = eq.params['jaxpr'] + name = eq.params.get('name') + if name in ('B', 'B_and_dB_by_dX') and _supported_field(closed, name != 'B'): + result = _field_call(closed, values, name != 'B') + else: + result = _rewrite(closed.jaxpr,closed.consts,*values) + else: + result = _bind_primitive(eq.primitive, values, eq.params) + if not eq.primitive.multiple_results: + result = [result] + env.update(zip(eq.outvars,result)) + return [read(var) for var in graph.outvars] + + +def prepare_biot_savart_rhs(prepare,evaluate,t,y,raw): + """Specialize only the prepared reverse RHS; preserve the original setup.""" + parameters = prepare(raw) + graph = jax.make_jaxpr(evaluate)(t,y,parameters) + if not has_prepared_biot_savart(graph.jaxpr): + return None + def rhs(t,y,parameters): + return _rewrite(graph.jaxpr,graph.consts,t,y,*tree_util.tree_leaves(parameters))[0] + # Materialize the transformed graph now so the selection is deterministic. + changed = jax.make_jaxpr(rhs)(t,y,parameters) + def prepared_rhs(t,y,parameters): + return jax.core.eval_jaxpr(changed.jaxpr,changed.consts,t,y,*tree_util.tree_leaves(parameters))[0] + prepared_rhs._native_biot_savart_transpose = True + return prepare,prepared_rhs + + +def prepare_reverse_rhs(prepare, evaluate, t, y, raw, *, specialize_biot_savart=True): + """Repartition the same RHS after exposing jit boundaries to reverse AD. + + This is a reverse-only representation: the adaptive forward driver keeps + its original prepared RHS. Field objects and their own AD rules are unchanged. + Stock prepared Biot--Savart B and B/J calls use exact geometry transposes. + RHSs containing custom derivative primitives retain their original + preparation, including rules nested in jit or control-flow calls. + """ + original = jax.make_jaxpr(lambda t,y,p: evaluate(t,y,prepare(p)))(t,y,raw) + if _contains_custom_rule(original.jaxpr): + return prepare, evaluate + if specialize_biot_savart: + if has_prepared_biot_savart(original.jaxpr): + specialized = prepare_biot_savart_rhs(prepare, evaluate, t, y, raw) + if specialized is not None: + return specialized + if not any(eq.primitive.name == "jit" for eq in original.jaxpr.eqns): + return prepare, evaluate + graph = jax.make_jaxpr(lambda t,y,p: _evaluate_inline(original.jaxpr, original.consts, + t,y,*tree_util.tree_leaves(p))[0])(t,y,raw) + setup, stage, _, _ = partial_eval.partial_eval_jaxpr_nounits( + graph, [True, True]+[False]*len(tree_util.tree_leaves(raw)), instantiate=True) + + def prepare_values(raw): + return tuple(jax.core.eval_jaxpr(setup.jaxpr, setup.consts, *tree_util.tree_leaves(raw))) + + def rhs(t,y,parameters): + return jax.core.eval_jaxpr(stage.jaxpr, stage.consts, *parameters,t,y)[0] + + return prepare_values, rhs + + +def prepare_rhs_linearization(rhs, t, y, parameters, *, cache_field_outputs=True): + """Return ``(evaluate, pullback, initial_cache)`` or None for cheap RHSs. + + ``evaluate(t, y)`` returns the original RHS and compact residuals. + ``pullback(cache, seed)`` returns state and prepared-parameter cotangents. + The initial cache is used only for the first accepted step's initial FSAL + derivative. Other steps reuse the preceding endpoint derivative in AD. + Named small Biot--Savart outputs remain visible even when their reductions + are hidden behind a custom JVP. Large geometry arrays are rematerialized. + ``cache_field_outputs=False`` isolates this retention in internal benchmarks. + """ + selected = [] + + def save_compact_value(primitive, *avals, **params): + if (cache_field_outputs and primitive.name == "name" + and params.get("name") == "native_biot_savart_output"): + keep = len(avals) == 1 and np.prod(avals[0].shape) <= 12 + if keep: + selected.append(True) + return bool(keep) + if primitive.name != "reduce_sum": + return False + shape = avals[0].shape + output_size = np.prod([size for axis, size in enumerate(shape) if axis not in params["axes"]]) + keep = np.prod(shape) > 9 and output_size <= 9 + if keep: + selected.append(True) + return bool(keep) + + remat_rhs = jax.checkpoint(rhs, policy=save_compact_value, prevent_cse=False) + transpose_graph = [] + + def linearize(t, y, values): + value, pullback = jax.vjp(lambda y, p: remat_rhs(t, y, p), y, values) + graph, shape = jax.make_jaxpr(pullback, return_shape=True)(jnp.zeros_like(value)) + transpose_graph[:] = [(graph.jaxpr, tree_util.tree_structure(shape))] + return value, tuple(graph.consts) + + graph = jax.make_jaxpr(linearize)(t, y, parameters) + if not selected: + return None + # This is value dependence for storing residuals, not a stop-gradient on + # physical parameters: the transpose still returns every parameter bar. + setup, stage, unknown, _ = partial_eval.partial_eval_jaxpr_nounits( + graph, [True, True]+[False]*len(tree_util.tree_leaves(parameters)), + instantiate=[True]+[False]*(len(graph.out_avals)-1)) + values = jax.core.eval_jaxpr(setup.jaxpr, setup.consts, *tree_util.tree_leaves(parameters)) + fixed_count = sum(not flag for flag in unknown) + constants, bindings = values[:fixed_count], values[fixed_count:] + + descriptors, groups = [], {} + for aval in stage.out_avals[1:]: + dtype = aval.dtype + size = int(np.prod(aval.shape)) + group = len(groups) if dtype not in groups else list(groups).index(dtype) + offset = groups.get(dtype, 0) + groups[dtype] = offset+size + descriptors.append((group, offset, size, aval.shape)) + + def evaluate(t, y): + out = jax.core.eval_jaxpr(stage.jaxpr, stage.consts, *bindings, t, y) + buffers = [[] for _ in groups] + for value, (group, _, _, _) in zip(out[1:], descriptors): + buffers[group].append(jnp.ravel(value)) + return out[0], tuple(jnp.concatenate(values) for values in buffers) + + transpose, structure = transpose_graph[0] + + def pullback(packed, seed): + residuals = [packed[group][offset:offset+size].reshape(shape) + for group, offset, size, shape in descriptors] + fixed, variable = iter(constants), iter(residuals) + values = [next(variable) if flag else next(fixed) for flag in unknown[1:]] + out = jax.core.eval_jaxpr(transpose, values, seed) + return tree_util.tree_unflatten(structure, out) + + return evaluate, pullback, evaluate(t, y)[1] + + +def _zeros(tree): + def zero(x): + x = jnp.asarray(x) + dtype = x.dtype if jnp.issubdtype(x.dtype, jnp.inexact) else jax.dtypes.float0 + return jnp.zeros(x.shape, dtype=dtype) + return tree_util.tree_map(zero, tree) + + +def _add(left, right): + return tree_util.tree_map(lambda a, b: a if a.dtype == jax.dtypes.float0 else a+b, left, right) + + +class _ParameterActivity(eqx.Module): + """Static JAX activity flags, distinct from the frozen time schedule.""" + flags: tuple = eqx.field(static=True) + + +def _convert_all(function, *examples): + """Expose every graph constant, including outer jit tracers, as an input.""" + graph, shape = jax.make_jaxpr(function, return_shape=True)(*examples) + structure = tree_util.tree_structure(shape) + def evaluate(arguments, constants): + flat = jax.core.eval_jaxpr(graph.jaxpr, constants, *tree_util.tree_leaves(arguments)) + return tree_util.tree_unflatten(structure, flat) + return evaluate, graph.consts + + +def _prepared_activity(prepare, active): + """Exclude fixed tables from parameter transposes before tracing stages.""" + graph=jax.make_jaxpr(prepare)(active) + live=set(graph.jaxpr.invars) + for equation in graph.jaxpr.eqns: + if equation.primitive.name!='stop_gradient' and any( + not isinstance(v,Literal) and v in live for v in equation.invars): + live.update(equation.outvars) + return tuple(not isinstance(v,Literal) and v in live for v in graph.jaxpr.outvars) + + +def _freeze_fixed(values, flags): + leaves,structure=tree_util.tree_flatten(values) + return tree_util.tree_unflatten(structure, + [value if active else lax.stop_gradient(value) for value,active in zip(leaves,flags)]) + + +def _step_pullback(rhs, y, t, h, endpoint, increments, parameters, + fraction, sample_fractions, owned, by, bf, saved_bar, method, + initial_fsal=False, cached_pullback=None): + """Transpose the RK recurrence from reconstructed primal stage values. + + Segment reconstruction supplies the primal stage values. Linear RK/dense + algebra is transposed separately; each RHS VJP retains the physical + derivatives at the original stage time/state. Stock prepared Biot--Savart + calls can use the exact native field linearization. Only one RHS transpose's temporary arrays are + live at a time, rather than every stage's field intermediates. The reverse + recurrence includes all stage dependencies; stages are not frozen in AD. + """ + nodes, rows, _ = (_C, _A, _ERROR) if method == "dopri5" else (_C8, _A8, _ERROR8) + dense = _rk45_dense if method == "dopri5" else _dopri8_dense + def outputs(y, endpoint, increments, parameters): + terminal = dense(y, endpoint, increments, fraction) + samples = jax.vmap(lambda s: dense(y, endpoint, increments, s))(sample_fractions) + return terminal, samples + _, output_vjp = jax.vjp(outputs, y, endpoint, increments, parameters) + dy, dy1, dk, dense_parameters = output_vjp((by, jnp.where(owned[:, None], saved_bar, 0.))) + dp = dense_parameters + + dy = dy+dy1 + bank = increments[:-1] + dk = dk.at[:-1].add(jnp.asarray(rows[-1], y.dtype)[:, None]*dy1) + coefficients = np.zeros((len(increments), len(bank))) + for i, row in enumerate(rows, start=1): + coefficients[i, :len(row)] = row + coefficients = jnp.asarray(coefficients, y.dtype) + times = jnp.asarray((0.,)+nodes, y.dtype) + + def stage(reverse_index, carry): + dy, dk, dp = carry + i = len(increments)-1-reverse_index + weights = coefficients[i] + point = y+jnp.tensordot(weights, bank, axes=1) + point = jnp.where(i == len(increments)-1, endpoint, jnp.where(i == 0, y, point)) + # The endpoint FSAL derivative is unscaled; its RK increment also + # contributes to dense output. Stage zero is visited only on the first + # accepted step, where the initial FSAL value is an actual RHS call. + seed = h*dk[i]+jnp.where(i == len(increments)-1, bf, 0.) + if cached_pullback is None: + _, rhs_vjp = jax.vjp(lambda state,p: rhs(t+times[i]*h,state,p), point, parameters) + dpoint, dparams = rhs_vjp(seed) + else: + dpoint, dparams = cached_pullback(i, seed) + return dy+dpoint, dk.at[:-1].add(weights[:, None]*dpoint), _add(dp, dparams) + bound = len(increments)-1+jnp.asarray(initial_fsal, jnp.int32) + dy, dk, dp = lax.fori_loop(jnp.asarray(0, jnp.int32), bound, stage, (dy, dk, dp)) + return dy, jnp.where(initial_fsal, 0., h*dk[0]), dp + + +def _trial_with_residuals(linearize, t, y, h, f0, constants, initial_cache): + """Replay the unchanged RK stages and keep compact RHS residuals. + + Used only in backward reconstruction; no embedded error is needed here. + Stage zero's cache belongs to the initial trajectory RHS. It is consumed + only when ``initial_fsal`` is true in the first accepted step's pullback. + """ + nodes, rows, error_weights = constants + n = len(error_weights) + coefficients = np.zeros((n-2, n-1)) + for i, row in enumerate(rows[:-1]): + coefficients[i, :len(row)] = row + coefficients = jnp.asarray(coefficients, y.dtype) + times = jnp.asarray(nodes[:-1], y.dtype) + bank = jnp.concatenate([(h*f0)[None], jnp.zeros((n-2,)+y.shape, y.dtype)]) + cache = tree_util.tree_map(lambda r: jnp.zeros((n,)+r.shape, r.dtype).at[0].set(r), initial_cache) + + def stage(i, values): + bank, cache = values + point = y+jnp.tensordot(coefficients[i-1], bank, axes=1) + f, residuals = linearize(t+times[i-1]*h, point) + return lax.dynamic_update_index_in_dim(bank, h*f, i, axis=0), tree_util.tree_map( + lambda buffer, r: lax.dynamic_update_index_in_dim(buffer, r, i, axis=0), cache, residuals) + + bank, cache = lax.fori_loop(1, n-1, stage, (bank, cache)) + endpoint = y+jnp.tensordot(jnp.asarray(rows[-1], y.dtype), bank, axes=1) + final, residuals = linearize(t+h, endpoint) + cache = tree_util.tree_map(lambda buffer, r: buffer.at[-1].set(r), cache, residuals) + trial = _RKTrial(endpoint, jnp.zeros_like(y), jnp.concatenate([bank, (h*final)[None]]), final) + return trial, cache + + +def solve_accepted(rhs, y0, args=None, **options): + """Return the original forward result with an accepted-step reverse rule. + + Closure conversion exposes RHS field/coil parameters as explicit VJP inputs. + A second conversion exposes forward-only controls (including event/norm + closures) separately: their cotangents are zero under this AD contract. + """ + if options.get("event") is not None: + # The converted driver uses prepared RHS parameters internally; event + # callbacks must still receive their original public args object. + options["event"] = tree_util.tree_map( + lambda function:lambda t,y,unused:function(t,y,args), options["event"]) + y0 = jnp.asarray(y0, dtype=jnp.result_type(y0, float)) + t0 = lax.stop_gradient(jnp.asarray(options.get("t0", 0.), dtype=y0.dtype)) + ts = lax.stop_gradient(jnp.asarray(options.get("ts", ()), dtype=y0.dtype)) + _validate_ad_sizes(adjoint_checkpoint_steps=options.get('adjoint_checkpoint_steps',16), + adjoint_max_accepted_steps=options.get('adjoint_max_accepted_steps')) + checkpoint_steps = int(options.pop("adjoint_checkpoint_steps", 16)) + parameter_accumulation = options.pop("adjoint_parameter_accumulation", "segment") + if parameter_accumulation not in ("step", "segment"): + raise ValueError("adjoint_parameter_accumulation must be 'step' or 'segment'") + # Bind arbitrary ESSOS args before conversion. Particles intentionally is + # an ordinary object, and need not become a new field/particle PyTree just + # to cross the custom VJP boundary. Its actually used traced attributes, + # and those of the field, are exposed by the converted numerical graph. + setup, stage = _partition_rhs(rhs, t0, y0, args) + raw_parameters = (setup.consts, stage.consts) + + def prepare(raw): + return jax.core.eval_jaxpr(setup.jaxpr, raw[0]), raw[1] + + def evaluate(t, y, parameters): + prepared, stage_constants = parameters + return jax.core.eval_jaxpr(stage.jaxpr, stage_constants, *prepared, t, y)[0] + + def forward(initial, parameters): + return solve_rk(evaluate, initial, parameters, **options, + _recorder=_OrbitRecorder(options.get("adjoint_max_accepted_steps") or options.get("max_steps", 1_000_000), checkpoint_steps)) + + converted_forward, driver_constants = _convert_all(forward, y0, prepare(raw_parameters)) + controls = (driver_constants, t0, ts) + constants = (_C, _A, _ERROR) if options.get("method", "dopri5") == "dopri5" else (_C8, _A8, _ERROR8) + method = options.get("method", "dopri5") + + @jax.custom_vjp + def integrate(initial, parameters, controls): + return converted_forward((initial, prepare(parameters)), controls[0])[0] + + def fwd(initial, parameters, controls): + activity = _ParameterActivity(tuple(leaf.perturbed for leaf in tree_util.tree_leaves(parameters))) + initial, raw, controls = custom_vjp_primal_tree_values((initial, parameters, controls)) + parameters = prepare(raw) + out, tape = converted_forward((initial, parameters), controls[0]) + return out, (initial, raw, controls, tape, activity) + + def bwd(residual, bar): + initial, raw, controls, tape, activity = residual + tape = eqx.error_if(tape, tape.count > tape.step_sizes.shape[0], + "accepted-step AD capacity exceeded; increase adjoint_max_accepted_steps") + raw_leaves, raw_structure = tree_util.tree_flatten(raw) + active = tuple(value for value, flag in zip(raw_leaves, activity.flags) if flag) + backward_prepare, backward_rhs = prepare_reverse_rhs(prepare, evaluate, controls[1], initial, raw) + def prepare_active(values): + iterator = iter(values) + full = tree_util.tree_unflatten(raw_structure, + [next(iterator) if flag else value for value, flag in zip(raw_leaves, activity.flags)]) + return backward_prepare(full) + parameters, setup_pullback = jax.vjp(prepare_active, active) + parameter_flags=_prepared_activity(prepare_active,active) + original_rhs=backward_rhs + backward_rhs=lambda t,y,p:original_rhs(t,y,_freeze_fixed(p,parameter_flags)) + _, t0, ts = controls + linearization = prepare_rhs_linearization(backward_rhs, t0, initial, parameters) + if linearization is None: + initial_cache = () + else: + linearize, rhs_pullback, initial_cache = linearization + sample_indices = jnp.arange(len(ts)) + terminal_bar = jnp.zeros_like(initial) if isinstance(bar.y, SymbolicZero) else bar.y + saved_bar = jnp.zeros((len(ts), initial.size), initial.dtype) if isinstance(bar.ys, SymbolicZero) else bar.ys + + def replay_trial(t, y, h, f): + if linearization is None: + return _trial_step(backward_rhs, t, y, h, parameters, f, *constants), () + return _trial_with_residuals(linearize, t, y, h, f, constants, initial_cache) + + def reverse_step(carry, y, t, endpoint, increments, cache): + i, by, bf, bp = carry + i = i-1 + h = tape.step_sizes[i] + fraction = jnp.where(i == tape.count-1, tape.fraction, 1.) + end_time = jnp.where(i == tape.count-1, tape.final_time, t+h) + owned = (ts > t) & (ts <= end_time) + sample_fractions = jnp.where(owned, (ts-t)/h, 0.) + def cached_pullback(index, seed): + return rhs_pullback(tree_util.tree_map(lambda buffer: buffer[index], cache), seed) + dy, df, dp = _step_pullback(backward_rhs, y, t, h, endpoint, increments, parameters, + fraction, sample_fractions, owned, by, bf, saved_bar, method, + initial_fsal=(i == 0), cached_pullback=None if linearization is None else cached_pullback) + contribution = setup_pullback(dp)[0] if parameter_accumulation == "step" else dp + return i, dy, df, _add(bp, contribution) + + def reverse_segment(carry): + end = carry[0] + segment = jnp.maximum((end-1) // checkpoint_steps, 0) + start = segment*checkpoint_steps + y, f = tape.states[segment], tape.derivatives[segment] + t = tape.times[segment] + if checkpoint_steps == 1: + trial, cache = replay_trial(t, y, tape.step_sizes[start], f) + return reverse_step(carry, y, t, trial.y, trial.increments, cache) + + # Reconstruct the segment once. Cache RK stage vectors and compact + # RHS reductions; field-sized arrays are rematerialized. + # Rejections and adaptation are absent from this RK reverse replay. + states = jnp.zeros((checkpoint_steps, initial.size), initial.dtype) + endpoints = jnp.zeros_like(states) + increments = jnp.zeros((checkpoint_steps, len(constants[2]), initial.size), initial.dtype) + times = jnp.zeros((checkpoint_steps,), initial.dtype) + cache = tree_util.tree_map(lambda r: jnp.zeros( + (checkpoint_steps, len(constants[2]))+r.shape, r.dtype), initial_cache) + def reconstruct(local): + i, t, y, f, states, endpoints, increments, times, cache = local + slot = i-start + states = states.at[slot].set(y) + times = times.at[slot].set(t) + h = tape.step_sizes[i] + trial, residuals = replay_trial(t, y, h, f) + cache = tree_util.tree_map(lambda buffer, r: buffer.at[slot].set(r), cache, residuals) + endpoints = endpoints.at[slot].set(trial.y) + increments = increments.at[slot].set(trial.increments) + # An event can only terminate the last accepted step. Its + # full endpoint is harmless here: no later slot consumes it. + return i+1, t+h, trial.y, trial.f1, states, endpoints, increments, times, cache + _, _, _, _, states, endpoints, increments, times, cache = lax.while_loop( + lambda local: local[0] < end, reconstruct, + (start, t, y, f, states, endpoints, increments, times, cache)) + def local_reverse(local): + index = local[0]-1-start + return reverse_step(local, states[index], times[index], endpoints[index], increments[index], + tree_util.tree_map(lambda buffer: buffer[index], cache)) + return lax.while_loop(lambda local: local[0] > start, local_reverse, carry) + + def reverse(carry): + if parameter_accumulation == "step": + return reverse_segment(carry) + # Preparation's pullback is linear in these cotangents. Sum them + # locally before applying it; the outer carry still stores only + # active raw-parameter bars, never a full-trajectory field tape. + i, by, bf, bp = carry + i, dy, df, dp = reverse_segment((i, by, bf, _zeros(parameters))) + return i, dy, df, _add(bp, setup_pullback(dp)[0]) + + _, by, bf, bp = lax.while_loop(lambda carry: carry[0] > 0, reverse, + (tape.count, terminal_bar, jnp.zeros_like(initial), _zeros(active))) + by = by+jnp.sum(jnp.where((sample_indices < tape.initial_saves)[:, None], saved_bar, 0.), axis=0) + iterator = iter(bp) + raw_bar = tree_util.tree_unflatten(raw_structure, + [next(iterator) if flag else _zeros(value) for value, flag in zip(raw_leaves, activity.flags)]) + derivatives = (by, raw_bar, _zeros(controls)) + return eqx.error_if(derivatives, tape.status > RKStatus.EVENT, + "accepted-step AD requires a successful/event solve; inspect status and max_steps") + + integrate.defvjp(fwd, bwd, symbolic_zeros=True) + return integrate(y0, raw_parameters, controls) + + +def replay_accepted(rhs, y0, args, tape, ts, *, method='dopri8', stage_execution='loop'): + """Independent JVP/FD oracle: propagate new inputs on the frozen grid.""" + tape = tree_util.tree_map(lax.stop_gradient, tape) + dense = _rk45_dense if method == 'dopri5' else _dopri8_dense + constants = (_C, _A, _ERROR) if method == 'dopri5' else (_C8, _A8, _ERROR8) + trial_step = _select_trial_step(stage_execution) + ts = lax.stop_gradient(jnp.asarray(ts)) + y0 = jnp.asarray(y0) + t0 = tape.times[0] + saved = jnp.where((jnp.arange(len(ts)) < tape.initial_saves)[:,None],y0,jnp.inf) + def step(c): + i,t,y,f,saved=c + h=tape.step_sizes[i] + trial=trial_step(rhs,t,y,h,args,f,*constants) + end=jnp.where(i==tape.count-1,tape.final_time,t+h) + fraction=jnp.where(i==tape.count-1,tape.fraction,1.) + owned=(ts>t)&(ts<=end) + fractions=jnp.where(owned,(ts-t)/h,0.) + values=jax.vmap(lambda s:dense(y,trial.y,trial.increments,s))(fractions) + return i+1,t+h,dense(y,trial.y,trial.increments,fraction),trial.f1,jnp.where(owned[:,None],values,saved) + _,_,y,_,saved=lax.while_loop(lambda c:c[0] SplitStatus.EVENT, + "accepted split AD requires a successful/event solve; inspect status and work limits"), + (tape.count > tape.times.shape[0], + "accepted split AD capacity exceeded; increase adjoint_max_accepted_steps"), + (tape.orbit_count > tape.orbit_times.shape[0], + "accepted orbit AD capacity exceeded; increase adjoint_max_orbit_steps")): + checked = eqx.error_if(checked, condition, message) + return tape._replace(count=checked) if compact else checked + + +def _partition(function, *examples): + """Expose closure parameters and hoist parameter-only kernel preparation.""" + graph, shape = jax.make_jaxpr(function, return_shape=True)(*examples) + structure = tree_util.tree_structure(shape) + setup, stage = _partition_graph(graph, [True] * len(examples)) + + def prepare(raw): + return jax.core.eval_jaxpr(setup.jaxpr, raw[0]), raw[1] + + def evaluate(arguments, parameters): + residuals, constants = parameters + out = jax.core.eval_jaxpr(stage.jaxpr, constants, *residuals, *arguments) + return tree_util.tree_unflatten(structure, out) + + return (setup.consts, stage.consts), prepare, evaluate + + +def _state_projection(prepare, evaluate, raw, *examples): + """Prune collision error-only inputs before transposing parameter setup. + + The forward driver still evaluates the complete production CollisionStep. + Reverse replay uses its state result only. Selecting live prepared inputs + here avoids differentiating error-only preparation, including expressions + whose derivatives can be singular even when the physical kick is regular. + """ + parameters = prepare(raw) + leaves = tree_util.tree_leaves(parameters) + graph = jax.make_jaxpr(lambda arguments,p:evaluate(arguments,p).y)(examples,parameters) + nargs = len(tree_util.tree_leaves(examples)) + state_graph, used = partial_eval.dce_jaxpr(graph.jaxpr,[True], + instantiate=[True]*nargs+[False]*len(leaves)) + live = used[nargs:] + + def prepare_state(values): + return tuple(value for value,flag in zip(tree_util.tree_leaves(prepare(values)),live) if flag) + + def state(arguments,values): + return jax.core.eval_jaxpr(state_graph,graph.consts,*tree_util.tree_leaves(arguments),*values)[0] + + return prepare_state,state + + +def _orbit_replay(rhs, initial, parameters, tape, index, method, stage_execution="loop"): + """Forward-only oracle; propagate new physical inputs on the frozen grid.""" + trial_step = _select_trial_step(stage_execution) + constants = (_C, _A, _ERROR) if method == "dopri5" else (_C8, _A8, _ERROR8) + dense = _rk45_dense if method == "dopri5" else _dopri8_dense + start, end = tape.offsets[index], tape.offsets[index+1] + f = rhs(tape.orbit_times[start, 0], initial, parameters) + + def step(local): + i, y, f = local + t, h = tape.orbit_times[i] + trial = trial_step(rhs, t, y, h, parameters, f, *constants) + fraction = jnp.where(i == end-1, tape.fractions[index], 1.) + terminal = dense(y, trial.y, trial.increments, fraction) + return i+1, terminal, trial.f1 + + _, final, _ = lax.while_loop( + lambda local: local[0] < end, step, (start, initial, f)) + return final + + +def replay_accepted_split(rhs, collision, initial, args, tape, ts, *, method="dopri8", stage_execution="loop"): + """Forward-only frozen-schedule/noise oracle for finite-difference checks. + + New parameters propagate through every orbit and collision map. Recorded + checkpoint states are deliberately ignored. No adaptation or noise drawing + occurs. Returns (saved_states, terminal_state); ordinary JVPs are supported. + """ + tape = _checked_tape(tree_util.tree_map(lax.stop_gradient, tape)) + ts = lax.stop_gradient(jnp.asarray(ts)) + rhs_bound = lambda t, y, unused: rhs(t, y, args) + + def advance(local): + index, y, saved = local + y = _orbit_replay(rhs_bound, y, None, tape, index, method, stage_execution) + t, end = tape.times[index] + y = lax.cond(tape.kicks[index], + lambda y: collision(end, y, end-t, tape.increments[index], args).y, + lambda y: y, y) + owned = (ts > t) & (ts <= end) + return index+1, y, jnp.where(owned[:, None], y, saved) + + _, final, saved = lax.while_loop(lambda local: local[0] < tape.count, advance, + (jnp.array(0), initial, jnp.broadcast_to(initial, (len(ts), initial.size)))) + saved = jnp.where((jnp.arange(len(ts)) >= tape.saved_count)[:, None], final, saved) + return saved, final + + +def solve_accepted_split(rhs, collision, y0, args=None, **options): + """Attach a discrete reverse rule to the unchanged production split solve.""" + forward_override = options.pop('_forward_override',None) + # Kernels receive prepared numerical parameters internally. Control + # callbacks retain the user's original args ABI, while their numerical + # decisions are frozen by the outer custom VJP. + if options.get("event") is not None: + options["event"] = tree_util.tree_map( + lambda function: lambda t,y,unused,**kw: function(t,y,args,**kw), options["event"]) + if options.get("step_limit") is not None: + step_limit = options["step_limit"] + options["step_limit"] = lambda t,y,unused: step_limit(t,y,args) + y0 = jnp.asarray(y0, dtype=jnp.result_type(y0, float)) + t0 = lax.stop_gradient(jnp.asarray(options.get("t0", 0.), y0.dtype)) + ts = lax.stop_gradient(jnp.asarray(options["ts"], y0.dtype)) + h0 = jnp.asarray(options["dt0"], y0.dtype) + noise = jnp.zeros((options["noise_dim"],), y0.dtype) + raw_rhs, prepare_rhs, evaluate_rhs = _partition(lambda t, y: rhs(t, y, args), t0, y0) + raw_collision, prepare_collision, evaluate_collision = _partition( + lambda t, y, h, dw: collision(t, y, h, dw, args), t0, y0, h0, noise) + prepare_collision_state, collision_state = _state_projection( + prepare_collision,evaluate_collision,raw_collision,t0,y0,h0,noise) + + def prepare(raw): + return prepare_rhs(raw[0]), prepare_collision(raw[1]) + + def orbit_rhs(t, y, parameters): + return evaluate_rhs((t, y), parameters) + + # Components omitted from a stored endpoint must be copied unchanged by + # the collision map. This metadata selects compact full-orbit storage; + # generic maps and GC retain their previous layout. + collision_indices = options.get("_collision_state_indices") + forward_options = dict(options) + if collision_indices is not None: + # _partition already hoisted all parameter-only RHS preparation. + forward_options["_orbit_rhs_prepared"] = True + + def forward(initial, parameters): + if forward_override is not None: + # The independent recorder supplies the same accepted tape ABI. + # Its numerical inputs are closure-converted into frozen controls; + # physical bars still flow through raw_rhs/raw_collision below. + return forward_override(initial,parameters,record=True) + return solve_split(lambda t, y, p: orbit_rhs(t, y, p[0]), + lambda t, y, h, dw, p: evaluate_collision((t, y, h, dw), p[1]), + initial, parameters, **forward_options, _recorder=_SplitRecorder.from_options(initial, forward_options)) + + raw = (raw_rhs, raw_collision) + converted_forward, driver_constants = _convert_all(forward, y0, prepare(raw)) + controls = (driver_constants, ts) + outer_segment = int(options.get("adjoint_checkpoint_steps", 16)) + inner_segment = int(options.get("adjoint_orbit_checkpoint_steps", 16)) + workspace = min(options.get("max_orbit_steps", 10_000), + options.get("adjoint_max_orbit_steps") or options.get("max_steps", 100_000)) + method = options.get("method", "dopri8") + constants = (_C, _A, _ERROR) if method == "dopri5" else (_C8, _A8, _ERROR8) + + @jax.custom_vjp + def integrate(initial, raw, controls): + return converted_forward((initial, prepare(raw)), controls[0])[0] + + def fwd(initial, raw, controls): + activity = _ParameterActivity(tuple(leaf.perturbed for leaf in tree_util.tree_leaves(raw))) + initial, raw, controls = custom_vjp_primal_tree_values((initial, raw, controls)) + out, tape = converted_forward((initial, prepare(raw)), controls[0]) + saved_controls = (None,controls[1]) if forward_override is not None else controls + return out, (initial, raw, saved_controls, tape, activity, + out.y if collision_indices is not None else None) + + def bwd(residual, bar): + initial, raw, controls, tape, activity, final = residual + tape = _checked_tape(tape, compact=collision_indices is not None) + raw_leaves, raw_structure = tree_util.tree_flatten(raw) + active = tuple(value for value, flag in zip(raw_leaves, activity.flags) if flag) + + def active_raw(values): + iterator = iter(values) + return tree_util.tree_unflatten(raw_structure, + [next(iterator) if flag else value for value, flag in zip(raw_leaves, activity.flags)]) + + backward_prepare, backward_rhs = prepare_reverse_rhs( + prepare_rhs, orbit_rhs, t0, initial, raw[0]) + rp, rhs_setup_pullback = jax.vjp( + lambda values: backward_prepare(active_raw(values)[0]), active) + rhs_flags=_prepared_activity(lambda values:backward_prepare(active_raw(values)[0]),active) + original_rhs=backward_rhs + backward_rhs=lambda t,y,p:original_rhs(t,y,_freeze_fixed(p,rhs_flags)) + linearization = prepare_rhs_linearization(backward_rhs, t0, initial, rp) + if linearization is not None: + linearize, rhs_pullback, initial_cache = linearization + else: + initial_cache = () + csp, collision_setup_pullback = jax.vjp( + lambda values:prepare_collision_state(active_raw(values)[1]),active) + collision_flags=_prepared_activity(lambda values:prepare_collision_state(active_raw(values)[1]),active) + backward_collision_state=lambda arguments,p:collision_state(arguments,_freeze_fixed(p,collision_flags)) + ts = controls[1] + saved_bar = jnp.zeros((len(ts), initial.size), initial.dtype) if isinstance(bar.ys, SymbolicZero) else bar.ys + terminal_bar = jnp.zeros_like(initial) if isinstance(bar.y, SymbolicZero) else bar.y + terminal_bar += jnp.sum(jnp.where((jnp.arange(len(ts)) >= tape.saved_count)[:, None], saved_bar, 0.), axis=0) + + def reverse_map(carry, initial): + index, by, bp, post = carry + index -= 1 + offset = tape.checkpoint_offsets[index] + # The next map's initial state is this map's post-collision state. + # Restore only changed components to obtain the pre-collision state. + orbit_end = (tape.orbit_endpoints[index] if collision_indices is None else + post.at[jnp.asarray(collision_indices)].set(tape.orbit_endpoints[index])) + count = (workspace+inner_segment-1)//inner_segment + rows = offset+jnp.arange(count) + # Padded rows are never read by the bounded inner reverse loop. + if collision_indices is None: + checkpoints = (tape.orbit_states[rows],tape.orbit_derivatives[rows]) + else: + # One first derivative per preceding interval is omitted. + derivative_rows = offset-index+jnp.arange(max(count-1,0)) + checkpoints = (tape.orbit_states[rows],tape.orbit_derivatives[derivative_rows]) + t, end = tape.times[index] + by += jnp.sum(jnp.where(((ts > t) & (ts <= end))[:, None], saved_bar, 0.), axis=0) + + def kick_reverse(values): + by, bp = values + _, pullback = jax.vjp(lambda y, values: backward_collision_state( + (end, y, end-t, tape.increments[index]),values),orbit_end,csp) + dy, dp = pullback(by) + return dy, (bp[0],_add(bp[1],dp)) + + by, bp = lax.cond(tape.kicks[index], kick_reverse, lambda values: values, (by, bp)) + orbit_start, orbit_stop = tape.offsets[index], tape.offsets[index+1] + states, derivatives = checkpoints + # Each collision starts a new orbit: its initial FSAL cache must + # use this map's state, not the trajectory's original birth state. + if collision_indices is None: + map_initial_cache = (linearize(tape.orbit_times[orbit_start, 0], initial)[1] + if linearization is not None else ()) + elif linearization is not None: + map_initial_value, map_initial_cache = linearize(tape.orbit_times[orbit_start, 0], initial) + else: + map_initial_value = backward_rhs(tape.orbit_times[orbit_start, 0], initial, rp) + map_initial_cache = () + + def reverse_orbit_segment(local): + stop, by, bf, bp = local + segment = jnp.maximum((stop-orbit_start-1) // inner_segment, 0) + start = orbit_start + segment*inner_segment + y = states[segment] + if collision_indices is None: + f = derivatives[segment] + else: + f = (jnp.where(segment == 0, map_initial_value, derivatives[jnp.maximum(segment-1,0)]) + if derivatives.shape[0] else map_initial_value) + state_bank = jnp.zeros((inner_segment, initial.size), initial.dtype) + endpoint_bank = jnp.zeros_like(state_bank) + increment_bank = jnp.zeros((inner_segment, len(constants[2]), initial.size), initial.dtype) + cache_bank = tree_util.tree_map(lambda value: jnp.zeros( + (inner_segment, len(constants[2]))+value.shape, value.dtype), initial_cache) + + def reconstruct(values): + i, y, f, state_bank, endpoint_bank, increment_bank, cache_bank = values + slot = i-start + t, h = tape.orbit_times[i] + if linearization is None: + trial = _trial_step(backward_rhs, t, y, h, rp, f, *constants) + residuals = () + else: + trial, residuals = _trial_with_residuals( + linearize, t, y, h, f, constants, map_initial_cache) + cache_bank = tree_util.tree_map( + lambda buffer,value: buffer.at[slot].set(value), cache_bank, residuals) + return (i+1, trial.y, trial.f1, state_bank.at[slot].set(y), + endpoint_bank.at[slot].set(trial.y), increment_bank.at[slot].set(trial.increments), + cache_bank) + + _, _, _, state_bank, endpoint_bank, increment_bank, cache_bank = lax.while_loop( + lambda values: values[0] < stop, reconstruct, + (start, y, f, state_bank, endpoint_bank, increment_bank, cache_bank)) + + def reverse_step(values): + i, by, bf, dp = values + i -= 1 + slot = i-start + t, h = tape.orbit_times[i] + fraction = jnp.where(i == orbit_stop-1, tape.fractions[index], 1.) + def cached_pullback(stage, seed): + return rhs_pullback(tree_util.tree_map( + lambda buffer: buffer[slot, stage], cache_bank), seed) + dy, df, contribution = _step_pullback(backward_rhs, state_bank[slot], t, h, + endpoint_bank[slot], increment_bank[slot], rp, fraction, + jnp.empty((0,), initial.dtype), jnp.empty((0,), bool), + by, bf, jnp.empty((0, initial.size), initial.dtype), method, + initial_fsal=(i == orbit_start), + cached_pullback=cached_pullback if linearization is not None else None) + return i, dy, df, _add(dp, contribution) + + # Share the orbit-only segment policy: transpose parameter + # preparation once after summing the segment's prepared bars. + i, by, bf, dp = lax.while_loop(lambda values: values[0] > start, reverse_step, + (stop, by, bf, _zeros(rp))) + return i, by, bf, (_add(bp[0],rhs_setup_pullback(dp)[0]),bp[1]) + + _, by, _, bp = lax.while_loop(lambda values: values[0] > orbit_start, + reverse_orbit_segment, (orbit_stop, by, jnp.zeros_like(initial), bp)) + return index, by, bp, initial if collision_indices is not None else None + + def reverse(carry): + stop = carry[0] + segment = jnp.maximum((stop-1) // outer_segment, 0) + start = segment*outer_segment + def reverse_recorded(values): + index = values[0]-1 + initial = (jnp.where(tape.offsets[index+1]>tape.offsets[index], + tape.orbit_states[tape.checkpoint_offsets[index]],tape.orbit_endpoints[index]) + if collision_indices is None else tape.orbit_states[tape.checkpoint_offsets[index]]) + return reverse_map(values,initial) + return lax.while_loop(lambda values: values[0]>start,reverse_recorded,carry) + + _, by, bp, _ = lax.while_loop(lambda values: values[0] > 0, reverse, + (tape.count, terminal_bar, (_zeros(active),_zeros(csp)), final)) + has_kick = jnp.any((jnp.arange(tape.kicks.size) < tape.count) & tape.kicks) + collision_bar = lax.cond(has_kick,lambda _:collision_setup_pullback(bp[1])[0], + lambda _:_zeros(active),None) + bp = _add(bp[0],collision_bar) + by += jnp.sum(jnp.where((jnp.arange(len(ts)) < tape.initial_saves)[:, None], saved_bar, 0.), axis=0) + iterator = iter(bp) + raw_bar = tree_util.tree_unflatten(raw_structure, + [next(iterator) if flag else _zeros(value) for value, flag in zip(raw_leaves, activity.flags)]) + # Independent GPU preparation is frozen controller/forward data. + # A symbolic zero prunes its entire setup transpose. Materialized + # zero arrays can otherwise retain a second coil-geometry pullback. + return by, raw_bar, None if forward_override is not None else _zeros(controls) + + integrate.defvjp(fwd, bwd, symbolic_zeros=True) + return integrate(y0, raw, controls) + + +class _OrbitRecorder: + """Sparse states/FSAL plus accepted time sizes; never record a rejection.""" + def __init__(self, capacity, segment, schedule=False): + self.capacity, self.segment, self.schedule = capacity, segment, schedule + _validate_ad_sizes(capacity=capacity, segment=segment) + + def initialize(self, state): + y = state['y']; nodes = (self.capacity+self.segment-1)//self.segment + state.update(ad_states=jnp.zeros((nodes,y.size),y.dtype), + ad_derivatives=jnp.zeros((nodes,y.size),y.dtype), + ad_times=jnp.zeros((nodes,),y.dtype), ad_steps=jnp.zeros((self.capacity,),y.dtype), + ad_fraction=jnp.ones((),y.dtype)) + if self.schedule: + state['ad_schedule']=jnp.zeros((self.capacity,2),y.dtype) + return state + + def record(self, previous, updated, t, y, h, fraction, accept): + i=previous['accepted'] + def store(state): + def checkpoint(state): + slot=i//self.segment + return dict(state,ad_states=state['ad_states'].at[slot].set(y), + ad_derivatives=state['ad_derivatives'].at[slot].set(previous['f']), + ad_times=state['ad_times'].at[slot].set(t)) + state=lax.cond(i%self.segment==0,checkpoint,lambda s:s,state) + state=dict(state,ad_steps=state['ad_steps'].at[i].set(h),ad_fraction=fraction) + if self.schedule: + state['ad_schedule']=state['ad_schedule'].at[i].set(jnp.stack([t,h])) + return state + return lax.cond(accept&(i=saved_count[...], saved(i), zero8) + gp = tuple(jnp.zeros_like(value) for value in geom) + cp = jnp.zeros((1 << (ncoeff-1).bit_length(),), jnp.float64) + fp = zero + row_indices = jnp.arange(16)[:, None] + def reverse_map(carry): + index, by, gp, cp, fp, post = carry + index -= 1 + t, end = tref[index, 0], tref[index, 1] + for i in range(nsave): + by += jnp.where((tsref[i]>t)&(tsref[i]<=end), saved(i), zero8) + offset = nodes[index] + map_initial = read_state(states, offset) + endpoint = (read_state(endpoints, index) if gc else + pack(tuple(scalar(post, i) for i in range(3))+ + tuple(endpoints[index, i] for i in range(3))+(zero, zero))) + def kick_reverse(values): + by, gp, cp, fp = values + dw = tuple(dwref[index, j] for j in range(noise_dim)) + result = evaluate(kick_pb.jaxpr, kick_constants, *at(endpoint), *geom, + *cvalues, floor_value, end-t, *dw, *at(by), scalarize=True) + by = pack(result[:8]) + gp = tuple(a+b for a, b in zip(gp, result[8:8+nfield])) + first_constant=8+nfield + cp += pack(tuple(jnp.asarray(v).reshape(()) for v in result[first_constant:first_constant+ncoeff]) + +(zero,)*(cp.shape[0]-ncoeff)) + fp += result[first_constant+ncoeff].reshape(()) + return by, gp, cp, fp + by, gp, cp, fp = jax.lax.cond(kicks[index], kick_reverse, lambda values: values, (by, gp, cp, fp)) + orbit_start, orbit_stop = offsets[index], offsets[index+1] + def reverse_segment(local): + stop, by, bf, gp = local + segment = (stop-orbit_start-1)//segment_steps + start = orbit_start+segment*segment_steps + y = read_state(states, offset+segment) + f, cache = rhs(y) + def reconstruct(values): + i, y, f, cache = values + h = otime[i, 1] + bank = jnp.where(row_indices==0, h*f[None, :], jnp.zeros((16, 8), jnp.float64)) + cache_bank = jnp.where(row_indices==0, cache[None,:], jnp.zeros((16,cache_width),jnp.float64)) + def stage(j, values): + bank, f, cache_bank, cache = values + point = y+jnp.sum(jnp.where(row_indicesstart, reverse_step, (stop, by, bf, gp)) + _, by, _, gp = jax.lax.while_loop(lambda values: values[0]>orbit_start, + reverse_segment, (orbit_stop, by, zero8, gp)) + return index, by, gp, cp, fp, map_initial + post = yref[...] + _, by, gp, cp, fp, _ = jax.lax.while_loop(lambda values: values[0]>0, reverse_map, + (countref[...], by, gp, cp, fp, post)) + for i in range(nsave): + by += jnp.where(i= 0 if name == "rtol" else value > 0) + if not bool(valid): + raise ValueError(f"orbit {name} must be finite and {'nonnegative' if name == 'rtol' else 'positive'}") + + def __call__(self, y0, y1, error): + del y0 # Reference scales do not depend on the coordinate origin. + if self.position_map is None: + position_error = error[:3] + else: + position_error = self.position_map(y1) - self.position_map(y1 - error) + velocity_error = error[3:3 + self.velocity_components] + budget = jnp.asarray(self.atol) + jnp.asarray(self.rtol) + normalized = jnp.concatenate([position_error / (budget * self.length_scale), + velocity_error / (budget * self.speed_scale)]) + value = orbit_block_norm(normalized, self.velocity_components) + valid = ((self.length_scale > 0) & jnp.isfinite(self.length_scale) & + (self.speed_scale > 0) & jnp.isfinite(self.speed_scale) & + (self.rtol >= 0) & (self.atol > 0) & jnp.isfinite(budget) & + jnp.isfinite(y1).all() & jnp.isfinite(error).all() & jnp.isfinite(value)) + return jnp.where(valid, value, jnp.inf) + +# Runge-Kutta stages and portable driver + +class RKStatus(IntEnum): + SUCCESS = 0 + EVENT = 1 + MAX_STEPS = 2 + MIN_STEP = 3 + NONFINITE = 4 + INVALID_INPUT = 5 + + +class RKStep(NamedTuple): + y: jax.Array + error: jax.Array + stages: jax.Array + + +class _RKTrial(NamedTuple): + """Forward-driver stages k=h*f, with the unscaled FSAL value separate.""" + y: jax.Array + error: jax.Array + increments: jax.Array + f1: jax.Array + + +class RKStats(NamedTuple): + steps: jax.Array + accepted: jax.Array + rejected: jax.Array + + +class RKSolution(NamedTuple): + ts: jax.Array + ys: jax.Array + t: jax.Array + y: jax.Array + status: jax.Array + event_mask: object + stats: RKStats + step_ts: jax.Array + next_dt: object = None + + +# Dormand--Prince stages, with Shampine's embedded error estimator (1986). +# These constants also allow direct comparison with Diffrax's Dopri5. +_C = (1 / 5, 3 / 10, 4 / 5, 8 / 9, 1., 1.) +_A = ( + (1 / 5,), + (3 / 40, 9 / 40), + (44 / 45, -56 / 15, 32 / 9), + (19372 / 6561, -25360 / 2187, 64448 / 6561, -212 / 729), + (9017 / 3168, -355 / 33, 46732 / 5247, 49 / 176, -5103 / 18656), + (35 / 384, 0., 500 / 1113, 125 / 192, -2187 / 6784, 11 / 84), +) +_ERROR = (35 / 384 - 1951 / 21600, 0., 500 / 1113 - 22642 / 50085, + 125 / 192 - 451 / 720, -2187 / 6784 + 12231 / 42400, + 11 / 84 - 649 / 6300, -1 / 60) +_MID = (6025192743 / 30085553152 / 2, 0., 51252292925 / 65400821598 / 2, + -2691868925 / 45128329728 / 2, 187940372067 / 1594534317056 / 2, + -1776094331 / 19743644256 / 2, 11237099 / 235043384 / 2) + +# Prince--Dormand (1981) 8(7), including the final FSAL derivative. +_C8 = (1/18, 1/12, 1/8, 5/16, 3/8, 59/400, 93/200, + 5490023248/9719169821, 13/20, 1201146811/1299019798, 1., 1., 1.) +_A8 = ( + (1/18,), + (1/48, 1/16), + (1/32, 0., 3/32), + (5/16, 0., -75/64, 75/64), + (3/80, 0., 0., 3/16, 3/20), + (29443841/614563906, 0., 0., 77736538/692538347, -28693883/1125000000, 23124283/1800000000), + (16016141/946692911, 0., 0., 61564180/158732637, 22789713/633445777, + 545815736/2771057229, -180193667/1043307555), + (39632708/573591083, 0., 0., -433636366/683701615, -421739975/2616292301, + 100302831/723423059, 790204164/839813087, 800635310/3783071287), + (246121993/1340847787, 0., 0., -37695042795/15268766246, -309121744/1061227803, + -12992083/490766935, 6005943493/2108947869, 393006217/1396673457, 123872331/1001029789), + (-1028468189/846180014, 0., 0., 8478235783/508512852, 1311729495/1432422823, + -10304129995/1701304382, -48777925059/3047939560, 15336726248/1032824649, + -45442868181/3398467696, 3065993473/597172653), + (185892177/718116043, 0., 0., -3185094517/667107341, -477755414/1098053517, + -703635378/230739211, 5731566787/1027545527, 5232866602/850066563, + -4093664535/808688257, 3962137247/1805957418, 65686358/487910083), + (403863854/491063109, 0., 0., -5068492393/434740067, -411421997/543043805, + 652783627/914296604, 11173962825/925320556, -13158990841/6184727034, + 3936647629/1978049680, -160528059/685178525, 248638103/1413531060, 0.), + (14005451/335480064, 0., 0., 0., 0., -59238493/1068277825, 181606767/758867731, + 561292985/797845732, -1041891430/1371343529, 760417239/1151165299, + 118820643/751138087, -528747749/2220607170, 1/4), +) +_ERROR8 = (14005451/335480064 - 13451932/455176623, 0., 0., 0., 0., + -59238493/1068277825 + 808719846/976000145, + 181606767/758867731 - 1757004468/5645159321, + 561292985/797845732 - 656045339/265891186, + -1041891430/1371343529 + 3867574721/1518517206, + 760417239/1151165299 - 465885868/322736535, + 118820643/751138087 - 53011238/667516719, -528747749/2220607170 - 2/45, 1/4, 0.) +# Bogacki--Shampine (1990) continuous extension, in descending powers, followed +# by an overall factor s. These mathematical coefficients match Dopri8. +_DENSE8 = ( + (-6.3448349392860401388, 22.1396504998094068976, -30.0610568289666450593, + 19.9990069333683970610, -6.6910181737837595697, 1.), + (0., 0., 0., 0., 0., 0.), + (0., 0., 0., 0., 0., 0.), + (0., 0., 0., 0., 0., 0.), + (0., 0., 0., 0., 0., 0.), + (-39.6107919852202505218, 116.4422149550342161651, -121.4999627731334642623, + 52.2273532792945524050, -7.6142658045872677172, 0.), + (20.3761213808791436958, -67.1451318825957197185, 83.1721004639847717481, + -46.8919164181093621583, 10.7281392630428866124, 0.), + (7.3347098826795362023, -16.5672243527496524646, 9.5724507555993664382, + -.1890893225010595467, .5526637063753648783, 0.), + (32.8801774352459155182, -89.9916014847245016028, 87.8406057677205645007, + -35.7075975946222072821, 4.2186562625665153803, 0.), + (-10.1588990526426760954, 22.6237489648532849093, -17.4152107770762969005, + 6.2736448083240352160, -.6627209125361597559, 0.), + (-12.5401268098782561200, 32.2362340167355370113, -28.5903289514790976966, + 10.3160881272450748458, -1.2636789001135462218, 0.), + (29.5553001484516038033, -82.1020315488359848644, 81.6630950584341412934, + -34.7650769866611817349, 5.4106037898590422230, 0.), + (-41.7923486424390588923, 116.2662185791119533462, -114.9375291377009418170, + 47.7457971078225540396, -7.0321379067945741781, 0.), + (20.3006925822100825485, -53.9020777466385396792, 50.2558364226176017553, + -19.0082099341608028453, 2.3537586759714983486, 0.), +) + + +def _rk_step(rhs, t, y, h, args, f0, nodes, rows, error_weights): + # Keep the differentiable numerical map independent of retries/controller + # state. Zero tableau entries create no dependencies in the accepted map. + stages = [rhs(t, y, args) if f0 is None else f0] + for c, weights in zip(nodes, rows): + trial = y + h * sum(a * k for a, k in zip(weights, stages) if a != 0) + stages.append(rhs(t + c * h, trial, args)) + # For both FSAL tableaus the final stage is evaluated at the solution. + error = h * sum(a * k for a, k in zip(error_weights, stages) if a != 0) + return RKStep(trial, error, jnp.stack(stages)) + + +def rk45_step(rhs, t, y, h, args=None, *, f0=None): + """One DP5(4) trial step. ``stages`` contains derivatives, not h*f. + + Pass the last derivative of the previous *accepted* step as ``f0`` for + FSAL reuse. Rejected trials must leave that cached derivative unchanged. + """ + return _rk_step(rhs, t, y, h, args, f0, _C, _A, _ERROR) + + +def dopri8_step(rhs, t, y, h, args=None, *, f0=None): + """One DP8(7) trial step, with the same FSAL contract as rk45_step.""" + return _rk_step(rhs, t, y, h, args, f0, _C8, _A8, _ERROR8) + + +def _trial_step(rhs, t, y, h, args, f0, nodes, rows, error_weights): + """The same explicit RK formula, storing increments for the forward driver. + + A static stage loop supports ordinary JAX forward/reverse derivatives. + Only k is carried; the final FSAL evaluation is outside the loop and is + kept unscaled, so cache reuse and h=0 derivatives need no division by h. + Both particle models use this map without a physics-specific branch. + """ + f0 = rhs(t, y, args) if f0 is None else f0 + n = len(error_weights) + coefficients = np.zeros((n - 2, n - 1)) + for i, row in enumerate(rows[:-1]): + coefficients[i, :len(row)] = row + coefficients = jnp.asarray(coefficients, dtype=y.dtype) + times = jnp.asarray(nodes[:-1], dtype=y.dtype) + endpoint_weights = jnp.asarray(rows[-1], dtype=y.dtype) + bank = jnp.concatenate([(h * f0)[None], jnp.zeros((n - 2,) + y.shape, y.dtype)]) + + def stage(i, bank): + point = y + jnp.tensordot(coefficients[i - 1], bank, axes=1) + increment = h * rhs(t + times[i - 1] * h, point, args) + return lax.dynamic_update_index_in_dim(bank, increment, i, axis=0) + + bank = lax.fori_loop(1, n - 1, stage, bank) + endpoint = y + jnp.tensordot(endpoint_weights, bank, axes=1) + final = rhs(t + h, endpoint, args) + error = jnp.tensordot(jnp.asarray(error_weights[:-1], dtype=y.dtype), bank, axes=1) + if error_weights[-1] != 0: + error = error + error_weights[-1] * (h * final) + increments = jnp.concatenate([bank, (h * final)[None]]) + return _RKTrial(endpoint, error, increments, final) + + +def _trial_unrolled(rhs, t, y, h, args, f0, nodes, rows, weights): + """Explicit component arithmetic exposes independent operations to XLA.""" + increments = [tuple(h * value for value in f0)] + for node, row in zip(nodes, rows): + point = tuple(value + sum(a*k[i] for a,k in zip(row,increments) if a) + for i,value in enumerate(y)) + final = tuple(rhs(t+node*h, jnp.stack(point), args)) + increments.append(tuple(h*value for value in final)) + error = tuple(sum(a*k[i] for a,k in zip(weights,increments) if a) for i in range(len(y))) + return _RKTrial(jnp.stack(point), jnp.stack(error), + jnp.stack(tuple(jnp.stack(k) for k in increments)), jnp.stack(final)) + + +def rk45_interpolate(y0, h, step, fraction): + """Quartic dense output on an accepted step, for 0 <= fraction <= 1.""" + return _rk45_dense(y0, step.y, h * step.stages, fraction) + + +def _rk45_dense(y0, y1, k, fraction): + delta = y1 - y0 + midpoint = jnp.tensordot(jnp.asarray(_MID, dtype=y0.dtype), k, axes=1) + # Interpolate the endpoints, endpoint derivatives, and Shampine midpoint. + a = 2 * (k[-1] - k[0]) - 8 * delta + 16 * midpoint + b = 5 * k[0] - 3 * k[-1] + 14 * delta - 32 * midpoint + c = k[-1] - 4 * k[0] - 5 * delta + 16 * midpoint + s = fraction + value = y0 + s * (k[0] + s * (c + s * (b + s * a))) + return jnp.where(s == 0, y0, jnp.where(s == 1, y1, value)) + + +def dopri8_interpolate(y0, h, step, fraction): + """Dopri8 continuous extension on a trial step, for 0 <= fraction <= 1.""" + return _dopri8_dense(y0, step.y, h * step.stages, fraction) + + +def _dopri8_dense(y0, y1, k, fraction): + coefficients = jnp.asarray(_DENSE8, dtype=y0.dtype) + weights = jax.vmap(jnp.polyval, in_axes=(0, None))(coefficients, fraction) * fraction + value = y0 + jnp.tensordot(weights, k, axes=1) + return jnp.where(fraction == 0, y0, jnp.where(fraction == 1, y1, value)) + + +def _concrete_check(value, predicate, message): + if not isinstance(value, jax.core.Tracer) and not predicate(np.asarray(value)): + raise ValueError(message) + + +def _prepare_rhs(rhs, t0, y0, args): + """Separate solve-invariant work from the time/state-dependent RHS. + + Time and the whole state are unknown to this JAX partial evaluation. + Parameter-only expressions are evaluated once per solve and passed to + every stage. They remain JAX values with ordinary parameter derivatives; + nothing is stopped, converted to NumPy, or stored on the field object. + Both orbit models use the same preparation and the original RHS. + + Keep this use of JAX's partial-evaluation interface isolated here. The + resulting setup/stage graphs execute ordinary JAX primitives, including + when enclosed by jit, vmap, JVP or VJP. + """ + graph = jax.make_jaxpr(lambda t, y: rhs(t, y, args))(t0, y0) + setup, stage, _, _ = partial_eval.partial_eval_jaxpr_nounits( + graph, [True, True], instantiate=True) + residuals = jax.core.eval_jaxpr(setup.jaxpr, setup.consts) + + def evaluate(t, y, unused_args): + return jax.core.eval_jaxpr(stage.jaxpr, stage.consts, *residuals, t, y)[0] + + return evaluate + + +def _first_hit(hits): + """Report one event, using leaf order to break simultaneous-event ties.""" + previous = jnp.asarray(False) + result = [] + for hit in hits: + result.append(hit & ~previous) + previous = previous | hit + return tuple(result) + + +def solve_rk(rhs, y0, args=None, *, t0=0., t1, dt0, ts=(), adaptive=True, + rtol=1e-9, atol=1e-9, event=None, root_find=True, + max_steps=1_000_000, dtmin=0., dtmax=np.inf, record_steps=False, method="dopri5", + error_norm=None, controller="i", pcoeff=.4, icoeff=.3, stage_execution="unrolled", + adjoint="none", adjoint_checkpoint_steps=16, adjoint_max_accepted_steps=None, + adjoint_parameter_accumulation="segment", _recorder=None): + """Integrate an array state forward in time with bounded adaptive retries. + + ``ts`` is an ordered save grid, independent of the integration steps. + Unreached saves are filled with infinity. ``t``/``y`` give the last accepted + state, including a refined event crossing. Level-set events fire on a sign + change (or an initial zero); boolean events fire when true. Event callables + have signature ``event(t, y, args)`` and may form a PyTree. + The earliest event is reported; ties use PyTree leaf order. + An initial event leaves all sampled saves empty, while returning t0/y0 as + the terminal state, matching Diffrax's event/save convention. + + By default a scaled RMS embedded error controls adaptive acceptance. Pass + ``error_norm(y0, y1, embedded_error) -> scalar`` to supply an already scaled + error (acceptance <= 1), for example ``essos.rk.OrbitErrorNorm``. + It affects acceptance and step selection only; it does not alter RK stages. + ``controller="i"`` keeps the original integral controller. ``"pi"`` uses + ``factor = .9 * error**(-(icoeff+pcoeff)/q) * previous_error**(pcoeff/q)``, + where q is the embedded error order and history changes only on acceptance. + PI defaults to p=.4, i=.3, with accepted growth bounded to [1, 10] and + rejected growth to [.2, .9], for comparison with ESSOS's Diffrax PI settings. + Fixed stepping + uses ``dt0`` (bounded by dtmax and t1), and still supplies dense output/events. + ``max_steps`` counts accepted and rejected trials. Failures return a status; + no inaccurate step is forced through a minimum step-size limit. + + By default memory holds only the save grid and current step. Opt into an + infinity-padded accepted-time history with ``record_steps=True``; its first + ``stats.accepted + 1`` entries are valid. This is diagnostic data for future + accepted-step inspection. ``adjoint="accepted"`` separately enables the + checkpointed reverse rule in ``essos.native_ad``. Its accepted times, event + fractions and controller decisions are frozen; stages and dense output + retain their physical derivatives. + + Concrete invalid inputs raise ValueError. Invalid dynamic values under JIT + return INVALID_INPUT. Non-finite states, derivatives or event values are + rejected, with NONFINITE returned when no smaller trial can proceed. + + ``method`` selects ``"dopri5"`` or ``"dopri8"``. The convenience entry points + ``solve_rk45`` and ``solve_dopri8`` fix this choice. + """ + if adjoint not in ('none','accepted'): + raise ValueError("adjoint must be 'none' or 'accepted'") + if adjoint == 'accepted': + options=locals().copy() + from .native_ad import solve_accepted + for name in ('rhs','y0','args','adjoint','_recorder'): + options.pop(name) + return solve_accepted(rhs,y0,args,**options) + if stage_execution not in ("loop", "unrolled"): + raise ValueError("stage_execution must be 'loop' or 'unrolled'") + trial_step = _trial_step if stage_execution == "loop" else _trial_unrolled + if method == "dopri5": + nodes, rows, weights, dense, error_order = _C, _A, _ERROR, _rk45_dense, 5 + elif method == "dopri8": + nodes, rows, weights, dense, error_order = _C8, _A8, _ERROR8, _dopri8_dense, 8 + else: + raise ValueError("method must be 'dopri5' or 'dopri8'") + if controller not in ("i", "pi"): + raise ValueError("controller must be 'i' or 'pi'") + if controller == "pi": + for value, name, positive in ((pcoeff, "pcoeff", False), (icoeff, "icoeff", True)): + if jnp.asarray(value).ndim != 0: + raise ValueError(f"{name} must be scalar") + _concrete_check(value, lambda x: np.isfinite(x) & ((x > 0) if positive else (x >= 0)), + f"{name} must be finite and {'positive' if positive else 'nonnegative'}") + def interpolate(y, h, trial, fraction): + return dense(y, trial.y, trial.increments, fraction) + if isinstance(max_steps, (bool, np.bool_)) or not isinstance(max_steps, (int, np.integer)) or max_steps <= 0: + raise ValueError("max_steps must be a positive integer") + y0 = jnp.asarray(y0) + y0 = y0.astype(jnp.result_type(y0, float)) + if y0.ndim != 1 or not y0.size: + raise ValueError("y0 must be a nonempty one-dimensional array") + if not jnp.issubdtype(y0.dtype, jnp.floating): + raise ValueError("y0 must contain real values") + ts = jnp.asarray(ts, dtype=y0.dtype) + if ts.ndim != 1: + raise ValueError("ts must be one-dimensional") + for value, name in ((t0, "t0"), (t1, "t1"), (dt0, "dt0"), (dtmin, "dtmin"), (dtmax, "dtmax")): + if jnp.asarray(value).ndim != 0: + raise ValueError(f"{name} must be scalar") + for value, name in ((dt0, "dt0"), (dtmax, "dtmax")): + _concrete_check(value, lambda x: np.all(x > 0), f"{name} must be positive") + _concrete_check(dt0, np.isfinite, "dt0 must be finite") + _concrete_check(t0, np.isfinite, "t0 must be finite") + _concrete_check(t1, np.isfinite, "t1 must be finite") + _concrete_check(dtmin, lambda x: np.isfinite(x) & (x >= 0), "dtmin must be finite and nonnegative") + _concrete_check(rtol, lambda x: np.all(np.isfinite(x) & (x >= 0)), "rtol must be finite and nonnegative") + _concrete_check(atol, lambda x: np.all(np.isfinite(x) & (x > 0)), "atol must be finite and positive") + _concrete_check(jnp.asarray(t1) - t0, lambda x: np.isfinite(x) & (x >= 0), "t1 must be finite and >= t0") + _concrete_check(ts, lambda x: np.all(np.isfinite(x)) and np.all(np.diff(x) >= 0), "ts must be finite and ordered") + _concrete_check(jnp.asarray(dtmax) - dtmin, lambda x: x >= 0, "dtmax must be >= dtmin") + _concrete_check(jnp.asarray(dt0) - dtmin, lambda x: x >= 0, "dt0 must be >= dtmin") + _concrete_check((ts >= t0) & (ts <= t1), np.all, "ts must lie in [t0, t1]") + t0, t1, h0 = (jnp.asarray(v, dtype=y0.dtype) for v in (t0, t1, dt0)) + # Comparisons made above may be tracers, so retain runtime validation too. + # For ordinary Tracing calls these constants are folded out by XLA. + valid_input = (jnp.isfinite(t0) & jnp.isfinite(t1) & (t1 >= t0) & + jnp.isfinite(h0) & (h0 > 0) & jnp.isfinite(dtmin) & (dtmin >= 0) & + (dtmax > 0) & (dtmax >= dtmin) & (h0 >= dtmin) & + jnp.all(jnp.isfinite(jnp.asarray(rtol)) & (jnp.asarray(rtol) >= 0)) & + jnp.all(jnp.isfinite(jnp.asarray(atol)) & (jnp.asarray(atol) > 0)) & + jnp.all(jnp.isfinite(ts) & (ts >= t0) & (ts <= t1)) & + jnp.all(jnp.diff(ts) >= 0)) + if controller == "pi": + valid_input = valid_input & jnp.isfinite(pcoeff) & (pcoeff >= 0) & jnp.isfinite(icoeff) & (icoeff > 0) + functions, structure = tree_util.tree_flatten(event) + + def events(t, y): + values = tuple(jnp.asarray(f(t, y, args)) for f in functions) + if any(v.shape != () or (v.dtype != jnp.bool_ and not jnp.issubdtype(v.dtype, jnp.floating)) for v in values): + raise ValueError("events must return scalar booleans or floating-point level sets") + return values + + def finite_events(values): + return jnp.all(jnp.asarray(tuple(jnp.isfinite(v) for v in values), dtype=bool)) + + values0 = events(t0, y0) + initial_hits = _first_hit(tuple(v if v.dtype == jnp.bool_ else v == 0 for v in values0)) + hit0 = jnp.any(jnp.asarray(initial_hits, dtype=bool)) + status0 = jnp.where(valid_input, + jnp.where(jnp.isfinite(y0).all() & finite_events(values0), + jnp.where(hit0, RKStatus.EVENT, RKStatus.SUCCESS), RKStatus.NONFINITE), + RKStatus.INVALID_INPUT) + rhs = _prepare_rhs(rhs, t0, y0, args) + state = dict(t=t0, y=y0, h=jnp.minimum(h0, dtmax), f=rhs(t0, y0, args), + values=values0, hits=initial_hits, status=status0, + ys=jnp.full((len(ts),) + y0.shape, jnp.inf, dtype=y0.dtype), + saved_ts=jnp.full(ts.shape, jnp.inf, dtype=ts.dtype), + index=jnp.array(0), steps=jnp.array(0), accepted=jnp.array(0), rejected=jnp.array(0), + history=jnp.full((max_steps + 1 if record_steps else 0,), jnp.inf, dtype=y0.dtype)) + if adaptive and controller == "pi": + state["previous_error"] = jnp.ones((), dtype=y0.dtype) + if record_steps: + state["history"] = state["history"].at[0].set(t0) + + def save_initial(s): + if not len(ts): + return s + def body(s): + i = s["index"] + return dict(s, ys=s["ys"].at[i].set(y0), saved_ts=s["saved_ts"].at[i].set(t0), index=i + 1) + return lax.while_loop(lambda s: ~hit0 & (s["index"] < len(ts)) & + (ts[jnp.minimum(s["index"], len(ts) - 1)] == t0), body, s) + + state = save_initial(state) + initial_saves = state["index"] + if _recorder is not None: + state = _recorder.initialize(state) + + def advance(s): + t, y = s["t"], s["y"] + remaining = t1 - t + if adaptive: + h = jnp.minimum(s["h"], remaining) + # Snap a roundoff-sized remainder instead of taking a tiny extra step. + h = jnp.where(remaining - h <= 8 * jnp.finfo(y.dtype).eps * + jnp.maximum(jnp.abs(t1), jnp.abs(t)), remaining, h) + end_t = jnp.where(h == remaining, t1, t + h) + else: + # Derive fixed times from the step index: repeatedly adding h0 can + # leave a tiny remainder even when the interval is exactly N*h0. + end_t = jnp.minimum(t0 + (s["accepted"] + 1) * jnp.minimum(h0, dtmax), t1) + h = end_t - t + trial = trial_step(rhs, t, y, h, args, s["f"], nodes, rows, weights) + finite = (jnp.isfinite(trial.y).all() & jnp.isfinite(trial.increments).all() & + jnp.isfinite(trial.f1).all() & jnp.isfinite(trial.error).all()) + if adaptive: + if error_norm is None: + scale = jnp.asarray(atol) + jnp.asarray(rtol) * jnp.maximum(jnp.abs(y), jnp.abs(trial.y)) + error = jnp.sqrt(jnp.mean(jnp.square(trial.error / scale))) + else: + error = jnp.asarray(error_norm(y, trial.y, trial.error)) + if error.ndim != 0: + raise ValueError("error_norm must return a scalar") + finite = finite & jnp.isfinite(error) & (error >= 0) + else: + error = jnp.zeros((), dtype=y.dtype) + new_values = events(end_t, trial.y) + finite = finite & finite_events(new_values) + accept = finite & ((error <= 1) | (not adaptive)) & (end_t > t) + triggered = tuple((new if old.dtype == jnp.bool_ else ((old > 0) != (new > 0)) | (new == 0)) & accept + for old, new in zip(s["values"], new_values)) + fractions = [] + valid_roots = [] + for f, old, new, hit in zip(functions, s["values"], new_values, triggered): + if root_find and old.dtype != jnp.bool_: + def bisect(c): + lo, hi, iteration, valid = c + mid = (lo + hi) / 2 + value = f(t + mid * h, interpolate(y, h, trial, mid), args) + same = (value > 0) == (old > 0) + return (jnp.where(same, mid, lo), jnp.where(same, hi, mid), + iteration + 1, valid & jnp.isfinite(value)) + # A while-loop avoids root work on ordinary steps under vmap. + lo, hi, _, valid_root = lax.while_loop(lambda c: hit & c[3] & (c[2] < 52), bisect, + (jnp.zeros_like(t), jnp.ones_like(t), jnp.array(0), jnp.asarray(True))) + fraction = (lo + hi) / 2 + else: + fraction = jnp.ones_like(t) + valid_root = jnp.asarray(True) + fractions.append(jnp.where(hit, fraction, jnp.inf)) + valid_roots.append(valid_root) + finite = finite & jnp.all(jnp.asarray(valid_roots, dtype=bool)) + accept = accept & finite + first = jnp.min(jnp.asarray(fractions)) if fractions else jnp.asarray(jnp.inf, dtype=t.dtype) + has_event = jnp.isfinite(first) & accept + fraction = jnp.minimum(first, 1.) + stop_t = jnp.where(has_event, t + fraction * h, end_t) + stop_y = interpolate(y, h, trial, fraction) + hits = _first_hit(tuple(hit & accept & (fraction_i == first) for hit, fraction_i in zip(triggered, fractions))) + if adaptive and controller == "pi": + # Work in log space so zero errors and clipped factors stay finite. + safe_error = jnp.maximum(jnp.where(finite, error, 1.), jnp.finfo(y.dtype).tiny) + log_factor = (jnp.log(.9) - (icoeff + pcoeff) / error_order * jnp.log(safe_error) + + pcoeff / error_order * jnp.log(s["previous_error"])) + factor = jnp.exp(jnp.clip(log_factor, jnp.log(jnp.where(accept, 1., .2)), + jnp.log(jnp.where(accept, 10., .9)))) + proposed = h * jnp.where(finite, factor, .2) + else: + # Preserve the original I-controller, including its growth limits. + factor = jnp.where(finite, jnp.clip(.9 * jnp.maximum(error, 1e-16)**(-1/error_order), .2, 5.), .2) + proposed = h * jnp.where(accept, factor, jnp.minimum(factor, .9)) if adaptive else h0 + next_h = jnp.clip(proposed, dtmin, dtmax) + stuck = (end_t <= t) | (~accept & ((h <= dtmin) | (t + next_h <= t))) + if not adaptive: + stuck = stuck | ~finite + status = jnp.where(has_event, RKStatus.EVENT, + jnp.where(stuck, jnp.where(finite, RKStatus.MIN_STEP, RKStatus.NONFINITE), RKStatus.SUCCESS)) + updated = dict(s, t=jnp.where(accept, stop_t, t), y=jnp.where(accept, stop_y, y), h=next_h, + f=jnp.where(accept, trial.f1, s["f"]), + values=tuple(jnp.where(accept, new, old) for old, new in zip(s["values"], new_values)), + hits=hits, status=status, steps=s["steps"] + 1, + accepted=s["accepted"] + accept.astype(int), rejected=s["rejected"] + (~accept).astype(int)) + if adaptive and controller == "pi": + # Zero errors use neutral history; rejected trials retain the last + # accepted error, including after a non-finite trial. + history_error = jnp.where(error >= jnp.finfo(y.dtype).tiny, safe_error, 1.) + updated["previous_error"] = jnp.where(accept, history_error, s["previous_error"]) + if record_steps: + updated["history"] = lax.cond(accept, lambda history: history.at[updated["accepted"]].set(stop_t), + lambda history: history, s["history"]) + if len(ts): + def save(s): + i = s["index"] + value = interpolate(y, h, trial, (ts[i] - t) / h) + return dict(s, ys=s["ys"].at[i].set(value), saved_ts=s["saved_ts"].at[i].set(ts[i]), index=i + 1) + updated = lax.while_loop(lambda s: accept & (s["index"] < len(ts)) & + (ts[jnp.minimum(s["index"], len(ts) - 1)] <= stop_t), save, updated) + if _recorder is not None: + updated = _recorder.record(s, updated, t, y, h, fraction, accept) + return updated + + state = lax.while_loop(lambda s: (s["t"] < t1) & (s["status"] == RKStatus.SUCCESS) & + (s["steps"] < max_steps), advance, state) + status = jnp.where((state["t"] < t1) & (state["status"] == RKStatus.SUCCESS), RKStatus.MAX_STEPS, state["status"]) + solution = RKSolution(state["saved_ts"], state["ys"], state["t"], state["y"], status, + tree_util.tree_unflatten(structure, state["hits"]), + RKStats(state["steps"], state["accepted"], state["rejected"]), state["history"], state["h"]) + return solution if _recorder is None else _recorder.finish(state, solution, initial_saves) + + +def solve_rk45(rhs, y0, args=None, **kwargs): + """Dormand--Prince 5(4); see solve_rk for integration options and results.""" + return solve_rk(rhs, y0, args, method="dopri5", **kwargs) + + +def solve_dopri8(rhs, y0, args=None, **kwargs): + """Dormand--Prince 8(7); see solve_rk for integration options and results.""" + return solve_rk(rhs, y0, args, method="dopri8", **kwargs) + +# GPU field access and JAX compatibility + +def _padded_spline(knots, coefficients): + """Power-of-two kernel view of the same piecewise cubics. + + End extrapolation is expressed about the last knot. Recentring and a + different reduction order can introduce ordinary floating-point changes. + This setup is outside jit and intended for fixed, nondifferentiated fields. + """ + knots, coefficients = np.asarray(knots), np.asarray(coefficients) + count = len(knots) + size = 1 << (count-1).bit_length() + width = 1 << (coefficients.shape[1]-1).bit_length() + grid = np.full(size, np.inf) + grid[:count] = knots + values = np.zeros((size, width, 4)) + values[:count-1, :coefficients.shape[1]] = coefficients + a, b, c, d = np.moveaxis(coefficients[-1], -1, 0) + h = knots[-1]-knots[-2] + shifted = np.stack((a, b+3*a*h, c+2*b*h+3*a*h*h, ((a*h+b)*h+c)*h+d), axis=-1) + values[count-1:, :coefficients.shape[1]] = shifted + return jnp.asarray(grid), jnp.asarray(values) + + +def _select_one(value, index, axis): + """Bit-preserving scalar/slice selection on a kernel-local array.""" + shape = [1]*value.ndim + shape[axis] = value.shape[axis] + mask = jnp.arange(value.shape[axis]).reshape(shape) == index + dtype = {8: jnp.uint64, 4: jnp.uint32, 2: jnp.uint16, 1: jnp.uint8}[value.dtype.itemsize] + bits = jax.lax.bitcast_convert_type(value, dtype) + selected = jnp.max(jnp.where(mask, bits, jnp.zeros_like(bits)), axis=axis, keepdims=True) + return jax.lax.bitcast_convert_type(selected, value.dtype) + + +def _kernel_is_finite(value): + """Exact IEEE finite test using primitives supported by older Pallas. + + JAX 0.7.2's Triton backend cannot lower lax.is_finite. Inspecting the + exponent preserves NaN/infinity rejection without changing the RHS guard. + Integer bit operations also avoid assumptions about fast float comparisons. + """ + if value.dtype == jnp.float64: + unsigned, exponent = jnp.uint64, 0x7ff0000000000000 + elif value.dtype == jnp.float32: + unsigned, exponent = jnp.uint32, 0x7f800000 + else: + raise TypeError("The fused trial finite guard supports float32/float64") + bits = jax.lax.bitcast_convert_type(value, unsigned) + mask = jnp.asarray(exponent, dtype=unsigned) + return jax.lax.bitwise_and(bits, mask) != mask + + +class _KernelField: + """Kernel-local Ref adapter; evaluation uses the original field methods.""" + table = sine_coef = None + def modB_derivatives(self, *args): + from .boozer import BoozerField + return BoozerField.modB_derivatives(self, *args) + + def __init__(self, refs, psi0): + radial, b, flux, profiles, xm, xn = refs + self.r_knots, self.b_coef = radial[...], b + self.s_knots, self.profile_coef = flux[...], profiles + self.xm, self.xn, self.psi0 = xm[...], xn[...], psi0 + + def profiles(self, s): + from .boozer import BoozerField + value, slope = BoozerField.profiles(self, s) + return tuple(value[i] for i in range(3)), tuple(slope[i] for i in range(3)) + + +def _kernel_rhs(model, y0, moment, mass, charge): + """Lower the original checked RHS; adapt unsupported local-array indexing.""" + from .boozer import guiding_center_rhs, _chart + + def physical(y): + value = guiding_center_rhs(model, y, moment, mass, charge) + _, r, theta, *_ = _chart(y) + B = model.modB_derivatives(r, theta, y[2])[0] + return jnp.where(jnp.isfinite(B) & (B > 0), value, jnp.nan) + + original = jax.make_jaxpr(physical)(y0) + flat = jax.make_jaxpr(lambda y: _evaluate_inline(original.jaxpr, original.consts, y)[0])(y0) + + def evaluate(y): + graph = flat.jaxpr + env = dict(zip(graph.constvars, flat.consts)) + env.update(zip(graph.invars, (y,))) + def read(v): + return v.val if isinstance(v, Literal) else env[v] + for equation in graph.eqns: + values = [read(v) for v in equation.invars] + name = equation.primitive.name + if name == "slice": + value = values[0] + for axis, (start, end, size) in enumerate(zip(equation.params["start_indices"], + equation.params["limit_indices"], value.shape)): + if start != 0 or end != size: + if end-start != 1: + raise ValueError("Unsupported kernel-local RHS slice") + value = _select_one(value, start, axis) + result = [value] + elif name == "dynamic_slice": + value = values[0] + for axis, (index, size, wanted) in enumerate(zip(values[1:], value.shape, + equation.params["slice_sizes"])): + if size != wanted: + if wanted != 1: + raise ValueError("Unsupported kernel-local dynamic RHS slice") + value = _select_one(value, jnp.clip(index, 0, size-1), axis) + result = [value] + elif name == "concatenate" and len(values) > 2: + value = jnp.zeros((len(values),), values[0].dtype) + for i, v in enumerate(values): + value = jnp.where(jnp.arange(len(values)) == i, jnp.reshape(v, ()), value) + result = [value] + elif name == "le_to": + # Positive finite knots followed by +inf; NaN queries sort last. + result = [jnp.less_equal(values[0], values[1]) | jnp.isnan(values[1])] + elif name == "is_finite": + result = [_kernel_is_finite(values[0])] + else: + result = _bind_primitive(equation.primitive, values, equation.params) + if not equation.primitive.multiple_results: + result = [result] + env.update(zip(equation.outvars, result)) + return read(graph.outvars[0]) + return evaluate + + + +def _bind_primitive(primitive, values, parameters): + """Bind an equation using either supported JAX get_bind_params ABI. + + Older JAX returns (subfunctions, keyword_parameters); newer JAX returns + only keyword_parameters. Keep legacy subfunctions for opaque AD/call + primitives rather than discarding them while adapting ordinary equations. + This Python dispatch runs during graph preparation, not each RK stage. + """ + binding = primitive.get_bind_params(parameters) + if isinstance(binding, tuple): + subfunctions, binding = binding + return primitive.bind(*subfunctions, *values, **binding) + return primitive.bind(*values, **binding) + + +def _evaluate_inline(graph, constants, *arguments): + """Expose jit boundaries without entering custom AD/control-flow calls.""" + from jax.extend.core import Literal + environment = dict(zip(graph.constvars, constants)) + environment.update(zip(graph.invars, arguments)) + + def read(var): + return var.val if isinstance(var, Literal) else environment[var] + + for equation in graph.eqns: + values = [read(var) for var in equation.invars] + if equation.primitive.name in ("jit", "pjit"): + nested = equation.params["jaxpr"] + result = _evaluate_inline(nested.jaxpr, nested.consts, *values) + else: + result = _bind_primitive(equation.primitive, values, equation.params) + if not equation.primitive.multiple_results: + result = [result] + environment.update(zip(equation.outvars, result)) + return [read(var) for var in graph.outvars] + +# Private Biot-Savart GPU view + +def _cross(a,b): + return a[1]*b[2]-a[2]*b[1],a[2]*b[0]-a[0]*b[2],a[0]*b[1]-a[1]*b[0] + + +def _dot(a,b): + return sum(x*y for x,y in zip(a,b)) + + +def _pack(values): + result = jnp.zeros((len(values),),values[0].dtype) + index = jnp.arange(len(values)) + for i,value in enumerate(values): + result = jnp.where(index==i,value,result) + return result + + +def _fourier_geometry(curves,second=False): + """Evaluate the existing Fourier DOFs with exact basis contractions. + + Avoids GPU miscompilation of fused gather/padding pullbacks, including + coil-length gradients. No curve reparameterization or derivative estimate. + """ + q=curves.quadpoints;basis=[jnp.ones_like(q)];derivative=[jnp.zeros_like(q)] + twice=[jnp.zeros_like(q)] + for mode in range(1,curves.order+1): + w=2*jnp.pi*mode;phase=w*q;s,c=jnp.sin(phase),jnp.cos(phase) + basis.extend((s,c));derivative.extend((w*c,-w*s)) + if second:twice.extend((-w*w*s,-w*w*c)) + return tuple(jnp.einsum('ncm,mq->nqc',curves.curves,jnp.stack(a)) + for a in ((basis,derivative,twice) if second else (basis,derivative))) + + +def _coil_geometry(field): + from .coils import Curves + curves=getattr(field.coils,'curves',None) + if isinstance(curves,Curves): + gamma,tangent=_fourier_geometry(curves) + else: + gamma,tangent=field.coils.gamma,field.coils.gamma_dash + current=field.coils.currents + nc,nq,_ = gamma.shape + pc,pq = (1<<(size-1).bit_length() for size in (nc,nq)) + weight = current*1e-7 + index=jnp.arange(pc*pq);row,column=index%pc,index//pc + valid=(row 0, np.maximum(k-2, -1), 0) + powers.append(k) + arrays.append(_pad_vmec(k, (width,))) + definitions = dict(field._NYQUIST) + definitions.update(rmnc=(False, {}, True), zmns=(False, {}, False)) + tables = {} + for name, (half_grid, options, cosine) in definitions.items(): + geometry = name in ('rmnc', 'zmns') + power_index = 2 if geometry else 1 if name == 'bsubsmns' else 0 + k = powers[power_index] + width = widths[1 if geometry else 0] + grid = grids[int(half_grid)] + pieces = [] + for partner, is_cosine in ((name, cosine), (VMEC_WOUT_PARTNERS[name], not cosine)): + table = getattr(field, partner) + if table is None: + continue + table = np.asarray(table)[1:] if half_grid else np.asarray(table) + scaled = table / np.where(grid > 0, grid, 1.)[:, None]**(k/2) + if not half_grid: + m = np.asarray(field.xm if geometry else field.xm_nyq).astype(int) + scaled[0] = np.where(m > 0, 2*scaled[1]-scaled[2], scaled[0]) + if name == 'bsubsmns': + axis = field._bsubs_axis_m1(partner != name) + if axis is not None: + scaled[0] = np.where(m == 1, np.asarray(axis), scaled[0]) + slope = np.asarray(_vmec_radial_slopes(jnp.asarray(scaled))) + index = len(arrays) + arrays.extend((_pad_vmec(scaled, (radial_width, width)), + _pad_vmec(slope, (radial_width, width)))) + pieces.append((index, index+1, int(half_grid), len(grid), 6+power_index, + 4 if geometry else 2, is_cosine)) + tables[name] = tuple(pieces) + return _VmecData(tuple(arrays), tables) + + + + +def _vmec_scalar(value,index): + return _select_one(value,index,0).reshape(()) + + +def _vmec_chart(y): + u, w = _vmec_scalar(y, 0), _vmec_scalar(y, 1) + s = u*u+w*w + theta = jnp.mod(jnp.arctan2(w, u)+_vmec_scalar(y, 4), 2*jnp.pi) + return s, jnp.where(_kernel_is_finite(s), theta, s), _vmec_scalar(y, 2) + + +def _vmec_radial(refs, s, metadata): + values, slopes, grid_index, count, power_index, _, _ = metadata + grid, k = refs[grid_index], refs[power_index][...] + ds = grid[1]-grid[0] + i = jnp.clip(jnp.floor((s-grid[0])/ds).astype(jnp.int32), 0, count-2) + u = (s-grid[i])/ds + a, b = refs[values][i, :], refs[values][i+1, :] + da, db = refs[slopes][i, :], refs[slopes][i+1, :] + + from .fields import _vmec_radial_segment + + interpolated, derivative = jax.jvp( + lambda v: _vmec_radial_segment(v, a, b, da, db), (u,), (jnp.ones_like(u),), + ) + derivative = derivative / ds + + def power(value): + q = jnp.sqrt(jnp.maximum(value, jnp.finfo(value.dtype).tiny)) + return jnp.where(k == -1, 1/q, jnp.where(k == 0, 1., + jnp.where(k == 1, q, jnp.where(k == 2, q*q, q*q*q)))) + + factor, dfactor = jax.jvp(power, (s,), (jnp.ones_like(s),)) + return factor*interpolated, dfactor*interpolated+factor*derivative + + +def _vmec_series(refs, point, pieces): + s, theta, phi = point + total = None + for metadata in pieces: + mode_index, cosine = metadata[-2:] + m, n = refs[mode_index][...], refs[mode_index+1][...] + angle = m*theta-n*phi + cos, sin = jnp.cos(angle), jnp.sin(angle) + f, df = _vmec_radial(refs, s, metadata) + if cosine: + value = (jnp.sum(f*cos), (jnp.sum(df*cos), -jnp.sum((m*f)*sin), jnp.sum((n*f)*sin))) + else: + value = (jnp.sum(f*sin), (jnp.sum(df*sin), jnp.sum((m*f)*cos), -jnp.sum((n*f)*cos))) + total = value if total is None else (total[0]+value[0], tuple(a+b for a, b in zip(total[1], value[1]))) + return total + + +def _vmec_quantities(refs, point, tables): + values = {name: _vmec_series(refs, point, tables[name]) for name in + ('bmnc', 'gmnc', 'bsubsmns', 'bsubumnc', 'bsubvmnc', 'bsupumnc', 'bsupvmnc')} + magnitude, gradient = values['bmnc'] + sqrtg = values['gmnc'][0] + covariant = tuple(values[name][0] for name in ('bsubsmns', 'bsubumnc', 'bsubvmnc')) + zero = magnitude*0 + contravariant = zero, values['bsupumnc'][0], values['bsupvmnc'][0] + jac = tuple(values[name][1] for name in ('bsubsmns', 'bsubumnc', 'bsubvmnc')) + curl = tuple(value/sqrtg for value in + (jac[2][1]-jac[1][2], jac[0][2]-jac[2][0], jac[1][0]-jac[0][1])) + correction = _cross(covariant, gradient) + curl_b = tuple(curl[i]/magnitude+correction[i]/magnitude**2/sqrtg for i in range(3)) + curvature = tuple(-value*sqrtg/magnitude for value in _cross(contravariant, curl_b)) + return covariant, contravariant, magnitude, gradient, curl_b, curvature, sqrtg + + +def _vmec_rhs_values(refs, y, tables, mass, charge, energy, moment=None): + point = _vmec_chart(y) + covariant, contravariant, magnitude, gradient, curl_b, curvature, sqrtg = _vmec_quantities(refs, point, tables) + vpar = _vmec_scalar(y, 3) + moment = (energy-mass*vpar**2/2)/magnitude if moment is None else moment + star = tuple(contravariant[i]+vpar*mass/charge*curl_b[i] for i in range(3)) + force = tuple(moment*gradient[i]+mass*vpar**2*curvature[i] for i in range(3)) + denominator = _dot(covariant, star) + perpendicular = _cross(covariant, force) + velocity = tuple(vpar*contravariant[i]/magnitude+perpendicular[i]/denominator/charge/sqrtg + for i in range(3)) + acceleration = -_dot(star, force)/denominator*magnitude/mass + u, w, s = _vmec_scalar(y, 0), _vmec_scalar(y, 1), point[0] + half = jnp.where(s > 0, .5/jnp.where(s > 0, s, 1.), 0.) + c = s/(s+1e-2) + zero = jnp.asarray(0., y.dtype) + return _pack((u*half*velocity[0]-(1-c)*w*velocity[1], + w*half*velocity[0]+(1-c)*u*velocity[1], velocity[2], acceleration, + c*velocity[1], zero, zero, zero)) + + +def _vmec_xyz_values(refs, y, tables): + point = _vmec_chart(y) + R = _vmec_series(refs, point, tables['rmnc'])[0] + Z = _vmec_series(refs, point, tables['zmns'])[0] + return R*jnp.cos(point[2]), R*jnp.sin(point[2]), Z + +def _prepare_vmec_gpu(field,mass,charge,energy,speed,times,dt0,rtol,atol,max_steps,*, + method="dopri8",adaptive=True,length_scale=1.,interpret=False): + prepared=_prepare_vmec_data(field) + def factory(refs,point,invariant): + evaluate=lambda y:_vmec_rhs_values(refs,y,prepared.tables,mass,charge,energy) + def estimate(endpoint,error,speed): + high,low=_vmec_xyz_values(refs,endpoint,prepared.tables),_vmec_xyz_values(refs,endpoint-error,prepared.tables) + position=jnp.sqrt(sum((a-b)**2 for a,b in zip(high,low)))/length_scale + return jnp.maximum(position,jnp.abs(_vmec_scalar(error,3))/speed) + return evaluate,estimate,lambda y:1.-_vmec_scalar(y,0)**2-_vmec_scalar(y,1)**2 + # Avoid cross-warp reductions for short spectra; keep parallelism for large ones. + warps = 1 if max(prepared.arrays[2].size, prepared.arrays[4].size) <= 128 else 4 + return _prepare_gpu_solver(prepared.arrays,factory,speed,times,dt0,rtol,atol,max_steps, + state_size=8,method=method,adaptive=adaptive,num_warps=warps,interpret=interpret) + +# Independent GPU particle loops + +def _prepare_gpu_solver(arrays, factory, speed, times, dt0, rtol, atol, max_steps, *, + state_size=4, method="dopri8", adaptive=True, num_warps=1, interpret=False): + """Prepare a CUDA solver outside jit; return solve(y0, invariant). + + Fixed and adaptive Dopri5/8 share FSAL stages and standard dense output. + Adaptive acceptance uses the adapter's error blocks and I control. Save + times do not constrain steps. Each particle stops independently; there is + no particle chunking or compaction. Numerical equivalence is subject to + ordinary floating-point changes from a different compiler execution path. + """ + from jax.experimental import pallas as pl + from jax.experimental.pallas import triton as plt + if method not in ("dopri5", "dopri8"): + raise ValueError("The fused orbit method must be dopri5 or dopri8") + if not interpret and (jax.default_backend() != "gpu" or "cuda" not in jax.devices()[0].client.platform_version.lower()): + raise ValueError("The experimental fused orbit solver requires CUDA") + times = np.asarray(times, dtype=np.float64) + if (times.ndim != 1 or len(times) < 2 or not np.isfinite(times).all() or + times[0] != 0 or times[-1] <= 0 or np.any(np.diff(times) < 0)): + raise ValueError("Save times must be ordered, start at zero and end at a positive time") + if not (np.isfinite(dt0) and dt0 > 0 and np.isfinite(speed) and speed > 0 and + np.isfinite(rtol) and rtol >= 0 and np.isfinite(atol) and atol > 0): + raise ValueError("Require positive finite dt0, speed, atol and finite rtol >= 0") + if (isinstance(max_steps, (bool, np.bool_)) or not isinstance(max_steps, (int, np.integer)) or + not 0 < max_steps <= np.iinfo(np.int32).max): + raise ValueError("max_steps must be a positive int32 work bound") + rows, weights, order = (_A, _ERROR, 5) if method == "dopri5" else (_A8, _ERROR8, 8) + stages = len(weights) + bank_size = 1 << (stages-1).bit_length() + matrix = np.zeros((bank_size, bank_size)) + for i, row in enumerate(rows, 1): + matrix[i, :len(row)] = row + coefficients = jnp.asarray(matrix) + error_weights = jnp.asarray(tuple(weights)+(0.,)*(bank_size-stages)) + if method == "dopri5": + dense_matrix = np.zeros((1, bank_size)) + dense_matrix[0, :stages] = np.asarray(_MID) + else: + dense_matrix = np.zeros((len(_DENSE8[0]), bank_size)) + dense_matrix[:, :stages] = np.asarray(_DENSE8).T + dense_coefficients = jnp.asarray(dense_matrix) + tmax = float(times[-1]) + # Load float64 scalars explicitly. Nested Pallas loops must not infer + # their device scalar precision from weak Python constant initializers. + scalars = jnp.asarray([0., dt0, tmax, 8*np.finfo(np.float64).eps*tmax, + speed, rtol+atol], jnp.float64) + inputs = tuple(arrays)+(coefficients, error_weights, dense_coefficients, jnp.asarray(times), scalars) + nsave = len(times) + + def solve(y0, moment): + if y0.shape != (state_size,) or y0.dtype != jnp.float64: + raise ValueError("The fused orbit solver requires a float64 power-of-two state") + # Validate the birth once with ordinary JAX, outside the persistent + # loop. Invalid inputs must not spend max_steps rejecting NaN trials. + initial_level = jnp.asarray(1., y0.dtype) + initial_status = jnp.where(jnp.isfinite(y0).all() & jnp.isfinite(moment).all() & jnp.isfinite(initial_level), + jnp.where(initial_level == 0, 1, 0), 4).astype(jnp.int32) + + def kernel(yref, mref, initial_status_ref, *refs): + (*field_refs, aref, eref, dref, tsref, paramsref, + ysout, tsout, yout, tout, hout, statsout, statusout) = refs + point = yref[...] + zero, initial_h, final_t, roundoff, particle_speed, budget = (paramsref[i] for i in range(6)) + evaluate, estimate, level = factory(field_refs, point, mref[...]) + + def finite(value): + return jnp.min(_kernel_is_finite(value).astype(jnp.int32)) > 0 + + def save_loop(condition, write, index): + # JAX 0.6 cannot discharge Pallas ref reads in while conditions. + def advance(carry): + index = write(carry[0]) + return index, condition(index) + return jax.lax.while_loop(lambda c: c[1], advance, + (index, condition(index)))[0] + + def dense(y, endpoint, bank, fraction): + if method == "dopri5": + # Same quartic extension as rk._rk45_dense; the padded + # bank's last row is not the final FSAL stage. + first = _select_one(bank, 0, 0).reshape(state_size) + last = _select_one(bank, stages-1, 0).reshape(state_size) + midpoint = jnp.sum(dref[0, :][:, None]*bank, axis=0) + delta = endpoint-y + a = 2*(last-first)-8*delta+16*midpoint + b = 5*first-3*last+14*delta-32*midpoint + c = last-4*first-5*delta+16*midpoint + value = y+fraction*(first+fraction*(c+fraction*(b+fraction*a))) + return jnp.where(fraction == 0, y, jnp.where(fraction == 1, endpoint, value)) + weights = jnp.zeros((bank_size,), point.dtype) + for power in range(dense_matrix.shape[0]): + weights = weights*fraction+dref[power, :] + value = y+jnp.sum((weights*fraction)[:, None]*bank, axis=0) + return jnp.where(fraction == 0, y, jnp.where(fraction == 1, endpoint, value)) + + def clear(i, _): + ysout[i, :] = jnp.full((state_size,), jnp.inf, point.dtype) + tsout[i] = tsref[0]+jnp.inf + return () + + jax.lax.fori_loop(0, nsave, clear, ()) + initial_level = level(point) + status = jnp.where(_kernel_is_finite(initial_level), + jnp.where(initial_level == 0, 1, initial_status_ref[...]), 4).astype(jnp.int32) + + def initial_save(i): + ysout[i, :] = point + tsout[i] = zero + return i+1 + + index = save_loop(lambda i: (status == 0) & (i < nsave) & + (tsref[jnp.minimum(i, nsave-1)] == 0), initial_save, jnp.asarray(0, jnp.int32)) + indexbank = jnp.arange(bank_size)[:, None] + # Time, state, FSAL derivative, proposal, event value, status, + # next save index, trials, accepted trials, rejected trials. + # Evaluate the first derivative in the stage loop so the compiler + # sees one RHS body. Cache it even when the first trial is rejected. + initial = (zero, point, jnp.zeros_like(point), initial_h, initial_level, status, index, + jnp.asarray(0, jnp.int32), jnp.asarray(0, jnp.int32), jnp.asarray(0, jnp.int32)) + + def advance(carry): + t, y, f0, next_h, old_value, status, index, trials, accepted, rejected = carry + remaining = final_t-t + h = jnp.minimum(next_h if adaptive else initial_h, remaining) + # 0 <= t <= final_t, so max(abs(t), abs(final_t)) is final_t. + h = jnp.where(remaining-h <= roundoff, remaining, h) + end_t = jnp.where(h == remaining, final_t, t+h) + if not adaptive: + end_t = jnp.minimum((accepted+1)*initial_h, final_t) + h = end_t-t + bank = jnp.where(indexbank == 0, h*f0[None, :], jnp.zeros((bank_size, state_size), point.dtype)) + + def stage(i, stage_carry): + bank, _, first = stage_carry + yi = y+jnp.sum(aref[i, :][:, None]*bank, axis=0) + fi = evaluate(yi) + return jnp.where(indexbank == i, h*fi[None, :], bank), fi, jnp.where(i == 0, fi, first) + + bank, f1, f0 = jax.lax.fori_loop((trials != 0).astype(jnp.int32), np.int32(stages), stage, (bank, f0, f0)) + endpoint = y+jnp.sum(aref[stages-1, :][:, None]*bank, axis=0) + embedded = jnp.sum(eref[...][:, None]*bank, axis=0) + error = estimate(endpoint, embedded, particle_speed)/budget if adaptive else zero + new_value = level(endpoint) + valid = (finite(endpoint) & finite(bank) & finite(f1) & finite(embedded) & + _kernel_is_finite(error) & (error >= 0) & _kernel_is_finite(new_value)) + accept = valid & ((error <= 1) | (not adaptive)) & (end_t > t) + crossing = accept & (((old_value > 0) != (new_value > 0)) | (new_value == 0)) + factor = jnp.where(valid, jnp.clip(.9*jnp.maximum(error, 1e-16)**(-1/order), .2, 5.), .2) + proposed = h*jnp.where(accept, factor, jnp.minimum(factor, .9)) + stuck = (end_t <= t) | (~accept & ((h <= 0) | (t+proposed <= t))) + if not adaptive: + stuck = stuck | ~valid + new_status = jnp.where(stuck, jnp.where(valid, 3, 4), 0).astype(jnp.int32) + + def bisect(root_carry): + lo, hi, i, valid_root = root_carry + mid = (lo+hi)/2 + value = level(dense(y, endpoint, bank, mid)) + same = (value > 0) == (old_value > 0) + return (jnp.where(same, mid, lo), jnp.where(same, hi, mid), i+1, + valid_root & _kernel_is_finite(value)) + + lo, hi, _, valid_root = jax.lax.while_loop(lambda c: crossing & c[3] & (c[2] < 52), + bisect, (zero, zero+1., jnp.asarray(0, jnp.int32), jnp.asarray(True))) + fraction = (lo+hi)/2 + stop_t = jnp.where(crossing, t+fraction*h, end_t) + stop_y = jax.lax.cond(crossing, + lambda _: dense(y, endpoint, bank, fraction), lambda _: endpoint, None) + # A nonfinite interpolant rejects the crossing and retries from + # the previous state with .2*h, matching the deferred root path. + root_invalid = crossing & ~valid_root + accept = accept & ~root_invalid + proposed = jnp.where(root_invalid, .2*h, proposed) + root_stuck = (h <= 0) | (t+proposed <= t) + new_status = jnp.where(crossing & valid_root, 1, + jnp.where(root_invalid, jnp.where(root_stuck, 4, 0), new_status)).astype(jnp.int32) + + def save(i): + ysout[i, :] = dense(y, endpoint, bank, (tsref[i]-t)/h) + tsout[i] = tsref[i] + return i+1 + + index = save_loop(lambda i: accept & (i < nsave) & + (tsref[jnp.minimum(i, nsave-1)] <= stop_t), save, index) + return (jnp.where(accept, stop_t, t), jnp.where(accept, stop_y, y), + jnp.where(accept, f1, f0), proposed, jnp.where(accept, new_value, old_value), + new_status, index, trials+1, accepted+accept.astype(jnp.int32), + rejected+(~accept).astype(jnp.int32)) + + result = jax.lax.while_loop(lambda c: (c[0] < final_t) & (c[5] == 0) & + (c[7] < max_steps), advance, initial) + t, y, _, h, _, status, _, trials, accepted, rejected = result + status = jnp.where((t < final_t) & (status == 0), 2, status) + yout[...], tout[...], hout[...] = y, t, h + statsout[0], statsout[1], statsout[2] = trials, accepted, rejected + statusout[...] = status + + shapes = (jax.ShapeDtypeStruct((nsave, state_size), y0.dtype), jax.ShapeDtypeStruct((nsave,), y0.dtype), + jax.ShapeDtypeStruct((state_size,), y0.dtype), jax.ShapeDtypeStruct((), y0.dtype), + jax.ShapeDtypeStruct((), y0.dtype), jax.ShapeDtypeStruct((3,), jnp.int32), + jax.ShapeDtypeStruct((), jnp.int32)) + ys, saved, y, t, h, counts, status = pl.pallas_call(kernel, out_shape=shapes, grid=(), + interpret=interpret, compiler_params=plt.CompilerParams(num_warps=num_warps))(y0, moment, initial_status, *inputs) + return RKSolution(saved, ys, t, y, status, status == 1, + RKStats(counts[0], counts[1], counts[2]), jnp.zeros((0,), y0.dtype), h) + + solve.method = method + return solve + +# Boozer GPU preparation + +def _prepare_boozer_gpu(field, mass, charge, speed, times, dt0, rtol, atol, max_steps, *, + method="dopri8", adaptive=True, interpret=False): + if field.table is not None or field.sine_coef is not None: + raise ValueError("The CUDA adapter requires a fixed cosine Fourier Boozer field") + radial, b = _padded_spline(field.r_knots, field.b_coef) + flux, profiles = _padded_spline(field.s_knots, field.profile_coef) + modes = b.shape[1] + arrays = (radial, b, flux, profiles, jnp.pad(field.xm, (0,modes-len(field.xm))), + jnp.pad(field.xn, (0,modes-len(field.xn)))) + scalar = lambda y,i: _select_one(y,i,0).reshape(()) + def factory(refs, point, moment): + model = _KernelField(refs, float(field.psi0)) + evaluate = _kernel_rhs(model, point, moment, mass, charge) + def estimate(endpoint, error, speed): + a,b,c,d = (scalar(error,i) for i in range(4)) + return jnp.maximum(jnp.sqrt(a*a+b*b),jnp.maximum(jnp.abs(c),jnp.abs(d)/speed)) + return evaluate, estimate, lambda y: 1.-scalar(y,0)**2-scalar(y,1)**2 + return _prepare_gpu_solver(arrays,factory,speed,times,dt0,rtol,atol,max_steps, + method=method,adaptive=adaptive,interpret=interpret) + +# Existing Tracing integration + +class _ParticleParameters(NamedTuple): + mass: float + charge: float + energy: float + total_speed: float + + +def prepare_solver(field, *, mass, charge, energy, times, dt0, model="gc", method="dopri8", + adaptive=True, rtol=1e-9, atol=1e-9, controller="i", pcoeff=.4, icoeff=.3, + max_steps=1_000_000, length_scale=1., execution="jax", interpret=False): + """Prepare ``solve(state) -> RKSolution`` for fixed-field forward tracing. + + Cartesian GC states are (x,y,z,vpar), Lorentz states (x,y,z,vx,vy,vz). + VMEC GC uses the existing five-component axis-regular chart. VMEC stops + at s=1. The CUDA path uses independent particle programs and I control; + the portable path supports I/PI. Use jit(vmap(solve)) for a batch. + This function prepares fixed fields outside jit. It defines no AD rule. + """ + import numpy as np + from .fields import BiotSavart, Vmec + from .dynamics import GuidingCenter, Lorentz, _axis_regular, _from_axis_regular + from .electric_field import Electric_field_zero + if execution not in ("jax", "cuda") or model not in ("gc", "lorentz"): + raise ValueError("Require execution jax/cuda and model gc/lorentz") + if not all(np.isfinite(v) for v in (mass,charge,energy,length_scale)) or min(mass,energy,length_scale)<=0 or charge==0: + raise ValueError("Require positive finite mass, energy, length_scale and nonzero charge") + speed=float(np.sqrt(2*energy/mass)) + vmec=isinstance(field,Vmec) + if vmec and model!='gc': + raise ValueError("VMEC native integration supports guiding centers") + size=5 if vmec else 4 if model=='gc' else 6 + if execution=='cuda': + if controller!='i': + raise ValueError("CUDA execution supports the I controller") + if vmec: + prepare_orbit_solver = _prepare_vmec_gpu + elif isinstance(field,BiotSavart): + prepare_orbit_solver = _prepare_coils_gpu + else: + raise ValueError("CUDA Cartesian fields must be BiotSavart") + options={} if vmec else dict(model=model) + kernel=prepare_orbit_solver(field,mass,charge,energy,speed,times,dt0,rtol,atol,max_steps, + method=method,adaptive=adaptive,length_scale=length_scale,interpret=interpret,**options) + padded=8 if size in (5,6) else 4 + def solve(y): + result=kernel(jnp.pad(y,(0,padded-size)),jnp.zeros((),y.dtype)) + return result._replace(ys=result.ys[:,:size],y=result.y[:size]) + return solve + particle=_ParticleParameters(mass,charge,energy,speed) + if model=='gc': + rhs=lambda t,y,args:GuidingCenter(t,y,(field,particle,Electric_field_zero())) + rhs=_axis_regular(rhs) if vmec else rhs + else: + rhs=lambda t,y,args:Lorentz(t,y,(field,particle)) + position=(lambda y:field.to_xyz(_from_axis_regular(y)[:3])) if vmec else None + norm=OrbitErrorNorm(rtol,atol,speed,length_scale,1 if model=='gc' else 3,position) + event=(lambda t,y,args:1.-y[0]**2-y[1]**2) if vmec else None + return lambda y:solve_rk(rhs,y,t1=times[-1],dt0=dt0,ts=times,method=method,adaptive=adaptive, + rtol=rtol,atol=atol,error_norm=norm,controller=controller,pcoeff=pcoeff,icoeff=icoeff, + event=event,max_steps=max_steps) + +class _NativeOrbitSolution(NamedTuple): + ys: object + ts: object + event_mask: object + result: object + + +def _configure_tracing(trace, integrator, model, solver, native_error_control, orbit_length_scale, + orbit_speed_scale, native_controller, native_pcoeff, native_icoeff): + if integrator not in ("diffrax", "essos_rk45", "essos_dopri8"): + raise ValueError("integrator must be 'diffrax', 'essos_rk45' or 'essos_dopri8'") + if integrator != "diffrax": + if model not in ('GuidingCenter', 'GuidingCenterAdaptative', 'FullOrbit', 'FullOrbitAdaptative'): + raise ValueError("native integrators currently support collisionless guiding-center and full-orbit models only") + if solver is not None: + raise ValueError("solver selects a Diffrax solver; omit it when using a native integrator") + trace.integrator = integrator + if native_error_control not in ("physics", "standard"): + raise ValueError("native_error_control must be 'physics' or 'standard'") + trace.native_error_control = native_error_control + if native_controller not in ("i", "pi"): + raise ValueError("native_controller must be 'i' or 'pi'") + trace.native_controller, trace.native_pcoeff, trace.native_icoeff = native_controller, native_pcoeff, native_icoeff + trace.orbit_length_scale, trace.orbit_speed_scale = orbit_length_scale, orbit_speed_scale + + +def _trace_error_norm(trace, *, exterior=False, flag=False): + """Physical blocks only; keep coordinates/diagnostics out of the RK map.""" + from .dynamics import _from_axis_regular + if trace.native_error_control == "standard": + return None + position_map = None + if trace._axis_regular and not exterior: + def position_map(y): + state = y[:-1] if flag else y + return trace.field.to_xyz(_from_axis_regular(state)[:3]) + return OrbitErrorNorm( + rtol=trace.rtol, atol=trace.atol, length_scale=trace.orbit_length_scale, + speed_scale=trace.particles.total_speed if trace.orbit_speed_scale is None else trace.orbit_speed_scale, + velocity_components=3 if trace.model.startswith("FullOrbit") else 1, + position_map=position_map) + + +def _solve_tracing(trace, terms, controller, t0, y0, args, event, throw, exterior, flag): + import diffrax + solution = solve_rk( + terms, y0, args, t0=t0, t1=trace.maxtime, dt0=trace.timestep, + ts=jnp.clip(trace.times, t0, trace.maxtime), adaptive=controller, + rtol=trace.rtol, atol=trace.atol, event=event.cond_fn, + root_find=event.root_finder is not None, max_steps=trace.max_steps, + method="dopri8" if trace.integrator == "essos_dopri8" else "dopri5", + error_norm=_trace_error_norm(trace, exterior=exterior, flag=flag), + controller=trace.native_controller, pcoeff=trace.native_pcoeff, icoeff=trace.native_icoeff, + adjoint=trace.native_adjoint, adjoint_checkpoint_steps=trace.native_adjoint_checkpoint_steps, + adjoint_max_accepted_steps=trace.native_adjoint_max_accepted_steps, + adjoint_parameter_accumulation=trace.native_adjoint_parameter_accumulation) + ys = solution.ys + if throw: + import equinox as eqx + ys = eqx.error_if(ys, solution.status > RKStatus.EVENT, "native RK solve failed; inspect solve_rk status/stats") + result = diffrax.RESULTS.where(solution.status == RKStatus.SUCCESS, diffrax.RESULTS.successful, + diffrax.RESULTS.where(solution.status == RKStatus.EVENT, diffrax.RESULTS.event_occurred, + diffrax.RESULTS.max_steps_reached)) + return _NativeOrbitSolution((ys, solution.y[None]), (solution.ts, solution.t[None]), + solution.event_mask, result) + +# Boozer tracing integration + +def _boozer_error_norm(error, speed, rtol, atol): + """Independent flux-radius, toroidal-radian and parallel-speed budgets.""" + return jnp.maximum(jnp.linalg.norm(error[:2]), jnp.maximum( + jnp.abs(error[2]), jnp.abs(error[3])/speed)) / (rtol + atol) + + +def trace_boozer_orbits(field, y0, mu0, mass, charge, speed, times, dt0, rtol, atol, + method, adaptive, controller, pcoeff, icoeff, max_steps, *, execution="jax"): + """Select portable JAX or fixed-field CUDA execution without changing physics. + + CUDA supports fixed steps and adaptive I control for cosine Fourier fields. The portable + path also supports fixed steps, PI control, sine modes and angle tables. + The choice is explicit: no backend, field layout or controller is changed. + """ + if execution not in ("jax", "cuda"): + raise ValueError("native_execution must be 'jax' or 'cuda'") + solver = None + if execution == "cuda": + if controller != "i": + raise ValueError("CUDA native orbits require I control") + prepare_orbit_solver = _prepare_boozer_gpu + solver = prepare_orbit_solver(field, mass, charge, float(speed), times, + dt0, rtol, atol, max_steps, method=method, adaptive=adaptive) + return _boozer_batch(field, y0, mu0, mass, charge, speed, times, dt0, rtol, atol, + method, adaptive, controller, pcoeff, icoeff, max_steps, solver) + + +@partial(jax.jit, static_argnames=("method", "adaptive", "controller", "max_steps", "orbit_solver")) +def _boozer_batch(field, y0, mu0, mass, charge, speed, times, dt0, rtol, atol, + method, adaptive, controller, pcoeff, icoeff, max_steps, orbit_solver=None): + """One shared native RK solve per orbit, independent of the save grid.""" + from .boozer import _chart, guiding_center_rhs + + def one(y0, mu): + def magnetic_field(y): + _, r, theta, *_ = _chart(y) + return field.modB_derivatives(r, theta, y[2])[0] + + def rhs(t, y, args): + del t, args + value = guiding_center_rhs(field, y, mu, mass, charge) + B = magnetic_field(y) + return jnp.where(jnp.isfinite(B) & (B > 0), value, jnp.nan) + + def error_norm(y0, y1, error): + del y0, y1 + # This field supplies |B| and profiles, not a Cartesian embedding. + # Use a unit flux-radius chart, one radian for zeta and birth speed + # for v_parallel. No scale grows with angle winding or vanishes at + # a parallel turning point; these are chart errors, not metres. + return _boozer_error_norm(error, speed, rtol, atol) + + if orbit_solver is None: + solution = solve_rk(rhs, y0, t1=times[-1], dt0=dt0, ts=times, + method=method, adaptive=adaptive, rtol=rtol, atol=atol, + error_norm=error_norm, controller=controller, pcoeff=pcoeff, icoeff=icoeff, + max_steps=max_steps, event=lambda t, y, args: 1. - y[0]**2 - y[1]**2) + else: + solution = orbit_solver(y0, mu) + + def output(y): + s, _, theta, *_ = _chart(y) + B = magnetic_field(y) + energy = .5*y[3]**2 + mu*B + state = jnp.array([s, theta, y[2], y[3], jnp.sqrt(jnp.maximum(2*energy, 0.))]) + valid = jnp.isfinite(state).all() & jnp.isfinite(energy) & (energy > 0) & (B > 0) + return state, energy, valid + + # Hold an orbit at the root-found loss point or last accepted state + # after failure. The solver itself leaves unreached saves infinite. + sampled = jnp.where(jnp.isfinite(solution.ys).all(axis=1)[:, None], solution.ys, solution.y) + values, energies, valid = jax.vmap(output)(sampled) + _, end_energy, end_valid = output(solution.y) + birth, birth_energy, _ = output(y0) + output_failed = ~jnp.all(valid) | ~end_valid + failed = (solution.status > RKStatus.EVENT) | output_failed + lost = (solution.status == RKStatus.EVENT) & ~failed + first_bad = jnp.min(jnp.where(valid, jnp.inf, times)) + failed_time = jnp.minimum(solution.t, first_bad) + + def hold(carry, item): + previous, finite_prefix = carry + value, finite = item + finite_prefix = finite_prefix & finite + previous = jnp.where(finite_prefix, value, previous) + return (previous, finite_prefix), previous + + _, values = jax.lax.scan(hold, (birth, jnp.asarray(True)), (values, valid)) + energy_error = jnp.maximum(jnp.max(jnp.abs(energies/birth_energy - 1)), + jnp.abs(end_energy/birth_energy - 1)) + return (values, jnp.where(lost, solution.t, -1.), jnp.where(failed, failed_time, -1.), + jnp.where(failed, jnp.inf, energy_error), jnp.stack(solution.stats), + jnp.where(output_failed, RKStatus.NONFINITE, solution.status)) + + return jax.vmap(one)(y0, mu0) diff --git a/essos/split.py b/essos/split.py new file mode 100644 index 00000000..bdf5fb54 --- /dev/null +++ b/essos/split.py @@ -0,0 +1,3162 @@ +"""Forward nonrelativistic orbit/collision splitting. + +An independently controlled native RK orbit solve precedes each Milstein +collision map. Brownian rejection memory preserves every sampled interval. +Private GPU adapters leave public field classes unchanged. Optional accepted-map +recording connects to the checkpointed reverse rules in ``essos.native_ad``. +""" +from enum import IntEnum +from functools import lru_cache +from typing import NamedTuple +import jax +import jax.numpy as jnp +import numpy as np +from jax import lax, tree_util +from .background_species import nu_D_ab, nu_par_ab, d_nu_par_ab, nu_s_ab +from .rk import RKStatus, solve_rk, _concrete_check, _prepare_rhs, OrbitErrorNorm + + + +# Collision error + + +class CollisionErrorModel(NamedTuple): + abs_drift: jax.Array + parallel: jax.Array + drift: jax.Array # .5 |Q Q'| (GC), or .5 |K K'| (particle) + diffusion: jax.Array # (D_parallel')**2 + pitch_drift: jax.Array # .5 |xi| nu**2; zero for particle control + pitch_diffusion: jax.Array # .5 sqrt((1-xi**2) nu) nu; zero for particle + tolerance: jax.Array + speed_noise_index: jax.Array # -2 for GC (including spatial noise), 2 for particle + +def _ratio(numerator, denominator): + safe = jnp.where(denominator > 0, denominator, 1.) + return jnp.where(denominator > 0, numerator/safe, + jnp.where(numerator == 0, 0., jnp.inf)) + +def collision_error_estimates(model, h, dw): + """Evaluate both normalized estimates without another coefficient/RHS call.""" + eps_v = model.tolerance*(model.abs_drift*h+jnp.sqrt(jnp.maximum(2*model.parallel*h, 0.))) + drift = jnp.maximum(_ratio(model.drift*h*h, eps_v), + model.pitch_drift*h*h/model.tolerance) + diffusion = jnp.maximum( + _ratio(model.diffusion*jnp.abs(dw[model.speed_noise_index])**3, + 6*eps_v*jnp.sqrt(jnp.maximum(model.parallel, 0.))), + model.pitch_diffusion*h*(jnp.abs(dw[-1])+jnp.sqrt(h/3))/model.tolerance) + return drift, diffusion + +def collision_error_passes(model, h, dw, *, target=1.): + """Check the same four bounds without forming normalized error ratios. + + Coefficients and tolerance are finite/nonnegative, with positive tolerance, + as supplied by the physical collision maps. Zero numerators and zero speed + diffusion retain the estimator's 0/0 -> 0 convention. The actual trial still + computes its normalized errors and independently checks finiteness. + """ + tolerance = target*model.tolerance + speed_scale = tolerance*(model.abs_drift*h+jnp.sqrt(jnp.maximum(2*model.parallel*h, 0.))) + return ((model.drift*h*h <= speed_scale) + & (model.diffusion*jnp.abs(dw[model.speed_noise_index])**3 + <= 6*speed_scale*jnp.sqrt(jnp.maximum(model.parallel, 0.))) + & (model.pitch_drift*h*h <= tolerance) + & (model.pitch_diffusion*h*(jnp.abs(dw[-1])+jnp.sqrt(h/3)) <= tolerance)) + + +# Collisions + + +class CollisionCoefficients(NamedTuple): + parallel: jax.Array # D_parallel [m^2/s^3] + perpendicular: jax.Array # D_perp [m^2/s^3] + parallel_derivative: jax.Array # dD_parallel/dv + friction: jax.Array # Q = -nu_s v [m/s^2] + friction_derivative: jax.Array + particle_drift_derivative: jax.Array # dK/dv, needed only by particle error control + +class CollisionStep(NamedTuple): + y: jax.Array + drift_error: jax.Array # dimensionless, acceptable if <= 1 + diffusion_error: jax.Array + error_model: CollisionErrorModel | None = None + +def _diffusion_root(value): + """sqrt(max(value, 0)) with a zero AD tangent at zero diffusion. + + The safe inner argument prevents 0*inf from contaminating vacuum-state + sensitivities. Positive-coefficient values/derivatives and invalid NaN + values are preserved. Turning on noise exactly at zero is not a regular + pathwise derivative; zero is the chosen boundary convention there. + """ + positive = value > 0 + return jnp.where(positive, jnp.sqrt(jnp.where(positive, value, 1.)), + jnp.where(jnp.isnan(value), value, 0.)) + +def guiding_center_spatial_diffusion(pitch, c, gyrofrequency): + """Paper Eq. (36), in SI velocity units: D_X [m^2/s]. + + This is the leading uniform-field GC coefficient, with no relativistic + factor c^2 because ``c.parallel/perpendicular`` already diffuse velocity. + """ + return (c.parallel*(1-pitch*pitch) + c.perpendicular*(1+pitch*pitch))/(2*gyrofrequency**2) + +def guiding_center_spatial_increment(pitch, dw, c, unit_b, gyrofrequency): + """Paper Eq. (69): frozen coefficient and perpendicular projection. + + ``dw`` is an independent spatial Wiener vector, with covariance h I; + speed/pitch use separate Wiener components. No spatial error estimator + or full multidimensional Milstein correction is supplied by this map. + """ + dx = guiding_center_spatial_diffusion(pitch, c, gyrofrequency) + return _diffusion_root(2*dx)*(dw-unit_b*jnp.dot(unit_b, dw)) + +def collision_coefficients(species, mass, charge, speed, point, *, full_orbit=False): + """SI diffusion and friction, including the speed-dependent Coulomb log. + + ``speed`` must be positive. ``point`` uses the field's profile coordinates. + The particle Ito drift is Q + D_parallel' + 2(D_parallel-D_perp)/v; + the speed Ito drift is Q + D_parallel' + 2 D_parallel/v. + """ + def values(v): + def pair(i): + nd = nu_D_ab(mass, charge, i, v, point, species) + np_ = nu_par_ab(mass, charge, i, v, point, species) + dnp = d_nu_par_ab(mass, charge, i, v, point, species) + ns = nu_s_ab(mass, charge, i, v, point, species) + return jnp.array([.5*v*v*np_, .5*v*v*nd, + v*np_ + .5*v*v*dnp, -ns*v]) + return jnp.sum(jax.vmap(pair)(species.species_indeces), axis=0) + + val, slope = jax.jvp(values, (speed,), (jnp.ones_like(speed),)) + dp, dt, ddp, q = val + if full_orbit: + dk = slope[3] + slope[2] + 2*(slope[0]-slope[1])/speed - 2*(dp-dt)/speed**2 + else: + dk = jnp.zeros_like(speed) + return CollisionCoefficients(dp, dt, ddp, q, slope[3], dk) + +def reflect_pitch(pitch): + """Repeated reflection onto [-1, 1], including overshoots beyond one wall.""" + return 1 - jnp.abs(jnp.mod(pitch + 1, 4) - 2) + +def _speed_diffusion_error(c, dw, tolerance): + return _ratio(c.parallel_derivative**2 * jnp.abs(dw)**3, + 6*tolerance*jnp.sqrt(jnp.maximum(c.parallel, 0.))) + +def guiding_center_collision_step(speed, pitch, h, dw, c, *, tolerance=1e-3, speed_floor=0., + return_error_model=False): + """Paper Eqs. (70)--(75), with speed [m/s] replacing normalized momentum. + + ``dw`` contains two independent Wiener increments of variance h, not unit + normals. The diffusion coefficients are frozen at the initial speed for + this local speed/pitch map, as in the paper. This is not a claim of a full + multidimensional Milstein expansion for arbitrary noncommuting noise. + """ + dp, dt, ddp, q, dq, _ = c + nu = 2*dt/speed**2 + drift = q + ddp + 2*dp/speed + # The 2 D_par/v part of the drift is the radial (Bessel) drift of a speed whose perpendicular + # velocity components also diffuse; explicit Euler overshoots when v^2 < 2 D_par h. It is applied + # as the perpendicular kick instead, v -> sqrt(v1^2 + 4 D_par h): same drift to O(h), v > 0. + v = speed + (drift-2*dp/speed)*h + _diffusion_root(2*dp)*dw[0] + .5*ddp*(dw[0]**2-h) + v = jnp.sqrt(v*v + 4*dp*h) + v = speed_floor + jnp.abs(v-speed_floor) + angular_noise = _diffusion_root((1-pitch**2)*nu) + xi = pitch - pitch*nu*h + angular_noise*dw[1] - .5*pitch*nu*(dw[1]**2-h) + eps_v = tolerance*(jnp.abs(drift)*h + jnp.sqrt(jnp.maximum(2*dp*h, 0.))) + ed = jnp.maximum(_ratio(.5*jnp.abs(q*dq)*h*h, eps_v), + .5*jnp.abs(pitch)*nu**2*h*h/tolerance) + # The paragraph after paper Eq. (55) explicitly uses |dW| + sqrt(h/3). + # Eq. (75)'s printed |dW + sqrt(h/3)| is inconsistent with that text; + # retain the sign-symmetric estimate rather than cancelling negative dW. + es = jnp.maximum(_speed_diffusion_error(c, dw[0], eps_v), + .5*angular_noise*nu*h*(jnp.abs(dw[1])+jnp.sqrt(h/3))/tolerance) + model = (CollisionErrorModel(jnp.abs(drift), dp, .5*jnp.abs(q*dq), ddp**2, + .5*jnp.abs(pitch)*nu**2, .5*angular_noise*nu, tolerance, jnp.array(-2)) + if return_error_model else None) + return CollisionStep(jnp.array([v, reflect_pitch(xi)]), ed, es, model) + +def velocity_basis(velocity): + """Orthonormal columns (perp1, perp2, parallel), evaluated at this step.""" + norm = jnp.linalg.norm(velocity) + direction = velocity/jnp.where(norm > 0, norm, 1.) + direction = jnp.where(norm > 0, direction, jnp.array([0., 0., 1.])) + reference = jnp.eye(3, dtype=velocity.dtype)[jnp.argmin(jnp.abs(direction))] + first = jnp.cross(direction, reference) + first = first/jnp.linalg.norm(first) + return jnp.stack([first, jnp.cross(direction, first), direction], axis=1) + +def particle_collision_step(velocity, h, dw, c, *, tolerance=1e-3, return_error_model=False): + """Paper Eqs. (57)--(62), in the local velocity-aligned basis. + + The parallel component is a Milstein increment; perpendicular components + use the additive-noise updates in the paper. ``dw`` has variance h. + """ + speed = jnp.linalg.norm(velocity) + dp, dt, ddp, q, _, dk = c + drift = q + ddp + 2*(dp-dt)/speed + delta = jnp.concatenate([_diffusion_root(2*dt)*dw[:2], + jnp.reshape(drift*h + _diffusion_root(2*dp)*dw[2] + + .5*ddp*(dw[2]**2-h), (1,))]) + eps_v = tolerance*(jnp.abs(drift)*h + jnp.sqrt(jnp.maximum(2*dp*h, 0.))) + model = (CollisionErrorModel(jnp.abs(drift), dp, .5*jnp.abs(drift*dk), ddp**2, + jnp.zeros_like(speed), jnp.zeros_like(speed), tolerance, jnp.array(2)) + if return_error_model else None) + return CollisionStep(velocity + velocity_basis(velocity) @ delta, + _ratio(.5*jnp.abs(drift*dk)*h*h, eps_v), _speed_diffusion_error(c, dw[2], eps_v), model) + +class BrownianMemory(NamedTuple): + """Stack of unconsumed intervals: the next interval is at size-1.""" + ends: jax.Array + increments: jax.Array + size: jax.Array + key: jax.Array + peak: jax.Array + t: jax.Array + +def brownian_memory(key, noise_dim, *, capacity=64, dtype=jnp.float64, t0=0.): + if isinstance(capacity, bool) or not isinstance(capacity, int) or capacity < 1: + raise ValueError("Brownian capacity must be a positive integer") + if isinstance(noise_dim, bool) or not isinstance(noise_dim, int) or noise_dim < 1: + raise ValueError("noise_dim must be a positive integer") + return BrownianMemory(jnp.zeros(capacity, dtype), jnp.zeros((capacity, noise_dim), dtype), + jnp.array(0), key, jnp.array(0), jnp.asarray(t0, dtype)) + +def brownian_propose(memory, h, *, t_end=None): + """Return (memory, h, dW, overflow) without consuming the proposed interval. + + A retry keeps its parent increment. A shorter request replaces it by + conditional left/right increments (paper Eqs. 83--84). Growth stops at the + next stored endpoint, so no sampled future value is discarded or skipped. + Only ``brownian_accept`` consumes an interval. Capacity overflow is reported + without replacing or discarding any stored increment. Absolute endpoints + keep roundoff in repeated duration subtraction from stranding an increment. + ``t_end`` optionally supplies the exact requested endpoint (e.g. a save). + """ + requested_end = memory.t+h if t_end is None else t_end + # Creating a parent and splitting a retained parent are exclusive. Share + # their original-key draw so vmap need not evaluate two normal generators. + key, draw = jax.random.split(memory.key) + normal = jax.random.normal(draw, memory.increments.shape[1:], dtype=memory.increments.dtype) + def new(m): + dw = jnp.sqrt(requested_end-m.t)*normal + return BrownianMemory(m.ends.at[0].set(requested_end), m.increments.at[0].set(dw), + jnp.array(1), key, jnp.maximum(m.peak, 1), m.t) + m = lax.cond(memory.size == 0, new, lambda m: m, memory) + top = m.size-1 + parent_end, parent = m.ends[top], m.increments[top] + duration = parent_end-m.t + end = jnp.minimum(requested_end, parent_end) + h = end-m.t + split = end < parent_end + overflow = split & (m.size == len(m.ends)) + + def bridge(m): + alpha = h/duration + left = alpha*parent + jnp.sqrt(h*(1-alpha))*normal + # Parent = left + right, including across repeated nested rejections. + return BrownianMemory(m.ends.at[top+1].set(end), + m.increments.at[top].set(parent-left).at[top+1].set(left), m.size+1, key, + jnp.maximum(m.peak, m.size+1), m.t) + m = lax.cond(split & ~overflow, bridge, lambda m: m, m) + return m, h, m.increments[m.size-1], overflow + +def brownian_accept(memory): + return memory._replace(size=memory.size-1, t=memory.ends[memory.size-1]) + +def brownian_sample(memory, end, *, normal=None): + """Sample W(end)-W(memory.t), retaining every sampled future point. + + Unlike ``brownian_propose``, this can span several stored intervals. New + points inside a stored interval use the conditional law in Eqs. 83--84; + points beyond the last sample extend it by an independent increment. + The descending endpoint/interval representation is shared with the stack + driver. Overflow leaves the memory and random key unchanged. + An explicit standard ``normal`` can be supplied by a caller that owns the + random-key advancement; otherwise a new key is split only for insertion. + """ + if normal is not None: + normal = jnp.asarray(normal, dtype=memory.increments.dtype) + if normal.shape != memory.increments.shape[1:]: + raise ValueError("normal must match the Wiener increment shape") + m = memory + indices = jnp.arange(len(m.ends)) + active = indices < m.size + matches = active & (m.ends == end) + known = jnp.any(matches) | (end == m.t) + overflow = ~known & (m.size == len(m.ends)) + + def insert(m): + # k=-1 extends the furthest endpoint; otherwise split interval k. + k = jnp.sum(active & (m.ends > end))-1 + extending = k < 0 + start = jnp.where(extending, + jnp.where(m.size > 0, m.ends[0], m.t), + jnp.where(k+1 < m.size, m.ends[jnp.minimum(k+1, len(m.ends)-1)], m.t)) + stop = m.ends[jnp.maximum(k, 0)] + duration = jnp.where(extending, end-start, stop-start) + fraction = jnp.where(extending, 1., (end-start)/jnp.where(duration > 0, duration, 1.)) + if normal is None: + key, draw = jax.random.split(m.key) + z = jax.random.normal(draw, m.increments.shape[1:], dtype=m.increments.dtype) + else: + key, z = m.key, normal + parent = m.increments[jnp.maximum(k, 0)] + left = jnp.where(extending, jnp.sqrt(jnp.maximum(end-start, 0.))*z, + fraction*parent+jnp.sqrt(jnp.maximum((end-start)*(1-fraction), 0.))*z) + at = k+1 + old_indices = jnp.clip(indices-(indices > at), 0, len(m.ends)-1) + ends, increments = m.ends[old_indices], m.increments[old_indices] + ends = ends.at[at].set(end) + increments = increments.at[at].set(left) + increments = lax.cond(extending, lambda a: a, + lambda a: a.at[k].set(parent-left), increments) + return BrownianMemory(ends, increments, m.size+1, key, + jnp.maximum(m.peak, m.size+1), m.t) + + m = lax.cond(~known & ~overflow, insert, lambda m: m, m) + value = jnp.sum(jnp.where(((indices < m.size) & (m.ends <= end))[:, None], m.increments, 0.), axis=0) + return m, value, overflow + +def brownian_consume(memory, end): + """Consume through an endpoint previously inserted by brownian_sample.""" + keep = (jnp.arange(len(memory.ends)) < memory.size) & (memory.ends > end) + return memory._replace(size=jnp.sum(keep), t=end) + +def paper_collision_step_size(memory, h, dw, drift_error, diffusion_error, + accepted, *, dtmin, dtmax, barrier, wiener_norm=None): + """Paper section 5.3, Eqs. 78--82, with retained Wiener look-ahead. + + Probe cumulative Wiener values at successive thirds, stopping at the + first threshold crossing. ``wiener_norm`` projects onto the noise components + present in the error estimate; its default is the Euclidean vector norm. + For the particle estimate (Eq. 62), only the parallel increment is relevant. + All probes, including the first failing one, remain in Brownian memory. + The first third is retried if no candidate passes; actual error estimates + still decide acceptance. dtmax and the next output/final time cap probes. + """ + drift_dominated = drift_error >= diffusion_error + base = jnp.where(drift_dominated, + jnp.minimum(1.5, .9*jnp.maximum(drift_error, 1e-30)**(-.5))*h, h) + limit = jnp.minimum(dtmax, barrier-memory.t) + unit = jnp.minimum(jnp.maximum(base/3, dtmin), limit) + norm = jnp.linalg.norm if wiener_norm is None else wiener_norm + amplitude = norm(dw) + optimum = .9*jnp.maximum(diffusion_error, 1e-30)**(-1/3)*amplitude + lmax = jnp.where(drift_dominated, 3, + jnp.where(~accepted, 2, jnp.where(amplitude < 2*jnp.sqrt(h), 4, 6))) + + def probe(carry): + m, n, chosen, running, overflow = carry + length = jnp.minimum(n*unit, limit) + end = jnp.minimum(m.t+length, barrier) + m, candidate, full = brownian_sample(m, end) + passes = norm(candidate) < optimum + chosen = jnp.where((n == 1) | passes, end-m.t, chosen) + return m, n+1, chosen, passes & ~full & (length < limit), overflow | full + + def stochastic(_): + m, _, chosen, _, overflow = lax.while_loop( + lambda c: (c[1] <= lmax) & c[3], probe, + (memory, jnp.array(1), unit, jnp.array(True), jnp.array(False))) + return m, chosen, overflow + + # A zero realized diffusion estimate leaves Eq. (80)'s threshold undefined + # when the controlled increment is also zero. Use the drift proposal as a + # fallback; zero realized error does not imply zero diffusion coefficients. + # The next actual trial must still satisfy both error limits. + return lax.cond(diffusion_error > 0, stochastic, + lambda _: (memory, jnp.minimum(jnp.maximum(base, dtmin), limit), jnp.array(False)), None) + + +# Collision controller + + +def _fit_error_step(model, bound, minimum, normal_magnitude, target): + """Largest bracketed step for frozen coefficients and fixed |dW|/sqrt(h). + + Eight bisections avoid assuming a common error power for speed and pitch. + This is a cheap prediction: the next actual Brownian sample is checked + separately. A sub-grid positive fallback still goes through real acceptance. + """ + # At fixed |dW|/sqrt(h), cancel the common sqrt(h) in the speed + # numerators/denominator and compare cross-products. These are exactly the + # same four error inequalities, including 0/0 -> 0 in vacuum, without + # repeated divisions, noise indexing, or coefficient square roots. + parallel = jnp.sqrt(jnp.maximum(model.parallel, 0.)) + thermal_noise = jnp.sqrt(jnp.maximum(2*model.parallel, 0.)) + speed_noise = model.diffusion*jnp.abs(normal_magnitude[model.speed_noise_index])**3 + pitch_noise = model.pitch_diffusion*(jnp.abs(normal_magnitude[-1])+1/jnp.sqrt(3.)) + tolerance = target*model.tolerance + + def passes(h): + root_h = jnp.sqrt(h) + scale = tolerance*(model.abs_drift*root_h+thermal_noise) + return ((model.drift*h*root_h <= scale) + & (speed_noise*h <= 6*parallel*scale) + & (model.pitch_drift*h*h <= tolerance) + & (pitch_noise*h*root_h <= tolerance)) + + def bisect(_): + def one(_, bracket): + lo, hi = bracket + middle = (lo+hi)/2 + passed = passes(middle) + return jnp.where(passed, middle, lo), jnp.where(passed, hi, middle) + lo, hi = lax.fori_loop(0, 8, one, (minimum, bound)) + return jnp.where(lo > 0, lo, hi/2) + return lax.cond(passes(bound), lambda _: bound, bisect, None) + +def candidate_collision_step_size(memory, h, error_model, accepted, *, + dtmin, dtmax, barrier, target=.9): + """Predict, probe and backtrack using both frozen normalized error estimates. + + Accepted trials can grow by at most two; rejected trials shrink by at least + 20%, subject to dtmin and save/final boundaries. The initial predictor uses + unit Gaussian magnitudes. A failed probe refits using its realized Gaussian + magnitudes and a smaller upper bound. At most four Wiener points are probed. + If the budget is exhausted, the last sampled step is returned for the real + acceptance test; no inaccurate step is forced through. + """ + limit = jnp.minimum(dtmax, barrier-memory.t) + bound = jnp.minimum(jnp.maximum(jnp.where(accepted, 2., .8)*h, dtmin), limit) + minimum = jnp.minimum(dtmin, bound) + unit_noise = jnp.ones(memory.increments.shape[1:], dtype=memory.increments.dtype) + proposal = _fit_error_step(error_model, bound, minimum, unit_noise, target) + + def stochastic(_): + def probe(carry): + m, wanted, last, count, running, overflow = carry + end = jnp.minimum(m.t+wanted, barrier) + length = end-m.t + m, dw, full = brownian_sample(m, end) + passed = collision_error_passes(error_model, length, dw, target=target) + retry = ~passed & ~full & (length > minimum) & (count < 3) + + def refit(_): + smaller = jnp.maximum(.8*length, minimum) + normal = jnp.abs(dw)/jnp.sqrt(length) + return _fit_error_step(error_model, smaller, minimum, normal, target) + next_h = lax.cond(retry, refit, lambda _: length, None) + return m, next_h, length, count+1, retry, overflow | full + m, _, last, _, _, overflow = lax.while_loop( + lambda c: c[4], probe, + (memory, proposal, proposal, jnp.array(0), jnp.array(True), jnp.array(False))) + return m, last, overflow + + has_noise_error = (error_model.diffusion > 0) | (error_model.pitch_diffusion > 0) + return lax.cond(has_noise_error, stochastic, + lambda _: (memory, proposal, jnp.array(False)), None) + +class SplitStatus(IntEnum): + SUCCESS = 0 + EVENT = 1 + MAX_STEPS = 2 + MIN_STEP = 3 + NONFINITE = 4 + INVALID_INPUT = 5 + BROWNIAN_CAPACITY = 6 + +class SplitStats(NamedTuple): + steps: jax.Array + accepted: jax.Array + rejected: jax.Array + orbit_steps: jax.Array + orbit_rejected: jax.Array + peak_pending: jax.Array + max_accepted_error: jax.Array + combined_rejected: jax.Array = 0 + max_accepted_combined_error: jax.Array = 0. + collision_updates: jax.Array = 0 + accepted_orbit_steps: jax.Array | None = None + max_orbit_steps_per_collision: jax.Array | None = None + +class SplitSolution(NamedTuple): + ts: jax.Array + ys: jax.Array + t: jax.Array + y: jax.Array + status: jax.Array + stats: SplitStats + step_ts: jax.Array + +def solve_split(rhs, collision, y0, args=None, *, t0=0.0, t1, dt0, ts, key, noise_dim, adaptive=True, dtmin=0.0, dtmax=jnp.inf, method='dopri8', orbit_dt0=None, orbit_adaptive=True, orbit_stage_execution='loop', reuse_orbit_step=True, collision_controller='conservative', collision_wiener_norm=None, rtol=1e-09, atol=1e-09, error_norm=None, controller='i', pcoeff=0.4, icoeff=0.3, event=None, max_steps=100000, max_orbit_steps=10000, max_pending=64, record_steps=False, step_limit=None, align_orbit=False, event_dtmax=None, combined_error_norm=None, shared_clock=False, reuse_combined_orbit=True, combined_controller='rms', _orbit_rhs_prepared=False, + adjoint='none', adjoint_checkpoint_steps=16, adjoint_orbit_checkpoint_steps=16, + adjoint_max_accepted_steps=None, adjoint_max_orbit_steps=None, + _record_ad=False, _collision_state_indices=None, _recorder=None): + """Orbit advancement followed by an endpoint collision kick. + +``collision(t, y, h, dW, args)`` returns ``CollisionStep`` with normalized +drift/diffusion estimates. Rejected trials repeat from the last accepted +state and retain all Brownian samples. The conservative controller uses +factors 0.9*min(E_drift**(-1/2), E_diff**(-2/3)), capped at 1.5. +``collision_controller="paper"`` selects section 5.3's Wiener look-ahead +(Eqs. 78--82), retaining every sampled candidate including failed probes. +``collision_controller="candidate"`` predicts both errors using frozen +local coefficients, then probes/backtracks on retained Wiener candidates. +It requires ``CollisionStep.error_model`` and still checks actual errors +for acceptance. The native collision kernels supply this metadata without +extra runtime coefficient evaluations. +``collision_wiener_norm`` selects the Wiener components that enter the +collision error estimate; by default it is the Euclidean norm of all noise. + +``dt0``/``dtmax`` control collision/splitting intervals; ``orbit_dt0`` and +rtol/atol control the independent RK solve within each interval. Collision +estimates do not bound operator-splitting error: refine dtmax to check it. +Saves are exact split boundaries, so changing ts can change the trajectory. +No ODE dense interpolation is applied to a stochastic trajectory. +``reuse_orbit_step`` carries the next adaptive RK step-size guess across +kicks and retries. Every solve recomputes its initial derivative; no FSAL +derivative or PI error history is carried across a collision. +``orbit_stage_execution`` selects the RK loop or unrolled execution layout; +it does not change the orbit formula or the collision sampling. + +``combined_error_norm(coarse, fine)`` optionally compares one full split step +with two Brownian-coupled half steps and accepts the fine result only when +this scalar estimate and all three collision estimates are <=1. Midpoints +remain in Brownian memory on rejection; growth cannot skip stored endpoints. +This experimental mode requires conservative adaptive collisions and no +events/step limits. Its H**(3/2) step-size predictor is a heuristic, not an +ensemble-error bound. ``accepted`` counts outer intervals; ``collision_updates`` +counts the two accepted half kicks. Recorded step_ts includes both half ends. +Work counters include the full comparison trajectory and rejected trials. +``reuse_combined_orbit`` shares the initial half-orbit between the coarse and +fine paths. The coarse orbit then continues without the midpoint kick; the +fine path continues after it. The coarse collision still spans the full +interval. RK tolerances and retained Brownian samples are unchanged. False +retains the original independent full-orbit comparison for verification. +``combined_controller="rms"`` predicts the next interval from an exponential +average of squared defects divided by (h/dt0)**3, including rejected trials. +The averaging weight is 1/4 and the normalized RMS target is .55. Save times +and retained endpoints can truncate h without shrinking the intended proposal. +Every actual trial still requires the same realized defect and collision +estimates <=1; this predictor is not a certified conditional RMS error bound. +``combined_controller="i"`` retains the original single-defect I proposal. + +``shared_clock=True`` is an experimental policy comparison: one accepted RK +step per collision update, with both error estimates constraining the common +interval. Rejected orbit trials retain their Wiener endpoints. It requires +adaptive conservative collisions/orbits, reused RK proposals and no events, +step limits or combined control. This uses native formulas, not ASCOT's solver. + +Events are scalar booleans or positive-inside level sets (or their PyTrees). +Orbit crossings are root-found before a kick. A kick crossing stops at its +endpoint; Brownian crossings are not root-found by ODE interpolation. +Optional ``step_limit(t, y, args)`` supplies a positive interval ceiling +from the current accepted state. Optional ``event_dtmax`` retries a detected +kick crossing until its interval is this small, retaining Brownian samples. +The two controls support boundary-resolution diagnostics; they do not detect +every crossing followed by a return, or certify an exact first-passage time. +Neither is enabled by default. Step limits also subdivide fixed grids while +retaining their original grid anchors. They must not depend on fresh noise. +Stopped/failed outputs hold the last finite state; always inspect status. +Work and Brownian memory are bounded. No inaccurate step is forced through +dtmin or a memory limit.""" + if adjoint not in ('none','accepted'): + raise ValueError("adjoint must be 'none' or 'accepted'") + if adjoint == 'accepted' or _record_ad: + options=locals().copy() + from .native_ad import solve_accepted_split, _SplitRecorder + for name in ('rhs','collision','y0','args','adjoint','_record_ad','_recorder'): + options.pop(name) + if adjoint == 'accepted': + return solve_accepted_split(rhs,collision,y0,args,**options) + _recorder=_SplitRecorder.from_options(jnp.asarray(y0),options) + if _recorder is not None and combined_error_norm is not None: + raise ValueError('accepted AD records the production moment controller; experimental step doubling is unsupported') + combined = combined_error_norm is not None + if combined_controller not in ('i','rms'): + raise ValueError("combined_controller must be 'i' or 'rms'") + rms = combined and combined_controller == 'rms' + if align_orbit and (not adaptive or not orbit_adaptive or not reuse_orbit_step or shared_clock or combined): + raise ValueError('orbit endpoint alignment requires separate adaptive clocks and orbit-step reuse') + if shared_clock and (combined or not adaptive or not orbit_adaptive or not reuse_orbit_step or collision_controller != 'conservative' or tree_util.tree_leaves(event) or step_limit is not None or event_dtmax is not None): + raise ValueError('shared_clock requires adaptive conservative collisions/orbits with reused steps, without combined control, events or step limits') + if combined and (not adaptive or collision_controller != 'conservative' or tree_util.tree_leaves(event) or step_limit is not None or event_dtmax is not None): + raise ValueError('combined control requires adaptive conservative collisions without events or step limits') + if combined and not callable(combined_error_norm): + raise ValueError('combined_error_norm must be callable') + for name, value in (('max_steps', max_steps), ('max_orbit_steps', max_orbit_steps)): + if isinstance(value, bool) or not isinstance(value, int) or value < 1: + raise ValueError(f'{name} must be a positive integer') + if orbit_stage_execution not in ('loop', 'unrolled'): + raise ValueError("orbit_stage_execution must be 'loop' or 'unrolled'") + if collision_controller not in ('conservative', 'paper', 'candidate'): + raise ValueError("collision_controller must be 'conservative', 'paper' or 'candidate'") + candidate = adaptive and collision_controller == 'candidate' + lookahead = adaptive and collision_controller in ('paper', 'candidate') + y0 = jnp.asarray(y0, dtype=jnp.result_type(y0, float)) + ts = jnp.asarray(ts, dtype=y0.dtype) + if y0.ndim != 1 or y0.size == 0 or (not jnp.issubdtype(y0.dtype, jnp.floating)): + raise ValueError('y0 must be a nonempty real vector') + if ts.ndim != 1: + raise ValueError('ts must be one-dimensional') + orbit_dt0 = dt0 if orbit_dt0 is None else orbit_dt0 + for name, value in (('t0', t0), ('t1', t1), ('dt0', dt0), ('dtmin', dtmin), ('dtmax', dtmax), ('orbit_dt0', orbit_dt0)): + if jnp.ndim(value) != 0: + raise ValueError(f'{name} must be scalar') + t0, t1, dt0, dtmin, dtmax, orbit_dt0 = (jnp.asarray(x, dtype=y0.dtype) for x in (t0, t1, dt0, dtmin, dtmax, orbit_dt0)) + orbit_rhs = rhs if _orbit_rhs_prepared else _prepare_rhs(rhs, t0, y0, args) + if event_dtmax is not None: + if event is None or jnp.ndim(event_dtmax) != 0: + raise ValueError('event_dtmax requires an event and a scalar interval') + event_dtmax = jnp.asarray(event_dtmax, dtype=y0.dtype) + valid = jnp.isfinite(t0) & jnp.isfinite(t1) & (t1 >= t0) & jnp.isfinite(dt0) & (dt0 > 0) & jnp.isfinite(dtmin) & (dtmin >= 0) & (dt0 >= dtmin) & (dtmax > 0) & (dtmax >= dtmin) & jnp.isfinite(orbit_dt0) & (orbit_dt0 > 0) & jnp.all(jnp.isfinite(ts) & (ts >= t0) & (ts <= t1)) & jnp.all(jnp.diff(ts) >= 0) + if event_dtmax is not None: + valid &= jnp.isfinite(event_dtmax) & (event_dtmax > 0) & (event_dtmax >= dtmin) + _concrete_check(valid, np.all, 'invalid split times or step limits') + empty_model = None + if candidate: + schema = jax.eval_shape(collision, t0, y0, dt0, jnp.zeros((noise_dim,), y0.dtype), args) + if not isinstance(schema.error_model, CollisionErrorModel): + raise ValueError('candidate controller requires CollisionStep.error_model') + if any((x.shape != () for x in tree_util.tree_leaves(schema.error_model))): + raise ValueError('collision error model coefficients must be scalars') + empty_model = tree_util.tree_map(lambda x: jnp.zeros(x.shape, x.dtype), schema.error_model) + empty_model = empty_model._replace(tolerance=jnp.ones_like(empty_model.tolerance)) + functions = tree_util.tree_leaves(event) + + def values(t, y): + out = tuple((jnp.asarray(f(t, y, args)) for f in functions)) + if any((x.shape != () or (x.dtype != jnp.bool_ and (not jnp.issubdtype(x.dtype, jnp.floating))) for x in out)): + raise ValueError('events must return scalar booleans or floating level sets') + return out + + def stopped(v): + return jnp.any(jnp.asarray([x if x.dtype == jnp.bool_ else x <= 0 for x in v], dtype=bool)) + + def finite_values(v): + return jnp.all(jnp.asarray([jnp.isfinite(x) for x in v], dtype=bool)) + v0 = values(t0, y0) + initial_status = jnp.where(~valid, SplitStatus.INVALID_INPUT, jnp.where(~jnp.isfinite(y0).all() | ~finite_values(v0), SplitStatus.NONFINITE, jnp.where(stopped(v0), SplitStatus.EVENT, SplitStatus.SUCCESS))) + memory = brownian_memory(key, noise_dim, capacity=max_pending, dtype=y0.dtype, t0=t0) + s = dict(t=t0, y=y0, h=jnp.minimum(dt0, dtmax), orbit_h=orbit_dt0, status=initial_status, memory=memory, index=jnp.array(0), ys=jnp.broadcast_to(y0, (len(ts), y0.size)), steps=jnp.array(0), accepted=jnp.array(0), rejected=jnp.array(0), orbit_steps=jnp.array(0), orbit_rejected=jnp.array(0), max_error=jnp.zeros((), y0.dtype), history=jnp.full(((2 if combined else 1)*max_steps + 1 if record_steps else 0,), jnp.inf, dtype=y0.dtype)) + if combined: + s.update(combined_rejected=jnp.array(0), combined_error=jnp.zeros((), y0.dtype), + accepted_orbit_steps=jnp.array(0), max_orbit_steps_per_collision=jnp.array(0)) + else: + s.update(accepted_orbit_steps=jnp.array(0), max_orbit_steps_per_collision=jnp.array(0)) + if rms: + s.update(combined_rate=jnp.zeros((),y0.dtype),combined_rate_ready=jnp.array(False)) + if record_steps: + s['history'] = s['history'].at[0].set(t0) + if not adaptive: + s['grid_index'] = jnp.array(0) + if event_dtmax is not None: + s['event_h'] = jnp.asarray(jnp.inf, dtype=y0.dtype) + + def save(s): + if not len(ts): + return s + + def one(s): + return dict(s, ys=s['ys'].at[s['index']].set(s['y']), index=s['index'] + 1) + return lax.while_loop(lambda s: (s['index'] < len(ts)) & (ts[jnp.minimum(s['index'], len(ts) - 1)] <= s['t']), one, s) + s = save(s) + initial_saves = s['index'] + if _recorder is not None: + s = _recorder.initialize(s) + + def integrate(t, y, end, guess): + if _recorder is not None: + from .native_ad import _OrbitRecorder + result = solve_rk(orbit_rhs, y, args, t0=t, t1=end, dt0=jnp.minimum(guess, end-t), ts=jnp.empty((0,), y0.dtype), method=method, adaptive=orbit_adaptive, rtol=rtol, atol=atol, stage_execution=orbit_stage_execution, error_norm=error_norm, controller=controller, pcoeff=pcoeff, icoeff=icoeff, event=event, root_find=True, max_steps=1 if shared_clock else max_orbit_steps, + _recorder=None if _recorder is None else _OrbitRecorder(max_orbit_steps,adjoint_orbit_checkpoint_steps,schedule=True)) + return result + + def kick(t, y, h, dw): + result = collision(t, y, h, dw, args) + if result.y.shape != y0.shape: + raise ValueError('collision must preserve the state shape') + if jnp.ndim(result.drift_error) or jnp.ndim(result.diffusion_error): + raise ValueError('collision errors must be scalars') + return result if candidate else result._replace(error_model=None) + + def valid_trial(trial): + errors=jnp.asarray([trial.drift_error,trial.diffusion_error]) + return jnp.isfinite(trial.y).all() & jnp.isfinite(errors).all() & jnp.all(errors>=0) + + def advance_with_limit(s, limit): + physical_barrier = t1 if not len(ts) else jnp.where(s['index'] < len(ts), ts[jnp.minimum(s['index'], len(ts) - 1)], t1) + barrier = physical_barrier + if step_limit is not None: + barrier = jnp.minimum(barrier, s['t'] + limit) + if event_dtmax is not None: + barrier = jnp.minimum(barrier, s['t'] + s['event_h']) + if adaptive: + proposal = jnp.minimum(s['h'], jnp.maximum(s['orbit_h'], dtmin)) if shared_clock else s['h'] + wanted_end = jnp.minimum(s['t'] + proposal, barrier) + else: + grid_end = t0 + (s['grid_index'] + 1) * jnp.minimum(dt0, dtmax) + close = jnp.abs(grid_end - barrier) <= 8 * jnp.finfo(y0.dtype).eps * jnp.maximum(jnp.abs(grid_end), jnp.abs(barrier)) + grid_end = jnp.where(close, barrier, grid_end) + wanted_end = jnp.minimum(grid_end, barrier) + if align_orbit: + length=wanted_end-s['t'];guess=s['orbit_h'] + near=(jnp.isfinite(guess)&(guess>0)&(wanted_end=.9*length)&(guesss['t']) & (barrier-wanted_end<=rounding),barrier,wanted_end) + parent = s['memory'].ends[jnp.maximum(s['memory'].size-1,0)] + wanted_end = jnp.where((s['memory'].size>0)&(parent>=wanted_end)&(parent<=barrier)&(parent-wanted_end<=rounding),parent,wanted_end) + if lookahead: + m, dw, overflow = brownian_sample(s['memory'], wanted_end) + end, h = (wanted_end, wanted_end - s['t']) + else: + m, h, dw, overflow = brownian_propose(s['memory'], wanted_end - s['t'], t_end=wanted_end) + end = m.ends[m.size - 1] + usable = ~overflow & (h > 0) & (end > s['t']) + + def attempt(_): + guess = h if shared_clock else s['orbit_h'] if reuse_orbit_step and orbit_adaptive else orbit_dt0 + if combined and reuse_combined_orbit: + half_end=s['t']+h/2 + shared_first=integrate(s['t'],s['y'],half_end,guess) + tail=lax.cond(shared_first.status==RKStatus.SUCCESS, + lambda _:integrate(half_end,shared_first.y,end,shared_first.next_dt if reuse_orbit_step and orbit_adaptive else orbit_dt0), + lambda _:shared_first._replace(stats=type(shared_first.stats)(*(jnp.zeros_like(v) for v in shared_first.stats))),None) + orbit=tail._replace(stats=type(tail.stats)(*(a+b for a,b in zip(shared_first.stats,tail.stats)))) + else: + result = integrate(s['t'], s['y'], end, guess) + orbit, schedule = result if _recorder is not None else (result, None) + trial = lax.cond(orbit.status == RKStatus.SUCCESS, lambda _: kick(end, orbit.y, h, dw), lambda _: CollisionStep(orbit.y, jnp.zeros((), y0.dtype), jnp.zeros((), y0.dtype), empty_model), None) + memory, combined_error = m, jnp.zeros((), y0.dtype) + if combined: + middle = s['t']+h/2 + splittable = (middle > s['t']) & (middle < end) + memory, _, left, full = lax.cond(splittable, + lambda m: brownian_propose(m, middle-s['t'], t_end=middle), + lambda m: (m, jnp.zeros_like(h), jnp.zeros_like(dw), jnp.array(False)), m) + def refine(_): + first = shared_first if reuse_combined_orbit else integrate(s['t'], s['y'], middle, guess) + a = kick(middle, first.y, middle-s['t'], left) + second = integrate(middle, a.y, end, first.next_dt if reuse_orbit_step and orbit_adaptive else orbit_dt0) + b = kick(end, second.y, end-middle, dw-left) + estimate = jnp.asarray(combined_error_norm(trial.y, b.y), dtype=y0.dtype) + if estimate.ndim != 0: + raise ValueError('combined error norm must return a scalar') + status = jnp.where(first.status != RKStatus.SUCCESS, first.status, + jnp.where(~jnp.isfinite(a.y).all(), RKStatus.NONFINITE, second.status)) + stats = type(orbit.stats)(*(x+z if reuse_combined_orbit else x+y+z for x,y,z in zip(orbit.stats,first.stats,second.stats))) + refined = b._replace(y=jnp.where(valid_trial(a)&valid_trial(b),b.y,jnp.full_like(b.y,jnp.nan)), + drift_error=jnp.maximum(trial.drift_error,jnp.maximum(a.drift_error,b.drift_error)), + diffusion_error=jnp.maximum(trial.diffusion_error,jnp.maximum(a.diffusion_error,b.diffusion_error))) + return (second._replace(status=status,stats=stats),refined,estimate, + (first.stats.accepted+second.stats.accepted).astype(s['accepted'].dtype), + jnp.maximum(first.stats.accepted,second.stats.accepted).astype(s['accepted'].dtype)) + orbit,trial,combined_error,path_steps,path_max = lax.cond(splittable & ~full & (orbit.status == RKStatus.SUCCESS) & valid_trial(trial), + refine, lambda _: (orbit,trial,combined_error,jnp.zeros_like(s['accepted']),jnp.zeros_like(s['accepted'])), None) + v = values(end, trial.y) + finite = valid_trial(trial) & finite_values(v) + finite &= jnp.isfinite(combined_error) & (combined_error >= 0) + error = jnp.maximum(trial.drift_error, trial.diffusion_error) + accepted = (orbit.status == RKStatus.SUCCESS) & finite & ((jnp.maximum(error,combined_error) <= 1) | (not adaptive)) + if combined: + accepted &= splittable & ~full + refine_event = jnp.array(False) + if event_dtmax is not None: + refine_event = accepted & stopped(v) & (h > event_dtmax * (1 + 8 * jnp.finfo(y0.dtype).eps)) + accepted &= ~refine_event + orbit_retry = (orbit.status == RKStatus.MAX_STEPS) & (orbit.stats.accepted == 0) & (orbit.stats.rejected == 1) if shared_clock else jnp.array(False) + orbit_status = jnp.where(orbit_retry, RKStatus.SUCCESS, orbit.status) + rejected = (orbit_status == RKStatus.SUCCESS) & finite & ~accepted + orbit_event = orbit.status == RKStatus.EVENT + status = jnp.where(orbit_status != RKStatus.SUCCESS, orbit_status, jnp.where(~finite, SplitStatus.NONFINITE, jnp.where(accepted & stopped(v), SplitStatus.EVENT, jnp.where(rejected & (h <= dtmin), SplitStatus.MIN_STEP, SplitStatus.SUCCESS)))) + if combined: + status = jnp.where(full, SplitStatus.BROWNIAN_CAPACITY, jnp.where(~splittable, SplitStatus.MIN_STEP, status)) + if rms: + observe=(h>dt0*1e-6)&(combined_error>1e-8)&jnp.isfinite(combined_error) + observation=combined_error**2/jnp.maximum((h/dt0)**3,1e-30) + rate=jnp.where(observe,jnp.where(s['combined_rate_ready'],.75*s['combined_rate']+.25*observation,observation),s['combined_rate']) + ready=s['combined_rate_ready']|observe + proposal=dt0*(.55**2/jnp.maximum(rate,1e-30))**(1/3) + collision=.9*h*jnp.minimum(jnp.maximum(trial.drift_error,1e-30)**(-.5),jnp.maximum(trial.diffusion_error,1e-30)**(-2/3)) + proposal=jnp.minimum(proposal,collision) + ceiling=jnp.where(accepted & (h1)).astype(s['rejected'].dtype), + combined_error=jnp.maximum(s['combined_error'],jnp.where(accepted,combined_error,0.)), + accepted_orbit_steps=s['accepted_orbit_steps']+jnp.where(accepted,path_steps,0), + max_orbit_steps_per_collision=jnp.maximum(s['max_orbit_steps_per_collision'],jnp.where(accepted,path_max,0))) + else: + path_steps = jnp.where(accepted,orbit.stats.accepted,0).astype(s['accepted'].dtype) + state.update(accepted_orbit_steps=s['accepted_orbit_steps']+path_steps, + max_orbit_steps_per_collision=jnp.maximum(s['max_orbit_steps_per_collision'],path_steps)) + if event_dtmax is not None: + state['event_h'] = jnp.where(refine_event, jnp.maximum(dtmin, 0.5 * h), jnp.inf) + state['h'] = jnp.where(refine_event, state['event_h'], state['h']) + if reuse_orbit_step and orbit_adaptive: + state['orbit_h'] = orbit.next_dt + if not adaptive: + state['grid_index'] = s['grid_index'] + (accepted & (end == grid_end)).astype(s['grid_index'].dtype) + if record_steps: + if combined: + state['history'] = lax.cond(accepted,lambda a:a.at[2*state['accepted']-1].set(middle).at[2*state['accepted']].set(end),lambda a:a,state['history']) + else: + state['history'] = lax.cond(accepted, lambda history: history.at[state['accepted']].set(end), lambda history: history, state['history']) + state = save(state) + if _recorder is not None: + state = _recorder.record(s,state,accepted,orbit_event,orbit,schedule,dw) + if lookahead: + + def choose(state): + barrier = t1 if not len(ts) else jnp.where(state['index'] < len(ts), ts[jnp.minimum(state['index'], len(ts) - 1)], t1) + if candidate: + memory, next_h, overflow = candidate_collision_step_size(state['memory'], h, trial.error_model, accepted, dtmin=dtmin, dtmax=dtmax, barrier=barrier) + else: + memory, next_h, overflow = paper_collision_step_size(state['memory'], h, dw, trial.drift_error, trial.diffusion_error, accepted, dtmin=dtmin, dtmax=dtmax, barrier=barrier, wiener_norm=collision_wiener_norm) + return dict(state, memory=memory, h=next_h, status=jnp.where(overflow, SplitStatus.BROWNIAN_CAPACITY, state['status'])) + state = lax.cond((state['status'] == SplitStatus.SUCCESS) & (state['t'] < t1) & ~refine_event, choose, lambda state: state, state) + return state + return lax.cond(usable, attempt, lambda _: dict(s, memory=m, status=jnp.where(overflow, SplitStatus.BROWNIAN_CAPACITY, SplitStatus.MIN_STEP)), None) + + def advance(s): + if step_limit is None: + return advance_with_limit(s, None) + limit = jnp.asarray(step_limit(s['t'], s['y'], args), dtype=y0.dtype) + if limit.ndim != 0: + raise ValueError('step_limit must return a scalar interval') + return lax.cond((limit > 0) & ~jnp.isnan(limit), lambda _: advance_with_limit(s, limit), lambda _: dict(s, status=jnp.asarray(SplitStatus.INVALID_INPUT)), None) + s = lax.while_loop(lambda s: (s['status'] == SplitStatus.SUCCESS) & (s['t'] < t1) & (s['steps'] < max_steps), advance, s) + status = jnp.where((s['status'] == SplitStatus.SUCCESS) & (s['t'] < t1), SplitStatus.MAX_STEPS, s['status']) + ys = jnp.where((jnp.arange(len(ts)) >= s['index'])[:, None], s['y'], s['ys']) + solution = SplitSolution(ts, ys, s['t'], s['y'], status, SplitStats(s['steps'], s['accepted'], s['rejected'], s['orbit_steps'], s['orbit_rejected'], s['memory'].peak, s['max_error'],s.get('combined_rejected',0),s.get('combined_error',0.),(2 if combined else 1)*s['accepted'],s.get('accepted_orbit_steps'),s.get('max_orbit_steps_per_collision')), s['history']) + return solution if _recorder is None else _recorder.finish(s,solution,initial_saves) + +def trace_split(field, particles, species, *, model='GuidingCenter', tmax, timestep, times=None, n_save=100, integrator='essos_dopri8', collision_tolerance=0.001, adaptive=True, collision_dtmax=None, orbit_dt0=None, orbit_adaptive=True, orbit_stage_execution=None, reuse_orbit_step=True, collision_controller='moments', moment_tolerance=.005, moment_reference_time=.005, rtol=1e-09, atol=1e-09, controller='i', pcoeff=0.4, icoeff=0.3, speed_floor=None, spatial_diffusion=None, spatial_geometry=None, orbit=True, electric_field=None, event=None, max_steps=100000, max_orbit_steps=10000, max_pending=64, record_steps=False, execution='shared', combined_tolerance=None, combined_length_scale=1., shared_clock=False, reuse_combined_orbit=True, combined_controller='rms', step_limit=None, + adjoint='none', adjoint_checkpoint_steps=16, adjoint_orbit_checkpoint_steps=16, + adjoint_max_accepted_steps=None, adjoint_max_orbit_steps=None, _record_ad=False, _replay_tapes=None, reverse_execution='auto'): + """Batched split tracing with optional accepted-map reverse differentiation. + +Returns a ``SplitSolution`` with shared ts and particle-leading arrays. GC states are +``(position[3], v_parallel, mu)`` with **physical** mu=m*v_perp^2/(2 B) +[J/T], unlike the legacy normalized collisional state. FullOrbit states +are ``(xyz, vx, vy, vz)``. VMEC/Boozer positions are (s, theta, zeta). +VMEC uses its regular axis chart; Boozer uses (sqrt(s)cos(theta), +sqrt(s)sin(theta)) internally. Both stop at the LCFS. Exterior continuation +is not part of this entry point. ``event`` receives public physical states. + +The default includes the existing paper Eq. (69) position diffusion for GC. +FullOrbit retains its particle collision map. Explicit ``spatial_diffusion=False`` +is retained for isolated operator diagnostics. VMEC uses its existing spatial +geometry; Boozer requires ``spatial_geometry=BoozerGeometry.from_booz_xform(b)`` +or an equivalent public-flux-coordinate to Cartesian map. Spatial kicks are +inverted nonlinearly in the regular chart, preserving the Cartesian update. +``orbit=False`` runs collision-only statistics. +``speed_floor`` defaults to 5% of the smallest active background thermal +speed for the test mass. The GC reflection wall affects near-zero speeds; +refine/check that parameter when studying the thermal population. + +Independent per-particle keys come from ``particles.random_keys``. The +field classes and existing Tracing/trace_boozer entry points are unchanged. + +``adjoint="accepted"`` records accepted outer/inner schedules and retained +Wiener increments. Reverse differentiates all accepted orbit/collision maps, +including spatial kicks, while freezing controller/rejection/event decisions. +``adjoint_orbit_checkpoint_steps`` bounds the live replay segment; the two +``adjoint_max_*`` options bound tape storage and raise on reverse overflow. +Independent forward execution keeps the same production GPU kernel. With +``reverse_execution="auto"``, uniform alpha/direct-coil cases use persistent +GPU reverse; other supported fields use checkpointed JAX reverse on the +selected device. Explicit ``"independent"`` rejects unsupported reverse cases. + + ``execution="independent"`` uses one persistent GPU program per particle. + It uses the same physical collision maps and moment predictor, including + background profiles, Coulomb-log selection and Cartesian GC spatial kicks. + It requires GPU float64, Threefry keys, zero electric field, Dopri8/I, + matching orbit/collision adaptation, and no step recording. Unsupported + GPU options raise; ``execution="shared"`` retains ordinary JAX execution. + + ``collision_controller="moments"`` is the adaptive default. It adds a + coupled mean/covariance interval ceiling while retaining native collision + checks at ``collision_tolerance`` and orbit checks at ``rtol/atol``. + ``moment_tolerance`` is a local predictor budget, not a global error bound. + + ``combined_tolerance`` enables experimental full-step/two-half-step control + on the shared Cartesian path. Position differences are scaled by + ``combined_length_scale`` [m]; velocity differences by birth speed, with + an additional pitch block for GC. This is a separate local budget from + collision_tolerance and RK rtol/atol. None retains the original method. + ``reuse_combined_orbit`` defaults to True; False retains independent + coarse/fine orbit integrations for comparison. It affects combined mode only. + ``combined_controller="rms"`` smooths squared defects for the next-step + proposal while retaining the existing per-trial checks. "i" is the old policy. + ``step_limit(t, y, args)`` optionally supplies a positive interval ceiling + in seconds using the current Cartesian physical state. It must not draw + fresh noise. This exposes solve_split's existing hook on the shared path; + an explicit callback replaces the default moment predictor. + ``shared_clock=True`` selects a native one-orbit-step/one-collision policy + for comparison, also limited to the shared Cartesian path without events. + """ + from .boozer import BoozerField, guiding_center_rhs + from .coils import Coils + from .fields import BiotSavart, Vmec + from .dynamics import _guiding_center_velocity, _axis_regular, _to_axis_regular, _from_axis_regular + from .electric_field import Electric_field_zero + from .constants import ELEMENTARY_CHARGE + + if adjoint not in ('none','accepted'): + raise ValueError("adjoint must be 'none' or 'accepted'") + if reverse_execution not in ('auto','shared','independent'): + raise ValueError("reverse_execution must be 'auto', 'shared' or 'independent'") + if (_record_ad and _replay_tapes is not None) or (adjoint!='none' and (_record_ad or _replay_tapes is not None)): + raise ValueError('record/replay and accepted AD are separate operations') + if adjoint=='accepted' and reverse_execution=='independent' and execution!='independent': + raise ValueError('independent reverse requires independent forward execution') + if adjoint=='accepted' or _record_ad: + from .native_ad import _validate_ad_sizes + _validate_ad_sizes(adjoint_checkpoint_steps=adjoint_checkpoint_steps, + adjoint_orbit_checkpoint_steps=adjoint_orbit_checkpoint_steps, + adjoint_max_accepted_steps=adjoint_max_accepted_steps,adjoint_max_orbit_steps=adjoint_max_orbit_steps) + if integrator not in ('essos_rk45', 'essos_dopri8'): + raise ValueError("split integrator must be 'essos_rk45' or 'essos_dopri8'") + if model not in ('GuidingCenter', 'FullOrbit'): + raise ValueError("split model must be 'GuidingCenter' or 'FullOrbit'") + if combined_controller not in ('i','rms'): + raise ValueError("combined_controller must be 'i' or 'rms'") + moment_control=collision_controller=='moments' and adaptive and step_limit is None and combined_tolerance is None and not shared_clock + if collision_controller=='moments': + collision_controller='conservative' + for name,value in (('moment_tolerance',moment_tolerance),('moment_reference_time',moment_reference_time)): + _concrete_check(value,lambda x:np.ndim(x)==0 and np.isfinite(x) and x>0,name+' must be positive and finite') + _concrete_check(collision_tolerance, lambda x: np.ndim(x) == 0 and np.isfinite(x) and (x > 0), 'collision_tolerance must be positive and finite') + if species is None: + raise ValueError('split collisions require BackgroundSpecies') + if species.number_species < 1: + raise ValueError('BackgroundSpecies must contain at least one species') + field = BiotSavart(field) if isinstance(field, Coils) else field + electric_field = Electric_field_zero() if electric_field is None else electric_field + if execution not in ('shared', 'independent'): + raise ValueError("split execution must be 'shared' or 'independent'") + boozer, vmec = (isinstance(field, BoozerField), isinstance(field, Vmec)) + if step_limit is not None and (execution != 'shared' or boozer or vmec): + raise ValueError('step_limit currently requires shared Cartesian tracing') + if shared_clock and (execution != 'shared' or boozer or vmec): + raise ValueError('shared_clock currently requires shared Cartesian tracing') + if combined_tolerance is not None: + if execution != 'shared' or boozer or vmec: + raise ValueError('combined control currently requires shared Cartesian tracing') + for name,value in (('combined_tolerance',combined_tolerance),('combined_length_scale',combined_length_scale)): + _concrete_check(value, lambda x: np.ndim(x)==0 and np.isfinite(x) and x>0, name+' must be positive and finite') + if orbit_stage_execution is None: + orbit_stage_execution = 'unrolled' if integrator == 'essos_dopri8' and model == 'GuidingCenter' and isinstance(field, BiotSavart) and (not adaptive) and (not orbit_adaptive) and (jax.default_backend() == 'gpu') else 'loop' + gc = model == 'GuidingCenter' + spatial_diffusion=gc if spatial_diffusion is None else spatial_diffusion + if not gc and (boozer or vmec): + raise ValueError('FullOrbit requires a Cartesian field') + if spatial_diffusion and (not gc or (boozer and spatial_geometry is None)): + raise ValueError('spatial_diffusion requires GC and Cartesian spatial_geometry for Boozer') + if boozer and (not isinstance(electric_field, Electric_field_zero)): + raise ValueError('Boozer split tracing does not yet support electric fields') + mass, charge = (particles.mass, particles.charge) + _concrete_check(mass, lambda x: np.isfinite(x) and x > 0, 'mass must be positive and finite') + _concrete_check(charge, lambda x: np.isfinite(x) and x != 0, 'charge must be finite and nonzero') + if times is None: + if isinstance(n_save, bool) or not isinstance(n_save, int) or n_save < 2: + raise ValueError('n_save must be an integer >= 2') + times = jnp.linspace(0.0, tmax, n_save) + times = jnp.asarray(times) + if times.ndim != 1: + raise ValueError('times must be one-dimensional') + if execution == 'independent': + _validate_independent(field, particles, species, model=model, integrator=integrator, adaptive=adaptive, orbit_adaptive=orbit_adaptive, controller=controller, collision_controller=collision_controller, electric_field=electric_field, spatial_diffusion=spatial_diffusion, orbit=orbit, record_steps=record_steps, reuse_orbit_step=reuse_orbit_step, event=event, times=times, tmax=tmax) + field_view = _split_field_data(field) if execution == 'independent' and isinstance(field,(BiotSavart,Vmec,BoozerField)) else None + moment_vmec_data=None + if vmec and moment_control and execution=='shared': + with jax.ensure_compile_time_eval(): + moment_vmec_data=_prepare_vmec_data(field) + + def magnitude(point,source=field): + return source.modB(*point) if boozer else source.AbsB(point) + + def public(y): + if vmec: + return _from_axis_regular(y) + if boozer: + return y.at[0].set(y[0] ** 2 + y[1] ** 2).at[1].set(jnp.arctan2(y[1], y[0])) + return y + + def spatial_position(y,source=field): + if boozer: + geometry=getattr(source,'to_xyz',spatial_geometry) + if hasattr(geometry,'regular_xyz'):return geometry.regular_xyz(y[:3]) + return geometry(public(y)[:3]) + return source.to_xyz(public(y)[:3]) if vmec else y[:3] + + def spatial_direction(y,B,source): + if vmec: + direction=_axis_regular(lambda t,q,a:jnp.concatenate((source.B_contravariant(q[:3]),jnp.zeros_like(q[3:]))))(0.,y,None) + tangent=jax.jvp(lambda q:spatial_position(q,source),(y,),(direction,))[1] + return tangent/jnp.linalg.norm(tangent) + if boozer: + (iota,G,I),_=source.profiles(public(y)[0]) + direction=jnp.zeros_like(y).at[:3].set(jnp.array([-y[1]*iota,y[0]*iota,1.])) + tangent=jax.jvp(lambda q:spatial_position(q,source),(y,),(direction,))[1] + return jnp.sign(G+iota*I)*tangent/jnp.linalg.norm(tangent) + return source.B_contravariant(y[:3])/B + + def gc_drift(t, y, args,source=field): + dx, dv = _guiding_center_velocity(source, electric_field, charge, mass, y[:3], y[3], mu=y[4]) + return jnp.concatenate([dx, jnp.array([dv, 0.0])]) + + def rhs(t, y, args,source=field): + if not orbit: + return jnp.zeros_like(y) + if boozer: + return jnp.append(guiding_center_rhs(source, y[:4], y[4] / mass, mass, charge), 0.0) + if vmec: + return _axis_regular(lambda t,y,a:gc_drift(t,y,a,source))(t, y, args) + if gc: + return gc_drift(t, y, args,source) + return jnp.concatenate([y[3:], charge / mass * (electric_field.E_covariant(y[:3]) + jnp.cross(y[3:], source.B_contravariant(y[:3])))]) + physical_rhs=rhs + if gc: + points = jnp.asarray(particles.initial_xyz) + b0 = jax.vmap(magnitude)(points) + _concrete_check(b0, lambda x: np.all(np.isfinite(x) & (x > 0)), 'birth |B| must be positive and finite') + _concrete_check(particles.initial_vparallel_over_v, lambda x: np.all(np.isfinite(x) & (np.abs(x) <= 1)), 'birth pitch must lie in [-1, 1]') + y0 = jnp.concatenate([points, particles.initial_vparallel[:, None], (mass * particles.initial_vperpendicular ** 2 / (2 * b0))[:, None]], axis=1) + if vmec: + y0 = jax.vmap(_to_axis_regular)(y0) + elif boozer: + _concrete_check(points[:, 0], lambda x: np.all(np.isfinite(x) & (x >= 0)), 'birth s must be nonnegative') + r = jnp.sqrt(points[:, 0]) + y0 = y0.at[:, 0].set(r * jnp.cos(points[:, 1])).at[:, 1].set(r * jnp.sin(points[:, 1])) + else: + if particles.initial_xyz_fullorbit is None or particles.initial_vxvyvz is None: + raise ValueError('FullOrbit requires initial full-orbit positions and velocities') + y0 = jnp.concatenate([jnp.asarray(particles.initial_xyz_fullorbit), jnp.asarray(particles.initial_vxvyvz)], axis=1) + if execution == "shared" and y0.shape[0]: + rhs = _prepare_rhs(rhs, jnp.zeros((), y0.dtype), y0[0], None) + def one(initial, key, tape=None): + birth = public(initial) + birth_speed = jnp.sqrt(birth[3] ** 2 + 2 * birth[4] * magnitude(birth[:3]) / mass) if gc else jnp.linalg.norm(birth[3:]) + if speed_floor is None: + thermal = jnp.stack([jnp.where(species.get_density(i, birth[:3]) > 0, jnp.sqrt(2 * ELEMENTARY_CHARGE * species.get_temperature(i, birth[:3]) / mass), jnp.inf) for i in range(species.number_species)]) + floor = 0.05 * jnp.min(thermal) + floor = jnp.where(jnp.isfinite(floor), floor, birth_speed * 1e-12) + else: + floor = jnp.asarray(speed_floor, dtype=initial.dtype) + + def kick(t, y, h, dw, args,source=field): + state = public(y) + point = state[:3] + B = magnitude(point,source) if gc else jnp.ones((), y.dtype) + speed = jnp.sqrt(state[3] ** 2 + 2 * state[4] * B / mass) if gc else jnp.linalg.norm(state[3:]) + c = collision_coefficients(species, mass, charge, speed, point, full_orbit=not gc) + if gc: + step = guiding_center_collision_step(speed, state[3] / speed, h, dw[-2:], c, tolerance=collision_tolerance, speed_floor=floor, return_error_model=adaptive and collision_controller == 'candidate') + v, pitch = step.y + if spatial_diffusion: + displacement=guiding_center_spatial_increment(state[3]/speed,dw[:3],c, + spatial_direction(y,B,source),charge*B/mass) + if vmec or boozer: + y=move_in_cartesian(y,displacement,lambda q:spatial_position(q,source), + implicit=adjoint=='accepted' and source is field) + point=public(y)[:3] + else: + point=point+displacement;y=y.at[:3].set(point) + B = magnitude(point,source) + result = y.at[3].set(v * pitch).at[4].set(mass * v * v * (1 - pitch * pitch) / (2 * B)) + else: + step = particle_collision_step(state[3:], h, dw, c, tolerance=collision_tolerance, return_error_model=adaptive and collision_controller == 'candidate') + result = y.at[3:].set(step.y) + valid_c = jnp.isfinite(jnp.asarray(c)).all() & (c.parallel >= 0) & (c.perpendicular >= 0) + result = jnp.where(jnp.isfinite(B) & (B > 0) & (speed > 0) & valid_c, result, jnp.full_like(result, jnp.nan)) + return step._replace(y=result) + + def position(y): + point = public(y)[:3] + return field.to_xyz(point) if vmec else point + + active_limit=step_limit + if moment_control and execution=='shared': + moment_position=position + if boozer: + moment_position=lambda y:y[:3] + elif vmec: + from .rk import _vmec_xyz_values + prepared=moment_vmec_data + moment_position=lambda y:jnp.asarray(_vmec_xyz_values(prepared.arrays,y[jnp.array([0,1,2,3,5])],prepared.tables)) + active_limit=native_step_limit(field,species,mass,charge,initial,rhs,public,moment_position,magnitude, + gc=gc,coordinate=vmec or boozer,boozer=boozer, + electric_field=electric_field,tmax=tmax,dtmax=timestep if collision_dtmax is None else collision_dtmax, + tolerance=moment_tolerance,reference_time=moment_reference_time,orbit=orbit) + + def collision_wiener_norm(dw): + return jnp.linalg.norm(dw[-2:]) if gc else jnp.abs(dw[2]) + norm = OrbitErrorNorm(rtol=rtol, atol=atol, speed_scale=birth_speed, velocity_components=1 if gc else 3, position_map=position if vmec else None) + combined_norm = None + if combined_tolerance is not None: + def combined_norm(coarse,fine): + delta_x=jnp.linalg.norm(fine[:3]-coarse[:3])/combined_length_scale + if gc: + def velocity(y): + speed=jnp.sqrt(y[3]**2+2*y[4]*magnitude(y[:3])/mass) + return speed,y[3]/speed + va,xa=velocity(coarse);vb,xb=velocity(fine) + delta_v=jnp.maximum(jnp.abs(va-vb)/birth_speed,jnp.abs(xa-xb)) + else: + delta_v=jnp.linalg.norm(fine[3:]-coarse[3:])/birth_speed + value=jnp.maximum(delta_x,delta_v)/combined_tolerance + return jnp.where((combined_tolerance>0)&(combined_length_scale>0)&jnp.isfinite(combined_tolerance)&jnp.isfinite(combined_length_scale),value,jnp.nan) + if boozer: + + def norm(a, b, error): + return jnp.maximum(jnp.linalg.norm(error[:2]), jnp.maximum(jnp.abs(error[2]), jnp.abs(error[3]) / birth_speed)) / (rtol + atol) + events = [] + if vmec or boozer: + events.append(lambda t, y, args: 1 - y[0] ** 2 - y[1] ** 2) + if event is not None: + events.extend([f if not (vmec or boozer) else + lambda t, y, args, f=f: f(t, public(y), args) for f in tree_util.tree_leaves(event)]) + if _replay_tapes is not None: + from .native_ad import replay_accepted_split + saved,final=replay_accepted_split(rhs,kick,initial,None,tape,times, + method='dopri5' if integrator=='essos_rk45' else 'dopri8',stage_execution=orbit_stage_execution) + return jax.vmap(public)(saved),public(final) + solve = solve_split + if execution == 'independent': + from functools import partial + def physics(source): + drift=lambda t,y,a:physical_rhs(t,y,a,source) + collision=lambda t,y,h,dw,a:kick(t,y,h,dw,a,source) + xyz=(lambda y:source.to_xyz(public(y)[:3])) if vmec else (lambda y:y[:3]) + measure=(lambda a,b,e:jnp.maximum(jnp.linalg.norm(e[:2]),jnp.maximum(jnp.abs(e[2]),jnp.abs(e[3])/birth_speed))/(rtol+atol)) if boozer else OrbitErrorNorm(rtol,atol,birth_speed,velocity_components=1 if gc else 3,position_map=xyz if vmec else None) + limit=native_step_limit(source,species,mass,charge,initial,drift,public,xyz,lambda p:magnitude(p,source), + gc=gc,coordinate=vmec or boozer,boozer=boozer, + electric_field=electric_field,tmax=tmax,dtmax=timestep if collision_dtmax is None else collision_dtmax, + tolerance=moment_tolerance,reference_time=moment_reference_time,orbit=orbit,reference_magnitude=magnitude) if moment_control else lambda t,y,a:jnp.asarray(jnp.inf) + level=lambda t,y,a:jnp.min(jnp.asarray([f(t,y,a) for f in events])) if events else jnp.asarray(1.,y.dtype) + return drift,collision,measure,level,limit + solve = partial(_solve_independent, field=field, species=species, gc=gc, birth_speed=birth_speed, speed_floor=floor, collision_tolerance=collision_tolerance, field_view=field_view,physics=physics,mass=mass,charge=charge,spatial_diffusion=spatial_diffusion,spatial_geometry=spatial_geometry,_reverse_execution=reverse_execution) + solution = solve(rhs, kick, initial, t1=tmax, dt0=timestep, ts=times, key=key, noise_dim=(5 if spatial_diffusion else 2) if gc else 3, dtmax=timestep if collision_dtmax is None else collision_dtmax, adaptive=adaptive, orbit_dt0=orbit_dt0, orbit_adaptive=orbit_adaptive, orbit_stage_execution=orbit_stage_execution, reuse_orbit_step=reuse_orbit_step, collision_controller=collision_controller, collision_wiener_norm=collision_wiener_norm, method='dopri5' if integrator == 'essos_rk45' else 'dopri8', rtol=rtol, atol=atol, controller=controller, pcoeff=pcoeff, icoeff=icoeff, error_norm=norm, combined_error_norm=combined_norm, shared_clock=shared_clock, reuse_combined_orbit=reuse_combined_orbit, combined_controller=combined_controller, step_limit=active_limit, align_orbit=moment_control and orbit_adaptive and reuse_orbit_step, event=tuple(events), max_steps=max_steps, max_orbit_steps=max_orbit_steps, max_pending=max_pending, record_steps=record_steps, _orbit_rhs_prepared=execution == "shared", + adjoint=adjoint,adjoint_checkpoint_steps=adjoint_checkpoint_steps, + adjoint_orbit_checkpoint_steps=adjoint_orbit_checkpoint_steps, + adjoint_max_accepted_steps=adjoint_max_accepted_steps,adjoint_max_orbit_steps=adjoint_max_orbit_steps, + _record_ad=_record_ad,_collision_state_indices=tuple(range(3,initial.size)) if not gc else None) + if _record_ad: + solution,tape=solution + return solution._replace(ys=jax.vmap(public)(solution.ys),y=public(solution.y)),tape + return solution._replace(ys=jax.vmap(public)(solution.ys), y=public(solution.y)) + if speed_floor is not None: + _concrete_check(speed_floor, lambda x: np.ndim(x) == 0 and np.isfinite(x) and (x > 0), 'speed_floor must be positive and finite') + if _replay_tapes is not None: + return jax.jit(jax.vmap(one))(y0,particles.random_keys,_replay_tapes) + if _record_ad: + solution,tapes=jax.jit(jax.vmap(one))(y0,particles.random_keys) + return solution._replace(ts=times),tapes + return jax.jit(jax.vmap(one))(y0, particles.random_keys)._replace(ts=times) + + + +# Independent GPU execution +from jax.extend.core import Literal +from .rk import (_select_one, _kernel_is_finite, _evaluate_inline, _bind_primitive, + _A8, _ERROR8, _DENSE8, _pack, _cross, _dot, _coil_geometry, + _coil_field_values, _coil_rhs_values, _prepare_vmec_data, _vmec_chart, + _vmec_series, _vmec_rhs_values, _vmec_xyz_values, _padded_spline, _KernelField) +from .constants import ALPHA_PARTICLE_MASS as M, ALPHA_PARTICLE_CHARGE as Q +from jax._src import random as jax_random +threefry = getattr(jax_random, "threefry2x32", None) or jax_random.prng + +def scalar(value, i): + return _select_one(value, i, 0).reshape(()) + +pack = _pack + +@lru_cache(maxsize=1) +def _kernel_erf(): + from jax.extend.core import Primitive + from jax._src.pallas.triton import lowering + from jax._src.interpreters import mlir + primitive = Primitive("essos_split_erf") + primitive.def_abstract_eval(lambda value: value) + primitive.def_impl(lax.erf) + mlir.register_lowering(primitive, mlir.lower_fun(lax.erf, multiple_results=False)) + lowering.register_lowering(primitive)(lowering._make_dispatch_table( + "erf", cuda=[lowering._Extern([jnp.float64], "__nv_erf", jnp.float64), + lowering._Extern([jnp.float32], "__nv_erff", jnp.float32)])) + return primitive + + +def _split_select(value, index, axis): + if value.dtype == jnp.bool_: + shape = [1] * value.ndim + shape[axis] = value.shape[axis] + return jnp.max((value & (jnp.arange(value.shape[axis]).reshape(shape) == index)).astype(jnp.int32), axis=axis, keepdims=True) > 0 + return _select_one(value, index, axis) + +def _flatten(function, *examples): + from jax._src.core import DropVar + from jax._src.interpreters import partial_eval + graph = jax.make_jaxpr(function)(*examples) + graph = jax.make_jaxpr(lambda *x: _evaluate_inline(graph.jaxpr, graph.consts, *x))(*examples) + aliases,expressions,kept={},{},[] + def freeze(value): + if isinstance(value,dict):return tuple((k,freeze(v)) for k,v in sorted(value.items())) + if isinstance(value,(tuple,list)):return tuple(freeze(v) for v in value) + if isinstance(value,np.ndarray):return value.dtype.str,value.shape,value.tobytes() + hash(value) + return value + def operand(value): + if not isinstance(value,Literal):return aliases.get(value,value) + data=np.asarray(value.val) + return ('literal',data.dtype.str,data.shape,data.tobytes(),value.aval.weak_type) + for eq in graph.jaxpr.eqns: + inputs=[v if isinstance(v,Literal) else aliases.get(v,v) for v in eq.invars] + key=None + if not eq.effects: + try:key=eq.primitive,tuple(operand(v) for v in inputs),freeze(eq.params) + except TypeError:pass + if key is not None and key in expressions: + index=expressions[key];previous=kept[index] + # Retain newly used outputs when an earlier identical call dropped + # them. A DropVar must never become an input alias. + outputs=[new if isinstance(old,DropVar) else old for old,new in zip(previous.outvars,eq.outvars)] + kept[index]=previous.replace(outvars=outputs) + aliases.update((new,old) for new,old in zip(eq.outvars,outputs) if not isinstance(new,DropVar)) + else: + kept.append(eq.replace(invars=inputs)) + if key is not None:expressions[key]=len(kept)-1 + graph=type(graph)(graph.jaxpr.replace(eqns=kept,outvars=[v if isinstance(v,Literal) else aliases.get(v,v) for v in graph.jaxpr.outvars]),graph.consts) + live,_=partial_eval.dce_jaxpr(graph.jaxpr,[True]*len(graph.jaxpr.outvars),instantiate=True) + return type(graph)(live,graph.consts) + +def _kernel_integer_power(value, exponent): + """Use the same power-by-squaring order with literal-safe GPU operations.""" + if exponent == 0: + return jnp.ones_like(value) + reciprocal = exponent < 0 + exponent = abs(exponent) + result = None + while exponent: + exponent, odd = divmod(exponent, 2) + if odd: + result = value if result is None else result * value + if exponent: + value = value * value + return jnp.ones_like(result) / result if reciprocal else result + + +def _evaluate_kernel(graph, constants, *arguments, scalarize=False): + literals={} + def local_constant(value): + if not isinstance(value,np.ndarray) or not value.ndim:return value + key=value.dtype.str,value.shape,value.tobytes() + if key not in literals: + first=value.flat[0] + if np.issubdtype(value.dtype,np.number) and value.tobytes()==np.arange(value.size,dtype=value.dtype).tobytes(): + result=jnp.arange(value.size,dtype=value.dtype).reshape(value.shape) + else: + result=jnp.full(value.shape,first.item(),dtype=value.dtype) + index=jnp.arange(value.size).reshape(value.shape) + for i,item in enumerate(value.flat): + if item.tobytes()!=first.tobytes(): + result=jnp.where(index==i,jnp.asarray(item.item(),dtype=value.dtype),result) + literals[key]=result + return literals[key] + def shrink(value): + return value.reshape(()) if scalarize and getattr(value, 'size', 0) == 1 else value + constants = tuple((shrink(v) for v in constants)) + env = dict(zip(graph.constvars, constants)) + env.update(zip(graph.invars, arguments)) + + def read(v): + return np.asarray(v.val, dtype=v.aval.dtype) if isinstance(v, Literal) else env[v] + for eq in graph.eqns: + vals = [read(v) for v in eq.invars] + name, p = (eq.primitive.name, eq.params) + if scalarize and len(eq.outvars) == 1 and (eq.outvars[0].aval.size == 1): + if name in ('broadcast_in_dim', 'reshape', 'squeeze', 'slice', 'dynamic_slice', 'gather', 'reduce_sum', 'reduce_or', 'reduce_and', 'stack'): + if vals[0].size == 1: + env[eq.outvars[0]] = shrink(vals[0]) + continue + if name == 'dynamic_update_slice' and vals[0].size == vals[1].size == 1: + env[eq.outvars[0]] = shrink(vals[1]) + continue + numpy_ops = {'add': np.add, 'add_any': np.add, 'sub': np.subtract, 'mul': np.multiply, 'div': np.divide, 'neg': np.negative, 'abs': np.abs, 'sqrt': np.sqrt, 'log': np.log, 'exp': np.exp, 'pow': np.power, 'square': np.square, 'max': np.maximum, 'min': np.minimum, 'lt': np.less, 'le': np.less_equal, 'gt': np.greater, 'ge': np.greater_equal, 'eq': np.equal, 'ne': np.not_equal, 'and': np.bitwise_and, 'or': np.bitwise_or} + if all((not isinstance(v, jax.core.Tracer) for v in vals)): + vals=[np.asarray(value) for value in vals] + folded = None + if name in numpy_ops: + folded = [numpy_ops[name](*vals)] + elif name == 'integer_pow': + folded = [np.power(vals[0], p['y'])] + elif name == 'convert_element_type': + folded = [np.asarray(vals[0], dtype=p['new_dtype'])] + elif name == 'broadcast_in_dim': + shape=[1]*len(p['shape']) + for i,axis in enumerate(p['broadcast_dimensions']):shape[axis]=vals[0].shape[i] + folded=[np.broadcast_to(np.reshape(vals[0],shape),p['shape'])] + elif name in ('reshape','squeeze','transpose'): + value=vals[0] + dimensions=p.get('dimensions') if name=='reshape' else p.get('permutation') if name=='transpose' else None + if dimensions is not None:value=np.transpose(value,dimensions) + folded=[np.reshape(value,eq.outvars[0].aval.shape)] + elif name=='iota': + shape=[1]*len(p['shape']);shape[p['dimension']]=p['shape'][p['dimension']] + folded=[np.broadcast_to(np.arange(shape[p['dimension']],dtype=p['dtype']).reshape(shape),p['shape'])] + elif name in ('concatenate','stack'): + folded=[(np.concatenate if name=='concatenate' else np.stack)(vals,axis=p.get('dimension',p.get('axis')))] + if folded is not None: + env.update(((out, np.asarray(value, dtype=out.aval.dtype)) for out, value in zip(eq.outvars, folded))) + continue + vals=[local_constant(value) for value in vals] + if name == 'slice': + value = vals[0] + for axis, (start, end, size) in enumerate(zip(p['start_indices'], p['limit_indices'], value.shape)): + if start != 0 or end != size: + if end - start != 1: + raise ValueError(('slice', p)) + value = _split_select(value, start, axis) + result = [value] + elif name == 'dynamic_slice': + value = vals[0] + for axis, (index, size, wanted) in enumerate(zip(vals[1:], value.shape, p['slice_sizes'])): + if size != wanted: + if wanted != 1: + raise ValueError(('dynamic slice', p)) + value = _split_select(value, jnp.clip(index, 0, size - 1), axis) + result = [value] + elif name == 'gather' and vals[0].ndim == 1 and (p['slice_sizes'] == (1,)): + operand, indices = vals + if indices.size != 1: + raise ValueError(('gather indices', indices.shape, p)) + index = jnp.clip(indices.reshape(()), 0, len(operand) - 1) + result = [_split_select(operand, index, 0).reshape(eq.outvars[0].aval.shape)] + elif name == 'stack' and len(vals) == 1: + result = [jnp.expand_dims(vals[0], p['axis'])] + elif name == 'unstack': + result = [_split_select(vals[0], i, p['axis']).reshape(out.aval.shape) for i, out in enumerate(eq.outvars)] + elif name == 'split' and vals[0].ndim == 1 and all((out.aval.size == 1 for out in eq.outvars)): + result = [_split_select(vals[0], i, 0).reshape(out.aval.shape) for i, out in enumerate(eq.outvars)] + elif name == 'reduce_or': + result = [jnp.max(vals[0].astype(jnp.int32), axis=p['axes']) > 0] + elif name == 'reduce_and': + result = [jnp.min(vals[0].astype(jnp.int32), axis=p['axes']) > 0] + elif name == 'add_any': + result = [vals[0] + vals[1]] + elif name == 'pad' and vals[0].size == 1 and (len(p['padding_config']) == 1): + low, _, _ = p['padding_config'][0] + result = [jnp.where(jnp.arange(eq.outvars[0].aval.size) == low, vals[0].reshape(()), vals[1])] + elif name == 'erf': + result = [_kernel_erf().bind(vals[0])] + elif name == 'integer_pow': + result = [_kernel_integer_power(vals[0], p['y'])] + elif name == 'le_to': + result = [jnp.less_equal(vals[0], vals[1]) | jnp.isnan(vals[1])] + elif name in ('concatenate', 'stack') and (len(vals) > 2 or (scalarize and all((v.size == 1 for v in vals)))): + outshape = eq.outvars[0].aval.shape + if any((v.size != 1 for v in vals)): + raise ValueError(('concatenate', p)) + result = jnp.zeros((len(vals),), vals[0].dtype) + for i, v in enumerate(vals): + result = jnp.where(jnp.arange(len(vals)) == i, v.reshape(()), result) + result = [result.reshape(outshape)] + elif name == 'is_finite': + result = [_kernel_is_finite(vals[0]) if isinstance(vals[0], jax.core.Tracer) else np.isfinite(vals[0])] + else: + parameters = dict(p) + if name == 'convert_element_type' and parameters.get('weak_type'): + parameters['weak_type'] = False + result = _bind_primitive(eq.primitive, vals, parameters) + if not eq.primitive.multiple_results: + result = [result] + env.update(((v, shrink(value)) for v, value in zip(eq.outvars, result))) + return tuple((read(v) for v in graph.outvars)) + +def _evaluate_surface(graph, constants, state): + """Scalarize short state-vector operations in a spatial level set. + + A physical five/six-vector is represented as scalar components, avoiding + non-power-of-two local arrays. This covers scalar indexing, vector norms + and dot products used by the toroidal/spherical safety surfaces. + """ + word = lambda value, i: _select_one(value, i, 0).reshape(()) + env = dict(zip(graph.constvars, constants)) + env[graph.invars[0]] = tuple((word(state, i) for i in range(graph.invars[0].aval.size))) + + def read(var): + return np.asarray(var.val, dtype=var.aval.dtype) if isinstance(var, Literal) else env[var] + for eq in graph.eqns: + values = [read(var) for var in eq.invars] + name, p = (eq.primitive.name, eq.params) + vector = lambda x: isinstance(x, tuple) + if name == 'slice' and vector(values[0]): + result = [values[0][p['start_indices'][0]:p['limit_indices'][0]:None if p.get('strides') is None else p['strides'][0]]] + elif name == 'squeeze' and vector(values[0]) and (len(values[0]) == 1): + result = [values[0][0]] + elif name == 'unstack': + result = list(values[0]) + elif name in ('stack', 'concatenate'): + result = [tuple((item for value in values for item in (value if vector(value) else (value,))))] + elif name in ('reshape', 'broadcast_in_dim'): + size = eq.outvars[0].aval.size + result = [values[0] if vector(values[0]) else (values[0],) * size] + if not eq.outvars[0].aval.shape: + result = [result[0][0]] + elif name in ('reduce_sum', 'reduce_max', 'reduce_min') and vector(values[0]): + value = values[0][0] + combine = {'reduce_sum': lambda a, b: a + b, 'reduce_max': jnp.maximum, 'reduce_min': jnp.minimum}[name] + for item in values[0][1:]: + value = combine(value, item) + result = [value] + elif name == 'dot_general' and all((vector(value) for value in values)): + result = [sum((a * b for a, b in zip(*values)))] + elif name == 'gather' and vector(values[0]) and (len(values[1]) == 1): + index = values[1][0] + value = values[0][0] + for i, item in enumerate(values[0]): + value = jnp.where(index == i, item, value) + result = [(value,) if eq.outvars[0].aval.shape else value] + else: + parameters = dict(p) + if name == 'convert_element_type': + parameters['weak_type'] = False + if any((vector(value) for value in values)): + width = max((len(value) for value in values if vector(value))) + elements = [] + for i in range(width): + elements.append(_bind_primitive(eq.primitive, [value[i] if vector(value) else value for value in values], parameters)) + result = [tuple(elements)] + else: + value = _bind_primitive(eq.primitive, values, parameters) + result = value if eq.primitive.multiple_results else [value] + env.update(zip(eq.outvars, result)) + result = read(graph.outvars[0]) + return result[0] if isinstance(result, tuple) else result + +def _draw_normal(key, dim): + if not jax.config.jax_threefry_partitionable: + raise ValueError('The exact adapter currently requires partitionable Threefry') + word = lambda a, i: _select_one(a, i, 0).reshape(()) + k0, k1 = (word(key, 0), word(key, 1)) + a, b = threefry._threefry2x32_lowering(k0, k1, jnp.asarray(0, jnp.uint32), jnp.arange(2, dtype=jnp.uint32), use_rolled_loops=False) + next_key = jnp.where(jnp.arange(2) == 0, word(a, 0), word(b, 0)) + d0, d1 = (word(a, 1), word(b, 1)) + padded = 1 << (dim - 1).bit_length() + hi, lo = threefry._threefry2x32_lowering(d0, d1, jnp.asarray(0, jnp.uint32), jnp.arange(padded, dtype=jnp.uint32), use_rolled_loops=False) + bits = hi.astype(jnp.uint64) << jnp.uint64(32) | lo.astype(jnp.uint64) + unit = jax.lax.bitcast_convert_type(bits >> jnp.uint64(12) | jnp.uint64(4607182418800017408), jnp.float64) - 1.0 + lower = np.nextafter(np.float64(-1.0), np.float64(0.0)) + uniform = jnp.maximum(lower, unit * (1.0 - lower) + lower) + return (next_key, jnp.sqrt(jnp.asarray(2.0, jnp.float64)) * jax.lax.erf_inv(uniform)) + +@lru_cache(None) +def _register_kernel_placement(): + """Lower unspecified JAX placement as identity on already resident values.""" + from jax._src.dispatch import device_put_p + from jax._src.pallas.triton import lowering + if device_put_p in lowering.triton_lowering_rules: + return lowering.triton_lowering_rules[device_put_p] + @lowering.register_lowering(device_put_p) + def placement(ctx,*values,**parameters): + if any(v is not None for name in ('devices','srcs') for v in parameters.get(name,())): + raise NotImplementedError('explicit device transfers are unsupported inside native GPU kernels') + return values + return placement + + +def _prepare_split_kernel(arrays, factory, times, *, adaptive, dt0, dtmax, speed, tolerance=1e-09, noise_dim=2, max_steps=100000, max_orbit_steps=10000, max_pending=64, warps=1, state_size=8, bank_components=8, orbit_dt0=None, final_time=None, align_orbit=False, interpret=False, + record=False, adjoint_checkpoint_steps=16, adjoint_orbit_checkpoint_steps=16, + adjoint_max_accepted_steps=None, adjoint_max_orbit_steps=None, collision_indices=None): + """Persistent particle loop; factory also supplies the optional predictor.""" + from jax.experimental import pallas as pl + from jax.experimental.pallas import triton as plt + if not interpret:_register_kernel_placement() + times = jnp.asarray(times, jnp.float64) + nsave, stages, bank_size = (len(times), len(_ERROR8), 16) + matrix = np.zeros((bank_size, bank_size)) + for i, row in enumerate(_A8, 1): + matrix[i, :len(row)] = row + dense = np.zeros((len(_DENSE8[0]), bank_size)) + dense[:, :stages] = np.asarray(_DENSE8).T + inputs = tuple(arrays) + (jnp.asarray(matrix), jnp.asarray(dense), jnp.asarray(tuple(_ERROR8) + (0.0,) * (bank_size - stages)), jnp.asarray(times), jnp.asarray([0.0, dt0, dtmax, times[-1] if final_time is None else final_time, speed, 2 * tolerance, dt0 if orbit_dt0 is None else orbit_dt0], jnp.float64)) + capacity = max_pending if adaptive else 1 + noise_size = 1 << (noise_dim - 1).bit_length() + + if record: + from .native_ad import _SplitCheckpointTape, _TapeView + outer_capacity = min(max_steps,adjoint_max_accepted_steps or max_steps) + inner_capacity = adjoint_max_orbit_steps or max_steps + inner_segment = adjoint_orbit_checkpoint_steps + outer_segment = adjoint_checkpoint_steps + if collision_indices is None: + node_capacity = (inner_capacity+inner_segment-1)//inner_segment+outer_capacity-1 + derivative_capacity = node_capacity + else: + nonempty_maps = min(outer_capacity,inner_capacity) + node_capacity = nonempty_maps+(inner_capacity-nonempty_maps)//inner_segment + derivative_capacity = (inner_capacity-1)//inner_segment + endpoint_size = 8 if collision_indices is None else len(collision_indices) + shape = lambda dims,dtype=jnp.float64:jax.ShapeDtypeStruct(dims,dtype) + tape_shapes = _SplitCheckpointTape( + shape((outer_capacity,2)),shape((outer_capacity,noise_dim)),shape((outer_capacity,),jnp.bool_), + shape((outer_capacity+1,),jnp.int32),shape((inner_capacity,2)),shape((outer_capacity,)), + shape(((outer_capacity+outer_segment-1)//outer_segment,8)), + shape((),jnp.int32),shape((),jnp.int32),shape((),jnp.int32),shape((),jnp.int32),shape((),jnp.int32), + shape((outer_capacity+1,),jnp.int32),shape((node_capacity,8)), + shape((derivative_capacity,8)),shape((outer_capacity,endpoint_size)),shape((),jnp.int32)) + padded_tape_shapes = tuple(shape(tuple(1< 0 if isinstance(x,jax.core.Tracer) else jnp.asarray(np.isfinite(x).all()) + bi = jnp.arange(bank_size)[:, None] + + def polynomial(y, endpoint, bank, fraction): + weights = jnp.zeros((bank_size,), y.dtype) + for power in range(dense.shape[0]): + weights = weights * fraction + dref[power, :] + result = y + expand(jnp.sum((weights * fraction)[:, None] * bank, axis=0)) + return jnp.where(fraction == 0, y, jnp.where(fraction == 1, endpoint, result)) + + def orbit(y, t, end, guess, outer_index, inner_index, node_index): + old = level(y) + start = (t, y, dynamic_rhs(y), jnp.minimum(guess, end - t), old, integer(0), integer(0), integer(0)) + ((zero+1,) if record else ()) + + def step(c): + t, y, f0, guess, old, status, trials, rejected = c[:8] + last_fraction = c[8] if record else zero+1 + remaining = end - t + h = jnp.minimum(guess, remaining) + close = remaining - h <= 8 * jnp.finfo(y.dtype).eps * jnp.maximum(jnp.abs(t), jnp.abs(end)) + h = jnp.where(close, remaining, h) + stop = jnp.where(h == remaining, end, t + h) + bank = jnp.where(bi == 0, h * f0[None, :], jnp.zeros((bank_size, bank_components), y.dtype)) + + def stage(i, carry): + bank, _, checked = carry + contribution = jnp.where(bi < i, aref[i, :][:, None] * bank, 0.0) + yi = y + expand(jnp.sum(contribution, axis=0)) + fi = dynamic_rhs(yi) + increment = h * fi + return (jnp.where(bi == i, increment[None, :], bank), fi, checked & finite(increment) & finite(fi)) + bank, f1, stage_finite = jax.lax.fori_loop(1, stages, stage, (bank, f0, finite(h * f0) & finite(f0))) + endpoint = y + expand(jnp.sum(jnp.where(bi < stages - 1, aref[stages - 1, :][:, None] * bank, 0.0), axis=0)) + embedded = expand(jnp.sum(jnp.where(bi < stages, eref[...][:, None] * bank, 0.0), axis=0)) + error = norm(endpoint, embedded, birth_speed, budget) if adaptive else zero + new = level(endpoint) + valid = finite(endpoint) & stage_finite & finite(f1) & finite(embedded) & finite(error) & finite(new) & (error >= 0) + accept = valid & ((error <= 1) | (not adaptive)) & (stop > t) + crossing = accept & (((old > 0) != (new > 0)) | (new == 0)) + factor = jnp.where(valid, jnp.clip(0.9 * jnp.maximum(error, 1e-16) ** (-1 / 8), 0.2, 5.0), 0.2) + proposal = h * jnp.where(accept, factor, jnp.minimum(factor, 0.9)) if adaptive else first_orbit_h + + def bisect(c): + lo, hi, i, ok = c + mid = (lo + hi) / 2 + value = level(polynomial(y, endpoint, bank, mid)) + same = (value > 0) == (old > 0) + return (jnp.where(same, mid, lo), jnp.where(same, hi, mid), i + 1, ok & finite(value)) + lo, hi, _, ok = jax.lax.while_loop(lambda c: crossing & c[3] & (c[2] < 52), bisect, (zero, zero + 1, integer(0), jnp.asarray(True))) + root = (lo + hi) / 2 + failed_root = crossing & ~ok + accept &= ~failed_root + proposal = jnp.where(failed_root, 0.2 * h, proposal) + stop_y = jax.lax.cond(crossing, lambda _: polynomial(y, endpoint, bank, root), lambda _: endpoint, None) + stuck = (stop <= t) | ~accept & ((h <= 0) | (t + proposal <= t)) + status = jnp.where(crossing & ok, 1, jnp.where(stuck, jnp.where(valid, 3, 4), 0)).astype(jnp.int32) + if not adaptive: + status = jnp.where(~valid, 4, status) + if record: + local_index = trials-rejected + slot = inner_index+local_index + node = node_index+local_index//inner_segment + def save_step(_): + tape_refs['orbit_times'][slot,0] = t + tape_refs['orbit_times'][slot,1] = h + def checkpoint(_): + tape_refs['orbit_states'][node,:] = y + if collision_indices is None: + tape_refs['orbit_derivatives'][node,:] = expand(f0) + elif derivative_capacity: + def derivative(_): + tape_refs['orbit_derivatives'][node-outer_index-1,:] = expand(f0) + jax.lax.cond(local_index>0,derivative,lambda _:None,None) + jax.lax.cond(local_index%inner_segment==0,checkpoint,lambda _:None,None) + jax.lax.cond(accept&(outer_index 0) & finite(first_h) & (ceiling > 0) & ~jnp.isnan(ceiling) & (first_orbit_h > 0) & finite(first_orbit_h) & (birth_speed > 0) & finite(birth_speed) & (budget > 0) & finite(budget) & (final_t >= 0) & finite(final_t) + previous = zero + for i in range(nsave): + stamp = tsref[i] + valid_inputs &= finite(stamp) & (stamp >= previous) & (stamp <= final_t) + previous = stamp + initial_status = jnp.where(valid_inputs, jnp.where(finite(y0) & finite(level(y0)), jnp.where(level(y0) <= 0, 1, 0), 4), 5).astype(jnp.int32) + index = save(y0, zero, integer(0)) + if record: + tape_refs['initial_saves'][...] = index + start = (zero, y0, jnp.minimum(first_h, ceiling), first_orbit_h, kref[...], integer(0), integer(0), index, integer(0), initial_status, integer(0), integer(0), integer(0), integer(0), integer(0), zero,integer(0),integer(0)) + ((integer(0),)*3 if record else ()) + + def advance(c): + t, y, h, oh, key, size, peak, index, grid, status, trials, accepted, rejected, ot, orr, maxerr,path_steps,path_max = c[:18] + ad_count,ad_inner,ad_nodes = c[18:] if record else (integer(0),)*3 + barrier = jnp.where(index < nsave, tsref[jnp.minimum(index, nsave - 1)], final_t) + limit=step_limit(t,y) if adaptive and step_limit is not None else zero+jnp.inf + valid_limit=(limit>0)&~jnp.isnan(limit) + if adaptive: + wanted = jnp.minimum(t + jnp.minimum(h,limit), barrier) + if align_orbit: + length=wanted-t + near=finite(oh)&(oh>0)&(wanted=.9*length)&(oh0,lambda _:ends[size-1],lambda _:wanted,None) + draw=(size==0)|((wanted 0) & (end > t) + + def attempt(_): + stop, endpoint, next_oh, os, orbit_trials, orbit_rejected, fraction = orbit(y, t, end, jnp.minimum(oh, h) if adaptive else jnp.minimum(first_orbit_h, h), ad_count, ad_inner, ad_nodes) + + def collide(_): + return kick(endpoint, h, increments[size - 1, :]) + trial, ed, es = jax.lax.cond(os == 0, collide, lambda _: (endpoint, zero, zero), None) + valid = finite(trial) & finite(level(trial)) & finite(ed) & finite(es) & (ed >= 0) & (es >= 0) + error = jnp.maximum(ed, es) + accept = (os == 0) & valid & ((error <= 1) | (not adaptive)) + reject = (os == 0) & valid & ~accept + event = os == 1 + ns = jnp.where(os != 0, os, jnp.where(~valid, 4, jnp.where(accept & (level(trial) <= 0), 1, 0))).astype(jnp.int32) + if adaptive: + factor = 0.9 * jnp.minimum(jnp.maximum(ed, 1e-30) ** (-0.5), jnp.maximum(es, 1e-30) ** (-2 / 3)) + upper = jnp.where(accept, zero + 1.5, zero + 0.9) + factor = jnp.maximum(zero + 0.1, jnp.minimum(factor, upper)) + nh = jnp.minimum(h * factor, ceiling) + else: + nh = first_h + nt = jnp.where(event, stop, jnp.where(accept, end, t)) + ny = jnp.where(event, endpoint, jnp.where(accept, trial, y)) + ni = save(ny, nt, index) + committed = accept|event + inner_count = orbit_trials-orbit_rejected + if record: + nodes = (inner_count+inner_segment-1)//inner_segment + def commit(_): + tape_refs['times'][ad_count,0],tape_refs['times'][ad_count,1] = t,nt + for component in range(noise_dim): + tape_refs['increments'][ad_count,component] = increments[size-1,component] + tape_refs['kicks'][ad_count] = accept + tape_refs['offsets'][ad_count+1] = ad_inner+inner_count + tape_refs['checkpoint_offsets'][ad_count+1] = ad_nodes+nodes + tape_refs['fractions'][ad_count] = fraction + endpoint_components = range(8) if collision_indices is None else collision_indices + for component,index_ in enumerate(endpoint_components): + tape_refs['orbit_endpoints'][ad_count,component] = scalar(endpoint,index_) + def outer_checkpoint(_): + tape_refs['states'][ad_count//outer_segment,:] = y + jax.lax.cond(ad_count%outer_segment==0,outer_checkpoint,lambda _:None,None) + jax.lax.cond(committed&(ad_count0)&(value<=axis[index]),index-1,index) + index=jnp.where((indexaxis[index+1]),index+1,index) + else: + def search(_, bounds): + low, high = bounds + middle = (low+high)//2 + below = axis[jnp.minimum(middle,n-1)] < value + return jnp.where(below,middle+1,low),jnp.where(below,high,middle) + insertion, _ = lax.fori_loop(0,n.bit_length(),search,(jnp.int32(0),jnp.int32(n))) + index = jnp.clip(insertion-1,0,n-2) + indices.append(index) + fractions.append((value-axis[index])/(axis[index+1]-axis[index])) + outside |= (valueaxis[n-1]) + result = jnp.asarray(0., y.dtype) + for corner in range(8): + index, weight = jnp.int32(0), jnp.asarray(1., y.dtype) + for axis, (start, fraction, n) in enumerate(zip(indices,fractions,shape)): + high = (corner>>(2-axis))&1 + index = index*n+start+high + weight *= fraction if high else 1-fraction + result += weight*refs[3][jnp.clip(index,0,int(np.prod(shape))-1)] + distance=jnp.where(outside,refs[4][()],result) + return jnp.maximum(0.,distance+refs[5][()]) if stopping else distance + return arrays, level + + +def _prepare_split_field(field, species, *, gc, collision_tolerance, speed_floor, + event=None, state_size=5, field_view=None,mass=M,charge=Q,spatial_diffusion=False): + """Reuse the orbit PR's private field views, carrying physical mu per kick.""" + from .fields import BiotSavart, Vmec + from .boozer import guiding_center_rhs + coil, vmec = isinstance(field, BiotSavart), isinstance(field, Vmec) + if spatial_diffusion and (not gc or not coil): + raise ValueError('the native coordinate adapter does not yet transform GC spatial diffusion') + arrays, metadata = _split_field_data(field) if field_view is None else field_view + if coil: + nc, nq = metadata + nfield = len(arrays) + cg = _coefficient_graph(species, not gc,mass,charge) + # Keep the per-particle floor as explicit data, not a captured map constant. + def gc_map(v, xi, h, dw, floor, *c): + out = guiding_center_collision_step(v, xi, h, dw, CollisionCoefficients(*c), + tolerance=collision_tolerance, speed_floor=floor) + return out.y, out.drift_error, out.diffusion_error + gg = _flatten(gc_map, jnp.asarray(4e5), jnp.asarray(.5), jnp.asarray(1e-7), + jnp.zeros(2),jnp.asarray(0.), *(jnp.asarray(1.),)*6) if gc else None + functions = tree_util.tree_leaves(event) + tables = [function._kernel_view() for function in functions if isinstance(function,ClassifierStop)] + functions = [function for function in functions if not isinstance(function,ClassifierStop)] + eg = _flatten(lambda y: jnp.min(jnp.asarray([f(0., y, None) for f in functions])), + jnp.zeros(state_size)) if functions else None + event_arrays = [] + if eg is not None: + for value in eg.consts: + if value.ndim > 1: + raise ValueError("independent stopping surfaces require scalar/vector constants") + event_arrays.append(value if value.ndim == 0 else + jnp.pad(value, (0, (1 << (value.size-1).bit_length())-value.size))) + all_arrays = (tuple(arrays)+tuple(cg.consts)+(tuple(gg.consts)+(jnp.asarray(speed_floor),) if gc else ())+tuple(event_arrays) + +tuple(value for values,_ in tables for value in values)) + + def factory(refs, y0): + frefs = refs[:nfield] + ci = nfield+len(cg.consts) + cc = [ref[...] for ref in refs[nfield:ci]] + mc = [ref[...] for ref in refs[ci:ci+len(gg.consts)+1]] if gc else () + event_start = ci+(len(gg.consts)+1 if gc else 0) + erefs = refs[event_start:event_start+len(event_arrays)] + ec = ([ref[...] if value.ndim == 0 else tuple(scalar(ref[...], i) for i in range(value.size)) + for ref, value in zip(erefs, eg.consts)] if eg is not None else ()) + zero = scalar(y0, 7) + def orbit_state(y): + return pack(tuple(scalar(y, i) for i in (0, 1, 2, 3, 5))+(zero, zero, zero)) + if coil: + def rhs(y): + value = _coil_rhs_values(frefs, y, nc, nq, "gc" if gc else "lorentz", 0., mass, charge,scalar(y,4) if gc else None) + return pack(tuple(scalar(value, i) for i in range(4))+(zero, zero, zero, zero)) if gc else value + def magnitude(y): + B, _ = _coil_field_values(frefs, tuple(scalar(y, i) for i in range(3)), nc, nq, False) + return jnp.sqrt(_dot(B, B)) + def norm(y, e, speed, budget): + pos = jnp.sqrt(sum(scalar(e, i)**2 for i in range(3))) + vel = jnp.abs(scalar(e, 3)) if gc else jnp.sqrt(sum(scalar(e, i)**2 for i in range(3, 6))) + return jnp.maximum(pos, vel/speed)/budget + elif vmec: + def rhs(y): + value = _vmec_rhs_values(frefs, orbit_state(y), metadata, mass, charge,0.,scalar(y,4)) + return pack(tuple(scalar(value, i) for i in range(4))+(zero, scalar(value, 4), zero, zero)) + magnitude = lambda y: _vmec_series(frefs, _vmec_chart(orbit_state(y)), metadata['bmnc'])[0] + def norm(y, e, speed, budget): + a = _vmec_xyz_values(frefs, orbit_state(y), metadata) + b = _vmec_xyz_values(frefs, orbit_state(y-e), metadata) + return jnp.maximum(jnp.sqrt(sum((u-v)**2 for u, v in zip(a, b))), jnp.abs(scalar(e, 3))/speed)/budget + else: + model = _KernelField(frefs, float(field.psi0)) + def physical(y): + value = guiding_center_rhs(model, y, y[4]/mass, mass, charge) + return pack(tuple(value[i] for i in range(4))+(zero, zero, zero, zero)) + graph = _flatten(physical, y0) + rhs = lambda y: _evaluate_kernel(graph.jaxpr, graph.consts, y)[0] + bg = _flatten(lambda y: model.modB_derivatives(jnp.sqrt(y[0]**2+y[1]**2), + jnp.arctan2(y[1], y[0]), y[2])[0], y0) + magnitude = lambda y: _evaluate_kernel(bg.jaxpr, bg.consts, y)[0] + def norm(y, e, speed, budget): + return jnp.maximum(jnp.sqrt(scalar(e, 0)**2+scalar(e, 1)**2), + jnp.maximum(jnp.abs(scalar(e, 2)), jnp.abs(scalar(e, 3))/speed))/budget + table_levels = [] + start = event_start+len(event_arrays) + for values, evaluate in tables: + table_levels.append(lambda y, evaluate=evaluate, data=refs[start:start+len(values)]:evaluate(data,y)) + start += len(values) + def level(y): + result = _evaluate_surface(eg.jaxpr,ec,y) if eg is not None else zero+jnp.inf + for function in table_levels: + result = jnp.minimum(result,function(y)) + return result if eg is not None or table_levels else zero+1. + def kick(y, h, dw): + if gc and spatial_diffusion: + vector,_=_coil_field_values(frefs,tuple(scalar(y,i) for i in range(3)),nc,nq,False) + B=jnp.sqrt(_dot(vector,vector)) + else: + B = magnitude(y) if gc else zero+1. + speed = jnp.sqrt(scalar(y, 3)**2+2*scalar(y, 4)*B/mass) if gc else jnp.sqrt(sum(scalar(y, i)**2 for i in range(3, 6))) + c = _evaluate_kernel(cg.jaxpr, cc, speed, scalarize=True) + if gc: + xi=scalar(y,3)/speed + velocity_noise=pack(tuple(scalar(dw,i) for i in (3,4))) if spatial_diffusion else dw + changed, ed, es = _evaluate_kernel(gg.jaxpr, mc[:-1], speed, xi, h, velocity_noise,mc[-1], *c, scalarize=True) + v, xi = scalar(changed, 0), scalar(changed, 1) + if spatial_diffusion: + unit=tuple(b/B for b in vector);noise=tuple(scalar(dw,i) for i in range(3)) + scale=_diffusion_root(2*guiding_center_spatial_diffusion(scalar(y,3)/speed,CollisionCoefficients(*c),charge*B/mass)) + parallel=_dot(unit,noise) + point=tuple(scalar(y,i)+scale*(noise[i]-unit[i]*parallel) for i in range(3)) + y=pack(point+tuple(scalar(y,i) for i in range(3,8))) + B=magnitude(y) + result = jnp.where(jnp.arange(8) == 3, v*xi, + jnp.where(jnp.arange(8) == 4, mass*v*v*(1-xi*xi)/(2*B), y)) + else: + # Particle map (57)-(62), scalarized in the velocity-aligned basis. + dp, dt, ddp, q, _, dk = c + drift = q+ddp+2*(dp-dt)/speed + delta = (_diffusion_root(2*dt)*scalar(dw, 0), _diffusion_root(2*dt)*scalar(dw, 1), + drift*h+_diffusion_root(2*dp)*scalar(dw, 2)+.5*ddp*(scalar(dw, 2)**2-h)) + direction = tuple(scalar(y, i)/speed for i in range(3, 6)) + a = tuple(jnp.abs(v) for v in direction) + i0 = (a[0] <= a[1]) & (a[0] <= a[2]); i1 = ~i0 & (a[1] <= a[2]) + ref = tuple(v.astype(y.dtype) for v in (i0, i1, ~i0 & ~i1)) + first = _cross(direction, ref); length = jnp.sqrt(_dot(first, first)) + first = tuple(v/length for v in first); second = _cross(direction, first) + velocity = tuple(scalar(y, 3+i)+first[i]*delta[0]+second[i]*delta[1]+direction[i]*delta[2] for i in range(3)) + result = pack(tuple(scalar(y, i) for i in range(3))+velocity+(zero, zero)) + eps = collision_tolerance*(jnp.abs(drift)*h+jnp.sqrt(jnp.maximum(2*dp*h, 0.))) + def ratio(numerator, denominator): + safe = jnp.where(denominator > 0, denominator, zero+1.) + return jnp.where(denominator > 0, numerator/safe, + jnp.where(numerator == 0, zero, zero+jnp.inf)) + ed = ratio(.5*jnp.abs(drift*dk)*h*h, eps) + es = ratio(ddp**2*jnp.abs(scalar(dw, 2))**3, 6*eps*jnp.sqrt(jnp.maximum(dp, 0.))) + valid = _kernel_is_finite(B) & (B > 0) & (speed > 0) & (c[0] >= 0) & (c[1] >= 0) + for value in c: + valid &= _kernel_is_finite(value) if isinstance(value, jax.core.Tracer) else np.isfinite(value) + return jnp.where(valid, result, jnp.nan), ed, es + return rhs, kick, norm, level + return all_arrays, factory + + +def _solve_independent(rhs, collision, initial, args=None, *, field, species, gc, + birth_speed, speed_floor, collision_tolerance, field_view=None, physics=None, + mass=M,charge=Q,spatial_diffusion=False,spatial_geometry=None,**options): + from .fields import BiotSavart,Vmec + for name in ('max_steps', 'max_orbit_steps', 'max_pending'): + value = options[name] + if isinstance(value, (bool, np.bool_)) or not isinstance(value, (int, np.integer)) or value < 1: + raise ValueError(name+" must be a positive integer") + nstate = initial.size + screening=getattr(species,'screening_species',None) + fast=field_view is not None and species.radial_grid is None and (screening is None or screening.radial_grid is None) + if spatial_diffusion and field_view is not None and not isinstance(field,BiotSavart):fast=False + if physics is None or fast: + arrays, factory = _prepare_split_field(field, species, gc=gc, + collision_tolerance=collision_tolerance, speed_floor=speed_floor, + event=options['event'], state_size=nstate, field_view=field_view, + mass=mass,charge=charge,spatial_diffusion=spatial_diffusion) + if physics is not None: + predictor_arrays,predictor_factory=prepare_physics(field,field_view,physics,initial,options['noise_dim'],predictor_only=True) + nfield=len(field_view[0]);nphysics=len(arrays);original_factory=factory + arrays=tuple(arrays)+tuple(predictor_arrays[nfield:]) + def factory(refs,y0): + physical=original_factory(refs[:nphysics],y0) + prediction=predictor_factory(refs[:nfield]+refs[nphysics:],y0)[4] + return (*physical,prediction) + else: + arrays,factory=prepare_physics(field,field_view,physics,initial,options['noise_dim'],spatial_geometry=spatial_geometry) + def forward(initial, parameters=None, *, record=False): + solve = _prepare_split_kernel(arrays, factory, options['ts'], adaptive=options['adaptive'], + dt0=options['dt0'], dtmax=options['dtmax'], speed=birth_speed, + tolerance=(options['rtol']+options['atol'])/2, noise_dim=options['noise_dim'], + max_steps=options['max_steps'], max_orbit_steps=options['max_orbit_steps'], + max_pending=options['max_pending'], state_size=nstate, + bank_components=4 if gc and nstate == 5 else 8, + orbit_dt0=options['orbit_dt0'], final_time=options['t1'],align_orbit=options.get('align_orbit',False), + warps=4 if isinstance(field,Vmec) and not spatial_diffusion else 1, + record=record,adjoint_checkpoint_steps=options.get('adjoint_checkpoint_steps',16), + adjoint_orbit_checkpoint_steps=options.get('adjoint_orbit_checkpoint_steps',16), + adjoint_max_accepted_steps=options.get('adjoint_max_accepted_steps'), + adjoint_max_orbit_steps=options.get('adjoint_max_orbit_steps'), + collision_indices=options.get('_collision_state_indices')) + result = solve(jnp.pad(initial, (0, 8-nstate)), jax.random.key_data(options['key'])) + if record: + result,tape=result + tape=tape._replace(states=tape.states[:,:nstate],orbit_states=tape.orbit_states[:,:nstate], + orbit_derivatives=tape.orbit_derivatives[:,:nstate], + orbit_endpoints=tape.orbit_endpoints[:,:nstate] if options.get('_collision_state_indices') is None else tape.orbit_endpoints) + ys,y,t,stats,status=result + solution = SplitSolution(options['ts'], ys[:, :nstate], t, y[:nstate], status, + SplitStats(*(stats[i].astype(jnp.int32) for i in range(6)), stats[6],collision_updates=stats[1].astype(jnp.int32), + accepted_orbit_steps=stats[7].astype(jnp.int32),max_orbit_steps_per_collision=stats[8].astype(jnp.int32)), + jnp.empty((0,), initial.dtype)) + return (solution,tape) if record else solution + if options.get('adjoint','none') == 'accepted': + from .native_ad import solve_accepted_split, solve_gpu_accepted + direct=(isinstance(field,BiotSavart) and fast and mass==M and charge==Q) + if options.get('_reverse_execution','auto') not in ('auto','shared','independent'): + raise ValueError("reverse_execution must be 'auto', 'shared' or 'independent'") + if options.get('_reverse_execution','auto')=='independent' and not direct: + raise ValueError('independent reverse currently requires direct alpha coils and uniform background') + if direct and options.get('_reverse_execution','auto')!='shared': + return solve_gpu_accepted(forward,initial,field,species,gc=gc,speed_floor=speed_floor, + options=options,arrays=arrays,spatial_diffusion=spatial_diffusion) + ad_options={k:v for k,v in options.items() if k not in ('adjoint','_record_ad','_reverse_execution')} + return solve_accepted_split(rhs,collision,initial,args,_forward_override=forward,**ad_options) + return forward(initial,record=options.get('_record_ad',False)) + + +# Spatial geometry + +def move_in_cartesian(state, displacement, position, *, implicit=False): + """Invert the Cartesian Euler kick in the existing regular position chart. + + Solving the nonlinear map retains its Ito coordinate drift automatically; + multiplying the noise by an inverse Jacobian alone would omit that drift. + Velocity and the VMEC poloidal-angle gauge are held fixed. A failed inverse + returns NaNs so the driver reports failure instead of dropping the kick. + """ + target=position(state)+displacement + mapping=lambda point:position(state.at[:3].set(point)) + threshold=64*jnp.finfo(state.dtype).eps + def advance(carry): + point,_,iteration=carry + residual=mapping(point)-target + matrix=jax.jacfwd(mapping)(point) + a,b,c=matrix[:,0],matrix[:,1],matrix[:,2] + rows=jnp.stack((jnp.cross(b,c),jnp.cross(c,a),jnp.cross(a,b))) + point=point-(rows@residual)/jnp.dot(a,rows[0]) + scale=jnp.maximum(1.,jnp.maximum(jnp.linalg.norm(target), + jnp.linalg.norm(matrix)*jnp.maximum(1.,jnp.linalg.norm(point)))) + return point,jnp.linalg.norm(mapping(point)-target)/scale,iteration+1 + if not implicit: + point,error,_=jax.lax.while_loop(lambda c:((c[2]==0)|(c[1]>threshold))&(c[2]<8),advance, + (state[:3],jnp.linalg.norm(displacement),jnp.asarray(0))) + return state.at[:3].set(jnp.where(error<=threshold,point,jnp.full_like(point,jnp.nan))) + def solve_root(function, guess): + del function + return jax.lax.while_loop(lambda c:((c[2]==0)|(c[1]>threshold))&(c[2]<8),advance, + (guess,jnp.linalg.norm(displacement),jnp.asarray(0)))[0] + def tangent_solve(linear, value): + a,b,c=jax.vmap(linear)(jnp.eye(3,dtype=state.dtype)) + rows=jnp.stack((jnp.cross(b,c),jnp.cross(c,a),jnp.cross(a,b))) + return (rows@value)/jnp.dot(a,rows[0]) + point=jax.lax.custom_root(lambda q:mapping(q)-target,state[:3],solve_root,tangent_solve) + matrix=jax.jacfwd(mapping)(point) + scale=jnp.maximum(1.,jnp.maximum(jnp.linalg.norm(target), + jnp.linalg.norm(matrix)*jnp.maximum(1.,jnp.linalg.norm(point)))) + error=jnp.linalg.norm(mapping(point)-target)/scale + return state.at[:3].set(jnp.where(error<=threshold,point,jnp.full_like(point,jnp.nan))) + +class BoozerGeometry(NamedTuple): + """Spatial geometry exported alongside Boozer magnetic tables. + + The toroidal shift is nu=zeta_B-phi, following booz_xform's numn*_b + convention. Geometry modes are retained independently of magnetic cuts. + """ + knots: object + coefficients: object + xm: object + xn: object + + @classmethod + def from_booz_xform(cls,booz): + from .boozer import _spline + s=np.asarray(booz.s_b,float);m=np.asarray(booz.xm_b,int) + if s.ndim!=1 or len(s)<2 or np.any(~np.isfinite(s)) or np.any(s<=0) or np.any(np.diff(s)<=0): + raise ValueError('Boozer geometry requires at least two increasing positive surfaces') + shape=(len(m),len(s)) + def spectrum(name): + value=getattr(booz,name,None) + if value is None or not np.size(value):return np.zeros(shape) + value=np.asarray(value,float) + if value.shape!=shape:raise ValueError(name+' must have mode/surface axes') + return value + for name in ('rmnc_b','zmns_b','numns_b'): + if getattr(booz,name,None) is None or not np.size(getattr(booz,name,None)): + raise ValueError('Boozer spatial diffusion requires geometry: '+name) + values=np.stack([spectrum(name) for name in + ('rmnc_b','rmns_b','zmnc_b','zmns_b','numnc_b','numns_b')],axis=-1) + # A mode m scales as r**m at the axis. Evaluate its angular factor as + # a polynomial in u+iw rather than differentiating atan2 there. + powers=np.minimum(m,2+m%2) + scaled=np.moveaxis(values,1,0)/np.sqrt(s)[:,None,None]**powers[None,:,None] + axis=scaled[0]-s[0]*(scaled[1]-scaled[0])/(s[1]-s[0]) + knots,coefficients=_spline(np.r_[0.,s],np.concatenate((axis[None],scaled))) + return cls(knots,coefficients,jnp.asarray(m),jnp.asarray(booz.xn_b)) + + def regular_xyz(self,point): + """Cartesian position from (sqrt(s)cos(theta),sqrt(s)sin(theta),zeta).""" + from .boozer import _evaluate + u,w,zeta=point;s=u*u+w*w + amplitude=_evaluate(self.knots,self.coefficients,s)[0] + # Recur on complex harmonics using real operations supported by Pallas. + real,imag=jnp.ones_like(self.xm,dtype=u.dtype),jnp.zeros_like(self.xm,dtype=u.dtype) + for k in range(int(np.max(np.asarray(self.xm)))): + active=kpowers,jnp.maximum(s,1e-30)**((powers-self.xm)/2),1.) + c,t=jnp.cos(self.xn*zeta),jnp.sin(self.xn*zeta) + cosine,sine=(real*c+imag*t)*factor,(imag*c-real*t)*factor + R=jnp.sum(amplitude[:,0]*cosine+amplitude[:,1]*sine) + Z=jnp.sum(amplitude[:,2]*cosine+amplitude[:,3]*sine) + shift=jnp.sum(amplitude[:,4]*cosine+amplitude[:,5]*sine) + return jnp.array([R*jnp.cos(zeta-shift),R*jnp.sin(zeta-shift),Z]) + + def __call__(self,point): + r=jnp.sqrt(point[0]) + return self.regular_xyz(jnp.array([r*jnp.cos(point[1]),r*jnp.sin(point[1]),point[2]])) + + def _kernel_view(self): + """Keep geometry-table reads vectorized inside the independent kernel.""" + from .rk import _select_one + nr,nm=(1<<(n-1).bit_length() for n in (len(self.knots),len(self.xm))) + knots=np.full(nr,np.inf);knots[:len(self.knots)]=np.asarray(self.knots) + coefficients=np.zeros((nr,nm,8,4));c=np.asarray(self.coefficients) + coefficients[:c.shape[0],:c.shape[1],:6]=c + arrays=tuple(map(jnp.asarray,(knots,coefficients,np.pad(np.asarray(self.xm),(0,nm-len(self.xm))), + np.pad(np.asarray(self.xn),(0,nm-len(self.xn)))))) + def evaluate(refs,s,theta,zeta): + grid,table,m,n=refs + i=jnp.clip(jnp.sum((s>=grid[...]).astype(jnp.int32))-1,0,len(self.knots)-2) + d=s-grid[i] + amplitude=((table[i,:,:,0]*d+table[i,:,:,1])*d+table[i,:,:,2])*d+table[i,:,:,3] + power=jnp.minimum(m[...],2+m[...]%2);root=jnp.sqrt(s) + factor=jnp.where(power==0,1.,jnp.where(power==1,root,jnp.where(power==2,s,s*root))) + phase=m[...]*theta-n[...]*zeta;cosine,sine=factor*jnp.cos(phase),factor*jnp.sin(phase) + column=lambda i:_select_one(amplitude,i,1).reshape((nm,)) + values=tuple(jnp.sum(column(i)*cosine+column(i+1)*sine) for i in (0,2,4)) + R,Z,shift=values + return R*jnp.cos(zeta-shift),R*jnp.sin(zeta-shift),Z + return arrays,evaluate + + +# Moment predictor + +class CollisionJet(NamedTuple): + drift: object + noise: object + drift_jacobian: object + drift_hessian: object + variance_gradient: object + variance_hessian: object + spatial_drift: object + spatial_variance: object + +class MomentDefect(NamedTuple): + mean: object + covariance: object + cubic_covariance: object + noise: object + orbit_jacobian: object + +def collision_jet(radial,r,xi,point,direction): + """Analytic pitch derivatives of drift/variance; two radial derivatives. + + Differentiate Q=g*g directly: Q is smooth at pitch endpoints even though + derivatives of sqrt(1-xi*xi) are singular. Profile convection is retained. + """ + values,spatial=jax.jvp(lambda x:radial(r,x),(point,),(direction,)) + first=jax.jacfwd(radial)(r,point) + second=jax.jacfwd(jax.jacfwd(radial))(r,point) + a,b,d=values;da,db,dd=first;dda,ddb,ddd=second + drift=jnp.array([a,-xi*d*d]);noise=jnp.array([b,jnp.sqrt(jnp.maximum(0.,1-xi*xi))*d]) + aj=jnp.array([[da,0.],[-2*xi*d*dd,-d*d]]) + ah=jnp.array([[[dda,0.],[0.,0.]], + [[-2*xi*(dd*dd+d*ddd),-2*d*dd],[-2*d*dd,0.]]]) + qj=jnp.array([[2*b*db,0.],[2*(1-xi*xi)*d*dd,-2*xi*d*d]]) + qh=jnp.array([[[2*(db*db+b*ddb),0.],[0.,0.]], + [[2*(1-xi*xi)*(dd*dd+d*ddd),-4*xi*d*dd],[-4*xi*d*dd,-2*d*d]]]) + return CollisionJet(drift,noise,aj,ah,qj,qh, + jnp.array([spatial[0],-2*xi*d*spatial[2]]), + jnp.array([2*b*spatial[1],2*(1-xi*xi)*d*spatial[2]])) + +def moment_defect(f,vel,jet,*,collision_remainder=True,orbit_jet=None): + """E[split-exact] = mean*h^2/2, delta Cov = covariance*h^2/2. + + Splitting terms are [L_orbit,L_collision] on linear/quadratic tests. + The optional collision remainder matches the implemented diagonal + Milstein map, not an exact collision semigroup. The cubic spatial block + is the missing integrated velocity noise, exact for free Brownian flight. + Higher-order terms for a general nonlinear field are not included. + """ + a,g,aj,ah,qj,qh,xa,xq=jet;q=g*g + if orbit_jet is None: + f0=f(vel);fj=jax.jacfwd(f)(vel) + trace=jnp.einsum('ijj,j->i',jax.jacfwd(jax.jacfwd(f))(vel),q) + else: + f0,fj,diagonal=orbit_jet;trace=diagonal@q + n=f0.size + J=jnp.zeros((n,n)).at[:,-2:].set(fj) + G=jnp.zeros((n,2)).at[-2:,:].set(jnp.diag(g));Q=G@G.T + mean=-fj@a-.5*trace + mean=mean.at[-2:].add(aj@f0[-2:]+xa) + cov=jnp.zeros((n,n)).at[-2:,-2:].set(jnp.diag(qj@f0[-2:]+xq)) + cov=cov-J@Q-Q@J.T + if collision_remainder: + la=aj@a+.5*jnp.einsum('ijj,j->i',ah,q) + lq=qj@a+.5*jnp.einsum('ijj,j->i',qh,q) + mean=mean.at[-2:].add(-la) + correction=jnp.diag(.25*jnp.diag(qj)**2-lq)-aj@jnp.diag(q)-jnp.diag(q)@aj.T + cov=cov.at[-2:,-2:].add(correction) + B=(J@G).at[-2:,:].set(0.) + return MomentDefect(mean,cov,-B@B.T/3,G,J) + +def budget_components(defect,vel,tau): + """Mean/covariance error rates over tau using linear orbit transport. + + Averaging I+sJ over 0<=s<=tau propagates local mixed defects into + later position variance. This captures the leading global Brownian- + flight variance bias which a diagonal local RMS error omits. + """ + b,C,D,G,J=defect + b=b+.5*tau*(J@b) + def transport(A):return A+.5*tau*(J@A+A@J.T)+(tau*tau/3)*(J@A@J.T) + C,D=transport(C),transport(D) + B=J@G + # PSD Gramian diagonal: integral_0^tau |G+s JG|^2 ds. + # Add physical parallel velocity p=r*xi as an observable, retaining its + # Ito mean correction from the mixed covariance defect. + n=b.size;P=jnp.concatenate((jnp.eye(n),jnp.zeros((1,n)).at[0,-2:].set(vel[::-1])),axis=0) + bp=P@b;bp=bp.at[-1].add(C[-2,-1]) + Cp,Dp=P@C@P.T,P@D@P.T + Gp,Bp=P@G,P@B + spreadp=tau*jnp.sum((Gp+.5*tau*Bp)**2,axis=1)+tau**3/12*jnp.sum(Bp*Bp,axis=1) + scale=jnp.sqrt(jnp.maximum(spreadp,1e-28)) + return (.5*tau*jnp.abs(bp)/scale, + .5*tau*jnp.abs(Cp)/(scale[:,None]*scale[None,:]), + tau*jnp.abs(Dp)/(scale[:,None]*scale[None,:])) + +def transported_budget(defect,vel,tau): + """Reduce the individual mean/covariance limits without extra evaluations.""" + means,covariance,quadratic=budget_components(defect,vel,tau) + return jnp.maximum(jnp.max(means),jnp.max(covariance)),jnp.max(quadratic) + +def interval_from_budget(linear,quadratic,tolerance,cap=.0025): + """Largest h satisfying linear*h+quadratic*h*h <= .8*tolerance.""" + target=.8*tolerance + denominator=linear+jnp.sqrt(linear*linear+4*quadratic*target) + h=2*target/jnp.maximum(denominator,1e-300) + return jnp.minimum(cap,h) + +def _gc_velocity_jet(field,point,vel,physical): + """Exact velocity derivatives of the existing E=0 Cartesian GC RHS. + + At a fixed position the five phase velocities have the form N(r,xi)/D, + where N is polynomial and D=d0+d1*r*xi. Quotient derivatives supply the + Jacobian and diagonal Hessian used above. Public field quantities and + the GC equations are unchanged; field/profile dependence remains in AD. + """ + from essos.dynamics import _gc_quantities + from essos.constants import PROTON_MASS as M,ELEMENTARY_CHARGE as Q + M,Q=getattr(physical,"mass",M),getattr(physical,"charge",Q) + Bc,B,Bmag,grad,curl,kappa,sqrtg=_gc_quantities(field,point) + r,xi=vel;U=B/Bmag;A=grad/(2*Bmag);K=kappa-A + d0=Bc@B;d1=physical.sigma*M/Q*(Bc@curl) + c0=M*physical.sigma/(Q*sqrtg)*jnp.cross(Bc,A) + c2=M*physical.sigma/(Q*sqrtg)*jnp.cross(Bc,K)+d1*U + v0=B@A;v2=B@K + v1=physical.sigma*M/Q*(curl@A);v3=physical.sigma*M/Q*(curl@K) + factor=-Bmag*physical.sigma/physical.nu + q0=v0+v2*xi**2;q1=v1*xi+v3*xi**3 + N=jnp.r_[d0*U*r*xi+r*r*(c0+c2*xi*xi),0.,factor*(r*q0+r*r*q1)] + Nr=jnp.r_[d0*U*xi+2*r*(c0+c2*xi*xi),0.,factor*(q0+2*r*q1)] + Nrr=jnp.r_[2*(c0+c2*xi*xi),0.,2*factor*q1] + Nx=jnp.r_[d0*U*r+2*r*r*c2*xi,0.,factor*(2*r*v2*xi+r*r*(v1+3*v3*xi*xi))] + Nxx=jnp.r_[2*r*r*c2,0.,factor*(2*r*v2+6*r*r*v3*xi)] + D=d0+d1*r*xi;Dr=d1*xi;Dx=d1*r + value=N/D + first=jnp.stack(((Nr-value*Dr)/D,(Nx-value*Dx)/D),axis=1) + second=jnp.stack(((Nrr-2*first[:,0]*Dr)/D,(Nxx-2*first[:,1]*Dx)/D),axis=1) + return value,first,second + +def expanded_moment_budget(velocity,jet,vel,tau): + """Same weak-moment budget, expanding the two diagonal noise directions. + + This removes small batched matrix products. Radial and field derivatives + remain unchanged; no term of the existing estimator is dropped. + """ + f,F,H=velocity;a,g,aj,ah,qj,qh,xa,xq=jet;q=g*g + multiply=lambda A,v:A[:,0]*v[0]+A[:,1]*v[1] + contraction=lambda A:A[:,0,0]*q[0]+A[:,1,1]*q[1] + mean=-multiply(F,a)-.5*multiply(H,q) + mean=mean.at[-2:].add(multiply(aj,f[-2:])+xa-multiply(aj,a)-.5*contraction(ah)) + aq=aj*q[None,:] + correction=jnp.diag(.25*jnp.diag(qj)**2-multiply(qj,a)-.5*contraction(qh))-aq-aq.T + cov=jnp.zeros((5,5)).at[-2:,-2:].set(jnp.diag(multiply(qj,f[-2:])+xq)+correction) + fq=F*q[None,:];cov=cov.at[:,-2:].add(-fq).at[-2:,:].add(-fq.T) + B=F*g[None,:];noise=B.at[-2:,:].set(0.) + mean=mean+.5*tau*multiply(F,mean[-2:]) + def transport(A): + left=F[:,0,None]*A[None,-2,:]+F[:,1,None]*A[None,-1,:] + right=A[:,-2,None]*F[None,:,0]+A[:,-1,None]*F[None,:,1] + inner=(F[:,0,None]*(A[-2,-2]*F[None,:,0]+A[-2,-1]*F[None,:,1])+ + F[:,1,None]*(A[-1,-2]*F[None,:,0]+A[-1,-1]*F[None,:,1])) + return A+.5*tau*(left+right)+tau*tau/3*inner + cov=transport(cov) + xi,r=vel[::-1] + def vector(A):return jnp.concatenate((A,(xi*A[-2]+r*A[-1])[None]),axis=0) + def matrix(A): + right=xi*A[:,-2]+r*A[:,-1];bottom=xi*A[-2,:]+r*A[-1,:] + return jnp.concatenate((jnp.concatenate((A,right[:,None]),axis=1),jnp.r_[bottom,xi*right[-2]+r*right[-1]][None,:]),axis=0) + bp=vector(mean).at[-1].add(cov[-2,-1]);Cp=matrix(cov) + Gp=vector(jnp.zeros((5,2)).at[-2:,:].set(jnp.diag(g)));Bp=vector(B) + spread=tau*jnp.sum((Gp+.5*tau*Bp)**2,axis=1)+tau**3/12*jnp.sum(Bp*Bp,axis=1) + inverse=1/jnp.sqrt(jnp.maximum(spread,1e-28)) + # Covariance symmetry lets scalar lowering omit duplicated lower entries. + pairs=jnp.stack([.5*tau*jnp.abs(Cp[i,j])*(inverse[i]*inverse[j]) + for i in range(6) for j in range(i,6)]) + linear=jnp.maximum(jnp.max(.5*tau*jnp.abs(bp)*inverse),jnp.max(pairs)) + # J*noise=0: cubic transport/projection leaves only its spatial block. + # The normalized absolute maximum of its noise Gram block is diagonal. + diagonal=(noise[:3,0]**2+noise[:3,1]**2)/3 + quadratic=jnp.max(tau*diagonal*(inverse[:3]*inverse[:3])) + return linear,quadratic + +def make_step_limit(field,bath,physical,tolerance=.005,*,reference_time=.005,cap=.0025,expanded=True,projection=None): + """Predict intervals from a fractional moment-defect budget. + + reference_time is in t*nu0 units, NOT a timestep cap. It sets the earliest + observation timescale; elapsed time subsequently grows the spread proxy. + Tolerance differs from the old local-trajectory RMS tolerance. Independent + physical/paired tests, rather than this proxy, determine achieved error. + expanded=False retains the dense algebra reference; both use the same + native coefficient and field derivatives. + """ + to_phase,_,_,radial=_cartesian_model(field,bath,physical) + def limit(t,y,args): + u=to_phase(y);vel=u[-2:];point=y[:3] + velocity=_gc_velocity_jet(field,point,vel,physical) + jet=collision_jet(radial,vel[0],vel[1],point,velocity[0][:3]*physical.sigma/physical.nu) + if projection is not None: + jacobian=jax.jacfwd(projection)(point) + velocity=tuple(jnp.concatenate((jacobian@value[:3],value[3:]),axis=0) for value in velocity) + tau=jnp.maximum(reference_time,t*physical.nu) + if expanded: + linear,quadratic=expanded_moment_budget(velocity,jet,vel,tau) + else: + defect=moment_defect(None,vel,jet,orbit_jet=velocity) + linear,quadratic=transported_budget(defect,vel,tau) + return interval_from_budget(linear,quadratic,tolerance,cap=cap)/physical.nu + return limit + +def _cartesian_model(field,bath,physical): + """Native GC coefficients in normalized physical coordinates.""" + from .constants import PROTON_MASS as M,ELEMENTARY_CHARGE as Q + from .dynamics import _guiding_center_velocity + from .electric_field import Electric_field_zero + M,Q=getattr(physical,"mass",M),getattr(physical,"charge",Q) + sigma,nu=physical.sigma,physical.nu + electric=Electric_field_zero() + def phase(y): + speed=jnp.sqrt(y[3]**2+2*y[4]*field.AbsB(y[:3])/M) + return jnp.r_[y[:3]*nu/sigma,speed/sigma,y[3]/speed] + def restore(u): + point=u[:3]*sigma/nu + return jnp.r_[point,sigma*u[3]*u[4],M*sigma**2*u[3]**2*(1-u[4]**2)/(2*field.AbsB(point))] + def drift(u): + y=restore(u) + dx,dv=_guiding_center_velocity(field,electric,Q,M,y[:3],y[3],mu=y[4]) + return jnp.r_[dx/sigma,0.,dv/(nu*sigma*u[3])] + def radial(r,point): + c=collision_coefficients(bath,M,Q,sigma*r,point) + return jnp.array([(c.friction+c.parallel_derivative+2*c.parallel/(sigma*r))/(sigma*nu), + _diffusion_root(2*c.parallel/(sigma*sigma*nu)), + _diffusion_root(2*c.perpendicular/(sigma*sigma*r*r*nu))]) + return phase,restore,drift,radial + +def _particle_ito(velocity,unit_b,rates): + K,P,T=rates + r=jnp.linalg.norm(velocity);u=velocity/r;xi=unit_b@u + rows=jnp.stack((u,(unit_b-xi*u)/r,unit_b));projected=rows@u + cross=2*T*rows+2*(P-T)*projected[:,None]*u[None,:] + low=2*T*(rows@rows.T)+2*(P-T)*projected[:,None]*projected[None,:] + vv=2*T*jnp.eye(3)+2*(P-T)*u[:,None]*u[None,:] + covariance=jnp.concatenate((jnp.concatenate((vv,cross.T),axis=1),jnp.concatenate((cross,low),axis=1)),axis=0) + return jnp.r_[K*u,K+2*T/r,-2*T*xi/r**2,K*xi],covariance + +def _particle_local_moments(velocity,unit_b,coefficients): + """Exact weak-two moments of the existing frozen Lorentz collision map. + + Coordinates are (v_x,v_y,v_z,speed,pitch,v_parallel), normalized before + this call. Return drift, diffusion covariance, h^2 mean and h^2 covariance. + P/T are parallel/perpendicular diffusion; K is the Cartesian Ito drift + magnitude and Pprime is its parallel-diffusion speed derivative. No + collision update, derivative approximation or sampled calibration occurs. + """ + K,P,T,Pprime=coefficients + r=jnp.linalg.norm(velocity);u=velocity/r;xi=unit_b@u + tangent=unit_b-xi*u + drift,diffusion=_particle_ito(velocity,unit_b,jnp.array([K,P,T])) + second_mean=jnp.zeros(6).at[3].set(-2*K*T/r**2+4*T*(P-T)/r**3) + second_mean=second_mean.at[4].set(xi*(4*K*T/r**3+12*T*(T-P)/r**4)) + parallel=.5*Pprime**2 + vr=u*(parallel-4*P*T/r**2) + vx=u*xi*8*P*T/r**3+tangent*(-2*K*T/r**2+(4*P*T-8*T*T)/r**3) + second=jnp.zeros((5,5)).at[:3,:3].set(parallel*u[:,None]*u[None,:]) + second=second.at[:3,3].set(vr).at[3,:3].set(vr).at[:3,4].set(vx).at[4,:3].set(vx) + second=second.at[3,3].set(parallel+(4*T*T-8*P*T)/r**2) + cross=4*xi*T*(2*P-T)/r**3 + second=second.at[3,4].set(cross).at[4,3].set(cross) + second=second.at[4,4].set(-4*K*T*(1-xi*xi)/r**3+ + ((20*xi*xi-16)*T*T+12*P*T*(1-xi*xi))/r**4) + parallel_projection=jnp.concatenate((jnp.eye(5),jnp.r_[unit_b,0.,0.][None,:])) + return drift,diffusion,second_mean,parallel_projection@second@parallel_projection.T + +def _particle_collision_generator(velocity,unit_b,rates,first,second): + """Exact Coulomb generator on the six drift/covariance observables. + + In polar velocity coordinates L=A*d_r+P*d_rr+(T/r^2)*Delta_sphere. + The observables contain spherical harmonics of degree at most two, so + these contractions need no materialized third/fourth-order tensors. + """ + r=jnp.linalg.norm(velocity);u=velocity/r;xi=unit_b@u + K,P,T=rates;A=K+2*T/r + RK,RP,RT=A*first+P*second + def radial_power(n): + return 2/r**n*(A*(first[2]-n*T/r)+P*(second[2]-2*n*first[2]/r+n*(n+1)*T/r**2)) + h1,h2=2*T/r,2*T/r**2;R1,R2=radial_power(1),radial_power(2) + vector=(RK-2*T*K/r**2)*u + mean=jnp.r_[vector,RK+R1,(-R2+2*T*h2/r**2)*xi,unit_b@vector] + outer=u[:,None]*u[None,:] + vv=(2*RT+4*T*(P-T)/r**2)*jnp.eye(3)+(2*(RP-RT)-12*T*(P-T)/r**2)*outer + vr=(2*RP-4*T*P/r**2)*u + vx=(R1-2*T*h1/r**2)*unit_b+(-R1+6*T*h1/r**2)*xi*u + covariance=jnp.zeros((6,6)).at[:3,:3].set(vv) + covariance=covariance.at[:3,3].set(vr).at[3,:3].set(vr).at[:3,4].set(vx).at[4,:3].set(vx) + covariance=covariance.at[3,3].set(2*RP).at[4,4].set(R2*(1-xi*xi)+T*h2/r**2*(-2+6*xi*xi)) + projected=covariance[:5,:3]@unit_b + covariance=covariance.at[:5,5].set(projected).at[5,:5].set(projected).at[5,5].set(unit_b@vv@unit_b) + return mean,covariance + +def _particle_flow_generator(v,b,gradient,rotation,electric,rates,orbit): + """Same exact generator on position, Lorentz force, speed and pitch flow.""" + r=jnp.linalg.norm(v);u=v/r;xi=b@u;K,P,T=rates;A=K+2*T/r + quad=u@gradient@u;trace=jnp.trace(gradient);e=u@electric;parallel=b@electric + speed=-2*T/r**2*e + pitch=(A-6*T/r)*quad+2*T/r*trace+(-A/r**2+2*P/r**3)*(parallel-xi*e)+T/r**3*(-2*parallel+6*xi*e) + par=(2*r*A+2*P-6*T)*quad+2*T*trace + return jnp.r_[K*u if orbit else jnp.zeros(3),rotation@(K*u),speed,pitch,par] + +def _particle_velocity_jacobians(v,b,gradient,rotation,electric,rates,first,*,orbit=True): + """Exact velocity Jacobians of the existing collision drift and orbit flow.""" + r=jnp.linalg.norm(v);u=v/r;xi=b@u;K,_,T=rates;dK,_,dT=first + pitch_gradient=(b-xi*u)/r + drift=K/r*jnp.eye(3)+(dK-K/r)*u[:,None]*u[None,:] + speed=(dK+2*dT/r-2*T/r**2)*u + pitch=-2*dT*xi/r**2*u-2*T/r**2*pitch_gradient+4*T*xi/r**3*u + parallel=dK*xi*u+K*pitch_gradient + A1=jnp.concatenate((drift,speed[None,:],pitch[None,:],parallel[None,:])) + e=u@electric;de=(electric-e*u)/r + p=(gradient@v)@v+b@electric;dp=(gradient+gradient.T)@v + pitch_rate=(p-xi*e)/r + df=(dp-e*pitch_gradient-xi*de-pitch_rate*u)/r + F=jnp.concatenate((jnp.eye(3) if orbit else jnp.zeros((3,3)),rotation,de[None,:],df[None,:],dp[None,:])) + return A1,F + +def _particle_budget(velocity,unit_b,unit_gradient,rotation,electric,rates, + rate_first,rate_second,profile_rate,tau,*,details=False,orbit=True): + """Same weak-moment budget for Lorentz motion, including speed and pitch. + + Field/profile derivatives are current exact derivatives. The local radial + polynomial supplies their exact value/first/second velocity jets at this + state; it is not a cached coefficient model or a trajectory approximation. + Accepted tracing still calls the original orbit and collision maps. + """ + r=jnp.linalg.norm(velocity);u=velocity/r;xi=unit_b@u + K,P,T=rates + diffusion=2*T*jnp.eye(3)+2*(P-T)*u[:,None]*u[None,:] + A1,F=_particle_velocity_jacobians(velocity,unit_b,unit_gradient,rotation,electric,rates,rate_first,orbit=orbit) + la,lq=_particle_collision_generator(velocity,unit_b,rates,rate_first,rate_second) + force=rotation@velocity+electric + values,convected=jax.jvp(_particle_ito,(velocity,unit_b,rates), + (force,unit_gradient@velocity,profile_rate+rate_first*(u@electric))) + a,q=values;oa,oq=convected + _,_,mean2,cov2=_particle_local_moments(velocity,unit_b,jnp.r_[rates,rate_first[1]]) + extend=lambda x:jnp.concatenate((jnp.zeros((3,)+x.shape[1:]),x),axis=0) + G=jnp.concatenate((jnp.zeros((3,3)),jnp.eye(3),u[None,:], + (unit_b-xi*u)[None,:]/r,unit_b[None,:])) + mean=extend(oa-la+2*mean2)-_particle_flow_generator(velocity,unit_b,unit_gradient,rotation,electric,rates,orbit) + covariance=jnp.pad(oq-lq+2*cov2,((3,0),(3,0))) + cross=(F+extend(A1))@diffusion@G.T + covariance=covariance-cross-cross.T + mean=mean+.5*tau*(F@mean[3:6]) + covariance=(covariance+.5*tau*(F@covariance[3:6,:]+covariance[:,3:6]@F.T) + +tau*tau/3*(F@covariance[3:6,3:6]@F.T)) + noise=velocity_basis(velocity)*jnp.array([_diffusion_root(2*T),_diffusion_root(2*T),_diffusion_root(2*P)])[None,:] + gp,bp=G@noise,F@noise + spread=tau*jnp.sum((gp+.5*tau*bp)**2,axis=1)+tau**3/12*jnp.sum(bp*bp,axis=1) + scale=jnp.sqrt(jnp.maximum(spread,1e-28)) + pairs=jnp.stack([.5*tau*jnp.abs(covariance[i,j])/(scale[i]*scale[j]) + for i in range(9) for j in range(i,9)]) + linear=jnp.maximum(jnp.max(.5*tau*jnp.abs(mean)/scale),jnp.max(pairs)) + spatial_response=F[:3]@noise + quadratic=jnp.max(tau*jnp.sum(spatial_response*spatial_response,axis=1)/(3*scale[:3]*scale[:3])) + return (linear,quadratic,mean,covariance) if details else (linear,quadratic) + +def native_step_limit(field,bath,mass,charge,initial,rhs,public,position,magnitude, + *,gc,coordinate=False,boozer=False, + electric_field,tmax,dtmax,tolerance=.005,reference_time=.005,orbit=True,reference_magnitude=None): + """Construct the default physical moment controller without benchmark data. + + Reference units use birth density-weighted temperature and the friction + frequency at sqrt(T/m). They only normalize the estimator. VMEC uses its + Cartesian position map; Boozer uses its regular flux/angle chart because + magnetic Boozer tables do not specify a Cartesian surface embedding. + + The selected GC predictor is retained when the spatial collision update + is enabled. That update does not select a different error estimator. + """ + from types import SimpleNamespace + from .constants import ELEMENTARY_CHARGE + from .electric_field import Electric_field_zero + birth=public(initial);point=birth[:3] + density=jnp.stack([bath.get_density(i,point) for i in range(bath.number_species)]) + temperatures=jnp.stack([bath.get_temperature(i,point) for i in range(bath.number_species)]) + initial_magnitude=magnitude if reference_magnitude is None else reference_magnitude + speed=jnp.sqrt(birth[3]**2+2*birth[4]*initial_magnitude(point)/mass) if gc else jnp.linalg.norm(birth[3:]) + temperature=jnp.sum(density*temperatures)/jnp.where(jnp.sum(density)>0,jnp.sum(density),1.) + sigma=jnp.where(jnp.sum(density)>0,jnp.sqrt(ELEMENTARY_CHARGE*temperature/mass),speed/jnp.sqrt(10.)) + friction=collision_coefficients(bath,mass,charge,sigma,point).friction + nu=jnp.where(friction==0,1/jnp.maximum(tmax,1e-30),-friction/sigma) + physical=SimpleNamespace(sigma=sigma,nu=nu,mass=mass,charge=charge) + cap=dtmax*nu;zero_electric=isinstance(electric_field,Electric_field_zero) + if gc and not boozer and zero_electric and orbit: + limit=make_step_limit(field,bath,physical,tolerance,reference_time=reference_time,cap=cap, + projection=field.to_xyz if coordinate else None) + return (lambda t,y,args:limit(t,public(y),args)) if coordinate else limit + if gc: + def phase(y): + state=public(y);v=jnp.sqrt(state[3]**2+2*state[4]*magnitude(state[:3])/mass) + return jnp.r_[position(y)*(1. if boozer else nu/sigma),v/sigma,state[3]/v] + def radial(r,y): + point=public(y)[:3] + c=collision_coefficients(bath,mass,charge,sigma*r,point) + return jnp.array([(c.friction+c.parallel_derivative+2*c.parallel/(sigma*r))/(sigma*nu), + _diffusion_root(2*c.parallel/(sigma*sigma*nu)),_diffusion_root(2*c.perpendicular/(sigma*sigma*r*r*nu))]) + def velocity(v,template): + B=magnitude(public(template)[:3]);r,xi=v + y=template.at[3].set(sigma*r*xi).at[4].set(mass*sigma*sigma*r*r*(1-xi*xi)/(2*B)) + dy=rhs(0.,y,None) + dx=jax.jvp(position,(y,),(dy,))[1]/(nu if boozer else sigma) + dr=0. if zero_electric else jax.jvp(lambda y:phase(y)[3],(y,),(dy,))[1]/nu + return jnp.r_[dx,dr,dy[3]/(sigma*nu*r)-xi*dr/r] + def limit(t,y,args): + vel=phase(y)[-2:] + f=lambda v:velocity(v,y) + f0=f(vel);F=jax.jacfwd(f)(vel);H=jax.jacfwd(jax.jacfwd(f))(vel) + jet=collision_jet(radial,*vel,y,rhs(t,y,args)/nu) + linear,quadratic=expanded_moment_budget((f0,F,jnp.stack((H[:,0,0],H[:,1,1]),axis=1)),jet,vel,jnp.maximum(reference_time,t*nu)) + return interval_from_budget(linear,quadratic,tolerance,cap=cap)/nu + return limit + def radial(r,point): + c=collision_coefficients(bath,mass,charge,sigma*r,point,full_orbit=True) + return jnp.array([(c.friction+c.parallel_derivative+2*(c.parallel-c.perpendicular)/(sigma*r))/(sigma*nu), + c.parallel/(sigma*sigma*nu),c.perpendicular/(sigma*sigma*nu)]) + def unit_b(point): + B=field.B_contravariant(point) + return B/jnp.linalg.norm(B) + def limit(t,y,args): + point=y[:3];v=y[3:]/sigma;r=jnp.linalg.norm(v);B=field.B_contravariant(point);b=unit_b(point) + _,profile=jax.jvp(lambda x:radial(r,x),(point,),(sigma*v/nu if orbit else jnp.zeros(3),)) + values=radial(r,point);first=jax.jacfwd(radial)(r,point);second=jax.jacfwd(jax.jacfwd(radial))(r,point) + bx,by,bz=B + rotation=charge/(mass*nu)*jnp.array([[0.,bz,-by],[-bz,0.,bx],[by,-bx,0.]]) + electric=charge/(mass*sigma*nu)*electric_field.E_covariant(point) + gradient=jax.jacfwd(unit_b)(point)*sigma/nu if orbit else jnp.zeros((3,3)) + linear,quadratic=_particle_budget(v,b,gradient,rotation if orbit else jnp.zeros((3,3)), + electric if orbit else jnp.zeros(3),values,first,second,profile,jnp.maximum(reference_time,t*nu),orbit=orbit) + return interval_from_budget(linear,quadratic,tolerance,cap=cap)/nu + return limit + + +# GPU predictor lowering + +class KernelCalls: + """Keep native field reductions intact while scalarizing moment algebra.""" + def __init__(self):self.handlers={} + + def first_jet(self,function,kernel_function): + """Share one exact 3D value/Jacobian evaluation across JVP directions.""" + def ordinary(*point): + jacobian=jax.jacfwd(lambda x:jnp.asarray(function(*x)))(jnp.asarray(point)) + return (*function(*point),*jacobian.reshape(-1)) + packed=self.add(ordinary,kernel_function,12) + @jax.custom_jvp + def value(*point):return packed(*point)[:3] + @value.defjvp + def directional(primals,tangents): + data=packed(*primals) + return data[:3],tuple(sum(data[3+3*i+j]*tangents[j] for j in range(3)) for i in range(3)) + return value + + def add(self, function, kernel_function, count,*,kernel_jvp=None): + from jax.extend.core import Primitive + from jax._src.interpreters import ad, batching + primitive=Primitive('essos_split_field_call') + primitive.multiple_results=True + primitive.def_impl(function) + primitive.def_abstract_eval(lambda *avals:tuple(jax.core.ShapedArray((),avals[0].dtype) for _ in range(count))) + self.handlers[primitive]=kernel_function + derivatives={} + def jvp(primals,tangents): + active=tuple(i for i,t in enumerate(tangents) if not isinstance(t,ad.Zero)) + result=primitive.bind(*primals) + if not active:return result,tuple(ad.Zero.from_primal_value(x) for x in result) + if active not in derivatives: + size=len(primals) + def directional(fn): + def evaluate(*args): + def restricted(*values): + primals=list(args[:size]) + for i,v in zip(active,values):primals[i]=v + return fn(*primals) + return jax.jvp(restricted,tuple(args[i] for i in active),args[size:])[1] + return evaluate + def kernel_direction(refs,*args): + if kernel_jvp is not None: + directions=dict(zip(active,args[size:])) + return kernel_jvp(refs,args[:size],tuple(directions.get(i,jnp.zeros_like(args[i])) for i in range(size))) + graph=_flatten(directional(lambda *x:kernel_function(refs,*x)),*args) + return _evaluate_kernel(graph.jaxpr,graph.consts,*args) + derivatives[active]=self.add(directional(function),kernel_direction,count) + return result,derivatives[active](*primals,*(tangents[i] for i in active)) + ad.primitive_jvps[primitive]=jvp + def batch(values,axes): + size=next(x.shape[axis] for x,axis in zip(values,axes) if axis is not None) + rows=[primitive.bind(*(x if axis is None else jnp.take(x,i,axis=axis) for x,axis in zip(values,axes))) for i in range(size)] + return tuple(jnp.stack(column) for column in zip(*rows)),(0,)*count + batching.primitive_batchers[primitive]=batch + return lambda *args:tuple(primitive.bind(*args)) + +def _vmec_position_tangent(refs,point,direction,tables): + """Exact first derivative already returned by the native Fourier series.""" + from .rk import _vmec_series + R,dR=_vmec_series(refs,point,tables['rmnc']) + _,dZ=_vmec_series(refs,point,tables['zmns']) + radial=sum(a*b for a,b in zip(dR,direction));vertical=sum(a*b for a,b in zip(dZ,direction)) + c,s=jnp.cos(point[2]),jnp.sin(point[2]) + return radial*c-R*s*direction[2],radial*s+R*c*direction[2],vertical + +def scalar_graph(graph, constants, *arguments, calls=None, refs=(),memo=None,defer=False): + memo={} if memo is None else memo + def word_key(value): + if isinstance(value,(jax.core.Tracer,jax.Array)): + memo[('retain',id(value))]=value + return ('value',id(value)) + value=np.asarray(value) + return ('literal',value.dtype.str,value.shape,value.tobytes()) + def logical(value, shape): + if isinstance(value, tuple): + out=np.empty((len(value),),object) + for i,v in enumerate(value):out[i]=v + return out.reshape(shape) + if isinstance(value,(np.ndarray,np.generic,int,float,bool)): + return np.asarray(value).reshape(shape) + out=np.empty(shape,object) + for index in np.ndindex(shape): + item=value + for axis,i in enumerate(index):item=_select_one(item,i,axis) + out[index]=item if not item.shape else item.reshape(()) + return out + + env={v:logical(x,v.aval.shape) for v,x in zip(graph.constvars,constants)} + env.update({v:logical(x,v.aval.shape) for v,x in zip(graph.invars,arguments)}) + read=lambda v:np.asarray(v.val,dtype=v.aval.dtype) if isinstance(v,Literal) else env[v] + def elements(function,*values): + return np.frompyfunc(function,len(values),1)(*values) + def scalar(value): + while isinstance(value,np.ndarray):value=value.reshape(()).item() + return value + def device_scalar(value,dtype): + while isinstance(value,np.ndarray) and not value.shape:value=value.item() + return jnp.asarray(value,dtype=dtype) + def reduced(value,axes,combine): + result=value + for axis in sorted(axes,reverse=True): + result=np.frompyfunc(combine,2,1).reduce(result,axis=axis) + return result + + for equation in graph.eqns: + values=[read(v) for v in equation.invars];p=equation.params;name=equation.primitive.name + folded={'add':np.add,'sub':np.subtract,'mul':np.multiply,'div':np.divide, + 'neg':np.negative,'abs':np.abs,'sqrt':np.sqrt,'eq':np.equal,'ne':np.not_equal, + 'lt':np.less,'le':np.less_equal,'gt':np.greater,'ge':np.greater_equal, + 'max':np.maximum,'min':np.minimum,'and':np.bitwise_and,'or':np.bitwise_or} + static=all(np.asarray(v).dtype!=object for v in values) + if calls is not None and equation.primitive in calls.handlers: + words=tuple(scalar(v) for v in values) + key=('field',equation.primitive,tuple(word_key(v) for v in words)) + if key not in memo: + arguments=tuple(device_scalar(v,var.aval.dtype) for v,var in zip(words,equation.invars)) + if defer: + memo[key]=equation.primitive.bind(*arguments,**equation.params) + else: + memo[key]=calls.handlers[equation.primitive](refs,*arguments) + result=memo[key] + elif static and name in folded:result=[folded[name](*values)] + elif static and name=='is_finite':result=[np.isfinite(values[0])] + elif static and name=='convert_element_type':result=[values[0].astype(p['new_dtype'])] + elif static and name=='integer_pow':result=[np.power(values[0],p['y'])] + elif static and name=='select_n':result=[np.choose(values[0],values[1:])] + elif name=='platform_index': + backend='cuda' if jax.default_backend()=='gpu' else jax.default_backend() + default=next((i for i,group in enumerate(p['platforms']) if group is None),0) + result=[np.asarray(next((i for i,group in enumerate(p['platforms']) if group is not None and backend in group),default),np.int32)] + elif (name=='call_hi_primitive' and type(p['_prim']).__name__=='SearchSorted' + and np.ndim(values[0])==1 and not np.ndim(values[1])): + # JAX >= 0.12 keeps searchsorted (e.g. inside jnp.interp) as one primitive. + right,query,count='side=right' in repr(p['_prim']),scalar(values[1]),np.empty((),object) + count[()]=sum(jnp.asarray(x<=query if right else xbest) + better=better|(jnp.isnan(item)&~jnp.isnan(best)) + chosen=jnp.where(better,jnp.asarray(i,p['index_dtype']),chosen);best=jnp.where(better,item,best) + out[index]=chosen + result=[out] + elif name=='dot_general': + (lc,rc),(lb,rb)=p['dimension_numbers'];lhs,rhs=values + lf=tuple(i for i in range(lhs.ndim) if i not in lc+lb) + rf=tuple(i for i in range(rhs.ndim) if i not in rc+rb) + batch=tuple(lhs.shape[i] for i in lb) + left=tuple(lhs.shape[i] for i in lf);right=tuple(rhs.shape[i] for i in rf) + inner=int(np.prod([lhs.shape[i] for i in lc])) + lhs=np.transpose(lhs,lb+lf+lc).reshape(batch+(int(np.prod(left)),inner)) + rhs=np.transpose(rhs,rb+rc+rf).reshape(batch+(inner,int(np.prod(right)))) + result=[np.matmul(lhs,rhs).reshape(batch+left+right)] + elif name=='pad': + value=values[0];config=p['padding_config'] + shape=tuple(a+b+n+(n-1)*c for n,(a,b,c) in zip(value.shape,config)) + out=np.empty(shape,object);out.fill(scalar(values[1])) + out[tuple(slice(a,a+n*(c+1),c+1) for n,(a,b,c) in zip(value.shape,config))]=value + result=[out] + elif name.startswith('scatter'): + operand,indices,updates=values;dims=p['dimension_numbers'] + if indices.dtype==object: + raise ValueError('predictor lowering requires static scalar scatter indices') + out=np.array(operand,object,copy=True) + window_axes=[i for i in range(out.ndim) if i not in dims.inserted_window_dims] + batch_axes=[i for i in range(updates.ndim) if i not in dims.update_window_dims] + for index in np.ndindex(updates.shape): + batch=tuple(index[i] for i in batch_axes);target=[0]*out.ndim + for axis,item in zip(dims.scatter_dims_to_operand_dims,indices[batch]):target[axis]=int(item) + for axis,i in zip(window_axes,dims.update_window_dims):target[axis]+=index[i] + if any(i<0 or i>=n for i,n in zip(target,out.shape)):continue + target=tuple(target);new=updates[index] + out[target]=out[target]+new if name=='scatter-add' else new + result=[out] + elif name=='gather': + operand,indices=values;dims=p['dimension_numbers'] + if indices.dtype==object: + from itertools import product + out=np.empty(equation.outvars[0].aval.shape,object) + batch_axes=[i for i in range(out.ndim) if i not in dims.offset_dims] + window_axes=[i for i in range(operand.ndim) if i not in dims.collapsed_slice_dims] + for index in np.ndindex(out.shape): + batch=tuple(index[i] for i in batch_axes);selected=[0]*operand.ndim + for axis,item in zip(dims.start_index_map,indices[batch]):selected[axis]=jnp.clip(item,0,operand.shape[axis]-p['slice_sizes'][axis]) + for axis,i in zip(window_axes,dims.offset_dims):selected[axis]+=index[i] + choices=[range(n) if isinstance(i,jax.core.Tracer) else (int(i),) for i,n in zip(selected,operand.shape)] + value=operand[tuple(next(iter(c)) for c in choices)] + for source in product(*choices): + match=jnp.asarray(True) + for i,j in zip(selected,source):match &= i==j + value=jnp.where(match,operand[source],value) + out[index]=value + result=[out] + env.update((v,logical(x,v.aval.shape)) for v,x in zip(equation.outvars,result)) + continue + pieces=[] + for index in np.ndindex(indices.shape[:-1]): + starts=[0]*operand.ndim + for axis,item in zip(dims.start_index_map,indices[index]):starts[axis]=int(item) + block=operand[tuple(slice(a,a+n) for a,n in zip(starts,p['slice_sizes']))] + pieces.append(np.squeeze(block,axis=dims.collapsed_slice_dims)) + result=[np.asarray(pieces,dtype=object).reshape(equation.outvars[0].aval.shape)] + else: + parameters=dict(p) + if name=='convert_element_type':parameters['weak_type']=False + def bind(*xs): + if all(not isinstance(x,jax.core.Tracer) for x in xs): + if name in folded:return folded[name](*xs) + if name=='integer_pow':return np.power(xs[0],p['y']) + if name=='convert_element_type':return np.asarray(xs[0],dtype=p['new_dtype']) + if name=='select_n':return xs[1+int(xs[0])] + if name=='is_finite':return _kernel_is_finite(xs[0]) if isinstance(xs[0],jax.core.Tracer) else np.isfinite(xs[0]) + if name=='erf': + return _kernel_erf().bind(jnp.asarray(xs[0])) + if name=='integer_pow': + return _kernel_integer_power(device_scalar(xs[0],equation.invars[0].aval.dtype),p['y']) + if name=='add_any':return xs[0]+xs[1] + if name=='le_to':return jnp.less_equal(*xs)|jnp.isnan(xs[1]) + return _bind_primitive(equation.primitive,[device_scalar(x,v.aval.dtype) for x,v in zip(xs,equation.invars)],parameters) + signature=None + try: + signature=('scalar',equation.primitive,tuple(parameters.items()), + tuple((v.aval.dtype.str,v.aval.weak_type) for v in equation.invars)) + hash(signature) + except TypeError:signature=None + if equation.effects:signature=None + def cached(*xs): + if signature is None:return bind(*xs) + key=signature+tuple(word_key(v) for v in xs) + if key not in memo:memo[key]=bind(*xs) + return memo[key] + try:result=[elements(cached,*values)] + except (ValueError,TypeError,NotImplementedError) as error: + raise ValueError(f"scalar predictor operation {name}, input shapes {[v.aval.shape for v in equation.invars]}: {error}") from error + env.update((v,logical(x,v.aval.shape)) for v,x in zip(equation.outvars,result)) + return tuple(jnp.asarray(scalar(read(v)),dtype=v.aval.dtype) if not v.aval.shape else read(v) for v in graph.outvars) + +def _scalar_predictor(graph,calls): + """Simplify scalar moment algebra before expanding native field reductions.""" + variables=(*graph.jaxpr.constvars,*graph.jaxpr.invars) + def evaluate(*words): + values=[];offset=0 + for variable in variables: + size=variable.aval.size + values.append(tuple(words[offset:offset+size]));offset+=size + count=len(graph.jaxpr.constvars) + return scalar_graph(graph.jaxpr,values[:count],*values[count:],calls=calls,defer=True) + examples=tuple(jnp.zeros((),v.aval.dtype) for v in variables for _ in range(v.aval.size)) + return _flatten(evaluate,*examples) + +def prepare_physics(field, field_view, build, initial, noise_dim,*,predictor_only=False,spatial_geometry=None): + """Compile the production orbit, kick and predictor into one GPU factory. + + Only field evaluation has a private adapter. Every collision map, physical + normalization and moment derivative is the same function as shared JAX. + """ + from .rk import _coil_field_values, _dot, _cross, _vmec_quantities, _vmec_series, _KernelField + from .dynamics import _gc_quantities + from .fields import BiotSavart, Vmec + from .boozer import BoozerField + calls=KernelCalls();coil=isinstance(field,BiotSavart);vmec=isinstance(field,Vmec) + boozer=isinstance(field,BoozerField) + arrays,metadata=field_view if field_view is not None else ((),None) + nsource=len(arrays) + extra=[] + + def flatten_values(values): + return tuple(v for item in values for v in (tuple(item) if isinstance(item,(tuple,list)) or getattr(item,'ndim',0) else (item,))) + def ordinary(fn): + graph=_flatten(fn,*(jnp.zeros((),jnp.float64) for _ in range(3))) + start=len(arrays)+len(extra);extra.extend(graph.consts) + def evaluate(refs,*args): + constants=[tuple(ref[index] for index in np.ndindex(v.shape)) if v.ndim else ref[()] + for v,ref in zip(graph.consts,refs[start:start+len(graph.consts)])] + return scalar_graph(graph.jaxpr,constants,*args) + return evaluate + def geometric(*point):return flatten_values(_gc_quantities(field,jnp.asarray(point))) + def fast_geometry(refs,*point): + if vmec:return flatten_values(_vmec_quantities(refs,point,metadata)) + B,J=_coil_field_values(refs,point,*metadata,True) + magnitude=jnp.sqrt(_dot(B,B)) + gradient=tuple(sum(J[i][j]*B[i]/magnitude for i in range(3)) for j in range(3)) + curl=(J[2][1]-J[1][2],J[0][2]-J[2][0],J[1][0]-J[0][1]) + correction=_cross(B,gradient) + curl=tuple(curl[i]/magnitude+correction[i]/magnitude**2 for i in range(3)) + curvature=tuple(-v/magnitude for v in _cross(B,curl)) + return (*B,*B,magnitude,*gradient,*curl,*curvature,jnp.asarray(1.,magnitude.dtype)) + geometry=None if boozer else calls.add(geometric,fast_geometry if coil or vmec else ordinary(geometric),17) + + def absb(*point):return (field.modB(*point) if boozer else field.AbsB(jnp.asarray(point)),) + def fast_absb(refs,*point): + if coil: + B,_=_coil_field_values(refs,point,*metadata,False) + return (jnp.sqrt(_dot(B,B)),) + if vmec:return (_vmec_series(refs,point,metadata['bmnc'])[0],) + model=_KernelField(refs[:nsource],float(field.psi0)) + graph=_flatten(lambda r,theta,z:model.modB_derivatives(r,theta,z)[0],jnp.sqrt(point[0]),point[1],point[2]) + return _evaluate_kernel(graph.jaxpr,graph.consts,jnp.sqrt(point[0]),point[1],point[2]) + magnitude=calls.add(absb,fast_absb if coil or vmec or boozer else ordinary(absb),1) + if not boozer: + vector=lambda *point:tuple(field.B_contravariant(jnp.asarray(point))) + fast_vector=(lambda refs,*point:_coil_field_values(refs,point,*metadata,False)[0]) if coil else ( + lambda refs,*point:_vmec_quantities(refs,point,metadata)[1]) if vmec else ordinary(vector) + magnetic_vector=calls.add(vector,fast_vector,3) + + class View: + def gc_quantities(self,point): + v=geometry(*point) + return jnp.asarray(v[:3]),jnp.asarray(v[3:6]),v[6],jnp.asarray(v[7:10]),jnp.asarray(v[10:13]),jnp.asarray(v[13:16]),v[16] + def AbsB(self,point):return magnitude(*point)[0] + def B_contravariant(self,point):return jnp.asarray(magnetic_vector(*point)) + def B_covariant(self,point):return self.gc_quantities(point)[0] + view=View() + if vmec: + xyz=lambda s,theta,z:tuple(field.to_xyz(jnp.array([s,theta,z]))) + def fast_xyz(refs,s,theta,z): + R=_vmec_series(refs,(s,theta,z),metadata['rmnc'])[0] + Z=_vmec_series(refs,(s,theta,z),metadata['zmns'])[0] + return R*jnp.cos(z),R*jnp.sin(z),Z + position=calls.add(xyz,fast_xyz,3,kernel_jvp=lambda refs,p,d:_vmec_position_tangent(refs,p,d,metadata)) + view.to_xyz=lambda point:jnp.asarray(position(*point)) + if boozer: + def modb(r,theta,z):return tuple(field.modB_derivatives(r,theta,z)) + def profiles(s):return flatten_values(field.profiles(s)) + def boozer_fast(fn): + def evaluate(refs,*args): + model=_KernelField(refs[:nsource],float(field.psi0)) + graph=_flatten(lambda *x:fn(model,*x),*args) + return _evaluate_kernel(graph.jaxpr,graph.consts,*args) + return evaluate + mod=calls.add(modb,boozer_fast(lambda model,*x:tuple(model.modB_derivatives(*x))),4) + prof=calls.add(profiles,boozer_fast(lambda model,s:flatten_values(model.profiles(s))),6) + view.modB_derivatives=lambda *point:mod(*point) + view.modB=lambda *point:magnitude(*point)[0] + view.profiles=lambda s:(prof(s)[:3],prof(s)[3:]) + view.psi0=field.psi0 + if spatial_geometry is not None: + xyz=lambda *q:tuple(spatial_geometry(jnp.asarray(q))) + if hasattr(spatial_geometry,'_kernel_view'): + data,evaluate=spatial_geometry._kernel_view();start=nsource+len(extra);extra.extend(data) + fast_xyz=lambda refs,*q:evaluate(refs[start:start+len(data)],*q) + else:fast_xyz=ordinary(xyz) + position=calls.add(xyz,fast_xyz,3) + view.to_xyz=lambda point:jnp.asarray(position(*point)) + nfield=len(arrays)+len(extra) + arrays=tuple(arrays)+tuple(extra) + rhs,kick,norm,level,limit=build(view) + nstate=initial.size + def kicked(y,h,dw): + result=kick(0.,y,h,dw,None) + return (*result.y,result.drift_error,result.diffusion_error) + graphs=([] if predictor_only else [ + _flatten(lambda y:tuple(rhs(0.,y,None)),initial), + _flatten(kicked,initial,jnp.asarray(1e-9),jnp.zeros(noise_dim)), + _flatten(lambda y,e:norm(y,y,e),initial,jnp.zeros_like(initial)), + _flatten(lambda y:level(0.,y,None),initial)]) + if coil and nstate==6: + def vector_jet(refs,*point): + B,J=_coil_field_values(refs,point,*metadata,True) + return (*B,*(x for row in J for x in row)) + magnetic_vector=calls.first_jet(vector,vector_jet) + graphs.append(_flatten(lambda t,y:limit(t,y,None),jnp.asarray(0.),initial)) + prediction=_scalar_predictor(graphs[-1],calls) + all_arrays=tuple(arrays)+tuple(v for graph in graphs for v in graph.consts) + def factory(refs,y0): + offset=nfield;constants=[] + for graph in graphs: + values=[] + for v,ref in zip(graph.consts,refs[offset:offset+len(graph.consts)]): + values.append(tuple(ref[index] for index in np.ndindex(v.shape)) if v.ndim else ref[()]) + constants.append(values);offset+=len(graph.consts) + def evaluate(i,*args): + if i==len(graphs)-1: + words=tuple(word for value in (*constants[i],*args) + for word in (value if isinstance(value,tuple) else (value,))) + return scalar_graph(prediction.jaxpr,prediction.consts,*words,calls=calls,refs=refs[:nfield]) + return scalar_graph(graphs[i].jaxpr,constants[i],*args,calls=calls,refs=refs[:nfield]) + state=lambda y:tuple(scalar(y,i) for i in range(nstate)) + if predictor_only: + return None,None,None,None,lambda t,y:evaluate(0,t,state(y))[0] + def padded(values):return pack(tuple(values)+(scalar(y0,7),)*(8-len(values))) + def rhs(y):return padded(evaluate(0,state(y))) + def kick(y,h,dw): + result=evaluate(1,state(y),h,tuple(scalar(dw,i) for i in range(noise_dim))) + return padded(result[:nstate]),result[-2],result[-1] + def norm(y,e,speed,budget):return evaluate(2,state(y),state(e))[0] + return rhs,kick,norm,lambda y:evaluate(3,state(y))[0],lambda t,y:evaluate(4,t,state(y))[0] + return all_arrays,factory diff --git a/examples/benchmarks/analyze_collisional_convergence.py b/examples/benchmarks/analyze_collisional_convergence.py new file mode 100644 index 00000000..eea42bf7 --- /dev/null +++ b/examples/benchmarks/analyze_collisional_convergence.py @@ -0,0 +1,24 @@ +"""Conditional spatial-noise statistic shared by accepted physics benchmarks.""" +import numpy as np +from scipy.stats import expon, kstest + + +def conditional_spatial_statistics(msd, integral): + """Conditional spatial-noise check for the uniform-field discrete scheme. + + For each trajectory Q=4 sum D_X h. Given its velocity/noise-selected grid, + independent perpendicular spatial noise gives |X_perp|^2/Q ~ Exp(mean=1). + The unscaled terminal displacement is a variance mixture, not a universal + chi-square distribution. This tests noise bookkeeping separately from + whether Q converges to its continuous physical reference. + """ + msd, integral = np.asarray(msd), np.asarray(integral) + if msd.shape != integral.shape or msd.ndim != 1 or len(msd) < 2: + raise ValueError("need matching independent particle arrays") + if np.any(~np.isfinite(msd) | ~np.isfinite(integral) | (msd < 0) | (integral <= 0)): + raise ValueError("need nonnegative displacements and positive finite diffusion integrals") + ratio = msd/integral + ks = kstest(ratio, expon.cdf) + return dict(ratio=ratio.tolist(), mean=float(ratio.mean()), + mean_se_under_null=float(1/np.sqrt(len(ratio))), ks_distance=float(ks.statistic), + ks_pvalue=float(ks.pvalue), marginal_99_dkw_limit=float(np.sqrt(np.log(200)/(2*len(ratio))))) diff --git a/examples/benchmarks/benchmark_combined_validation.py b/examples/benchmarks/benchmark_combined_validation.py new file mode 100644 index 00000000..bba20d2a --- /dev/null +++ b/examples/benchmarks/benchmark_combined_validation.py @@ -0,0 +1,112 @@ +"""Independent coupled axial GC moment references for retained benchmarks.""" +import json +from time import perf_counter +import numpy as np +from .mirror_collision_reference import MirrorCollisionReference,interpolation_weights + +VARIABLES=('position','speed','pitch','parallel') +PAIRS=((0,1),(0,2),(0,3),(1,2),(1,3),(2,3)) + + +def observables(z,r,xi): + p=r*xi + return np.stack((np.ones_like(z),z,r,xi,p,z*z,r*r,xi*xi,p*p,z*r,z*xi,z*p,r*p,xi*p),axis=-1) + +def moments(raw): + raw=np.asarray(raw);mean=raw[...,1:5] + covariance=np.zeros(mean.shape[:-1]+(4,4)) + for i in range(4):covariance[...,i,i]=raw[...,5+i]-mean[...,i]**2 + for (i,j),index in zip(PAIRS,(9,10,11,4,12,13)): + covariance[...,i,j]=covariance[...,j,i]=raw[...,index]-mean[...,i]*mean[...,j] + return dict(mean=mean.tolist(),covariance=covariance.tolist(),mass=raw[...,0].tolist()) + +def reference(field,times,grid): + """Same independently coded generator, more joint observables.""" + if field=='mirror': + nz,nr,nxi,steps=grid + ref=MirrorCollisionReference(nz=nz,nr=nr,nxi=nxi) + z,r,xi=np.meshgrid(ref.z,ref.r,ref.xi,indexing='ij') + f=observables(z,r,xi) + else: + nr,nxi,steps=grid + ref=MirrorCollisionReference(nz=8,nr=nr,nxi=nxi) + r,xi=np.meshgrid(ref.r,ref.xi,indexing='ij') + # Exact polynomial transport in z, retaining coefficients of z**0/1/2. + f=np.zeros((3,nr,nxi,14));f[0]=observables(np.zeros_like(r),r,xi) + f[1,...,1]=1.;f[2,...,5]=1. + f[1,...,9]=r;f[1,...,10]=xi;f[1,...,11]=r*xi + u=.5*r*xi/(1-.75*20000*r*xi/2000000) + ir,wr=interpolation_weights(ref.r,np.asarray(np.sqrt(10.))) + ix,wx=interpolation_weights(ref.xi,np.asarray(.6)) + h=times[-1]/((len(times)-1)*steps) + half,whole=ref.collision_matrices(h) + mapping=ref.characteristics(h) if field=='mirror' else None + values=[observables(np.asarray(0.),np.asarray(np.sqrt(10.)),np.asarray(.6))] + current=ref.collide(f,half) + for k in range(1,(len(times)-1)*steps+1): + if field=='mirror':current=ref.transport(current,mapping) + else: + old=current.copy();shift=(h*u)[...,None] + current[0]=old[0]+shift*old[1]+shift*shift*old[2] + current[1]=old[1]+2*shift*old[2] + if k%steps==0: + value=ref.collide(current,half) + values.append(ref.evaluate(value) if field=='mirror' else np.einsum('i,j,ijo->o',wr,wx,value[0,ir[:,None],ix[None,:]])) + if k<(len(times)-1)*steps:current=ref.collide(current,whole) + answer=moments(values) + assert np.max(abs(np.asarray(answer['mass'])-1))<1e-9 + assert np.min(np.diagonal(np.asarray(answer['covariance'])[1:],axis1=-2,axis2=-1))>-1e-8 + return answer + +def references(options): + report=dict(times=np.asarray(getattr(options,'times',np.linspace(0.,.025,6))).tolist(),variables=VARIABLES, + scope='Independent backward Fokker-Planck generator for coupled z/speed/pitch motion, plus parallel velocity. Helix uses exact polynomial-in-z transport. No native tracer or stochastic trajectories.',fields={}) + for field in options.fields: + grids=([(65,32,33,4),(97,48,49,8),(145,64,65,16),(97,48,49,16)] if field=='mirror' else + [(128,12,16),(256,16,32),(384,24,64),(256,16,64)]) + grids=[(*grid[:-1],max(1,int(np.ceil(grid[-1]*5/(len(report['times'])-1))))) for grid in grids] + grids[-1]=(*grids[-1][:-1],max(grids[-1][-1],2*grids[1][-1])) + rows=[] + for grid in grids: + print('Coupled physical reference',field,grid,flush=True) + start=perf_counter();value=reference(field,np.asarray(report['times']),grid) + rows.append(dict(grid=grid,seconds=perf_counter()-start,**value)) + report['fields'][field]=dict(levels=rows) + (options.output/'reference.json').write_text(json.dumps(report,indent=2,allow_nan=False)+'\n') + print('Reference finished',field,grid,rows[-1]['seconds'],flush=True) + return report + +def uncertainty(levels): + fine,medium,temporal=levels[2],levels[1],levels[3] + return {name:np.maximum(abs(np.asarray(fine[name])-medium[name]),abs(np.asarray(temporal[name])-medium[name])) for name in ('mean','covariance')} + +def add_speed_reference(options,data): + """Use the better-resolved independent radial marginal for speed moments. + + Six-point evaluation preserves the exact monoenergetic birth moments; + two-point evaluation otherwise introduces a small initial mesh variance. + Only smooth moments use these signed interpolation weights, not CDFs. + """ + if 'speed_reference' in data:return + from .thermal_relaxation_reference import RelaxationReference,impact_coefficients + levels=[] + for nodes in (768,1536): + ref=RelaxationReference(lower=.05*np.sqrt(2.),nodes=nodes,law=impact_coefficients) + index,weight=interpolation_weights(ref.grid,np.asarray(np.sqrt(10.))) + ref.evaluate[:]=0.;ref.evaluate[index]=weight;ref._spectra={} + birth=np.dot(ref.evaluate,ref.grid**2)-np.dot(ref.evaluate,ref.grid)**2 + assert abs(birth)<1e-12 + value=ref.moments(np.asarray(data['times'])) + levels.append(dict(nodes=nodes,initial_variance=float(birth),speed_mean=value['speed_mean'].tolist(),speed_variance=value['speed_variance'].tolist())) + data['speed_reference']=dict(levels=levels,scope='Independent radial finite-volume generator; high-order evaluation of smooth moments at the exact birth. The magnetic field does no work in either benchmark.') + (options.output/'reference.json').write_text(json.dumps(data,indent=2,allow_nan=False)+'\n') + +def physical_moments(data,field): + levels=data['fields'][field]['levels'];ref=levels[2] + mu=np.asarray(ref['mean']).copy();cov=np.asarray(ref['covariance']).copy() + error=uncertainty(levels) + a,b=data['speed_reference']['levels'] + mu[:,1]=b['speed_mean'];cov[:,1,1]=b['speed_variance'] + error['mean'][:,1]=abs(np.asarray(b['speed_mean'])-a['speed_mean']) + error['covariance'][:,1,1]=abs(np.asarray(b['speed_variance'])-a['speed_variance']) + return mu,cov,error diff --git a/examples/benchmarks/benchmark_native_ad.py b/examples/benchmarks/benchmark_native_ad.py new file mode 100644 index 00000000..d881d663 --- /dev/null +++ b/examples/benchmarks/benchmark_native_ad.py @@ -0,0 +1,227 @@ +"""Reproduce accepted-path gradient checks and blocked timing/memory measurements. + +Run each field/model/stepping case in a fresh process for allocator peaks. +No particle chunking, field interpolation, fitted controller or GPU selection +is imposed. JAX uses the machine's selected backend. +""" +import argparse +import json +from pathlib import Path +from time import perf_counter +import jax +import jax.numpy as jnp +import numpy as np +from essos.constants import ALPHA_PARTICLE_MASS as M, ALPHA_PARTICLE_CHARGE as Q, ONE_EV +from essos.coils import Coils +from essos.fields import BiotSavart, Vmec +from essos.boozer import BoozerField, psi0_from_vmec +from essos.dynamics import Particles +from essos.background_species import BackgroundSpecies +from essos.split import trace_split, BoozerGeometry + +ROOT=Path(__file__).resolve().parents[2] + + +def build(options): + if options.kernel_audit: + return kernel_audit(options) + geometry=None; n=options.particles + if options.field=='coils': + base=Coils.from_json(str(ROOT/'examples/input_files/ESSOS_biot_savart_LandremanPaulQA.json')) + coil_dofs=jnp.asarray(base.dofs) + points=jnp.column_stack((jnp.linspace(1.23,1.27,n),jnp.zeros((n,2)))) + field=None + elif options.field=='vmec': + field=Vmec(str(options.wout),ntheta=8,nphi=8) + coil_dofs=jnp.empty(0) + else: + from booz_xform_jax import Booz_xform + from netCDF4 import Dataset + transform=Booz_xform(verbose=0,mboz=options.mboz,nboz=options.nboz) + transform.read_wout(str(options.wout),flux=False);transform.run() + with Dataset(options.wout) as data: psi=psi0_from_vmec(data['phi'][-1]) + field=BoozerField.from_booz(transform.s_b,transform.bmnc_b,transform.xm_b,transform.xn_b, + transform.iota,transform.Boozer_G,transform.Boozer_I,psi,transform.nfp, + mode_tolerance=options.mode_cut) + geometry=BoozerGeometry.from_booz_xform(transform) + coil_dofs=jnp.empty(0) + if options.field!='coils': + rng=np.random.default_rng(options.seed) + points=jnp.asarray(np.column_stack((np.full(n,.3),rng.uniform(0,2*np.pi,n), + rng.uniform(0,2*np.pi/field.nfp,n)))) + bath=BackgroundSpecies(1,jnp.array([1.]),jnp.array([1.]),jnp.array([1e20]),jnp.array([1000.])) + pitch=jnp.linspace(.35,.65,n) + parameters=jnp.concatenate((coil_dofs,jnp.zeros(3))) + gc=options.model=='gc';adaptive=options.stepping=='adaptive' + dt=options.horizon/4 if adaptive else options.horizon/options.steps + times=jnp.linspace(0.,options.horizon,options.saves) + def run(p, *, adjoint='none', record=False, tapes=None): + source=BiotSavart(base.with_dofs(p[:-3])) if options.field=='coils' else field + shifted=points.at[:,0].add(p[-3]) + birth=Particles(shifted,mass=M,charge=Q,energy=options.energy_ev*ONE_EV*jnp.exp(p[-1]), + initial_vparallel_over_v=pitch+p[-2],field=source if not gc else None,phase_angle_full_orbit=jnp.pi) + birth.random_keys=jax.random.split(jax.random.key(options.seed),n) + return trace_split(source,birth,bath,model='GuidingCenter' if gc else 'FullOrbit', + tmax=options.horizon,timestep=dt,collision_dtmax=options.horizon/2 if adaptive else dt, + times=times,orbit_dt0=dt,adaptive=adaptive,orbit_adaptive=adaptive, + rtol=options.rtol,atol=options.atol,collision_tolerance=.001, + moment_tolerance=options.moment_tolerance,spatial_geometry=geometry, + spatial_diffusion=gc,execution='shared' if tapes is not None else options.execution, + reverse_execution=options.reverse_execution,adjoint=adjoint, + max_steps=options.max_steps,max_orbit_steps=options.max_orbit_steps, + adjoint_max_accepted_steps=options.capacity,adjoint_max_orbit_steps=options.capacity, + adjoint_checkpoint_steps=options.segment,adjoint_orbit_checkpoint_steps=options.segment, + _record_ad=record,_replay_tapes=tapes) + def metric(saved,final): + # The same smooth scalar in every chart, in that chart's public units. + # Position/pitch/energy derivatives are all exercised. This is an AD + # diagnostic, not a proposed confinement objective. + speed=np.sqrt(2*options.energy_ev*ONE_EV/M) + return jnp.mean(jnp.sum(saved[...,:3]**2,axis=-1))+jnp.mean(final[...,3]**2)/speed**2 + return parameters,run,metric + + +def kernel_audit(options): + """Small field/kernel regression fixtures, separate from physical statistics.""" + from types import SimpleNamespace + from essos.coils import CreateEquallySpacedCurves + gc=options.model=='gc';coordinate=options.field!='coils';geometry=None + if options.field=='coils': + base=Coils(CreateEquallySpacedCurves(1,1,1.,.4,7,1,False),[1e6]) + dofs=jnp.asarray(base.dofs) + elif options.field=='vmec': + field=Vmec(str(options.wout),ntheta=8,nphi=8) + else: + s=np.linspace(.005,.995,5) + field=BoozerField.from_booz(s,np.stack((s*0+5.,-.2*np.sqrt(s))),[0,1],[0,0], + s*0+.4,s*0+40.,s*0,40.,1,angle_grid=None) + radial=np.array([.1,.3,.5]);r=.2*np.sqrt(radial) + geometry=BoozerGeometry.from_booz_xform(SimpleNamespace(s_b=radial,xm_b=np.array([0,1]),xn_b=np.zeros(2), + rmnc_b=np.stack((radial*0+2.,r)),zmns_b=np.stack((radial*0,r)), + numns_b=np.stack((radial*0,.05*np.sqrt(radial))))) + bath=BackgroundSpecies(1,jnp.array([1.]),jnp.array([1.]),jnp.array([1e20]),jnp.array([1000.])) + options.particles=1;options.horizon=2e-10 if coordinate else 2e-9;options.saves=3 + options.energy_ev=4000.;options.steps=2 + p=jnp.array([.4,1.,.3 if coordinate else 0.]) + def run(p, *, adjoint='none', record=False, tapes=None): + source=field if coordinate else BiotSavart(base.with_dofs(dofs.at[0].add(p[2]))) + points=jnp.array([[p[2],.2,.1]]) if coordinate else jnp.array([[1.,.03,.01]]) + birth=Particles(points,mass=M,charge=Q,energy=4000*ONE_EV*p[1],initial_vparallel_over_v=p[:1], + field=source if not gc else None) + return trace_split(source,birth,bath,model='GuidingCenter' if gc else 'FullOrbit', + tmax=options.horizon,timestep=options.horizon/2,n_save=3, + execution='shared' if tapes is not None else options.execution, + adjoint=adjoint,reverse_execution=options.reverse_execution, + adaptive=options.stepping=='adaptive',orbit_adaptive=options.stepping=='adaptive', + moment_tolerance=.01,max_steps=16,max_orbit_steps=16, + adjoint_max_accepted_steps=16,adjoint_max_orbit_steps=32, + adjoint_orbit_checkpoint_steps=2,spatial_geometry=geometry,_record_ad=record,_replay_tapes=tapes) + speed=np.sqrt(8000*ONE_EV/M) + def metric(saved,final): + spatial=jnp.sum(saved[...,:3]**2) + return (spatial+jnp.sum(final[...,3])/speed+jnp.sum(final[...,4])/(4000*ONE_EV) if coordinate else + spatial+jnp.sum(final[...,3]**2)/1e12) + return p,run,metric + + +def measure(function, parameters, repeats): + start=perf_counter();exe=jax.jit(function).lower(parameters).compile() + compile_s=perf_counter()-start + start=perf_counter();result=jax.block_until_ready(exe(parameters)) + first_s=perf_counter()-start + stats=jax.devices()[0].memory_stats() + jax.block_until_ready(exe(parameters)) + samples=[] + for _ in range(repeats): + start=perf_counter();jax.block_until_ready(exe(parameters));samples.append(1000*(perf_counter()-start)) + memory=exe.memory_analysis() + buffers=sum(getattr(memory,k,0) or 0 for k in + ('argument_size_in_bytes','output_size_in_bytes','temp_size_in_bytes'))-(getattr(memory,'alias_size_in_bytes',0) or 0) + return result,dict(compile_s=compile_s,first_s=first_s,warm_ms=float(np.median(samples)), + samples_ms=samples,compiled_buffers_bytes=buffers,allocator_after_first=stats) + + +def main(): + parser=argparse.ArgumentParser(description=__doc__) + parser.add_argument('--field',choices=('coils','vmec','boozer'),default='coils') + parser.add_argument('--model',choices=('gc','lorentz'),default='gc') + parser.add_argument('--stepping',choices=('fixed','adaptive'),default='adaptive') + parser.add_argument('--execution',choices=('shared','independent')) + parser.add_argument('--reverse-execution',choices=('auto','shared','independent'),default='auto') + parser.add_argument('--particles',type=int,default=64);parser.add_argument('--repeats',type=int,default=3) + parser.add_argument('--horizon',type=float,default=2e-6);parser.add_argument('--steps',type=int,default=28) + parser.add_argument('--saves',type=int,default=8);parser.add_argument('--seed',type=int,default=42) + parser.add_argument('--energy-ev',type=float,default=4000.) + parser.add_argument('--rtol',type=float,default=1e-9);parser.add_argument('--atol',type=float,default=1e-9) + parser.add_argument('--moment-tolerance',type=float,default=.01) + parser.add_argument('--segment',type=int,default=16);parser.add_argument('--capacity',type=int,default=4096) + parser.add_argument('--max-steps',type=int,default=4096);parser.add_argument('--max-orbit-steps',type=int,default=256) + parser.add_argument('--wout',type=Path,default=ROOT/'examples/input_files/wout_LandremanPaul2021_QA_reactorScale_lowres.nc') + parser.add_argument('--mboz',type=int,default=16);parser.add_argument('--nboz',type=int,default=16) + parser.add_argument('--mode-cut',type=float,default=1e-4) + parser.add_argument('--check-gradient',action=argparse.BooleanOptionalAction,default=True) + parser.add_argument('--kernel-audit',action='store_true',help='One-particle derivative fixtures; manufactured Boozer spectrum/geometry') + parser.add_argument('--forward-only',action='store_true',help='Fresh-process forward allocator peak without building AD') + parser.add_argument('--cold-compile',action='store_true',help='Disable the persistent compilation cache for this process') + parser.add_argument('--output',type=Path,default=Path('output/native_ad/comparison.json')) + o=parser.parse_args() + if o.cold_compile:jax.config.update('jax_enable_compilation_cache',False) + if o.execution is None:o.execution='independent' if jax.default_backend()=='gpu' else 'shared' + if o.model=='lorentz' and o.field!='coils':parser.error('Lorentz requires Cartesian coil fields') + if min(o.particles,o.repeats,o.steps,o.saves-1,o.segment,o.capacity,o.max_steps,o.max_orbit_steps)<1: + parser.error('particle/save/work limits must be positive') + if not np.isfinite(o.horizon) or o.horizon<=0:parser.error('positive finite horizon required') + print('Preparing',o.field,o.model,o.stepping,jax.devices()[0],flush=True) + p,run,metric=build(o) + if o.forward_only: + out,forward=measure(run,p,o.repeats) + np.testing.assert_array_equal(out.status,0) + report=dict(field=o.field,model=o.model,stepping=o.stepping,particles=o.particles, + horizon_s=o.horizon,forward=forward,particle_chunking=False,kernel_audit=o.kernel_audit, + peak_scope='Fresh process: setup and first forward execution; no AD executable built', + jax=jax.__version__,device=jax.devices()[0].device_kind,cold_compile=o.cold_compile) + o.output.parent.mkdir(parents=True,exist_ok=True) + o.output.write_text(json.dumps(report,indent=2)+'\n') + print('Forward',forward['warm_ms'],'ms; saved',o.output,flush=True) + return + def objective(p): + out=run(p,adjoint='accepted') + return metric(out.ys,out.y),out + # Compile and execute AD first: the allocator peak includes this case's + # setup/AD compilation/execution, before other executables are built. + ((value,out),gradient),ad=measure(jax.value_and_grad(objective,has_aux=True),p,o.repeats) + print('Complete AD',ad['warm_ms'],'ms',flush=True) + ordinary,forward=measure(run,p,o.repeats) + ad['allocator_peak_scope']='Fresh case setup/AD compilation/first execution, before forward executable' + forward['allocator_peak_scope']='Cumulative after AD; use --forward-only for an isolated forward peak' + np.testing.assert_array_equal(out.status,0) + np.testing.assert_allclose(out.ys,ordinary.ys,rtol=3e-12,atol=1e-15) + np.testing.assert_array_equal(out.stats[:6],ordinary.stats[:6]) + if not np.isfinite(gradient).all():raise AssertionError('nonfinite gradient') + report=dict(field=o.field,model=o.model,stepping=o.stepping,particles=o.particles,horizon_s=o.horizon, + execution=o.execution,reverse_execution=o.reverse_execution,spatial_kicks=o.model=='gc', + moment_tolerance=o.moment_tolerance,rtol=o.rtol,atol=o.atol,seed=o.seed, + jax=jax.__version__,device=jax.devices()[0].device_kind,particle_chunking=False, + dofs=('pitch, energy, first coil DOF' if o.field=='coils' else 'pitch, energy, birth radius') if o.kernel_audit else ( + 'coil Fourier/current parameters and three birth controls' if o.field=='coils' else 'three birth controls; fixed equilibrium'), + kernel_audit=o.kernel_audit,cold_compile=o.cold_compile, + forward=forward,value_and_gradient=ad,total_over_forward=ad['warm_ms']/forward['warm_ms'], + value=float(value),gradient_norm=float(jnp.linalg.norm(gradient)), + collision_updates=np.asarray(out.stats.collision_updates).tolist(), + accepted_orbit_steps=np.asarray(out.stats.accepted_orbit_steps).tolist()) + if o.check_gradient: + recorded,tapes=jax.jit(lambda p:run(p,record=True))(p) + def frozen(p):return metric(*run(p,tapes=tapes)) + direction=jnp.array([.2,.3,.1]) if o.kernel_audit else jnp.asarray(np.random.default_rng(24).normal(size=p.size)) + if not o.kernel_audit:direction/=jnp.linalg.norm(direction) + _,expected=jax.jit(lambda p:jax.jvp(frozen,(p,),(direction,)))(p) + actual=jnp.vdot(gradient,direction) + np.testing.assert_allclose(actual,expected,rtol=5e-7,atol=1e-9) + report.update(directional_reverse=float(actual),directional_frozen_jvp=float(expected)) + o.output.parent.mkdir(parents=True,exist_ok=True) + o.output.write_text(json.dumps(report,indent=2)+'\n') + print('Forward',forward['warm_ms'],'ms; complete/forward',report['total_over_forward'],flush=True) + print('Saved',o.output,flush=True) + + +if __name__=='__main__':main() diff --git a/examples/benchmarks/benchmark_native_boozer_alpha.py b/examples/benchmarks/benchmark_native_boozer_alpha.py new file mode 100644 index 00000000..7d1671ed --- /dev/null +++ b/examples/benchmarks/benchmark_native_boozer_alpha.py @@ -0,0 +1,204 @@ +"""8192-alpha Boozer workload: native Dopri5/8 and the existing fixed RK4 tracer. + +Setup/field transformation is excluded from trace timings. JAX chooses the +machine backend; --execution selects the native solver layout, never a device. +""" +import argparse +import json +import hashlib +from pathlib import Path +from time import perf_counter +import jax +import jax.numpy as jnp +import numpy as np +from netCDF4 import Dataset +from essos.boozer import BoozerField, _start, _advance, psi0_from_vmec +from essos.rk import _boozer_batch as _native_orbits +from essos.constants import ALPHA_PARTICLE_MASS as MASS, ALPHA_PARTICLE_CHARGE as CHARGE, ONE_EV +from essos.rk import RKStatus + +ROOT=Path(__file__).resolve().parents[2] +PARAMETERS=dict(particles=8192,horizon=.02,saves=101,energy_ev=3.52e6,birth_s=.3,seed=42, + timestep=1.25e-7,integrator="essos_dopri8",rtol=1e-10,atol=1e-10,controller="i", + max_steps=1_000_000,mboz=32,nboz=32,mode_cut=1e-4,repeats=2,execution="auto", + wout=ROOT/"examples/input_files/wout_LandremanPaul2021_QA_reactorScale_lowres.nc", + output=Path("output/native_boozer_alpha")) + +def digest(path): + return hashlib.sha256(Path(path).read_bytes()).hexdigest() + + +def setup(options): + if options.field_cache is None: + from booz_xform_jax import Booz_xform + transform = Booz_xform(verbose=0, mboz=options.mboz, nboz=options.nboz) + transform.read_wout(str(options.wout), flux=False) + transform.run() + with Dataset(options.wout) as data: + psi0 = psi0_from_vmec(data["phi"][-1]) + values = {name:np.asarray(getattr(transform, key)) for name,key in ( + ("s_grid","s_b"),("bmnc","bmnc_b"),("xm","xm_b"),("xn","xn_b"), + ("iota","iota"),("G","Boozer_G"),("I","Boozer_I"))} + sine = getattr(transform, "bmns_b", None) + if sine is not None: + values["bmns"] = np.asarray(sine) + values.update(psi0=psi0, nfp=int(transform.nfp), mboz=options.mboz, + nboz=options.nboz, wout_sha256=digest(options.wout)) + else: + with np.load(options.field_cache) as cache: + names = ("s_grid","bmnc","xm","xn","iota","G","I","psi0","nfp","mboz","nboz","wout_sha256") + values = {name:cache[name] for name in names} + if "bmns" in cache: + values["bmns"] = cache["bmns"] + if (str(values["wout_sha256"]) != digest(options.wout) or + int(values["mboz"]) != options.mboz or int(values["nboz"]) != options.nboz): + raise ValueError("Cached transform does not match --wout/--mboz/--nboz") + field = BoozerField.from_booz(values["s_grid"], values["bmnc"], values["xm"], values["xn"], + values["iota"], values["G"], values["I"], float(values["psi0"]), int(values["nfp"]), + mode_tolerance=options.mode_cut, bmns=values.get("bmns")) + rng = np.random.default_rng(options.seed) + s = np.full(options.particles, options.birth_s) + theta = rng.uniform(0., 2*np.pi, options.particles) + zeta = rng.uniform(0., 2*np.pi/field.nfp, options.particles) + pitch = rng.uniform(-1., 1., options.particles) + speed = float(np.sqrt(2*options.energy_ev*ONE_EV/MASS)) + magnetic = jax.vmap(field.modB)(jnp.asarray(s), jnp.asarray(theta), jnp.asarray(zeta)) + if not np.all(np.isfinite(magnetic) & (np.asarray(magnetic) > 0)): + raise ValueError("Birth field must be positive and finite") + initial = jnp.asarray(np.column_stack((np.sqrt(s)*np.cos(theta), np.sqrt(s)*np.sin(theta), zeta, speed*pitch))) + mu = speed**2*(1-jnp.asarray(pitch)**2)/(2*magnetic) + births = dict(s=s, theta=theta, zeta=zeta, pitch=pitch, initial=np.asarray(initial), mu=np.asarray(mu)) + return field, initial, mu, speed, births, values + + +def plots(folder, times, states, loss_times, errors, counts): + import matplotlib + matplotlib.use("Agg") + import matplotlib.pyplot as plt + fig, axes = plt.subplots(2, 2, figsize=(11, 8), constrained_layout=True) + lost = (loss_times[:,None] >= 0) & (loss_times[:,None] <= times) + axes[0,0].plot(times*1e3, 100*lost.mean(axis=0)) + axes[0,0].set(xlabel="Time (ms)", ylabel="Lost (%)", title="QA equilibrium boundary: s=1") + for q in (50, 95, 100): + axes[0,1].plot(times*1e3, np.percentile(errors,q,axis=0), label=f"{q}th percentile") + axes[0,1].set(xlabel="Time (ms)", ylabel="Relative energy drift at saved states") + axes[0,1].legend() + axes[1,0].hist(counts[:,1], bins=40, alpha=.7, label="Accepted") + axes[1,0].hist(counts[:,2], bins=40, alpha=.7, label="Rejected") + axes[1,0].set(xlabel="Steps per particle", ylabel="Particles") + axes[1,0].legend() + angles = np.linspace(0., 2*np.pi, 201) + axes[1,1].plot(np.cos(angles), np.sin(angles), "k--", lw=.8) + selected = np.random.default_rng(17).choice(len(states), min(10,len(states)), replace=False) + for i in selected: + radius = np.sqrt(np.maximum(states[i,:,0],0.)) + axes[1,1].plot(radius*np.cos(states[i,:,1]), radius*np.sin(states[i,:,1]), lw=.8) + axes[1,1].set(xlabel="sqrt(s) cos(theta)", ylabel="sqrt(s) sin(theta)", aspect="equal", + title="Up to ten trajectories: flux chart, not metres") + fig.savefig(folder/"benchmark.png", dpi=160) + plt.close(fig) + + +def standard_rk4_orbits(field, initial, mu, speed, times, timestep, seed): + """Call the existing production RK4 driver; no new RK or field formula.""" + intervals = len(times)-1 + n_sub = max(1, int(np.ceil(float(times[-1])/(intervals*timestep)-1e-9))) + dt = float(times[-1])/(intervals*n_sub) + keys = jax.random.split(jax.random.PRNGKey(seed), len(initial)) + + def run(y0, mu0): + carry, first = _start(field, y0, mu0) + carry, values = _advance(field, dt, n_sub, MASS, CHARGE, None, 1.5, + carry, keys, 0, intervals, "rk4", 1e-10) + states = jnp.concatenate((first[:, None], values), axis=1) + status = jnp.where(carry[6] >= 0, RKStatus.NONFINITE, + jnp.where(carry[4] >= 0, RKStatus.EVENT, RKStatus.SUCCESS)) + counts = jnp.stack((carry[10], carry[10], jnp.zeros_like(carry[10])), axis=-1) + return states, carry[4], carry[6], carry[7], counts, status + + return run, dt, n_sub*intervals + + + +def compiler_options(): + if jax.default_backend()=="gpu": + return dict(xla_gpu_enable_command_buffer="FUSION,WHILE,CONDITIONAL",xla_gpu_graph_min_graph_size=1) + return {} + + +def compiled_bytes(executable): + memory=executable.memory_analysis() + return int(memory.argument_size_in_bytes+memory.output_size_in_bytes+memory.temp_size_in_bytes-memory.alias_size_in_bytes) + + +def main(argv=None): + parser=argparse.ArgumentParser(description=__doc__) + for name,value in PARAMETERS.items(): + parser.add_argument('--'+name.replace('_','-'),type=type(value),default=value) + parser.add_argument('--field-cache',type=Path) + options=parser.parse_args(argv) + if options.field_cache is not None and not options.field_cache.is_file(): + parser.error('--field-cache must name an existing boozer_inputs.npz; omit it to build the field') + if options.integrator not in ('essos_rk45','essos_dopri8','rk4') or options.execution not in ('auto','jax','cuda'): + parser.error('Require integrator essos_rk45/essos_dopri8/rk4 and execution auto/jax/cuda') + if (min(options.particles,options.horizon,options.energy_ev,options.timestep,options.atol,options.repeats)<=0 + or options.saves<2 or options.rtol<0 or not 0=2, rtol>=0, 0=0)),failed=int(np.count_nonzero(failed>=0)), + max_relative_energy_error=float(energy.max()) if np.isfinite(energy.max()) else None,fixed_dt=dt,fixed_grid_slots=slots, + collisions=False,reverse_ad=False,particle_chunking=False, + peak_memory_scope='one compiled trace in this process; setup and compilation included', + gpu_memory=jax.devices()[0].memory_stats()) + (options.output/'benchmark.json').write_text(json.dumps(report,indent=2,allow_nan=False)+'\n') + np.savez_compressed(options.output/'traces.npz',times=np.asarray(times),states=states,loss_times=loss,failed_times=failed, + energy_error=energy,counts=counts,status=status) + plots(options.output,np.asarray(times),states,loss, + np.abs(states[:,:,4]**2/speed**2-1),counts) + print(f'Warm median {np.median(samples):.3f} s; lost {report["lost"]}; failed {report["failed"]}; saved {options.output.resolve()}',flush=True) + + +if __name__=='__main__': main() diff --git a/examples/benchmarks/benchmark_native_orbits.py b/examples/benchmarks/benchmark_native_orbits.py new file mode 100644 index 00000000..2bf7b621 --- /dev/null +++ b/examples/benchmarks/benchmark_native_orbits.py @@ -0,0 +1,234 @@ +"""Forward native/Diffrax comparison on bundled coil or VMEC/Boozer fields. + +Each pair uses identical births, fields, save times, error blocks and stepping +mode. Fixed runs use the same dt. All executions block on device completion; +setup and reference integration are excluded. No collisions, AD or chunking. +""" +import argparse +import csv +import hashlib +import json +from pathlib import Path +from time import perf_counter +import diffrax +import equinox as eqx +import jax +import jax.numpy as jnp +import numpy as np +from essos.constants import ALPHA_PARTICLE_MASS as M, ALPHA_PARTICLE_CHARGE as Q, ONE_EV +from essos.coils import Coils +from essos.fields import BiotSavart, Vmec +from essos.dynamics import Particles, GuidingCenter, Lorentz, _axis_regular, _to_axis_regular, _from_axis_regular +from essos.electric_field import Electric_field_zero +from essos.boozer import guiding_center_rhs +from essos.rk import prepare_solver +from essos.rk import _boozer_error_norm +from essos.rk import OrbitErrorNorm +from essos.rk import solve_rk +from .benchmark_native_boozer_alpha import PARAMETERS, setup, compiler_options, compiled_bytes + +ROOT=Path(__file__).resolve().parents[2] + + +def case(options): + rng=np.random.default_rng(options.seed) + speed=float(np.sqrt(2*options.energy_ev*ONE_EV/M)) + if options.field=='coils': + field=BiotSavart(Coils.from_json(str(ROOT/'examples/input_files/ESSOS_biot_savart_LandremanPaulQA.json'))) + points=jnp.column_stack((jnp.linspace(1.23,1.27,options.particles),jnp.zeros((options.particles,2)))) + p=Particles(points,mass=M,charge=Q,energy=options.energy_ev*ONE_EV, + initial_vparallel_over_v=jnp.linspace(.35,.65,options.particles), + field=field if options.model=='lorentz' else None,phase_angle_full_orbit=jnp.pi) + initial=(jnp.column_stack((points,p.initial_vparallel)) if options.model=='gc' else + jnp.column_stack((p.initial_xyz_fullorbit,p.initial_vxvyvz))) + rhs=(lambda t,y,mu:GuidingCenter(t,y,(field,p,Electric_field_zero()))) if options.model=='gc' else ( + lambda t,y,mu:Lorentz(t,y,(field,p))) + norm=OrbitErrorNorm(options.rtol,options.atol,speed,velocity_components=1 if options.model=='gc' else 3) + event=None + moment=jnp.zeros(options.particles) + elif options.field=='vmec': + field=Vmec(str(options.wout),ntheta=8,nphi=8) + points=jnp.asarray(np.column_stack((np.full(options.particles,.3),rng.uniform(0,2*np.pi,options.particles), + rng.uniform(0,2*np.pi/field.nfp,options.particles)))) + p=Particles(points,mass=M,charge=Q,energy=options.energy_ev*ONE_EV, + initial_vparallel_over_v=jnp.asarray(rng.uniform(-.7,.7,options.particles))) + initial=jax.vmap(_to_axis_regular)(jnp.column_stack((points,p.initial_vparallel))) + rhs=_axis_regular(lambda t,y,mu:GuidingCenter(t,y,(field,p,Electric_field_zero()))) + norm=OrbitErrorNorm(options.rtol,options.atol,speed, + position_map=lambda y:field.to_xyz(_from_axis_regular(y)[:3])) + event=lambda t,y,args,**kwargs:1.-y[0]**2-y[1]**2 + moment=jnp.zeros(options.particles) + else: + settings=argparse.Namespace(**(PARAMETERS|vars(options))) + settings.birth_s=.3 + field,initial,moment,speed,_,_=setup(settings) + rhs=lambda t,y,mu:guiding_center_rhs(field,y,mu,M,Q) + norm=lambda y0,y1,error:_boozer_error_norm(error,speed,options.rtol,options.atol) + event=lambda t,y,args,**kwargs:1.-y[0]**2-y[1]**2 + return field,initial,moment,speed,rhs,norm,event + + +def functions(options,data,method,tolerance=None): + field,initial,moment,speed,rhs,norm,event=data + adaptive=options.stepping=='adaptive' + times=np.linspace(0.,options.horizon,options.saves) + dt=options.horizon/4 if adaptive else options.horizon/options.steps + rtol,atol=(options.rtol,options.atol) if tolerance is None else (tolerance,tolerance) + if tolerance is not None: + # Scale the same normalized physical/chart error budget for the reference. + original=norm + norm=lambda y0,y1,e:original(y0,y1,e)*(options.rtol+options.atol)/(rtol+atol) + if options.field=='boozer': + if options.execution=='cuda' and tolerance is None: + from essos.rk import _prepare_boozer_gpu as prepare_orbit_solver + solve=prepare_orbit_solver(field,M,Q,speed,times,dt,rtol,atol,options.max_steps, + method=method,adaptive=adaptive) + else: + solve=lambda y,mu:solve_rk(rhs,y,mu,t1=options.horizon,dt0=dt,ts=times,method=method, + adaptive=adaptive if tolerance is None else True,error_norm=norm,event=event, + rtol=rtol,atol=atol,max_steps=options.max_steps) + else: + prepared=prepare_solver(field,mass=M,charge=Q,energy=options.energy_ev*ONE_EV,times=times, + dt0=dt,model=options.model,method=method,adaptive=adaptive,rtol=rtol,atol=atol, + max_steps=options.max_steps,execution=options.execution) + solve=lambda y,mu:prepared(y) + def native_one(y,mu): + out=solve(y,mu) + return out.ys,out.y,out.t,out.status,jnp.stack(out.stats) + + # Feed the same scalar embedded block error to Diffrax's ordinary I controller. + # Its default component RMS error would impose a different acceptance test. + base=diffrax.Dopri5 if method=='dopri5' else diffrax.Dopri8 + class PhysicalSolver(base): + physical_norm: object=eqx.field(static=True,default=None) + def step(self,terms,t0,t1,y0,args,solver_state,made_jump): + y1,error,dense,state,result=super().step(terms,t0,t1,y0,args,solver_state,made_jump) + return y1,jnp.full_like(error,self.physical_norm(y0,y1,error)),dense,state,result + solver=PhysicalSolver(physical_norm=norm) if adaptive or tolerance is not None else base() + control=(diffrax.PIDController(rtol=0.,atol=1.,pcoeff=0.,icoeff=1.,dcoeff=0.,factormin=.2,factormax=5.) + if adaptive or tolerance is not None else diffrax.ConstantStepSize()) + def diffrax_one(y,mu): + out=diffrax.diffeqsolve(diffrax.ODETerm(rhs),solver,t0=0.,t1=options.horizon,dt0=dt,y0=y,args=mu, + stepsize_controller=control,event=None if event is None else diffrax.Event(event, + root_finder=__import__('optimistix').Bisection(rtol=1e-12,atol=1e-12)), + saveat=diffrax.SaveAt(subs=[diffrax.SubSaveAt(ts=jnp.asarray(times)),diffrax.SubSaveAt(t1=True)]), + max_steps=options.max_steps,throw=False) + status=jnp.where(out.result==diffrax.RESULTS.successful,0, + jnp.where(out.result==diffrax.RESULTS.event_occurred,1,2)) + counts=jnp.stack([out.stats[k] for k in ('num_steps','num_accepted_steps','num_rejected_steps')]) + return out.ys[0],out.ys[1][-1],out.ts[1][-1],status,counts + return jax.jit(jax.vmap(native_one),compiler_options=compiler_options()),jax.jit(jax.vmap(diffrax_one),compiler_options=compiler_options()) + + +def _suite(options): + """Regenerate the README workloads and their aggregate files under output/.""" + rows = [] + for field,model,horizon,steps in (('boozer','gc',options.horizon,options.steps), + ('vmec','gc',options.horizon,options.steps), + ('coils','gc',options.horizon,224), + ('coils','lorentz',2e-6,1792)): + for stepping in ('adaptive','fixed'): + output = options.output/f'{field}_{model}_{stepping}' + settings = vars(options) | dict(field=field,model=model,horizon=horizon, + steps=steps,stepping=stepping,output=output) + arguments = [] + for name,value in settings.items(): + if name=='suite' or value is None or (name=='field_cache' and field!='boozer'): + continue + arguments += ['--'+name.replace('_','-'),*(str(v) for v in value)] if isinstance(value,list) else [ + '--'+name.replace('_','-'),str(value)] + main(arguments) + report = json.loads((output/'comparison.json').read_text()) + for name,row in report['rows'].items(): + rows.append(dict(field=field,model=model,stepping=stepping,solver=name, + **{k:v for k,v in row.items() if k!='warm_ms'})) + with (options.output/'forward.csv').open('w',newline='') as stream: + writer = csv.DictWriter(stream,fieldnames=list(rows[0])) + writer.writeheader() + writer.writerows(rows) + table = ['| Field / model | Stepping | Solver | Warm ms | Buffers MiB |', + '|---|---|---|---:|---:|'] + for row in rows: + table.append(f'| {row["field"]} / {row["model"]} | {row["stepping"]} | {row["solver"]} | ' + f'{row["warm_median_ms"]:.3f} | {row["compiled_buffers_bytes"]/2**20:.3f} |') + (options.output/'forward.md').write_text('\n'.join(table)+'\n') + + +def main(argv=None): + parser=argparse.ArgumentParser(description=__doc__) + parser.add_argument('--field',choices=['coils','vmec','boozer'],default='coils') + parser.add_argument('--model',choices=['gc','lorentz'],default='gc') + parser.add_argument('--stepping',choices=['fixed','adaptive'],default='adaptive') + parser.add_argument('--execution',choices=['jax','cuda'],default='cuda') + parser.add_argument('--suite',action='store_true',help='Regenerate all eight README workloads and aggregate CSV/Markdown') + parser.add_argument('--cases',nargs='+',default=['native_dopri8','diffrax_dopri8']) + for name,value in dict(particles=64,horizon=2e-5,saves=8,steps=160,repeats=3,seed=42,energy_ev=4000., + rtol=1e-9,atol=1e-9,max_steps=4096,mboz=32,nboz=32,mode_cut=1e-4).items(): + parser.add_argument('--'+name.replace('_','-'),type=type(value),default=value) + parser.add_argument('--wout',type=Path,default=PARAMETERS['wout']) + parser.add_argument('--field-cache',type=Path) + parser.add_argument('--output',type=Path,default=Path('output/native_forward_comparison')) + options=parser.parse_args(argv) + if options.model=='lorentz' and options.field!='coils': parser.error('Lorentz requires Cartesian coils') + if options.field_cache is not None and not options.field_cache.is_file(): parser.error('Missing --field-cache') + if min(options.particles,options.horizon,options.steps,options.repeats,options.atol)<=0 or options.saves<2 or options.rtol<0: + parser.error('Require positive counts, horizon, steps, repeats and atol; saves>=2, rtol>=0') + if options.suite: + return _suite(options) + if (options.output/'comparison.json').exists(): parser.error('Choose a fresh output directory') + options.output.mkdir(parents=True,exist_ok=True) + print(f'{jax.devices()}; {options.field}/{options.model}; {options.stepping}; {options.execution}',flush=True) + data=case(options) + initial,moment=data[1:3] + jax.block_until_ready(data[1:4]) + report=dict(settings={k:str(v) if isinstance(v,Path) else v for k,v in vars(options).items()}, + device=jax.devices()[0].device_kind,jax=jax.__version__,collisions=False,reverse_ad=False, + source_sha256={name:hashlib.sha256((ROOT/'essos'/name).read_bytes()).hexdigest() + for name in ('rk.py','fields.py','boozer.py','dynamics.py')}, + birth_sha256=hashlib.sha256(np.asarray(initial).tobytes()).hexdigest(), + input_sha256=hashlib.sha256((ROOT/'examples/input_files/ESSOS_biot_savart_LandremanPaulQA.json' + if options.field=='coils' else options.wout).read_bytes()).hexdigest(), + compiled_buffers_scope='argument + output + temporary - alias; excludes executable constants and resident setup data', + rows={}) + outputs={}; executables={} + for name in options.cases: + backend,method=name.split('_',1) + if backend not in ('native','diffrax') or method not in ('dopri5','dopri8'): parser.error('Invalid --cases') + native,reference=functions(options,data,method) + print('Compiling '+name,flush=True) + start=perf_counter(); exe=(native if backend=='native' else reference).lower(initial,moment).compile() + compile_s=perf_counter()-start + output=jax.block_until_ready(exe(initial,moment)) + jax.block_until_ready(exe(initial,moment)) + outputs[name]=output;executables[name]=exe + report['rows'][name]=dict(compile_s=compile_s,compiled_buffers_bytes=compiled_bytes(exe),warm_ms=[]) + for iteration in range(options.repeats): + for name in list(executables) if iteration%2==0 else reversed(list(executables)): + start=perf_counter(); jax.block_until_ready(executables[name](initial,moment)) + report['rows'][name]['warm_ms'].append(1000*(perf_counter()-start)) + _,reference=functions(options,data,'dopri8',tolerance=1e-12) + truth=jax.block_until_ready(reference(initial,moment))[0] + for name,row in report['rows'].items(): + states,_,_,status,counts=map(np.asarray,outputs[name]); target=np.asarray(truth) + valid=np.isfinite(states).all(-1)&np.isfinite(target).all(-1) + if options.field=='vmec': + mapped=jax.jit(jax.vmap(jax.vmap(lambda y:data[0].to_xyz(_from_axis_regular(y)[:3])))) + position=np.asarray(mapped(jnp.asarray(states)))-np.asarray(mapped(jnp.asarray(target))) + else: position=states[:,:,:3]-target[:,:,:3] + row.update(warm_median_ms=float(np.median(row['warm_ms'])),accepted=int(counts[:,1].sum()), + rejected=int(counts[:,2].sum()),failed=int(np.count_nonzero(status>1)),lost=int(np.count_nonzero(status==1)), + max_position_or_chart_error=float(np.max(np.linalg.norm(position[valid],axis=-1))), + max_velocity_error_m_s=float(np.max(np.linalg.norm( + (states[:,:,3:6 if options.model=='lorentz' else 4]-target[:,:,3:6 if options.model=='lorentz' else 4])[valid],axis=-1))), + max_velocity_error_over_birth_speed=float(np.max(np.linalg.norm( + (states[:,:,3:6 if options.model=='lorentz' else 4]-target[:,:,3:6 if options.model=='lorentz' else 4])[valid],axis=-1))/data[3])) + print(f'{name}: {row["warm_median_ms"]:.3f} ms, {row["accepted"]} accepted, {row["rejected"]} rejected',flush=True) + report['gpu_memory']=jax.devices()[0].memory_stats() + report['peak_scope']='cumulative across setup, compilation, all cases and reference; not a per-solver peak' + (options.output/'comparison.json').write_text(json.dumps(report,indent=2,allow_nan=False)+'\n') + with (options.output/'comparison.csv').open('w',newline='') as f: + rows=[dict(case=name,**{k:v for k,v in row.items() if k!='warm_ms'}) for name,row in report['rows'].items()] + writer=csv.DictWriter(f,fieldnames=rows[0]);writer.writeheader();writer.writerows(rows) + + +if __name__=='__main__': main() diff --git a/examples/benchmarks/benchmark_split_coordinate_physics.py b/examples/benchmarks/benchmark_split_coordinate_physics.py new file mode 100644 index 00000000..d90785de --- /dev/null +++ b/examples/benchmarks/benchmark_split_coordinate_physics.py @@ -0,0 +1,406 @@ +"""Regenerate coupled mirror/helix statistics in Cartesian and flux charts. + +These are coordinate transformations of prescribed fields, not VMEC MHD +equilibria or Boozer K=0 magnetic spectra. Real equilibrium adapter checks are +separate. All charts use the production collision maps, moment predictor, +retained Brownian driver and nonlinear Cartesian spatial-kick inversion. +""" +import argparse +import json +from pathlib import Path +from time import perf_counter +from types import SimpleNamespace +import jax +import jax.numpy as jnp +import numpy as np +from essos.background_species import BackgroundSpecies +from essos.constants import PROTON_MASS as M,ELEMENTARY_CHARGE as Q +from essos.dynamics import _guiding_center_velocity +from essos.electric_field import Electric_field_zero +from essos.rk import OrbitErrorNorm +from essos.split import (solve_split,collision_coefficients,guiding_center_collision_step, + guiding_center_spatial_increment,particle_collision_step,native_step_limit,move_in_cartesian,BoozerGeometry) +from .benchmark_split_mirror import MagneticMirror +from .benchmark_split_helix import HelicalField +from .benchmark_split_multirate import UniformMagneticField +from .nonrelativistic_collision_reference import ProtonBackground +from .validate_beam_relaxation import estimate +from .collision_plotting import presentation, series, save + + +def chart_maps(chart,scale): + """Circular-tube embedding, regular axis variables and VMEC angle gauge. + + The Boozer-style chart also has a toroidal angle shift. This manufactured + geometry checks coordinate covariance; it is not a magnetic equilibrium. + """ + if chart=='cartesian':return lambda y:y,lambda y:y + gauge=.2 if chart=='vmec' else 0.;shift=.1 if chart=='boozer' else 0. + def cartesian(y): + u,w=y[0],y[1] + if chart=='vmec':u,w=u*jnp.cos(y[-1])-w*jnp.sin(y[-1]),w*jnp.cos(y[-1])+u*jnp.sin(y[-1]) + phi=y[2]-shift*w;R=scale*(3+u) + return jnp.concatenate((jnp.array([R*jnp.cos(phi)-3.3*scale,R*jnp.sin(phi),scale*w]),y[3:5])) + def regular(y): + R=jnp.hypot(y[0]+3.3*scale,y[1]);u=R/scale-3;w=y[2]/scale + zeta=jnp.arctan2(y[1],y[0]+3.3*scale)+shift*w + point=jnp.array([u*jnp.cos(gauge)+w*jnp.sin(gauge),w*jnp.cos(gauge)-u*jnp.sin(gauge),zeta]) + return jnp.concatenate((point,y[3:5],jnp.array([gauge]) if chart=='vmec' else jnp.empty(0))) + return cartesian,regular + + +def birth_state(field,sigma,model): + """Same birth speed/pitch; Lorentz gyromotion is centred at the GC birth.""" + speed=sigma*np.sqrt(10.);point=jnp.zeros(3);B=field.AbsB(point) + if model=='gc':return jnp.array([0.,0.,0.,.6*speed,M*(.8*speed)**2/(2*B)]) + unit=field.B_contravariant(point)/B + perpendicular=jnp.cross(jnp.array([0.,1.,0.]),unit) + perpendicular=perpendicular/jnp.linalg.norm(perpendicular) + velocity=speed*(.6*unit+.8*perpendicular) + point=-jnp.cross(velocity,unit)/(Q*B/M) + return jnp.concatenate((point,velocity)) + + +def solver(fieldname,chart,options,*,spatial=True,model='gc'): + p=ProtonBackground(coulomb_log_model='impact');sigma,nu=p.sigma,p.nu + omega=2e6 if fieldname=='helix' else 2048. + field=(MagneticMirror(omega*nu*M/Q,.03*sigma/nu) if fieldname=='mirror' else + HelicalField(omega*nu*M/Q,20000*nu/sigma) if fieldname=='helix' else + UniformMagneticField(omega*nu*M/Q)) + bath=BackgroundSpecies(1,jnp.array([1.]),jnp.array([1.]),jnp.array([p.density]), + jnp.array([p.temperature_ev]),coulomb_log_model='impact') + electric=Electric_field_zero();gc=model=='gc' + to_cartesian,to_regular=chart_maps(chart,sigma/nu) + y0=birth_state(field,sigma,model) + def physical_rhs(t,y,args): + if gc: + dx,dv=_guiding_center_velocity(field,electric,Q,M,y[:3],y[3],mu=y[4]) + return jnp.concatenate((dx,jnp.array([dv,0.]))) + return jnp.concatenate((y[3:],Q/M*jnp.cross(y[3:],field.B_contravariant(y[:3])))) + cap=getattr(options,'cap',.0025) + bound=native_step_limit(field,bath,M,Q,y0,physical_rhs,lambda y:y,lambda y:y[:3],field.AbsB, + gc=gc,electric_field=electric,tmax=options.horizon/nu,dtmax=cap/nu,tolerance=options.tolerance) + initial=to_regular(y0) + def rhs(t,y,args): + if chart=='cartesian':return physical_rhs(t,y,args) + physical=to_cartesian(y);flow=physical_rhs(t,physical,args) + result=jax.jvp(to_regular,(physical,),(flow,))[1] + if chart=='vmec': + # Re-express the inverse with this state's gauge, not the birth gauge. + angle=y[-1]-.2;c,s=jnp.cos(angle),jnp.sin(angle) + du,dw=result[0]*c+result[1]*s,result[1]*c-result[0]*s + radius=y[0]**2+y[1]**2 + rotation=(y[0]*dw-y[1]*du)/(radius+.01) + result=result.at[0].set(du+y[1]*rotation).at[1].set(dw-y[0]*rotation).at[-1].set(rotation) + return result + def kick(t,y,h,dw,args): + physical=to_cartesian(y);point=physical[:3];B=field.AbsB(point) + speed=jnp.sqrt(physical[3]**2+2*physical[4]*B/M) if gc else jnp.linalg.norm(physical[3:]) + coefficients=collision_coefficients(bath,M,Q,speed,point,full_orbit=not gc) + if not gc: + step=particle_collision_step(physical[3:],h,dw,coefficients,tolerance=.001) + return step._replace(y=y.at[3:].set(step.y)) + pitch=physical[3]/speed + step=guiding_center_collision_step(speed,pitch,h,dw[-2:],coefficients, + tolerance=.001,speed_floor=.05*np.sqrt(2)*sigma) + if spatial: + dx=guiding_center_spatial_increment(pitch,dw[:3],coefficients,field.B_contravariant(point)/B,Q*B/M) + y=y.at[:3].add(dx) if chart=='cartesian' else move_in_cartesian(y,dx,lambda q:to_cartesian(q)[:3]) + B=field.AbsB(to_cartesian(y)[:3]) + v,xi=step.y + return step._replace(y=y.at[3].set(v*xi).at[4].set(M*v*v*(1-xi*xi)/(2*B))) + times=np.linspace(0.,options.horizon,getattr(options,'save_points',6));si_times=times/nu;si_times[-1]=options.horizon/nu + def one(key): + out=solve_split(rhs,kick,initial,t1=options.horizon/nu,dt0=cap/nu,dtmax=cap/nu, + ts=jnp.asarray(si_times),key=key,noise_dim=5 if gc and spatial else 2 if gc else 3, + method='dopri8',rtol=1e-10,atol=1e-10,orbit_stage_execution='unrolled', + error_norm=OrbitErrorNorm(1e-10,1e-10,float(sigma*np.sqrt(10)),velocity_components=1 if gc else 3, + position_map=lambda y:to_cartesian(y)[:3]), + step_limit=lambda t,y,a:bound(t,to_cartesian(y),a),align_orbit=True, + collision_wiener_norm=(lambda w:jnp.linalg.norm(w[-2:])) if gc else lambda w:jnp.abs(w[2]), + max_steps=10000,max_orbit_steps=4096) + return out._replace(ys=jax.vmap(to_cartesian)(out.ys),y=to_cartesian(out.y)) + return jax.jit(jax.vmap(one)),p,field,times + + +def summarize(states,physical,field,model): + xyz=states[...,:3] + if model=='gc': + B=np.asarray(jax.vmap(jax.vmap(field.AbsB))(jnp.asarray(xyz))) + speed=np.sqrt(states[...,3]**2+2*states[...,4]*B/M);parallel=states[...,3] + else: + speed=np.linalg.norm(states[...,3:],axis=-1) + unit=np.asarray(jax.vmap(jax.vmap(lambda x:field.B_contravariant(x)/field.AbsB(x)))(jnp.asarray(xyz))) + parallel=np.sum(states[...,3:]*unit,axis=-1) + return np.stack((xyz[...,2],speed,parallel/speed,parallel),axis=-1) + + +def apply_lorentz_reference(report,reference): + """Correct spatial/pitch references; keep independent radial speed theory.""" + from scipy.stats import t as student_t + critical=student_t.ppf(.975,min(report['particles'],reference['particles'])-1) + if 'times' in report and (len(report['times'])!=len(reference['times']) or not np.allclose(report['times'],reference['times'],rtol=0,atol=1e-14)): + raise ValueError('Lorentz reference and production save times do not match') + for row in report['rows']: + if row.get('model','gc')!='lorentz':continue + target=reference['fields'][row['field']]['levels'][-1]['evolution'] + if len(target)!=len(row['evolution']):raise ValueError('Lorentz reference save times do not match the particle report') + for measured,expected in zip(row['evolution'],target): + for name,value in measured.items(): + if name.startswith('speed_'):continue + other=expected[name];value.update(reference=other['value'],reference_se=other['se'], + reference_half95=other['half95'],difference=value['value']-other['value']) + se=np.hypot(value['se'],other['se']) + value.update(difference_half95=float(critical*se),z=float(value['difference']/se) if se>1e-14 else None) + row['reference_scope']='Independent full-Lorentz numerical ensemble with refinement controls; speed uses independent radial theory.' + report['lorentz_reference']=reference + + +def run(options): + from .benchmark_combined_validation import references,add_speed_reference,physical_moments + output=options.output;output.mkdir(parents=True,exist_ok=True) + reference_path=options.reference or output/'reference.json' + times=np.linspace(0.,options.horizon,options.save_points) + if reference_path.exists():reference=json.loads(reference_path.read_text()) + else: + reference=references(SimpleNamespace(fields=options.fields,output=output,times=times)) + add_speed_reference(SimpleNamespace(output=output),reference) + if len(reference['times'])!=len(times) or not np.allclose(reference['times'],times,rtol=0,atol=1e-14): + raise ValueError('Reference save times differ; use a fresh output folder or matching reference') + report=dict(moment_tolerance=options.tolerance,collision_tolerance=.001,orbit_tolerance=1e-10,seed=options.seed,cap=options.cap, + particles=options.particles,times=times.tolist(),backend=jax.default_backend(),device=jax.devices()[0].device_kind, + scope='Same prescribed Cartesian physics transformed into regular flux charts; these are not VMEC equilibria or Boozer K=0 spectra.',rows=[]) + numerical=None + if 'lorentz' in options.models: + from .lorentz_collision_reference import generate + path=options.lorentz_reference or output/'lorentz_reference.json' + numerical=json.loads(path.read_text()) if path.exists() else generate(options.fields,options.particles,output=path,save_points=options.save_points) + for name in options.fields: + expected_mean,expected_cov,error=physical_moments(reference,name) + configurations=[(model,chart) for model in options.models for chart in (options.charts if model=='gc' else ['cartesian'])] + for model,chart in configurations: + function,p,field,times=solver(name,chart,options,spatial=options.spatial_diffusion,model=model) + seed=options.seed if options.seed is not None else 8706 if name=='mirror' else 9706 + keys=jax.random.split(jax.random.PRNGKey(seed),options.particles) + print('Compiling',name,model,chart,'N=',options.particles,flush=True) + start=perf_counter();executable=function.lower(keys).compile();compile_s=perf_counter()-start + start=perf_counter();out=jax.device_get(jax.block_until_ready(executable(keys)));elapsed=perf_counter()-start + if np.any(out.status):raise RuntimeError((name,chart,np.unique(out.status,return_counts=True))) + values=summarize(out.ys,p,field,model);n=len(values) + units=np.array([p.sigma/p.nu,p.sigma,1.,p.sigma]);mu=expected_mean*units;cov=expected_cov*units[None,:,None]*units[None,None,:] + if model=='lorentz': + from .benchmark_split_multirate import velocity_reference + _,_,radial,_,_=velocity_reference(model,times,'impact',need_pitch=False) + mu[:,1]=np.asarray(radial['moments']['speed_mean'])*p.sigma + cov[:,1,1]=np.asarray(radial['moments']['speed_variance'])*p.sigma**2 + checks=[] + for i in range(len(times)): + row={} + for k,variable in enumerate(('position','speed','pitch','parallel')): + row[variable+'_mean']=estimate(values[:,i,k],mu[i,k]) + row[variable+'_variance']=estimate(values[:,i,k],cov[i,k,k],variance=True) + row['position_parallel_covariance']=estimate(n/(n-1)*(values[:,i,0]-values[:,i,0].mean())*(values[:,i,3]-values[:,i,3].mean()),cov[i,0,3]) + checks.append(row) + counts=out.stats + record=dict(field=name,model=model,chart=chart,spatial_diffusion=options.spatial_diffusion and model=='gc',compile_s=compile_s,execution_s=elapsed, + reference_scope='Independent axial GC reference' if model=='gc' else 'Independent speed theory; GC-limit comparison only for position/pitch/parallel moments', + collision_updates=int(counts.collision_updates.sum()),accepted_orbit_steps=int(counts.accepted_orbit_steps.sum()), + max_orbit_steps_per_collision=int(counts.max_orbit_steps_per_collision.max()),evolution=checks) + report['rows'].append(record) + if numerical is not None:apply_lorentz_reference(report,numerical) + suffix='' if model=='gc' else '_lorentz' + np.savez_compressed(output/f'{name}_{chart}{suffix}.npz',moments=values,states=out.ys) + (output/'comparison.json').write_text(json.dumps(report,indent=2)+'\n') + print(name,chart,'completed',elapsed,'s; orbit/collision',record['accepted_orbit_steps']/record['collision_updates'],flush=True) + plot(report,output,times,charts=options.charts) + + +@presentation +def plot(report,output,times,charts=None): + import matplotlib.pyplot as plt + p=ProtonBackground(coulomb_log_model='impact') + panels=(('position',r'z\nu_0/\sigma_T',p.sigma/p.nu),('speed',r'v/\sigma_T',p.sigma), + ('pitch',r'\xi',1.),('parallel',r'v_\parallel/\sigma_T',p.sigma)) + for field,model in dict.fromkeys((row['field'],row.get('model','gc')) for row in report['rows']): + rows=[r for r in report['rows'] if r['field']==field and r.get('model','gc')==model and (charts is None or r['chart'] in charts)] + if not rows:continue + fig,axes=plt.subplots(2,4,figsize=(19,7),layout='constrained') + for j,(variable,symbol,scale) in enumerate(panels): + for i,stat in enumerate(('mean','variance')): + ax=axes[i,j];name=variable+'_'+stat + for k,row in enumerate(rows): + data=row['evolution'] + series(ax,times,[e[name]['value'] for e in data],[e[name]['half95'] for e in data], + std=i==1,scale=scale,label=model.upper()+' / '+row['chart'],color=f'C{k}') + data=rows[0]['evolution'] + series(ax,times,[e[name]['reference'] for e in data],[e[name].get('reference_half95',0.) for e in data], + std=i==1,scale=scale,reference=True,label='Independent speed theory' if variable=='speed' else 'Independent GC reference' if model=='gc' else 'Full-Lorentz reference') + ax.set(title=r'$\langle '+symbol+r'\rangle$' if i==0 else r'$\sigma('+symbol+r')$', + xlabel=r'$t\nu_0$') + axes[0,0].legend() + fig.suptitle(f"{model.upper()} · {field.capitalize()} · N={report['particles']:,} · budget {report['moment_tolerance']:g}") + suffix='' if model=='gc' else '_lorentz' + save(fig,output/f'{field}{suffix}_moments.png') + + +def diffusion(options): + """Known transient velocity and perpendicular-diffusion references.""" + from .benchmark_split_multirate import velocity_reference,observables + from .lorentz_spatial_reference import guiding_center_msd + output=options.output;output.mkdir(parents=True,exist_ok=True) + times=np.linspace(0.,options.horizon,options.save_points);rows=[];omega=2048. + for model in options.models: + coarse,fine,reference,_,_=velocity_reference(model,times,'impact',need_pitch=False) + target=reference['moments'] + expected=np.asarray(target['spatial_integral']) if model=='gc' else guiding_center_msd(fine,times,omega) + for chart in options.charts if model=='gc' else ['cartesian']: + function,p,field,_=solver('uniform',chart,options,model=model) + seed=7706 if options.seed is None else options.seed + keys=jax.random.split(jax.random.PRNGKey(seed),options.particles) + print('Compiling diffusion',model,chart,flush=True) + out=jax.device_get(jax.block_until_ready(function(keys))) + if np.any(out.status):raise RuntimeError((model,chart,np.unique(out.status,return_counts=True))) + scale=np.array([p.sigma/p.nu]*3+([p.sigma,M*p.sigma**2/field.magnitude] if model=='gc' else [p.sigma]*3)) + speed,pitch,_,msd=observables(out.ys/scale,omega,model) + values=(msd,speed,pitch,speed,pitch,speed*pitch,speed*pitch) + names=('spatial','speed_mean','pitch_mean','speed_variance','pitch_variance','parallel_variance','parallel_mean') + evolution=[] + for i in range(len(times)): + evolution.append({name:estimate(value[:,i],expected[i] if name=='spatial' else target[name][i], + variance='variance' in name) for name,value in zip(names,values)}) + label=model+' / '+chart + row=dict(model=model,chart=chart,evolution=evolution,collision_updates=int(out.stats.collision_updates.sum()), + accepted_orbit_steps=int(out.stats.accepted_orbit_steps.sum()), + max_orbit_steps_per_collision=int(out.stats.max_orbit_steps_per_collision.max())) + rows.append(row) + print('Completed diffusion',label,'orbit/collision',row['accepted_orbit_steps']/row['collision_updates'],flush=True) + report=dict(particles=options.particles,moment_tolerance=options.tolerance,times=times.tolist(),seed=seed,cap=options.cap, + omega=omega,scope='Uniform physical field; manufactured flux charts; normalized speed and rho_sigma displacement.',rows=rows) + (output/'comparison.json').write_text(json.dumps(report,indent=2)+'\n') + plot_diffusion(report,output,charts=options.charts) + + +@presentation +def plot_diffusion(report,output,charts=None): + import matplotlib.pyplot as plt + times=np.asarray(report.get('times',np.linspace(0.,.1,6))) + for model in dict.fromkeys(r['model'] for r in report['rows']): + rows=[r for r in report['rows'] if r['model']==model and (charts is None or r['chart'] in charts)] + if not rows:continue + panels=[('speed',r'v/\sigma_T'),('pitch',r'\xi')] + if 'parallel_mean' in rows[0]['evolution'][0]:panels.append(('parallel',r'v_\parallel/\sigma_T')) + fig,axes=plt.subplots(2,len(panels),figsize=(5*len(panels),7),layout='constrained') + for j,(variable,symbol) in enumerate(panels): + for i,stat in enumerate(('mean','variance')): + ax=axes[i,j];name=variable+'_'+stat + for k,row in enumerate(rows): + series(ax,times,[e[name]['value'] for e in row['evolution']],[e[name]['half95'] for e in row['evolution']], + std=i==1,label=model.upper()+' / '+row['chart'],color=f'C{k}') + series(ax,times,[e[name]['reference'] for e in rows[0]['evolution']],std=i==1,reference=True,label='Independent theory') + ax.set(title=r'$\langle '+symbol+r'\rangle$' if i==0 else r'$\sigma('+symbol+r')$',xlabel=r'$t\nu_0$') + axes[0,0].legend() + fig.suptitle(f"{model.upper()} · Uniform field · N={report['particles']:,} · budget {report['moment_tolerance']:g}") + save(fig,output/f'diffusion_{model}_moments.png') + fig,ax=plt.subplots(figsize=(7,4.5),layout='constrained') + for k,row in enumerate(rows): + series(ax,times,[e['spatial']['value'] for e in row['evolution']],[e['spatial']['half95'] for e in row['evolution']], + label=model.upper()+' / '+row['chart'],color=f'C{k}') + series(ax,times,[e['spatial']['reference'] for e in rows[0]['evolution']],reference=True,label='Independent theory') + ax.set(xlabel=r'$t\nu_0$',ylabel=r'$\langle|\Delta G_\bot|^2\rangle/\rho_\sigma^2$',title=model.upper()+': spatial diffusion') + ax.legend();save(fig,output/f'diffusion_{model}_spatial.png') + + +def adapters(options): + """Actual QA field-table checks, distinct from manufactured-chart theory.""" + from netCDF4 import Dataset + from booz_xform_jax import Booz_xform + from essos.coils import Coils + from essos.fields import BiotSavart,Vmec + from essos.boozer import BoozerField + from essos.dynamics import Particles + from essos.split import trace_split + root=Path(__file__).resolve().parents[2]/'examples/input_files' + path=root/'wout_LandremanPaul2021_QA_reactorScale_lowres.nc' + transform=Booz_xform(verbose=0,mboz=options.mboz,nboz=options.nboz) + transform.read_wout(str(path),flux=False);transform.run() + with Dataset(path) as data:psi0=-float(data.variables['phi'][-1])/(2*np.pi) + boozer=BoozerField.from_booz_xform(transform,psi0,angle_grid=None) + geometry=BoozerGeometry.from_booz_xform(transform) + coil=BiotSavart(Coils.from_json(str(root/'ESSOS_biot_savart_LandremanPaulQA.json'))) + coil.coils.gamma,coil.coils.gamma_dash,coil.coils.currents + vmec=Vmec(str(path),ntheta=8,nphi=8) + bath=BackgroundSpecies(1,jnp.array([1.]),jnp.array([1.]),jnp.array([1e20]),jnp.array([1000.]),coulomb_log_model='impact') + options.output.mkdir(parents=True,exist_ok=True) + rows=[] + for name,field,embedding,model in (('coils_gc',coil,None,'GuidingCenter'), + ('coils_lorentz',coil,None,'FullOrbit'),('vmec_gc',vmec,None,'GuidingCenter'),('boozer_gc',boozer,geometry,'GuidingCenter')): + if name not in options.adapter_fields:continue + points=(jnp.column_stack((jnp.linspace(1.23,1.27,options.particles),jnp.zeros((options.particles,2)))) + if field is coil else jnp.column_stack((jnp.full(options.particles,.3),jnp.linspace(.2,.5,options.particles),jnp.full(options.particles,.1)))) + birth=Particles(points,mass=M,charge=Q,energy=5000*Q, + initial_vparallel_over_v=jnp.linspace(.4,.6,options.particles),field=field if model=='FullOrbit' else None, + phase_angle_full_orbit=jnp.pi) + birth.random_keys=jax.random.split(jax.random.PRNGKey(42),options.particles) + for clock in options.clocks: + outputs={} + for execution in ('shared','independent') if jax.default_backend()=='gpu' else ('shared',): + def run():return trace_split(field,birth,bath,model=model,tmax=4e-10,timestep=1e-10, + collision_dtmax=2e-10,orbit_dt0=1e-10,n_save=3,adaptive=clock=='adaptive',orbit_adaptive=clock=='adaptive', + collision_controller='moments',moment_tolerance=options.tolerance,spatial_diffusion=model=='GuidingCenter', + spatial_geometry=embedding,max_steps=32,max_orbit_steps=64,execution=execution) + print('Preparing actual QA adapter',name,clock,execution,flush=True) + start=perf_counter();exe=jax.jit(run).lower().compile();compile_s=perf_counter()-start + first=jax.device_get(jax.block_until_ready(exe()));second=jax.device_get(jax.block_until_ready(exe())) + print('Results',name,clock,execution,'failed',int(np.count_nonzero(first.status)), + 'repeatable',np.array_equal(first.ys,second.ys),flush=True) + if np.any(first.status) or not np.array_equal(first.ys,second.ys):raise RuntimeError((name,clock,execution,'failure or nonrepeatable')) + outputs[execution]=first + rows.append(dict(field=name,clock=clock,execution=execution,compile_s=compile_s,failed=0, + collision_updates=int(first.stats.collision_updates.sum()),accepted_orbit_steps=int(first.stats.accepted_orbit_steps.sum()))) + (options.output/'comparison.json').write_text(json.dumps(dict(particles=options.particles,moment_tolerance=options.tolerance, + mboz=options.mboz,nboz=options.nboz,scope='Real QA field tables; repeatability and shared/GPU path agreement, not an independent statistical physics reference.',rows=rows),indent=2)+'\n') + if 'independent' in outputs: + np.testing.assert_allclose(outputs['independent'].ys,outputs['shared'].ys,rtol=2e-9,atol=3e-12) + print('PASS actual QA adapter',name,clock,flush=True) + + +def main(): + parser=argparse.ArgumentParser(description=__doc__) + parser.add_argument('--particles',type=int,default=2000) + parser.add_argument('--seed',type=int) + parser.add_argument('--cap',type=float,default=.0025) + parser.add_argument('--tolerance',type=float,default=.01) + parser.add_argument('--horizon',type=float) + parser.add_argument('--save-points',type=int,default=201,help='actual saved times; no interpolation of particle samples') + parser.add_argument('--study',choices=('coupled','diffusion','adapters'),default='coupled') + parser.add_argument('--models',nargs='+',choices=('gc','lorentz'),help='Coupled defaults to GC; select Lorentz explicitly for full-gyromotion runs') + parser.add_argument('--fields',nargs='+',choices=('mirror','helix'),default=['mirror','helix']) + parser.add_argument('--charts',nargs='+',choices=('cartesian','vmec','boozer'),default=['cartesian','vmec','boozer']) + parser.add_argument('--spatial-diffusion',action=argparse.BooleanOptionalAction,default=True) + parser.add_argument('--reference',type=Path) + parser.add_argument('--lorentz-reference',type=Path,help='Independent full-Lorentz ensemble reference; generated for coupled Lorentz runs if absent') + parser.add_argument('--plot-only',action='store_true',help='Regenerate figures from an ignored generated report without tracing') + parser.add_argument('--mboz',type=int,default=4);parser.add_argument('--nboz',type=int,default=4) + parser.add_argument('--clocks',nargs='+',choices=('fixed','adaptive'),default=['fixed','adaptive']) + parser.add_argument('--adapter-fields',nargs='+',choices=('coils_gc','coils_lorentz','vmec_gc','boozer_gc'), + default=['coils_gc','coils_lorentz','vmec_gc','boozer_gc']) + parser.add_argument('--output',type=Path,required=True) + options=parser.parse_args() + if options.models is None:options.models=['gc'] if options.study=='coupled' else ['gc','lorentz'] + if options.horizon is None:options.horizon=.025 if options.study=='coupled' else .1 + if options.particles<2 or options.save_points<2 or options.tolerance<=0 or options.cap<=0 or (options.study=='coupled' and options.horizon!=.025): + parser.error('use >=2 particles, positive budget and the coupled reference horizon .025') + if options.plot_only: + report=json.loads((options.output/'comparison.json').read_text()) + if options.lorentz_reference is not None: + apply_lorentz_reference(report,json.loads(options.lorentz_reference.read_text())) + (options.output/'comparison.json').write_text(json.dumps(report,indent=2)+'\n') + elif any(row.get('model')=='lorentz' for row in report['rows']) and options.study=='coupled' and 'lorentz_reference' not in report: + parser.error('old Lorentz reports require --lorentz-reference; GC curves are not Lorentz references') + if options.study=='diffusion':plot_diffusion(report,options.output,charts=options.charts) + elif options.study=='coupled':plot(report,options.output,np.asarray(report.get('times',np.linspace(0.,options.horizon,6))),charts=options.charts) + else:parser.error('adapter checks have no figure') + else:{'coupled':run,'diffusion':diffusion,'adapters':adapters}[options.study](options) + + +if __name__=='__main__':main() diff --git a/examples/benchmarks/benchmark_split_helix.py b/examples/benchmarks/benchmark_split_helix.py new file mode 100644 index 00000000..8486c53f --- /dev/null +++ b/examples/benchmarks/benchmark_split_helix.py @@ -0,0 +1,31 @@ +"""Prescribed helical field and exact collisionless full-B-star GC flow.""" +import jax.numpy as jnp +from essos.constants import PROTON_MASS as M,ELEMENTARY_CHARGE as Q + + +class HelicalField: + """B/B0=(sqrt(1-c*c)cos(kz), sqrt(1-c*c)sin(kz), c).""" + def __init__(self, magnitude, wave, c=.5): + self.magnitude, self.wave, self.c = magnitude, wave, c + + def gc_quantities(self, point): + phase = self.wave*point[2]; a = jnp.sqrt(1-self.c**2) + x, y = a*jnp.cos(phase), a*jnp.sin(phase) + B = self.magnitude*jnp.array([x, y, self.c]) + return B, B, self.magnitude, jnp.zeros(3), -self.wave*jnp.array([x, y, 0.]), self.wave*self.c*jnp.array([-y, x, 0.]), 1. + + def B_contravariant(self, point): return self.gc_quantities(point)[0] + B_covariant = B_contravariant + def AbsB(self, point): return self.magnitude + def dAbsB_by_dX(self, point): return jnp.zeros(3) + def curl_b(self, point): return self.gc_quantities(point)[4] + def kappa(self, point): return self.gc_quantities(point)[5] + def sqrtg(self, point): return 1. + +def exact_orbit(y, h, field): + """Exact full B-star GC flow, including the v_parallel=0 limit.""" + omega = Q*field.magnitude/M; k, c = field.wave, field.c + z = y[2]+h*y[3]*c/(1-(1-c*c)*k*y[3]/omega) + amplitude = jnp.sqrt(1-c*c)/c*(1-k*y[3]/omega)/k + return y.at[0].add(amplitude*(jnp.sin(k*z)-jnp.sin(k*y[2]))).at[1].add( + amplitude*(jnp.cos(k*y[2])-jnp.cos(k*z))).at[2].set(z) diff --git a/examples/benchmarks/benchmark_split_mirror.py b/examples/benchmarks/benchmark_split_mirror.py new file mode 100644 index 00000000..d9675b51 --- /dev/null +++ b/examples/benchmarks/benchmark_split_mirror.py @@ -0,0 +1,49 @@ +"""Prescribed mirror/profile fields and an exact collisionless axial GC orbit.""" +import jax.numpy as jnp +from essos.constants import PROTON_MASS as M + + +class MagneticMirror: + """B/B0=(-a*x*z,-a*y*z,1+a*z*z), a=strength/L**2; div B=0.""" + def __init__(self,magnitude,length,strength=1.): + self.magnitude,self.length,self.strength=magnitude,length,strength + def B_contravariant(self,point): + x,y,z=point;a=self.strength/self.length**2 + return self.magnitude*jnp.array([-a*x*z,-a*y*z,1+a*z*z]) + B_covariant=B_contravariant + def AbsB(self,point):return jnp.linalg.norm(self.B_contravariant(point)) + def sqrtg(self,point):return 1. + def gc_quantities(self,point): + x,y,z=point;a=self.strength/self.length**2 + B=self.B_contravariant(point);value=jnp.linalg.norm(B);b=B/value + jac=self.magnitude*jnp.array([[-a*z,0.,-a*x],[0.,-a*z,-a*y],[0.,0.,2*a*z]]) + gradient=jac.T@b + db=(jac-b[:,None]*gradient[None,:])/value + curl=jnp.array([db[2,1]-db[1,2],db[0,2]-db[2,0],db[1,0]-db[0,1]]) + return B,B,value,gradient,curl,db@b,1. + def dAbsB_by_dX(self,point):return self.gc_quantities(point)[3] + def curl_b(self,point):return self.gc_quantities(point)[4] + def kappa(self,point):return self.gc_quantities(point)[5] + +def exact_mirror_orbit(y,h,field): + """Exact collisionless on-axis GC flow, including the mu=0 limit.""" + w=jnp.sqrt(2*y[4]*field.magnitude/(M*field.length**2));phase=w*h + return y.at[2].set(y[2]*jnp.cos(phase)+y[3]*h*jnp.sinc(phase/jnp.pi)).at[3].set( + y[3]*jnp.cos(phase)-y[2]*w*jnp.sin(phase)) + + +class TransitField: + """Uniform B along x so native radial profiles vary along the orbit.""" + def __init__(self,magnitude):self.magnitude=magnitude + def AbsB(self,x):return self.magnitude + def gc_quantities(self,x): + b=jnp.array([self.magnitude,0.,0.]);z=jnp.zeros(3) + return b,b,self.magnitude,z,z,z,1. + +def background(physical,*,varying=False): + from essos.background_species import BackgroundSpecies + return BackgroundSpecies(1,jnp.array([1.]),jnp.array([1.]), + jnp.array([[.2e20,1.8e20]]) if varying else jnp.array([1e20]), + jnp.array([[500.,1500.]]) if varying else jnp.array([1000.]), + radial_grid=jnp.array([-.1,.1])*physical.sigma/physical.nu if varying else None, + coulomb_log_model='impact') diff --git a/examples/benchmarks/benchmark_split_multirate.py b/examples/benchmarks/benchmark_split_multirate.py new file mode 100644 index 00000000..1d51b37a --- /dev/null +++ b/examples/benchmarks/benchmark_split_multirate.py @@ -0,0 +1,303 @@ +"""Joint velocity and spatial statistics with separate orbit/collision clocks. + +Uses production trace_split, Lorentz motion, SI Coulomb coefficients and +retained Brownian memory, for Lorentz and GC motion. Velocity moments and +distributions come from the same trajectories as spatial moments. Independent +Fokker-Planck references describe the transient beam, including GC's reflecting +speed floor. Lorentz spatial theory retains finite gyrofrequency; GC uses its +own spatial diffusion operator. JAX selects the machine backend. No source. +""" +import argparse +import csv +import hashlib +import json +from pathlib import Path +from time import perf_counter +import jax +import jax.numpy as jnp +import numpy as np +from essos.split import trace_split +from essos.background_species import BackgroundSpecies +from essos.constants import PROTON_MASS, ELEMENTARY_CHARGE, ONE_EV +from essos.dynamics import Particles +from scipy.stats import kstest, norm +from .validate_beam_relaxation import estimate, statistics +from .nonrelativistic_collision_reference import ProtonBackground +from .thermal_relaxation_reference import RelaxationReference, PhysicalRelaxationReference, impact_coefficients +from .lorentz_spatial_reference import guiding_center_msd + +PARAMETERS = dict(particles=512, batch_size=64, seed=7706, horizon=.1, saves=5, + omegas=[128., 512., 2048.], caps=[.0025, .00125], tolerance=.001, + orbit_tolerance=1e-10, phase_step=.1, coulomb_log_model='impact', models=['lorentz','gc']) + + +class UniformMagneticField: + def __init__(self, magnitude): self.magnitude = magnitude + def B_contravariant(self, point): return jnp.array([0., 0., self.magnitude]) + B_covariant = B_contravariant + def AbsB(self, point): return self.magnitude + def dAbsB_by_dX(self, point): return jnp.zeros(3) + curl_b = kappa = dAbsB_by_dX + def sqrtg(self, point): return 1. + + +def solver(adaptive, times, options, model='lorentz'): + physical = ProtonBackground(coulomb_log_model=options.coulomb_log_model) + sigma, frequency = physical.sigma, physical.nu + background = BackgroundSpecies(1, jnp.array([1.]), jnp.array([1.]), + jnp.array([physical.density]), jnp.array([physical.temperature_ev]), + coulomb_log_model=options.coulomb_log_model) + gc = model == 'gc' + def batch(initial, keys, cap, omega): + field = UniformMagneticField(omega*frequency*PROTON_MASS/ELEMENTARY_CHARGE) + scale = (jnp.array([sigma/frequency]*3+[sigma,PROTON_MASS*sigma**2/field.magnitude]) + if gc else jnp.array([sigma/frequency]*3+[sigma]*3)) + birth = Particles(initial[:, :3]*scale[:3], mass=PROTON_MASS, charge=ELEMENTARY_CHARGE, + energy=5*physical.temperature_ev*ONE_EV, initial_vparallel_over_v=jnp.full(len(initial), .6), + initial_xyz_fullorbit=initial[:, :3]*scale[:3], initial_vxvyvz=initial[:, 3:]*sigma) + birth.random_keys = keys + out = trace_split(field, birth, background, model='GuidingCenter' if gc else 'FullOrbit', + tmax=options.horizon/frequency, timestep=cap/frequency, + collision_dtmax=cap/frequency, orbit_dt0=jnp.minimum(cap, options.phase_step/omega)/frequency, + times=jnp.asarray(times)/frequency, adaptive=adaptive, orbit_adaptive=adaptive, + collision_controller=getattr(options,'collision_controller','conservative'), collision_tolerance=options.tolerance, + moment_tolerance=getattr(options,'moment_tolerance',.005), + spatial_diffusion=gc, speed_floor=.05*np.sqrt(2.)*sigma if gc else None, + orbit_stage_execution='unrolled', rtol=options.orbit_tolerance, atol=options.orbit_tolerance, + max_steps=10000, max_orbit_steps=2048) + return out._replace(ys=out.ys/scale, y=out.y/scale, t=out.t*frequency, ts=jnp.asarray(times)) + return jax.jit(batch) + + +def observables(states, omega, model): + """Read physical observables from the production solver's normalized output.""" + if model == 'gc': + speed = np.sqrt(states[...,3]**2+2*states[...,4]) + pitch = states[...,3]/speed + displacement = omega*(states[...,:2]-states[:,:1,:2]) + else: + speed = np.linalg.norm(states[...,3:],axis=-1) + pitch = states[...,5]/speed + cross = np.stack((states[...,4],-states[...,3]),axis=-1) + guiding = omega*states[...,:2]+cross + displacement = guiding-guiding[:,:1] + return speed,pitch,displacement,np.sum(displacement**2,axis=-1) + + +def velocity_reference(model,times,coefficient_model,*,need_pitch=True): + lower = .05*np.sqrt(2.) if model=='gc' else 0. + cls = RelaxationReference if coefficient_model=='impact' else PhysicalRelaxationReference + kwargs = dict(lower=lower,**(dict(law=impact_coefficients) if coefficient_model=='impact' else {})) + coarse,fine,upper = cls(nodes=384,**kwargs),cls(nodes=768,**kwargs),cls(nodes=960,upper=10.,**kwargs) + a,b,c = [ref.moments(times) for ref in (coarse,fine,upper)] + changes = {name:dict(mesh=float(np.max(abs(a[name]-b[name]))/max(1.,np.max(abs(b[name])))), + upper=float(np.max(abs(c[name]-b[name]))/max(1.,np.max(abs(b[name]))))) for name in b} + if max(value[key] for value in changes.values() for key in ('mesh','upper'))>3e-4: + raise RuntimeError(f'velocity reference refinement failed: {changes}') + pitch_cdf,harmonic_change=None,None + if need_pitch: + pitch_grid = np.linspace(-1.,1.,801) + pitch_low = fine.pitch_cdf(times[-1],harmonics=32) + pitch_cdf = fine.pitch_cdf(times[-1],harmonics=64) + harmonic_change = float(np.max(abs(pitch_low(pitch_grid)-pitch_cdf(pitch_grid)))) + if harmonic_change>1e-7: + pitch_low,pitch_cdf = pitch_cdf,fine.pitch_cdf(times[-1],harmonics=96) + harmonic_change = float(np.max(abs(pitch_low(pitch_grid)-pitch_cdf(pitch_grid)))) + if harmonic_change>1e-7: raise RuntimeError(f'pitch reference needs more harmonics: {harmonic_change}') + speed_cdf = fine.speed_cdf(times[-1]) + # Only l=0,1,2 spectra are needed for spatial/moment references afterward. + fine._spectra = {ell:value for ell,value in fine._spectra.items() if ell<=2} + speed_edges,pitch_edges = np.linspace(0.,6.,61),np.linspace(-1.,1.,61) + record = dict(speed_floor=lower,moments={name:value.tolist() for name,value in b.items()}, + refinement=changes,pitch_harmonic_change=harmonic_change, + distribution=dict(speed_edges=speed_edges.tolist(), + speed_density=(np.diff(speed_cdf(speed_edges))/np.diff(speed_edges)).tolist())) + if need_pitch:record['distribution'].update(pitch_edges=pitch_edges.tolist(), + pitch_density=(np.diff(pitch_cdf(pitch_edges))/np.diff(pitch_edges)).tolist()) + return coarse,fine,record,speed_cdf,pitch_cdf + + +def plot_spatial(report, folder, model): + import matplotlib.pyplot as plt + meta = report['metadata']; omegas = meta['omegas']; times = np.asarray(meta['times']) + fig, axes = plt.subplots(2, len(omegas), figsize=(5*len(omegas), 7), constrained_layout=True, squeeze=False) + for column, omega in enumerate(omegas): + ax, work = axes[:, column] + refs = report['gc_references'] if model=='gc' else report['references'] + ax.plot(times, refs[str(omega)]['msd'], 'k', lw=2, + label='GC diffusion theory' if model=='gc' else 'Finite-Omega theory') + selected = [r for r in report['rows'] if r['omega'] == omega and r.get('model','lorentz')==model] + for index, row in enumerate(selected): + color = 'C0' if row['method'] == 'fixed' else 'C1' + fine = row['cap'] == min(meta['caps']) + values = np.array([e['value'] for e in row['evolution']]) + half = np.array([e['half95'] for e in row['evolution']]) + label = f"{row['method']}, collision cap {row['cap']:g}" + ax.plot(times, values, color=color, ls='-' if fine else ':', label=label) + if fine: ax.fill_between(times, values-half, values+half, color=color, alpha=.12) + work.bar(index, row['accepted_orbit_per_collision'], color=color, alpha=.8) + ax.set(title=rf'$\Omega/\nu_0={omega:g}$', xlabel=r'$t\nu_0$', ylabel=r'$E[|\Delta G_\perp|^2]/\rho_\sigma^2$') + work.axhline(1., color='k', ls='--', lw=1) + work.set(xticks=range(len(selected)), xticklabels=[f"{r['method']}\n{r['cap']:g}" for r in selected], + ylabel='Accepted orbit steps / collision steps') + ax.grid(alpha=.2); work.grid(axis='y', alpha=.2) + axes[0, 0].legend(fontsize=7) + fig.suptitle(f"Production split {model.upper()}/Coulomb statistics; N={meta['particles']}; {meta['backend']}\n" + "Initially 5T beam, pitch 0.6; no source; shading = marginal 95% sampling intervals") + stem = 'multirate_gc' if model=='gc' else 'multirate' + fig.savefig(folder/(stem+'.png'), dpi=160) + fig.savefig(folder/(stem+'.svg')) + plt.close(fig) + + +def plot_velocity(report,folder,model): + import matplotlib.pyplot as plt + meta=report['metadata'];times=np.asarray(meta['times']);reference=report['velocity_references'][model] + selected=[r for r in report['rows'] if r['model']==model and r['cap']==min(meta['caps'])] + names=('speed_mean','speed_variance','pitch_mean','pitch_variance','parallel_mean','parallel_variance') + fig,axes=plt.subplots(3,2,figsize=(12,10),constrained_layout=True) + hist,hist_axes=plt.subplots(1,2,figsize=(12,4.5),constrained_layout=True) + for name,ax in zip(names,axes.flat): + ax.plot(times,reference['moments'][name],'k',lw=2,label='Independent transient theory') + for row in selected: + values=np.array([sample[name]['value'] for sample in row['velocity']]) + half=np.array([sample[name]['half95'] for sample in row['velocity']]) + color='C'+str(meta['omegas'].index(row['omega'])) + label=rf"{row['method']}, $\Omega/\nu_0={row['omega']:g}$" + ax.plot(times,values,color=color,ls='--' if row['method']=='fixed' else '-',label=label) + ax.fill_between(times,values-half,values+half,color=color,alpha=.07) + ax.set(title=name.replace('_',' '),xlabel=r'$t\nu_0$',ylabel='Normalized velocity / pitch units');ax.grid(alpha=.2) + for name,ax in zip(('speed','pitch'),hist_axes): + edges=np.asarray(reference['distribution'][name+'_edges']) + ax.stairs(reference['distribution'][name+'_density'],edges,color='k',lw=2,label='Independent transient theory') + for row in selected: + color='C'+str(meta['omegas'].index(row['omega'])) + ax.stairs(np.asarray(row['histograms'][name])/(meta['particles']*np.diff(edges)),edges, + color=color,ls='--' if row['method']=='fixed' else '-',label=f"{row['method']}, Omega={row['omega']:g}") + ax.set(title='Final '+name+' distribution',xlabel='v/sigma' if name=='speed' else 'pitch',ylabel='Probability density');ax.grid(alpha=.2) + caption=f"{model.upper()}: same multirate trajectories; N={meta['particles']}; finest cap {min(meta['caps']):g}" + fig.suptitle(caption+'\nTransient beam reference; shading = marginal 95% sampling intervals') + hist.suptitle(caption+f"; final t*nu0={times[-1]:g}") + axes[0,0].legend(fontsize=7);hist_axes[0].legend(fontsize=7) + for suffix,figure in (('velocity',fig),('distributions',hist)): + for extension in ('png','svg'):figure.savefig(folder/f'multirate_{model}_{suffix}.{extension}',dpi=160) + plt.close(figure) + + +def plot(report,folder): + for model in report['metadata'].get('models',['lorentz']): + plot_spatial(report,folder,model) + if 'velocity_references' in report:plot_velocity(report,folder,model) + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + for name in ('particles', 'batch_size', 'seed', 'saves'): + parser.add_argument('--'+name.replace('_', '-'), type=int, default=PARAMETERS[name]) + for name in ('horizon', 'tolerance', 'orbit_tolerance', 'phase_step'): + parser.add_argument('--'+name.replace('_', '-'), type=float, default=PARAMETERS[name]) + parser.add_argument('--omegas', type=float, nargs='+', default=PARAMETERS['omegas']) + parser.add_argument('--caps', type=float, nargs='+', default=PARAMETERS['caps']) + parser.add_argument('--coulomb-log-model', choices=('nrl', 'impact'), default=PARAMETERS['coulomb_log_model']) + parser.add_argument('--models',choices=('lorentz','gc'),nargs='+',default=PARAMETERS['models']) + parser.add_argument('--collision-controller',choices=('conservative','moments'),default='conservative') + parser.add_argument('--moment-tolerance',type=float,default=.005) + parser.add_argument('--output', type=Path, default=Path('output/split_multirate')) + parser.add_argument('--plot-only', action='store_true') + options = parser.parse_args(); folder = options.output; folder.mkdir(parents=True, exist_ok=True) + if options.plot_only: + plot(json.loads((folder/'comparison.json').read_text()), folder); return + if (folder/'comparison.json').exists():parser.error('choose a fresh output directory') + if options.particles < 2 or options.batch_size < 1 or options.particles % options.batch_size or options.saves<2: + parser.error('particles must be >=2 and divisible by batch size') + if not all(np.isfinite(x) and x>0 for x in options.omegas+options.caps+[options.horizon, options.tolerance, options.phase_step,options.orbit_tolerance]): + parser.error('frequencies, intervals and tolerances must be positive') + times = np.linspace(0., options.horizon, options.saves) + meta = vars(options).copy(); meta['output'] = str(folder) + meta.update(backend=jax.default_backend(), device=jax.devices()[0].device_kind, jax=jax.__version__, + times=times.tolist(), orbit_control='fixed/fixed or adaptive/adaptive; independent intervals', + framework='production trace_split with actual SI fields, births, Coulomb coefficients and Brownian stack', + uncertainty='Independent particles; marginal 95% intervals; shared keys across settings do not imply shared paths') + meta.update(velocity_scope='Transient speed/pitch/parallel moments and final CDFs from the same saved paths; not an equilibrium test', + gc_orbit_scope='Uniform-field GC has no gyromotion; adaptive orbit control may need one step per collision. Fixed controls subcycle explicitly.') + report = dict(complete=False, metadata=meta, references={}, gc_references={},velocity_references={},rows=[]) + root=Path(__file__).resolve().parents[2] + report['source_sha256']={name:hashlib.sha256((root/name).read_bytes()).hexdigest() for name in ( + 'essos/split.py','essos/background_species.py','essos/rk.py', + 'examples/benchmarks/benchmark_split_multirate.py','examples/benchmarks/thermal_relaxation_reference.py', + 'examples/benchmarks/lorentz_spatial_reference.py','examples/benchmarks/nonrelativistic_collision_reference.py')} + save = lambda: (folder/'comparison.json').write_text(json.dumps(report, indent=2)+'\n') + references={} + for model in options.models: + start=perf_counter() + coarse,fine,record,speed_cdf,pitch_cdf=velocity_reference(model,times,options.coulomb_log_model) + report['velocity_references'][model]=record;references[model]=(speed_cdf,pitch_cdf) + for omega in options.omegas: + a,b=(coarse.moments(times)['spatial_integral'],np.asarray(record['moments']['spatial_integral'])) if model=='gc' else ( + guiding_center_msd(coarse,times,omega),guiding_center_msd(fine,times,omega)) + change=float(np.max(abs(a-b))/max(b[-1],1e-30)) + if change>1e-3:raise RuntimeError(f'spatial reference refinement failed: {change}') + target=report['gc_references'] if model=='gc' else report['references'] + target[str(omega)]=dict(msd=b.tolist(),radial_refinement=change) + print(f'{model.upper()} references: {perf_counter()-start:.2f}s; pitch harmonic change {record["pitch_harmonic_change"]:.3g}',flush=True) + save() + keys = jax.random.split(jax.random.PRNGKey(options.seed), options.particles) + initial = np.array([0., 0., 0., np.sqrt(10.)*.8, 0., np.sqrt(10.)*.6]) + births = jnp.broadcast_to(jnp.asarray(initial), (options.batch_size, 6)) + cdf_alpha=.01/(2*len(options.models)*2*len(options.omegas)*len(options.caps)) + cdf_limit=float(np.sqrt(np.log(2/cdf_alpha)/(2*options.particles))) + critical=float(norm.ppf(1-.01/(2*len(options.models)*2*len(options.omegas)*len(options.caps)*(len(times)-1)*7))) + gc_controls={} + for model,adaptive in ((m,a) for m in options.models for a in (False,True)): + function = solver(adaptive, times, options,model) + for omega in options.omegas: + for cap in options.caps: + start = perf_counter(); outputs = [] + for offset in range(0, options.particles, options.batch_size): + outputs.append(jax.device_get(jax.block_until_ready(function(births, + keys[offset:offset+options.batch_size], jnp.asarray(cap), jnp.asarray(omega))))) + out = jax.tree.map(lambda *a: np.concatenate(a, axis=0), *outputs) + if np.any(out.status != 0): raise RuntimeError(f'solver failures: {np.unique(out.status, return_counts=True)}') + speed,pitch,delta,msd = observables(out.ys,omega,model) + expected = (report['gc_references'] if model=='gc' else report['references'])[str(omega)]['msd'] + velocity_expected=report['velocity_references'][model]['moments'] + inner = out.stats.orbit_steps-out.stats.orbit_rejected + row = dict(model=model,method='adaptive' if adaptive else 'fixed', omega=omega, cap=cap, + elapsed_s=perf_counter()-start, collision_accepted=int(out.stats.accepted.sum()), + collision_rejected=int(out.stats.rejected.sum()), orbit_accepted=int(inner.sum()), + orbit_rejected=int(out.stats.orbit_rejected.sum()), + accepted_orbit_per_collision=float(inner.sum()/out.stats.accepted.sum()), + max_accepted_collision_error=float(out.stats.max_accepted_error.max()), + evolution=[estimate(msd[:, i], target) for i, target in enumerate(expected)], + velocity=[statistics(speed[:,i],pitch[:,i],{name:values[i] for name,values in velocity_expected.items()}) for i in range(len(times))], + cdf={},histograms={}) + if adaptive and row['max_accepted_collision_error']>1:raise RuntimeError('accepted collision estimate exceeds one') + for name,values,cdf in (('speed',speed[:,-1],references[model][0]),('pitch',pitch[:,-1],references[model][1])): + result=kstest(values,cdf) + row['cdf'][name]=dict(distance=float(result.statistic),pvalue=float(result.pvalue),familywise_limit=cdf_limit, + passed=bool(result.statistic<=cdf_limit)) + edges=report['velocity_references'][model]['distribution'][name+'_edges'] + row['histograms'][name]=np.histogram(values,edges)[0].tolist() + worst=max(abs(value['z']) for sample in row['velocity'][1:] for value in sample.values() if value['z'] is not None) + row['velocity_screen']=dict(max_abs_z=worst,critical=critical,passed=bool(worst<=critical)) + if model=='gc': + row['spatial_components']=[dict(mean=[estimate(delta[:,i,j],0.) for j in range(2)], + variance=[estimate(delta[:,i,j],expected[i]/2,variance=True) for j in range(2)]) for i in range(len(times))] + control_key=(adaptive,cap) + if control_key in gc_controls: + a,b,c=gc_controls[control_key] + row['frequency_control']=dict(max_speed_difference=float(np.max(abs(speed-a))), + max_pitch_difference=float(np.max(abs(pitch-b))),max_scaled_msd_difference=float(np.max(abs(msd-c)))) + else:gc_controls[control_key]=(speed,pitch,msd) + report['rows'].append(row); save() + print(f"{model}/{row['method']} Omega={omega:g} cap={cap:g}: orbit/collision={row['accepted_orbit_per_collision']:.2f}, " + f"MSD z={row['evolution'][-1]['z']:.2f}, velocity max|z|={worst:.2f}, CDF pass={all(v['passed'] for v in row['cdf'].values())}, {row['elapsed_s']:.2f}s", flush=True) + report['complete'] = True; save(); plot(report, folder) + fields = ['model','method','omega','cap','collision_accepted','collision_rejected','orbit_accepted', + 'orbit_rejected','accepted_orbit_per_collision','max_accepted_collision_error','elapsed_s'] + with (folder/'comparison.csv').open('w', newline='') as stream: + writer=csv.DictWriter(stream, fieldnames=fields, extrasaction='ignore'); writer.writeheader(); writer.writerows(report['rows']) + + +if __name__ == '__main__': + main() diff --git a/examples/benchmarks/benchmark_split_orbits.py b/examples/benchmarks/benchmark_split_orbits.py new file mode 100644 index 00000000..ae6de7d2 --- /dev/null +++ b/examples/benchmarks/benchmark_split_orbits.py @@ -0,0 +1,221 @@ +"""Matched forward split timing and memory on bundled coil/VMEC/Boozer fields. + +Each case runs in a fresh process when --case all is selected. Fixed cases +use identical orbit/collision intervals; adaptive native cases adapt both. +Diffrax uses the existing fixed SDE tracer. Boozer's existing collisional +baseline is its fixed Dopri8/Euler implementation, labelled separately. +Field construction is excluded from blocked warm timings and included in +allocator peaks. No custom reverse rule or particle chunking is used. +""" +import argparse +import hashlib +import json +from pathlib import Path +import subprocess +import sys +from time import perf_counter +import diffrax +import jax +import jax.numpy as jnp +import numpy as np +from essos.background_species import BackgroundSpecies +from essos.constants import ALPHA_PARTICLE_MASS as M, ALPHA_PARTICLE_CHARGE as Q, ONE_EV, SPEED_OF_LIGHT +from essos.dynamics import Particles, _to_axis_regular, _from_axis_regular, _axis_regular, _SDE_MODELS, _EVENT_ROOT_FINDER +from essos.electric_field import Electric_field_zero +from essos.split import trace_split +from .benchmark_native_orbits import case, functions +from .benchmark_native_boozer_alpha import PARAMETERS, compiler_options, compiled_bytes + +MODULE = 'examples.benchmarks.benchmark_split_orbits' + + +def build(options): + data = case(options); field, initial, moment, speed, *_ = data + if options.field=='coils': + # Materialize cached geometry during field setup, before the outer JIT. + field.coils.gamma, field.coils.gamma_dash, field.coils.currents + if options.field == 'vmec': + physical = jax.vmap(_from_axis_regular)(initial); points = physical[:, :3]; pitches = physical[:, 3]/speed + elif options.field == 'boozer': + points = jnp.column_stack((initial[:,0]**2+initial[:,1]**2,jnp.arctan2(initial[:,1],initial[:,0]),initial[:,2])) + pitches = initial[:,3]/speed + else: + points = initial[:,:3]; pitches = jnp.linspace(.35,.65,options.particles) + birth = Particles(points,mass=M,charge=Q,energy=options.energy_ev*ONE_EV,initial_vparallel_over_v=pitches, + initial_xyz_fullorbit=initial[:,:3] if options.model=='lorentz' else None, + initial_vxvyvz=initial[:,3:] if options.model=='lorentz' else None) + birth.random_keys = jax.random.split(jax.random.PRNGKey(options.seed),options.particles) + background = BackgroundSpecies(1,jnp.array([1.]),jnp.array([1.]),jnp.array([1e20]),jnp.array([1000.])) + times = jnp.linspace(0.,options.horizon,options.saves) + adaptive = options.stepping == 'adaptive'; dt = options.horizon/4 if adaptive else options.horizon/options.steps + fingerprint = hashlib.sha256(np.asarray(jnp.column_stack((points,pitches))).tobytes()).hexdigest() + if options.case.startswith('native_') and options.case != 'native_collisionless': + def run(): + out = trace_split(field,birth,background,model='GuidingCenter' if options.model=='gc' else 'FullOrbit', + tmax=options.horizon,timestep=dt,collision_dtmax=options.horizon/2 if adaptive else dt, + orbit_dt0=dt,adaptive=adaptive,orbit_adaptive=adaptive,times=times, + rtol=options.rtol,atol=options.atol,collision_tolerance=options.collision_tolerance, + collision_controller=options.collision_controller,moment_tolerance=options.moment_tolerance, + spatial_diffusion=options.spatial_diffusion, + max_steps=options.max_steps,max_orbit_steps=options.max_orbit_steps, + execution='independent' if options.case=='native_independent' else 'shared') + return out.ys,out.y,out.t,out.status,jnp.stack(out.stats,axis=-1) + label = 'Native Dopri8 / Milstein; '+(options.collision_controller if adaptive else 'fixed') + elif options.case == 'native_collisionless': + native,_ = functions(options,data,'dopri8') + def run(): + ys,y,t,status,counts = native.__wrapped__(initial,moment) + counts = jnp.pad(counts,((0,0),(0,4))) + return ys,y,t,status,counts + label = 'Native Dopri8; no collisions' + elif options.field == 'boozer': + from essos.boozer import _start, _advance + def run(): + carry,first = _start(field,initial,moment) + carry,states = _advance(field,dt,options.steps//(options.saves-1),M,Q,background,0., + carry,birth.random_keys,0,options.saves-1,'dopri8',1e-9) + states = jnp.concatenate((first[:,None],states),axis=1) + status = jnp.where(carry[6]>=0,4,jnp.where(carry[4]>=0,1,0)) + counts = jnp.stack((carry[10],carry[10],jnp.zeros_like(carry[10])),axis=-1) + return states,states[:,-1],carry[2],status,jnp.pad(counts,((0,0),(0,4))) + label = 'Existing Boozer fixed Dopri8 / Euler collisions (not Diffrax)' + else: + gc, vmec = options.model=='gc', options.field=='vmec' + drift,noise,stepper,dimension = _SDE_MODELS['GuidingCenterCollisionsMuFixed' if gc else 'FullOrbitCollisions'] + scale = jnp.array([1.,1.,1.,SPEED_OF_LIGHT,SPEED_OF_LIGHT**2*M] if gc else [1.]*6) + if gc: + B = jax.vmap(field.AbsB)(points) + y0 = jnp.column_stack((points,birth.initial_vparallel,M*birth.initial_vperpendicular**2/(2*B)))/scale + if vmec: y0 = jax.vmap(_to_axis_regular)(y0) + else: y0 = initial/scale + args = (field,birth,Electric_field_zero(),background,1.) if gc else (field,birth,background) + rhs = lambda t,y,a:drift(t,y,args) + diffusion = lambda t,y,a:noise(t,y,args) + if vmec: rhs,diffusion = _axis_regular(rhs),_axis_regular(diffusion) + def one(y,key): + bm = diffrax.VirtualBrownianTree(0.,options.horizon,tol=dt*.5,shape=(dimension,),key=key, + levy_area=diffrax.SpaceTimeTimeLevyArea) + terms = diffrax.MultiTerm(diffrax.ODETerm(rhs),diffrax.ControlTerm(diffusion,bm)) + event = diffrax.Event(lambda t,y,args,**k:1-y[0]**2-y[1]**2,root_finder=_EVENT_ROOT_FINDER) if vmec else None + out = diffrax.diffeqsolve(terms,stepper(),t0=0.,t1=options.horizon,dt0=dt,y0=y, + stepsize_controller=diffrax.ConstantStepSize(),event=event, + saveat=diffrax.SaveAt(subs=[diffrax.SubSaveAt(ts=times),diffrax.SubSaveAt(t1=True)]), + max_steps=options.max_steps,throw=False) + saved,terminal = out.ys[0],out.ys[1][-1] + saved = jnp.where(jnp.isfinite(saved).all(axis=1)[:,None],saved,terminal) + if vmec: saved,terminal = jax.vmap(_from_axis_regular)(saved),_from_axis_regular(terminal) + status = jnp.where(out.result==diffrax.RESULTS.successful,0,jnp.where(out.result==diffrax.RESULTS.event_occurred,1,4)) + counts = jnp.array([out.stats[k] for k in ('num_steps','num_accepted_steps','num_rejected_steps')]+[0]*4) + return saved*scale,terminal*scale,out.ts[1][-1],status,counts + run = lambda:jax.vmap(one)(y0,birth.random_keys) + label = f'Existing Diffrax {stepper.__name__}, fixed SDE steps' + return run,label,fingerprint + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('--field',choices=('coils','vmec','boozer'),default='coils') + parser.add_argument('--model',choices=('gc','lorentz'),default='gc') + parser.add_argument('--stepping',choices=('fixed','adaptive'),default='fixed') + parser.add_argument('--case',choices=('all','native_shared','native_independent','reference_fixed','native_collisionless'),default='all') + parser.add_argument('--particles',type=int,default=64); parser.add_argument('--saves',type=int,default=8) + parser.add_argument('--horizon',type=float); parser.add_argument('--steps',type=int) + parser.add_argument('--repeats',type=int,default=3); parser.add_argument('--seed',type=int,default=42) + parser.add_argument('--energy-ev',type=float,default=4000.) + parser.add_argument('--rtol',type=float,default=1e-9); parser.add_argument('--atol',type=float,default=1e-9) + parser.add_argument('--collision-tolerance',type=float,default=.001) + parser.add_argument('--collision-controller',choices=('moments','conservative'),default='moments') + parser.add_argument('--moment-tolerance',type=float,default=.005) + parser.add_argument('--spatial-diffusion',action=argparse.BooleanOptionalAction,default=None, + help='GC position diffusion; enabled by default for native GC; legacy reference omits it') + parser.add_argument('--max-steps',type=int,default=4096); parser.add_argument('--max-orbit-steps',type=int,default=256) + parser.add_argument('--field-cache',type=Path); parser.add_argument('--output',type=Path,default=Path('output/split_forward')) + parser.add_argument('--resume',action='store_true') + parser.add_argument('--cold-compile',action='store_true',help='Disable the persistent cache for measured solver compilation') + options = parser.parse_args() + if min(options.particles,options.repeats,options.max_steps,options.max_orbit_steps)<1 or options.saves<2: + parser.error('require positive work limits and at least two saves') + if not all(np.isfinite(x) and x>0 for x in (options.energy_ev,options.atol,options.collision_tolerance,options.moment_tolerance)) or options.rtol<0: + parser.error('require finite positive energy, atol and collision tolerance; rtol>=0') + if options.field_cache is not None and not options.field_cache.is_file(): parser.error('missing --field-cache') + if options.model=='lorentz' and options.field!='coils': parser.error('Lorentz requires Cartesian coil fields') + if options.case=='reference_fixed' and options.stepping!='fixed': parser.error('the reference is fixed-step only') + if options.horizon is None: options.horizon=2e-6 if options.model=='lorentz' else 2e-5 + if options.steps is None: options.steps=1792 if options.model=='lorentz' else 224 + if options.steps<1 or not np.isfinite(options.horizon) or options.horizon<=0: parser.error('positive steps and horizon required') + if options.steps%(options.saves-1): parser.error('fixed steps must be divisible by saves-1 for aligned clocks') + options.output.mkdir(parents=True,exist_ok=True) + if options.case=='all': + rows={}; cases=['native_independent' if jax.default_backend()=='gpu' else 'native_shared','native_collisionless'] + if options.stepping=='fixed': cases.append('reference_fixed') + for name in cases: + saved=options.output/name/'comparison.json' + if saved.is_file() and options.resume: + previous=json.loads(saved.read_text()) + expected={k:getattr(options,k) for k in ('field','model','stepping','particles','saves','steps','seed','rtol','atol','collision_tolerance','collision_controller','moment_tolerance')} + expected['horizon_s']=options.horizon + expected['spatial_diffusion']=bool(options.model=='gc' and name in ('native_shared','native_independent') and options.spatial_diffusion is not False) + if not all(previous.get(k)==v for k,v in expected.items()) or previous.get('energy_ev',4000.)!=options.energy_ev: + parser.error('saved case settings differ; choose a fresh output directory') + rows[name]=previous + continue + command=[sys.executable,'-m',MODULE,*sys.argv[1:],'--case',name,'--output',str(options.output/name)] + subprocess.run(command,check=True) + rows[name]=json.loads((options.output/name/'comparison.json').read_text()) + (options.output/'comparison.json').write_text(json.dumps(dict(rows=rows),indent=2)+'\n') + return + # Reuse the orbit PR's field/birth preparation and collisionless baseline. + for name,value in PARAMETERS.items(): + if not hasattr(options,name): setattr(options,name,value) + options.execution='cuda' if jax.default_backend()=='gpu' else 'jax' + if options.case=='native_independent' and options.execution!='cuda': parser.error('independent execution requires GPU') + run,label,fingerprint=build(options) + if options.cold_compile: + from jax.experimental.compilation_cache import compilation_cache + jax.config.update('jax_enable_compilation_cache',False) + # Setup may already have initialized JAX's cached cache-use decision. + compilation_cache.reset_cache() + if options.cold_compile:print(f'{options.field}/{options.model}/{options.case}: lowering',flush=True) + start=perf_counter(); lowered=jax.jit(run,compiler_options=compiler_options()).lower() + lower_s=perf_counter()-start + if options.cold_compile:print(f'Lowering {lower_s:.3f} s; compiling',flush=True) + start=perf_counter();executable=lowered.compile();backend_compile_s=perf_counter()-start + compile_s=lower_s+backend_compile_s + if options.cold_compile:print(f'Compilation {backend_compile_s:.3f} s; first execution',flush=True) + start=perf_counter();out=jax.block_until_ready(executable());first_execution_s=perf_counter()-start + jax.block_until_ready(executable()) + samples=[] + for _ in range(options.repeats): + start=perf_counter(); out=jax.block_until_ready(executable()); samples.append(1000*(perf_counter()-start)) + states,terminal,end,status,counts=map(np.asarray,out) + memory=jax.devices()[0].memory_stats() or {} + report=dict(field=options.field,model=options.model,stepping=options.stepping,case=options.case, + reference=label,backend=jax.default_backend(),device=jax.devices()[0].device_kind,jax=jax.__version__, + particles=options.particles,energy_ev=options.energy_ev,horizon_s=options.horizon,saves=options.saves,steps=options.steps, + seed=options.seed,birth_sha256=fingerprint,rtol=options.rtol,atol=options.atol, + collision_tolerance=options.collision_tolerance,collision_controller=options.collision_controller, + moment_tolerance=options.moment_tolerance, + spatial_diffusion=bool(options.model=='gc' and options.case in ('native_shared','native_independent') and options.spatial_diffusion is not False), + lower_s=lower_s,backend_compile_s=backend_compile_s,compile_s=compile_s,lower_and_compile_s=compile_s, + first_execution_s=first_execution_s,startup_s=compile_s+first_execution_s, + persistent_compilation_cache=bool(jax.config.jax_enable_compilation_cache),samples_ms=samples, + warm_ms=float(np.median(samples)),compiled_buffers_bytes=compiled_bytes(executable), + peak_allocator_bytes=memory.get('peak_bytes_in_use'),live_allocator_bytes=memory.get('bytes_in_use'), + reserved_pool_bytes=memory.get('pool_bytes'),memory_scope='Fresh process; setup, compilation and warm executions; JAX allocator only', + lost=int(np.sum(status==1)),failed=int(np.sum(status>1)), + counts_total=counts[:,:5].sum(axis=0).tolist(), + count_columns=(['collision_trials','collision_accepted','collision_rejected','orbit_trials','orbit_rejected'] + if options.case in ('native_shared','native_independent') else ['solver_steps','solver_accepted','solver_rejected','unused','unused']), + peak_pending=int(counts[:,5].max()),max_accepted_collision_error=float(counts[:,6].max()), + terminal_sha256=hashlib.sha256(terminal.tobytes()).hexdigest()) + if options.case in ('native_shared','native_independent'): + report.update(collision_updates_total=int(counts[:,9].sum()),accepted_orbit_steps_total=int(counts[:,10].sum()), + max_orbit_steps_per_collision=int(counts[:,11].max())) + if report['failed']: raise RuntimeError(f"solver failed: {report['failed']} particles") + np.savez_compressed(options.output/'states.npz',states=states,terminal=terminal,status=status,counts=counts) + (options.output/'comparison.json').write_text(json.dumps(report,indent=2)+'\n') + print(f"{options.field}/{options.model}/{options.stepping}/{options.case}: {report['warm_ms']:.3f} ms; " + f"buffers {report['compiled_buffers_bytes']/2**20:.3f} MiB; peak {report['peak_allocator_bytes']}",flush=True) + + +if __name__=='__main__': main() diff --git a/examples/benchmarks/benchmark_split_path_convergence.py b/examples/benchmarks/benchmark_split_path_convergence.py new file mode 100644 index 00000000..cb42dbea --- /dev/null +++ b/examples/benchmarks/benchmark_split_path_convergence.py @@ -0,0 +1,225 @@ +"""Global refinement on the SAME native Brownian increments as each coarse solve. + +Record accepted production endpoints/increments without changing numerical +math. Refine each recorded interval with the production Brownian-memory +sampler, using an independent diagnostic namespace for conditional bridges. +Reference paths continue globally; they do NOT restart at coarse states. +""" +import inspect +import jax +import jax.numpy as jnp +import essos.split as split +from essos.rk import solve_rk,RKStatus + +MAX_ROOTS=4096 +def make_paired_solver(base,*,max_roots=MAX_ROOTS,refinements=(8,16,32)): + if len(refinements)!=3 or tuple(sorted(set(refinements)))!=tuple(refinements) or any(n<2 or n>64 or n&(n-1) for n in refinements): + raise ValueError('three increasing power-of-two refinements in 2..64 required') + finest=refinements[-1] + source=getattr(base,'_prototype_source',None) or inspect.getsource(base) + def replace(old,new): + nonlocal source + assert source.count(old)==1,(old,source.count(old));source=source.replace(old,new) + replace(" if record_steps:\n s['history']", " s.update(pair_t=jnp.zeros(MAX_ROOTS,y0.dtype),pair_dw=jnp.zeros((MAX_ROOTS,noise_dim),y0.dtype))\n if record_steps:\n s['history']") + replace(" state = save(state)",""" if combined: + state['pair_t']=lax.cond(accepted,lambda a:a.at[2*s['accepted']].set(middle).at[2*s['accepted']+1].set(end),lambda a:a,s['pair_t']) + state['pair_dw']=lax.cond(accepted,lambda a:a.at[2*s['accepted']].set(left).at[2*s['accepted']+1].set(dw-left),lambda a:a,s['pair_dw']) + else: + state['pair_t']=lax.cond(accepted,lambda a:a.at[s['accepted']].set(end),lambda a:a,s['pair_t']) + state['pair_dw']=lax.cond(accepted,lambda a:a.at[s['accepted']].set(dw),lambda a:a,s['pair_dw']) + state = save(state)""") + replace(' return solution\n'," return solution._replace(step_ts=(s['pair_t'],s['pair_dw']))\n") + namespace=dict(base.__globals__);namespace['MAX_ROOTS']=max_roots + exec(compile(source,'','exec'),namespace) + recorded=namespace['solve_split'] + + def solve(rhs,collision,y0,args=None,**kwargs): + coarse=recorded(rhs,collision,y0,args,**kwargs) + roots,dws=coarse.step_ts + count=coarse.stats.collision_updates + key=kwargs['key'];ts=kwargs['ts'];t0=jnp.asarray(kwargs.get('t0',0.),y0.dtype) + initial_ok=(coarse.status==0)&(count<=max_roots) + tag=jax.random.fold_in(key,0x50414952) + + def noise(i,start,end,dw): + memory=split.brownian_memory(jax.random.fold_in(tag,i),dw.size,capacity=64,dtype=y0.dtype,t0=start) + memory=memory._replace(ends=memory.ends.at[0].set(end),increments=memory.increments.at[0].set(dw),size=jnp.array(1),peak=jnp.array(1)) + valid=jnp.array(True) + for n in (2**i for i in range(1,finest.bit_length())): + grid=(start+(end-start)*jnp.arange(1,n+1,dtype=y0.dtype)/n).at[-1].set(end) + def draw(m,t): + m,w,full=split.brownian_sample(m,t) + return m,(w,full) + memory,(cum,full)=jax.lax.scan(draw,memory,grid) + valid &= ~jnp.any(full) + return jnp.diff(jnp.concatenate((jnp.zeros((1,dw.size),y0.dtype),cum)),axis=0),valid + + def flow(y,start,end): + out=solve_rk(rhs,y,args,t0=start,t1=end,dt0=end-start,ts=jnp.empty(0,y0.dtype), + method=kwargs['method'],adaptive=True,error_norm=kwargs['error_norm'], + rtol=kwargs['rtol'],atol=kwargs['atol'],stage_execution=kwargs['orbit_stage_execution'], + max_steps=64) + return out.y,out.status==RKStatus.SUCCESS + + answers=[];valids=[] + for n in refinements: + state=(jnp.array(0),t0,y0,jnp.broadcast_to(y0,(len(ts),len(y0))),jnp.array(1),initial_ok) + def advance(state): + i,start,y,saves,index,ok=state;end=roots[i] + fine,valid=noise(i,start,end,dws[i]) + increments=fine.reshape(n,finest//n,-1).sum(axis=1) + grid=(start+(end-start)*jnp.arange(1,n+1,dtype=y0.dtype)/n).at[-1].set(end) + def substep(carry,data): + t,y,ok=carry;target,w=data;h=target-t + y,a=flow(y,t,target) + kick=collision(target,y,h,w,args) + y=kick.y + good=a&jnp.isfinite(y).all()&(kick.drift_error<=1)&(kick.diffusion_error<=1) + return (target,y,ok&good),None + (_,y,good),_=jax.lax.scan(substep,(start,y,ok&valid),(grid,increments)) + def save(carry): + saves,index=carry + return saves.at[index].set(y),index+1 + saves,index=jax.lax.while_loop(lambda c:(c[1]64 or n&(n-1) for n in args.refinements):parser.error('three increasing power-of-two refinements in 2..64 required') + original=split.solve_split;folder=args.output;folder.mkdir(parents=True,exist_ok=True) + from types import SimpleNamespace + from .benchmark_combined_validation import references,add_speed_reference,physical_moments + if args.reference is not None: + data=json.loads(args.reference.read_text()) + else: + settings=SimpleNamespace(fields=[f for f in args.fields if f!='profiles'],output=folder) + data=references(settings);add_speed_reference(settings,data) + report=dict(particles=args.particles,control=args.control,refinements=args.refinements,max_steps=args.max_steps,max_roots=args.max_roots,scope='Global coarse/native-refined trajectory errors and paired weak moment differences on the SAME Brownian path within each case. Combined recording preserves BOTH accepted half-step increments. Each tolerance has its own production path; refinements are conditional native Brownian bridges, no new coarse noise. No timing claims from this instrumented diagnostic.',rows=[]) + for fieldname in args.fields: + p=ProtonBackground(coulomb_log_model='impact');sigma,nu=p.sigma,p.nu + field=(MagneticMirror(2048*nu*M/Q,.03*sigma/nu) if fieldname=='mirror' else + HelicalField(2e6*nu*M/Q,2e4*nu/sigma) if fieldname=='helix' else TransitField(2048*nu*M/Q)) + bath=background(p,varying=fieldname=='profiles') + if fieldname=='profiles': + expected=dict(position_variance=np.ones(6),pitch_variance=np.ones(6));speed_expected=dict(speed_variance=np.ones(6)) + else: + _,covariance,_=physical_moments(data,fieldname) + expected=dict(position_variance=covariance[:,0,0],pitch_variance=covariance[:,2,2]) + speed_expected=dict(speed_variance=covariance[:,1,1]) + keys=jax.random.split(jax.random.PRNGKey(8706 if fieldname=='mirror' else 9706),2000)[:args.particles] + for composition in ('lie',): + paired=make_paired_solver(original,max_roots=args.max_roots,refinements=tuple(args.refinements)) + def batch(keys,tolerance): + birth=Particles(jnp.zeros((len(keys),3)),mass=M,charge=Q,energy=5*p.temperature_ev*ONE_EV,initial_vparallel_over_v=jnp.full(len(keys),.6)) + birth.random_keys=keys + return split.trace_split(field,birth,bath,tmax=.025/nu,timestep=.0025/nu,collision_dtmax=.0025/nu, + times=jnp.linspace(0.,.025/nu,6),orbit_dt0=(.1/20000 if fieldname=='helix' else min(.0025,.1/2048))/nu, + orbit_stage_execution='unrolled',rtol=1e-10,atol=1e-10,collision_tolerance=.001,speed_floor=.05*np.sqrt(2.)*sigma, + spatial_diffusion=False, # Retain the axial coupled-reference model and its two noise components. + step_limit=make_step_limit(field,bath,p,tolerance) if args.control=='moments' else None, + combined_tolerance=tolerance if args.control=='combined' else None, + combined_length_scale=.03*sigma/nu,max_steps=args.max_steps,max_orbit_steps=4096) + fn=jax.jit(batch) + for tolerance in args.tolerances: + print('PAIRED START',fieldname,'budget',tolerance,'paths',args.particles,'refinements',args.refinements,flush=True) + start=perf_counter();previous=split.solve_split;split.solve_split=paired + try:out=jax.device_get(fn(keys,jnp.asarray(tolerance))) + finally:split.solve_split=previous + elapsed=perf_counter()-start + refs,valid,roots,dws=out.step_ts + assert np.all(valid) and np.all(out.status==0),(fieldname,composition,tolerance,valid,out.status) + def phase(states): + points=states[...,:3] + b=np.asarray(jax.jit(jax.vmap(field.AbsB))(jnp.asarray(points.reshape(-1,3)))).reshape(points.shape[:-1]) + speed=np.sqrt(states[...,3]**2+2*states[...,4]*b/M)/sigma + return states[...,:3]*nu/sigma,speed,states[...,3]/(speed*sigma) + xc,vc,pc=phase(out.ys);xr,vr,pr=phase(refs) + rms=[] + for j in range(3): + rms.append(dict(refinement=args.refinements[j],position=(np.sqrt(np.mean(np.sum((xc-xr[:,j])**2,axis=-1),axis=0))/.03).tolist(), + speed=(np.sqrt(np.mean((vc-vr[:,j])**2,axis=0))/np.sqrt(10)).tolist(),pitch=np.sqrt(np.mean((pc-pr[:,j])**2,axis=0)).tolist())) + weak=[] + for i in range(1,6): + moments={} + axis=0 if fieldname=='profiles' else 2 + for name,a,b,denominator in (('position_variance',xc[:,i,axis],xr[:,2,i,axis],expected['position_variance'][i]), + ('speed_variance',vc[:,i],vr[:,2,i],speed_expected['speed_variance'][i]), + ('pitch_variance',pc[:,i],pr[:,2,i],expected['pitch_variance'][i])): + if fieldname=='profiles':denominator=np.var(b,ddof=1) + influence=args.particles/(args.particles-1)*((a-a.mean())**2-(b-b.mean())**2) + value=estimate(influence,0.) + moments[name]=dict(percent=100*value['value']/denominator,half95=100*value['half95']/denominator) + weak.append(moments) + row=dict(field=fieldname,composition=composition,tolerance=tolerance,seconds_including_compile=elapsed, + refinements=args.refinements, + relative_moment_scale='fine-sample variance' if fieldname=='profiles' else 'independent reference variance', + mean_collision_updates=float(out.stats.collision_updates.mean()),rms=rms,paired_weak=weak,all_reference_solves_passed=True) + report['rows'].append(row) + np.savez_compressed(folder/f'{fieldname}_{composition}_{tolerance:g}.npz',coarse=out.ys,reference=refs,roots=roots,noise=dws,counts=out.stats.accepted) + (folder/'comparison.json').write_text(json.dumps(report,indent=2)+'\n') + print('GLOBAL PAIRED',fieldname,composition,tolerance,'kicks',row['mean_collision_updates'],'RMS final',rms[-1]['position'][-1],rms[-1]['speed'][-1],rms[-1]['pitch'][-1], + 'early weak',weak[0],'later weak',weak[3],'seconds',elapsed,flush=True) + print('Saved',folder,flush=True) + if not args.no_plots:plot(report,folder) + + +def plot(report,folder): + """Plot paired numerical errors, separate from population/theory gaps.""" + import numpy as np + import matplotlib.pyplot as plt + fields=list(dict.fromkeys(r['field'] for r in report['rows'])) + fig,axes=plt.subplots(len(fields),3,figsize=(14,4*len(fields)),squeeze=False,constrained_layout=True) + weak,panels=plt.subplots(len(fields),3,figsize=(14,4*len(fields)),squeeze=False,constrained_layout=True) + for fieldname,row_axes,row_panels in zip(fields,axes,panels): + for comp in ('lie',): + rows=sorted((r for r in report['rows'] if r['field']==fieldname and r['composition']==comp),key=lambda r:r['tolerance']) + if not rows:continue + for ax,name in zip(row_axes,('position','speed','pitch')): + ax.loglog([r['tolerance'] for r in rows],[r['rms'][-1][name][-1] for r in rows],'-o',label=comp+'; finest reference') + ax.loglog([r['tolerance'] for r in rows],[r['rms'][-2][name][-1] for r in rows],':',alpha=.6,label=comp+'; preceding reference') + ax.set(title=fieldname+': '+name,xlabel='Local tolerance',ylabel='Normalized global RMS error');ax.grid(alpha=.2,which='both') + for row in (r for r in report['rows'] if r['field']==fieldname): + for ax,name in zip(row_panels,('position_variance','speed_variance','pitch_variance')): + points=[r[name] for r in row['paired_weak']] + ax.errorbar(np.linspace(.005,.025,5),[p['percent'] for p in points],yerr=[p['half95'] for p in points],alpha=.8, + label=f"{row['composition']} {row['tolerance']:g}") + ax.set(title=fieldname+': '+name.replace('_',' '),xlabel=r'$t\nu_0$',ylabel='Paired numerical difference [%]');ax.grid(alpha=.2) + row_axes[0].legend(fontsize=7) + row_panels[0].legend(fontsize=7) + for ax in row_panels:ax.axhline(0,color='k',lw=1.5) + fig.suptitle(f"Brownian-coupled numerical convergence; N={report['particles']}; final time t nu0=.025") + weak.suptitle(f"Coarse minus refined native statistics on the SAME Brownian path; N={report['particles']}\nPaired 95% sampling intervals; zero is the reference") + fig.savefig(folder/'local_rms_path_convergence.png',dpi=160) + weak.savefig(folder/'local_rms_paired_moments.png',dpi=160) + plt.close(fig);plt.close(weak) + + +if __name__=='__main__':main() diff --git a/examples/benchmarks/collision_event_diagnostic.py b/examples/benchmarks/collision_event_diagnostic.py new file mode 100644 index 00000000..010e936f --- /dev/null +++ b/examples/benchmarks/collision_event_diagnostic.py @@ -0,0 +1,25 @@ +"""Opt-in resolution of a positive thermal-speed first-passage diagnostic. + +This limits monitoring intervals; it is not an exact Brownian crossing sampler. +The policy depends only on the current accepted state. Both an inward drift +budget and a diffusion-distance budget are used. A positive resolution floor +permits crossings, rather than approaching the boundary in infinitely many +steps. The split driver separately refines detected crossing intervals. +""" +import jax.numpy as jnp + + +def boundary_step_limit(speed, boundary, diffusion, drift, resolution, *, safety=.2): + """Return a time interval using consistently scaled speed, D and drift. + + ``diffusion`` is D in dv=A dt+sqrt(2D)dW. ``resolution`` is the smallest + boundary-policy interval and the detected-crossing ceiling, not a bound on + the unknown continuous hit time. Missed returns require convergence checks. + """ + distance = jnp.maximum(speed-boundary, 0.) + diffusive = safety*distance**2/jnp.where(diffusion > 0, 2*diffusion, 1.) + diffusive = jnp.where(diffusion > 0, diffusive, jnp.inf) + inward = jnp.maximum(-drift, 0.) + advective = safety*distance/jnp.where(inward > 0, inward, 1.) + advective = jnp.where(inward > 0, advective, jnp.inf) + return jnp.maximum(resolution, jnp.minimum(diffusive, advective)) diff --git a/examples/benchmarks/collision_plotting.py b/examples/benchmarks/collision_plotting.py new file mode 100644 index 00000000..88d43b05 --- /dev/null +++ b/examples/benchmarks/collision_plotting.py @@ -0,0 +1,60 @@ +"""Shared presentation style for collision benchmark figures.""" +from functools import wraps +from pathlib import Path +import matplotlib.pyplot as plt +import numpy as np + + +def presentation(function): + @wraps(function) + def wrapped(*args, **kwargs): + with plt.rc_context({ + 'font.size': 16, 'font.weight': 'bold', 'axes.labelweight': 'bold', + 'axes.titleweight': 'bold', 'axes.titlesize': 18, 'axes.labelsize': 17, + 'xtick.labelsize': 14, 'ytick.labelsize': 14, 'legend.fontsize': 11, + 'axes.linewidth': 1.2, 'lines.linewidth': 2.6, 'figure.facecolor': 'white', + 'savefig.facecolor': 'white', 'pdf.fonttype': 42, 'mathtext.fontset': 'dejavusans', + }): + return function(*args, **kwargs) + return wrapped + + +def series(ax, times, values, half=None, *, std=False, scale=1., reference=False, label=None, color='C0'): + values = np.asarray(values, float) + half = np.zeros_like(values) if half is None else np.asarray(half) + low, high = values-half, values+half + if std: + values, low, high = (np.sqrt(np.maximum(x, 0.)) for x in (values, low, high)) + values, low, high = (x/scale for x in (values, low, high)) + color = 'black' if reference else color + if np.any(half): + ax.fill_between(times, low, high, color=color, alpha=.12 if reference else .18, linewidth=0) + ax.plot(times, values, color=color, label=label, zorder=8 if reference else 4, + marker=None if reference or len(times)>16 else 'o', markersize=4) + ax.grid(False) + ax.tick_params(direction='in', length=5) + ax.ticklabel_format(axis='y', style='sci', scilimits=(-3, 4), useOffset=False) + ax.set_xlim(times[0], times[-1]) + + +def histogram(ax, edges, counts, density, *, particles, initial=None, label='Simulation', curve=None): + edges, counts = np.asarray(edges), np.asarray(counts) + centers, widths = (edges[1:]+edges[:-1])/2, np.diff(edges) + ax.bar(centers, counts, width=widths*.94, color='tab:orange', alpha=.75, + edgecolor='.25', linewidth=.7, label=label, zorder=2) + x, y = (centers, np.asarray(density)*particles*widths) if curve is None else (curve[0], curve[1]*particles*widths[0]) + ax.plot(x, y, color='black', lw=2.8, label='Independent theory', zorder=10) + if initial is not None: + ax.axvline(initial, color='blue', ls='--', lw=2.4, label='Initial value', zorder=9) + ax.set_ylabel('Counts') + ax.set_ylim(bottom=0) + ax.grid(False) + ax.tick_params(direction='in', length=5) + + +def save(figure, path): + path = Path(path) + path.parent.mkdir(parents=True, exist_ok=True) + figure.savefig(path.with_suffix('.png'), dpi=320, bbox_inches='tight') + figure.savefig(path.with_suffix('.pdf'), bbox_inches='tight') + plt.close(figure) diff --git a/examples/benchmarks/lorentz_collision_reference.py b/examples/benchmarks/lorentz_collision_reference.py new file mode 100644 index 00000000..1c3ad4e0 --- /dev/null +++ b/examples/benchmarks/lorentz_collision_reference.py @@ -0,0 +1,167 @@ +"""Independent full-Lorentz numerical ensemble reference, with refinement. + +Dimensionless Cartesian Lorentz motion uses a centred exact-angle rotation. Coulomb +coefficients are independently evaluated from the proton impact-parameter law; +Cartesian Euler--Maruyama samples the corresponding Ito generator. This is a +reference calculation, not an alteration of the production splitting scheme. +Black reference curves require their own sampling and refinement uncertainties. +An orthogonal frame transported by the magnetic rotation couples refinement +levels without replacing their physical diffusion tensor or Ito drift. +""" +import argparse +import json +from pathlib import Path +from time import perf_counter +import jax +import jax.numpy as jnp +import numpy as np +from jax.scipy.special import erf,gammainc +from essos.constants import ELEMENTARY_CHARGE as Q,PROTON_MASS as M,EPSILON_0,HBAR +from .nonrelativistic_collision_reference import ProtonBackground +from .validate_beam_relaxation import estimate + + +def magnetic(x,field): + x=jnp.asarray(x);z=x[...,2] + if field=='helix':return 2e6*jnp.stack((jnp.sqrt(.75)*jnp.cos(20000*z),jnp.sqrt(.75)*jnp.sin(20000*z),jnp.full_like(z,.5)),axis=-1) + if field=='mirror':return 2048*jnp.stack((-x[...,0]*z/.03**2,-x[...,1]*z/.03**2,1+z*z/.03**2),axis=-1) + if field!='uniform':raise ValueError('unknown reference magnetic field') + return jnp.broadcast_to(jnp.array([0.,0.,2048.]),x.shape) + + +def coefficients(r): + """Independent dimensionless parallel/perpendicular diffusion and Ito drift.""" + p=ProtonBackground(coulomb_log_model='impact');s=p.sigma + relative=s*s*(r*r+3);classical=Q*Q/(4*np.pi*EPSILON_0*(M/2));quantum=HBAR/M + debye=np.sqrt(EPSILON_0*p.temperature_ev/(p.density*Q)) + logarithm=jnp.log(debye)+jnp.log(relative)-.5*jnp.log(classical**2+quantum**2*relative) + slope=2*r/(r*r+3)-quantum**2*s*s*r/(classical**2+quantum**2*relative) + x=r/jnp.sqrt(2.);g=gammainc(1.5,x*x)/(2*x*x) + dg=(2/jnp.sqrt(jnp.pi)*jnp.exp(-x*x)-2*g/x)/jnp.sqrt(2.) + factor=Q**4*p.density/(4*np.pi*EPSILON_0**2*M**2*s**3*p.nu) + parallel=factor*logarithm*g/r + perpendicular=.5*factor*logarithm*(erf(x)-g)/r + derivative=factor*(slope*g/r+logarithm*(dg/r-g/r**2)) + drift=-r*parallel+derivative+2*(parallel-perpendicular)/r + return parallel,perpendicular,drift + + +def orbit(y,h,field,phase): + """Centred drift/rotation/drift; magnetic-only update preserves |v|.""" + # A conservative bound for the tested mirror trajectories; checked below. + frequency=2e6 if field=='helix' else 4*2048 + count=max(1,int(np.ceil(h*frequency/phase)));dt=h/count + def step(_,state): + x,v=state[...,:3],state[...,3:6];middle=x+.5*dt*v + B=magnetic(middle,field);strength=jnp.linalg.norm(B,axis=-1,keepdims=True);unit=B/strength + angle=dt*strength;sine=jnp.sin(angle);cosine_defect=2*jnp.sin(angle/2)**2 + cross=jnp.cross(v,unit);rotated=v+sine*cross+cosine_defect*jnp.cross(cross,unit) + result=jnp.concatenate((middle+.5*dt*rotated,rotated),axis=-1) + if state.shape[-1]>6: + frame=state[...,6:].reshape(state.shape[:-1]+(3,3)) + cross=jnp.cross(frame,unit[...,None,:]) + frame=frame+sine[...,None]*cross+cosine_defect[...,None]*jnp.cross(cross,unit[...,None,:]) + result=jnp.concatenate((result,frame.reshape(state.shape[:-1]+(9,))),axis=-1) + return result + return jax.lax.fori_loop(0,count,step,y) + + +def collision(y,h,dw): + v=y[...,3:6];r=jnp.linalg.norm(v,axis=-1);u=v/r[...,None] + if y.shape[-1]>6:dw=jnp.einsum('...i,...ij->...j',dw,y[...,6:].reshape(y.shape[:-1]+(3,3))) + parallel,perpendicular,drift=coefficients(r) + root=jnp.sqrt(2*perpendicular);difference=jnp.sqrt(2*parallel)-root + increment=h*drift[...,None]*u+root[...,None]*dw+difference[...,None]*u*jnp.sum(u*dw,axis=-1,keepdims=True) + return y.at[...,3:6].add(increment) + + +def birth(field): + b=np.array([np.sqrt(.75),0.,.5]) if field=='helix' else np.array([0.,0.,1.]) + e=np.cross([0.,1.,0.],b);e/=np.linalg.norm(e) + v=np.sqrt(10.)*(.6*b+.8*e);omega=2e6 if field=='helix' else 2048. + return jnp.asarray(np.r_[-np.cross(v,b)/omega,v]) + + +def solve(field,particles,seed,*,steps=400,phase=.1,save_points=6): + """Three coupled controls: base, finer orbit, finer orbit+collision time.""" + h=.025/((save_points-1)*steps);state=jnp.concatenate((birth(field),jnp.eye(3).ravel())) + initial=jnp.broadcast_to(state,(particles,15));key=jax.random.PRNGKey(seed) + # The same fine Cartesian Brownian increments drive all reference levels. + def run(): + def segment(states,segment_index): + def advance(i,states): + k=jax.random.fold_in(key,segment_index*steps+i) + left,right=jax.random.normal(k,(2,particles,3),dtype=jnp.float64)*jnp.sqrt(h/2) + a=collision(orbit(states[0],h,field,phase),h,left+right) + b=collision(orbit(states[1],h,field,phase/2),h,left+right) + c=collision(orbit(states[2],h/2,field,phase/2),h/2,left) + c=collision(orbit(c,h/2,field,phase/2),h/2,right) + return jnp.stack((a,b,c)) + states=jax.lax.fori_loop(0,steps,advance,states) + return states,states + start=jnp.broadcast_to(initial,(3,particles,15)) + _,saved=jax.lax.scan(segment,start,jnp.arange(save_points-1)) + return jnp.concatenate((start[None],saved),axis=0) + states=np.asarray(jax.jit(run)()) + if not np.isfinite(states).all():raise RuntimeError('nonfinite independent Lorentz reference') + frame=states[...,6:].reshape(states.shape[:-1]+(3,3)) + if np.max(abs(frame@np.swapaxes(frame,-1,-2)-np.eye(3)))>1e-8:raise RuntimeError('reference noise frame lost orthogonality') + if field=='mirror' and np.max(np.linalg.norm(np.asarray(magnetic(states[...,:3],field)),axis=-1))>4*2048: + raise RuntimeError('reference mirror gyrofrequency exceeded its subdivision bound') + return states[...,:6] + + +def moments(states,field): + p=ProtonBackground(coulomb_log_model='impact');v=states[...,3:];speed=np.linalg.norm(v,axis=-1) + b=np.array(magnetic(states[...,:3],field));b/=np.linalg.norm(b,axis=-1,keepdims=True) + parallel=np.sum(v*b,axis=-1) + return np.stack((states[...,2]*p.sigma/p.nu,speed*p.sigma,parallel/speed,parallel*p.sigma),axis=-1) + + +def statistics(values,other=None): + rows=[];n=values.shape[1] + for index,sample in enumerate(values): + row={} + for k,name in enumerate(('position','speed','pitch','parallel')): + x=sample[:,k] + row[name+'_mean']=estimate(x if other is None else x-other[index,:,k],0.) + row[name+'_variance']=(estimate(x,0.,variance=True) if other is None else + estimate(n/(n-1)*((x-x.mean())**2-(other[index,:,k]-other[index,:,k].mean())**2),0.)) + covariance=n/(n-1)*(sample[:,0]-sample[:,0].mean())*(sample[:,3]-sample[:,3].mean()) + if other is not None: + b=other[index];covariance-=n/(n-1)*(b[:,0]-b[:,0].mean())*(b[:,3]-b[:,3].mean()) + row['position_parallel_covariance']=estimate(covariance,0.) + rows.append(row) + return rows + + +def generate(fields,particles,*,steps=400,phase=.1,seed=20261028,output=None,save_points=6): + steps=max(1,int(np.ceil(steps*5/(save_points-1)))) + report=dict(particles=particles,times=np.linspace(0.,.025,save_points).tolist(),seed=seed,steps_per_save=steps,phase=phase, + scope='Independent full-Lorentz numerical Monte Carlo reference; Cartesian Ito EM in a transported orthogonal noise frame and centred exact-angle magnetic rotation, with orbit/collision refinements. Not an analytic solution.',fields={}) + for field in fields: + print('Independent Lorentz reference',field,'N=',particles,'steps/save=',steps,flush=True) + start=perf_counter();states=solve(field,particles,seed+(field=='helix'),steps=steps,phase=phase,save_points=save_points) + values=moments(states,field);levels=[] + for i in range(3):levels.append(dict(collision_interval=.005/steps/(2 if i==2 else 1), + phase=phase/(2 if i else 1),evolution=statistics(values[:,i]))) + report['fields'][field]=dict(elapsed_s=perf_counter()-start,levels=levels, + paired_changes=dict(orbit=statistics(values[:,0],values[:,1]),collision=statistics(values[:,1],values[:,2]))) + if output is not None:Path(output).write_text(json.dumps(report,indent=2)+'\n') + print('Completed reference',field,report['fields'][field]['elapsed_s'],'s',flush=True) + return report + + +def main(): + parser=argparse.ArgumentParser(description=__doc__) + parser.add_argument('--fields',nargs='+',choices=('mirror','helix'),default=['mirror','helix']) + parser.add_argument('--particles',type=int,default=2000);parser.add_argument('--steps',type=int,default=400) + parser.add_argument('--phase',type=float,default=.1);parser.add_argument('--seed',type=int,default=20261028) + parser.add_argument('--save-points',type=int,default=6) + parser.add_argument('--output',type=Path,required=True);args=parser.parse_args() + if args.particles<2 or args.steps<1 or args.phase<=0 or args.save_points<2:parser.error('positive resolution and at least two particles required') + args.output.parent.mkdir(parents=True,exist_ok=True) + generate(args.fields,args.particles,steps=args.steps,phase=args.phase,seed=args.seed,output=args.output,save_points=args.save_points) + + +if __name__=='__main__':main() diff --git a/examples/benchmarks/lorentz_spatial_reference.py b/examples/benchmarks/lorentz_spatial_reference.py new file mode 100644 index 00000000..6cdcad93 --- /dev/null +++ b/examples/benchmarks/lorentz_spatial_reference.py @@ -0,0 +1,53 @@ +"""Finite-gyrofrequency Coulomb spatial moments without particle tracing. + +For U=vx+i*vy, orbit rotation contributes -i*Omega U. The radial l=1 +semigroup predicts velocity correlations. Radial l=0,2 sectors average their +perpendicular amplitudes. A triangular backward system integrates these +correlations to obtain the exact mean squared guiding-centre displacement +G=x+v cross b/Omega. No strong-magnetization approximation is used. +""" +import numpy as np +from scipy.integrate import solve_ivp +from scipy.sparse import bmat, diags, eye + + +def guiding_center_msd(reference, times, omega): + t = np.asarray(times, float) + if t.ndim != 1 or len(t) < 1 or t[0] < 0 or t[-1] <= 0 or np.any(np.diff(t) < 0) or omega <= 0: + raise ValueError("ordered nonnegative times and positive gyrofrequency required") + r, mass = reference.grid, reference.mass + n = len(r) + _, _, nu = reference.law(r) + operators = [diags((reference.off, reference.diagonal-ell*(ell+1)*nu/2, reference.off), + (-1, 0, 1), format="csc", dtype=complex) for ell in (0, 1, 2)] + l0, l1, l2 = operators + unit = eye(n, format="csc", dtype=complex) + radius = diags(r, format="csc", dtype=complex) + zero = diags(np.zeros(n), format="csc", dtype=complex) + # m=e^(L1-iOmega)t r; n_l=convolution(L_l,r*m); q_l=int n_l; + # w=int m. All vectors are in the symmetric radial representation. + matrix = bmat([[l1-1j*omega*unit, None, None, None, None, None], + [radius, l0, None, None, None, None], [radius, None, l2, None, None, None], + [None, unit, None, zero, None, None], [None, None, unit, None, zero, None], + [unit, None, None, None, None, zero]], format="csc") + initial = np.r_[np.sqrt(mass)*r, np.zeros(5*n)].astype(complex) + result = solve_ivp(lambda s, u: matrix@u, (0., float(t[-1])), initial, + t_eval=t, method="BDF", jac=matrix, rtol=2e-10, atol=2e-12) + if not result.success: + raise RuntimeError(result.message) + evaluate = reference.evaluate/np.sqrt(mass) + m, n0, n2, q0, q2, w = [evaluate@v for v in np.split(result.y, 6)] + p2 = (3*reference.pitch**2-1)/2 + initial_amplitude = reference.start*(1-reference.pitch**2) + end_correlation = initial_amplitude*m + integrated_end_correlation = 2/3*(n0-p2*n2) + integrated_start_correlation = initial_amplitude*w.conj() + integrated_position2 = 2*np.real(2/3*(q0-p2*q2)) + perpendicular2 = 2/3*(reference.expectation(t, r*r)-p2*reference.expectation(t, r*r, 2)) + endpoint_change2 = perpendicular2+reference.start**2*(1-reference.pitch**2)-2*end_correlation.real + scaled_msd = omega**2*integrated_position2+endpoint_change2+2*omega*np.imag( + integrated_end_correlation-integrated_start_correlation) + scaled_msd[t == 0] = 0. + if np.min(scaled_msd) < -1e-8: + raise RuntimeError("negative finite-gyrofrequency spatial moment") + return np.maximum(scaled_msd, 0.) diff --git a/examples/benchmarks/mirror_collision_reference.py b/examples/benchmarks/mirror_collision_reference.py new file mode 100644 index 00000000..b7f3e5a1 --- /dev/null +++ b/examples/benchmarks/mirror_collision_reference.py @@ -0,0 +1,102 @@ +"""Independent radial/Legendre Coulomb generator and exact axial GC transport.""" +from dataclasses import dataclass +import numpy as np +from scipy.linalg import eigh_tridiagonal +from .thermal_relaxation_reference import RelaxationReference,impact_coefficients + + +def interpolation_weights(grid,points): + """Six-point local polynomial interpolation on a nonuniform grid.""" + start=np.clip(np.searchsorted(grid,points)-3,0,len(grid)-6) + indices=start[...,None]+np.arange(6) + nodes=grid[indices];weights=np.ones_like(nodes) + for i in range(6): + for j in range(6): + if i!=j:weights[...,i]*=(points-nodes[...,j])/(nodes[...,i]-nodes[...,j]) + return indices.astype(np.int32),weights + +@dataclass +class MirrorCollisionReference: + length: float=.03 + nz: int=81 + nr: int=48 + nxi: int=49 + zmax: float=.8 + upper: float=6. + lower: float=.05*np.sqrt(2.) + + def __post_init__(self): + if min(self.nz,self.nr,self.nxi)<8 or self.length<=0 or self.zmax<=0:raise ValueError('invalid reference grid') + self.radial=RelaxationReference(lower=self.lower,upper=self.upper,nodes=self.nr,law=impact_coefficients) + self.r=self.radial.grid + self.z=self.length*np.sinh(np.linspace(-np.arcsinh(self.zmax/self.length),np.arcsinh(self.zmax/self.length),self.nz)) + self.xi,weights=np.polynomial.legendre.leggauss(self.nxi) + ell=np.arange(self.nxi);self.angular_root=np.sqrt(weights) + self.angular=np.polynomial.legendre.legvander(self.xi,self.nxi-1)*self.angular_root[:,None]*np.sqrt((2*ell+1)/2) + self.killing=ell*(ell+1)/2 + + def collision_matrices(self,h): + _,_,nu=self.radial.law(self.r);root=np.sqrt(self.radial.mass) + half,whole=[],[] + for rate in self.killing: + values,vectors=eigh_tridiagonal(self.radial.diagonal-rate*nu,self.radial.off) + if rate==0:values[-1]=0. + half.append(((vectors*np.exp(.5*h*values))@vectors.T)*root[None,:]/root[:,None]) + whole.append(((vectors*np.exp(h*values))@vectors.T)*root[None,:]/root[:,None]) + return np.asarray(half),np.asarray(whole) + + def collide(self,f,matrices): + nz,nr,nxi,observables=f.shape + weighted=f*self.angular_root[None,None,:,None] + modes=(weighted.transpose(0,1,3,2).reshape(-1,nxi)@self.angular).reshape(nz,nr,observables,nxi) + for ell in range(nxi): + value=modes[:,:,:,ell].transpose(0,2,1).reshape(-1,nr)@matrices[ell].T + modes[:,:,:,ell]=value.reshape(nz,observables,nr).transpose(0,2,1) + result=(modes.reshape(-1,nxi)@self.angular.T).reshape(nz,nr,observables,nxi).transpose(0,1,3,2) + return result/self.angular_root[None,None,:,None] + + def characteristics(self,h): + z,r,xi=np.meshgrid(self.z,self.r,self.xi,indexing='ij') + w=r*np.sqrt(1-xi*xi)/np.sqrt(self.length**2+z*z) + sine=h*np.sinc(w*h/np.pi);cosine=np.cos(w*h) + new_z=z*cosine+r*xi*sine + new_xi=xi*cosine-z*w*w*sine/r + # No birth can reach the remote z walls within the reporting horizon; + # the grid edge treatment is checked independently by domain refinement. + iz,wz=interpolation_weights(self.z,np.clip(new_z,self.z[0],self.z[-1])) + ix,wx=interpolation_weights(self.xi,np.clip(new_xi,-1.,1.)) + return iz,wz,ix,wx + + def transport(self,f,mapping): + iz,wz,ix,wx=mapping;radial=np.arange(self.nr)[None,:,None] + out=np.zeros_like(f) + for a in range(6): + for b in range(6):out+=(wz[...,a]*wx[...,b])[...,None]*f[iz[...,a],radial,ix[...,b],:] + return out + + def evaluate(self,f,z=0.,r=np.sqrt(10.),xi=.6): + iz,wz=interpolation_weights(self.z,np.asarray(z));ir,wr=interpolation_weights(self.r,np.asarray(r));ix,wx=interpolation_weights(self.xi,np.asarray(xi)) + return np.einsum('i,j,k,ijko->o',wz,wr,wx,f[iz[:,None,None],ir[None,:,None],ix[None,None,:],:]) + + def moments(self,times,*,steps_per_save=8,collisions=True,transport=True): + times=np.asarray(times,float) + if times[0]!=0 or len(times)<2 or not np.allclose(np.diff(times),times[-1]/(len(times)-1)):raise ValueError('uniform times starting at zero required') + if self.zmax<=self.upper*times[-1]:raise ValueError('z domain can be reached from the birth; increase zmax') + z,r,xi=np.meshgrid(self.z,self.r,self.xi,indexing='ij') + f=np.stack((z,z*z,xi,xi*xi,z*xi),axis=-1) + h=times[-1]/((len(times)-1)*steps_per_save) + half,whole=self.collision_matrices(h) if collisions else (None,None) + mapping=self.characteristics(h) if transport else None + values=[np.array([0.,0.,.6,.36,0.])] + current=self.collide(f,half) if collisions else f + steps=(len(times)-1)*steps_per_save + for step in range(1,steps+1): + if transport:current=self.transport(current,mapping) + if step%steps_per_save==0: + value=self.collide(current,half) if collisions else current + values.append(self.evaluate(value)) + if step 3*self.sigma**2 + if self.coulomb_log_model == "impact": + # Independent algebraic log and analytic derivative. Screening is + # the explicitly specified proton bath, with no inferred electrons. + relative_squared = v*v+3*self.sigma**2 + classical_constant = Q*Q/(4*np.pi*EPSILON_0*(M/2)) + quantum_constant = HBAR/(2*(M/2)) + debye = np.sqrt(EPSILON_0*T*Q/(self.density*Q*Q)) + logarithm = (np.log(debye)+np.log(relative_squared) + -.5*np.log(classical_constant**2+quantum_constant**2*relative_squared)) + slope = 2*v/relative_squared-quantum_constant**2*v/(classical_constant**2+quantum_constant**2*relative_squared) + else: + logarithm = np.where(beam, beam_log, thermal_log) + slope = np.where(beam, 3/v, (2*Ta+T)/(v*(T+Ta))) + x = v/(np.sqrt(2)*self.sigma) + G = gammainc(1.5, x*x)/(2*x*x) + Gprime = 2/np.sqrt(np.pi)*np.exp(-x*x)-2*G/x + prefactor = Q**4*self.density/(4*np.pi*EPSILON_0**2*M**2) + dp = prefactor*logarithm*G/v + ddp = prefactor*(slope*G/v+logarithm*(Gprime/(np.sqrt(2)*self.sigma*v)-G/v**2)) + dt = .5*prefactor*logarithm*(erf(x)-G)/v + friction = -v*dp/self.sigma**2 + return dict(parallel=dp, perpendicular=dt, parallel_derivative=ddp, + friction=friction, speed_drift=friction+ddp+2*dp/v) + + @property + def nu(self): + return float(-self.coefficients(self.sigma)["friction"]/self.sigma) + + def diffusion(self, r): + return self.coefficients(self.sigma*np.asarray(r))["parallel"]/(self.sigma**2*self.nu) + + +def maxwell_weight(r): + r = np.asarray(r) + return r*r*np.exp(-r*r/2) + + +@dataclass +class FirstPassageReference: + boundary: float + start: float + upper: float + nodes: int + rates: np.ndarray + weights: np.ndarray + mean: float + variance: float + + def cdf(self, times): + times = np.asarray(times, dtype=float) + if np.any(~np.isfinite(times) | (times < 0)): + raise ValueError("first-passage times must be finite and nonnegative") + survival = np.exp(-times[..., None]*self.rates) @ self.weights + return np.clip(1-survival, 0., 1.) + + def restricted_moments(self, horizon): + """E[min(tau,H)**k], k=1..4; censored paths are never discarded.""" + if not np.isfinite(horizon) or horizon <= 0: + raise ValueError("horizon must be positive and finite") + return np.array([factorial(k)*np.sum(self.weights*gammainc(k, self.rates*horizon)/self.rates**k) + for k in range(1, 5)]) + + +def radial_generator(diffusion, density, *, boundary, start, upper=8., nodes=768): + """Absorbing/reflecting radial generator and evaluation at initial speed.""" + if not 0 <= boundary < start < upper or not isinstance(nodes, int) or nodes < 8: + raise ValueError("require 0 <= boundary < start < upper and >=8 nodes") + grid = np.linspace(boundary, upper, nodes+1) + dx = grid[1]-grid[0] + centers = (grid[1:]+grid[:-1])/2 + mass = np.asarray(density(grid[1:]))*dx + mass[-1] /= 2 + conductance = np.asarray(diffusion(centers))*density(centers)/dx + if np.any(~np.isfinite(mass) | (mass <= 0)) or np.any(~np.isfinite(conductance) | (conductance <= 0)): + raise ValueError("diffusion and density must be finite and positive on the reference grid") + lower = conductance/mass + higher = np.r_[conductance[1:], 0.]/mass + diagonal = -(lower+higher) + symmetric_off = conductance[1:]/np.sqrt(mass[:-1]*mass[1:]) + # Interpolate backward solutions at the prescribed initial speed. + evaluate = np.zeros(nodes) + i = int(np.searchsorted(grid, start)-1) + fraction = (start-grid[i])/dx + if i: + evaluate[i-1] = 1-fraction + evaluate[i] = fraction + return grid[1:], mass, lower, higher, diagonal, symmetric_off, evaluate + + +def first_passage_reference(diffusion, density, *, boundary, start, upper=8., nodes=768): + """Reversible finite-volume discretization of a scalar backward generator. + + Absorb at boundary; reflect at upper. The tridiagonal matrix is similar + to a symmetric matrix, giving survival probabilities without time-stepping. + Moment equations use an independent banded linear solve. + """ + _, mass, lower, higher, diagonal, symmetric_off, evaluate = radial_generator( + diffusion, density, boundary=boundary, start=start, upper=upper, nodes=nodes) + eigenvalues, vectors = eigh_tridiagonal(diagonal, symmetric_off) + if np.any(eigenvalues >= 0): + raise ValueError("absorbing reference generator must have negative eigenvalues") + spectral_weights = ((evaluate/np.sqrt(mass)) @ vectors)*(vectors.T @ np.sqrt(mass)) + band = np.zeros((3, nodes)) + band[0, 1:] = -higher[:-1] + band[1] = -diagonal + band[2, :-1] = -lower[1:] + m1 = solve_banded((1, 1), band, np.ones(nodes)) + m2 = solve_banded((1, 1), band, 2*m1) + mean = float(evaluate @ m1) + return FirstPassageReference(boundary, start, upper, nodes, -eigenvalues, + spectral_weights, mean, float(evaluate @ m2-mean**2)) + + +def proton_first_passage(background, *, initial_energy_over_T=5., threshold_energy_over_T=2., + upper=8., nodes=768): + lower = 1.5 if background.coulomb_log_model == "nrl" else 0. + if not lower < threshold_energy_over_T < initial_energy_over_T: + raise ValueError(f"physical reference requires {lower} < threshold/T < initial energy/T") + return first_passage_reference(background.diffusion, maxwell_weight, + boundary=np.sqrt(2*threshold_energy_over_T), start=np.sqrt(2*initial_energy_over_T), + upper=upper, nodes=nodes) + + +def quadrature_mean(background, boundary, start): + """Natural upper-boundary mean, independent of the finite-volume mesh. + + m1(v0)=integral_a^v0 [integral_z^infinity rho(u)du]/[D(z)rho(z)] dz. + The Maxwell tail integral is analytic. This is not a drag-only estimate. + """ + def integrand(r): + tail = r*np.exp(-r*r/2)+np.sqrt(np.pi/2)*erfc(r/np.sqrt(2)) + return tail/(background.diffusion(r)*maxwell_weight(r)) + return quad(integrand, boundary, start, epsabs=1e-10, epsrel=1e-10)[0] + + +def passage_statistics(times, hit, reference, horizon, *, alpha=.01): + """Small-ensemble diagnostics against the reference, including censoring. + + DKW is a simultaneous CDF bound on [0,H); moment four-SE gates are + diagnostics, not confidence intervals or bounds on discretization error. + The reference moments provide the MC variance of an independent ensemble. + """ + times, hit = np.asarray(times, dtype=float), np.asarray(hit, dtype=bool) + if times.ndim != 1 or hit.shape != times.shape or len(times) < 2: + raise ValueError("need matching independent path arrays with >=2 entries") + if np.any(~np.isfinite(times) | (times < 0) | (times > horizon)): + raise ValueError("observed times must lie in [0,horizon]") + if not 0 < alpha < 1: + raise ValueError("alpha must lie in (0,1)") + n = len(times) + raw = reference.restricted_moments(horizon) + mean, variance = raw[0], raw[1]-raw[0]**2 + fourth = raw[3]-4*mean*raw[2]+6*mean**2*raw[1]-3*mean**4 + variance_se = np.sqrt(max(0., (fourth-(n-3)/(n-1)*variance**2)/n)) + clipped = np.where(hit, times, horizon) + def moment(value, expected, se): + return dict(value=float(value), expected=float(expected), mc_se=float(se), + sigma=float((value-expected)/se), passed=bool(abs(value-expected) <= 4*se)) + events = np.sort(times[hit & (times < horizon)]) + cdf = reference.cdf(events) + distance = max(float(reference.cdf(horizon))-len(events)/n, + float(np.max(np.arange(1, len(events)+1)/n-cdf)) if len(events) else 0., + float(np.max(cdf-np.arange(len(events))/n)) if len(events) else 0.) + limit = np.sqrt(np.log(2/alpha)/(2*n)) + moments = dict(restricted_mean=moment(clipped.mean(), mean, np.sqrt(variance/n)), + restricted_variance=moment(clipped.var(ddof=1), variance, variance_se)) + return dict(paths=n, hits=int(hit.sum()), censored=int((~hit).sum()), + moments=moments, cdf=dict(distance=distance, limit=float(limit), alpha=alpha, + passed=bool(distance <= limit)), + passed=bool(all(m["passed"] for m in moments.values()) and distance <= limit)) diff --git a/examples/benchmarks/results/native_split_20261025/README.md b/examples/benchmarks/results/native_split_20261025/README.md new file mode 100644 index 00000000..c6c3b193 --- /dev/null +++ b/examples/benchmarks/results/native_split_20261025/README.md @@ -0,0 +1,348 @@ +# Native split benchmark reproduction + +Thermalization, first passage and the coordinate moment studies were rerun on +2026-10-28 with 2,000 particles per configuration. Older multirate/convergence +figures remain labelled separately. The paired convergence figure was also +regenerated with 64 common-Brownian paths at .01 and .005. These physics studies are not new performance +measurements of the specialized GPU integration. Numerical reports and samples +are generated under `output/`; no prior JSON/CSV/SVG/PPTX files are required in +the repository. The scripts select the machine's normal JAX backend. Population +and independent PDE reference studies are deliberately separate from CI. + +The split branch is based on `feat/native_dopri` (commit `3d20e36`). Its CI +suite adds 19 test functions, using small deterministic problems and one/two +particles rather than population studies or reference-mesh sweeps. Public field +classes are unchanged; geometry conversion stays in the split solver modules. +Only scripts, Markdown and selected README PNGs belong in this addition. +Generated TMP/SVG/PPTX/CSV/JSON files stay under ignored `output/`. + +### Presentation refresh + +The primary uniform/helix views use 2,000 particles, budget .01 and +--save-points 201 for actual time resolution. Production and independent +references are evaluated at matching times. --charts cartesian selects one +curve per physical model. Black curves retain the distinct GC and full-Lorentz +references; grey/blue bands retain their separate sampling uncertainties. +Panels show means and standard deviations; variance confidence intervals are +transformed by the square root with their lower endpoint clipped at zero. +The six-save diagnostics and their numerical tables below remain historical +results, rather than statistics of the new save grid. + +Thermalization and first-stopping reports can be rendered again with +--plot-only, without tracing. PNG export is 320 dpi, with a PDF companion. +Thermalization histograms retain the independent finite-time speed and pitch +theory, with blue birth-value markers. First stopping +plots only the tight adaptive histogram and black reference. Data are not +pooled across methods or models. +Smooth reference PDFs are scaled by particle count times bin width for the +count histograms. The Lorentz moments are instantaneous samples, not gyro- +averages: the 201-point output grid does not resolve every fast gyroperiod +in the helix, even though the adaptive orbit integration resolves gyromotion. + +After generating the reports, regenerate only the figures with: + +~~~sh +python -m examples.benchmarks.benchmark_split_coordinate_physics --plot-only --study diffusion --charts cartesian --output output/uniform +python -m examples.benchmarks.benchmark_split_coordinate_physics --plot-only --study coupled --charts cartesian --output output/coupled_moments +python -m examples.benchmarks.validate_beam_relaxation --plot-only --output output/thermalization.json +python -m examples.benchmarks.validate_production_tolerance --plot-only --output output/first_passage.json +~~~ + +## Physics studies + +Run from the repository root. These commands launch population studies; they +are provided for later reproduction and are not run by installing the package. + +```sh +python -m examples.benchmarks.validate_beam_relaxation \ + --particles 2000 --batch-size 2000 --coefficient-model impact \ + --methods conservative --settings fine --output output/split_thermalization.json +python -m examples.benchmarks.validate_production_tolerance \ + --particles 2000 --batch-size 2000 --output output/split_first_passage.json +python -m examples.benchmarks.benchmark_split_coordinate_physics \ + --study diffusion --particles 2000 --tolerance .01 --output output/coordinate_diffusion +python -m examples.benchmarks.benchmark_split_coordinate_physics \ + --study coupled --models gc lorentz --particles 2000 --tolerance .01 --output output/coordinate_moments +python -m examples.benchmarks.benchmark_split_multirate \ + --particles 2000 --models gc lorentz --output output/split_multirate +``` + +Thermalization and first passage are collision-operator checks in a fixed bath. +The multirate script uses production `trace_split` and measures speed/pitch and +spatial observables from the same trajectories. It includes GC spatial diffusion +and finite-gyrofrequency Lorentz motion. Its original fixed/conservative controls +remain explicit, so changing the public default does not relabel old results. + +The new coordinate script evolves the same prescribed mirror/helix equations +in Cartesian, VMEC regular and Boozer-style regular charts. The latter include +an angle gauge and toroidal shift, respectively. They are manufactured charts, +not VMEC equilibria or Boozer K=0 magnetic spectra. All three use the production +collision maps, moment predictor, retained Brownian driver and nonlinear +Cartesian spatial-kick inversion. The population reference path uses shared +JAX execution. The mirror/helix axial reference generators omit perpendicular +spatial kicks, while the particles include them; the black curves are therefore +strong-magnetization references. The uniform-field diffusion reference includes +the tested spatial operator. Its Lorentz reference retains finite gyrofrequency. + +Actual QA field-table checks, separate from those independent physics references: + +```sh +python -m examples.benchmarks.benchmark_split_coordinate_physics \ + --study adapters --particles 64 --clocks fixed adaptive --tolerance .01 \ + --output output/equilibrium_adapters +``` + +This checks coils/GC, coils/Lorentz, VMEC/GC and Boozer/GC against shared JAX, +including GPU repeatability when a GPU is available. These checks establish +adapter agreement, not independent statistical accuracy in the QA equilibrium. +Boozer geometry is generated from the same transform as its magnetic tables; +`--mboz` and `--nboz` default to 4 for this small adapter check. VMEC uses its +existing geometric tables. Missing Boozer spatial geometry raises explicitly. + +Black lines show ensemble expectations from independent references. Sampling +intervals, particle variances and paired numerical-refinement differences are +different quantities. A smaller predictor tolerance does not force an individual +finite-population curve closer to its ensemble expectation at every time. +Reference-mesh refinement and paired Brownian-path refinement must be assessed +separately from those sampling intervals. + +For the recorded .01 run, the following final variance gaps are relative to the +independent axial reference. Both numbers are percentages of the reference +variance: the first is the sample gap and the second is its marginal 95% +sampling half-width. Neither number is the controller's estimated error. + +| Field / chart | Position variance gap % | Pitch variance gap % | Parallel-velocity variance gap % | +|---|---:|---:|---:| +| Mirror / Cartesian | -6.73 +/- 5.78 | -9.66 +/- 5.88 | -10.51 +/- 5.66 | +| Mirror / VMEC chart | -6.73 +/- 5.78 | -9.65 +/- 5.88 | -10.51 +/- 5.66 | +| Mirror / Boozer chart | -6.73 +/- 5.78 | -9.66 +/- 5.88 | -10.51 +/- 5.66 | +| Helix / Cartesian | +0.71 +/- 6.00 | +3.95 +/- 6.32 | +0.64 +/- 6.05 | +| Helix / VMEC chart | +0.71 +/- 6.00 | +4.76 +/- 6.37 | +1.38 +/- 6.10 | +| Helix / Boozer chart | +0.68 +/- 5.99 | +3.91 +/- 6.38 | +1.10 +/- 6.14 | + +Reference-refinement indicators for these variances reach 0.23% in the mirror +and 0.006% in the helix; they are not included in the sampling half-widths above. +The mirror offsets exceed marginal sampling intervals in this seed. Agreement +between charts does not resolve that physical-reference discrepancy, and this +run is not a general validation of a .01 budget. Independent-seed and numerical +refinement checks are separate from increasing the interval width by combining +many comparisons. + +An independent mirror ensemble (seed 8707, same .01 budget and .0025 cap) +gave final variance gaps of `+1.85 +/- 6.17%` in position, +`-0.08 +/- 6.30%` in pitch, and `-1.89 +/- 6.06%` in parallel velocity. +Its speed variance was `-7.53 +/- 5.53%`. The changing offsets illustrate why a +single population/reference gap cannot identify numerical bias. These two +ensembles are reported separately; the primary figure has not been replaced +by a more favourable seed. Reproduce with `--fields mirror --charts cartesian +--seed 8707` and the same budget. + +Uniform-field perpendicular spreading at `Omega/nu0=2048` gave +`-0.88 +/- 4.48%` for GC in each chart and `+0.41 +/- 4.62%` for Lorentz. +The same trajectories gave speed-variance gaps `+9.19 +/- 7.23%` (GC) and +`-11.32 +/- 5.46%` (Lorentz). These velocity offsets require further numerical +and ensemble convergence; the recorded .01 run is not an all-statistics pass. + +The uniform figure runs to `t*nu0=0.1`; the mirror/helix figures end at 0.025. +The following additional ensembles use 2,000 particles, moment budget +.01 and cap .0025. Each entry is the final speed-variance gap plus/minus its +marginal 95% sampling half-width, in percent of the independent reference. + +| Duration t*nu0 | Seed | GC gap % | Lorentz gap % | +|---|---:|---:|---:| +| 0.1, primary figure | 7706 | +9.19 +/- 7.23 | -11.32 +/- 5.46 | +| 0.1, independent ensemble | 8706 | -1.00 +/- 6.30 | -2.50 +/- 6.14 | +| 0.025, matched mirror duration | 8706 | -2.36 +/- 5.96 | +0.19 +/- 6.11 | + +Changing only the seed at the original duration changes both offsets +substantially. These results do not support a claim that uniform-field speed +physics is intrinsically less accurate, but they do not separate all numerical +bias from sampling either. The primary figure has not been replaced. Reproduce +the extra ensembles with: + +```sh +python -m examples.benchmarks.benchmark_split_coordinate_physics \ + --study diffusion --models gc lorentz --charts cartesian --particles 2000 \ + --tolerance .01 --seed 8706 --horizon .1 --output output/uniform_seed8706 +python -m examples.benchmarks.benchmark_split_coordinate_physics \ + --study diffusion --models gc lorentz --charts cartesian --particles 2000 \ + --tolerance .01 --seed 8706 --horizon .025 --output output/uniform_matched_duration +``` + +Additional uniform Lorentz ensembles at the original duration gave speed +variance gaps `+2.01 +/- 6.34%` (seed 7707), `-3.47 +/- 6.15%` (7708), +`-1.63 +/- 6.15%` (7709), and `+4.59 +/- 6.18%` (7710). Each uses 2,000 +particles and the unchanged .01 budget/.0025 cap; reproduce by changing +`--seed` in the uniform command above. All four marginal intervals include +the reference; the original seed 7706 remains recorded as an outlier. + +A separate diagnostic retained the original 2,000-particle Brownian increments +and globally continued the production Lorentz map through conditional +subintervals. Subdivision factors 2, 4 and 8 changed the final speed variance +by `+0.019 +/- 0.082`, `+0.040 +/- 0.096` and `+0.049 +/- 0.108` percentage +points of the theoretical variance (coarse minus refined, paired 95% sampling +intervals). The coarse ensemble exactly reproduced the original variance; +the eightfold-refined ensemble remained 11.37% below theory. Doubling the +radial reference mesh from 768 to 1,536 cells changed its final variance by +0.014%. These checks support ensemble fluctuation over collision-step bias +as the explanation of this particular deficit; they do not certify every +phase-space statistic or eliminate all possible systematic errors. + +The coupled script also supports Cartesian Lorentz mirror/helix runs through +`--models lorentz`. Velocities are aligned to give birth pitch 0.6 in each +local field, with the leading-order gyrocentre at the GC birth point. It keeps +the GC benchmark's gyrofrequency ratios: 2048 in the mirror and 2,000,000 in +the helix. Resolving the latter's gyromotion requires many orbit substeps per +collision interval. The speed reference is independent for both models, since +the field does no work in this homogeneous bath. Position, pitch and parallel +moments now use a separately implemented full-Lorentz numerical reference in +both the mirror and helix. The earlier GC-limit curves have been replaced. + +The independent reference uses centred exact-angle magnetic rotations and Cartesian +Euler--Maruyama updates of the independently evaluated proton Coulomb Ito +generator. Its Gaussian noise is carried in a transported orthogonal frame; +this changes neither the physical drift nor diffusion tensor and makes its +paired refinements less sensitive to fast gyrophase differences. Production +RK, collision maps, predictor and Brownian memory are unchanged. Reference +controls halve the orbit phase limit, then halve the collision interval on +the same reference Brownian path. Defaults are 2,000 independent particles, +400 coarse collision steps per save, five save intervals of .005, and phase +limits .1/.05 radians. The finest collision interval is 6.25e-6/nu0. + +```sh +python -m examples.benchmarks.lorentz_collision_reference \ + --particles 2000 --steps 400 --phase .1 --output output/lorentz_reference.json +python -m examples.benchmarks.benchmark_split_coordinate_physics \ + --study coupled --models lorentz --particles 2000 --tolerance .01 \ + --lorentz-reference output/lorentz_reference.json --output output/lorentz_moments +``` + +Use `--plot-only --lorentz-reference PATH` on an existing coupled report to +correct its reference and regenerate figures without retracing particles. +Old Lorentz reports cannot silently plot GC curves as Lorentz references. +Grey bands show reference sampling uncertainty, blue bands show production +sampling uncertainty. Gaps between independent sample means use the combined +standard error; reference step-refinement uncertainty remains separate. These +are model-matched numerical ensemble references, not analytic solutions. + +The 2,000-particle Lorentz runs completed without solver failures. Final speed +variance gaps are `-0.28 +/- 6.09%` in the mirror and `-3.00 +/- 6.25%` in the +helix. Mean accepted orbit steps per collision are 1.006 and 256.77, respectively; +the gyrofrequency parameters were retained. These production trajectories +are unchanged by the corrected reference calculation. + +Final production-minus-reference gaps, normalized by the absolute reference +value, are below. Intervals combine independent production and reference +sampling standard errors; deterministic radial theory is used for speed. + +| Field | Mean z gap % | Mean pitch gap % | Var z gap % | Var pitch gap % | +|---|---:|---:|---:|---:| +| Mirror | +0.44 +/- 0.82 | +0.16 +/- 1.06 | +1.64 +/- 8.82 | -1.51 +/- 9.08 | +| Helix | -0.11 +/- 0.33 | -0.13 +/- 0.52 | -7.90 +/- 8.28 | -2.67 +/- 8.48 | + +The helix reference's final paired orbit-refinement changes are +`-0.00103 +/- 0.00011%` for mean z and `-0.00489 +/- 0.00413%` for Var z. +Collision-interval refinement gives `+0.0107 +/- 0.0234%` and +`-0.2263 +/- 0.8591%`, respectively. These reference changes are substantially +smaller than the production/reference sampling intervals, but are not global +error bounds. For the mirror, collision refinement changes Var z by +`-0.0279 +/- 0.0048%`: this small nonzero numerical difference remains recorded. +The final variance measurements agree within their combined intervals, whose +widths are too large to certify 1% variance accuracy. Several earlier helix +variance/covariance gaps remain outside pointwise 95% intervals: Var z gaps +are `-9.00 +/- 8.21%`, `-9.91 +/- 8.13%`, `-10.91 +/- 8.06%` and +`-10.17 +/- 8.10%` at t*nu0=.005/.01/.015/.02. These are unresolved physical +statistics discrepancies; the corrected references do not make the entire +benchmark an all-moments pass. Finite-sample agreement is not a general +guarantee for the .01 controller budget. + +The reference magnetic rotation uses the exact angle |Omega|*dt. The earlier +Cayley-angle trial had a gyrophase error visible in the helix pitch transient, +so it is not used for the retained figures. Collisionless exact-angle controls +converge to a tight full-Lorentz Dopri8 solve: at phase limit .05 the helix +relative z error is 3.26e-6 and the absolute pitch error is 6.70e-6. Both errors +fall by approximately four on halving that phase limit. This checks the orbit +reference separately from its Monte Carlo sampling and collision resolution. + +The old Lorentz helix mean axial position was 1.94% +/- 0.22% below the GC-limit +curve. A collisionless control with the same field and birth convention +already differs by 1.76% from the exact GC orbit. Tightening Lorentz orbit +tolerances from 1e-10 to 1e-12 changes its final axial position by less than +2e-11 in relative terms; the speed error decreases from 1.44e-7 to 8.67e-10. +Thus most of this spatial gap precedes collisions and cannot be attributed +to the collision controller. Here k*rho at birth is approximately .0253; +the GC and Lorentz states are matched using only a leading-order gyrocentre +conversion. The test does not separately resolve finite-gyro model effects +from birth-coordinate conversion. This GC/Lorentz diagnostic is separate +from comparison with the new matched numerical reference. + +## Retained predictor and controller experiments + +Production uses the original orbit-then-collision map and retained Brownian +rejection memory. The selected moment predictor adds a state-dependent coupled +mean/covariance interval ceiling. Native collision and embedded RK checks remain +active. The default moment budget is `0.005`, collision tolerance is `0.001`, +and orbit tolerances are separate. These numbers are not interchangeable error +bounds and do not promise a global percentage error in physical statistics. + +Earlier comparisons included conservative coefficient control, paper Wiener +look-ahead, shared-clock controls, full-step/two-half-step combined control, +local trajectory-RMS and coupling estimates, accumulated-history budgets, +scheduled tolerances and local quadrature probes. Combined control remains an +expensive convergence comparator. The retained moment predictor avoids the +comparison trajectory. Discarded history/scheduling/quadrature variants are +not production defaults or dependencies of the GPU kernel. No change to Strang +splitting, fitted calibration or finite-difference derivatives is included. + +Generate other moment-budget checks without a saved numerical archive: + +```sh +python -m examples.benchmarks.benchmark_split_coordinate_physics \ + --particles 2000 --tolerance .005 --output output/moment_005 +``` + +The script regenerates its independent references by default. `--reference` +optionally reuses an ignored reference file from a previous invocation. `--cap` +and `--seed` provide explicit convergence and independent-ensemble controls; +the documented .01 run retains cap .0025. Paired numerical refinement is +provided separately and also regenerates its independent normalization reference: + +```sh +python -m examples.benchmarks.benchmark_split_path_convergence \ + --control moments --particles 64 --tolerances .01 .005 \ + --refinements 8 16 32 --max-steps 2000 --max-roots 4096 \ + --output output/paired_convergence +``` + +`--reference` optionally supplies the reference generated by the coordinate +script. This check uses the axial model with spatial kicks disabled and retains +the same Brownian realization within each coarse/refined pair. It does not +regenerate the population confidence bands. Its .005 cases roughly double +collision updates compared with .01 and reduce position and speed path errors +in the recorded run; the physical sampling offsets above are a separate result. + +## Timing and memory + +See the [cold compilation comparison](compilation_20261027.md) for separately +measured lowering, backend compilation and first execution on the local GPU. + +`examples.benchmarks.benchmark_split_orbits` separates compilation from blocked +warm tracing, records compiler buffers and allocator peaks, and supports the +shared and specialized native implementations. Use separate fresh processes +for allocator-peak comparisons: + +```sh +python -m examples.benchmarks.benchmark_split_orbits --field coils --model gc \ + --case native_independent --stepping adaptive --particles 64 \ + --output output/split_gpu_gc +python -m examples.benchmarks.benchmark_split_orbits --field coils --model gc \ + --case native_shared --stepping adaptive --particles 64 \ + --output output/split_shared_gc +``` + +Use `--model lorentz` for full orbit or `--stepping fixed` for fixed clocks. +The legacy Diffrax GC reference omits spatial diffusion; use the explicit +`--no-spatial-diffusion` diagnostic for a matched comparison to that operator. +Coordinate-field GC diffusion uses the nonlinear Cartesian kick inversion. +Boozer callers supply `BoozerGeometry.from_booz_xform(transform)` through +`spatial_geometry`; the magnetic spectrum alone contains insufficient geometry. diff --git a/examples/benchmarks/results/native_split_20261025/compilation_20261027.md b/examples/benchmarks/results/native_split_20261025/compilation_20261027.md new file mode 100644 index 00000000..722a85be --- /dev/null +++ b/examples/benchmarks/results/native_split_20261025/compilation_20261027.md @@ -0,0 +1,354 @@ +# Cold compilation comparison, 27 October 2026 + +Local GPU: NVIDIA GeForce RTX 5060 Laptop GPU; JAX/JAXLIB 0.11.2, +Python 3.14 under WSL. Each row uses a fresh process with the persistent JAX +solver compilation cache disabled and a separate Triton cache directory. These are +single cold measurements, not averages or A100 measurements. + +The split-native rows use adaptive Dopri8, the retained moment predictor +(`moment_tolerance=0.005`), collision tolerance `0.001`, and orbit +`rtol=atol=1e-10`. Shared and independent execution use the same particles, +field and numerical method within each workload. Cartesian GC includes its +existing spatial collision update. VMEC/Boozer use their existing velocity/pitch +collision operators with spatial diffusion explicitly disabled. + +Two 4 keV alpha particles, seed 42, a 1 ns horizon, three saves, 32 maximum +collision trials and 64 maximum inner orbit trials keep execution short while +compiling the full selected solver. A uniform prescribed background has density +`1e20 m^-3` and temperature `1000 eV`. Coil geometry is the bundled +Landreman/Paul QA coil set; VMEC and Boozer use the bundled QA equilibrium. + +Field loading/construction, imports and particle setup are excluded. Lowering +includes tracing and solver graph preparation; backend compilation is measured +by `lowered.compile()`. The first execution is timed separately and synchronized +with `jax.block_until_ready`. Cold total means lowering plus backend compilation, +without execution. These small-population measurements do not establish +production execution speed, population scaling or physical accuracy. + +| Field / model | Execution | Lowering s | Backend compile s | Cold total s | First execution s | +|---|---|---:|---:|---:|---:| +| Coils / GC | Shared JAX | 2.91 | 8.79 | 11.70 | 0.039 | +| Coils / GC | Specialized GPU | 5.14 | 65.32 | 70.46 | 0.093 | +| Coils / Lorentz | Shared JAX | 2.82 | 8.81 | 11.63 | 0.028 | +| Coils / Lorentz | Specialized GPU | 6.97 | 346.09 | 353.06 | 0.108 | +| VMEC / GC | Shared JAX | 9.25 | 13.63 | 22.88 | 0.041 | +| VMEC / GC | Specialized GPU | 15.89 | 260.03 | 275.92 | 0.041 | +| Boozer / GC | Shared JAX | 3.22 | 10.26 | 13.47 | 0.025 | +| Boozer / GC | Specialized GPU | 5.07 | 66.88 | 71.95 | 0.039 | + +These baseline measurements locate most of the specialized implementation's +extra cost in backend compilation. Subsequent compiler simplifications are +compared against these same native workloads. No Diffrax comparison is included. + +## Exact shared field Jacobians + +The predictor's private adapter now shares one field-value/Jacobian evaluation +across its Lorentz derivative directions. The custom JVP uses the existing exact +native coil Jacobian. These +are changes to code generation within the solver adapter; the selected moment +predictor and orbit/collision maps are unchanged. No public field classes change. + +| Workload | Original cold total s | Shared-Jacobian cold total s | Reduction | +|---|---:|---:|---:| +| Coils / Lorentz, predictor enabled | 353.06 | 126.27 | 64.2% | + +Lorentz backend compilation decreased from 346.09 to 119.67 seconds. Saved +states and step counts were identical in the matched check; compiled executable +buffers stayed at 7,056 bytes. This tiny-population check establishes equivalence +for these inputs, not a general production runtime benchmark. + +A fresh confirmation with the corrected cold-cache policy below measured +5.69 seconds lowering and 99.27 seconds backend compilation (104.96 seconds +total). The helper code was unchanged from the earlier 126.27-second run; +the difference between those runs is not an additional optimization claim. +Warm median was 6.047 ms versus the historical 5.964 ms, with only three/one +samples respectively. Saved states, terminal states and all counters were +bitwise identical; executable buffers remained 7,056 bytes. The process-wide +JAX allocator peak was 143,360 bytes, including setup, compilation and execution. + +As a diagnostic only, the same native Lorentz workload with conservative +collision control and no moment predictor took 2.81 seconds lowering and 5.07 +seconds backend compilation (7.88 seconds total). The production default remains +the moment predictor. This comparison isolates the additional compiler burden; +it is not a recommendation to disable the predictor. + +## GC symmetric covariance reduction + +The GC predictor now evaluates the maximum over the unique entries of its +symmetric projected covariance, rather than both triangles. Every unique +covariance constraint remains present. This reduces the isolated scalar budget +graph from 908 to 712 expressions without changing coefficients, field queries, +the collision map or the selected controller. + +The following fresh measurements use the corrected cold-cache policy described +below. Their full-matrix repeat is the appropriate baseline for this candidate; +the historical 70.46-second measurement above is retained separately. + +| GC / direct coils | Lowering s | Backend compile s | Cold total s | Compiled buffers bytes | Allocator peak bytes | +|---|---:|---:|---:|---:|---:| +| Full covariance reduction | 5.25 | 73.79 | 79.04 | 135,544 | 83,988,736 | +| Unique symmetric entries | 5.26 | 66.35 | 71.61 | 135,544 | 83,988,736 | + +This pair gives a 9.4% cold-total reduction. A separate warm comparison alternated +30 calls per version in one process: median 12.710 versus 12.683 ms, with +interquartile ranges 12.634–12.792 and 12.633–12.766 ms, respectively. All returned +arrays were bitwise identical. These two-particle checks support unchanged warm +cost for this workload; they do not establish population scaling. The allocator +peak includes setup, compilation and execution, and is not a per-particle cost. + +The expanded budget is checked against the independent dense matrix calculation, +including mixed covariances, nonzero velocity curvature, pitch endpoints and +zero/tiny noise. This extends an existing test; the native split suite still has +19 test functions. + +After the earlier covariance-symmetry change, `pytest tests/test_native_split.py -q` passed all +19 tests in 164.19 seconds on the local CPU. Actual GPU checks above validate +the coil kernels separately; the CPU suite does not measure GPU performance. + +## Cold-cache validation + +In the installed JAX version, changing the cache-enable setting after setup does +not invalidate its memoized cache-use decision. An attempted full-matrix repeat +loaded an executable in 0.040 seconds despite the setting reporting disabled; +that cached result is excluded from the cold comparisons. The benchmark now +calls the public experimental `compilation_cache.reset_cache()` after disabling +the cache and before solver lowering. Setup can still use the persistent cache. +No disk caches are deleted. Distinct Triton cache directories remain required. + +## Further retained coil reductions + +These follow-up measurements use the same GPU, two-particle inputs, controls, +spatial-diffusion settings and corrected cold-cache policy. The before column +uses the preceding retained implementations, rather than the original baseline. + +| Direct coil field / model | Before cold total s | After this stage s | Additional reduction | Compiled buffers bytes | Allocator peak bytes | +|---|---:|---:|---:|---:|---:| +| GC | 71.61 | 66.54 | 7.1% | 135,544, unchanged | 83,988,736, unchanged | +| Lorentz | 104.96 | 83.10 | 20.8% | 7,056, unchanged | 143,360, unchanged | + +At this stage GC lowering/backend compilation took 4.81/61.73 seconds; Lorentz took +5.01/78.08 seconds. These remain single cold measurements, not timing averages. +Paired warm checks alternated 30 calls per implementation in one process: + +| Model | Before median ms (interquartile range) | After median ms (interquartile range) | +|---|---:|---:| +| GC | 12.677 (12.593–12.806) | 12.652 (12.561–12.740) | +| Lorentz | 4.885 (4.828–5.069) | 4.921 (4.835–5.099) | + +The warm checks show no meaningful runtime change for this workload; they are +not evidence of a production throughput gain. Saved states, terminal states, +times, statuses and counters were bitwise identical in both paired checks. + +GC now reuses reciprocal normalization scales, reducing scalar divisions from +35 to 11; its scalar expression count changes from 712 to 718. Lorentz evaluates +the Ito covariance in blocks and reduces its symmetric covariance maximum over +unique entries, reducing the scalar budget graph from 5,073 to 3,966 expressions. +The block covariance agrees with the original dense product in value, Jacobian +and Hessian, including unconstrained field-direction derivatives, pitch endpoints +and zero diffusion. The predictor, numerical scheme and public field classes +are unchanged. No finite-difference derivatives or fitted calibration enter. + +Reciprocal normalization was also tested for Lorentz: 84.84 seconds cold versus +83.10 seconds for covariance blocks alone. It was reverted. A GC audit that +differentiated physical variances directly passed both Coulomb models with +smooth varying profiles, low speeds and vacuum, but removed only 58 scalar +expressions; that alternative was not added to production. + +The audit also exposed a pre-existing interpolation-lowering incompatibility +with JAX 0.11 scan metadata. The private adapter now accepts both metadata forms +and stacks scalar tracers without converting them to host values. Forward and +reverse scans, interpolation and its forward derivative are covered within the +existing scalar-lowering test; the suite still contains 19 test functions. + +After all the retained follow-up changes, `pytest tests/test_native_split.py -q` +passed all 19 tests in 174.35 seconds on the local CPU. Source whitespace checks +passed, and the orbit/collision stepper file matched its pre-optimization hash. + +The follow-up raw results are under `output/compile_optimization_20261027/` +in `gc_inverse_scale`, `lorentz_covariance_blocks`, and the two +`{gc,lorentz}_algebra_warm_pair.json` reports. Generated raw files remain ignored. + +## Exact Lorentz velocity Jacobians + +The predictor now uses exact formulas for the partial velocity Jacobians of its +collision drift and orbit flow. These replace two small forward-AD calculations; +they do not change the tracing RHS, collision update, estimator or field classes. +The formulas retain field/profile dependence and remain differentiable in their +inputs. Independent AD comparisons cover values and higher velocity derivatives, +nonzero electric fields, pitch endpoints, zero rates and both orbit settings. +The scalar Lorentz budget graph decreases from 3,966 to 3,711 expressions. + +| Latest retained coil implementation | Previous cold total s | Retained cold total s | Additional reduction | +|---|---:|---:|---:| +| GC | 66.54 | 66.54 (unchanged; preceding measurement) | None | +| Lorentz | 83.10 | 78.00 | 6.1% | + +The new Lorentz cold run measured 5.50 seconds lowering and 72.50 seconds backend +compilation. Compiled buffers remained 7,056 bytes and the fresh-process JAX +allocator peak remained 143,360 bytes. The inputs and controls match the earlier +two-particle adaptive Dopri8/direct-coil workload; this is one cold measurement. + +Thirty alternating blocked warm calls gave medians 4.867 ms before and 4.782 ms +after, with interquartile ranges 4.764–5.032 and 4.738–4.976 ms. No separate warm +throughput improvement is claimed. Every returned array, including saved and +terminal states, times, statuses and counters, was bitwise identical. + +A shared reciprocal for the GC field magnitude and velocity-jet denominator +reduced the isolated division count from 32 to 3 and passed independent-reference +checks. Its measured cold total was 68.91 seconds versus 66.54 seconds, so it was +reverted. A scalar-identity pruning audit removed only 12/15 expressions from +the GC/Lorentz budgets and was not added to production. + +The final suite passed all 19 tests in 122.13 seconds on CPU, while untimed GPU +executable preparation ran separately. GPU warm timing waited until CPU tests +finished. Results are in `lorentz_analytic_velocity` and +`lorentz_jacobian_warm_pair.json` beneath the same ignored output directory; +the discarded GC trial is `gc_shared_velocity_denominators`. + +## Three additional passes: no further retained change + +Three additional investigations kept the same predictor, collision update, +orbit method and field classes. None passed both the performance and correctness +requirements, so the retained cold totals remain **66.54 s for GC** and +**78.00 s for Lorentz**. Those are the preceding measurements, not new timings. + +1. **Covariance contractions.** Factoring GC noise amplitudes increased the + scalar budget graph from 718 to 728 expressions. A direct Lorentz covariance + contraction reduced 3,711 expressions to 3,637, but its measured cold total + with the experimental two-warp layout was 71.05 s versus 71.10 s for that + layout alone. This does not establish a useful gain, and neither variant was + retained. +2. **Shared coefficient derivatives.** Sharing primal values through ordinary + nested JVPs left the scalar coefficient graph sizes unchanged. Low-speed + derivative comparisons failed the existing strict reference tolerances for + both GC and Lorentz, with both Coulomb-log models. These variants were + rejected; no derivative tolerance was relaxed. Grouping source locations also + reduced generated IR size by less than one percent and was not retained. +3. **GPU layout.** Two warps instead of one gave the following preliminary + two-particle cold timings, with unchanged compiled buffers and allocator + peaks. A subsequent 64-particle check invalidated this candidate. + +| Direct coil model | Validated one-warp cold total s | Experimental two-warp cold total s | Decision | +|---|---:|---:|---| +| GC | 66.54 | 53.86 | Rejected: GPU correctness failure | +| Lorentz | 78.00 | 71.10 | Not retained: proposed layout failed GC validation | + +The initial two-particle outputs agreed to roundoff and did not expose the GPU +layout defect. At 64 particles, repeated calls to the same two-warp GC executable +produced different outputs in both fixed and adaptive modes. The one-warp +executable was reproducible in the same checks. Separately, 16 consecutive +production Brownian draws for each of 64 keys agreed bitwise between layouts, +for noise dimensions two, three and five. Thus an adaptive Brownian-path change +does not explain the fixed-step failure. The underlying layout/code-generation +mechanism has not been isolated. No two-warp speedup is considered validated; +the launch change was completely reverted, and a larger-population Lorentz +comparison was not pursued. + +No production source or tests remain changed by these three passes. The source +files were compared byte-for-byte with their preceding validated snapshots. +The suite still has 19 test functions; all 19 passed in 114.65 s during this +investigation. The restored source also matches the earlier validated version +whose full suite passed in 122.13 s. Diagnostic outputs remain ignored beneath +`output/compile_optimization_20261027/three_pass_*`; the experiment scripts are +workspace scratch files, not added production dependencies. + +## Discarded alternatives + +The following experiments are not production dependencies: + +* Simplifying the expanded predictor again, sharing immutable table reads, and + exposing literal padding zeros did not yield a shorter cold compile. These + experiments were stopped without completed timings and were reverted; their + partial runs are not presented as measured compile durations. +* An exact custom JVP for the six Lorentz collision moments passed first- and + second-derivative comparisons against ordinary AD. After simplification, the + complete local Lorentz budget had 5,183 scalar expressions instead of 5,073. + This rule was discarded before another expensive GPU compilation. +* A joint Taylor-mode evaluation of radial coefficient derivatives produced + 2,454 scalar expressions instead of 1,255 in the NRL coefficient audit and + failed the stringent low-speed derivative comparison. It was not added to + production. +* Reducing the compiler's software-pipeline depth from three stages to one did + not produce a shorter compile before the experiment was stopped. The default + compiler setting was restored. +* Sharing the VMEC position/Jacobian in the same way exceeded the original + compilation cost before completing. That variant was reverted; the existing + analytic VMEC position derivative remains in use. +* Reusing the Cartesian GC predictor's magnitude from its full geometry query + increased cold total from 70.46 to 91.02 seconds (backend: 65.32 to 82.94 + seconds). That variant was also reverted. GC/coils and Boozer retain their + original field adapters; the GC improvement above changes covariance algebra. +* Four-warps GC launch layouts, with three/one software-pipeline stages, took + 77.15/74.07 seconds cold, versus the original 70.46 seconds. Two-particle warm + calls took 6.37/6.95 ms versus 12.69 ms, but larger-population runtime was not + validated. These launch settings are not retained for the compilation target. + +An additional JAX compiler trace of unchanged GC code recorded about 77.9 seconds +in backend compilation, with 0.59 seconds in ordinary HLO optimization. The long +`CompileModuleToLlvmIr` span includes kernel code generation and nested assembly +work; the largest nested `PTX->CUBIN` event was 16.69 seconds. These spans overlap +and must not be summed. This is a diagnostic capture, not a new unprofiled timing +baseline. The remaining GC kernel-generation cost has not been eliminated. + +A custom VJP does not supply the forward-mode and second derivatives used by +this predictor. Custom JVPs can provide those derivatives, but the tested rule +shows that replacing AD alone does not guarantee a smaller generated kernel. + +## Corrected coordinate spatial kernels, 28 October + +These follow-up adapter checks include Cartesian spatial kicks transformed +nonlinearly into VMEC and Boozer charts. They use 64 protons at 5 keV, +adaptive Dopri8, moment budget .01, native collision tolerance .001, +orbit rtol=atol=1e-9, three saves and a .4 ns horizon. Both implementations +execute on the local GPU. Setup is excluded from the timer; lowering and +backend compilation are included, execution is excluded. Persistent caching +is allowed and no cold-cache claim is made. + +| Field / model | Shared native JAX s | Independent GPU s | +|---|---:|---:| +| Coils / GC | 12.9327 | 63.5113 | +| Coils / Lorentz | 8.4850 | 81.4998 | +| VMEC / GC | 9.4936 | 369.9863 | +| Boozer / GC | 12.2298 | 209.4124 | + +All four pairs passed shared/GPU state agreement and exact repeatability of +repeated GPU calls at 64 particles. The new coordinate-spatial VMEC kernel +uses one warp: its previous four-warp launch failed the larger check despite +passing the initial two-particle check. The collision map and predictor were +unchanged. This is a layout correction, not a fallback to shared execution. +Boozer geometry table reads remain vectorized in its private solver adapter. + +These are not before/after matches to the earlier cold alpha measurements: +population, species, controls and coordinate spatial physics differ. In +particular, the VMEC and Boozer compilation costs remain large. These adapter +checks also do not establish statistical physics accuracy in the QA equilibrium. + +Reproduce with `benchmark_split_coordinate_physics --study adapters --particles +64 --clocks adaptive --tolerance .01 --output output/equilibrium_adapters`. +The optional `--adapter-fields` selects subsets. The source exports Boozer +spatial geometry from the same transform as its magnetic tables. + +## Reproduction + +From the repository root, start a fresh Python process for each row. For example: + +```sh +XLA_PYTHON_CLIENT_PREALLOCATE=false OPENBLAS_NUM_THREADS=1 \ +TRITON_CACHE_DIR=output/compile_gc_independent/triton_cache \ +python -m examples.benchmarks.benchmark_split_orbits \ + --field coils --model gc --case native_independent --stepping adaptive \ + --particles 2 --horizon 1e-9 --saves 3 --steps 2 --repeats 1 \ + --max-steps 32 --max-orbit-steps 64 --rtol 1e-10 --atol 1e-10 \ + --collision-tolerance .001 --moment-tolerance .005 --cold-compile \ + --output output/compile_gc_independent +``` + +Repeat with `--case native_shared` and a fresh output/cache directory for the +shared implementation. Use `--model lorentz` for coil full orbits. For VMEC or +Boozer use `--field vmec` or `--field boozer`, `--model gc` and +`--no-spatial-diffusion`. Boozer accepts `--field-cache PATH/boozer_inputs.npz` +from the native Boozer alpha example; field preparation is excluded either way. + +Raw reports and logs are generated under `output/compilation_comparison_20261027/` +and `output/compile_optimization_20261027/`; +they are deliberately not versioned. diff --git a/examples/benchmarks/thermal_relaxation_reference.py b/examples/benchmarks/thermal_relaxation_reference.py new file mode 100644 index 00000000..2006ea02 --- /dev/null +++ b/examples/benchmarks/thermal_relaxation_reference.py @@ -0,0 +1,211 @@ +"""Independent nonrelativistic Coulomb beam relaxation in a Maxwellian bath. + +Velocity uses sigma=sqrt(T/m), time uses 1/nu_s(sigma). Holding the Coulomb +logarithm fixed makes the exact equilibrium Maxwellian. NumPy incomplete-gamma +coefficients and a reflecting finite-volume backward generator are independent +of the JAX collision maps and their time driver. Legendre sectors resolve pitch +and GC spatial diffusion without stochastic trajectories or an SDE solver. +""" +from dataclasses import dataclass + +import numpy as np +from scipy.linalg import eigh_tridiagonal +from scipy.special import gammainc +from scipy.stats import maxwell + + +def coefficients(r): + """Return dimensionless D_parallel, D_perp, nu_pitch independently.""" + r = np.asarray(r, float) + if np.any(~np.isfinite(r) | (r <= 0)): + raise ValueError("positive finite radial coordinates required") + x = r/np.sqrt(2.) + normalizer = float(gammainc(1.5, .5)) + g = gammainc(1.5, x*x)/(2*x*x) + dp = g/(r*normalizer) + # erf(x)=P(1/2,x^2), independent of ESSOS's erf/Chandrasekhar code. + dt = (gammainc(.5, x*x)-g)/(2*r*normalizer) + return dp, dt, 2*dt/r**2 + + +@dataclass +class RelaxationReference: + lower: float = 0. + upper: float = 8. + nodes: int = 768 + start: float = np.sqrt(10.) + pitch: float = .6 + law: object = coefficients + + def __post_init__(self): + if not 0 <= self.lower < self.start < self.upper or not -1 <= self.pitch <= 1 or self.nodes < 32: + raise ValueError("invalid radial domain, mesh or pitch") + self.edges = np.linspace(self.lower, self.upper, self.nodes+1) + self.grid = (self.edges[:-1]+self.edges[1:])/2 + dr = self.edges[1]-self.edges[0] + # Exact Maxwellian mass in each finite volume; this also resolves the + # integrable radial-coordinate singularity at zero without a fake wall. + self.mass = np.diff(maxwell.cdf(self.edges)) + # sf differences avoid cancellation in the remote tail near r=8. + high = self.edges[:-1] > 4. + self.mass[high] = -np.diff(maxwell.sf(self.edges))[high] + dp, _, _ = self.law(self.edges[1:-1]) + conductance = dp*maxwell.pdf(self.edges[1:-1])/dr + self.low = np.r_[0., conductance/self.mass[1:]] + self.high = np.r_[conductance/self.mass[:-1], 0.] + self.diagonal = -(self.low+self.high) + self.off = conductance/np.sqrt(self.mass[:-1]*self.mass[1:]) + self.evaluate = np.zeros(self.nodes) + i = np.searchsorted(self.grid, self.start)-1 + fraction = (self.start-self.grid[i])/dr + self.evaluate[i:i+2] = (1-fraction, fraction) + self.root_mass = np.sqrt(self.mass) + self._spectra = {} + + def spectrum(self, ell): + if ell not in self._spectra: + _, _, nu = self.law(self.grid) + values, vectors = eigh_tridiagonal(self.diagonal-ell*(ell+1)*nu/2, self.off) + if ell == 0: + if abs(values[-1]) > 2e-8: + raise RuntimeError("reflecting generator has no stationary mode") + values[-1] = 0. + self._spectra[ell] = (values, vectors, (self.evaluate/self.root_mass)@vectors) + return self._spectra[ell] + + def expectation(self, times, observable, ell=0, *, integral=False): + t = np.asarray(times, float) + if np.any(~np.isfinite(t) | (t < 0)): + raise ValueError("finite nonnegative times required") + values, vectors, initial = self.spectrum(ell) + amplitude = initial*(vectors.T@(self.root_mass*np.broadcast_to(observable, self.grid.shape))) + if integral: + zero = values == 0 + rate = np.where(zero, -1., values) + kernel = np.expm1(t[..., None]*rate)/rate + kernel[..., zero] = t[..., None] + else: + kernel = np.exp(t[..., None]*values) + return kernel@amplitude + + def moments(self, times): + t = np.asarray(times, float) + r = self.grid + m1, m2 = (self.expectation(t, r**k) for k in (1, 2)) + p2 = (3*self.pitch**2-1)/2 + xi = self.pitch*self.expectation(t, 1., 1) + xi2 = (1+2*p2*self.expectation(t, 1., 2))/3 + parallel = self.pitch*self.expectation(t, r, 1) + parallel2 = (m2+2*p2*self.expectation(t, r*r, 2))/3 + dp, dt, _ = self.law(r) + q = 4*(self.expectation(t, (dp+2*dt)/3, integral=True) + +p2*self.expectation(t, (dt-dp)/3, 2, integral=True)) + result = dict(speed_mean=m1, speed_variance=m2-m1*m1, speed2=m2, + pitch_mean=xi, pitch_variance=xi2-xi*xi, + parallel_mean=parallel, parallel_variance=parallel2-parallel*parallel, + spatial_integral=q) + # The monoenergetic initial distribution is exact, independent of mesh + # interpolation of its squared speed at an interior evaluation point. + initial = dict(speed_mean=self.start, speed_variance=0., speed2=self.start**2, + pitch_mean=self.pitch, pitch_variance=0., parallel_mean=self.start*self.pitch, + parallel_variance=0., spatial_integral=0.) + return {name: np.where(t == 0, initial[name], value) for name, value in result.items()} + + def speed_cdf(self, time): + if time <= 0: + return lambda r: (np.asarray(r) >= self.start).astype(float) + values, vectors, initial = self.spectrum(0) + probability = self.root_mass*(vectors@(np.exp(time*values)*initial)) + if probability.min() < -1e-10 or abs(probability.sum()-1) > 1e-8: + raise RuntimeError("invalid thermal-reference probability") + cdf = np.r_[0., np.cumsum(np.maximum(probability, 0.))] + cdf /= cdf[-1] + return lambda r: np.interp(r, self.edges, cdf, left=0., right=1.) + + def pitch_cdf(self, time, *, harmonics=16): + """Finite-time angular marginal; compare harmonic truncations.""" + from scipy.special import eval_legendre + angular = [float(eval_legendre(ell, self.pitch)*self.expectation(time, 1., ell)) + for ell in range(1, harmonics+1)] + def cdf(xi): + x = np.clip(np.asarray(xi), -1., 1.) + result = (x+1)/2 + for ell, a in enumerate(angular, 1): + result = result+.5*a*(eval_legendre(ell+1, x)-eval_legendre(ell-1, x)) + return result + return cdf + + def equilibrium(self): + return dict(speed_mean=float(maxwell.expect(lambda r: r, lb=self.lower, ub=self.upper, conditional=True)), + speed_variance=float(maxwell.expect(lambda r: r*r, lb=self.lower, ub=self.upper, conditional=True) + -maxwell.expect(lambda r: r, lb=self.lower, ub=self.upper, conditional=True)**2), + pitch_mean=0., pitch_variance=1/3) + + +def physical_coefficients(r, coulomb_log_model="nrl"): + """Production-law coefficients evaluated independently in NumPy.""" + from .nonrelativistic_collision_reference import ProtonBackground + p = ProtonBackground(coulomb_log_model=coulomb_log_model) + r = np.asarray(r) + c = p.coefficients(p.sigma*r) + dp = c["parallel"]/(p.sigma**2*p.nu) + dt = c["perpendicular"]/(p.sigma**2*p.nu) + return dp, dt, 2*dt/r**2 + + +def impact_coefficients(r): + """Smooth effective-speed cutoff law; exact Maxwell stationary weight.""" + return physical_coefficients(r, "impact") + + +@dataclass +class PhysicalRelaxationReference(RelaxationReference): + """Explicit-drift reference for ESSOS's piecewise Coulomb logarithm. + + A central-difference backward Ito generator handles the log's branch jump + without assuming Maxwell detailed balance across that interface. Its + reversible discrete weights follow from its birth/death rates. A separate + analytic stationary-density calculation checks the interface behaviour. + """ + law: object = physical_coefficients + + def __post_init__(self): + from .nonrelativistic_collision_reference import ProtonBackground + super().__post_init__() + p = ProtonBackground() + c = p.coefficients(p.sigma*self.grid) + d = c["parallel"]/(p.sigma**2*p.nu) + a = c["speed_drift"]/(p.sigma*p.nu) + dr = self.edges[1]-self.edges[0] + self.low = d/dr**2-a/(2*dr) + self.high = d/dr**2+a/(2*dr) + self.low[0] = self.high[-1] = 0. + if np.any(self.low[1:] <= 0) or np.any(self.high[:-1] <= 0): + raise ValueError("physical drift requires a finer radial mesh") + log_mass = np.r_[0., np.cumsum(np.log(self.high[:-1])-np.log(self.low[1:]))] + self.mass = np.exp(log_mass-log_mass.max()) + self.mass /= self.mass.sum() + self.root_mass = np.sqrt(self.mass) + self.diagonal = -(self.low+self.high) + self.off = np.sqrt(self.high[:-1]*self.low[1:]) + self._spectra = {} + + def equilibrium(self): + """Stationary Ito density, including the Coulomb-log branch jump. + + Within each branch rho is Maxwell. At a finite diffusion jump, D*rho + is continuous for the ordinary Ito SDE with finite piecewise drift. + Thus its stationary density has an inverse diffusion-jump factor. + """ + from .nonrelativistic_collision_reference import ProtonBackground + p = ProtonBackground() + switch = np.sqrt(3.) + eps = 1e-9 + jump = float(p.coefficients(p.sigma*switch*(1+eps))["parallel"]/ + p.coefficients(p.sigma*switch*(1-eps))["parallel"]) + normalizer = (maxwell.cdf(switch)-maxwell.cdf(self.lower) + +(maxwell.sf(switch)-maxwell.sf(self.upper))/jump) + raw = [(maxwell.expect(lambda r: r**k, lb=self.lower, ub=switch) + +maxwell.expect(lambda r: r**k, lb=switch, ub=self.upper)/jump)/normalizer for k in (1, 2)] + return dict(speed_mean=float(raw[0]), speed_variance=float(raw[1]-raw[0]**2), + pitch_mean=0., pitch_variance=1/3) diff --git a/examples/benchmarks/validate_beam_relaxation.py b/examples/benchmarks/validate_beam_relaxation.py new file mode 100644 index 00000000..cb6ed1d2 --- /dev/null +++ b/examples/benchmarks/validate_beam_relaxation.py @@ -0,0 +1,300 @@ +"""Validate hot-beam relaxation and unabsorbed GC spatial diffusion. + +Run up to 2,000 independent particles per configuration, one execution only, +using native fixed/conservative stepping at two caps. This declared fixed- +Coulomb-log control has exact Maxwell equilibrium; ``--coefficient-model +physical`` uses the production speed-dependent coefficients and an independent +explicit-drift reference. Both predict the transient, not merely equilibrium. +""" +import argparse +import csv +import hashlib +import json +import os +from pathlib import Path + +os.environ.setdefault("ESSOS_PROGRESS", "0") +os.environ.setdefault("ESSOS_XLA_CACHE", "") +os.environ.setdefault("MPLBACKEND", "Agg") + +import jax +import jax.numpy as jnp +import numpy as np +from scipy.stats import kstest, norm, t as student_t + +from .thermal_relaxation_reference import RelaxationReference, PhysicalRelaxationReference, impact_coefficients +from .validate_collision_physics import thermal_solver, run_batches, work +from .analyze_collisional_convergence import conditional_spatial_statistics +from .collision_plotting import presentation, series, histogram, save + + +def estimate(values, expected, *, variance=False): + x = np.asarray(values, float) + n = len(x) + if variance: + influence = n/(n-1)*(x-x.mean())**2 + value = x.var(ddof=1) + else: + influence, value = x, x.mean() + se = influence.std(ddof=1)/np.sqrt(n) + half = student_t.ppf(.975, n-1)*se + return dict(value=float(value), reference=float(expected), difference=float(value-expected), + se=float(se), half95=float(half), z=float((value-expected)/se) if se > 1e-14 else None) + + +def statistics(r, xi, reference): + return dict(speed_mean=estimate(r, reference["speed_mean"]), + speed_variance=estimate(r, reference["speed_variance"], variance=True), + speed2=estimate(r*r, reference["speed2"]), + pitch_mean=estimate(xi, reference["pitch_mean"]), + pitch_variance=estimate(xi, reference["pitch_variance"], variance=True), + parallel_mean=estimate(r*xi, reference["parallel_mean"]), + parallel_variance=estimate(r*xi, reference["parallel_variance"], variance=True)) + + +def physical_native_coefficients(coulomb_log_model="nrl"): + from essos.background_species import BackgroundSpecies + from essos.split import collision_coefficients, CollisionCoefficients + from essos.constants import PROTON_MASS, ELEMENTARY_CHARGE + from .nonrelativistic_collision_reference import ProtonBackground + p = ProtonBackground(coulomb_log_model=coulomb_log_model) + species = BackgroundSpecies(1, jnp.array([1.]), jnp.array([1.]), jnp.array([p.density]), jnp.array([p.temperature_ev]), + coulomb_log_model=coulomb_log_model) + def law(r, *, full_orbit=False): + c = collision_coefficients(species, PROTON_MASS, ELEMENTARY_CHARGE, p.sigma*r, jnp.zeros(3), full_orbit=full_orbit) + return CollisionCoefficients(c.parallel/(p.sigma**2*p.nu), c.perpendicular/(p.sigma**2*p.nu), + c.parallel_derivative/(p.sigma*p.nu), c.friction/(p.sigma*p.nu), + c.friction_derivative/p.nu, c.particle_drift_derivative/p.nu) + return law + + +def prepare_references(times, coefficient_model="constant_log"): + references, checks = {}, {} + for model in ("gc", "lorentz"): + lower = .05*np.sqrt(2.) if model == "gc" else 0. + cls = PhysicalRelaxationReference if coefficient_model == "physical" else RelaxationReference + kwargs = dict(law=impact_coefficients) if coefficient_model == "impact" else {} + coarse = cls(lower=lower, nodes=512, **kwargs) + fine = cls(lower=lower, nodes=1024, **kwargs) + upper = cls(lower=lower, upper=10., nodes=1280, **kwargs) + a, b, c = (ref.moments(times) for ref in (coarse, fine, upper)) + changes = {} + for name in b: + scale = max(1., np.max(np.abs(b[name]))) + changes[name] = dict(mesh=float(np.max(abs(a[name]-b[name]))/scale), + upper=float(np.max(abs(c[name]-b[name]))/scale)) + grid = np.linspace(-1., 1., 201) + pitch8 = fine.pitch_cdf(times[-1], harmonics=8) + pitch12 = fine.pitch_cdf(times[-1], harmonics=12) + angular_error = float(np.max(abs(pitch8(grid)-pitch12(grid)))) + maximum = max(v[k] for v in changes.values() for k in ("mesh", "upper")) + if maximum > 3e-4 or angular_error > 1e-6: + raise RuntimeError(f"reference refinement failed: {model}, {changes}, angular={angular_error}") + references[model] = (fine, b, pitch12) + checks[model] = dict(changes=changes, max_scaled_change=maximum, pitch_harmonic_change=angular_error, + equilibrium=fine.equilibrium(), maxwell_equilibrium=RelaxationReference(lower=lower, nodes=32).equilibrium(), + transient={name: value.tolist() for name, value in b.items()}) + speed_edges, pitch_edges = np.linspace(0., 6., 37), np.linspace(-1., 1., 25) + checks[model]["distribution"] = dict(speed_edges=speed_edges.tolist(), pitch_edges=pitch_edges.tolist(), + speed_density=(np.diff(fine.speed_cdf(times[-1])(speed_edges))/np.diff(speed_edges)).tolist(), + pitch_density=(np.diff(pitch12(pitch_edges))/np.diff(pitch_edges)).tolist()) + print(f"{model} reference: maximum scaled refinement change {maximum:.3g}", flush=True) + return references, checks + + +@presentation +def plot(report, output): + import matplotlib.pyplot as plt + times=np.asarray(report["metadata"]["times"]);meta=report["metadata"] + panels=(("speed",r"v/\sigma_T"),("pitch",r"\xi"),("parallel",r"v_\parallel/\sigma_T")) + for model in ("gc","lorentz"): + ref=report["references"][model] + rows=[r for r in report["rows"] if r["model"]==model] + selected=[r for r in rows if r["setting"]=="fine"] or rows + fig,axes=plt.subplots(2,3,figsize=(15,7),layout="constrained") + for j,(variable,symbol) in enumerate(panels): + for i,stat in enumerate(("mean","variance")): + ax=axes[i,j];name=variable+"_"+stat + for k,row in enumerate(selected): + series(ax,times,[s[name]["value"] for s in row["evolution"]],[s[name]["half95"] for s in row["evolution"]], + std=i==1,label=model.upper(),color=f"C{k}") + series(ax,times,ref["transient"][name],std=i==1,reference=True,label="Independent theory") + ax.set(title=r"$\langle "+symbol+r"\rangle$" if i==0 else r"$\sigma("+symbol+r")$",xlabel=r"$t\nu_0$") + axes[0,0].legend() + fig.suptitle(f"{model.upper()} · Thermalization · N={meta['particles']:,}") + save(fig,output.with_name(output.stem+"_"+model)) + # Keep the unabsorbed spatial-diffusion diagnostic. + fig,axes=plt.subplots(1,3,figsize=(16,4.5),layout="constrained") + ref=np.asarray(report["references"]["gc"]["transient"]["spatial_integral"]) + for row in report["rows"]: + if row["model"]!="gc":continue + for ax,name in zip(axes[:2],("spatial_integral","displacement2")): + series(ax,times,[s[name]["value"] for s in row["spatial"]],[s[name]["half95"] for s in row["spatial"]], + label=row["method"]+" / "+row["setting"]) + if row["setting"]=="fine": + axes[2].plot(times,[s.get("noise",{}).get("mean",1.) for s in row["spatial"]],label=row["method"]) + for ax,title in zip(axes[:2],("Accumulated diffusion","Spatial spreading")): + series(ax,times,ref,reference=True,label="Independent theory") + ax.set(title=title,xlabel=r"$t\nu_0$",ylabel=r"$\langle R_\bot^2\rangle/\rho_\sigma^2$") + half=1.96/np.sqrt(meta["particles"]) + axes[2].axhspan(1-half,1+half,color=".8",alpha=.3) + axes[2].axhline(1.,color="k",ls="--");axes[2].set(title="Conditional-noise mean",xlabel=r"$t\nu_0$") + axes[0].legend();save(fig,output.with_name(output.stem+"_spatial")) + if not all("distribution" in report["references"][model] for model in ("gc","lorentz")):return + fig,axes=plt.subplots(2,2,figsize=(13,9),layout="constrained") + for i,model in enumerate(("gc","lorentz")): + ref=report["references"][model]["distribution"] + row=min((r for r in report["rows"] if r["model"]==model),key=lambda r:(r["method"]=="fixed",r["cap"])) + # Raw samples allow finer bins, evaluated against the same independent generator. + family=meta.get("coefficient_model","constant_log") + cls=PhysicalRelaxationReference if family=="physical" else RelaxationReference + reference=cls(lower=.05*np.sqrt(2.) if model=="gc" else 0.,nodes=1024, + **(dict(law=impact_coefficients) if family=="impact" else {})) + for j,name in enumerate(("speed","pitch")): + ax=axes[i,j];edges=np.asarray(ref[name+"_edges"]) + if "histograms" in row: + counts=np.asarray(row["histograms"][name]["counts"]);count=row["histograms"][name]["particles"] + density=np.asarray(ref[name+"_density"]) + else: + samples=row["final_"+name];edges=np.linspace(0.,6.,61) if name=="speed" else np.linspace(-1.,1.,51) + counts=np.histogram(samples,edges)[0];count=len(samples) + cdf=reference.speed_cdf(times[-1]) if name=="speed" else reference.pitch_cdf(times[-1],harmonics=12) + density=np.diff(cdf(edges))/np.diff(edges) + grid=np.linspace(edges[0],edges[-1],501) + cdf=reference.speed_cdf(times[-1]) if name=="speed" else reference.pitch_cdf(times[-1],harmonics=12) + histogram(ax,edges,counts,density,particles=count,initial=meta.get("initial_"+name,np.sqrt(10.) if name=="speed" else .6), + curve=(grid,np.gradient(cdf(grid),grid))) + ax.set(title=model.upper()+": "+("Speed distribution" if name=="speed" else "Pitch distribution"), + xlabel=r"$v/\sigma_T$" if name=="speed" else r"$\xi$") + ax.legend(fontsize=10) + if name=="pitch":ax.set_ylim(top=max(counts)*1.4) + fig.suptitle(f"Thermalized distributions · N={meta['particles']:,} · "+r"$t\nu_0=$"+f"{times[-1]:g}") + save(fig,output.with_name(output.stem+"_distribution")) + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--output", type=Path, required=True) + parser.add_argument("--particles", type=int, default=2000) + parser.add_argument("--batch-size", type=int, default=50) + parser.add_argument("--horizon", type=float, default=20.) + parser.add_argument("--seed", type=int, default=6706) + parser.add_argument("--caps", type=float, nargs=2, default=[.0025, .000625]) + parser.add_argument("--coefficient-model", choices=("constant_log", "physical", "impact"), default="constant_log") + parser.add_argument("--methods", choices=("fixed", "conservative"), nargs="+", default=["fixed", "conservative"]) + parser.add_argument("--settings", choices=("coarse", "fine"), nargs="+", default=["coarse", "fine"]) + parser.add_argument("--resume", action="store_true") + parser.add_argument("--plot-only", action="store_true") + args = parser.parse_args() + if args.plot_only: + plot(json.loads(args.output.read_text()), args.output) + return + n, batch_size = args.particles, args.batch_size + if not 2 <= n <= 2000 or not 2 <= batch_size <= n or n % batch_size: + parser.error("use at most 2000 particles and a dividing batch size") + if not np.isfinite(args.horizon) or args.horizon <= 0 or not all(np.isfinite(h) and h > 0 for h in args.caps) or args.caps[0] <= args.caps[1]: + parser.error("positive horizon and coarse>fine>0 caps required") + times = np.linspace(0., args.horizon, 41) + metadata = dict(particles=n, batch_size=batch_size, seed=args.seed, times=times.tolist(), caps=args.caps, + collision_tolerance=.001, initial_speed=float(np.sqrt(10.)), initial_pitch=.6, + coefficient_model=args.coefficient_model, methods=args.methods, settings=args.settings, + scope="Native collision-only relaxation from a monoenergetic anisotropic beam; declared coefficient law; no source or stopping", + uncertainty="Independent particles; configurations share ordered keys, not exact Brownian paths; time samples are not pooled") + report = dict(complete=False, metadata=metadata, rows=[]) + if args.output.exists(): + if not args.resume: + raise ValueError("output exists; use --resume or a new path") + report = json.loads(args.output.read_text()) + if "coefficient_model" not in report["metadata"]: + # Completed early control files predate the explicit family flags. + report["metadata"].update(coefficient_model="constant_log", methods=["fixed", "conservative"], settings=["coarse", "fine"], + scope=metadata["scope"]) + if report["metadata"] != metadata: + raise ValueError("resume metadata differs") + report["complete"] = False + args.output.parent.mkdir(parents=True, exist_ok=True) + def save(): + args.output.write_text(json.dumps(report, indent=2)+"\n") + references, report["references"] = prepare_references(times, args.coefficient_model) + save() + keys = jax.vmap(lambda i: jax.random.fold_in(jax.random.key(args.seed), i))(jnp.arange(n)).reshape((-1, batch_size)) + completed = {r["id"] for r in report["rows"]} + cdf_alpha = .01/(2*2*len(args.methods)*len(args.settings)) + limit = float(np.sqrt(np.log(2/cdf_alpha)/(2*n))) + for model in ("gc", "lorentz"): + ref, expected, pitch_cdf = references[model] + initial = ([0., 0., 0., np.sqrt(10.), .6, 0.] if model == "gc" else [np.sqrt(10.)*.8, 0., np.sqrt(10.)*.6]) + initial = jnp.broadcast_to(jnp.asarray(initial), (n, len(initial))).reshape((-1, batch_size, len(initial))) + for method in args.methods: + pending = [(setting, cap) for setting, cap in zip(("coarse", "fine"), args.caps) + if setting in args.settings and f"{model}/{method}/{setting}" not in completed] + if not pending: + continue + kwargs = (dict(coefficient_law=physical_native_coefficients("impact" if args.coefficient_model == "impact" else "nrl")) + if args.coefficient_model != "constant_log" else {}) + function = thermal_solver(model, method, args.horizon, times, **kwargs) + parameters = tuple(map(jnp.asarray, (.001, pending[0][1], pending[0][1]))) + executable = function.lower(initial[0], keys[0], *parameters).compile() + for setting, cap in pending: + identifier = f"{model}/{method}/{setting}" + print(f"Running {identifier}: N={n}, horizon={args.horizon}, cap={cap}", flush=True) + output, elapsed = run_batches(executable, list(zip(initial, keys)), tuple(map(jnp.asarray, (.001, cap, cap)))) + if np.any(output.status != 0): + raise RuntimeError("all unabsorbed thermal particles must reach the fixed horizon") + if method != "fixed" and output.stats.max_accepted_error.max() > 1: + raise RuntimeError("an accepted adaptive collision error exceeds one") + r = output.ys[:, :, 3] if model == "gc" else np.linalg.norm(output.ys, axis=-1) + xi = output.ys[:, :, 4] if model == "gc" else output.ys[:, :, 2]/r + row = dict(id=identifier, model=model, method=method, setting=setting, cap=cap, + elapsed_seconds=elapsed, **work(output), + evolution=[statistics(r[:, i], xi[:, i], {k: v[i] for k, v in expected.items()}) for i in range(len(times))], + final_speed=r[:, -1].tolist(), final_pitch=xi[:, -1].tolist(), cdf={}) + for name, values, cdf in (("speed", r[:, -1], ref.speed_cdf(args.horizon)), ("pitch", xi[:, -1], pitch_cdf)): + check = kstest(values, cdf) + row["cdf"][name] = dict(distance=float(check.statistic), pvalue=float(check.pvalue), + familywise_limit=limit, within_limit=bool(check.statistic <= limit)) + if model == "gc": + row["spatial"] = [] + for i, t in enumerate(times): + q, msd = output.ys[:, i, 5], np.sum(output.ys[:, i, :2]**2, axis=1) + value = dict(spatial_integral=estimate(q, expected["spatial_integral"][i]), + displacement2=estimate(msd, expected["spatial_integral"][i])) + if t: + value["noise"] = {k: v for k, v in conditional_spatial_statistics(msd, q).items() if k != "ratio"} + row["spatial"].append(value) + report["rows"].append(row) + completed.add(identifier) + save() + print(json.dumps(dict(id=identifier, elapsed=elapsed, + final_moments={k: dict(difference=v["difference"], z=v["z"]) for k, v in row["evolution"][-1].items()}, cdf=row["cdf"])), flush=True) + screens = [] + count = len(report["rows"])*(len(times)-1)*7 + critical = float(norm.ppf(1-.01/(2*count))) + for row in report["rows"]: + deviations = [(abs(value["z"]), float(t), name) for t, sample in zip(times[1:], row["evolution"][1:]) + for name, value in sample.items() if value["z"] is not None] + worst = max(deviations) + screens.append(dict(id=row["id"], maximum_abs_z=worst[0], time=worst[1], quantity=worst[2], + critical=critical, within_familywise_screen=bool(worst[0] <= critical))) + report["moment_screens"] = screens + root = Path(__file__).resolve().parents[2] + report["source_sha256"] = {name: hashlib.sha256((root/name).read_bytes()).hexdigest() for name in ( + "examples/benchmarks/validate_beam_relaxation.py", "examples/benchmarks/thermal_relaxation_reference.py", + "examples/benchmarks/validate_collision_physics.py", "essos/split.py", + "essos/background_species.py", + "examples/benchmarks/nonrelativistic_collision_reference.py")} + report["interpretation"] = "CDF and moment screens test statistical consistency, not a numerical-accuracy bound; compare both caps and report achieved uncertainty." + report["complete"] = True + save() + table = [dict(id=row["id"], time=float(t), quantity=name, **value) + for row in report["rows"] for t, sample in zip(times, row["evolution"]) for name, value in sample.items()] + with args.output.with_suffix(".csv").open("w", newline="") as stream: + writer = csv.DictWriter(stream, fieldnames=list(table[0])) + writer.writeheader() + writer.writerows(table) + plot(report, args.output) + print(json.dumps(dict(complete=True, moment_screens=screens)), flush=True) + + +if __name__ == "__main__": + main() diff --git a/examples/benchmarks/validate_collision_physics.py b/examples/benchmarks/validate_collision_physics.py new file mode 100644 index 00000000..4b0d6e42 --- /dev/null +++ b/examples/benchmarks/validate_collision_physics.py @@ -0,0 +1,65 @@ +"""Shared physics helpers using the production collision maps and Brownian driver.""" +from time import perf_counter +import jax +import jax.numpy as jnp +import numpy as np +from essos.background_species import chandrasekhar, d_chandrasekhar +from essos.split import CollisionCoefficients, guiding_center_collision_step, particle_collision_step, guiding_center_spatial_diffusion, guiding_center_spatial_increment +from essos.split import solve_split + +def constant_log_coefficients(speed, *, full_orbit=False): + """Nonrelativistic equal-proton Maxwellian coefficients with fixed ln Lambda. + + Velocity is in sigma=sqrt(T/m); time is in 1/nu_s(sigma). Spatial units + are rho_sigma. This control leaves the production coefficients untouched. + """ + normalizer = chandrasekhar(jnp.asarray(1 / np.sqrt(2.0))) + + def values(v): + x = v / jnp.sqrt(2.0) + g = chandrasekhar(x) + dp = g / (v * normalizer) + dt = (jax.scipy.special.erf(x) - g) / (2 * v * normalizer) + ddp = (d_chandrasekhar(x) / (jnp.sqrt(2.0) * v) - g / v ** 2) / normalizer + return jnp.array([dp, dt, ddp, -v * dp]) + value, slope = jax.jvp(values, (speed,), (jnp.ones_like(speed),)) + dp, dt, ddp, q = value + dk = slope[3] + slope[2] + 2 * (slope[0] - slope[1]) / speed - 2 * (dp - dt) / speed ** 2 if full_orbit else jnp.zeros_like(speed) + return CollisionCoefficients(dp, dt, ddp, q, slope[3], dk) + +def thermal_solver(model, method, horizon, times, *, coefficient_law=constant_log_coefficients): + """Use the actual native collision maps and driver for the analytic control.""" + gc, adaptive = (model == 'gc', method != 'fixed') + controller = method if adaptive else 'conservative' + + def batch(initial, keys, tolerance, cap, first): + + def one(y0, key): + + def kick(t, y, h, dw, args): + speed = y[3] if gc else jnp.linalg.norm(y) + c = coefficient_law(speed, full_orbit=not gc) + kwargs = dict(tolerance=tolerance, return_error_model=adaptive and controller == 'candidate') + if gc: + trial = guiding_center_collision_step(speed, y[4], h, dw[-2:], c, speed_floor=0.05 * np.sqrt(2.0), **kwargs) + dx = guiding_center_spatial_increment(y[4], dw[:3], c, jnp.array([0.0, 0.0, 1.0]), 1.0) + value = y.at[:3].add(dx).at[3:5].set(trial.y) + value = value.at[5].add(4 * guiding_center_spatial_diffusion(y[4], c, 1.0) * h) + return trial._replace(y=value) + return particle_collision_step(y, h, dw, c, **kwargs) + return solve_split(lambda t, y, a: jnp.zeros_like(y), kick, y0, t1=horizon, dt0=first, dtmax=cap, ts=jnp.asarray(times), key=key, noise_dim=5 if gc else 3, adaptive=adaptive, collision_controller=controller, collision_wiener_norm=(lambda w: jnp.linalg.norm(w[-2:])) if gc else lambda w: abs(w[2]), method='dopri5', max_steps=100000) + return jax.vmap(one)(initial, keys) + return jax.jit(batch) + +def run_batches(executable, batches, parameters): + outputs = [] + start = perf_counter() + for inputs in batches: + outputs.append(jax.device_get(jax.block_until_ready(executable(*inputs, *parameters)))) + output = jax.tree.map(lambda *x: np.concatenate(x, axis=0), *outputs) + if np.any((output.status != 0) & (output.status != 1)): + raise RuntimeError(f'invalid physical solve: {np.unique(output.status, return_counts=True)}') + return (output, perf_counter() - start) + +def work(output): + return dict(accepted_mean=float(output.stats.accepted.mean()), rejected_mean=float(output.stats.rejected.mean()), trials_mean=float(output.stats.steps.mean()), max_accepted_error=float(output.stats.max_accepted_error.max()), peak_pending=int(output.stats.peak_pending.max())) diff --git a/examples/benchmarks/validate_collisional_slowing_down.py b/examples/benchmarks/validate_collisional_slowing_down.py new file mode 100644 index 00000000..44d5e1ab --- /dev/null +++ b/examples/benchmarks/validate_collisional_slowing_down.py @@ -0,0 +1,99 @@ +"""Production first-passage diagnostic used by validate_production_tolerance.""" +import jax +import jax.numpy as jnp +import numpy as np +from essos.background_species import BackgroundSpecies +from essos.constants import PROTON_MASS as M,ELEMENTARY_CHARGE as Q +from essos.split import (solve_split,collision_coefficients,guiding_center_collision_step,particle_collision_step, + guiding_center_spatial_diffusion,guiding_center_spatial_increment) +from .collision_event_diagnostic import boundary_step_limit + + +def native_solver(model, controller, adaptive, physical, horizon, threshold, *, + spatial=False, times=None, magnetic_field=1., boundary_shift=False, + event_interval=None, event_safety=.2, record_steps=False): + """Native benchmark, optionally testing a discrete-exit boundary correction. + + ``boundary_shift`` tests the Gobet--Menozzi shift at each actual step h; + it is not enabled in production tracing. The event flag is auxiliary and + does not enter the velocity/spatial update or the local error estimates. + ``event_interval`` enables boundary-aware stepping and refinement of + detected crossing intervals. It is in collision-time units (h*nu0), + independently of the collision tolerance. No boundary shift is needed. + """ + if spatial and model != "gc": + raise ValueError("explicit spatial kicks require the GC model") + if event_interval is not None: + if not np.isfinite(event_interval) or event_interval <= 0 or not np.isfinite(threshold) or threshold <= 0: + raise ValueError("event_interval and the thermal threshold must be positive and finite") + if not np.isfinite(event_safety) or not 0 < event_safety < 1: + raise ValueError("event_safety must lie strictly between zero and one") + if boundary_shift: + raise ValueError("compare event refinement and the experimental shift separately") + species = BackgroundSpecies(1, jnp.array([1.]), jnp.array([1.]), + jnp.array([physical.density]), jnp.array([physical.temperature_ev]), + coulomb_log_model=physical.coulomb_log_model) + gc = model == "gc" + v0 = physical.sigma*np.sqrt(10.) + y0 = jnp.array([v0, .6]) if gc else jnp.array([.8*v0, 0., .6*v0]) + if spatial: + # Position, speed, pitch, accumulated 4*D_X*dt. All units are SI. + y0 = jnp.array([0., 0., 0., v0, .6, 0.]) + physical_size = y0.size + if boundary_shift: + y0 = jnp.append(y0, v0/physical.sigma-threshold) + boundary_diffusion = float(physical.coefficients(threshold*physical.sigma)["parallel"]) + nu = physical.nu + save_times = jnp.empty((0,)) if times is None else jnp.asarray(times)/nu + if times is not None: + # JAX division may use a reciprocal multiplication, differing from + # Python's horizon/nu by one ulp. A save at the requested horizon must + # use the exact same SI endpoint as t1, rather than be rejected as >t1. + save_times = jnp.where(jnp.asarray(times) == horizon, jnp.asarray(horizon/nu), save_times) + + def batch(keys, tolerance, cap, initial): + def one(key): + def event_limit(t, y, args): + speed = y[3] if spatial else (y[0] if gc else jnp.linalg.norm(y)) + c = collision_coefficients(species, M, Q, speed, jnp.zeros(3)) + drift = c.friction+c.parallel_derivative+2*c.parallel/speed + return boundary_step_limit(speed, threshold*physical.sigma, c.parallel, + drift, event_interval/nu, safety=event_safety) + + def kick(t, y, h, dw, args): + y = y[:physical_size] + speed = y[3] if spatial else (y[0] if gc else jnp.linalg.norm(y)) + pitch = y[4] if spatial else y[1] + c = collision_coefficients(species, M, Q, speed, jnp.zeros(3), full_orbit=not gc) + kwargs = dict(tolerance=tolerance, return_error_model=adaptive and controller == "candidate") + # Keep driver, Wiener increments and candidate-error metadata + # in SI units. Only reporting converts to collision time. + result = (guiding_center_collision_step(speed, pitch, h, dw[-2:], c, + speed_floor=.05*np.sqrt(2)*physical.sigma, **kwargs) if gc else + particle_collision_step(y, h, dw, c, **kwargs)) + if spatial: + omega = Q*magnetic_field/M + displacement = guiding_center_spatial_increment(pitch, dw[:3], c, jnp.array([0., 0., 1.]), omega) + value = y.at[:3].add(displacement).at[3:5].set(result.y) + value = value.at[5].add(4*guiding_center_spatial_diffusion(pitch, c, omega)*h) + result = result._replace(y=value) + if boundary_shift: + value = result.y + next_speed = value[3] if spatial else (value[0] if gc else jnp.linalg.norm(value)) + level = (next_speed-threshold*physical.sigma + -.5825971579390108*jnp.sqrt(2*boundary_diffusion*h))/physical.sigma + result = result._replace(y=jnp.append(value, level)) + return result + return solve_split(lambda t, y, args: jnp.zeros_like(y), kick, y0, + t1=horizon/nu, dt0=initial/nu, dtmax=cap/nu, ts=save_times, + key=key, noise_dim=(5 if spatial else 2) if gc else 3, method="dopri5", adaptive=adaptive, + collision_controller=controller, + collision_wiener_norm=(lambda w: jnp.linalg.norm(w[-2:])) if gc else (lambda w: jnp.abs(w[2])), + event=lambda t, y, args: y[-1] if boundary_shift else + (y[3] if spatial else (y[0] if gc else jnp.linalg.norm(y)))/physical.sigma-threshold, + max_steps=100_000, record_steps=record_steps, + step_limit=event_limit if event_interval is not None else None, + event_dtmax=None if event_interval is None else event_interval/nu) + out = jax.vmap(one)(keys) + return out._replace(t=out.t*nu) + return jax.jit(batch) diff --git a/examples/benchmarks/validate_production_tolerance.py b/examples/benchmarks/validate_production_tolerance.py new file mode 100644 index 00000000..d76fe52a --- /dev/null +++ b/examples/benchmarks/validate_production_tolerance.py @@ -0,0 +1,119 @@ +"""Source-free first stopping with production collision maps and Brownian memory. + +Fresh fixed/base/tight ensembles use the same cap and event resolution. Keys +are repeatable; different adaptive meshes need not produce common paths. +Reports retain CDF/histogram and moment summaries, not raw particle histories. +""" +import argparse +import hashlib +import json +from pathlib import Path +import jax +import jax.numpy as jnp +import numpy as np +from .nonrelativistic_collision_reference import ProtonBackground, proton_first_passage, passage_statistics +from .validate_collisional_slowing_down import native_solver +from .validate_collision_physics import run_batches, work +from .validate_beam_relaxation import estimate +from .collision_plotting import presentation, histogram, save + + +@presentation +def plot(report, reference, output): + import matplotlib.pyplot as plt + meta=report["metadata"] + edges=np.asarray(report["plot_reference"]["histogram_edges"]) + density=np.diff(reference.cdf(edges))/np.diff(edges) + fig,axes=plt.subplots(1,2,figsize=(13,4.8),layout="constrained") + for ax,model in zip(axes,("gc","lorentz")): + row=min((r for r in report["rows"] if r["model"]==model), + key=lambda r:(r["method"]=="fixed",r["tolerance"] if r["tolerance"] is not None else np.inf)) + counts=np.asarray(row["plot"]["histogram_density"])*meta["particles"]*np.diff(edges) + grid=np.linspace(0.,edges[-1],1001) + histogram(ax,edges,counts,density,particles=meta["particles"],curve=(grid,np.gradient(reference.cdf(grid),grid))) + ax.set(title=model.upper()+": first-stopping distribution",xlabel=r"$\tau\nu_0$",xlim=(0.,edges[-1])) + ax.legend() + fig.suptitle(f"First crossing from 5T to 2T · N={meta['particles']:,}") + save(fig,output.with_name(output.stem+"_distribution")) + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--output", type=Path, required=True) + parser.add_argument("--particles", type=int, default=32) + parser.add_argument("--batch-size", type=int, default=16) + parser.add_argument("--seed", type=int, default=3706) + parser.add_argument("--cap", type=float, default=.00078125) + parser.add_argument("--base-tolerance", type=float, default=.001) + parser.add_argument("--tight-tolerance", type=float, default=.00025) + parser.add_argument("--horizon", type=float, default=40.) + parser.add_argument("--event-interval", type=float, default=1.220703125e-5) + parser.add_argument("--plot-only", action="store_true") + args = parser.parse_args() + p = ProtonBackground(coulomb_log_model="impact") + reference = proton_first_passage(p, nodes=1536) + if args.plot_only: + report = json.loads(args.output.read_text()) + if not report.get("complete"): parser.error("plot-only requires a complete report") + plot(report, reference, args.output) + return + n, batch = args.particles, args.batch_size + if not 2 <= n <= 2000 or not 2 <= batch <= n or n % batch: + parser.error("use 2..2000 particles and a dividing batch size >=2") + values = (args.cap, args.base_tolerance, args.tight_tolerance, args.horizon, args.event_interval) + if not all(np.isfinite(x) and x > 0 for x in values) or args.tight_tolerance >= args.base_tolerance: + parser.error("require positive finite parameters and tight tolerance < base tolerance") + if args.output.exists(): parser.error("use a fresh output path") + times = np.r_[np.linspace(0., min(10.370951771498717, args.horizon), 21), args.horizon] + times = np.unique(times) + grid = np.linspace(0., args.horizon, 201) + right = float(np.ceil(np.interp(.995, reference.cdf(grid), grid))) + edges = np.linspace(0., right, 46) + raw = reference.restricted_moments(args.horizon) + report = dict(complete=False, metadata=dict(particles=n, batch_size=batch, seed=args.seed, + backend=jax.default_backend(), jax_version=jax.__version__, cap=args.cap, horizon=args.horizon, + initial_step=args.cap, event_interval=args.event_interval, save_times=times.tolist(), + base_tolerance=args.base_tolerance, tight_tolerance=args.tight_tolerance, + coulomb_log_model="impact", controller="conservative", orbit=False, + framework="native_solver -> solve_split -> production retained Brownian memory; SI coefficients", + uncertainty="Independent particles; marginal 95% intervals; common seeds do not imply identical Wiener paths"), + reference=dict(restricted_mean=float(raw[0]), restricted_variance=float(raw[1]-raw[0]**2)), + plot_reference=dict(times=grid.tolist(), cdf=reference.cdf(grid).tolist(), + histogram_edges=edges.tolist()), rows=[]) + root = Path(__file__).resolve().parents[2] + names = ("essos/split.py", "essos/background_species.py", + "examples/benchmarks/validate_production_tolerance.py", "examples/benchmarks/validate_collisional_slowing_down.py", + "examples/benchmarks/nonrelativistic_collision_reference.py") + report["source_sha256"] = {name: hashlib.sha256((root/name).read_bytes()).hexdigest() for name in names} + args.output.parent.mkdir(parents=True, exist_ok=True) + save = lambda: args.output.write_text(json.dumps(report, indent=2)+"\n") + keys = jax.vmap(lambda i: jax.random.fold_in(jax.random.key(args.seed), i))(jnp.arange(n)).reshape((-1, batch)) + for model in ("gc", "lorentz"): + for adaptive in (False, True): + function = native_solver(model, "conservative", adaptive, p, args.horizon, 2., + spatial=model=="gc", times=times, event_interval=args.event_interval) + parameters = tuple(map(jnp.asarray, (args.base_tolerance, args.cap, args.cap))) + executable = function.lower(keys[0], *parameters).compile() + tolerances = (args.base_tolerance, args.tight_tolerance) if adaptive else (args.base_tolerance,) + for tolerance in tolerances: + print(f"Running {model}: adaptive={adaptive}, tolerance={tolerance:g}, N={n}", flush=True) + parameters = tuple(map(jnp.asarray, (tolerance, args.cap, args.cap))) + out, elapsed = run_batches(executable, [(key,) for key in keys], parameters) + if np.any(out.status != 1): + raise RuntimeError("first-stopping plot requires complete uncensored trajectories; increase horizon") + if adaptive and np.max(out.stats.max_accepted_error) > 1: + raise RuntimeError("accepted collision estimate exceeds one") + samples = np.asarray(out.t) + row = dict(model=model, method="conservative" if adaptive else "fixed", + tolerance=tolerance if adaptive else None, elapsed_seconds=elapsed, **work(out), + mean=estimate(samples,float(raw[0])), variance=estimate(samples,float(raw[1]-raw[0]**2),variance=True), + statistics=passage_statistics(samples, out.status==1, reference, args.horizon, alpha=.01/6), + empirical_cdf=(np.searchsorted(np.sort(samples),grid,side="right")/n).tolist(), + plot=dict(histogram_density=(np.histogram(samples,edges)[0]/(n*np.diff(edges))).tolist(), + fraction_beyond_display=float(np.mean(samples>right)))) + report["rows"].append(row); save() + report["complete"] = True; save(); plot(report, reference, args.output) + print("Saved "+str(args.output), flush=True) + + +if __name__ == "__main__": main() diff --git a/examples/coil_optimization/native_gc_alm.py b/examples/coil_optimization/native_gc_alm.py new file mode 100644 index 00000000..0ad9e662 --- /dev/null +++ b/examples/coil_optimization/native_gc_alm.py @@ -0,0 +1,416 @@ +"""Shared QI ALM setup recovered from en/jax_13 (638916d). + +Three entry scripts select the particle constraint. The current ESSOS ALM +and accepted-map native reverse replace the historical optimizer/custom VJPs. +Imports never start tracing. All particles and random paths remain fixed. +""" +import argparse +import csv +import json +from functools import partial +from pathlib import Path +from time import perf_counter +from types import SimpleNamespace +import equinox as eqx +import jax +import jaxlib +import jax.numpy as jnp +import numpy as np +from essos import augmented_lagrangian as alm +from essos.coils import Coils +from essos.constants import (ALPHA_PARTICLE_MASS, ALPHA_PARTICLE_CHARGE, + FUSION_ALPHA_PARTICLE_ENERGY, ELECTRON_MASS, PROTON_MASS, ONE_EV) +from essos.dynamics import Particles, Tracing +from essos.fields import BiotSavart +from essos.particle_losses import (classifier_loss_fraction, classifier_line_loss, + classifier_energy_cost) +from essos.surfaces import SurfaceRZFourier, SurfaceClassifier +from essos.split import ClassifierStop +from essos.native_ad import gpu_jit_options +from essos.rk import _fourier_geometry,_coil_geometry,_coil_field_values +from .native_particle_optimization import save_optimization_plots + +INPUT = Path(__file__).resolve().parents[1]/"input_files" +DEFAULTS = dict( + coils=INPUT/"QI_opt_coils_essos_5.json", + wout=INPUT/"wout_QI_nfp2_stable_Er_006_000043_hires_scaled.nc", + particles=20, seed=42, birth_fraction=.7, energy_ev=FUSION_ALPHA_PARTICLE_ENERGY/ONE_EV, + horizon=1e-4, initial_step=1e-8, saves=10, rtol=1e-7, atol=1e-7, + checkpoint_steps=16, accepted_capacity=32768, max_steps=65536, + length_target=45., curvature_target=1., axis_field_target=5.7, + softness=30., location_softness=10., line_mode="fixed_theta", + line_theta=1.5*np.pi, line_phi=np.pi, bdotn_target=1e-3, bdotn_weight=0., + surface_points=60, classifier_h=.1, safety_margin=.2, birth_axis_samples=1000, + maxiter=100, inner_maxiter=50, max_change=.05, penalty=1., beta=1.01, + eta_tol=1e-5, omega_tol=1e-7, model_mu="Mu_Adaptative_2", + collisions=True, execution="auto", collision_step=1e-8, collision_dtmax=1e-6, + collision_capacity=4096, max_orbit_steps=4096, + collision_tolerance=.001, moment_tolerance=.01, collision_seed=42, + background_density=4.21e20, background_temperature_ev=17.8e3, + optimizer="optimistix", scipy_ftol=1e-12, + save_plots=True, output=Path("output/native_gc_alm")) + + +def surface_point(surface, theta, phi): + angle = surface.xm*theta-surface.xn*phi + radius, height = jnp.sum(surface.rc*jnp.cos(angle)), jnp.sum(surface.zs*jnp.sin(angle)) + return jnp.array([radius*jnp.cos(phi), radius*jnp.sin(phi), height]) + + +def boundary_line(surface, theta, phi, mode): + """Infinite tangent line at a fixed-theta or fixed-phi boundary curve.""" + if mode not in ("fixed_theta", "fixed_phi"): + raise ValueError("line_mode must be fixed_theta or fixed_phi") + angles = jnp.array([theta, phi]) + direction = jnp.array([0., 1.]) if mode == "fixed_theta" else jnp.array([1., 0.]) + point, tangent = jax.jvp(lambda a: surface_point(surface, *a), (angles,), (direction,)) + return point, tangent/jnp.linalg.norm(tangent) + + +def make_constraints(geometry, particle, options): + """Current alm.ineq uses g >= 0: upper limits are target minus value.""" + p = dict(penalty=options.penalty, omega=1/options.penalty, eta=1/options.penalty**.1) + constraints = [alm.eq(lambda x: geometry(x)["axis"], **p), + alm.ineq(lambda x: geometry(x)["length"], **p), + alm.ineq(lambda x: geometry(x)["curvature"], **p), alm.eq(particle, **p)] + if options.bdotn_weight: + constraints.append(alm.ineq(lambda x: geometry(x)["bdotn"], + weight=options.bdotn_weight, **p)) + return alm.combine(*constraints) + + +def compile_optimizer(optimizer,*,independent=True): + """Apply the split GPU capture policy to ALM's outer compiled functions.""" + options=gpu_jit_options() if independent else {} + if not options:return optimizer + update=optimizer.update + return optimizer._replace( + init=jax.jit(optimizer.init.__wrapped__,**options), + update=partial(jax.jit(update.func.__wrapped__,static_argnums=(4,5,6,7,8,9,10),**options), + *update.args,**update.keywords)) + + +def scipy_optimizer(constraints, options): + """Host L-BFGS-B, retaining ESSOS ALM constraints and multiplier updates. + + Only one native value/gradient executable is compiled. SciPy enforces the + same [-1, 1] scaled-DOF box directly, rather than through tanh coordinates. + Its inner gradient tolerance is omega_tol; ftol is independently selectable. + """ + import optax + from scipy.optimize import minimize + policy = gpu_jit_options() if options.collisions and options.execution != "shared" else {} + def lagrangian(x, lp): + value, violations = constraints.loss(lp, x) + return value, (jnp.zeros_like(value), value, violations) + value_grad = jax.jit(jax.value_and_grad(lagrangian, argnums=(0, 1), has_aux=True), **policy) + executable = None + statistics = dict(evaluations=0, compile_s=0., first_evaluation_s=0., inner_solves=[]) + + def evaluate(x, lp): + (value, info), gradient = jax.block_until_ready(executable(jnp.asarray(x), lp)) + if not np.isfinite(value) or not np.isfinite(gradient[0]).all(): + raise RuntimeError("nonfinite SciPy native value/gradient") + statistics["evaluations"] += 1 + return float(value), gradient, info + + def init(params): + nonlocal executable + start = perf_counter() + executable = value_grad.lower(*params).compile() + statistics["compile_s"] = perf_counter()-start + print(f"Native objective/gradient lowering+compilation: {statistics['compile_s']:.2f} s; starting first evaluation", flush=True) + start = perf_counter() + _, gradient, info = evaluate(*params) + statistics["first_evaluation_s"] = perf_counter()-start + print(f"First native value/gradient execution: {statistics['first_evaluation_s']:.2f} s", flush=True) + return statistics, gradient, info + + @jax.jit + def update_multipliers(lp, gradient, info, old_info): + kwargs = dict(model_lagrangian="Standard", beta=options.beta, + eta_tol=options.eta_tol, omega_tol=options.omega_tol) + if options.model_mu == "Mu_Tolerance": + updates = alm.apply_mu_tolerance_all_constraints(lp, + grad_dicts_map=gradient, constraint_infos_map=info, **kwargs) + else: + updates = jax.tree_util.tree_map(lambda p, g, new, old: + alm.apply_mu_tolerance_per_constraint(p, g, new, constraint_info_prev=old, + model_mu=options.model_mu, decrease_tol=.75, **kwargs), + lp, gradient, info, old_info, is_leaf=lambda x:isinstance(x, dict)) + return optax.apply_updates(lp, updates) + + def update(params, state, gradient, info): + x, lp = params + old_info, latest, steps = info[2], {}, [] + start = perf_counter() + def fun(candidate): + value, grad, aux = evaluate(candidate, lp) + latest.update(x=candidate.copy(), gradient=grad, info=aux) + return value, np.asarray(grad[0], dtype=np.float64) + def callback(candidate): + steps.append(None) + print(f" SciPy L-BFGS-B inner {len(steps)}: " + f"{statistics['evaluations']} total value/gradient calls; {perf_counter()-start:.2f} s", flush=True) + result = minimize(fun, np.asarray(x, dtype=np.float64), method="L-BFGS-B", jac=True, + bounds=[(-1., 1.)]*x.size, callback=callback, + options=dict(maxiter=options.inner_maxiter, gtol=options.omega_tol, ftol=options.scipy_ftol)) + x = jnp.asarray(result.x) + if np.array_equal(result.x, latest.get("x")): + gradient, info = latest["gradient"], latest["info"] + else: + _, gradient, info = evaluate(x, lp) + lp = update_multipliers(lp, gradient[1], info[2], old_info) + _, gradient, info = evaluate(x, lp) + statistics["inner_solves"].append(dict(iterations=int(result.nit), evaluations=int(result.nfev), + status=int(result.status), message=str(result.message), seconds=perf_counter()-start)) + print(f" SciPy inner solve: {result.message}; {result.nit} iterations, {result.nfev} evaluations", flush=True) + return (x, lp), statistics, gradient, info + return alm.ALM(init, update) + + +def field_normal_ratio(surface,field): + """Use the native direct-coil evaluator for the unchanged B.n/|B| constraint.""" + arrays,nc,nq=_coil_geometry(field) + magnetic=jax.vmap(lambda x:jnp.asarray(_coil_field_values(arrays,tuple(x),nc,nq,False)[0]))( + surface.gamma.reshape(-1,3)).reshape(surface.gamma.shape) + return jnp.sum(magnetic*surface.unitnormal,axis=-1)/jnp.linalg.norm(magnetic,axis=-1) + + +def save_coil_iteration(output,iteration,coil_dofs,parameters): + """Store public coil DOFs and optimizer coordinates without particle tracing.""" + directory=Path(output)/"iterations" + directory.mkdir(exist_ok=True) + np.savez_compressed(directory/f"{iteration:06d}.npz",iteration=iteration, + coil_dofs=np.asarray(coil_dofs),parameters=np.asarray(parameters)) + + +def build_problem(options, objective): + if objective not in ("loss_fraction", "distance", "heat_flux"): + raise ValueError("unknown QI particle constraint") + for path in (options.coils, options.wout): + if not Path(path).is_file(): + raise FileNotFoundError(f"Missing physical input: {path}; use --coils/--wout") + base = Coils.from_json(str(options.coils)) + surface = SurfaceRZFourier.from_wout_file(str(options.wout), s=1, + ntheta=options.surface_points, nphi=options.surface_points, range_torus="full torus") + axis = SurfaceRZFourier.from_wout_file(str(options.wout), s=0, + ntheta=options.surface_points, nphi=options.surface_points, range_torus="full torus") + phi = jnp.linspace(0., 2*jnp.pi, 200) + axis_points = jax.vmap(lambda p: surface_point(axis, 0., p))(phi) + initial_field = BiotSavart(base) + factor = options.axis_field_target/jnp.mean(jax.vmap(initial_field.AbsB)(axis_points)) + # Fix normalization after physical scaling so current DOFs remain order one. + base = Coils(base.curves, base.dofs_currents_raw*factor) + theta0 = jnp.asarray(base.dofs) + print(f"Preparing fixed QI classifier: {options.surface_points} surface samples/angle; h={options.classifier_h} m", flush=True) + boundary = SurfaceClassifier(surface, h=options.classifier_h, + padding=max(.1, 1.5*options.safety_margin)) + print(f"Seeding {options.particles} fixed births at boundary fraction {options.birth_fraction}", flush=True) + particles = Particles.InitializeParticlesAroundSurfaceAxis(axis, options.particles, + boundary_surface=surface, distance_mode="fraction_to_boundary", + distance_from_axis=options.birth_fraction, random_seed=options.seed, + n_arc_samples=options.birth_axis_samples, + mass=ALPHA_PARTICLE_MASS, charge=ALPHA_PARTICLE_CHARGE, + energy=options.energy_ev*ONE_EV) + particles.random_keys = jax.random.split(jax.random.key(options.collision_seed), options.particles) + if bool(jnp.any(jax.vmap(boundary.evaluate_xyz)(particles.initial_xyz)<=-options.safety_margin)): + raise ValueError("birth outside safety surface; check classifier/surface resolution and input geometry") + print(f"Prepared {len(base.dofs_currents)} independent coils at {options.axis_field_target} T; {theta0.size} scaled DOFs", flush=True) + point, direction = boundary_line(surface, options.line_theta, options.line_phi, options.line_mode) + ncoils = len(base.dofs_currents) + field_at = lambda x: BiotSavart(base.with_dofs(theta0+options.max_change*x)) + + def geometry(x): + field = field_at(x) + _,tangent,second=_fourier_geometry(field.coils.curves,second=True) + speed=jnp.linalg.norm(tangent,axis=-1) + length=jnp.mean(speed,axis=-1) + curvature=jnp.linalg.norm(jnp.cross(tangent,second),axis=-1)/speed**3 + result = dict(axis=jnp.mean(jax.vmap(field.AbsB)(axis_points))-options.axis_field_target, + length=options.length_target-length[:ncoils], + curvature=options.curvature_target-curvature[:ncoils]) + if options.bdotn_weight: + values = jnp.abs(field_normal_ratio(surface, field))-options.bdotn_target + sharpness = 20/options.bdotn_target + result["bdotn"] = -(jax.scipy.special.logsumexp(sharpness*values) + -jnp.log(values.size))/sharpness + return result + + safety = ClassifierStop(boundary, options.safety_margin) + + if options.collisions: + from essos.background_species import BackgroundSpecies + background = BackgroundSpecies(2, jnp.array([ELECTRON_MASS/PROTON_MASS, 2.]), + jnp.array([-1., 1.]), jnp.full(2, options.background_density), + jnp.full(2, options.background_temperature_ev)) + execution = ("independent" if jax.default_backend()=="gpu" else "shared") if options.execution=="auto" else options.execution + if options.collisions:print(f"Native split execution: forward={execution}; reverse={execution}",flush=True) + + def trace(x): + field = field_at(x) + if options.collisions: + from essos.split import trace_split, SplitStatus + result = trace_split(field, particles, background, model="GuidingCenter", + integrator="essos_dopri8", tmax=options.horizon, n_save=options.saves, + timestep=options.collision_step, collision_dtmax=options.collision_dtmax, + adaptive=True, orbit_adaptive=True, + collision_tolerance=options.collision_tolerance, collision_controller="moments", + moment_tolerance=options.moment_tolerance, orbit_dt0=options.initial_step, + rtol=options.rtol, atol=options.atol, event=safety, + max_steps=options.max_steps, max_orbit_steps=options.max_orbit_steps, + adjoint="accepted", adjoint_checkpoint_steps=options.checkpoint_steps, + adjoint_orbit_checkpoint_steps=options.checkpoint_steps, + adjoint_max_accepted_steps=options.collision_capacity, + adjoint_max_orbit_steps=options.accepted_capacity, + execution=execution, reverse_execution="independent" if execution=="independent" else "shared") + states = eqx.error_if(result.ys, jnp.any(result.status>SplitStatus.EVENT), + "native split solve failed; inspect work/tape capacities") + else: + result = Tracing(field=field, particles=particles, model="GuidingCenterAdaptative", + integrator="essos_dopri8", native_adjoint="accepted", native_controller="i", + native_adjoint_checkpoint_steps=options.checkpoint_steps, + native_adjoint_max_accepted_steps=options.accepted_capacity, + maxtime=options.horizon, timestep=options.initial_step, times_to_trace=options.saves, + rtol=options.rtol, atol=options.atol, max_steps=options.max_steps, + stopping_criteria=safety, progress=False) + states = result.trajectories + return eqx.error_if(states, ~jnp.isfinite(states).all(), "nonfinite native GC trajectory") + + def metrics(x, states): + field = field_at(x) + return dict(loss_fraction=classifier_loss_fraction(states, safety, options.softness), + distance=classifier_line_loss(states, point, direction, safety, + options.softness, options.location_softness), + heat_flux=classifier_energy_cost(states, field, particles.mass, particles.energy, + "GuidingCenterAdaptative", safety, softness=options.softness)) + + def particle(x): + states = trace(x) + # Trace only once and evaluate only the selected particle constraint. + if objective == "loss_fraction": + return classifier_loss_fraction(states, safety, options.softness) + if objective == "distance": + return classifier_line_loss(states, point, direction, safety, + options.softness, options.location_softness) + return classifier_energy_cost(states, field_at(x), particles.mass, particles.energy, + "GuidingCenterAdaptative", safety, softness=options.softness) + + constraints = make_constraints(geometry, particle, options) + return SimpleNamespace(base=base, theta0=theta0, particles=particles, field=field_at, + surface=surface, axis_points=axis_points, boundary=boundary, line=(point, direction), + geometry=geometry, particle=particle, trace=trace, metrics=metrics, + constraints=constraints, initial=jnp.zeros_like(theta0)) + + +def run(objective, defaults=None, argv=None): + settings = dict(DEFAULTS, **(defaults or {})) + parser = argparse.ArgumentParser(description=__doc__) + for name, value in settings.items(): + kwargs = dict(default=value) + if isinstance(value, bool): + kwargs["action"] = argparse.BooleanOptionalAction + else: + kwargs["type"] = Path if isinstance(value, Path) else type(value) + parser.add_argument("--"+name.replace("_", "-"), **kwargs) + parser.add_argument("--evaluate-only", action="store_true", help="One value/gradient; skip ALM updates") + o = parser.parse_args(argv) + for name in ("particles", "saves", "surface_points", "birth_axis_samples", "maxiter", "inner_maxiter", + "accepted_capacity", "collision_capacity", "max_steps", "max_orbit_steps"): + if getattr(o, name) < (2 if name in ("saves", "surface_points", "birth_axis_samples") else 1): + parser.error(name+" is too small") + if not (0<=o.birth_fraction<1 and 00 + and o.classifier_h>0 and o.safety_margin>0 and o.penalty>0 and o.bdotn_target>0): + parser.error("invalid birth fraction, time, scale, classifier, penalty or Bn target") + if o.execution not in ("auto", "shared", "independent"): + parser.error("execution must be auto, shared or independent") + if o.optimizer not in ("optimistix", "scipy") or not 0 < o.scipy_ftol < 1: + parser.error("optimizer must be optimistix or scipy; scipy-ftol must lie between 0 and 1") + if o.execution=="independent" and not o.collisions: + parser.error("independent split execution requires --collisions") + o.output.mkdir(parents=True, exist_ok=True) + if (o.output/"summary.json").exists() or (o.output/"iterations").exists(): + parser.error("choose a fresh output directory") + print(f"JAX backend: {jax.default_backend()}; devices: {jax.devices()}", flush=True) + print(f"QI GC ALM: {objective}; native Dopri8 accepted-map AD; collisions={o.collisions}", flush=True) + problem = build_problem(o, objective) + problem.base.to_json(str(o.output/"initial_coils.json")) + print("Initializing ALM multipliers and native value/gradient", flush=True) + constraints = problem.constraints + # Multiplier setup needs output shapes only; JIT prunes particle tracing. + params = problem.initial, jax.jit(constraints.init)(problem.initial) + if o.optimizer == "scipy": + optimizer = scipy_optimizer(constraints, o) + else: + optimizer = alm.ALM_model_lbfgs(constraints, beta=o.beta, model_mu=o.model_mu, + eta_tol=o.eta_tol, omega_tol=o.omega_tol, inner_maxiter=o.inner_maxiter, + bounds=(-jnp.ones_like(params[0]), jnp.ones_like(params[0]))) + optimizer=compile_optimizer(optimizer,independent=o.collisions and o.execution!='shared') + start = perf_counter() + state, gradient, info = jax.block_until_ready(optimizer.init(params)) + initialization_s = perf_counter()-start + records = [] + def record(iteration, seconds): + values = dict(iteration=iteration, lagrangian=float(info[1]), + particle_metric=float(info[2][3]), + constraint_norm=float(alm.norm_constraints(info[2])), + gradient_norm=float(jnp.linalg.norm(gradient[0])), seconds=seconds) + if not np.isfinite(list(values.values())).all(): + raise RuntimeError("nonfinite ALM value or gradient") + save_coil_iteration(o.output,iteration, + np.asarray(problem.theta0)+o.max_change*np.asarray(params[0]),params[0]) + records.append(values) + print(f"ALM {iteration}: particle={values['particle_metric']:.8g}; L={values['lagrangian']:.8g}; constraints={values['constraint_norm']:.4g}; " + f"|grad|={values['gradient_norm']:.4g}; {seconds:.2f} s", flush=True) + with (o.output/"history.csv").open("w", newline="") as stream: + writer = csv.DictWriter(stream, fieldnames=values) + writer.writeheader(); writer.writerows(records) + record(0, initialization_s) + for iteration in range(1, 1+(0 if o.evaluate_only else o.maxiter)): + if records[-1]["constraint_norm"]<=o.eta_tol and records[-1]["gradient_norm"]<=o.omega_tol: + break + phase="; first call also traces/compiles the update" if iteration==1 and o.optimizer=="optimistix" else "" + print(f"ALM {iteration}: starting inner L-BFGS (max {o.inner_maxiter} steps){phase}",flush=True) + start = perf_counter() + params, state, gradient, info = jax.block_until_ready(optimizer.update(params, state, gradient, info)) + record(iteration, perf_counter()-start) + print("Tracing initial/final coils for saved diagnostics", flush=True) + trace = jax.jit(problem.trace, **(gpu_jit_options() if o.collisions and o.execution!='shared' else {})) + initial, final = jax.block_until_ready((trace(problem.initial), trace(params[0]))) + initial_metrics = problem.metrics(problem.initial, initial) + final_metrics = problem.metrics(params[0], final) + print(f"Particle cost consistency: logged {records[0]['particle_metric']:.9g} -> {records[-1]['particle_metric']:.9g}; " + f"retraced {float(initial_metrics[objective]):.9g} -> {float(final_metrics[objective]):.9g}", flush=True) + optimized = problem.field(params[0]).coils + optimized.to_json(str(o.output/"optimized_coils.json")) + np.savez_compressed(o.output/"optimization.npz", parameters=params[0], + initial_dofs=problem.theta0, optimized_dofs=optimized.dofs, + births=problem.particles.initial_xyz, pitches=problem.particles.initial_vparallel_over_v, + initial_trajectories=initial, optimized_trajectories=final, line_point=problem.line[0], + line_direction=problem.line[1], lagrange=jax.flatten_util.ravel_pytree(params[1])[0]) + if o.save_plots: + axis_rz = np.asarray(problem.axis_points).mean(axis=0) + save_optimization_plots(o.output, problem.base, optimized, initial, final, + axis=(float(jnp.mean(jnp.linalg.norm(problem.axis_points[:, :2], axis=1))),float(axis_rz[2])), seed=o.seed) + report = dict(settings={k:str(v) if isinstance(v,Path) else v for k,v in vars(o).items()}, + objective=objective, source_branch="en/jax_13", source_commit="638916db823c0fe4689913b779eb473d55d6e3ae", + initial={k:float(v) for k,v in initial_metrics.items()}, + final={k:float(v) for k,v in final_metrics.items()}, history=records, + solver="essos_dopri8", adjoint="accepted", backend=jax.default_backend(), + distance_definition="Per-save escape-centroid distance to an infinite boundary tangent line, as in classic jax_13", + heat_definition="First-loss-weighted E_total*v_perp normalized by birth E*v; dimensionless proxy", + optimizer=("ESSOS ALM with host SciPy L-BFGS-B and a reused native value/gradient executable" + if o.optimizer=="scipy" else "Current ESSOS ALM with bounded Optimistix LBFGS; no historical frozen-trajectory custom VJP")) + report["cost_retrace"] = dict(logged_initial=records[0]["particle_metric"], + retraced_initial=float(initial_metrics[objective]), logged_final=records[-1]["particle_metric"], + retraced_final=float(final_metrics[objective])) + report["runtime"] = dict(jax=jax.__version__, jaxlib=jaxlib.__version__, + devices=[str(device) for device in jax.devices()], prng=str(jax.config.jax_default_prng_impl), + threefry_partitionable=bool(jax.config.jax_threefry_partitionable)) + if o.optimizer == "scipy": + report["optimizer_statistics"] = state + (o.output/"summary.json").write_text(json.dumps(report, indent=2)+"\n") + if o.save_plots: + from .plot_native_gc_alm import plot_run + plot_run(o.output, problem.surface, ClassifierStop(problem.boundary), vars(o)) + print(f"Saved {o.output.resolve()}", flush=True) diff --git a/examples/coil_optimization/native_particle_optimization.py b/examples/coil_optimization/native_particle_optimization.py new file mode 100644 index 00000000..f165a9ca --- /dev/null +++ b/examples/coil_optimization/native_particle_optimization.py @@ -0,0 +1,611 @@ +"""Shared setup for accepted-step reverse-AD coil optimization examples. + +Run an objective-specific entry point with ``python -m``; importing this module +does not trace particles or start an optimization. All particles are traced +together. Birth parameters, reference axis and classifier remain fixed. +""" +import argparse +import csv +import json +import os +from pathlib import Path +from time import perf_counter + +os.environ.setdefault("ESSOS_PROGRESS", "0") + +import jax +import jax.numpy as jnp +import numpy as np +from scipy.optimize import minimize + +from essos.coils import Coils, CreateEquallySpacedCurves +from essos.constants import ALPHA_PARTICLE_MASS, ALPHA_PARTICLE_CHARGE, ONE_EV +from essos.dynamics import Particles, Tracing +from essos.fields import BiotSavart +from essos.particle_losses import mean_final_radius, minor_radius, classifier_loss_fraction +from essos.surfaces import BdotN_over_B, SurfaceClassifier, SurfaceRZFourier + +ROOT = Path(__file__).resolve().parents[2] +COILS = ROOT / "examples/input_files/ESSOS_biot_savart_LandremanPaulQA.json" +WOUT = ROOT / "examples/input_files/wout_LandremanPaul2021_QA_reactorScale_lowres.nc" +PARTICLE_OBJECTIVES = ("loss_fraction", "final_radius", "radial_increment") + + +def save_optimization_plots(output, initial_coils, optimized_coils, + initial_trajectories, final_trajectories, *, axis, + count=10, seed=42, target_torus=None, safety_torus=None, + target_label="Soft target"): + """Save matched 3D and R-Z views of a random subset of stored trajectories. + + R-Z panels are poloidal projections across all toroidal angles, not + Poincare sections. No additional particle tracing or random births occur. + """ + from matplotlib import colormaps + from matplotlib.figure import Figure + from matplotlib.backends.backend_agg import FigureCanvasAgg + + before = np.asarray(initial_trajectories)[..., :3] + after = np.asarray(final_trajectories)[..., :3] + if before.ndim != 3 or before.shape != after.shape or not len(before) or count < 1: + raise ValueError("plotting requires matching nonempty trajectories and a positive particle count") + indices = np.random.default_rng(seed).choice(len(before), min(count, len(before)), replace=False) + curves = [np.asarray(coils.gamma) for coils in (initial_coils, optimized_coils)] + xyz = np.concatenate([curves[0].reshape(-1,3), curves[1].reshape(-1,3), + before[indices].reshape(-1,3), after[indices].reshape(-1,3)]) + lo, hi = xyz.min(axis=0), xyz.max(axis=0) + spans = np.maximum(hi-lo, 1e-6) + rz = [np.stack((np.hypot(paths[indices,...,0], paths[indices,...,1]), + paths[indices,...,2]), axis=-1) for paths in (before, after)] + angle = np.linspace(0., 2*np.pi, 97) + outlines = [np.column_stack((major+minor*np.cos(angle), z_axis+minor*np.sin(angle))) + for torus in (target_torus, safety_torus) if torus is not None + for major, minor, z_axis in (torus,)] + rz_all = np.concatenate([values.reshape(-1,2) for values in rz] + + [np.asarray(axis)[None,:]] + outlines) + rz_lo, rz_hi = rz_all.min(axis=0), rz_all.max(axis=0) + rz_pad = .08*np.maximum(rz_hi-rz_lo, 1e-6) + figure = Figure(figsize=(14,11)) + FigureCanvasAgg(figure) # Save headlessly without changing the user's pyplot backend. + axes3d = [figure.add_subplot(2,2,i+1, projection="3d") for i in range(2)] + axesrz = [figure.add_subplot(2,2,i+3) for i in range(2)] + for column, (title, paths) in enumerate((("Initial", before), ("Optimized", after))): + ax3d, axrz = axes3d[column], axesrz[column] + for torus, color, label in ((target_torus, "black", target_label), + (safety_torus, "crimson", "Safety stop")): + if torus is None: + continue + major, minor, z_axis = torus + radius, height = major + minor*np.cos(angle), z_axis + minor*np.sin(angle) + axrz.plot(radius, height, "--", color=color, linewidth=1., label=label) + for phi in np.linspace(0., 2*np.pi, 9)[:-1]: + ax3d.plot(radius*np.cos(phi), radius*np.sin(phi), height, + "--", color=color, linewidth=.6, alpha=.35) + for curve in curves[column]: + closed = np.concatenate((curve, curve[:1])) + ax3d.plot(*closed.T, color="0.45", linewidth=1., alpha=.65) + for rank, index in enumerate(indices): + color = colormaps["tab10"](rank % 10) + points = paths[index] + ax3d.plot(*points.T, color=color, linewidth=1.3) + ax3d.scatter(*points[0], color=color, s=12) + axrz.plot(*rz[column][rank].T, color=color, linewidth=1.3, label=f"Particle {index}") + axrz.scatter(*rz[column][rank,0], color=color, s=12) + ax3d.set(title=f"{title} coils and trajectories", xlabel="x [m]", ylabel="y [m]", zlabel="z [m]") + ax3d.set_xlim(lo[0]-.05*spans[0], hi[0]+.05*spans[0]) + ax3d.set_ylim(lo[1]-.05*spans[1], hi[1]+.05*spans[1]) + ax3d.set_zlim(lo[2]-.05*spans[2], hi[2]+.05*spans[2]) + ax3d.set_box_aspect(spans) + ax3d.view_init(elev=25, azim=-55) + axrz.scatter(*axis, marker="+", color="black", s=40, zorder=4) + axrz.set(title=f"{title}: R-Z poloidal projection", xlabel="R [m]", ylabel="Z [m]", + xlim=(rz_lo[0]-rz_pad[0],rz_hi[0]+rz_pad[0]), + ylim=(rz_lo[1]-rz_pad[1],rz_hi[1]+rz_pad[1])) + axrz.set_aspect("equal", adjustable="box") + axrz.grid(alpha=.25) + figure.suptitle(f"Coil optimization: {len(indices)} sampled particle trajectories") + figure.legend(*axesrz[0].get_legend_handles_labels(), loc="lower center", + ncol=min(5,len(indices)), frameon=False) + figure.subplots_adjust(left=.07, right=.97, bottom=.10, top=.94, hspace=.25, wspace=.20) + paths = [Path(output)/"orbit_comparison.png"] + try: + for path in paths: + figure.savefig(path, dpi=160) + finally: + figure.clear() + return dict(files=[path.name for path in paths], seed=seed, requested=count, + particle_indices=indices.tolist(), + selection="Same random subset of the optimization population before and after optimization", + poloidal_view="R-Z projection across all toroidal angles") + + +def radial_increment_cost(trajectories, axis_r, axis_z): + """Reference full-orbit metric, with Cartesian/time indexing corrected. + + This is sum_i(mean_j(r[i,j+1]-r[i,j]))**2, without division by dt. + It depends on save count and measures net drift, not oscillatory excursions. + """ + radius = minor_radius(trajectories, axis_r, axis_z) + return jnp.sum(jnp.mean(jnp.diff(radius, axis=1), axis=1)**2) + + +def fixed_surface(wout, *, ntheta=64, nphi=64, range_torus="full torus", major_radius=1., + shape="qa", minor_radius=.2, nfp=1): + """QA shape or circular torus, held fixed during coil optimization.""" + if shape == "torus": + if not (np.isfinite(major_radius) and np.isfinite(minor_radius) + and 0 < minor_radius < major_radius): + raise ValueError("torus radii must be finite with 0 < minor radius < major radius") + return SurfaceRZFourier(jnp.array([major_radius, minor_radius]), + jnp.array([0., minor_radius]), nfp, 1, 0, ntheta=ntheta, nphi=nphi, + range_torus=range_torus) + if shape != "qa": + raise ValueError("target surface must be 'qa' or 'torus'") + surface = SurfaceRZFourier.from_wout_file(str(wout)) + scale = surface.rc[0] + return SurfaceRZFourier(surface.rc * (major_radius / scale), surface.zs * (major_radius / scale), + surface.nfp, surface.mpol, surface.ntor, ntheta=ntheta, nphi=nphi, + range_torus=range_torus) + + +def fixed_classifier(wout, *, major_radius=1., shape="qa", minor_radius=.2, nfp=1): + """Fixed reference surface classifier used by the orbit benchmarks. + + This is a geometric confinement target, not an equilibrium recalculated + after a coil update. Periodic cubic angular interpolation also matches + derivatives at the toroidal seam. Distances are positive inside. + """ + return SurfaceClassifier(fixed_surface(wout, major_radius=major_radius, + shape=shape, minor_radius=minor_radius, nfp=nfp), + h=.03 * major_radius, padding=.16 * major_radius, + angular_interpolation="periodic_cubic") + + +def toroidal_safety_stop(major_radius, minor_radius, axis_z=0.): + """Cheap analytic level set, independent of the soft loss classifier. + + Positive inside, zero at/outside the safety torus. The squared minor + radius avoids a square-root derivative at axis births. Clamping to zero + also stops particles initially outside instead of waiting for re-entry. + """ + def stop(t, y, args, **kwargs): + del t, args, kwargs + radial = jnp.hypot(y[0], y[1]) - major_radius + return jnp.maximum(0., minor_radius**2 - radial**2 - (y[2]-axis_z)**2) + return stop + + +def coil_penalties(field, surface, options): + """Scalar penalties matching optimize_coils_vmec_surface.py. + + Length and pointwise curvature use the mean positive excess above their + targets. The normal-field term is the sum of abs(B dot n / |B|) on the + fixed surface. Zero weights omit the corresponding calculation entirely. + """ + return dict( + length_penalty=jnp.mean(jnp.maximum(field.coils.length - options.length_target, 0.)) + if options.length_weight else jnp.array(0.), + curvature_penalty=jnp.mean(jnp.maximum(field.coils.curvature - options.curvature_target, 0.)) + if options.curvature_weight else jnp.array(0.), + bdotn_penalty=jnp.sum(jnp.abs(BdotN_over_B(surface, field))) + if options.bdotn_weight else jnp.array(0.)) + + +def build_objective(options, objective): + """Return the coil-only scalar objective with saved trajectories as aux.""" + if objective not in PARTICLE_OBJECTIVES: + raise ValueError("unknown particle objective") + if options.coils is None: + # Higher Fourier modes start at zero; optimization can deform circles. + curves = CreateEquallySpacedCurves(n_curves=options.coil_count, + order=options.coil_order, R=options.coil_major_radius, r=options.coil_minor_radius, + n_segments=options.coil_segments, nfp=options.coil_nfp, stellsym=options.coil_stellsym, + scaling_type="L2", scaling_factor=options.coil_scaling_factor) + base = Coils(curves, jnp.full(options.coil_count, options.coil_current)) + else: + base = Coils.from_json(str(options.coils)) + theta0 = jnp.asarray(base.dofs) + initial_field = BiotSavart(base) + axis = (float(initial_field.r_axis), float(initial_field.z_axis)) + if options.length_target is None: + options.length_target = 1.05 * float(jnp.max(base.length)) + if options.curvature_target is None: + options.curvature_target = 1.05 * float(jnp.max(base.curvature)) + target = dict(major_radius=options.reference_major_radius, + shape=getattr(options, "target_surface", "qa"), + minor_radius=getattr(options, "target_minor_radius", .2), nfp=base.nfp) + classifier = fixed_classifier(options.wout, **target) if objective == "loss_fraction" else None + surface = fixed_surface(options.wout, ntheta=options.surface_ntheta, + nphi=options.surface_nphi, range_torus="half period", **target) if options.bdotn_weight else None + if options.particle_setup == "axis": + # Match the reference examples, including the duplicated 0/2pi birth. + phi = jnp.linspace(0., 2*jnp.pi, options.particles) + xyz = jnp.column_stack((axis[0]*jnp.cos(phi), axis[0]*jnp.sin(phi), + jnp.full_like(phi, axis[1]))) + pitches = jax.random.uniform(jax.random.PRNGKey(options.birth_seed), (options.particles,), + minval=options.pitch_min, maxval=options.pitch_max) + else: + xyz = jnp.column_stack((jnp.linspace(1.23, 1.27, options.particles), + jnp.zeros((options.particles, 2)))) + pitches = jnp.linspace(.35, .65, options.particles) + model = "GuidingCenterAdaptative" if options.model == "gc" else "FullOrbitAdaptative" + integrator = "essos_dopri8" if options.method == "dopri8" else "essos_rk45" + phi_axis = jnp.linspace(0., 2*jnp.pi, options.axis_field_points) + axis_points = jnp.column_stack((axis[0]*jnp.cos(phi_axis), axis[0]*jnp.sin(phi_axis), + jnp.full_like(phi_axis, axis[1]))) + safety_radius = getattr(options, "safety_minor_radius", None) + safety_stop = toroidal_safety_stop(axis[0], safety_radius, axis[1]) if safety_radius is not None else None + collisions = getattr(options, "collisions", False) + if collisions: + from essos.background_species import BackgroundSpecies + from essos.split import trace_split, SplitStatus + import equinox as eqx + + background = BackgroundSpecies(1, jnp.array([options.background_mass_proton]), + jnp.array([options.background_charge_e]), jnp.array([options.background_density]), + jnp.array([options.background_temperature_ev]), coulomb_log_model=options.coulomb_log_model) + + def evaluate(delta): + # Coils.dofs already applies the public curve/current normalization. + # A dimensionless bounded displacement makes max_change an explicit + # absolute limit in those DOFs, including initially zero coefficients. + field = BiotSavart(base.with_dofs(theta0 + options.max_change * delta)) + birth = Particles(xyz, initial_vparallel_over_v=pitches, + mass=ALPHA_PARTICLE_MASS, charge=ALPHA_PARTICLE_CHARGE, + energy=options.energy_ev * ONE_EV, + field=field if options.model == "lorentz" else None, + phase_angle_full_orbit=options.gyrophase) + if collisions: + out = trace_split(field, birth, background, + model="GuidingCenter" if options.model == "gc" else "FullOrbit", + integrator=integrator, tmax=options.horizon, n_save=options.saves, + timestep=options.collision_step, collision_dtmax=options.collision_dtmax, + collision_tolerance=options.collision_tolerance, + collision_controller=options.collision_controller, adaptive=options.collision_adaptive, + moment_tolerance=options.moment_tolerance, + orbit_dt0=options.initial_step if options.initial_step is not None else options.horizon / 2, + spatial_diffusion=options.collision_spatial_diffusion, + rtol=options.tolerance, atol=options.tolerance, event=safety_stop, + max_steps=options.max_steps, max_orbit_steps=options.max_orbit_steps, + execution="independent" if jax.default_backend()=="gpu" and options.method=="dopri8" and options.collision_adaptive else "shared", + adjoint="accepted", adjoint_checkpoint_steps=options.collision_checkpoint_steps, + adjoint_orbit_checkpoint_steps=options.checkpoint_steps, + adjoint_max_accepted_steps=options.collision_accepted_capacity, + adjoint_max_orbit_steps=options.accepted_capacity) + states = eqx.error_if(out.ys, jnp.any(out.status > SplitStatus.EVENT), + "split optimization solve failed; inspect collision/orbit work limits") + stop_fraction = jnp.mean((out.status == SplitStatus.EVENT).astype(float)) + work = dict(mean_collision_accepted=jnp.mean(out.stats.accepted.astype(float)), + mean_collision_rejected=jnp.mean(out.stats.rejected.astype(float)), + mean_orbit_trials=jnp.mean(out.stats.orbit_steps.astype(float)), + mean_orbit_rejected=jnp.mean(out.stats.orbit_rejected.astype(float))) + else: + trace = Tracing(field=field, particles=birth, model=model, + integrator=integrator, native_adjoint="accepted", + native_adjoint_checkpoint_steps=options.checkpoint_steps, + native_adjoint_parameter_accumulation=getattr(options, "parameter_accumulation", "segment"), + native_adjoint_max_accepted_steps=options.accepted_capacity, + native_controller="i", + rtol=options.tolerance, atol=options.tolerance, + maxtime=options.horizon, + timestep=options.initial_step if options.initial_step is not None else options.horizon / 2, + times_to_trace=options.saves, max_steps=options.max_steps, + stopping_criteria=safety_stop, + progress=False) + states, stop_fraction, work = trace.trajectories, jnp.mean(trace.boundary_hits.astype(float)), {} + if objective == "loss_fraction": + metric = classifier_loss_fraction(states, classifier, softness=options.softness) + elif objective == "final_radius": + metric = mean_final_radius(states, *axis) + else: + metric = radial_increment_cost(states, *axis) + components = dict(particle_metric=metric, + safety_stop_fraction=stop_fraction, + **work, **coil_penalties(field, surface, options), + axis_field_penalty=jnp.abs(jnp.mean(jax.vmap(field.AbsB)(axis_points)) - options.axis_field_target) + if options.axis_field_weight else jnp.array(0.), + regularization_penalty=jnp.mean(delta**2)) + cost = (options.particle_weight * metric + + options.length_weight * components["length_penalty"] + + options.curvature_weight * components["curvature_penalty"] + + options.bdotn_weight * components["bdotn_penalty"] + + options.axis_field_weight * components["axis_field_penalty"] + + options.regularization * components["regularization_penalty"]) + return cost, (components, states) + + return base, theta0, axis, xyz, pitches, evaluate + + +def run(objective, argv=None, *, defaults=None): + """Run a selected native objective with optional editable script defaults.""" + defaults = {} if defaults is None else dict(defaults) + if objective not in PARTICLE_OBJECTIVES: + raise ValueError("unknown particle objective") + parser = argparse.ArgumentParser(description= + "Optimize coil geometry and currents using native accepted-step reverse AD.") + parser.add_argument("--objective", choices=PARTICLE_OBJECTIVES, default=objective) + parser.add_argument("--output", type=Path, required="output" not in defaults, help="New output directory") + coil_source = parser.add_mutually_exclusive_group() + coil_source.add_argument("--coils", type=Path, default=COILS, help="Initial coil JSON") + coil_source.add_argument("--circular-coils", dest="coils", action="store_const", const=None, + help="Create equally spaced planar circular coils") + parser.add_argument("--coil-count", type=int, default=3, help="Independent coils per half field period") + parser.add_argument("--coil-order", type=int, default=6) + parser.add_argument("--coil-major-radius", type=float, default=7.74) + parser.add_argument("--coil-minor-radius", type=float, default=4.5) + parser.add_argument("--coil-current", type=float, default=1.84e7, help="Amperes per independent coil") + parser.add_argument("--coil-nfp", type=int, default=2) + parser.add_argument("--coil-stellsym", action=argparse.BooleanOptionalAction, default=True) + parser.add_argument("--coil-segments", type=int, default=60) + parser.add_argument("--coil-scaling-factor", type=float, default=0.) + parser.add_argument("--wout", type=Path, default=WOUT, help="VMEC target file when target-surface is qa") + parser.add_argument("--target-surface", choices=("qa", "torus"), default="qa", + help="Fixed geometry shared by the loss classifier and B dot n / |B|") + parser.add_argument("--target-minor-radius", type=float, default=.2, + help="Metres; circular target torus minor radius") + safety = parser.add_mutually_exclusive_group() + safety.add_argument("--safety-minor-radius", type=float, + help="Metres; separate hard stopping torus about the fixed initial axis (disabled if omitted)") + safety.add_argument("--no-safety-stop", dest="safety_minor_radius", action="store_const", const=None, + help="Disable the separate safety stopping torus") + parser.add_argument("--model", choices=("gc", "lorentz"), default="gc") + parser.add_argument("--method", choices=("dopri5", "dopri8"), default="dopri8") + parser.add_argument("--particles", type=int, default=8) + parser.add_argument("--particle-setup", choices=("line", "axis"), default="line") + parser.add_argument("--birth-seed", type=int, default=42) + parser.add_argument("--pitch-min", type=float, default=-1.) + parser.add_argument("--pitch-max", type=float, default=1.) + parser.add_argument("--gyrophase", type=float, default=float(jnp.pi), help="Radians") + parser.add_argument("--horizon", type=float, help="Seconds; default GC 20 us, Lorentz 2 us") + parser.add_argument("--initial-step", type=float, help="Initial adaptive step in seconds; default horizon/2") + parser.add_argument("--saves", type=int, default=32) + parser.add_argument("--energy-ev", type=float, default=4000.) + parser.add_argument("--tolerance", type=float, default=1e-9) + parser.add_argument("--checkpoint-steps", type=int, default=16) + parser.add_argument("--parameter-accumulation", choices=("step", "segment"), default="segment", + help="Collisionless RHS parameter pullback per step or checkpoint segment") + parser.add_argument("--accepted-capacity", type=int, default=512) + parser.add_argument("--max-steps", type=int, default=4096) + parser.add_argument("--collisions", action=argparse.BooleanOptionalAction, default=False, + help="Use production split orbit/collision tracing with accepted-step reverse AD") + parser.add_argument("--collision-adaptive", action=argparse.BooleanOptionalAction, default=True) + parser.add_argument("--collision-controller", choices=("moments", "conservative", "paper", "candidate"), default="moments") + parser.add_argument("--collision-tolerance", type=float, default=.001) + parser.add_argument("--moment-tolerance", type=float, default=.005) + parser.add_argument("--collision-step", type=float, default=1e-7, help="Initial or fixed collision interval [s]") + parser.add_argument("--collision-dtmax", type=float, default=1e-6, help="Collision/splitting interval ceiling [s]") + parser.add_argument("--collision-spatial-diffusion", action=argparse.BooleanOptionalAction, default=None, + help="Enable the Cartesian GC spatial collision increment") + parser.add_argument("--collision-checkpoint-steps", type=int, default=16, help="Accepted split maps per checkpoint") + parser.add_argument("--collision-accepted-capacity", type=int, default=4096, + help="Maximum recorded accepted split maps per particle") + parser.add_argument("--max-orbit-steps", type=int, default=4096, + help="Orbit trial limit within each collision interval; accepted-capacity bounds the total inner tape") + parser.add_argument("--background-density", type=float, default=1e20, help="Uniform background density [m^-3]") + parser.add_argument("--background-temperature-ev", type=float, default=1000.) + parser.add_argument("--background-mass-proton", type=float, default=1.) + parser.add_argument("--background-charge-e", type=float, default=1.) + parser.add_argument("--coulomb-log-model", choices=("nrl", "impact"), default="nrl") + parser.add_argument("--maxiter", type=int, default=10) + parser.add_argument("--max-evaluations", type=int, help="L-BFGS-B function evaluation limit") + parser.add_argument("--max-change", type=float, default=.01, + help="Absolute displacement bound in each public normalized coil DOF") + parser.add_argument("--regularization", type=float, default=0., + help="Optional mean-square bounded-displacement penalty") + parser.add_argument("--particle-weight", type=float, default=1.) + parser.add_argument("--length-weight", type=float, default=1., help="Weight of mean positive coil-length excess") + parser.add_argument("--curvature-weight", type=float, default=1., help="Weight of mean positive pointwise curvature excess") + parser.add_argument("--bdotn-weight", type=float, default=1., help="Weight of summed abs(B dot n / |B|) on the fixed surface") + parser.add_argument("--axis-field-weight", type=float, default=0., help="Weight of abs(mean axis |B| - target)") + parser.add_argument("--axis-field-target", type=float, default=5.7, help="Tesla") + parser.add_argument("--axis-field-points", type=int, default=15) + parser.add_argument("--length-target", type=float, help="Metres; default 1.05 times the largest initial coil length") + parser.add_argument("--curvature-target", type=float, help="1/metre; default 1.05 times the largest initial pointwise curvature") + parser.add_argument("--surface-ntheta", type=int, default=30, help="Poloidal points for the normal-field objective") + parser.add_argument("--surface-nphi", type=int, default=30, help="Toroidal points over a half field period for the normal-field objective") + parser.add_argument("--reference-major-radius", type=float, default=1., help="Metres; fixed target major radius") + parser.add_argument("--softness", type=float, default=10., help="Loss sigmoid slope in 1/metre") + parser.add_argument("--save-plots", action=argparse.BooleanOptionalAction, default=True) + parser.add_argument("--plot-particles", type=int, default=10, help="Random subset size, capped by traced population") + parser.add_argument("--plot-seed", type=int, default=42) + unknown = defaults.keys() - {action.dest for action in parser._actions} + if unknown: + raise ValueError(f"unknown native optimization settings: {sorted(unknown)}") + parser.set_defaults(**defaults) + options = parser.parse_args(argv) + for action in parser._actions: + if action.choices is not None and getattr(options, action.dest) not in action.choices: + parser.error(f"invalid {action.dest} in script settings; choose from {action.choices}") + objective = options.objective + if options.horizon is None: + options.horizon = 2e-5 if options.model == "gc" else 2e-6 + positive = (options.horizon, options.energy_ev, options.tolerance, + options.max_change, options.softness, options.reference_major_radius, + options.coil_major_radius, options.coil_minor_radius) + if any(not np.isfinite(value) or value <= 0 for value in positive): + parser.error("horizon, energy, tolerance, max-change, softness and radii must be finite and positive") + if options.target_surface == "torus": + if not (np.isfinite(options.target_minor_radius) + and 0 < options.target_minor_radius < options.reference_major_radius): + parser.error("target torus requires 0 < target-minor-radius < reference-major-radius") + if options.coils is None and options.target_minor_radius >= options.coil_minor_radius: + parser.error("target-minor-radius must be smaller than the initial circular coil radius") + if options.safety_minor_radius is not None: + if not (np.isfinite(options.safety_minor_radius) and options.safety_minor_radius > 0): + parser.error("safety-minor-radius must be finite and positive") + if options.target_surface == "torus" and options.safety_minor_radius <= options.target_minor_radius: + parser.error("safety-minor-radius must be larger than target-minor-radius") + if options.coils is None and options.safety_minor_radius >= options.coil_minor_radius: + parser.error("safety-minor-radius must be smaller than the initial circular coil radius") + if options.initial_step is not None and (not np.isfinite(options.initial_step) or options.initial_step <= 0): + parser.error("initial-step must be finite and positive") + if options.collisions: + if any(not np.isfinite(value) or value <= 0 for value in + (options.collision_tolerance, options.collision_step, options.collision_dtmax, + options.background_temperature_ev, options.background_mass_proton)): + parser.error("collision intervals/tolerance and background mass/temperature must be finite and positive") + if not np.isfinite(options.background_density) or options.background_density < 0: + parser.error("background-density must be finite and nonnegative") + if not np.isfinite(options.background_charge_e) or options.background_charge_e == 0: + parser.error("background-charge-e must be finite and nonzero") + if min(options.collision_checkpoint_steps, options.collision_accepted_capacity, options.max_orbit_steps) < 1: + parser.error("positive collision checkpoint/capacity and orbit work limits required") + if options.collision_spatial_diffusion and options.model != "gc": + parser.error("collision-spatial-diffusion requires the GC model") + if (not -1 <= options.pitch_min < options.pitch_max <= 1 or + not np.isfinite(options.gyrophase) or not np.isfinite(options.coil_current) or + options.coil_current == 0 or not np.isfinite(options.coil_scaling_factor)): + parser.error("invalid pitch range, gyrophase, coil current or Fourier scaling") + if (min(options.coil_count, options.coil_order, options.coil_nfp) < 1 or + options.coil_segments < 3 or options.coil_minor_radius >= options.coil_major_radius or + (options.max_evaluations is not None and options.max_evaluations < 1)): + parser.error("positive coil counts/order, at least three segments, major > minor radius and positive evaluation limit required") + if min(options.particles, options.checkpoint_steps, options.accepted_capacity, + options.max_steps, options.maxiter, options.plot_particles) < 1 or min(options.saves, + options.surface_ntheta, options.surface_nphi, options.axis_field_points) < 2: + parser.error("positive particle/step/iteration counts and at least two saves and surface points per direction required") + weights = (options.particle_weight, options.length_weight, + options.curvature_weight, options.bdotn_weight, options.axis_field_weight, options.regularization) + if any(not np.isfinite(value) or value < 0 for value in weights) or not any(weights): + parser.error("weights must be finite and nonnegative, with at least one nonzero weight") + targets = (options.length_target, options.curvature_target, options.axis_field_target) + if any(value is not None and (not np.isfinite(value) or value < 0) for value in targets): + parser.error("length, curvature and axis-field targets must be finite and nonnegative") + if options.output.exists(): + parser.error("output directory already exists; choose a new path") + print(f"JAX backend: {jax.default_backend()}; devices: {jax.devices()}", flush=True) + options.output.mkdir(parents=True) + print(f"Building {objective}, {options.model}, {options.particles} particles; coil DOFs only", flush=True) + base, theta0, axis, xyz, pitches, objective_fn = build_objective(options, objective) + base.to_json(str(options.output / "initial_coils.json")) + print("Initial coils: " + (str(options.coils) if options.coils is not None else + f"{base.gamma.shape[0]} planar circles ({options.coil_count} independent), " + f"R={options.coil_major_radius:g} m, r={options.coil_minor_radius:g} m, " + f"current={options.coil_current:g} A"), flush=True) + print(f"Length target {options.length_target:.6g} m; curvature target " + f"{options.curvature_target:.6g} /m; particle/length/curvature/Bn/axis weights " + f"{weights[:5]}", flush=True) + print(f"Fixed target surface: {options.target_surface}; " + f"major radius {options.reference_major_radius:g} m" + + (f"; minor radius {options.target_minor_radius:g} m" if options.target_surface == "torus" else ""), + flush=True) + if options.safety_minor_radius is not None: + print(f"Safety stopping torus: R={axis[0]:g} m, Z={axis[1]:g} m; " + f"minor radius {options.safety_minor_radius:g} m (separate from the soft target)", flush=True) + if options.collisions: + print(f"Split collisions: {'adaptive' if options.collision_adaptive else 'fixed'}, " + f"{options.collision_controller} controller, tolerance {options.collision_tolerance:g}; " + f"n={options.background_density:g} /m^3, T={options.background_temperature_ev:g} eV; " + "production per-particle keys (seed 42)", flush=True) + evaluate = jax.jit(jax.value_and_grad(objective_fn, has_aux=True)) + history = [] + cached = None + + with (options.output / "history.csv").open("w", newline="") as stream: + fieldnames = ("evaluation", "cost", "particle_metric", + "safety_stop_fraction", "length_penalty", "curvature_penalty", "bdotn_penalty", "axis_field_penalty", "regularization_penalty", + "gradient_l2", "max_abs_displacement", "seconds") + if options.collisions: + fieldnames += ("mean_collision_accepted", "mean_collision_rejected", "mean_orbit_trials", "mean_orbit_rejected") + writer = csv.DictWriter(stream, fieldnames=fieldnames) + writer.writeheader() + + def value_gradient(delta): + nonlocal cached + delta = np.asarray(delta, dtype=np.float64) + if cached is not None and np.array_equal(delta, cached[0]): + return cached[1], cached[2] + start = perf_counter() + (value, (components, trajectories)), gradient = jax.block_until_ready(evaluate(jnp.asarray(delta))) + value = float(value) + components = {name: float(term) for name, term in components.items()} + metric = components["particle_metric"] + gradient, trajectories = np.asarray(gradient), np.asarray(trajectories) + if not (np.isfinite(value) and all(np.isfinite(list(components.values()))) + and np.isfinite(gradient).all() and np.isfinite(trajectories).all()): + raise RuntimeError("nonfinite orbit, objective or gradient") + row = dict(evaluation=len(history), cost=value, **components, + gradient_l2=float(np.linalg.norm(gradient)), + max_abs_displacement=float(options.max_change * np.max(np.abs(delta))), + seconds=perf_counter() - start) + history.append(row) + writer.writerow(row) + stream.flush() + print(f"eval {row['evaluation']:3d}: metric={metric:.10g}, " + f"cost={value:.10g}, |grad|={row['gradient_l2']:.4g}, " + f"safety stops={components['safety_stop_fraction']:.1%}, " + f"{row['seconds']:.2f} s", flush=True) + cached = (delta.copy(), value, gradient, components, trajectories) + return value, gradient + + delta0 = np.zeros(theta0.size) + initial_value, initial_gradient = value_gradient(delta0) + initial_components, initial_trajectories = cached[3], cached[4].copy() + optimizer_options = dict(maxiter=options.maxiter, maxls=12, ftol=1e-12, gtol=1e-10) + if options.max_evaluations is not None: + optimizer_options["maxfun"] = options.max_evaluations + result = minimize(value_gradient, delta0, method="L-BFGS-B", jac=True, + bounds=[(-1., 1.)] * theta0.size, + options=optimizer_options) + final_value, final_gradient = value_gradient(result.x) + final_components, final_trajectories = cached[3], cached[4] + + final_dofs = theta0 + options.max_change * jnp.asarray(result.x) + base.with_dofs(final_dofs).to_json(str(options.output / "optimized_coils.json")) + np.savez_compressed(options.output / "orbits.npz", + times=np.linspace(0., options.horizon, options.saves), + initial_trajectories=initial_trajectories, final_trajectories=final_trajectories, + initial_coil_dofs=np.asarray(theta0), final_coil_dofs=np.asarray(final_dofs), + birth_xyz=np.asarray(xyz), birth_pitch=np.asarray(pitches)) + plots = save_optimization_plots(options.output, base, base.with_dofs(final_dofs), + initial_trajectories, final_trajectories, axis=axis, + count=options.plot_particles, seed=options.plot_seed, + target_torus=(options.reference_major_radius, options.target_minor_radius, 0.) + if options.target_surface == "torus" else None, + safety_torus=(axis[0], options.safety_minor_radius, axis[1]) + if options.safety_minor_radius is not None else None) if options.save_plots else None + units = {"loss_fraction": "probability", "final_radius": "metres", "radial_increment": "metres squared"} + report = dict(objective=objective, metric_units=units[objective], + coil_initialization="planar_circular" if options.coils is None else "json_file", + initial_cost=initial_value, final_cost=final_value, + initial_particle_metric=initial_components["particle_metric"], + final_particle_metric=final_components["particle_metric"], + initial_components=initial_components, final_components=final_components, + loss_weights=dict(particle_metric=options.particle_weight, length_penalty=options.length_weight, + curvature_penalty=options.curvature_weight, bdotn_penalty=options.bdotn_weight, + axis_field_penalty=options.axis_field_weight, + regularization_penalty=options.regularization), + loss_definitions=dict(length_penalty="mean(max(coil_length_m - length_target_m, 0))", + curvature_penalty="mean(max(pointwise_curvature_per_m - curvature_target_per_m, 0))", + bdotn_penalty="sum(abs(B dot unitnormal / |B|)) over fixed half-period surface mesh", + axis_field_penalty="abs(mean(|B| on fixed initial axis circle) - axis_field_target_T)", + radial_increment="sum_i(mean_j(r[i,j+1]-r[i,j]))**2; no division by dt; save-count dependent", + regularization_penalty="mean(delta**2)"), + initial_gradient_l2=float(np.linalg.norm(initial_gradient)), + final_gradient_l2=float(np.linalg.norm(final_gradient)), + optimizer_success=bool(result.success), optimizer_message=str(result.message), + iterations=int(result.nit), function_evaluations=int(result.nfev), + recorded_evaluations=len(history), coil_dof_names=list(base.dof_names), + reference_axis_r_z_m=axis, backend=jax.default_backend(), + devices=[str(device) for device in jax.devices()], jax=jax.__version__, + settings={name: str(value.resolve()) if isinstance(value, Path) else value + for name, value in vars(options).items()}, + plots=plots, + derivative_policy="Accepted-step reverse AD with frozen adaptive times; segment checkpoints; full population vmap" + + ("; collision coefficients and kicks differentiated with exact recorded production Wiener increments" if options.collisions else ""), + birth_policy="Fixed GC birth XYZ, pitch, energy and gyrophase; Lorentz conversion remains field-dependent", + target_policy="Fixed initial reference axis and fixed soft target; separate optional safety stopping torus", + safety_policy=("Split orbit crossings are root-found; velocity kicks follow the production split event rules; " + "later saves hold the terminal state. " if options.collisions else + "Stop on the first accepted step reaching the safety torus; hold the last saved interior state; ") + + "accepted step times, stopping decisions and saved-time masks are frozen in reverse AD. " + "The safety-stop fraction is a diagnostic, not an added objective.", + collision_policy="Production split sampler and per-particle keys (seed 42); exact accepted increments frozen in AD; " + "one uniform Maxwellian background; splitting error is not bounded by collision tolerance" + if options.collisions else "disabled", + gradient_coordinates="Dimensionless delta; coil DOFs = initial DOFs + max_change * delta", + timing_scope="First evaluation includes compilation; later evaluations reuse compiled value_and_grad") + (options.output / "summary.json").write_text(json.dumps(report, indent=2) + "\n") + print(f"Cost {initial_value:.10g} -> {final_value:.10g}; particle metric " + f"{initial_components['particle_metric']:.10g} -> {final_components['particle_metric']:.10g}; {result.message}; " + f"saved {options.output}", flush=True) + diff --git a/examples/coil_optimization/optimize_coils_native_final_radius.py b/examples/coil_optimization/optimize_coils_native_final_radius.py new file mode 100644 index 00000000..562fb919 --- /dev/null +++ b/examples/coil_optimization/optimize_coils_native_final_radius.py @@ -0,0 +1,10 @@ +"""Optimize final minor radius, coil length/curvature and B dot n / |B| with native AD. + +From the checkout root: +python -m examples.coil_optimization.optimize_coils_native_final_radius --output output/final_radius +""" +from .native_particle_optimization import run + + +if __name__ == "__main__": + run("final_radius") diff --git a/examples/coil_optimization/optimize_coils_native_gc_alm_distance.py b/examples/coil_optimization/optimize_coils_native_gc_alm_distance.py new file mode 100644 index 00000000..9325c43e --- /dev/null +++ b/examples/coil_optimization/optimize_coils_native_gc_alm_distance.py @@ -0,0 +1,17 @@ +"""QI escape-line ALM, recovered from the classic jax_13 escape_line case.""" +from pathlib import Path +import numpy as np +from .native_gc_alm import run + +# This is the infinite tangent line at theta=3*pi/2, phi=pi on the QI surface. +# Set collisions=False or pass --no-collisions for collisionless GC AD. +PARAMETERS = dict(particles=20, horizon=1e-4, saves=10, collisions=True, + line_mode="fixed_theta", line_theta=1.5*np.pi, line_phi=np.pi, + location_softness=10., bdotn_weight=0., maxiter=100, + output=Path("output/native_gc_alm_distance")) + +def main(argv=None): + run("distance", PARAMETERS, argv) + +if __name__ == "__main__": + main() diff --git a/examples/coil_optimization/optimize_coils_native_gc_alm_heat_flux.py b/examples/coil_optimization/optimize_coils_native_gc_alm_heat_flux.py new file mode 100644 index 00000000..6d082f7d --- /dev/null +++ b/examples/coil_optimization/optimize_coils_native_gc_alm_heat_flux.py @@ -0,0 +1,15 @@ +"""QI heat-proxy ALM, recovered from the classic jax_13 heat_flux case.""" +from pathlib import Path +from .native_gc_alm import run + +# E_total*v_perp is normalized by birth E*v; it is not W/m^2. +# Current native split collisions replace the old Diffrax Mu-fixed model. +PARAMETERS = dict(particles=20, horizon=1e-4, saves=10, collisions=True, + bdotn_weight=1., bdotn_target=1e-3, maxiter=100, + output=Path("output/native_gc_alm_heat_flux")) + +def main(argv=None): + run("heat_flux", PARAMETERS, argv) + +if __name__ == "__main__": + main() diff --git a/examples/coil_optimization/optimize_coils_native_gc_alm_loss_fraction.py b/examples/coil_optimization/optimize_coils_native_gc_alm_loss_fraction.py new file mode 100644 index 00000000..16a8b65b --- /dev/null +++ b/examples/coil_optimization/optimize_coils_native_gc_alm_loss_fraction.py @@ -0,0 +1,15 @@ +"""QI classifier loss-fraction ALM, recovered from jax_13 surface_coils.""" +from pathlib import Path +from .native_gc_alm import run + +# Common editable physical/solver defaults are in native_gc_alm.DEFAULTS. +# CLI flags override both dictionaries; no CPU or GPU backend is forced. +PARAMETERS = dict(particles=20, horizon=1e-4, saves=10, collisions=True, + maxiter=100, length_target=45., curvature_target=1., axis_field_target=5.7, + output=Path("output/native_gc_alm_loss_fraction")) + +def main(argv=None): + run("loss_fraction", PARAMETERS, argv) + +if __name__ == "__main__": + main() diff --git a/examples/coil_optimization/optimize_coils_native_loss_fraction.py b/examples/coil_optimization/optimize_coils_native_loss_fraction.py new file mode 100644 index 00000000..5f9edc08 --- /dev/null +++ b/examples/coil_optimization/optimize_coils_native_loss_fraction.py @@ -0,0 +1,10 @@ +"""Optimize loss fraction, coil length/curvature and B dot n / |B| with native AD. + +From the checkout root: +python -m examples.coil_optimization.optimize_coils_native_loss_fraction --output output/loss_fraction +""" +from .native_particle_optimization import run + + +if __name__ == "__main__": + run("loss_fraction") diff --git a/examples/coil_optimization/optimize_coils_particle_confinement_fullorbit_native.py b/examples/coil_optimization/optimize_coils_particle_confinement_fullorbit_native.py new file mode 100644 index 00000000..c6e7c07e --- /dev/null +++ b/examples/coil_optimization/optimize_coils_particle_confinement_fullorbit_native.py @@ -0,0 +1,93 @@ +"""Full-orbit reference case with the existing checkpointed native AD runner. + +Edit PARTICLE_OBJECTIVE and PARAMETERS below, then run from the checkout root: +python -m examples.coil_optimization.optimize_coils_particle_confinement_fullorbit_native + +CLI arguments optionally override these settings. No optimization runs on import. +""" +from pathlib import Path +from .native_particle_optimization import run + +# Select "final_radius", "loss_fraction", or "radial_increment". The last +# matches the intended legacy full-orbit metric with its time indexing fixed. +PARTICLE_OBJECTIVE = "final_radius" + +# Physical setup from optimize_coils_particle_confinement_fullorbit.py. +# Solver, checkpointing, DOF bounds and optimizer use the native example path. +PARAMETERS = dict( + coils=None, # Generate planar circular coils. + coil_count=3, # Independent coils per half field period. + coil_nfp=2, + coil_stellsym=True, # 12 physical coils after symmetry. + coil_order=6, + coil_segments=60, + coil_major_radius=7.74, # m + coil_minor_radius=4.5, # m + coil_current=1.84e7, # A + coil_scaling_factor=0., # Same Fourier normalization as reference. + particles=10, + particle_setup="axis", # Equally spaced around R=7.74 m, Z=0. + birth_seed=42, # Fixed uniform pitch sample in [-1, 1]. + pitch_min=-1., + pitch_max=1., + energy_ev=3.52e6, # Alpha-particle mass and charge. + gyrophase=0., # radians; full-orbit birth conversion is active in AD. + model="lorentz", + horizon=1e-4, # s; final tracing time. + initial_step=1e-14, # Initial adaptive guess, not a fixed step. + tolerance=1e-8, + saves=1000, + method="dopri8", + checkpoint_steps=16, + parameter_accumulation="segment", # Shared GC/Lorentz reverse accumulation policy. + accepted_capacity=65536, + max_steps=262144, + collisions=False, # Opt in to full split orbit/collision reverse AD. + collision_adaptive=True, + collision_controller="moments", + collision_tolerance=.001, + collision_step=1e-7, # s; initial adaptive or fixed split interval. + collision_dtmax=1e-6, # s; independent operator-splitting ceiling. + collision_spatial_diffusion=None, # GC only. + collision_checkpoint_steps=16, + collision_accepted_capacity=4096, # Outer maps; accepted_capacity bounds the total inner RK tape. + max_orbit_steps=4096, # Inner orbit trial limit per collision interval. + background_density=1e20, # m^-3; one uniform Maxwellian species. + background_temperature_ev=1000., + background_mass_proton=1., + background_charge_e=1., + coulomb_log_model="nrl", + maxiter=200, + max_evaluations=200, # Native L-BFGS-B function evaluation limit. + max_change=.01, # Bound in public normalized coil DOFs. + particle_weight=1., + length_weight=1., # Set any objective weight to zero to omit it. + length_target=31., # m + curvature_weight=1., + curvature_target=.4, # 1/m + bdotn_weight=1., + wout=Path(__file__).resolve().parents[1] / "input_files/wout_LandremanPaul2021_QA_reactorScale_lowres.nc", + target_surface="torus", # Fixed classifier and Bn target, inside the coils. + reference_major_radius=7.74, # m; torus major radius. + target_minor_radius=3.5, # m; smaller than coil_minor_radius=4.5 m. + safety_minor_radius=4.4, # m; stop 10 cm inside the initial coil circles. + surface_ntheta=30, + surface_nphi=30, + softness=10./7.74, # 1/m; same relative sigmoid width as native example. + axis_field_weight=1., + axis_field_target=5.7, # T + axis_field_points=15, + regularization=0., + save_plots=True, # Matched 3D coil/orbit and R-Z views, PNG. + plot_particles=10, # Random subset of traced particles; same IDs in both views. + plot_seed=42, + output=Path("output/native_fullorbit_confinement"), +) + + +def main(argv=None): + run(PARTICLE_OBJECTIVE, argv, defaults=PARAMETERS) + + +if __name__ == "__main__": + main() diff --git a/examples/coil_optimization/optimize_coils_particle_confinement_guidingcenter_native.py b/examples/coil_optimization/optimize_coils_particle_confinement_guidingcenter_native.py new file mode 100644 index 00000000..64341463 --- /dev/null +++ b/examples/coil_optimization/optimize_coils_particle_confinement_guidingcenter_native.py @@ -0,0 +1,92 @@ +"""Guiding-center reference case with the existing checkpointed native AD runner. + +Edit PARTICLE_OBJECTIVE and PARAMETERS below, then run from the checkout root: +python -m examples.coil_optimization.optimize_coils_particle_confinement_guidingcenter_native + +CLI arguments optionally override these settings. No optimization runs on import. +""" +from pathlib import Path +from .native_particle_optimization import run + +# Select "final_radius", "loss_fraction", or "radial_increment". +PARTICLE_OBJECTIVE = "final_radius" + +# Physical setup from optimize_coils_particle_confinement_guidingcenter.py. +# Solver, checkpointing, DOF bounds and optimizer use the native example path. +PARAMETERS = dict( + coils=None, # Generate planar circular coils. + coil_count=3, # Independent coils per half field period. + coil_nfp=2, + coil_stellsym=True, # 12 physical coils after symmetry. + coil_order=6, + coil_segments=60, + coil_major_radius=7.74, # m + coil_minor_radius=4.5, # m + coil_current=1.84e7, # A + coil_scaling_factor=1.2, # L2 mode scaling in the GC reference. + particles=10, + particle_setup="axis", # Equally spaced around R=7.74 m, Z=0. + birth_seed=42, # Fixed uniform pitch sample in [-1, 1]. + pitch_min=-1., + pitch_max=1., + energy_ev=3.52e6, # Alpha-particle mass and charge. + gyrophase=0., + model="gc", + horizon=1e-4, # s; final tracing time. + initial_step=1e-14, # Initial adaptive guess, not a fixed step. + tolerance=1e-8, + saves=1000, + method="dopri8", + checkpoint_steps=16, + parameter_accumulation="segment", # Shared GC/Lorentz reverse accumulation policy. + accepted_capacity=8192, + max_steps=32768, + collisions=False, # Opt in to full split orbit/collision reverse AD. + collision_adaptive=True, + collision_controller="moments", + collision_tolerance=.001, + collision_step=1e-7, # s; initial adaptive or fixed split interval. + collision_dtmax=1e-6, # s; independent operator-splitting ceiling. + collision_spatial_diffusion=None, # Optional Cartesian GC spatial collision increment. + collision_checkpoint_steps=16, + collision_accepted_capacity=4096, # Outer maps; accepted_capacity bounds the total inner RK tape. + max_orbit_steps=4096, # Inner orbit trial limit per collision interval. + background_density=1e20, # m^-3; one uniform Maxwellian species. + background_temperature_ev=1000., + background_mass_proton=1., + background_charge_e=1., + coulomb_log_model="nrl", + maxiter=200, + max_evaluations=200, # Native L-BFGS-B function evaluation limit. + max_change=.01, # Bound in public normalized coil DOFs. + particle_weight=1., + length_weight=1., # Set any objective weight to zero to omit it. + length_target=31., # m + curvature_weight=1., + curvature_target=.4, # 1/m + bdotn_weight=1., + wout=Path(__file__).resolve().parents[1] / "input_files/wout_LandremanPaul2021_QA_reactorScale_lowres.nc", + target_surface="torus", # Fixed classifier and Bn target, inside the coils. + reference_major_radius=7.74, # m; torus major radius. + target_minor_radius=3.5, # m; smaller than coil_minor_radius=4.5 m. + safety_minor_radius=4.4, # m; stop 10 cm inside the initial coil circles. + surface_ntheta=30, + surface_nphi=30, + softness=10./7.74, # 1/m; same relative sigmoid width as native example. + axis_field_weight=1., + axis_field_target=5.7, # T + axis_field_points=15, + regularization=0., + save_plots=True, # Matched 3D coil/orbit and R-Z views, PNG. + plot_particles=10, # Random subset of traced particles; same IDs in both views. + plot_seed=42, + output=Path("output/native_gc_confinement"), +) + + +def main(argv=None): + run(PARTICLE_OBJECTIVE, argv, defaults=PARAMETERS) + + +if __name__ == "__main__": + main() diff --git a/examples/coil_optimization/plot_native_gc_alm.py b/examples/coil_optimization/plot_native_gc_alm.py new file mode 100644 index 00000000..01347979 --- /dev/null +++ b/examples/coil_optimization/plot_native_gc_alm.py @@ -0,0 +1,206 @@ +"""Plot downloaded QI ALM runs without tracing or differentiating again. + +Loss means first saved position outside the fixed classifier (signed distance +<= 0), not the soft optimization score or an exact wall-impact diagnostic. +The heat proxy is E_total*v_perp [W m], not a surface heat-flux density. +""" +import argparse +import json +from pathlib import Path +from tempfile import NamedTemporaryFile + +import jax +import jax.numpy as jnp +import numpy as np +from matplotlib import colors +from matplotlib.cm import ScalarMappable +from matplotlib.figure import Figure + +from essos.coils import Coils +from essos.constants import ALPHA_PARTICLE_MASS +from essos.fields import BiotSavart +from essos.split import ClassifierStop +from essos.surfaces import SurfaceClassifier, SurfaceRZFourier + +INPUT = Path(__file__).resolve().parents[1]/"input_files" +PAIR_COLORS = ("royalblue", "goldenrod") +LABELS = ("Initial", "Optimized") + + +def diagnostics(states, coils, boundary, softness): + """Use the physical-mu GC states and the run's original signed distance.""" + states = np.asarray(states) + if states.ndim != 3 or states.shape[-1] != 5 or not np.isfinite(states).all(): + raise ValueError("Expected finite (particles, saves, 5) Cartesian physical-mu GC states") + distance = np.asarray(jax.jit(jax.vmap(boundary.evaluate_xyz))( + jnp.asarray(states[..., :3].reshape(-1, 3)))).reshape(states.shape[:2]) + escaped = np.maximum.accumulate(distance <= 0., axis=1) + lost = escaped[:, -1] + first = np.argmax(escaped[lost], axis=1) + hits = states[lost][np.arange(np.count_nonzero(lost)), first] + if len(hits): + magnitude = np.asarray(jax.jit(jax.vmap(BiotSavart(coils).AbsB))(jnp.asarray(hits[:, :3]))) + perpendicular = np.maximum(hits[:, 4]*magnitude, 0.) + energy = .5*ALPHA_PARTICLE_MASS*hits[:, 3]**2+perpendicular + heat = energy*np.sqrt(2*perpendicular/ALPHA_PARTICLE_MASS) + else: + heat = np.empty(0) + # Stable sigmoid, matching the soft score but keeping it distinct from counts. + z = -softness*distance + probability = np.exp(-np.logaddexp(0., -z)) + return dict(fraction=escaped.mean(axis=0), hits=hits[:, :3], heat=heat, + count=int(lost.sum()), soft=float(probability.max(axis=1).mean())) + + +def view3d(ax, points): + lo, hi = points.min(axis=0), points.max(axis=0) + pad = .06*np.maximum(hi-lo, 1.) + ax.set(xlabel="x [m]", ylabel="y [m]", zlabel="z [m]", + xlim=(lo[0]-pad[0], hi[0]+pad[0]), + ylim=(lo[1]-pad[1], hi[1]+pad[1]), + zlim=(lo[2]-pad[2], hi[2]+pad[2])) + ax.set_box_aspect(np.maximum(hi-lo, 1.), zoom=.88) + ax.view_init(elev=25, azim=-55) + + +def save(fig, path): + # Atomic replacement also allows regenerating a PNG displayed by Windows. + with NamedTemporaryFile(dir=path.parent, suffix=".png", delete=False) as stream: + temporary = Path(stream.name) + try: + fig.savefig(temporary, dpi=180, facecolor="white", bbox_inches="tight") + temporary.replace(path) + finally: + temporary.unlink(missing_ok=True) + fig.clear() + + +def plot_run(folder, surface, boundary, settings): + coils = [Coils.from_json(str(folder/f"{name}_coils.json")) + for name in ("initial", "optimized")] + with np.load(folder/"optimization.npz") as data: + states = [data[f"{name}_trajectories"] for name in ("initial", "optimized")] + for model, name in zip(coils, ("initial", "optimized")): + np.testing.assert_allclose(model.dofs, data[f"{name}_dofs"], rtol=1e-12, atol=1e-12) + if states[0].shape != states[1].shape or not np.array_equal(states[0][:, 0, :3], states[1][:, 0, :3]): + raise ValueError("Initial and optimized runs must use matching saved particles and birth positions") + if states[0].shape[:2] != (settings["particles"], settings["saves"]): + raise ValueError("Saved trajectory dimensions disagree with summary settings") + rows = [diagnostics(y, c, boundary, settings["softness"]) for y, c in zip(states, coils)] + report = json.loads((folder/"summary.json").read_text()) + for name, row in zip(("initial", "final"), rows): + np.testing.assert_allclose(row["soft"], report[name]["loss_fraction"], rtol=1e-6, atol=1e-8, + err_msg="Reconstructed classifier disagrees with saved run") + times = np.linspace(0., settings["horizon"], states[0].shape[1]) + curves = [np.asarray(c.gamma) for c in coils] + surf = np.asarray(surface.gamma) + coil_points = np.concatenate([g.reshape(-1, 3) for g in curves]) + hit_points = np.concatenate([surf.reshape(-1, 3)]+[r["hits"] for r in rows]) + all_heat = np.concatenate([r["heat"] for r in rows]) + norm = colors.Normalize(vmin=0., vmax=max(float(all_heat.max()) if all_heat.size else 0., 1e-30)) + bins = np.linspace(norm.vmin, norm.vmax, 21) + + def draw_coils(ax): + for g, label, color in zip(curves, LABELS, PAIR_COLORS): + for i, curve in enumerate(g): + ax.plot(*np.concatenate((curve, curve[:1])).T, color=color, + label=label if i == 0 else None, linewidth=1., alpha=.85) + view3d(ax, coil_points) + ax.set_title("Initial and optimized coils") + ax.legend(loc="upper left") + + def draw_loss(ax): + for row, label, color in zip(rows, LABELS, PAIR_COLORS): + ax.step(times, row["fraction"], where="post", color=color, linewidth=2., + label=f"{label}: {row['count']}/{len(states[0])}") + ax.set(title="Loss fraction vs time", xlabel="Time [s]", ylabel="Cumulative lost fraction", ylim=(0., max(.05, 1.12*max(r["fraction"][-1] for r in rows)))) + ax.ticklabel_format(axis="x", style="sci", scilimits=(0, 0)) + ax.grid(alpha=.2) + ax.legend() + + def draw_histogram(ax): + for row, label, color in zip(rows, LABELS, PAIR_COLORS): + ax.hist(row["heat"], bins=bins, color=color, alpha=.6, label=label, edgecolor="white") + ax.set(title="Heat proxy at first recorded loss", xlabel=r"$E\,v_\perp$ [W m]", ylabel="Particle count") + ax.ticklabel_format(axis="x", style="sci", scilimits=(0, 0)) + ax.legend() + + def draw_hits(ax, i): + ax.plot_surface(*np.moveaxis(surf, -1, 0), color="0.7", alpha=.18, + linewidth=0., shade=False, rcount=60, ccount=60) + row = rows[i] + ax.scatter(*row["hits"].T, c=row["heat"], cmap="turbo", norm=norm, + s=26, edgecolors="0.25", linewidths=.4, depthshade=False) + view3d(ax, hit_points) + ax.set_title(f"{LABELS[i]}: {row['count']} lost particles") + + out = folder/"comparison_plots" + out.mkdir(exist_ok=True) + objective = report["objective"] + title = f"QI GC + collisions: {objective.replace('_', ' ')} optimization; N={len(states[0])}" + note = ("Loss locations/energies: first saved point outside the physical classifier; " + f"{len(times)} saves, spacing {np.diff(times)[0]*1e6:.2f} microseconds.\n" + "Colours show E v_perp [W m], not heat flux per unit area.") + + fig = Figure(figsize=(10, 8), layout="constrained") + draw_coils(fig.add_subplot(projection="3d")) + save(fig, out/"coil_comparison.png") + fig = Figure(figsize=(7, 4.5), layout="constrained") + draw_loss(fig.add_subplot()) + save(fig, out/"loss_fraction.png") + fig = Figure(figsize=(17, 6.5), layout="constrained") + fig.get_layout_engine().set(w_pad=.15, wspace=.08) + draw_histogram(fig.add_subplot(131)) + axes = [fig.add_subplot(132+i, projection="3d") for i in range(2)] + for i, ax in enumerate(axes): + draw_hits(ax, i) + fig.colorbar(ScalarMappable(norm=norm, cmap="turbo"), ax=axes, + label=r"$E\,v_\perp$ [W m]", shrink=.65, pad=.02) + fig.suptitle(title+"\n"+note, fontsize=11) + save(fig, out/"lost_heat_comparison.png") + + fig = Figure(figsize=(17, 12), layout="constrained") + fig.get_layout_engine().set(w_pad=.15, wspace=.08) + grid = fig.add_gridspec(2, 6) + draw_coils(fig.add_subplot(grid[0, :2], projection="3d")) + draw_loss(fig.add_subplot(grid[0, 2:4])) + draw_histogram(fig.add_subplot(grid[0, 4:])) + axes = [fig.add_subplot(grid[1, 3*i:3*(i+1)], projection="3d") for i in range(2)] + for i, ax in enumerate(axes): + draw_hits(ax, i) + fig.colorbar(ScalarMappable(norm=norm, cmap="turbo"), ax=axes, + label=r"$E\,v_\perp$ [W m]", shrink=.65, pad=.02) + fig.suptitle(title+"\n"+note, fontsize=12) + save(fig, out/"overview.png") + for label, row in zip(LABELS, rows): + print(f"{folder.name}: {label}: losses {row['count']}/{len(states[0])}; " + f"soft score {row['soft']:.9f}; mean lost E*v_perp " + f"{row['heat'].mean() if row['heat'].size else float('nan'):.9g} W m", flush=True) + print(f"Saved {out.resolve()}", flush=True) + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("runs", nargs="+", type=Path) + parser.add_argument("--wout", type=Path, help="Local copy of the run's unchanged classifier equilibrium") + args = parser.parse_args() + cache = {} + for folder in args.runs: + settings = json.loads((folder/"summary.json").read_text())["settings"] + wout = args.wout or Path(settings["wout"]) + if not wout.is_file(): + wout = INPUT/wout.name + if not wout.is_file(): + raise FileNotFoundError("Original classifier equilibrium missing; supply --wout") + key = (str(wout.resolve()), settings["surface_points"], settings["classifier_h"], settings["safety_margin"]) + if key not in cache: + print(f"Preparing the original fixed classifier from {wout.name}", flush=True) + surface = SurfaceRZFourier.from_wout_file(str(wout), s=1, + ntheta=key[1], nphi=key[1], range_torus="full torus") + boundary = ClassifierStop(SurfaceClassifier(surface, h=key[2], padding=max(.1, 1.5*key[3]))) + cache[key] = surface, boundary + plot_run(folder, *cache[key], settings) + + +if __name__ == "__main__": + main() diff --git a/examples/input_files/QI_opt_coils_essos_5.json b/examples/input_files/QI_opt_coils_essos_5.json new file mode 100644 index 00000000..da936913 --- /dev/null +++ b/examples/input_files/QI_opt_coils_essos_5.json @@ -0,0 +1,254 @@ +{ + "nfp": 2, + "stellsym": true, + "order": 6, + "n_segments": 60, + "dofs_curves_raw": [ + [ + [ + 16.155636305699783, + 5.2356787736233565, + 1.2359911128825818, + 0.5295595100682028, + -0.7223334369979009, + 0.06464560899002597, + -0.05544060339308811, + -0.006313375238318115, + -0.008926011544764693, + -0.0004876919104011803, + -0.00031357224186313816, + 0.00019107520196244302, + -1.2024084172037508e-05 + ], + [ + 2.9613922516381823, + 0.19391189015126029, + 3.8370634943602138, + -0.01101331685189782, + -0.24335881993737365, + 0.5788370115982625, + -0.37781507699734207, + 0.011025682062643444, + 0.002254998707533778, + -0.0008539108345051103, + 0.0038859640402681417, + 0.0001511571336913123, + 0.00027096892088457087 + ], + [ + -2.017364513492174, + -0.13441790090538777, + 5.856601983993343, + 2.2045772425673764, + 0.7138454425687819, + -0.30110895195041226, + 0.3114971853307977, + -0.00496897477958369, + 0.0065205670273770526, + 0.0007466520892819779, + -0.0014475392667390732, + -0.00012886257969235219, + 3.303581588776989e-06 + ] + ], + [ + [ + 15.346639292583694, + 4.996763279653159, + 0.9503940371674736, + -0.6573787644655633, + -1.4371161501517735, + 0.004742402110799854, + -0.05400739922516495, + 0.019212880042301643, + 0.005561546654567476, + 0.0001660477541015725, + 0.0014389680107628924, + -4.6170136237585334e-05, + 4.4495678680055236e-05 + ], + [ + 8.77732463010045, + 1.7446217248328417, + 3.454902563235903, + 0.010593408286874308, + -0.722065404460578, + 0.5194440951714187, + -0.24875221151400106, + 0.031523535424682336, + 0.01933820182100617, + -0.00107761724478171, + 0.002790999396075535, + -0.0003308831744207904, + 1.888533063311385e-06 + ], + [ + -5.216485529051776, + -1.130663483566804, + 6.217156212929919, + 1.3592207339153928, + 0.8897026960720864, + -0.287086463910678, + 0.24675085789707848, + -0.02947499768143196, + -0.012514687271580779, + 0.0006729848835203368, + -0.002825711170175339, + 0.00022185927956423852, + -2.3061829846733293e-05 + ] + ], + [ + [ + 11.340004184740463, + 2.601216515182227, + 2.164617783513445, + 0.48996352322710074, + -0.41098605634815477, + -0.133599546527975, + -0.19214123227304544, + 0.011459447286759454, + -0.02121319181462201, + 0.0019115524402099843, + 0.0009646703007296914, + -1.6678202795446426e-05, + 0.0002567838912942542 + ], + [ + 14.223937954780379, + 4.840966340598378, + 2.165772669699287, + -0.7874813440510238, + 0.034333645820993366, + 0.0869290588776922, + -0.035836103777948616, + 0.011043891614696872, + 0.0058590056971479145, + -0.00012007874865772608, + 0.0011579738786593142, + -7.655388801808769e-05, + -1.1567194301175158e-05 + ], + [ + -8.249303507829792, + -0.8633568585403878, + 7.707067586618187, + 0.09328566194135003, + 0.34983756243698916, + -0.07861549958462212, + 0.07439563891597378, + -0.011778864708363443, + -0.0022437977228318296, + -0.0008104949599339625, + -0.0010009160667646942, + 2.7634475429862017e-05, + -9.0895643192136e-05 + ] + ], + [ + [ + 6.846976953839684, + 0.1972683415776897, + 3.2407184529260693, + -0.3722389119076819, + -2.507101392939118, + 0.2330343175109371, + -0.3254121093224774, + 0.03434655055076893, + -0.005441117896106274, + 0.0014717495446099117, + 0.0023235966710538933, + -0.00011661824187243144, + 0.00026179065071122 + ], + [ + 15.483093885508811, + 5.225804184458776, + 1.678260229321091, + -0.9676815662554781, + -0.9103260091017761, + 0.016757674493701222, + -0.027978011659940388, + -0.004222475749853247, + 0.003814480818321295, + -0.0002164148973710951, + -0.0013732214972965678, + 0.00013725367538833632, + -8.182561590135934e-05 + ], + [ + -5.38007530831794, + 0.6010363924373548, + 4.9847137125206755, + 1.2887822309769756, + 0.048359073575503, + 0.0941097560401785, + 0.15128766731687224, + -0.00464461874476862, + 0.01380421415446056, + -0.0005552972330689962, + 0.001013747372038928, + -6.056003508151553e-05, + 5.9605091078975595e-05 + ] + ], + [ + [ + 2.4627428428759885, + -0.18640697195972258, + 3.783831999631245, + -1.484008814380631, + -1.6629066482585035, + -0.07688940634847238, + -0.17953879433559491, + -0.0002128497608101822, + -0.00870076131278896, + 0.0013992288786393071, + -0.0014827888237588334, + 4.715537666622463e-05, + -4.3621035986738046e-05 + ], + [ + 16.180454756995697, + 6.754442609471512, + 1.5182061356664562, + -0.4106184673952501, + -0.6909524947259235, + 0.023883946138595045, + 0.006187149605544186, + 0.0025356027736772786, + -0.0005489314385078558, + -0.0005735205268066593, + -9.825250261535214e-05, + 3.906302804030308e-05, + -3.576176247960722e-05 + ], + [ + -1.915091224437484, + 0.4548251534676736, + 3.3847448123876793, + 1.532547422477969, + 0.07924258511907706, + 0.10924516067871172, + 0.07556330839776348, + 0.007229950683363023, + -0.00906047406472728, + 0.00044137152909370453, + 0.0002753055918563237, + 0.00013927733395914424, + -3.933544221247448e-05 + ] + ] + ], + "scaling_type": Infinity, + "scaling_factor": 1.2, + "scale_fixed": 1.0, + "dofs_currents_raw": [ + 1.6480386481840175, + 1.2564451255256068, + 0.8019029994314764, + 0.5691502936080739, + 0.745845851723556 + ], + "currents_scale": null +} \ No newline at end of file diff --git a/examples/input_files/wout_QI_nfp2_stable_Er_006_000043_hires_scaled.nc b/examples/input_files/wout_QI_nfp2_stable_Er_006_000043_hires_scaled.nc new file mode 100644 index 00000000..068093e9 Binary files /dev/null and b/examples/input_files/wout_QI_nfp2_stable_Er_006_000043_hires_scaled.nc differ diff --git a/tests/test_dynamics.py b/tests/test_dynamics.py index 739be077..0c78aa5b 100644 --- a/tests/test_dynamics.py +++ b/tests/test_dynamics.py @@ -186,6 +186,7 @@ def _tolerance_controller(model, axis_regular, flag=False, atol=1e-8, size=4): tracing = Tracing.__new__(Tracing) tracing.model, tracing._axis_regular, tracing.field = model, axis_regular, None + tracing.integrator = "diffrax" tracing.initial_conditions = jnp.ones((1, size)) tracing.rtol, tracing.atol = 1e-7, atol tracing.timestep, tracing.solver = .1, None diff --git a/tests/test_native_ad.py b/tests/test_native_ad.py new file mode 100644 index 00000000..463ae95a --- /dev/null +++ b/tests/test_native_ad.py @@ -0,0 +1,490 @@ +"""Small accepted-path oracles; no long tracing or Monte Carlo runs in CI.""" +import jax +import jax.numpy as jnp +import numpy as np +import pytest +from essos.rk import solve_rk +from essos.split import solve_split, CollisionStep, move_in_cartesian +from essos.native_ad import replay_accepted_split, _OrbitRecorder, replay_accepted + + +def kernels(): + def rhs(t,y,p): + return p[0]*jnp.sin(y+12*t) + def kick(t,y,h,dw,p): + return CollisionStep(y-p[2]*h*y+p[1]*(.7+.1*y)*dw, + (h/(.04*jnp.exp(p[3])))**2,jnp.array(0.)) + return rhs,kick + + +def settings(method='dopri8', segment=3): + return dict(t1=.4,dt0=.3,ts=jnp.array([0.,0.,.13,.4]), + key=jax.random.key(71),noise_dim=1,method=method,rtol=1e-8,atol=1e-8, + max_steps=64,max_orbit_steps=32,adjoint_checkpoint_steps=segment, + adjoint_orbit_checkpoint_steps=segment,adjoint_max_accepted_steps=32, + adjoint_max_orbit_steps=128) + + +def cost(out): + return jnp.sum(out.ys**2)+.3*jnp.sum(out.y**2) + + +@pytest.mark.parametrize('method',['dopri5','dopri8']) +def test_split_reverse_matches_frozen_jvp_with_rejections(method): + rhs,kick=kernels();p=jnp.array([.8,.1,.2,0.]);y=jnp.array([.7]);o=settings(method) + out,tape=jax.jit(lambda p:solve_split(rhs,kick,y,p,_record_ad=True,**o))(p) + assert out.status==0 and out.stats.rejected>0 and out.stats.orbit_rejected>0 + def frozen(p): + saved,terminal=replay_accepted_split(rhs,kick,y,p,tape,o['ts'],method=method) + return jnp.sum(saved**2)+.3*jnp.sum(terminal**2) + value,gradient=jax.jit(jax.value_and_grad(lambda p:cost(solve_split(rhs,kick,y,p,adjoint='accepted',**o))))(p) + direction=jnp.array([.2,-.3,.4,.5]) + expected,tangent=jax.jit(lambda p,d:jax.jvp(frozen,(p,),(d,)))(p,direction) + np.testing.assert_allclose(value,expected,rtol=3e-12) + np.testing.assert_allclose(jnp.dot(gradient,direction),tangent,rtol=3e-10,atol=1e-11) + assert gradient[3]==0 # acceptance-only parameter is frozen + + +@pytest.mark.parametrize('method',['dopri5','dopri8']) +def test_orbit_dense_output_and_checkpoint_sizes(method): + rhs=lambda t,y,p:p*jnp.sin(y+t) + y=jnp.array([.7]);p=jnp.array(.3) + o=dict(t1=.4,dt0=.12,ts=jnp.array([0.,.031,.17,.4]),method=method,max_steps=32) + out,tape=jax.jit(lambda p:solve_rk(rhs,y,p,_recorder=_OrbitRecorder(32,3),**o))(p) + def frozen(p): + saved,terminal=replay_accepted(rhs,y,p,tape,o['ts'],method=method) + return jnp.sum(saved**2)+.3*jnp.sum(terminal**2) + expected,tangent=jax.jvp(frozen,(p,),(jnp.ones_like(p),)) + for segment in (1,3,8): + value,gradient=jax.jit(jax.value_and_grad(lambda p:cost(solve_rk(rhs,y,p, + adjoint='accepted',adjoint_checkpoint_steps=segment,**o))))(p) + np.testing.assert_allclose(value,cost(out),rtol=3e-13) + np.testing.assert_allclose(value,expected,rtol=3e-13) + np.testing.assert_allclose(gradient,tangent,rtol=2e-10) + + +def test_chart_kick_has_exact_inverse_derivative_including_gauge(): + def position(y): + u,w=y[0]*jnp.cos(y[5])-y[1]*jnp.sin(y[5]),y[1]*jnp.cos(y[5])+y[0]*jnp.sin(y[5]) + return jnp.array([(3+u)*jnp.cos(y[2]),(3+u)*jnp.sin(y[2]),w]) + y=jnp.array([.2,.1,.3,2.,.4,.2]);delta=jnp.array([.03,-.02,.04]) + def fn(y,delta):return position(move_in_cartesian(y,delta,position,implicit=True)) + by,bd=jax.jit(jax.jacrev(fn,argnums=(0,1)))(y,delta) + np.testing.assert_allclose(bd,jnp.eye(3),atol=5e-14) + np.testing.assert_allclose(by,jax.jacfwd(position)(y),atol=8e-14) + np.testing.assert_array_equal(move_in_cartesian(y,delta,position)[3:],y[3:]) + + +def test_split_events_hold_saves_and_skip_collision_derivatives(): + rhs=lambda t,y,p:jnp.ones_like(y)*p[0] + kick=lambda t,y,h,dw,p:CollisionStep(y+p[1]*dw,jnp.array(0.),jnp.array(0.)) + o=dict(t1=1.,dt0=.5,ts=jnp.array([0.,.7,1.]),key=jax.random.key(1),noise_dim=1, + event=lambda t,y,p:.2-y[0],adaptive=False,orbit_adaptive=False,max_steps=8,max_orbit_steps=8) + value,g=jax.jit(jax.value_and_grad(lambda p:cost(solve_split(rhs,kick,jnp.zeros(1),p, + adjoint='accepted',**o))))(jnp.array([1.,.3])) + assert np.isfinite(value) and np.isfinite(g).all() and g[1]==0 + # Event fraction is frozen: endpoint sensitivity is the recorded crossing time. + np.testing.assert_allclose(g[0],2*.2*.2*2.3,atol=2e-13) + + +def test_failed_or_capacity_limited_reverse_raises(): + rhs,kick=kernels();o=settings();o.update(adaptive=False,orbit_adaptive=False,dt0=.1,orbit_dt0=.01, + adjoint_max_orbit_steps=1) + f=jax.jit(jax.grad(lambda p:cost(solve_split(rhs,kick,jnp.array([.7]),p,adjoint='accepted',**o)))) + with pytest.raises(Exception,match='capacity exceeded'): + jax.block_until_ready(f(jnp.array([.8,.1,.2,0.]))) + + +def test_closure_parameters_initial_state_and_custom_jvp_are_preserved(): + @jax.custom_jvp + def nonlinear(y):return jnp.sin(y) + @nonlinear.defjvp + def tangent(primals,tangents): + y,=primals;dy,=tangents + return nonlinear(y),3*jnp.cos(y)*dy + o=dict(t1=.2,dt0=.1,ts=jnp.array([0.,.13,.2]),adaptive=False,max_steps=4) + def run(p,record=False): + rhs=lambda t,y,a:p[0]*nonlinear(y) + return solve_rk(rhs,p[1:],adjoint='none' if record else 'accepted', + _recorder=_OrbitRecorder(4,2) if record else None,**o) + p=jnp.array([.3,.7]);out,tape=jax.jit(lambda p:run(p,True))(p) + def frozen(p): + saved,final=replay_accepted(lambda t,y,a:p[0]*nonlinear(y),p[1:],None,tape,o['ts'],method='dopri5') + return jnp.sum(saved**2)+.3*jnp.sum(final**2) + gradient=jax.jit(jax.grad(lambda p:cost(run(p))))(p) + _,expected=jax.jvp(frozen,(p,),(jnp.array([.2,.4]),)) + np.testing.assert_allclose(gradient@jnp.array([.2,.4]),expected,rtol=3e-11) + + +def test_gpu_recorder_interpretation_keeps_primal_noise_and_sparse_nodes(): + from essos.split import _prepare_split_kernel, scalar,_register_kernel_placement + placement=_register_kernel_placement();value=jnp.array([1.,2.]) + assert placement(None,value,devices=(None,),srcs=(None,))[0] is value + with pytest.raises(NotImplementedError,match='explicit device transfers'): + placement(None,value,devices=(object(),),srcs=(None,)) + def factory(refs,y0): + zero=scalar(y0,7) + def rhs(y):return jnp.where(jnp.arange(8)==0,zero+1,zero) + def kick(y,h,w):return y+jnp.where(jnp.arange(8)==3,scalar(w,0),zero),zero,zero + return rhs,kick,lambda y,e,v,b:zero,lambda y:zero+1 + options=dict(adaptive=False,dt0=.1,dtmax=.1,speed=1.,orbit_dt0=.025, + max_steps=8,max_orbit_steps=8,interpret=True,adjoint_max_orbit_steps=16, + adjoint_orbit_checkpoint_steps=2,adjoint_max_accepted_steps=8) + times=jnp.array([0.,.1,.2]);y=jnp.zeros(8);key=jax.random.PRNGKey(3) + ordinary=jax.jit(_prepare_split_kernel((),factory,times,**options))(y,key) + recorded,tape=jax.jit(_prepare_split_kernel((),factory,times,record=True,**options))(y,key) + for left,right in zip(ordinary,recorded):np.testing.assert_array_equal(left,right) + assert tape.count==2 and tape.orbit_count==8 and tape.checkpoint_count==4 + assert tape.initial_saves==1 + np.testing.assert_array_equal(tape.offsets[:3],[0,4,8]) + np.testing.assert_allclose(tape.orbit_states[:4,0],[0.,.05,.1,.15],atol=2e-15) + rhs=lambda t,y,a:jnp.where(jnp.arange(8)==0,1.,0.) + kick=lambda t,y,h,dw,a:CollisionStep(y.at[3].add(dw[0]),jnp.array(0.),jnp.array(0.)) + saved,final=jax.jit(lambda:replay_accepted_split(rhs,kick,y,None,tape,times))() + np.testing.assert_allclose(saved,recorded[0],atol=2e-15) + np.testing.assert_allclose(final,recorded[1],atol=2e-15) + + +def test_exact_coil_field_transpose_includes_jacobian_sensitivities(): + from tests.test_native_orbit import coil_field + from essos.rk import _coil_geometry + from essos.native_ad import _field_transpose, _reverse_field_values + field=coil_field();arrays,nc,nq=_coil_geometry(field) + x=tuple(jnp.asarray(v) for v in (1.1,.03,.02)) + b=tuple(jnp.asarray(v) for v in (.2,-.3,.4)) + bj=tuple(tuple(jnp.asarray(v) for v in row) for row in ((.2,.4,.3),(-.1,.5,.2),(.4,.3,-.2))) + for gc in (False,True): + seed=(b,bj if gc else None) + expected=jax.vjp(lambda p,g:_reverse_field_values(g,p,nc,nq,gc),x,arrays)[1](seed) + actual=_field_transpose(arrays,x,b,seed[1],nc,nq,gc) + for left,right in zip(jax.tree.leaves(actual),jax.tree.leaves(expected)): + np.testing.assert_allclose(left,right,rtol=5e-12,atol=3e-12) + + +def test_gc_spatial_kick_gradient_uses_new_position_and_magnetic_moment(): + from tests.test_native_orbit import coil_field + from tests.test_native_split import bath + from essos.constants import ALPHA_PARTICLE_MASS as mass, ALPHA_PARTICLE_CHARGE as charge + from essos.rk import _coil_geometry + from essos.native_ad import _kick, coefficient_graph + from essos.split import (guiding_center_collision_step, collision_coefficients, + guiding_center_spatial_increment) + field=coil_field();arrays,nc,nq=_coil_geometry(field);background=bath() + graph=coefficient_graph(background,False);constants=tuple(graph.consts) + y=jnp.array([1.1,.03,.02,2e5,1e-15,0.,0.,0.]);h=1e-9 + dw=jnp.array([.2,-.3,.4,-.5,.3])*jnp.sqrt(h) + def production(y): + B=field.AbsB(y[:3]);speed=jnp.sqrt(y[3]**2+2*y[4]*B/mass) + c=collision_coefficients(background,mass,charge,speed,y[:3]);pitch=y[3]/speed + step=guiding_center_collision_step(speed,pitch,h,dw[-2:],c,speed_floor=1.) + dx=guiding_center_spatial_increment(pitch,dw[:3],c,field.B(y[:3])/B,charge*B/mass) + point=y[:3]+dx;v,xi=step.y + return y.at[:3].set(point).at[3].set(v*xi).at[4].set(mass*v*v*(1-xi*xi)/(2*field.AbsB(point))) + def native(y): + return jnp.asarray(_kick(tuple(y),arrays,constants,jnp.asarray(1.),h,tuple(dw),graph,nc,nq,True,spatial_diffusion=True)) + scale=jnp.array([1.,1.,1.,1e5,1e-15,1.,1.,1.]);direction=scale*jnp.array([.1,.2,-.1,.3,.2,0.,0.,0.]) + left,dl=jax.jvp(native,(y,),(direction,));right,dr=jax.jvp(production,(y,),(direction,)) + np.testing.assert_allclose(left/scale,right/scale,rtol=5e-12,atol=2e-13) + np.testing.assert_allclose(dl/scale,dr/scale,rtol=5e-11,atol=2e-12) + + +def test_ad_configuration_rejects_invalid_modes_and_capacities(): + from essos.split import trace_split + for value in (0,-1,True,1.5): + with pytest.raises(ValueError):_OrbitRecorder(8,value) + for options in (dict(adjoint='bad'),dict(reverse_execution='bad'), + dict(adjoint='accepted',adjoint_orbit_checkpoint_steps=0), + dict(adjoint='accepted',reverse_execution='independent'), + dict(adjoint='accepted',_replay_tapes=object())): + with pytest.raises(ValueError):trace_split(None,None,None,tmax=.1,timestep=.1,**options) + + +def test_native_tracing_api_and_array_objectives_receive_physical_gradients(): + from types import SimpleNamespace + from tests.test_native_orbit import UniformField + from essos.dynamics import Particles,Tracing + from essos.particle_losses import (mean_final_radius,classifier_loss_fraction, + classifier_loss_location,classifier_energy_cost) + def objective(v): + p=Particles(jnp.zeros((1,3)),initial_vparallel_over_v=[.2],mass=1.,charge=1.,energy=.5, + initial_xyz_fullorbit=jnp.zeros((1,3)),initial_vxvyvz=jnp.array([[v,0.,.2]])) + out=Tracing(field=UniformField(),particles=p,model='FullOrbitAdaptative',integrator='essos_dopri8', + native_adjoint='accepted',maxtime=.2,timestep=.1,times_to_trace=3,max_steps=16,progress=False) + return jnp.sum(out.trajectories[0,-1,:3]**2) + gradient=jax.jit(jax.grad(objective))(jnp.array(.3)) + np.testing.assert_allclose(gradient,8*.3*np.sin(.1)**2,rtol=2e-10) + states=jnp.array([[[0.,0.,0.,.2,.3,.4],[.2,0.,0.,.2,.3,.4]], + [[0.,0.,0.,.2,.3,.4],[.3,0.,0.,.2,.3,.4]]]) + boundary=SimpleNamespace(evaluate_xyz=lambda x:.5-x[0]) + np.testing.assert_allclose(mean_final_radius(states,0.,0.),.25,atol=2e-12) + np.testing.assert_allclose(classifier_loss_fraction(states,boundary,softness=4.), + jnp.mean(jax.nn.sigmoid(jnp.array([-1.2,-.8]))),rtol=1e-14) + distance=classifier_loss_location(states,jnp.array([1.,0.,0.]),boundary) + assert .71e-8 + + +@pytest.mark.parametrize('gc',[False,True]) +def test_persistent_reverse_kernel_matches_complete_frozen_map_on_cpu(gc): + from tests.test_native_orbit import coil_field + from tests.test_native_split import bath + from essos.rk import _coil_geometry + from essos.native_ad import (_rhs_from_field,_reverse_field_values,_kick,physical_graphs,reverse_kernel) + field=coil_field();geometry,nc,nq=_coil_geometry(field);background=bath();floor=jnp.array(1.) + # Rate derivatives are checked above. Constant coefficients keep this + # complete RK/kick transpose fixture small enough for CPU-only CI. + diffusion=jnp.array(1e10) + flag=jnp.array(True) + coefficients=jax.make_jaxpr(lambda v:(jax.device_put(jnp.where(flag,diffusion,0.)),2*diffusion,jnp.array(0.), + jnp.array(-1e8),jnp.array(0.),jnp.array(0.)))(jnp.array(4e5)) + graphs=physical_graphs(geometry,background,floor,nc,nq,gc, + active_coefficients=False,active_floor=False,spatial_diffusion=gc, + coefficient_data=(coefficients.jaxpr,coefficients.consts)) + n=5 if gc else 6 + initial=jnp.array([1.1,.03,.02,2e5,1e-15] if gc else [1.1,.03,.02,1e5,2e5,3e5]) + def rhs(t,y,p): + state=tuple(jnp.pad(y,(0,8-n))) + return jnp.asarray(_rhs_from_field(state,*_reverse_field_values(p,state[:3],nc,nq,gc),gc))[:n] + def kick(t,y,h,dw,p): + state=_kick(tuple(jnp.pad(y,(0,8-n))),p,tuple(coefficients.consts),floor, + h,tuple(dw),coefficients,nc,nq,gc,spatial_diffusion=gc) + return CollisionStep(jnp.asarray(state)[:n],jnp.array(0.),jnp.array(0.)) + times=jnp.array([0.,1e-9]);options=dict(t1=1e-9,dt0=1e-9,ts=times,key=jax.random.key(3), + noise_dim=5 if gc else 3,adaptive=False,orbit_adaptive=False,max_steps=4,max_orbit_steps=4, + adjoint_orbit_checkpoint_steps=1,_collision_state_indices=None if gc else (3,4,5)) + out,tape=jax.jit(lambda:solve_split(rhs,kick,initial,geometry,_record_ad=True,**options))() + assert tape.count==1 and tape.orbit_count==1 + scale=jnp.array([1.,1.,1.,1e5,1e-15] if gc else [1.,1.,1.,1e5,1e5,1e5]) + saved_bar=jnp.ones((2,n))/scale;terminal_bar=.3/scale + def frozen(y,p): + from essos.rk import dopri8_step + endpoint=dopri8_step(rhs,0.,y,1e-9,p).y + terminal=kick(1e-9,endpoint,1e-9,tape.increments[0],p).y + saved=jnp.stack((y,terminal)) + return jnp.sum(saved*saved_bar)+jnp.sum(terminal*terminal_bar) + expected=jax.jit(lambda:jax.vjp(frozen,initial,geometry)[1](jnp.array(1.)))() + actual=jax.jit(lambda:reverse_kernel(out.y,(geometry,tuple(coefficients.consts),floor),tape, + saved_bar,terminal_bar,times,graphs[:3],gc=gc,segment_steps=1,spatial_diffusion=gc,interpret=True))() + for left,right in zip(jax.tree.leaves(actual[:2]),jax.tree.leaves(expected)): + np.testing.assert_allclose(left,right,rtol=2e-9,atol=2e-11) + for value,bar in zip(coefficients.consts,actual[2]): + if value.dtype==jnp.bool_:assert bar.dtype==jax.dtypes.float0 + + +def test_qi_alm_line_heat_and_upper_bound_constraints(monkeypatch,tmp_path): + from types import SimpleNamespace + from essos.particle_losses import classifier_line_loss, classifier_energy_cost + from examples.coil_optimization.native_gc_alm import (make_constraints, boundary_line, + compile_optimizer,field_normal_ratio,save_coil_iteration) + from essos import augmented_lagrangian as alm + from essos.surfaces import SurfaceRZFourier,BdotN_over_B + from essos.fields import BiotSavart + from tests.test_native_orbit import UniformField,coil_field + boundary=SimpleNamespace(evaluate_xyz=lambda x:-x[0]) + states=jnp.array([[[1.,.2,0.,.2,.3,.4],[2.,.4,0.,.2,.3,.4]], + [[.5,.3,0.,.2,.3,.4],[1.5,.7,0.,.2,.3,.4]]]) + probability=jax.nn.sigmoid(30*states[...,0]);total=probability.sum(axis=0) + centroids=(states[...,:3]*probability[...,None]).sum(axis=0)/(total[:,None]+1e-8) + expected=jnp.sum(jnp.linalg.norm(centroids[:,1:],axis=1)*(total/2)/(1+10*total/2)) + np.testing.assert_allclose(classifier_line_loss(states,jnp.zeros(3),jnp.array([1.,0.,0.]),boundary),expected,rtol=1e-12) + energy=classifier_energy_cost(states,UniformField(),1.,1.,'FullOrbit',boundary) + assert energy>0 and np.isfinite(jax.grad(lambda y:classifier_line_loss(y,jnp.zeros(3), + jnp.array([1.,0.,0.]),boundary))(states)).all() + torus=SurfaceRZFourier(jnp.array([3.,1.]),jnp.array([0.,1.]),1,1,0) + point,direction=boundary_line(torus,0.,0.,'fixed_theta') + np.testing.assert_allclose(point,[4.,0.,0.],atol=1e-14) + np.testing.assert_allclose(direction,[0.,1.,0.],atol=1e-14) + coils=coil_field().coils + def flux(x,direct): + field=BiotSavart(coils.with_dofs(coils.dofs+x)) + ratio=field_normal_ratio(torus,field) if direct else BdotN_over_B(torus,field) + return jnp.sum(ratio**2) + expected=jax.jit(jax.value_and_grad(lambda x:flux(x,False)))(jnp.zeros_like(coils.dofs)) + actual=jax.jit(jax.value_and_grad(lambda x:flux(x,True)))(jnp.zeros_like(coils.dofs)) + for a,b in zip(actual,expected):np.testing.assert_allclose(a,b,rtol=3e-12,atol=3e-12) + from essos.coils import Coils + coils.to_json(str(tmp_path/"initial_coils.json")) + for iteration in (0,1): + parameters=jnp.full_like(coils.dofs,.03*iteration) + changed=coils.with_dofs(coils.dofs+.05*parameters) + save_coil_iteration(tmp_path,iteration,changed.dofs,parameters) + with np.load(tmp_path/"iterations"/f"{iteration:06d}.npz",allow_pickle=False) as data: + assert data['iteration']==iteration + np.testing.assert_array_equal(data['parameters'],parameters) + recovered=Coils.from_json(str(tmp_path/"initial_coils.json")).with_dofs(data['coil_dofs']) + np.testing.assert_allclose(recovered.gamma,changed.gamma,atol=1e-14) + np.testing.assert_allclose(recovered.currents,changed.currents,rtol=1e-14) + geometry=lambda x:dict(axis=x[0],length=jnp.array([2.])-x[1],curvature=jnp.array([1.])-x[1]) + options=SimpleNamespace(penalty=1.,bdotn_weight=0.) + constraint=make_constraints(geometry,lambda x:x[0]**2,options) + feasible=jnp.zeros(2);bad=jnp.array([0.,3.]);lp=constraint.init(feasible) + assert float(constraint.loss(lp,feasible)[0])==0 + assert float(constraint.loss(lp,bad)[0])>0 + optimizer=alm.ALM_model_lbfgs(constraint,inner_maxiter=1) + monkeypatch.setattr(jax,'default_backend',lambda:'cpu') + assert compile_optimizer(optimizer) is optimizer + params=(bad,lp) + expected=jax.block_until_ready(optimizer.init(params)) + monkeypatch.setattr(jax,'default_backend',lambda:'gpu') + assert compile_optimizer(optimizer,independent=False) is optimizer + compiled=compile_optimizer(optimizer) + actual=jax.block_until_ready(compiled.init(params)) + for a,b in zip(jax.tree_util.tree_leaves(actual),jax.tree_util.tree_leaves(expected)): + np.testing.assert_allclose(a,b,rtol=1e-13,atol=1e-13) + + expected=jax.block_until_ready(optimizer.update(params,*expected)) + actual=jax.block_until_ready(compiled.update(params,*actual)) + for a,b in zip(jax.tree_util.tree_leaves(actual),jax.tree_util.tree_leaves(expected)): + np.testing.assert_allclose(a,b,rtol=1e-13,atol=1e-13) + + from examples.coil_optimization.native_gc_alm import scipy_optimizer, DEFAULTS + monkeypatch.setattr(jax,'default_backend',lambda:'cpu') + constraint=alm.combine(alm.eq(lambda x:x-jnp.array([2.,.25]))) + options=SimpleNamespace(**dict(DEFAULTS,collisions=False,inner_maxiter=10)) + params=(jnp.zeros(2),constraint.init(jnp.zeros(2))) + scipy=scipy_optimizer(constraint,options) + state,gradient,info=scipy.init(params) + reference=alm.ALM_model_lbfgs(constraint).init(params) + for a,b in zip(jax.tree_util.tree_leaves((gradient,info)),jax.tree_util.tree_leaves(reference[1:])): + np.testing.assert_allclose(a,b,rtol=1e-13,atol=1e-13) + compile_seconds=state['compile_s'] + for _ in range(2): + params,state,gradient,info=scipy.update(params,state,gradient,info) + np.testing.assert_allclose(params[0],[1.,.25],atol=1e-7) + assert state['compile_s']==compile_seconds and len(state['inner_solves'])==2 + + +def test_specialized_multispecies_rates_and_classifier_grid(): + from types import SimpleNamespace + from jax.scipy.interpolate import RegularGridInterpolator + from jax.experimental import pallas as pl + from essos.background_species import BackgroundSpecies + from essos.constants import (ELECTRON_MASS,PROTON_MASS, + ALPHA_PARTICLE_MASS as mass,ALPHA_PARTICLE_CHARGE as charge) + from essos.split import ClassifierStop,_coefficient_graph,collision_coefficients + from essos.rk import _coil_geometry + def buffers(p,direct): + gamma=jnp.arange(45,dtype=float).reshape(3,5,3)*p[0] + tangent=jnp.sin(gamma)*p[1];currents=jnp.array([1.,2.,3.])*p[2] + if direct:return jnp.stack(_coil_geometry(SimpleNamespace(coils=SimpleNamespace( + gamma=gamma,gamma_dash=tangent,currents=currents)))[0]) + return jnp.stack([jnp.pad(a[:,:,i].T,((0,3),(0,1))).reshape(-1) + for a in (gamma,tangent*(currents*1e-7)[:,None,None]) for i in range(3)]) + for transform in (jax.jit,lambda f:jax.jit(jax.jacfwd(f))): + np.testing.assert_allclose(transform(lambda p:buffers(p,True))(jnp.array([.1,.3,1e7])), + transform(lambda p:buffers(p,False))(jnp.array([.1,.3,1e7])),rtol=1e-14,atol=1e-14) + from essos.coils import Coils,CreateEquallySpacedCurves + from essos.fields import BiotSavart + from essos.rk import _fourier_geometry + coils=Coils(CreateEquallySpacedCurves(3,2,1.,.4,7,2,True),jnp.array([1e6,2e6,3e6])) + def fourier(p,direct,limits=False): + c=coils.with_dofs(coils.dofs*p) + if limits: + if direct:_,tangent,second=_fourier_geometry(c.curves,second=True) + else:tangent,second=c.gamma_dash,c.gamma_dashdash + speed=jnp.linalg.norm(tangent,axis=-1) + curvature=jnp.linalg.norm(jnp.cross(tangent,second),axis=-1)/speed**3 + return jnp.concatenate((jnp.mean(speed,axis=-1),curvature.reshape(-1))) + if direct:return jnp.stack(_coil_geometry(BiotSavart(c))[0]) + nc,nq,_=c.gamma.shape;pc,pq=(1<<(n-1).bit_length() for n in (nc,nq)) + return jnp.stack([jnp.pad(a[:,:,i].T,((0,pq-nq),(0,pc-nc))).reshape(-1) + for a in (c.gamma,c.gamma_dash*(c.currents*1e-7)[:,None,None]) for i in range(3)]) + p=jnp.ones_like(coils.dofs);direction=jnp.sin(jnp.arange(p.size)+.2) + for limits in (False,True): + shape=fourier(p,True,limits).shape;seeds=jnp.cos(jnp.arange(np.prod(shape))).reshape(shape) + for direct in (False,True): + values,tangent=jax.jit(lambda p:jax.jvp(lambda p:fourier(p,direct,limits),(p,),(direction,)))(p) + gradient=jax.jit(lambda p,s:jax.vjp(lambda p:fourier(p,direct,limits),p)[1](s)[0])(p,seeds) + if not direct:expected=(values,tangent,gradient) + else: + for a,b in zip((values,tangent,gradient),expected): + np.testing.assert_allclose(a,b,rtol=2e-12,atol=2e-12) + for n in (2,3): + def rates(p,prepared): + bath=BackgroundSpecies(n,jnp.array([ELECTRON_MASS/PROTON_MASS,2.,3.][:n]), + jnp.array([-1.,1.,1.][:n]),jnp.full(n,4e20)*jnp.exp(p[0]),jnp.full(n,17800.)) + v=1.3e7*jnp.exp(p[1]) + if not prepared:return jnp.array(collision_coefficients(bath,mass,charge,v,jnp.zeros(3),full_orbit=True)) + graph=_coefficient_graph(bath,True) + assert all(c.shape==() for c in graph.consts) + return jnp.array(jax.core.eval_jaxpr(graph.jaxpr,graph.consts,v)) + p=jnp.array([.1,.02]) + for transform in (lambda f:jax.jit(f),lambda f:jax.jit(jax.jacfwd(f))): + np.testing.assert_allclose(transform(lambda p:rates(p,True))(p), + transform(lambda p:rates(p,False))(p),rtol=3e-11,atol=1e-5) + for radii in (jnp.linspace(.8,2.,7),jnp.array([.8,.9,1.2,1.5,1.6,1.9,2.])): + grid=(radii,jnp.linspace(0.,2*jnp.pi,9),jnp.linspace(-.8,.8,6)) + r,phi,z=jnp.meshgrid(*grid,indexing='ij') + interpolation=RegularGridInterpolator(grid,(r+2*jnp.cos(phi)+.3*z*z)[...,None],fill_value=-1.) + def evaluate(x):return interpolation(jnp.array([jnp.hypot(x[0],x[1]), + jnp.mod(jnp.arctan2(x[1],x[0]),2*jnp.pi),x[2]]))[0,0] + stop=ClassifierStop(SimpleNamespace(dist=interpolation,evaluate_xyz=evaluate),.2) + data,level=stop._kernel_view() + def sample(point): + def kernel(y,*refs):refs[-1][()]=level(refs[:-1],y[...]) + return pl.pallas_call(kernel,out_shape=jax.ShapeDtypeStruct((),jnp.float64),interpret=True)(point,*data) + points=jnp.array([[1.2,0.,.1],[0.,1.4,-.3],[-1.2,-.2,.5],[.2,0.,0.], + [1.2,-1e-12,0.],[1.2,1e-12,0.]]) + padded=jnp.pad(points,((0,0),(0,5))) + np.testing.assert_allclose(jax.jit(jax.vmap(sample))(padded), + jax.vmap(lambda y:jnp.maximum(0.,evaluate(y[:3])+.2))(padded),rtol=1e-14,atol=2e-14) + np.testing.assert_allclose(jax.vmap(stop.evaluate_xyz)(points), + jax.vmap(evaluate)(points),rtol=1e-14,atol=2e-14) + np.testing.assert_allclose(jax.jit(jax.vmap(jax.grad(stop.evaluate_xyz)))(points), + jax.jit(jax.vmap(jax.grad(evaluate)))(points),rtol=2e-12,atol=2e-12) + from tests.test_native_orbit import coil_field + from essos.split import _prepare_split_field,guiding_center_collision_step + field=coil_field();y=jnp.array([1.,.03,.01,-2e5,1e-16,0.,0.,0.]) + bath=BackgroundSpecies(2,jnp.array([ELECTRON_MASS/PROTON_MASS,2.]), + jnp.array([-1.,1.]),jnp.full(2,4e20),jnp.full(2,17800.)) + def apply(floor): + data,factory=_prepare_split_field(field,bath,gc=True,collision_tolerance=.001, + speed_floor=floor,event=stop,state_size=5) + def kernel(yr,*refs): + _,kick,_,level=factory(refs[:-2],yr[...]) + refs[-2][...]=kick(yr[...],jnp.asarray(1e-9),jnp.zeros(8))[0] + refs[-1][()]=level(yr[...]) + return pl.pallas_call(kernel,out_shape=(jax.ShapeDtypeStruct((8,),y.dtype), + jax.ShapeDtypeStruct((),y.dtype)),interpret=True)(y,*data) + B=field.AbsB(y[:3]);v=jnp.sqrt(y[3]**2+2*y[4]*B/mass) + c=collision_coefficients(bath,mass,charge,v,y[:3]) + changed,level=jax.jit(apply)(jnp.asarray(1e4)) + speed,pitch=guiding_center_collision_step(v,y[3]/v,1e-9,jnp.zeros(2),c,speed_floor=1e4).y + expected=y.at[3].set(speed*pitch).at[4].set(mass*speed**2*(1-pitch**2)/(2*B)) + np.testing.assert_allclose(changed,expected,rtol=3e-12,atol=1e-20) + np.testing.assert_allclose(level,stop(0.,y),rtol=1e-14) diff --git a/tests/test_native_orbit.py b/tests/test_native_orbit.py new file mode 100644 index 00000000..6b6ca6c8 --- /dev/null +++ b/tests/test_native_orbit.py @@ -0,0 +1,379 @@ +"""Small forward contracts; GPU algebra is exercised on CPU via Pallas interpretation.""" +from pathlib import Path +from types import SimpleNamespace +import diffrax +import jax +import jax.numpy as jnp +import numpy as np +import pytest +from essos import rk +from essos.rk import OrbitErrorNorm + +jax.config.update('jax_enable_x64', True) + + +def oscillator(t,y,args): + return jnp.array([y[1],-y[0]]) + + +@pytest.mark.parametrize('method', ['dopri5','dopri8']) +def test_tableau_fsal_and_standard_dense_match_diffrax(method): + step_fn,interpolate,solver=((rk.rk45_step,rk.rk45_interpolate,diffrax.Dopri5()) if method=='dopri5' + else (rk.dopri8_step,rk.dopri8_interpolate,diffrax.Dopri8())) + y=jnp.array([1.,.2]); h=.1 + step=step_fn(oscillator,0.,y,h) + term=diffrax.ODETerm(oscillator) + yn,error,dense,_,_=solver.step(term,0.,h,y,None,solver.init(term,0.,h,y,None),False) + np.testing.assert_allclose(step.y,yn,rtol=0,atol=2e-15) + np.testing.assert_allclose(step.error,error,rtol=0,atol=2e-15) + reference=solver.interpolation_cls(t0=0.,t1=h,**dense) + for fraction in (0.,.2,.7,1.): + np.testing.assert_allclose(interpolate(y,h,step,fraction),reference.evaluate(fraction*h),atol=2e-14) + cached=step_fn(oscillator,h,step.y,h,f0=step.stages[-1]) + for a,b in zip(cached,step_fn(oscillator,h,step.y,h)): + np.testing.assert_array_equal(a,b) + + +@pytest.mark.parametrize('method', ['dopri5','dopri8']) +def test_adaptive_control_rejects_and_is_independent_of_saves(method): + for controller in ('i','pi'): + opts=dict(t1=2.,dt0=2.,rtol=1e-10,atol=1e-10,method=method,controller=controller, + max_steps=128,record_steps=True) + run=jax.jit(lambda saves:rk.solve_rk(oscillator,jnp.array([1.,0.]),ts=saves,**opts)) + a,b=run(jnp.array([0.,2.])),run(jnp.linspace(0,2,9)) + assert a.status==b.status==rk.RKStatus.SUCCESS and a.stats.rejected>0 + np.testing.assert_array_equal(a.stats,b.stats) + np.testing.assert_array_equal(a.step_ts,b.step_ts) + np.testing.assert_allclose(b.ys,jnp.stack((jnp.cos(b.ts),-jnp.sin(b.ts)),axis=1),atol=3e-8) + loop=jax.jit(lambda:rk.solve_rk(oscillator,jnp.array([1.,0.]),ts=jnp.array([0.,2.]), + stage_execution='loop',**opts))() + np.testing.assert_allclose(a.y,loop.y,atol=2e-12) + + +def test_fixed_clock_empty_duplicate_saves_and_zero_span(): + for solve in (rk.solve_rk45,rk.solve_dopri8): + a=jax.jit(lambda:solve(lambda t,y,a:jnp.ones_like(y),jnp.zeros(1),t0=.2,t1=1.2, + dt0=.1,adaptive=False,ts=jnp.array([.2,.2,.65,1.2]),max_steps=10))() + assert a.stats.accepted==10 and a.status==0 + np.testing.assert_allclose(a.ys[:,0],a.ts-.2,atol=2e-15) + z=solve(oscillator,jnp.array([1.,0.]),t1=0.,dt0=.1,ts=[0.,0.]) + assert z.stats.steps==0 + np.testing.assert_array_equal(z.ys,[[1.,0.],[1.,0.]]) + assert solve(oscillator,jnp.array([1.,0.]),t1=.1,dt0=.1).ys.shape==(0,2) + + +def test_levelset_boolean_initial_and_simultaneous_events(): + rhs=lambda t,y,a:jnp.ones_like(y) + for event,root,expected in (({'later':lambda t,y,a:.7-y[0],'first':lambda t,y,a:.3-y[0]},True,.3), + (lambda t,y,a:y[0]>.2,True,.4), + (lambda t,y,a:.3-y[0],False,.4), + (lambda t,y,a:y[0],True,0.)): + out=rk.solve_rk(rhs,jnp.zeros(1),t1=1.,dt0=.4,adaptive=False,ts=[0.,.1,.5,1.],event=event,root_find=root) + assert out.status==rk.RKStatus.EVENT + np.testing.assert_allclose(out.t,expected,atol=2e-15) + assert sum(map(bool,jax.tree_util.tree_leaves(out.event_mask)))==1 + if expected==0: + assert np.isinf(out.ys).all() + both=(lambda t,y,a:.3-y[0],)*2 + np.testing.assert_array_equal(rk.solve_rk(rhs,jnp.zeros(1),t1=1.,dt0=.4,event=both).event_mask,[True,False]) + + +def test_vmapped_particles_stop_independently(): + def one(v): + return rk.solve_rk(lambda t,y,a:jnp.ones_like(y)*v,jnp.zeros(1),t1=1.,dt0=.1, + event=lambda t,y,a:.3-y[0],max_steps=32) + out=jax.jit(jax.vmap(one))(jnp.array([1.,.1])) + np.testing.assert_array_equal(out.status,[1,0]) + np.testing.assert_allclose(out.t,[.3,1.],atol=2e-15) + + +def test_work_limits_nonfinite_and_recovery(): + for adaptive in (False,True): + out=rk.solve_rk(lambda t,y,a:jnp.full_like(y,jnp.nan),jnp.ones(1),t1=1.,dt0=.1, + adaptive=adaptive,dtmin=.1,max_steps=4) + assert out.status==rk.RKStatus.NONFINITE and out.t==0 + assert rk.solve_rk(oscillator,jnp.array([1.,0.]),t1=10.,dt0=.1,max_steps=1).status==rk.RKStatus.MAX_STEPS + assert rk.solve_rk(oscillator,jnp.array([1.,0.]),t1=10.,dt0=1.,dtmin=1.,atol=1e-15,rtol=0.).status==rk.RKStatus.MIN_STEP + rhs=lambda t,y,a:jnp.where(t>.3,jnp.nan,jnp.ones_like(y)) + out=rk.solve_rk(rhs,jnp.zeros(1),t1=.2,dt0=.2,max_steps=128) + assert out.status==0 + bad=rk.solve_rk(oscillator,jnp.array([1.,0.]),t1=1.,dt0=.1,event=lambda t,y,a:jnp.nan) + assert bad.status==rk.RKStatus.NONFINITE + + +def test_static_input_and_event_contracts(): + base=dict(t1=1.,dt0=.1) + invalid=[dict(method='rk4'),dict(controller='pid'),dict(stage_execution='x'),dict(max_steps=0), + dict(max_steps=True),dict(dt0=0),dict(dt0=np.inf),dict(t0=np.nan),dict(t1=-1), + dict(dtmin=-1),dict(dtmax=-1),dict(dtmin=.2),dict(dtmin=.1,dtmax=.01), + dict(atol=0),dict(rtol=-1),dict(ts=[.7,.2]),dict(ts=[2.]),dict(ts=[[0.]]), + dict(t0=[0.]),dict(controller='pi',pcoeff=-1),dict(controller='pi',icoeff=0), + dict(controller='pi',pcoeff=[.4]),dict(event=lambda t,y,a:jnp.ones(2)), + dict(event=lambda t,y,a:jnp.asarray(1)),dict(error_norm=lambda *a:jnp.ones(2))] + for change in invalid: + with pytest.raises(ValueError): + rk.solve_rk(oscillator,jnp.array([1.,0.]),**(base|change)) + for y in ([],[[1.]],jnp.array([1j])): + with pytest.raises(ValueError): + rk.solve_rk(oscillator,y,**base) + + +def test_dynamic_validation_and_physical_error_blocks(): + run=jax.jit(lambda dt,atol,p:rk.solve_rk(oscillator,jnp.array([1.,0.]),t1=1.,dt0=dt, + atol=atol,controller='pi',pcoeff=p,max_steps=16)) + for dt,atol,p in ((-1.,1e-9,.4),(.1,0.,.4),(.1,1e-9,-.4)): + assert run(dt,atol,p).status==rk.RKStatus.INVALID_INPUT + for components in (1,3): + norm=OrbitErrorNorm(1e-9,1e-9,10.,2.,components) + state=jnp.zeros(6); error=jnp.array([2e-9,0,0,1e-8,0,0]) + np.testing.assert_allclose(norm(state,state,error),.5) + mapped=OrbitErrorNorm(1e-9,1e-9,10.,2.,components,lambda y:2*y[:3]) + np.testing.assert_allclose(mapped(state,state,error),1.) + assert np.isinf(norm(state,state,jnp.full(6,jnp.nan))) + for options in (dict(velocity_components=2),dict(speed_scale=0.),dict(rtol=-1.),dict(length_scale=[1.])): + with pytest.raises(ValueError): + OrbitErrorNorm(**(dict(rtol=1e-9,atol=1e-9,speed_scale=1.)|options)) + + +class UniformField: + def B_contravariant(self,x): return jnp.array([0.,0.,1.]) + B_covariant=B_contravariant + def AbsB(self,x): return 1. + def dAbsB_by_dX(self,x): return jnp.zeros(3) + curl_b=kappa=dAbsB_by_dX + def sqrtg(self,x): return 1. + def to_xyz(self,x): return x + + +@pytest.mark.parametrize('model',['GuidingCenterAdaptative','FullOrbitAdaptative']) +def test_tracing_native_dispatch_matches_analytic_and_diffrax(model): + from essos.dynamics import Particles,Tracing + p=Particles(jnp.zeros((1,3)),initial_vparallel_over_v=[.2],mass=1.,charge=1.,energy=.5, + initial_xyz_fullorbit=jnp.zeros((1,3)),initial_vxvyvz=jnp.array([[.3,0.,.2]])) + opts=dict(field=UniformField(),particles=p,model=model,maxtime=.3,timestep=.1,times_to_trace=4,progress=False) + ref=Tracing(**opts) + for integrator in ('essos_rk45','essos_dopri8'): + out=Tracing(**opts,integrator=integrator) + assert out.rtol==out.atol==1e-9 + np.testing.assert_allclose(out.trajectories,ref.trajectories,atol=2e-9) + for options in (dict(integrator='x'),dict(integrator='essos_dopri8',solver=diffrax.Dopri8()), + dict(integrator='essos_dopri8',model='FullOrbitCollisions'), + dict(native_error_control='x'),dict(native_controller='x')): + with pytest.raises(ValueError): + Tracing(**(opts|options)) + standard=Tracing(**opts,integrator='essos_rk45',native_error_control='standard') + from essos.rk import _trace_error_norm as error_norm + assert error_norm(standard) is None + end=out._solve(*out._terms(None),0.,out.initial_conditions[0],out.args,diffrax.Event(lambda t,y,a:False),throw=True) + assert end.result==diffrax.RESULTS.successful + + +def coil_field(): + from essos.coils import Coils,CreateEquallySpacedCurves + from essos.fields import BiotSavart + return BiotSavart(Coils(CreateEquallySpacedCurves(1,1,1.,.4,7,1,False),[1e6])) + + +def test_private_coil_field_and_rhs_match_public_equations(): + from essos.rk import _coil_geometry as geometry, _coil_field_values as field_values, _coil_rhs_values as rhs_values + from essos.dynamics import Particles,GuidingCenter,Lorentz + from essos.electric_field import Electric_field_zero + field=coil_field(); arrays,nc,nq=geometry(field); x=jnp.array([1.,.03,.01]) + B,J=field_values(arrays,tuple(x),nc,nq,True) + np.testing.assert_allclose(B,field.B(x),atol=3e-15) + np.testing.assert_allclose(J,jax.jacfwd(field.B)(x),atol=3e-14) + p=Particles(x[None],initial_vparallel_over_v=[.3],mass=1.,charge=1.,energy=.5) + for model,y,rhs,args in (('gc',jnp.append(x,.3),GuidingCenter,(field,p,Electric_field_zero())), + ('lorentz',jnp.concatenate((x,jnp.array([.2,.1,.3]),jnp.zeros(2))),Lorentz,(field,p))): + actual=rhs_values(arrays,y,nc,nq,model,.5,1.,1.) + np.testing.assert_allclose(actual[:4 if model=='gc' else 6],rhs(0.,y[:4 if model=='gc' else 6],args),atol=3e-14) + + +def tokamak(): + from essos.boozer import BoozerField + s=np.linspace(.005,.995,5) + return BoozerField.from_booz(s,np.stack((s*0+5.,-.2*np.sqrt(s))),[0,1],[0,0], + s*0+.4,s*0+40.,s*0,40.,1,angle_grid=None) + + +def test_boozer_public_native_outputs_and_failures(monkeypatch): + from essos.boozer import trace_boozer + from essos.rk import trace_boozer_orbits as native_orbits + field=tokamak() + for method in ('essos_rk45','essos_dopri8'): + out=trace_boozer(field,[.3],[.4],[0.],[.2],speed=1.,mass=1.,charge=1.,tmax=.01, + timestep=.003,n_save=3,integrator=method,progress=False) + assert not out.failed.any() and not out.lost.any() and (out.step_stats[:,1]>0).all() + assert np.isfinite(out.states).all() + assert out.solver_status.shape==(1,) and out.terminal_states is None + with pytest.raises(ValueError,match='native_execution'): + native_orbits(field,None,None,1.,1.,1.,None,.1,1e-9,1e-9,'dopri8',True,'i',.4,.3,8,execution='bad') + kwargs=dict(speed=1.,mass=1.,charge=1.,tmax=.001,timestep=.001,n_save=2,integrator='essos_dopri8',progress=False) + legacy=trace_boozer(field,[.3],[.4],[0.],[.2],**(kwargs|dict(integrator=None,method='rk4'))) + assert np.isfinite(legacy.states).all() and legacy.step_stats is None + assert legacy.terminal_states.shape==(1,5) and np.isnan(legacy.terminal_states).all() + for change in (dict(integrator='x'),dict(method='rk4'),dict(species=object()),dict(adaptive='yes'),dict(rtol=-1.),dict(atol=0.)): + with pytest.raises(ValueError): trace_boozer(field,[.3],[.4],[0.],[.2],**(kwargs|change)) + from essos import rk as module + original=module._prepare_boozer_gpu + monkeypatch.setattr(module,'_prepare_boozer_gpu',lambda *a,**k:original(*a,**k,interpret=True)) + out=trace_boozer(field,[.3],[.4],[0.],[.2],**(kwargs|dict(native_execution='cuda',progress=lambda *a:None))) + assert not out.failed.any() + with pytest.raises(ValueError,match='I control'): + trace_boozer(field,[.3],[.4],[0.],[.2],**(kwargs|dict(native_execution='cuda',native_controller='pi'))) + with pytest.raises(ValueError,match='cosine'): + original(SimpleNamespace(table=1.,sine_coef=None),1.,1.,1.,[0.,.1],.1,1e-9,1e-9,8,interpret=True) + + +def test_vmec_private_values_match_current_main(monkeypatch): + from functools import partial + from essos.fields import Vmec + from essos.rk import _prepare_vmec_data as prepare, _vmec_quantities as quantities, _vmec_rhs_values as rhs_values, _vmec_xyz_values as xyz_values + from essos.dynamics import GuidingCenter,Particles,_axis_regular,_to_axis_regular + from essos.electric_field import Electric_field_zero + filename=Path(__file__).resolve().parents[1]/'examples/input_files/wout_LandremanPaul2021_QA_reactorScale_lowres.nc' + field=Vmec(str(filename),ntheta=3,nphi=3,mode_tolerance=1e-4) + prepared=prepare(field); x=jnp.array([.3,.4,.2]) + for s in (.3, 1e-8, .99999, float(field.s_half_grid[3])): + point=x.at[0].set(s) + actual=quantities(prepared.arrays,tuple(point),prepared.tables) + expected=(field.B_covariant(point),field.B_contravariant(point),field.AbsB(point),field.dAbsB_by_dX(point),field.curl_b(point),field.kappa(point),field.sqrtg(point)) + for a,b in zip(actual,expected): np.testing.assert_allclose(a,b,rtol=2e-12,atol=2e-12) + p=Particles(x[None],initial_vparallel_over_v=[.3],mass=1.,charge=1.,energy=.5) + y=jnp.pad(_to_axis_regular(jnp.append(x,.3)),(0,3)) + np.testing.assert_allclose(rhs_values(prepared.arrays,y,prepared.tables,1.,1.,.5)[:5], + _axis_regular(GuidingCenter)(0.,y[:5],(field,p,Electric_field_zero())),atol=3e-12) + np.testing.assert_allclose(xyz_values(prepared.arrays,y,prepared.tables),field.to_xyz(x),atol=3e-12) + from essos.rk import prepare_solver + args=dict(mass=1.,charge=1.,energy=.5,times=np.array([0.,.001]),dt0=.001,max_steps=8) + # Bound the real-equilibrium CPU reference graph on older XLA releases. + with monkeypatch.context() as patch: + patch.setattr(rk,'solve_rk',partial(rk.solve_rk,stage_execution='loop')) + reference=jax.jit(prepare_solver(field,**args))(y[:5]) + gpu=jax.jit(prepare_solver(field,execution='cuda',interpret=True,**args))(y[:5]) + np.testing.assert_allclose(gpu.y,reference.y,atol=3e-12) + for change in (dict(model='lorentz'),dict(execution='x'),dict(energy=-1),dict(execution='cuda',controller='pi')): + with pytest.raises(ValueError): prepare_solver(field,**(args|change)) + # Exercise segment dispatch on an analytic cylinder, avoiding compilation + # of the full equilibrium inverse map in this small CI integration test. + class Cylinder(UniformField,Vmec): + def __init__(self): self.Aminor_p=1. + def to_xyz(self,x): + r=jnp.sqrt(jnp.maximum(x[0],0.)) + return jnp.array([r*jnp.cos(x[1]),r*jnp.sin(x[1]),x[2]]) + def boundary_distance(self,x): return 1.-jnp.sqrt(x[0]**2+x[1]**2) + def flux_coordinates(self,x): + return jnp.array([x[0]**2+x[1]**2,jnp.arctan2(x[1],x[0]),x[2]]),True + from essos.dynamics import Tracing + trace=Tracing(field=Cylinder(),particles=p,model='GuidingCenterAdaptative',maxtime=.001,timestep=.001, + times_to_trace=2,integrator='essos_dopri8',progress=False,max_returns=1,exterior_field=UniformField()) + assert np.isfinite(trace.trajectories).all() + np.testing.assert_allclose(trace.trajectories[0,-1],jnp.array([.3,.4,.2003,.3]),atol=2e-14) + + +@pytest.mark.parametrize('method',['dopri5','dopri8']) +def test_independent_gpu_loop_on_cpu(method): + from essos.rk import _prepare_gpu_solver as prepare_gpu_solver + from essos.rk import _select_one + def factory(refs,point,invariant): + scalar=lambda y:_select_one(y,0,0).reshape(()) + return (lambda y:jnp.ones_like(y),lambda y,e,v:jnp.max(jnp.abs(e)),lambda y:.3-scalar(y)) + # Exercise repeated initial/interior saves in both Pallas save loops. + times=np.array([0.,0.,.1,.2,.2,.5]) + for adaptive in (False,True): + solve=prepare_gpu_solver((),factory,1.,times,.2,1e-9,1e-9,16,method=method, + adaptive=adaptive,interpret=True) + run=jax.jit(solve) + out=run(jnp.zeros(4),jnp.asarray(0.)) + assert out.status==rk.RKStatus.EVENT + np.testing.assert_allclose(out.t,.3,atol=2e-14) + np.testing.assert_allclose(out.ys[:-1],np.broadcast_to(times[:-1,None],(len(times)-1,4)),atol=2e-14) + assert np.isinf(out.ys[-1]).all() + invalid=run(jnp.full(4,jnp.nan),jnp.asarray(0.)) + assert invalid.status==rk.RKStatus.NONFINITE and invalid.stats.steps==0 + invalid=run(jnp.zeros(4),jnp.asarray(jnp.nan)) + assert invalid.status==rk.RKStatus.NONFINITE and invalid.stats.steps==0 + initial=run(jnp.full(4,.3),jnp.asarray(0.)) + assert initial.status==rk.RKStatus.EVENT and np.isinf(initial.ys).all() + base=dict(arrays=(),factory=factory,speed=1.,times=times,dt0=.2,rtol=1e-9,atol=1e-9,max_steps=16,interpret=True) + for change in (dict(method='rk4'),dict(times=[.1,.2]),dict(dt0=-1),dict(max_steps=0),dict(interpret=False)): + with pytest.raises(ValueError): prepare_gpu_solver(**(base|change)) + with pytest.raises(ValueError): solve(jnp.zeros(3),jnp.asarray(0.)) + limited=prepare_gpu_solver(**(base|dict(max_steps=1))) + result=jax.jit(limited)(jnp.zeros(4),jnp.asarray(0.)) + assert result.status==rk.RKStatus.MAX_STEPS and result.stats.accepted==1 + # A rejected first trial must retain its newly evaluated FSAL derivative. + def changing(refs,point,invariant): + return (lambda y:y,lambda y,e,v:jnp.max(jnp.abs(e)),lambda y:jnp.asarray(1.)) + for limit in (1,128): + retry=prepare_gpu_solver((),changing,1.,[0.,.25,1.],1.,1e-11,1e-11,limit, + method=method,adaptive=True,interpret=True) + recovered=jax.jit(retry)(jnp.ones(4),jnp.asarray(0.)) + assert recovered.stats.rejected>0 + if limit==1: + assert recovered.status==rk.RKStatus.MAX_STEPS and recovered.stats.accepted==0 + np.testing.assert_array_equal(recovered.y,np.ones(4)) + else: + assert recovered.status==rk.RKStatus.SUCCESS + np.testing.assert_allclose(recovered.y,np.full(4,np.e),rtol=1e-10) + + +def test_rhs_preparation_and_gpu_helpers_preserve_values(monkeypatch): + from essos.rk import _select_one, _kernel_is_finite, _bind_primitive + for dtype in (jnp.float32,jnp.float64): + values=jnp.array([1.,np.inf,np.nan,-np.inf,-0.],dtype=dtype) + np.testing.assert_array_equal(_kernel_is_finite(values),jnp.isfinite(values)) + assert np.signbit(_select_one(values,4,0).reshape(())) + class Primitive: + def get_bind_params(self,p): return ([],p) + def bind(self,*args,**kwargs): return args[0]+kwargs['offset'] + assert _bind_primitive(Primitive(),[2.],dict(offset=3.))==5. + # JAX 0.6 calls this boundary "pjit"; current releases call it "jit". + nested=jax.make_jaxpr(lambda x:x*jnp.array([2.,3.]))(jnp.ones(2)) + for name in ('jit','pjit'): + graph=SimpleNamespace(constvars=(),invars=('x',),outvars=('y',),eqns=( + SimpleNamespace(primitive=SimpleNamespace(name=name),params={'jaxpr':nested}, + invars=('x',),outvars=('y',)),)) + inline=lambda x:rk._evaluate_inline(graph,(),x)[0].sum() + np.testing.assert_allclose(jax.jit(inline)(jnp.ones(2)),5.,atol=0) + np.testing.assert_array_equal(jax.grad(inline)(jnp.ones(2)),[2.,3.]) + def value(p): + rhs=lambda t,y,args:jnp.sin(p)*y+t + prepared=rk._prepare_rhs(rhs,jnp.asarray(0.),jnp.ones(2),None) + return prepared(.2,jnp.array([2.,3.]),None).sum() + np.testing.assert_allclose(jax.grad(value)(.3),5*np.cos(.3),atol=2e-14) + with pytest.raises(TypeError): _kernel_is_finite(jnp.array([1],dtype=jnp.int32)) + import essos.rk as module + from essos import boozer as boozer_module + model=SimpleNamespace(modB_derivatives=lambda *a:(1.,0.,0.,0.)) + for f in (lambda field,y,*a:jnp.concatenate((y[:2],y[:2])), + lambda field,y,*a:jnp.concatenate((jax.lax.dynamic_slice(y,(y[0].astype(jnp.int32),),(2,)),jnp.ones(2)))): + monkeypatch.setattr(boozer_module,'guiding_center_rhs',f) + with pytest.raises(ValueError,match='slice'): + module._kernel_rhs(model,jnp.ones(4),.1,1.,1.)(jnp.ones(4)) + + +def test_fixed_field_adapter_solvers_on_cpu(): + from essos.rk import prepare_solver + from essos.rk import _prepare_boozer_gpu as prepare_orbit_solver + from essos.rk import _boozer_batch as _native_orbits + field=coil_field() + args=dict(mass=1.,charge=1.,energy=.5,times=np.array([0.,.001]),dt0=.001,max_steps=8) + with pytest.raises(ValueError): prepare_solver(UniformField(),execution='cuda',**args) + from essos.rk import _prepare_coils_gpu as coil_solver + with pytest.raises(ValueError): coil_solver(field,1.,1.,.5,1.,[0.,.001],.001,1e-9,1e-9,8,model='x',interpret=True) + for model,y in (('gc',jnp.array([1.,.03,.01,.3])), + ('lorentz',jnp.array([1.,.03,.01,.2,.1,.3]))): + args=dict(mass=1.,charge=1.,energy=.5,times=np.array([0.,.001]),dt0=.001,model=model,max_steps=8) + reference=jax.jit(prepare_solver(field,**args))(y) + gpu=jax.jit(prepare_solver(field,execution='cuda',interpret=True,**args))(y) + assert gpu.status==0 + np.testing.assert_allclose(gpu.y,reference.y,atol=3e-13) + boozer=tokamak(); y=jnp.array([[.5,0.,0.,.2]]); moments=jnp.array([.08]) + times=np.array([0.,.001]) + for method in ('dopri5','dopri8'): + solve=prepare_orbit_solver(boozer,1.,1.,1.,times,.001,1e-9,1e-9,8,method=method,interpret=True) + args=(boozer,y,moments,1.,1.,1.,jnp.asarray(times),.001,1e-9,1e-9,method,True,'i',.4,.3,8) + expected=_native_orbits(*args) + actual=_native_orbits(*args,orbit_solver=solve) + for a,b in zip(actual,expected): np.testing.assert_allclose(a,b,atol=3e-13) diff --git a/tests/test_native_split.py b/tests/test_native_split.py new file mode 100644 index 00000000..38d57d61 --- /dev/null +++ b/tests/test_native_split.py @@ -0,0 +1,1020 @@ +"""Forward split physics and bounded-control contracts; CPU-only CI.""" +from types import SimpleNamespace +import jax +import jax.numpy as jnp +import numpy as np +import pytest +from essos import split as s +from essos.split import ( + BoozerGeometry, CollisionJet, KernelCalls, _gc_velocity_jet, + _particle_collision_generator, _particle_ito, _particle_velocity_jacobians, _scalar_predictor, + _vmec_position_tangent, budget_components, collision_jet, expanded_moment_budget, + interval_from_budget, make_step_limit, moment_defect, move_in_cartesian, + native_step_limit, prepare_physics, scalar_graph, transported_budget) +from essos.background_species import BackgroundSpecies, nu_D_ab, nu_par_ab, nu_s_ab, coulomb_logarithm +from essos.constants import PROTON_MASS as M, ELEMENTARY_CHARGE as Q, EPSILON_0, HBAR, ONE_EV +from essos.dynamics import Particles, _guiding_center_velocity +from essos.electric_field import Electric_field_zero +from tests.test_native_orbit import UniformField, coil_field, tokamak + + +def bath(**kwargs): + return BackgroundSpecies(1, jnp.array([1.]), jnp.array([1.]), + jnp.array([kwargs.pop('density', 1e20)]), jnp.array([1000.]), **kwargs) + + +def zero(t, y, args): + return jnp.zeros_like(y) + + +def solve(kick, **kwargs): + options = dict(t1=1., dt0=.5, ts=jnp.array([0., 1.]), key=jax.random.PRNGKey(3), + noise_dim=1, method='dopri5', max_steps=64) | kwargs + return s.solve_split(zero, kick, jnp.zeros(1), **options) + + +def test_brownian_conditioning_preserves_samples_and_covariance(): + key = jax.random.PRNGKey(9) + memory = s.brownian_memory(key, 2, capacity=8) + parent, _, dw, full = s.brownian_propose(memory, 1.) + assert not full + repeated, _, same, _ = s.brownian_propose(parent, 1.) + np.testing.assert_array_equal(same, dw) + np.testing.assert_array_equal(repeated.key, parent.key) + child, h, left, full = s.brownian_propose(parent, .3, t_end=.3) + assert not full and h == .3 + tail = s.brownian_accept(child) + _, h, right, _ = s.brownian_propose(tail, 2.) + assert h == pytest.approx(.7) + np.testing.assert_allclose(left+right, dw, atol=2e-16) + z = jnp.array([.2, -.3]) + conditioned, left, full = s.brownian_sample(parent, .4, normal=z) + assert not full + np.testing.assert_allclose(left, .4*dw+np.sqrt(.24)*z, atol=2e-16) + jac = jax.jacfwd(lambda z: s.brownian_sample(parent, .4, normal=z)[1])(z) + np.testing.assert_allclose(jac@jac.T, .24*np.eye(2), atol=2e-16) + conditioned, whole, _ = s.brownian_sample(conditioned, 1.) + np.testing.assert_allclose(whole, dw, atol=2e-16) + tail = s.brownian_consume(conditioned, .4) + _, right, _ = s.brownian_sample(tail, 1.) + np.testing.assert_allclose(left+right, dw, atol=2e-16) + # Batched new/bridge/retained/overflow lanes consume the same key sequence. + def branch(key,kind): + empty=s.brownian_memory(key,2,capacity=2) + parent=s.brownian_propose(empty,1.)[0] + child=s.brownian_propose(parent,.5)[0] + memory=jax.tree.map(lambda a,b,c:jnp.where(kind==0,a,jnp.where(kind==3,c,b)),empty,parent,child) + out,_,_,full=s.brownian_propose(memory,jnp.where(kind==1,.5,jnp.where(kind==3,.25,1.))) + expected=jnp.where(kind==0,parent.key,jnp.where(kind==1,child.key,memory.key)) + return out.key,expected,full + keys,expected,full=jax.jit(jax.vmap(branch))(jax.random.split(key,4),jnp.arange(4)) + np.testing.assert_array_equal(keys,expected) + np.testing.assert_array_equal(full,jnp.array([False,False,False,True])) + + +def test_brownian_capacity_and_cumulative_sampling_are_bounded(): + for change in (dict(capacity=0), dict(capacity=True), dict(noise_dim=0), dict(noise_dim=True)): + options = dict(noise_dim=1, capacity=2) | change + with pytest.raises(ValueError): s.brownian_memory(jax.random.PRNGKey(1), **options) + memory, _, _, _ = s.brownian_propose(s.brownian_memory(jax.random.PRNGKey(1), 1, capacity=1), 1.) + after, _, _, full = s.brownian_propose(memory, .5) + assert full + for a, b in zip(memory, after): np.testing.assert_array_equal(a, b) + after, _, full = s.brownian_sample(memory, .5) + assert full + np.testing.assert_array_equal(after.increments, memory.increments) + memory = s.brownian_memory(jax.random.PRNGKey(2), 1, capacity=4) + memory, first, _ = s.brownian_sample(memory, .2) + with pytest.raises(ValueError): s.brownian_sample(memory,.1,normal=jnp.zeros(2)) + memory, whole, _ = s.brownian_sample(memory, .7) + consumed = s.brownian_consume(memory, .2) + _, tail, _ = s.brownian_sample(consumed, .7) + np.testing.assert_allclose(first+tail, whole, atol=2e-16) + + +def test_physical_coefficients_match_diffusion_divergence_and_zero_flux(): + from examples.benchmarks.lorentz_collision_reference import coefficients as independent,orbit as reference_orbit + from examples.benchmarks.nonrelativistic_collision_reference import ProtonBackground + p=ProtonBackground(coulomb_log_model='impact');r=jnp.array([.2,np.sqrt(10.),5.]) + physical=p.coefficients(p.sigma*np.asarray(r));a,b,k=independent(r) + expected=(physical['parallel']/(p.sigma**2*p.nu),physical['perpendicular']/(p.sigma**2*p.nu), + (physical['friction']+physical['parallel_derivative']+2*(physical['parallel']-physical['perpendicular'])/(p.sigma*r))/(p.sigma*p.nu)) + for before,after in zip((a,b,k),expected):np.testing.assert_allclose(before,after,rtol=2e-11) + state=jnp.array([[.1,.2,.3,1.,2.,3.]]);h=1e-5 + stepped=reference_orbit(state,h,'uniform',1.);angle=h*2048 + rotated=np.array([np.cos(angle)+2*np.sin(angle),2*np.cos(angle)-np.sin(angle),3.]) + np.testing.assert_allclose(stepped[0,3:],rotated,rtol=3e-14) + np.testing.assert_allclose(stepped[0,:3],state[0,:3]+h/2*(state[0,3:]+rotated),rtol=3e-14) + from examples.benchmarks.lorentz_collision_reference import collision as reference_collision + frame=jnp.array([[0.,1.,0.],[-1.,0.,0.],[0.,0.,1.]]) + augmented=jnp.concatenate((state,jnp.reshape(frame,(1,9))),axis=1) + noise=jnp.concatenate((jnp.eye(3),-jnp.eye(3)),axis=0)*np.sqrt(3*h) + increments=np.asarray(reference_collision(jnp.broadcast_to(augmented,(6,15)),h,noise)[:,3:6]-state[:,3:]) + speed=jnp.linalg.norm(state[0,3:]);direction=state[0,3:]/speed;a,b,k=independent(speed) + np.testing.assert_allclose(increments.mean(axis=0),h*k*direction,rtol=1e-10,atol=1e-15) + np.testing.assert_allclose(np.cov(increments,rowvar=False,ddof=0),2*h*(b*jnp.eye(3)+(a-b)*jnp.outer(direction,direction)),rtol=2e-11,atol=1e-15) + frame_after=np.asarray(reference_orbit(augmented,h,'uniform',1.)[0,6:]).reshape(3,3) + np.testing.assert_allclose(frame_after@frame_after.T,np.eye(3),atol=3e-14) + background, point = bath(coulomb_log_model='impact'), jnp.zeros(3) + for speed in (2e4, 2e6): + velocity = jnp.array([.3, -.4, np.sqrt(.75)])*speed + def diffusion(v): + r = jnp.linalg.norm(v); direction = v/r + dp = .5*r*r*nu_par_ab(M, Q, 0, r, point, background) + dt = .5*r*r*nu_D_ab(M, Q, 0, r, point, background) + return dt*jnp.eye(3)+(dp-dt)*jnp.outer(direction, direction) + divergence = jnp.einsum('ijj->i', jax.jacfwd(diffusion)(velocity)) + expected = -nu_s_ab(M, Q, 0, speed, point, background)*velocity+divergence + c = s.collision_coefficients(background, M, Q, jnp.asarray(speed), point, full_orbit=True) + drift = c.friction+c.parallel_derivative+2*(c.parallel-c.perpendicular)/speed + np.testing.assert_allclose(drift*velocity/speed, expected, rtol=2e-10) + np.testing.assert_allclose(c.friction, -M*speed*c.parallel/(1000*Q), rtol=3e-14) + basis = s.velocity_basis(velocity) + noise = basis@jnp.diag(jnp.sqrt(2*jnp.array([c.perpendicular, c.perpendicular, c.parallel]))) + np.testing.assert_allclose(noise@noise.T/2, diffusion(velocity), rtol=1e-12) + assert s.collision_coefficients(background, M, Q, jnp.asarray(1e5), point).particle_drift_derivative == 0 + rates=jnp.array([-.2,.4,.2]);first=jnp.array([.03,-.01,.02]);second=jnp.array([.01,.02,-.01]) + unit=jnp.array([.2,.4,.7]);unit=unit/jnp.linalg.norm(unit) + @jax.jit + def generator_check(velocity): + radius=jnp.linalg.norm(velocity);direction=velocity/radius + def coefficients(v): + delta=jnp.linalg.norm(v)-radius + return _particle_ito(v,unit,rates+delta*first+.5*delta**2*second) + jac=jax.jacfwd(coefficients)(velocity) + hessian=jax.jacfwd(jax.jacfwd(coefficients))(velocity) + diffusion=2*rates[2]*jnp.eye(3)+2*(rates[1]-rates[2])*jnp.outer(direction,direction) + reference=jax.tree.map(lambda J,H:jnp.tensordot(J,rates[0]*direction,axes=1)+ + .5*jnp.tensordot(H,diffusion,axes=2),jac,hessian) + return reference,_particle_collision_generator(velocity,unit,rates,first,second) + reference,actual=generator_check(jnp.array([1.2,-.7,2.3])) + for a,b in zip(reference,actual):np.testing.assert_allclose(a,b,rtol=2e-12,atol=2e-13) + # The block covariance must preserve unconstrained derivatives, including + # field-direction derivatives, rather than assuming unit-vector tangents. + def dense_covariance(x): + v,b,rates=x[:3],x[3:6],x[6:];r=jnp.linalg.norm(v);u=v/r;xi=b@u + S=jnp.concatenate((jnp.eye(3),u[None,:],(b-xi*u)[None,:]/r,b[None,:])) + return S@(2*rates[2]*jnp.eye(3)+2*(rates[1]-rates[2])*jnp.outer(u,u))@S.T + def covariance_jet(fn,x):return fn(x),jax.jacfwd(fn)(x),jax.jacfwd(jax.jacfwd(fn))(x) + points=jnp.array([[0.,0.,2.,0.,0.,1.,-.2,.4,.2], + [0.,0.,-2.,0.,0.,1.,-.2,.4,.2],[1.2,-.7,2.3,.2,.4,1.4,-.2,.4,.2], + [1.,.2,.3,.2,.4,.7,0.,0.,0.]]) + expected=jax.jit(jax.vmap(lambda x:covariance_jet(dense_covariance,x)))(points) + actual=jax.jit(jax.vmap(lambda x:covariance_jet(lambda w:_particle_ito(w[:3],w[3:6],w[6:])[1],x)))(points) + for a,b in zip(expected,actual):np.testing.assert_allclose(a,b,rtol=5e-11,atol=2e-12) + gradient=jnp.arange(9.).reshape(3,3)*.01;rotation=jnp.array([[0.,1.,-2.],[-1.,0.,3.],[2.,-3.,0.]]) + for orbit in (True,False): + for electric in (jnp.zeros(3),jnp.array([.1,-.2,.3])): + def jacobians(x): + v,b,rates=x[:3],x[3:6],x[6:];radius=jnp.linalg.norm(v) + def drift(w): + delta=jnp.linalg.norm(w)-radius + return _particle_ito(w,b,rates+delta*first+.5*delta**2*second)[0] + def flow(w): + r=jnp.linalg.norm(w);u=w/r;xi=b@u;e=u@electric + p=(gradient@w)@w+b@electric + return jnp.r_[w if orbit else jnp.zeros(3),rotation@w+electric,e,(p-xi*e)/r,p] + return (jax.jacfwd(drift)(v),jax.jacfwd(flow)(v)),_particle_velocity_jacobians(v,b,gradient,rotation,electric,rates,first,orbit=orbit) + before,after=jax.jit(jax.vmap(jacobians))(points) + for a,b in zip(before,after):np.testing.assert_allclose(a,b,rtol=3e-11,atol=3e-12) + + +def test_collision_maps_reflections_and_physical_noise_covariance(): + c = s.CollisionCoefficients(.8, .4, .12, -.3, .07, .02) + v, xi, h, tol = 2., -.4, .03, .004 + dw = jnp.array([.1, -.2]) + out = s.guiding_center_collision_step(v, xi, h, dw, c, tolerance=tol, return_error_model=True) + nu = 2*c.perpendicular/v**2 + v1 = v+(-.3+.12)*h+np.sqrt(1.6)*dw[0]+.06*(dw[0]**2-h) # the 2 D_par/v drift is the perpendicular kick below + expected = [np.sqrt(v1**2+4*.8*h), + xi-xi*nu*h+np.sqrt((1-xi*xi)*nu)*dw[1]-.5*xi*nu*(dw[1]**2-h)] + np.testing.assert_allclose(out.y, expected, rtol=2e-14) + np.testing.assert_allclose(s.reflect_pitch(jnp.array([-5.2, -1.2, 1.2, 7.3])), [-.8, -.8, .8, -.7], atol=2e-15) + for map_fn, initial, noise in ((s.guiding_center_collision_step, (2., .3), jnp.zeros(2)), + (s.particle_collision_step, (jnp.array([1.2, 0., 1.6]),), jnp.zeros(3))): + vacuum = s.CollisionCoefficients(*(0.,)*6) + result = map_fn(*initial, h, noise, vacuum) + np.testing.assert_allclose(result.y, jnp.asarray(initial if len(initial)==2 else initial[0])) + assert result.drift_error == result.diffusion_error == 0 + basis = s.velocity_basis(jnp.array([1., 2., 3.])) + np.testing.assert_allclose(basis.T@basis, np.eye(3), atol=3e-16) + point = jnp.array([0., 0., 1.]); w = jnp.array([.2, -.4, 3.]) + dx = s.guiding_center_spatial_diffusion(xi, c, 7.) + np.testing.assert_allclose(s.guiding_center_spatial_increment(xi, w, c, point, 7.), np.sqrt(2*dx)*w*jnp.array([1., 1., 0.])) + for value in (0., 1., np.nan): + result = s._diffusion_root(jnp.asarray(value)) + assert np.isnan(result) if np.isnan(value) else result == np.sqrt(value) + assert jax.grad(s._diffusion_root)(0.) == 0 + + +def test_error_models_match_actual_estimates_and_candidate_bounds(): + vel=jnp.array([2.,.5]);g=jnp.array([2.,0.]);zero=jnp.zeros(2) + jet=CollisionJet(zero,g,jnp.zeros((2,2)),jnp.zeros((2,2,2)), + jnp.zeros((2,2)),jnp.zeros((2,2,2)),zero,zero) + flight=lambda v:jnp.array([v[0],0.,0.,0.,0.]) + defect=moment_defect(flight,vel,jet) + np.testing.assert_allclose(defect.mean,0.,atol=1e-14) + assert defect.covariance[0,3]==defect.covariance[3,0]==-4. + assert defect.cubic_covariance[0,0]==pytest.approx(-4/3) + # Analytic Brownian-flight global variance defect is 3*h/(2*T) + # to leading order. Propagating the mixed defect recovers that rate. + linear,quadratic=transported_budget(defect,vel,.005) + np.testing.assert_allclose([linear,quadratic],[1.5/.005,1/.005**2],rtol=2e-14) + h=interval_from_budget(linear,quadratic,.01) + assert linear*h+quadratic*h*h==pytest.approx(.008) + assert interval_from_budget(0.,0.,.01)==.0025 + # OU kick: Euler mean error -gamma^2*v*h^2/2; variance error + # +gamma*g^2*h^2. Both velocity terms must be present. + ou=jet._replace(drift=jnp.array([-6.,0.]),drift_jacobian=jnp.diag(jnp.array([-3.,0.]))) + result=moment_defect(flight,vel,ou) + np.testing.assert_allclose(np.asarray(result.mean)[[0,3]],jnp.array([6.,-18.]),atol=1e-14) + assert result.covariance[3,3]==24. + interaction=moment_defect(flight,vel,ou,collision_remainder=False) + assert interaction.mean[0]==6. and interaction.mean[3]==0. and interaction.covariance[3,3]==0. + # Spatial density/temperature derivatives enter the weak defect too. + profile=lambda r,x:jnp.array([4*x[0],2+4*x[0],1+x[1]]) + for xi in (-1.,.4,1.): + model=collision_jet(profile,2.,xi,jnp.array([.2,.3,0.]),jnp.array([3.,2.,0.])) + assert all(np.isfinite(x).all() for x in model) + np.testing.assert_allclose(model.spatial_drift,[12.,-4*xi*1.3],atol=1e-14) + np.testing.assert_allclose(model.spatial_variance,[24*2.8,4*(1-xi*xi)*1.3],atol=1e-14) + for gc in (False, True): + for vacuum in (False, True): + c = s.CollisionCoefficients(*((0.,)*6 if vacuum else (.8, .4, .12, -.3, .07, .02))) + dw = jnp.array([.1, -.2] if gc else [.1, -.2, .3]) + out = (s.guiding_center_collision_step(2., -.4, .03, dw, c, tolerance=.004, return_error_model=True) + if gc else s.particle_collision_step(jnp.array([1.2, 0., 1.6]), .03, dw, c, tolerance=.004, return_error_model=True)) + np.testing.assert_allclose(s.collision_error_estimates(out.error_model, .03, dw), out[1:3], rtol=3e-14) + error = float(max(out.drift_error, out.diffusion_error)) + for target in (.9, 1., error/2+1e-14, 2*error+1e-14): + assert bool(s.collision_error_passes(out.error_model, .03, dw, target=target)) == (error <= target) + h = s._fit_error_step(out.error_model, 1., 0., jnp.ones_like(dw), .9) + estimates = s.collision_error_estimates(out.error_model, h, jnp.ones_like(dw)*jnp.sqrt(h)) + assert max(estimates) <= .9+1e-12 + model = s.CollisionErrorModel(.1, 0., 0., .1, 0., 0., .004, jnp.array(0)) + assert s.collision_error_passes(model, .03, jnp.zeros(1)) + assert not s.collision_error_passes(model, .03, jnp.ones(1)) + # Frozen angular diffusion has exact Legendre moments. The numerical + # mean/covariance remainder must match its small-step expansion. + rate=2.3;pitch=.6 + angular=collision_jet(lambda r,x:jnp.array([0.,0.,jnp.sqrt(rate)]), + jnp.array(3.),jnp.array(pitch),jnp.zeros(3),jnp.zeros(3)) + angular_defect=moment_defect(lambda v:jnp.zeros(5),jnp.array([3.,pitch]),angular) + assert angular_defect.mean[-1]==pytest.approx(-rate**2*pitch) + assert angular_defect.covariance[-1,-1]==pytest.approx(rate**2*(3-4*pitch**2)) + # Analytical derivatives retain the original GC RHS at off-axis states, + # including B-star and profile convection. The interval itself is unchanged. + from examples.benchmarks.benchmark_split_mirror import MagneticMirror,TransitField,background + from examples.benchmarks.benchmark_split_helix import HelicalField + from examples.benchmarks.nonrelativistic_collision_reference import ProtonBackground + audit_p=ProtonBackground(coulomb_log_model='impact') + audit_phase=jnp.array([[0.,0.,0.,np.sqrt(10.),.6], + [.004,-.003,.02,1.,-.4],[-.005,.007,-.015,5.,.95]]) + for audit_field in (MagneticMirror(2048*audit_p.nu*M/Q,.03*audit_p.sigma/audit_p.nu), + HelicalField(2e6*audit_p.nu*M/Q,2e4*audit_p.nu/audit_p.sigma),TransitField(2048*audit_p.nu*M/Q)): + audit_bath=background(audit_p,varying=True) + def audit_from_phase(u): + point=u[:3]*audit_p.sigma/audit_p.nu;r,xi=u[-2:];B=audit_field.AbsB(point) + return jnp.r_[point,audit_p.sigma*r*xi,M*audit_p.sigma**2*r*r*(1-xi*xi)/(2*B)] + def audit_drift(u): + y=audit_from_phase(u) + dx,dv=_guiding_center_velocity(audit_field,Electric_field_zero(),Q,M,y[:3],y[3],mu=y[4]) + return jnp.r_[dx/audit_p.sigma,0.,dv/(audit_p.nu*audit_p.sigma*u[3])] + def audit_radial(r,point): + c=s.collision_coefficients(audit_bath,M,Q,audit_p.sigma*r,point) + drift=(c.friction+c.parallel_derivative+2*c.parallel/(audit_p.sigma*r))/(audit_p.sigma*audit_p.nu) + return jnp.array([drift,jnp.sqrt(2*c.parallel/(audit_p.sigma**2*audit_p.nu)), + jnp.sqrt(2*c.perpendicular/(audit_p.sigma**2*r*r*audit_p.nu))]) + audit_limit=make_step_limit(audit_field,audit_bath,audit_p,.005) + def audit_one(u): + v=u[-2:];point=u[:3]*audit_p.sigma/audit_p.nu + f=lambda w:audit_drift(jnp.r_[u[:3],w]) + ref=(f(v),jax.jacfwd(f)(v),jnp.diagonal(jax.jacfwd(jax.jacfwd(f))(v),axis1=-2,axis2=-1)) + fast=_gc_velocity_jet(audit_field,point,v,audit_p) + model=collision_jet(audit_radial,v[0],v[1],point,ref[0][:3]*audit_p.sigma/audit_p.nu) + slow=moment_defect(f,v,model);new=moment_defect(None,v,model,orbit_jet=fast) + mean,cov,quadratic=budget_components(slow,v,.012) + bounds=transported_budget(slow,v,.012) + component_bounds=(jnp.maximum(jnp.max(mean),jnp.max(cov)),jnp.max(quadratic)) + expected_h=interval_from_budget(*bounds,.005)/audit_p.nu + actual_h=audit_limit(.012/audit_p.nu,audit_from_phase(u),None) + return ref,fast,slow,new,jnp.asarray(bounds),jnp.asarray(component_bounds),expected_h,actual_h + ref,fast,slow,new,bounds,components,expected_h,actual_h=jax.jit(jax.vmap(audit_one))(audit_phase) + for a,b in zip(ref,fast):np.testing.assert_allclose(a,b,rtol=3e-11,atol=5e-10) + for a,b in zip(slow,new):np.testing.assert_allclose(a,b,rtol=3e-11,atol=5e-10) + np.testing.assert_array_equal(bounds,components) + np.testing.assert_allclose(actual_h,expected_h,rtol=3e-11) + # The retained expanded algebra also covers vanishing velocity noise. + F=jnp.array([[1.,-2.],[.3,.1],[-.5,1.2],[0.,0.],[.2,-.1]]) + def noise_budget(g,F,H,v): + model=jet._replace(noise=g);velocity=(jnp.zeros(5),F,H) + reference=moment_defect(None,v,model,orbit_jet=velocity) + return jnp.asarray(transported_budget(reference,v,.005)),jnp.asarray(expanded_moment_budget(velocity,model,v,.005)) + # Include mixed covariances, nonzero curvature and both pitch endpoints. + rng=np.random.default_rng(42) + noises=jnp.concatenate((jnp.array([0.,1e-25,1.])[:,None]*jnp.array([.4,.3]),jnp.asarray(rng.uniform(.1,1.,(8,2))))) + jacobians=jnp.concatenate((jnp.broadcast_to(F,(3,5,2)),jnp.asarray(rng.normal(size=(8,5,2))))) + hessians=jnp.concatenate((jnp.zeros((3,5,2)),jnp.asarray(rng.normal(size=(8,5,2))))) + velocities=jnp.stack((jnp.full(11,2.),jnp.linspace(-1.,1.,11)),axis=1) + before,after=jax.jit(jax.vmap(noise_budget))(noises,jacobians,hessians,velocities) + np.testing.assert_allclose(before,after,rtol=3e-12,atol=3e-12) + +def test_controller_lookahead_retains_probes_and_respects_boundaries(): + memory = s.brownian_memory(jax.random.PRNGKey(8), 1, capacity=8) + for error, expected in ((.25, 1.5), (4., .45)): + after, h, full = s.paper_collision_step_size(memory, 1., jnp.array([2.]), error, + 1e-18, jnp.asarray(error <= 1), dtmin=0., dtmax=10., barrier=10.) + assert not full and h == pytest.approx(expected) and after.size > 0 + _, h, full = s.paper_collision_step_size(memory, 1., jnp.zeros(1), error, + 0., jnp.asarray(error <= 1), dtmin=.4, dtmax=10., barrier=.2) + assert not full and h == .2 + for drift in (0., 1.): + model = s.CollisionErrorModel(0., .5, drift, 0., 0., 0., 1., jnp.array(0)) + after, h, full = s.candidate_collision_step_size(memory, .5, model, jnp.array(True), dtmin=0., dtmax=2., barrier=1.) + assert not full and after.size == 0 and abs(h-(.9**(2/3) if drift else 1.)) < 1/256 + model = s.CollisionErrorModel(0., .5, 0., .3, 0., 0., .2, jnp.array(0)) + parent, _, _, _ = s.brownian_propose(s.brownian_memory(jax.random.PRNGKey(3), 1, capacity=1), 1.) + after, _, full = s.candidate_collision_step_size(parent, 1., model, jnp.array(False), dtmin=0., dtmax=1., barrier=1.) + assert full + np.testing.assert_array_equal(after.increments, parent.increments) + # Production endpoint alignment avoids a tiny second RK interval. + rhs=lambda t,y,args:jnp.ones_like(y) + kick=lambda t,y,h,dw,args:s.CollisionStep(y,jnp.zeros(()),jnp.zeros(())) + options=dict(t1=.5,dt0=.105,dtmax=.105,orbit_dt0=.1,ts=jnp.array([0.,.5]), + key=jax.random.PRNGKey(42),noise_dim=1,step_limit=lambda t,y,args:jnp.asarray(.105), + max_steps=20,max_orbit_steps=20) + original=s.solve_split(rhs,kick,jnp.zeros(1),**options) + aligned=s.solve_split(rhs,kick,jnp.zeros(1),align_orbit=True,**options) + assert original.status==aligned.status==0 + np.testing.assert_allclose(aligned.ys,original.ys,rtol=0,atol=2e-14) + assert aligned.t==.5 and aligned.stats.orbit_steps.4 + assert record['evolution'][0]['speed_mean']==dict(value=2.) + apply_lorentz_reference(report,numerical) + np.testing.assert_allclose(measurement['difference'],.1,atol=1e-15) + dx,dv=_guiding_center_velocity(helical,Electric_field_zero(),Q,M,helical_state[:3],helical_state[3],mu=helical_state[4]) + exact_rate=jax.jacfwd(lambda time:exact_orbit(helical_state,time,helical))(0.) + np.testing.assert_allclose(exact_rate[:3],dx,rtol=3e-14,atol=2e-10) + assert abs(dv)/(helical.wave*helical_state[3]**2)<1e-14 + np.testing.assert_allclose(exact_orbit(exact_orbit(helical_state,h,helical),h,helical), + exact_orbit(helical_state,2*h,helical),rtol=3e-14) + reference=MirrorCollisionReference(nz=13,nr=32,nxi=13) + half,_=reference.collision_matrices(.001) + constant=np.ones((13,32,13,1)) + np.testing.assert_allclose(reference.collide(constant,half),constant,atol=2e-9) + np.testing.assert_allclose(reference.transport(constant,reference.characteristics(.0005)),constant,atol=2e-12) + times=np.array([0.,.001]);collision_only=reference.moments(times,transport=False,steps_per_save=2) + independent=reference.radial.moments(times) + for name in ('pitch_mean','pitch_variance'): + np.testing.assert_allclose(collision_only[name],independent[name],atol=2e-6) + # A resolved helix moves in x/y but has no guiding-centre diffusion. + helix=np.array([[[0.,0.,0.,2.,0.,1.],[.5,-.5,1.,0.,-2.,1.]]]) + speed,pitch,_,msd=observables(helix,4.,'lorentz') + np.testing.assert_allclose(speed,np.sqrt(5.));np.testing.assert_allclose(pitch,1/np.sqrt(5.)) + np.testing.assert_allclose(msd,0.,atol=1e-15) + gc=np.array([[[0.,0.,0.,1.,2.],[.1,.2,1.,1.,2.]]]) + speed,pitch,_,msd=observables(gc,4.,'gc') + np.testing.assert_allclose(speed,np.sqrt(5.));np.testing.assert_allclose(pitch,1/np.sqrt(5.)) + np.testing.assert_allclose(msd,[[0.,.8]],atol=1e-15) + collision = lambda t, y, h, dw, a: s.CollisionStep(y+h, 0., 0.) + synchronized=s.solve_split(lambda t,y,a:jnp.ones_like(y),collision,jnp.zeros(1), + t1=1.,dt0=.25,orbit_dt0=.25,adaptive=False,orbit_adaptive=False,ts=jnp.array([0.,1.]), + key=jax.random.PRNGKey(1),noise_dim=1) + assert synchronized.status==0 and synchronized.stats.orbit_steps==synchronized.stats.accepted==4 + np.testing.assert_allclose(synchronized.y,[2.],atol=2e-14) + common=s.solve_split(lambda t,y,a:jnp.array([y[0],0.]), + lambda t,y,h,w,a:s.CollisionStep(y.at[1].add(w[0]),0.,0.), + jnp.array([1.,0.]),t1=1.,dt0=1.,orbit_dt0=1.,shared_clock=True,method='dopri5', + rtol=1e-8,atol=1e-8,ts=jnp.array([0.,1.]),key=jax.random.PRNGKey(1),noise_dim=1) + assert common.status==0 and common.stats.rejected>0 + assert common.stats.accepted_orbit_steps==common.stats.collision_updates + assert common.stats.max_orbit_steps_per_collision==1 + np.testing.assert_allclose(common.y[0],np.exp(1.),rtol=2e-8) + parent=jax.random.normal(jax.random.split(jax.random.PRNGKey(1))[1],(1,),dtype=jnp.float64) + np.testing.assert_allclose(common.y[1],parent[0],atol=2e-14) + for saves in (jnp.array([]), jnp.array([0., .1, .1, .4, 1.])): + out = jax.jit(lambda: s.solve_split(lambda t,y,a:jnp.ones_like(y), collision, jnp.zeros(1), + t1=1., dt0=.25, orbit_dt0=.05, adaptive=False, orbit_adaptive=False, ts=saves, + key=jax.random.PRNGKey(1), noise_dim=1, record_steps=True))() + assert out.status == 0 and out.stats.orbit_steps > 3*out.stats.accepted + np.testing.assert_allclose(out.y, [2.], atol=2e-14) + np.testing.assert_allclose(out.ys[:, 0], 2*saves, atol=2e-14) + assert out.step_ts[0] == 0 and out.step_ts[out.stats.accepted] == 1 + def refine(tolerance,reuse=True): + rhs=lambda t,y,a:jnp.array([y[1],0.]) + kick=lambda t,y,h,w,a:s.CollisionStep(y.at[1].add(h),0.,0.) + return s.solve_split(rhs,kick,jnp.zeros(2),t1=1.,dt0=1.,ts=jnp.array([0.,1.]), + orbit_dt0=.02,orbit_adaptive=False,key=jax.random.PRNGKey(3),noise_dim=1,method='dopri5', + combined_error_norm=lambda a,b:jnp.abs(a[0]-b[0])/tolerance,record_steps=True,max_steps=128,reuse_combined_orbit=reuse) + pair=jax.jit(jax.vmap(refine))(jnp.array([.02,.002])) + assert np.all(pair.status==0) and np.all(pair.stats.combined_rejected>0) + assert np.all(pair.stats.max_accepted_combined_error<=1) + assert np.all(pair.stats.accepted_orbit_steps>=pair.stats.collision_updates) + assert np.max(pair.stats.max_orbit_steps_per_collision)>1 + assert abs(pair.y[1,0]-.5)0) + target=.5-2*np.finfo(float).eps + snapped=s.solve_split(lambda t,y,a:jnp.array([y[1],0.]), + lambda t,y,h,w,a:s.CollisionStep(y.at[1].add(h),0.,0.),jnp.zeros(2), + t1=1.,dt0=1.,ts=jnp.array([1.]),key=jax.random.PRNGKey(3),noise_dim=1,method='dopri5', + combined_error_norm=lambda a,b:(.9*2*jnp.sqrt(jnp.abs(a[0]-b[0]))/target)**1.5,combined_controller='i',record_steps=True) + assert snapped.status==0 and snapped.stats.accepted==2 and snapped.stats.rejected==1 + np.testing.assert_allclose(snapped.step_ts[:5],[0.,.25,.5,.75,1.],atol=2e-15) + + +def test_adaptive_rejection_keeps_the_original_wiener_path(): + model = s.CollisionErrorModel(0., .5, .5, .3, 0., 0., .2, jnp.array(0)) + for controller in ('conservative', 'paper', 'candidate'): + def one(key): + def kick(t, y, h, dw, a): + ed, es = s.collision_error_estimates(model, h, dw) + return s.CollisionStep(y+dw, ed, es, model) + out = s.solve_split(zero, kick, jnp.zeros(1), t1=1., dt0=1., dtmax=1., ts=jnp.array([1.]), + key=key, noise_dim=1, method='dopri5', collision_controller=controller, max_steps=256) + _, draw = jax.random.split(key) + return out, jax.random.normal(draw, (1,), dtype=jnp.float64) + out, parent = jax.jit(jax.vmap(one))(jax.random.split(jax.random.PRNGKey(25), 8)) + assert np.all(out.status == 0) and np.all(out.stats.rejected > 0) + assert np.max(out.stats.max_accepted_error) <= 1 + np.testing.assert_allclose(out.y, parent, atol=1e-12, rtol=0) + def refined(key): + kick=lambda t,y,h,w,a:s.CollisionStep(y+w,(h/.15)**2,0.) + return s.solve_split(zero,kick,jnp.zeros(1),t1=1.,dt0=1.,ts=jnp.array([1.]), + key=key,noise_dim=1,combined_error_norm=lambda a,b:jnp.max(jnp.abs(a-b)),method='dopri5') + keys=jax.random.split(jax.random.PRNGKey(15),4) + out=jax.jit(jax.vmap(refined))(keys) + draws=jax.vmap(lambda k:jax.random.normal(jax.random.split(k)[1],(1,),dtype=jnp.float64))(keys) + assert np.all(out.status==0) and np.all(out.stats.rejected>0) and np.all(out.stats.peak_pending>=2) + np.testing.assert_allclose(out.y,draws,atol=2e-14,rtol=0) + + +def test_orbit_events_skip_kicks_and_refinement_retains_fixed_anchors(): + def bad_kick(t, y, h, dw, a): return s.CollisionStep(jnp.full_like(y, jnp.nan), 0., 0.) + out = s.solve_split(lambda t,y,a:jnp.ones_like(y), bad_kick, jnp.zeros(1), + t1=1., dt0=.5, ts=jnp.array([0., .1, 1.]), key=jax.random.PRNGKey(1), noise_dim=1, + event=(lambda t,y,a:.05-y[0], lambda t,y,a:.2-y[0]), method='dopri5') + assert out.status == 1 and out.stats.accepted == 0 + np.testing.assert_allclose(out.t, .05, atol=2e-14) + np.testing.assert_allclose(out.ys[:, 0], [0., .05, .05], atol=2e-14) + kick = lambda t,y,h,w,a:s.CollisionStep(y+h, 0., 0.) + out = solve(kick, adaptive=False, orbit_adaptive=False, event=lambda t,y,a:.31-y[0], + step_limit=lambda t,y,a:jnp.where(y[0] < .2, .2, .1), event_dtmax=.025, record_steps=True) + assert out.status == 1 and .31 <= float(out.y[0]) <= .335 + assert out.stats.rejected > 0 + + +def test_input_validation_and_failure_statuses_keep_last_finite_state(): + kick = lambda t,y,h,w,a:s.CollisionStep(y+h, 0., 0.) + for change in (dict(max_steps=0), dict(max_orbit_steps=True), dict(collision_controller='bad'), + dict(orbit_stage_execution='bad'), dict(combined_controller='bad'),dict(dtmax=-1.), dict(orbit_dt0=0.), + dict(dtmin=1.), dict(event_dtmax=.1), dict(t0=jnp.ones(2))): + with pytest.raises(ValueError): solve(kick, **change) + combined=lambda a,b:jnp.max(jnp.abs(a-b)) + for change in (dict(adaptive=False),dict(orbit_adaptive=False),dict(reuse_orbit_step=False), + dict(collision_controller='paper'),dict(event=lambda t,y,a:1.), + dict(step_limit=lambda t,y,a:.1),dict(combined_error_norm=combined)): + with pytest.raises(ValueError):solve(kick,shared_clock=True,**change) + for change in (dict(adaptive=False),dict(collision_controller='paper'),dict(event=lambda t,y,a:1.), + dict(step_limit=lambda t,y,a:.1),dict(event_dtmax=.1)): + with pytest.raises(ValueError):solve(kick,combined_error_norm=combined,**change) + for norm in (1,lambda a,b:jnp.ones(2)): + with pytest.raises(ValueError):solve(kick,combined_error_norm=norm) + bad=solve(kick,combined_error_norm=lambda a,b:jnp.nan) + assert bad.status==s.SplitStatus.NONFINITE and bad.stats.accepted==0 + bad=solve(lambda t,y,h,w,a:s.CollisionStep(y+h,jnp.where(h<.3,-1.,0.),0.),combined_error_norm=combined) + assert bad.status==s.SplitStatus.NONFINITE and bad.stats.accepted==0 + full=solve(kick,combined_error_norm=combined,max_pending=1) + assert full.status==s.SplitStatus.BROWNIAN_CAPACITY and full.y[0]==0 + tiny=s.solve_split(zero,kick,jnp.zeros(1),t0=1.,t1=np.nextafter(1.,2.),dt0=np.spacing(1.), + ts=jnp.array([]),key=jax.random.PRNGKey(0),noise_dim=1,combined_error_norm=combined) + assert tiny.status==s.SplitStatus.MIN_STEP and tiny.stats.accepted==0 + failed=s.solve_split(lambda t,y,a:jnp.where(y<.2,0.,jnp.nan),kick,jnp.zeros(1), + t1=1.,dt0=.5,ts=jnp.array([]),key=jax.random.PRNGKey(0),noise_dim=1,combined_error_norm=combined) + assert failed.status==s.SplitStatus.NONFINITE and failed.y[0]==0 + prefix=s.solve_split(lambda t,y,a:y,lambda t,y,h,w,a:s.CollisionStep(y,0.,0.),jnp.ones(1), + t1=1.,dt0=.5,orbit_dt0=.01,max_orbit_steps=1,ts=jnp.array([]), + key=jax.random.PRNGKey(0),noise_dim=1,combined_error_norm=combined) + assert prefix.status==s.SplitStatus.MAX_STEPS and prefix.stats.orbit_steps==1 and prefix.stats.accepted==0 + for bad in (lambda t,y,h,w,a:s.CollisionStep(jnp.zeros(2), 0., 0.), + lambda t,y,h,w,a:s.CollisionStep(y, jnp.zeros(2), 0.)): + with pytest.raises(ValueError): solve(bad) + with pytest.raises(ValueError): solve(kick, event=lambda t,y,a:jnp.zeros(2)) + with pytest.raises(ValueError): solve(kick, collision_controller='candidate') + model = s.CollisionErrorModel(0., 0., 0., 0., 0., 0., jnp.ones(2), jnp.array(0)) + with pytest.raises(ValueError): + solve(lambda t,y,h,w,a:s.CollisionStep(y, 0., 0., model), collision_controller='candidate') + bad = solve(lambda t,y,h,w,a:s.CollisionStep(jnp.full_like(y, jnp.nan), 0., 0.)) + assert bad.status == s.SplitStatus.NONFINITE + np.testing.assert_array_equal(bad.y, [0.]) + minimum = solve(lambda t,y,h,w,a:s.CollisionStep(y+1., 4., 0.), dtmin=.5) + assert minimum.status == s.SplitStatus.MIN_STEP and minimum.stats.accepted == 0 + limited = s.solve_split(zero, kick, jnp.zeros(1), t1=1., dt0=.1, ts=jnp.array([1.]), + key=jax.random.PRNGKey(1), noise_dim=1, adaptive=False, max_steps=1) + assert limited.status == s.SplitStatus.MAX_STEPS + invalid = solve(kick, step_limit=lambda t,y,a:jnp.asarray(-1.)) + assert invalid.status == s.SplitStatus.INVALID_INPUT + for limit in (lambda t,y,a:jnp.ones(2),): + with pytest.raises(ValueError): solve(kick, step_limit=limit) + for times in (jnp.ones((1, 1)),): + with pytest.raises(ValueError): s.solve_split(zero, kick, jnp.zeros(1), t1=1., dt0=.1, + ts=times, key=jax.random.PRNGKey(1), noise_dim=1) + for initial in (jnp.zeros((1,1)), jnp.array([],dtype=float), jnp.array([1+1j])): + with pytest.raises(ValueError): s.solve_split(zero, kick, initial, t1=1., dt0=.1, + ts=jnp.array([1.]), key=jax.random.PRNGKey(1), noise_dim=1) + + +def test_cartesian_gc_and_full_orbit_use_actual_collision_maps(): + field, background = UniformField(), bath(density=0.) + birth = Particles(jnp.array([[1., 0., 0.]]), mass=M, charge=Q, energy=10*ONE_EV, + initial_vparallel_over_v=jnp.array([.4]), field=field, phase_angle_full_orbit=0.) + for model in ('GuidingCenter', 'FullOrbit'): + for integrator in ('essos_rk45', 'essos_dopri8'): + out = s.trace_split(field, birth, background, model=model, integrator=integrator, + tmax=1e-10, timestep=5e-11, orbit_dt0=1e-11, n_save=2, + adaptive=False, orbit_adaptive=False, speed_floor=1., spatial_diffusion=model=='GuidingCenter') + assert out.status[0] == 0 and out.stats.orbit_steps[0] > out.stats.accepted[0] + assert np.isfinite(out.ys).all() + out = s.trace_split(field, birth, bath(), model=model, tmax=1e-10, + timestep=1e-10, n_save=2, orbit=False) + assert out.status[0] == 0 + combined=s.trace_split(field,birth,bath(),model=model,tmax=1e-10,timestep=5e-11, + n_save=2,combined_tolerance=.01) + assert combined.status[0]==0 and combined.stats.collision_updates[0]==2*combined.stats.accepted[0] + common=s.trace_split(field,birth,bath(),model=model,tmax=1e-10,timestep=5e-11, + n_save=2,shared_clock=True) + assert common.status[0]==0 and common.stats.accepted_orbit_steps[0]==common.stats.collision_updates[0] + limited=s.trace_split(field,birth,background,model=model,tmax=1e-10,timestep=1e-10, + n_save=2,step_limit=lambda t,y,a:2.5e-11) + assert limited.status[0]==0 and limited.stats.accepted[0]==4 + for controller in ('paper', 'candidate'): + out = s.trace_split(field, birth, bath(), model=model, tmax=1e-10, + timestep=5e-11, n_save=3, orbit=False, collision_controller=controller) + assert out.status[0] == 0 + for change in (dict(integrator='bad'), dict(model='bad'), dict(combined_controller='bad'), dict(collision_tolerance=0.), + dict(n_save=1), dict(execution='bad'), dict(spatial_diffusion=True, model='FullOrbit'), + dict(speed_floor=-1.), dict(times=jnp.zeros((1,1)))): + with pytest.raises(ValueError): s.trace_split(field, birth, bath(), tmax=1e-10, timestep=1e-10, **change) + for change in (dict(combined_tolerance=0.),dict(combined_tolerance=.01,combined_length_scale=0.), + dict(combined_tolerance=.01,execution='independent'),dict(shared_clock=True,execution='independent'), + dict(step_limit=lambda t,y,a:1.,execution='independent')): + with pytest.raises(ValueError):s.trace_split(field,birth,bath(),tmax=1e-10,timestep=1e-10,**change) + with pytest.raises(ValueError): s.trace_split(field, birth, None, tmax=1e-10, timestep=1e-10) + with pytest.raises(ValueError): s.trace_split(field, birth, SimpleNamespace(number_species=0), tmax=1e-10, timestep=1e-10) + for parameter, value in (('mass', -1.), ('charge', 0.), ('initial_vparallel_over_v', jnp.array([2.]))): + original = getattr(birth, parameter); setattr(birth, parameter, value) + with pytest.raises(ValueError): s.trace_split(field, birth, bath(), tmax=1e-10, timestep=1e-10) + setattr(birth, parameter, original) + birth.initial_xyz_fullorbit = None + with pytest.raises(ValueError): s.trace_split(field, birth, bath(), model='FullOrbit', tmax=1e-10, timestep=1e-10) + + +def test_coordinate_gc_charts_preserve_mu_and_enforce_supported_physics(): + from pathlib import Path + from essos.fields import Vmec + vmec = Vmec(str(Path(__file__).resolve().parents[1]/'examples/input_files/wout_LandremanPaul2021_QA_reactorScale_lowres.nc'), ntheta=8, nphi=8) + for field in (vmec, tokamak()): + birth = Particles(jnp.array([[.3, .2, .1]]), mass=M, charge=Q, energy=10*ONE_EV, + initial_vparallel_over_v=jnp.array([.4])) + out = s.trace_split(field, birth, bath(density=0.), tmax=1e-11, + timestep=1e-11, n_save=2, event=lambda t,y,a:1.-y[0],spatial_diffusion=False) + assert out.status[0] == 0 + if field is not vmec: + with pytest.raises(ValueError,match='spatial_geometry'): + s.trace_split(field,birth,bath(),tmax=1e-11,timestep=1e-11) + np.testing.assert_allclose(out.ys[0, 0, 4], out.y[0, 4], rtol=2e-14) + for change in (dict(model='FullOrbit'),): + with pytest.raises(ValueError): s.trace_split(field, birth, bath(), tmax=1e-11, timestep=1e-11, **change) + with pytest.raises(ValueError):s.trace_split(field,birth,bath(),tmax=1e-11,timestep=1e-11,combined_tolerance=.01) + birth.initial_xyz = jnp.array([[-.1, .2, .1]]) + with pytest.raises(ValueError): s.trace_split(tokamak(), birth, bath(), tmax=1e-11, timestep=1e-11) + with pytest.raises(ValueError): s.trace_split(tokamak(), birth, bath(), tmax=1e-11, timestep=1e-11, electric_field=object()) + # Nonlinear inversions must reproduce Cartesian kicks, including quadratic + # radial Ito drift, without relying on finite-difference derivatives. + point=jnp.array([.4,.3,.2,1.,2.]);dx=jnp.array([.02,-.03,.01]) + position=lambda y:jnp.array([y[0]+.2*y[1]**2,y[1],2*y[2]]) + moved=jax.jit(lambda y,d:move_in_cartesian(y,d,position))(point,dx) + np.testing.assert_allclose(position(moved),position(point)+dx,rtol=0,atol=1e-14) + np.testing.assert_array_equal(moved[3:],point[3:]) + np.testing.assert_allclose(jax.jacfwd(lambda d:move_in_cartesian(point,d,position)[:3])(dx), + jnp.linalg.inv(jax.jacfwd(lambda q:position(moved.at[:3].set(q)))(moved[:3])),rtol=2e-13) + np.testing.assert_array_equal(move_in_cartesian(point,jnp.zeros(3),position),point) + np.testing.assert_allclose(jax.jacfwd(lambda d:move_in_cartesian(point,d,position)[:3])(jnp.zeros(3)), + jnp.linalg.inv(jax.jacfwd(lambda q:position(point.at[:3].set(q)))(point[:3])),rtol=2e-13) + noise=jnp.concatenate((jnp.eye(3),-jnp.eye(3)))*.01 + ensemble=jax.vmap(lambda d:move_in_cartesian(point,d,position))(noise) + np.testing.assert_allclose(ensemble[:,0].mean()-point[0],-.2*jnp.mean(noise[:,1]**2),atol=2e-14) + assert np.isnan(move_in_cartesian(point,dx,lambda y:jnp.ones(3))[:3]).all() + # Known circular torus and toroidal-shift sign; symmetric spectra may omit + # their asymmetric partners. Check the regular magnetic-axis derivative. + radial=np.array([.1,.3,.5]);radius=.2*np.sqrt(radial) + export=SimpleNamespace(s_b=radial,xm_b=np.array([0,1]),xn_b=np.zeros(2), + rmnc_b=np.stack((np.full(3,2.),radius)),zmns_b=np.stack((np.zeros(3),radius)), + numns_b=np.zeros((2,3))) + geometry=BoozerGeometry.from_booz_xform(export) + q=jnp.array([.3,.4,.2]);R=2+.2*jnp.sqrt(q[0])*jnp.cos(q[1]) + np.testing.assert_allclose(geometry(q),[R*jnp.cos(q[2]),R*jnp.sin(q[2]),.2*jnp.sqrt(q[0])*jnp.sin(q[1])],atol=1e-14) + axis=jnp.array([0.,0.,.2]) + assert np.isfinite(jax.jacfwd(geometry.regular_xyz)(axis)).all() + shifted=SimpleNamespace(**vars(export));shifted.numns_b=np.stack((np.zeros(3),.05*np.sqrt(radial))) + shifted_geometry=BoozerGeometry.from_booz_xform(shifted) + phi=q[2]-.05*jnp.sqrt(q[0])*jnp.sin(q[1]) + np.testing.assert_allclose(shifted_geometry(q),[R*jnp.cos(phi),R*jnp.sin(phi),.2*jnp.sqrt(q[0])*jnp.sin(q[1])],atol=1e-14) + arrays,evaluate=shifted_geometry._kernel_view() + kernel=lambda q:jnp.asarray(evaluate(arrays,*q)) + np.testing.assert_allclose(jax.jit(kernel)(q),shifted_geometry(q),rtol=2e-13,atol=2e-14) + np.testing.assert_allclose(jax.jacfwd(kernel)(q),jax.jacfwd(shifted_geometry)(q),rtol=2e-12,atol=2e-13) + from essos.boozer import guiding_center_rhs + source=tokamak();initial=jnp.array([.3,.1,.2,1e5,1e-16]) + def build(view): + rhs=lambda t,y,a:jnp.append(guiding_center_rhs(view,y[:4],y[4]/M,M,Q),0.) + return rhs,lambda t,y,h,w,a:s.CollisionStep(y,0.,0.),lambda a,b,e:0.,lambda t,y,a:1.,lambda t,y,a:jnp.inf + arrays,factory=prepare_physics(source,s._split_field_data(source),build,initial,5,spatial_geometry=geometry) + rhs=factory(arrays,jnp.pad(initial,(0,3)))[0] + np.testing.assert_allclose(rhs(jnp.pad(initial,(0,3)))[:5],build(source)[0](0.,initial,None),rtol=3e-12,atol=1e-12) + # Real VMEC and Boozer collision kicks preserve speed and pitch results + # relative to the velocity-only operator when their field strength is fixed. + for field,embedding in ((vmec,None),(tokamak(),geometry)): + birth=Particles(jnp.array([[.3,.2,.1]]),mass=M,charge=Q,energy=10*ONE_EV, + initial_vparallel_over_v=jnp.array([.4])) + output=s.trace_split(field,birth,bath(),tmax=1e-11,timestep=1e-11,n_save=2, + spatial_geometry=embedding,orbit=False,collision_controller='conservative') + assert output.status[0]==0 and np.isfinite(output.ys).all() + assert np.linalg.norm(np.asarray(output.y[0,:3]-birth.initial_xyz[0]))>0 + q=birth.initial_xyz[0];mapping=field.to_xyz if field is vmec else embedding + B=field.AbsB(q) if field is vmec else field.modB(*q) + speed=birth.initial_vparallel[0]/.4;c=s.collision_coefficients(bath(),M,Q,speed,q) + _,_,dw,_=s.brownian_propose(s.brownian_memory(birth.random_keys[0],5),1e-11) + tangent=(jax.jacfwd(mapping)(q)@field.B_contravariant(q)) if field is vmec else ( + jax.jacfwd(mapping)(q)@jnp.array([0.,field.profiles(q[0])[0][0],1.])) + dx=s.guiding_center_spatial_increment(.4,dw[:3],c,tangent/jnp.linalg.norm(tangent),Q*B/M) + np.testing.assert_allclose(mapping(output.y[0,:3]),mapping(q)+dx,rtol=0,atol=3e-13) + expected=s.guiding_center_collision_step(speed,.4,1e-11,dw[-2:],c,speed_floor=.05*np.sqrt(2*1000*Q/M)).y + newB=field.AbsB(output.y[0,:3]) if field is vmec else field.modB(*output.y[0,:3]) + actual=jnp.sqrt(output.y[0,3]**2+2*output.y[0,4]*newB/M) + np.testing.assert_allclose([actual,output.y[0,3]/actual],expected,rtol=2e-13) + + +def test_independent_execution_validates_capabilities_without_fallback(monkeypatch): + field = coil_field() + birth = Particles(jnp.array([[1., .03, .01]]), mass=s.M, charge=s.Q, energy=4000*ONE_EV, + initial_vparallel_over_v=jnp.array([.5])) + options = dict(model='GuidingCenter', integrator='essos_dopri8', adaptive=True, + orbit_adaptive=True, controller='i', collision_controller='conservative', + electric_field=Electric_field_zero(), spatial_diffusion=False, orbit=True, + record_steps=False, reuse_orbit_step=True, event=None, times=jnp.array([0.,1.]), tmax=1.) + with pytest.raises(ValueError): s._validate_independent(field, birth, bath(), **options) + monkeypatch.setattr(jax, 'default_backend', lambda: 'gpu') + s._validate_independent(field, birth, bath(), **options) + for change in (dict(integrator='essos_rk45'), dict(controller='pi'), dict(collision_controller='paper'), + dict(orbit_adaptive=False), dict(reuse_orbit_step=False), + dict(electric_field=object()), dict(record_steps=True), + dict(times=jnp.array([])), dict(event=lambda t,y,a:True), + dict(event=lambda t,y,a:jnp.ones(2)), dict(event=lambda t,y,a:1.-t)): + with pytest.raises(ValueError): s._validate_independent(field, birth, bath(), **(options|change)) + for field_, species in ((UniformField(), bath()), (field, bath(coulomb_log_model='impact'))): + s._validate_independent(field_,birth,species,**options) + birth.mass = M + s._validate_independent(field,birth,bath(),**options) + birth.mass = s.M + old = birth.random_keys; birth.random_keys = jax.random.key(0, impl='rbg')[None] + with pytest.raises(ValueError): s._validate_independent(field, birth, bath(), **options) + birth.random_keys = old + s._validate_independent(field, birth, bath(), **(options|dict(event=lambda t,y,a:1.))) + jax.eval_shape(lambda mass:s._validate_independent(field, + SimpleNamespace(mass=mass,charge=s.Q,random_keys=old),bath(),**options),jnp.asarray(s.M)) + original = s._prepare_split_kernel + monkeypatch.setattr(s,'_prepare_split_kernel',lambda *a,**k:original(*a,**(k|dict(interpret=True)))) + monkeypatch.setattr(s,'_validate_independent',lambda *a,**k:None) + out = s.trace_split(field,birth,bath(),tmax=1e-12,timestep=1e-12,n_save=2, + adaptive=False,orbit_adaptive=False,execution='independent',max_steps=4,max_orbit_steps=4) + assert out.status[0] == 0 + + +def kernel_problem(*, adaptive=False, event=False, fail=False, limit=32, pending=8): + def factory(refs, y0): + z = s.scalar(y0, 7) + def rhs(y): return jnp.where(jnp.arange(8)==0, z+1., z) + def kick(y,h,w): + result = y+jnp.where(jnp.arange(8)==3, s.scalar(w, 0), z) + return result, (h/.04)**2 if adaptive else z, z + norm = lambda y,e,v,b:z + level = (lambda y:.05-s.scalar(y,0)) if event else lambda y:z+1. + return rhs,kick,norm,level + return s._prepare_split_kernel((),factory,jnp.array([0.,.1,.2]),adaptive=adaptive, + dt0=.1,dtmax=.1,speed=1.,orbit_dt0=.025,max_steps=limit,max_orbit_steps=16, + max_pending=pending,interpret=True) + + +def test_independent_kernel_interpretation_keeps_noise_and_inner_counts(): + initial, key = jnp.zeros(8), jax.random.PRNGKey(3) + for adaptive in (False, True): + out = jax.jit(kernel_problem(adaptive=adaptive))(initial,key) + ys,y,t,stats,status = out + assert status == 0 and t == .2 and stats[3] > stats[1] + np.testing.assert_allclose(ys[:,0], [0.,.1,.2], atol=3e-15) + if not adaptive: + assert stats[0] == stats[1] == 2 and stats[3] == 8 + assert stats[7]==8 and stats[8]==4 + else: + assert stats[2] > 0 and stats[6] <= 1 + assert 00 + _,y,t,stats,status = jax.jit(kernel_problem(event=True))(initial,key) + assert status == 1 and stats[1] == 0 + np.testing.assert_allclose(t,.05,atol=2e-14) + _,_,_,_,status = jax.jit(kernel_problem(limit=1))(initial,key) + assert status == 2 + _,_,_,_,status = jax.jit(kernel_problem(adaptive=True,pending=1))(initial,key) + assert status == 6 + + +def test_private_coil_field_and_collision_maps_match_public_functions(): + field, background = coil_field(), bath() + def check_kick(kick, initial, magnitude, gc=True): + h = jnp.asarray(1e-9) + dw = jnp.asarray([.2,-.3] if gc else [.2,-.3,.4])*jnp.sqrt(h) + actual,ed,es = jax.jit(kick)(initial,h,dw) + speed = jnp.sqrt(initial[3]**2+2*initial[4]*magnitude/s.M) if gc else jnp.linalg.norm(initial[3:6]) + c = s.collision_coefficients(background,s.M,s.Q,speed,jnp.zeros(3),full_orbit=not gc) + if gc: + step = s.guiding_center_collision_step(speed,initial[3]/speed,h,dw,c,tolerance=.003,speed_floor=1.) + v,xi = step.y + expected = initial.at[3].set(v*xi).at[4].set(s.M*v*v*(1-xi*xi)/(2*magnitude)) + else: + step = s.particle_collision_step(initial[3:6],h,dw,c,tolerance=.003) + expected = initial.at[3:6].set(step.y) + np.testing.assert_allclose(actual,expected,rtol=3e-10,atol=1e-25) + np.testing.assert_allclose([ed,es],[step.drift_error,step.diffusion_error],rtol=3e-9,atol=1e-25) + position = jnp.array([1., .03, .01]); vpar = 1e5; moment = s.M*2e10/(2*field.AbsB(position)) + for gc in (True, False): + initial = jnp.r_[position,jnp.array([vpar,moment,0.,0.,0.])] if gc else jnp.r_[position,jnp.array([1e5,2e5,1e5,0.,0.])] + arrays,factory = s._prepare_split_field(field,background,gc=gc,collision_tolerance=.003,speed_floor=1.) + rhs,kick,norm,level = factory(arrays,initial) + value = jax.jit(rhs)(initial) + if gc: + dx,dv = _guiding_center_velocity(field,Electric_field_zero(),s.Q,s.M,position,vpar,mu=moment) + expected = jnp.r_[dx,jnp.array([dv,0.,0.,0.,0.])] + else: + expected = jnp.r_[initial[3:6],s.Q/s.M*jnp.cross(initial[3:6],field.B_contravariant(position)),jnp.zeros(2)] + np.testing.assert_allclose(value,expected,rtol=3e-10,atol=1e-7) + changed,ed,es = jax.jit(kick)(initial,jnp.asarray(1e-9),jnp.zeros(2 if gc else 3)) + assert np.isfinite(changed).all() and ed >= 0 and es >= 0 + check_kick(kick,initial,field.AbsB(position),gc) + assert level(initial) > 0 and norm(initial,jnp.ones(8),4e5,1e-9) > 0 + with pytest.raises(ValueError): s._split_field_data(SimpleNamespace(table=True,sine_coef=None)) + from pathlib import Path + from essos.fields import Vmec + from essos.dynamics import _to_axis_regular, _axis_regular + from essos.boozer import guiding_center_rhs + vmec = Vmec(str(Path(__file__).resolve().parents[1]/'examples/input_files/wout_LandremanPaul2021_QA_reactorScale_lowres.nc'),ntheta=3,nphi=3) + for field in (vmec,tokamak()): + point = jnp.array([.3,.2,.1]) + B = field.AbsB(point) if isinstance(field,Vmec) else field.modB(*point) + moment = s.M*2e10/(2*B) + physical = jnp.r_[point,jnp.array([1e5,moment])] + initial = (_to_axis_regular(physical) if isinstance(field,Vmec) else + physical.at[0].set(jnp.sqrt(point[0])*jnp.cos(point[1])).at[1].set(jnp.sqrt(point[0])*jnp.sin(point[1]))) + nstate = initial.size; initial = jnp.pad(initial,(0,8-nstate)) + event = lambda t,y,a:4.-jnp.sum((y[:2]-jnp.array([.1,.2]))**2) + arrays,factory = s._prepare_split_field(field,background,gc=True,collision_tolerance=.003, + speed_floor=1.,state_size=nstate,event=event) + rhs,kick,norm,level = factory(arrays,initial) + value = jax.jit(rhs)(initial) + if isinstance(field,Vmec): + geometry,tables=s._split_field_data(field);direction=jnp.array([.2,-.1,.3]) + reference=jax.jvp(field.to_xyz,(point,),(direction,))[1] + np.testing.assert_allclose(_vmec_position_tangent(geometry,point,direction,tables),reference,rtol=3e-12,atol=2e-12) + def prepare_inside_jit(y): + arrays,factory = s._prepare_split_field(field,background,gc=True, + collision_tolerance=.003,speed_floor=1.,state_size=nstate) + return factory(arrays,y)[0](y) + np.testing.assert_allclose(jax.jit(prepare_inside_jit)(initial),value,rtol=3e-12,atol=1e-6) + def public_rhs(t,y,a): + dx,dv = _guiding_center_velocity(field,Electric_field_zero(),s.Q,s.M,y[:3],y[3],mu=y[4]) + return jnp.r_[dx,jnp.array([dv,0.])] + expected = jnp.pad(_axis_regular(public_rhs)(0.,initial[:nstate],None),(0,8-nstate)) + from essos.dynamics import _from_axis_regular + regular_rhs=_axis_regular(public_rhs) + settings=dict(gc=True,coordinate=True,tmax=.01,dtmax=.01,tolerance=.005) + def predictor(electric): + return native_step_limit(field,background,s.M,s.Q,initial[:nstate],regular_rhs, + _from_axis_regular,lambda y:field.to_xyz(_from_axis_regular(y)[:3]),field.AbsB, + electric_field=electric,**settings) + # A custom zero-E object follows the generic AD route; the built-in + # zero field selects the exact projected quotient derivatives. + fast=predictor(Electric_field_zero()) + reference=predictor(SimpleNamespace(E_covariant=lambda point:jnp.zeros(3))) + limits=jax.jit(lambda y:jnp.array([fast(0.,y,None),reference(0.,y,None)]))(initial[:nstate]) + assert 0= 0 and es >= 0 + check_kick(kick,initial,B) + assert np.isfinite(norm(initial,jnp.ones(8)*1e-12,4e5,1e-9)) + np.testing.assert_allclose(level(initial),event(0.,initial,None),atol=2e-15) + matrix = jnp.eye(2) + with pytest.raises(ValueError): + s._prepare_split_field(coil_field(),background,gc=True,collision_tolerance=.003, + speed_floor=1.,event=lambda t,y,a:jnp.sum(matrix@y[:2])) + + +def test_gpu_sampler_uses_the_production_threefry_normal_stream(): + key = jax.random.PRNGKey(19) + for dim in (2,3,5): + next_key, normal = jax.jit(lambda key:s._draw_normal(key,dim))(key) + expected_key, draw = jax.random.split(key) + expected = jax.random.normal(draw,(1<<(dim-1).bit_length(),),dtype=jnp.float64) + np.testing.assert_array_equal(next_key,expected_key) + np.testing.assert_allclose(normal,expected,rtol=2e-14,atol=2e-14) + original = jax.config.jax_threefry_partitionable + jax.config.update('jax_threefry_partitionable',False) + try: + with pytest.raises(ValueError): s._draw_normal(key,2) + finally: + jax.config.update('jax_threefry_partitionable',original) + + +def test_scalar_lowering_preserves_constants_slices_and_surface_values(monkeypatch): + x = jnp.array([.2,-.3,.4,.5,0.,0.,0.,0.]) + functions = (lambda x:x[1:2],lambda x:jax.lax.dynamic_slice(x,(x[0].astype(int),),(1,)), + lambda x:jnp.sin(x)+jnp.cos(x),lambda x:jax.lax.erf(x), + lambda x:jnp.array([jnp.sum(x),jnp.max(x),jnp.min(x)]), + lambda x:jnp.stack([x]),lambda x:x[jnp.array([2])], + lambda x:(jnp.any(x>0),jnp.all(x<1)),lambda x:tuple(x), + lambda x:tuple(jnp.split(x,len(x)))) + for function in functions: + graph = s._flatten(function,x) + actual = jax.jit(lambda x:s._evaluate_kernel(graph.jaxpr,graph.consts,x))(x) + for a,b in zip(actual,jax.tree.leaves(function(x))): np.testing.assert_allclose(a,b,atol=2e-15) + for function in (lambda x:jax.lax.dynamic_update_slice(x,x+1,(0,)),lambda x:jnp.pad(x,(1,0))): + small=jnp.array([.3]); graph=s._flatten(function,small) + actual=s._evaluate_kernel(graph.jaxpr,graph.consts,small,scalarize=True)[0] + np.testing.assert_allclose(actual,function(small),atol=2e-15) + from jax._src.lax.lax import _convert_element_type + graph=s._flatten(lambda x:_convert_element_type(x,np.dtype('float64'),weak_type=True),x) + np.testing.assert_allclose(jax.jit(lambda x:s._evaluate_kernel(graph.jaxpr,graph.consts,x)[0])(x),x) + for function in (lambda y:y[1:3],lambda y:jax.lax.dynamic_slice(y,(y[0].astype(int),),(2,)), + lambda y:y[jnp.array([1,2])],lambda y:jnp.concatenate((y,y,y))): + graph=s._flatten(function,x) + with pytest.raises(ValueError): jax.jit(lambda y:s._evaluate_kernel(graph.jaxpr,graph.consts,y))(x) + for function in (lambda y:1-jnp.sum(y[:3]**2),lambda y:jnp.dot(y[:3],y[:3])-.1, + lambda y:jnp.max(y[:3])-jnp.min(y[:3]),lambda y:y[jnp.array([1])][0], + lambda y:sum(y[:3]),lambda y:jnp.sum(jnp.array([y[0],y[1]])), + lambda y:y[:1].reshape(())): + graph = s._flatten(function,x) + np.testing.assert_allclose(s._evaluate_surface(graph.jaxpr,graph.consts,x),function(x),atol=2e-15) + flag = s._split_select(jnp.array([True,False]),1,0) + assert not flag[0] + def scanned(point,reverse): + carry,ys=jax.lax.scan(lambda a,b:(a+point[0]*b,a),point[1],point[2:5],reverse=reverse) + return jnp.r_[carry,ys] + interpolation=lambda point:jnp.interp(point[0],jnp.array([-1.,0.,1.]),point[1:4]) + for fn in (lambda p:scanned(p,False),lambda p:scanned(p,True),interpolation,jax.jacfwd(interpolation)): + flat=lambda p:tuple(jnp.ravel(fn(p)));graph=s._flatten(flat,x) + actual=jax.jit(lambda p:jnp.asarray(scalar_graph(graph.jaxpr,graph.consts,p)))(x) + np.testing.assert_allclose(actual,jnp.asarray(flat(x)),rtol=3e-13,atol=3e-14) + def bounded(p): + return jax.lax.while_loop(lambda c:c[0]<3+p[0], + lambda c:(c[0]+1,c[1]+p[1:3]),(jnp.asarray(0),jnp.ones(2)))[1] + flat=lambda p:tuple(bounded(p));graph=s._flatten(flat,x) + actual=jax.jit(lambda p:jnp.asarray(scalar_graph(graph.jaxpr,graph.consts,p)))(x) + np.testing.assert_allclose(actual,bounded(x),rtol=3e-13,atol=3e-14) + drift=jnp.array([0.,0.,1.8,0.,0.]);jac=jnp.arange(10.).reshape(5,2)*.01 + jet=CollisionJet(jnp.array([-.1,-.2]),jnp.array([.3,.4]),jnp.eye(2)*.1, + jnp.ones((2,2,2))*.01,jnp.ones((2,2))*.02,jnp.ones((2,2,2))*.002, + jnp.array([.001,.002]),jnp.array([.003,.004])) + def budget(velocity): + return expanded_moment_budget((drift,jac,jac*.1),jet,velocity,jnp.asarray(.005)) + velocity=jnp.array([3.,.6]);graph=s._flatten(budget,velocity) + actual=jax.jit(lambda v:jnp.asarray(scalar_graph(graph.jaxpr,graph.consts,v)))(velocity) + np.testing.assert_allclose(actual,jnp.asarray(budget(velocity)),rtol=3e-13) + prepared=_scalar_predictor(graph,KernelCalls()) + constants=tuple(word for value in graph.consts for word in jnp.ravel(value)) + def replay(v): + return jnp.asarray(scalar_graph(prepared.jaxpr,prepared.consts,*constants,*v)) + np.testing.assert_allclose(jax.jit(replay)(velocity),jnp.asarray(budget(velocity)),rtol=3e-13) + calls=KernelCalls() + original=lambda x,y,z:(x*x+y,jnp.sin(z),x*y*z) + fast=calls.first_jet(original,lambda refs,*point:original(*point)) + point=jnp.array([.2,.3,.4]);reference=lambda p:jnp.asarray(original(*p)) + value=lambda p:jnp.asarray(fast(*p)) + for fn in (lambda f:f,jax.jacfwd,lambda f:jax.jacfwd(jax.jacfwd(f))): + np.testing.assert_allclose(fn(value)(point),fn(reference)(point),rtol=3e-13,atol=3e-14) + graph=s._flatten(lambda p:(*fast(*p),*jax.jacfwd(value)(p).reshape(-1)),point) + prepared=_scalar_predictor(graph,calls) + assert sum(eq.primitive in calls.handlers for eq in prepared.jaxpr.eqns)==1 + # Older JAX keeps actual DropVars after inlining partially used calls. + # Coalescing must promote all required outputs into the shared definition. + from jax._src import core + calls=KernelCalls();formula=lambda x:(x*x,jnp.sin(x),x+3.) + call=calls.add(formula,lambda refs,x:formula(x),3) + def partial(x): + a,_,_=call(x);_,b,_=call(x);_,_,c=call(x) + return a+b+c + point=jnp.array(.2);legacy=jax.make_jaxpr(partial)(point) + used=set(legacy.jaxpr.outvars) + used.update(v for eq in legacy.jaxpr.eqns for v in eq.invars if not isinstance(v,core.Literal)) + legacy=type(legacy)(legacy.jaxpr.replace(eqns=[eq.replace(outvars=[ + v if v in used else core.DropVar(v.aval) for v in eq.outvars]) for eq in legacy.jaxpr.eqns]),legacy.consts) + core.check_jaxpr(legacy.jaxpr) + with monkeypatch.context() as patch: + patch.setattr(jax,'make_jaxpr',lambda *a,**k:lambda *v:legacy) + graph=s._flatten(partial,point) + core.check_jaxpr(graph.jaxpr) + assert sum(eq.primitive in calls.handlers for eq in graph.jaxpr.eqns)==1 + actual=jax.jit(jax.value_and_grad(lambda x:scalar_graph(graph.jaxpr,graph.consts,x,calls=calls)[0]))(point) + np.testing.assert_allclose(actual,(sum(formula(point)),2*point+jnp.cos(point)+1),rtol=3e-13) + powers=jnp.array([-.7, .7, 1.]) + for exponent in (-4,-2,-1,0,1,2,3,6): + actual=jax.jit(lambda v:s._kernel_integer_power(v,exponent))(powers) + np.testing.assert_array_equal(actual,jax.lax.integer_pow(powers,exponent)) + + +def test_independent_driver_rejects_invalid_work_limits(): + for name,value in (('max_steps',0),('max_orbit_steps',False),('max_pending',0)): + options = dict(max_steps=8,max_orbit_steps=8,max_pending=8) | {name:value} + with pytest.raises(ValueError): + s._solve_independent(None,None,jnp.zeros(5),field=None,species=None,gc=True, + birth_speed=1.,speed_floor=.1,collision_tolerance=.003,**options)