Field sources and coordinates¶

This page tells you which files to give SIMPLE for each kind of magnetic field and which integration coordinates work with it. Keys belong to the &config namelist of simple.in (Input parameters).

Method: Coordinates and field representation.

Input files¶

field_input (default ''): The magnetic field: VMEC wout (.nc), Boozer chartmap (.nc), SPECTRE (.h5) or a coil file. The type is detected from the file.
coord_input (default ''): The reference coordinates in which start points and results are given: a VMEC wout file or a chartmap. Empty means netcdffile, then field_input.
netcdffile (default ''): VMEC wout file; fallback for both keys above. Where a VMEC file is required and all three are empty, wout.nc is used.

Integration coordinates¶

integ_coords selects the coordinates in which orbits are integrated. Its older alias isw_field_type (default 0) applies when integ_coords is unset (default -1000).

Value	Name	Coordinates	Use
0	CANFLUX	\((s, \vartheta_c, \varphi_c)\)	canonical flux coordinates from VMEC; symplectic
1	VMEC	\((s, \vartheta, \varphi)\)	VMEC; `integmode = 0` only
2	BOOZER	\((s, \vartheta_B, \varphi_B)\)	Boozer, from VMEC or a Boozer chartmap; symplectic; standard for nested flux surfaces
3	MEISS	\((\rho, \vartheta_c, \varphi_c)\)	canonical without flux surfaces, e.g. coils; symplectic
4	ALBERT	\((\psi, \vartheta_c, \varphi_c)\)	as MEISS with \(\psi \propto A_\vartheta\); symplectic
5	REFCOORDS	reference coordinates	`field_input` splined on `coord_input`; `integmode = 0`
6	SPECTRE	\((\rho_g, \vartheta, \zeta)\)	per-volume SPECTRE/SPEC
-1	TEST	\((r, \vartheta, \varphi)\)	analytic tokamak for tests

VMEC equilibria¶

&config
netcdffile = 'wout.nc'
isw_field_type = 2      ! Boozer
/

SIMPLE splines VMEC’s \(R\), \(Z\) and \(\lambda\) over \(s\) (order ns_s, default 5) and the angles (order ns_tp, default 5, on \(m_\text{max}\,\) multharm \(+1\) poloidal and \(n_\text{max}\,\) multharm \(+1\) toroidal points, multharm default 5), transforms to Boozer or canonical flux coordinates and splines the canonical field components. axis_healing selects how the VMEC harmonics are continued to the axis; use 'polyfit', which replaces them below s_axis_heal (default 0.01) by a polynomial in \(s\).

vmec_B_scale and vmec_RZ_scale (default 1) multiply the field and the device size, for scans without a new equilibrium. The scaled field is an MHD equilibrium only with consistently scaled pressure.

Start positions (sbeg, start.dat) are given in VMEC coordinates \((s, \vartheta, \varphi)\).

Boozer chartmaps (GVEC, booz_xform)¶

A Boozer chartmap is a NetCDF file with geometry and Boozer field components on a uniform grid; no VMEC file is needed:

examples/simple_chartmap.in¶

&config
trace_time = 1d-2        ! slowing down time, s
sbeg = 0.3d0             ! starting s (normalized toroidal flux) for particles
ntestpart = 128          ! number of test particles
field_input = 'boozer_chartmap.nc'  ! Boozer chartmap NetCDF file for field data
coord_input = 'boozer_chartmap.nc'  ! same file for reference coordinates
isw_field_type = 2       ! Boozer field type
deterministic = .True.   ! fixed random seed for reproducibility
integmode = 1            ! Euler symplectic integrator
multharm = 5             ! angular grid factor
/

sbeg stays the normalised toroidal flux \(s\); positions in start.dat and the outputs use the chartmap radius \(\rho=\sqrt{s}\). Format, signs and scaling: Boozer chartmap format. Converters:

# GVEC (gvec Python package; installed by setup-venv.sh)
python tools/gvec_to_boozer_chartmap.py parameter_final.ini State_final.dat \
    boozer_chartmap.nc
# booz_xform
python tools/booz_xform_to_boozer_chartmap.py boozmn_case.nc boozer_chartmap.nc

Both take --nrho, --ntheta and --nphi (GVEC) or --nzeta (booz_xform). The GVEC converter reverses one angle (--flip tor, default, or pol) for SIMPLE’s left-handed convention; its tested workflow is test/tests/run_gvec_qa_roundtrip.py.

IMAS equilibrium IDS¶

pysimple.imas converts an axisymmetric equilibrium IDS through libneo into a Boozer chartmap and traces IDS markers in it; positions and outputs use the chartmap radius \(\rho\). Setup and conventions: IMAS workflow.

Coil fields¶

Coil fields follow particles outside the last closed flux surface (LCFS). The coil file is text: the number of points, then \(x, y, z\) (m) and current (A) per line. Points \(i\) and \(i+1\) are joined by a straight segment carrying the current of point \(i\); a zero current ends a coil. Convert STELLOPT/MAKEGRID files with

python test/tests/convert_coils_stellopt_to_simple.py coils.c09r00 coils.simple

python -m libneo.convert_coils_to_simple drops the zero-current points and so joins consecutive coils by spurious segments; do not use it for SIMPLE.

Coil fields need integ_coords = 3 or 4, or integ_coords = 5 with integmode = 0. A VMEC file still provides start positions and reference coordinates unless coord_input is a chartmap:

&config
netcdffile = 'wout.nc'
field_input = 'coils.simple'
isw_field_type = 3      ! Meiss
/

SIMPLE does not check that coils and equilibrium describe the same field.

Chartmaps beyond the LCFS¶

Wall losses need reference coordinates that continue beyond the LCFS. libneo writes such a chartmap from a VMEC file:

export PYTHONPATH=build/_deps/libneo-src/python
python -m libneo.chartmap_cli from-vmec-extended wout.nc chartmap_wall.nc \
    --nrho 33 --ntheta 65 --nzeta 33 --boundary-offset 0.15

The global attribute rho_lcfs records the LCFS radius. chart_boundary_kind (default 'auto') declares what the outer chartmap boundary is: 'lcfs' (loss, exit code 1), 'wall' (exit code 2) or 'domain' (numerical exit 101); 'auto' means 'lcfs' if rho_lcfs = 1, else 'domain'. The subcommands from-stl (chartmap inside an STL boundary) and from-vmec-to-wall (VMEC extended to an STL wall) need the Python packages map2disc and shapely.

SPECTRE equilibria¶

SPECTRE/SPEC multi-region relaxed MHD equilibria (HDF5) require integ_coords = 6. SIMPLE integrates guiding-centre orbits inside each volume and full orbits near the interfaces, where the field jumps:

examples/simple_spectre.in¶

&config
! Generate starting points on the committed multi-volume tokamak field.
! Copy test/tests/data/tok2vol.h5 next to this input and run
! ./build/simple.x simple_spectre.in. This input samples start points only.
! Set generate_start_only = .False. for multi-volume hybrid orbit tracing;
! see DOC/spectre-interface-crossing.md for its requirements and limits.
generate_start_only = .True.
field_input = 'tok2vol.h5'   ! SPECTRE HDF5 equilibrium (VMEC-free)
integ_coords = 6             ! SPECTRE per-volume stacked-rho chart
integmode = 3                ! symplectic midpoint (per-volume Meiss canonical)
trace_time = 1d-4            ! slowing-down trace time, s
sbeg = 0.5d0                 ! starting rho_g (SPECTRE radial label) for markers
ntestpart = 64               ! number of markers, area-weighted over the surface
ntimstep = 100               ! confined_fraction.dat time bins
npoiper2 = 256               ! integration steps per toroidal turn
facE_al = 8.0                ! 437.5 keV
relerr = 1d-11               ! integrator relative tolerance
deterministic = .True.       ! fixed seed for reproducible sampling
ran_seed = 12345
! Per-volume Meiss construction grid. spectre_ncon_phi = -1 (default) auto-clamps
! phi for axisymmetric fields (the tokamak memory saver); set r/th smaller for
! multi-volume cases, or spectre_ncon_phi = 32 to force the full phi resolution.
spectre_ncon_r = 48
spectre_ncon_th = 48
spectre_ncon_phi = -1
/

sbeg is the SPECTRE radial label \(\rho_g \in [0, M_\text{vol}]\), or \(s\) with spectre_sbeg_is_toroidal_flux = .true. (startmode = 1). The interface controls spectre_fo_entry_larmor, spectre_fo_tolerance and spectre_fo_grid are explained in Full orbit, SPECTRE and GPU objective.

Each volume builds its own Meiss canonical coordinates on a grid of spectre_ncon_r (default 48) by spectre_ncon_th (48) by spectre_ncon_phi points. With spectre_ncon_phi = -1 (default) SIMPLE uses 32 points, or 8 for an axisymmetric field (all toroidal mode numbers zero); a positive value is used as given. Memory scales with \(M_\text{vol}\,n_r n_\vartheta n_\varphi\); the log line spectre_construction_grid reports the grid in use.