CLI reference

The vmec command is a drop-in equivalent of the xvmec2000 executable: it parses the input deck, runs the NS_ARRAY multigrid ladder with VMEC2000-format console output, writes wout_<case>.nc, and prints the termination summary.

Usage

vmex input.X                — solve (INDATA or VMEC++ JSON), write wout_X.nc
vmex --plot wout_*.nc       — diagnostic plots from a WOUT file
vmex --plot mout_*.nc       — straight-axis mirror diagnostics
vmex --booz wout_*.nc       — run booz_xform_jax, write boozmn_*.nc
vmex --plot boozmn_*.nc     — Boozer contour/spectrum plots
vmex --doctor               — installation and JAX backend diagnostics
vmex --test                 — run and plot the bundled quick-start case

The positional argument is a VMEC input file (input.* namelist or a VMEC++-style .json deck), or a wout_*.nc/mout_*.nc/boozmn_*.nc file for --plot/--booz.

Options

Option

Meaning

--plot [PATH]

Generate plots. With a wout_*.nc file, plot WOUT diagnostics; with a mout_*.nc file, plot horizontal straight-axis mirror diagnostics; with a boozmn_*.nc file, plot Boozer diagnostics; with an input file, solve first and plot the resulting WOUT.

--booz

Run booz_xform_jax after solving, or directly from a wout_*.nc file, and write boozmn_*.nc.

--mbooz N / --nbooz N

Boozer poloidal / toroidal resolution (default 32 each).

--booz-surfaces S

Boozer surfaces: comma/space-separated normalized s values, or all (default).

--outdir DIR

Directory for wout/boozmn/figure output (default: alongside the input).

--quiet

Silence the VMEC-style stdout.

--mode {cli,jit}

Solver lane: cli (jitted blocks with host residual checks, live printing, exact-ftol exit; default) or jit (single lax.while_loop).

--ftol X

Override the final-stage FTOL_ARRAY tolerance.

--max-iter N

Override the final-stage NITER_ARRAY iteration cap.

--coils PATH

ESSOS-style coils file (.json or .npz with dofs_curves, dofs_currents, n_segments, nfp, stellsym) supplying the external field of an LFREEB = T deck directly via Biot-Savart (pairs with MGRID_FILE = 'DIRECT_COILS').

--doctor

Print installation, Python, package, and JAX backend diagnostics.

--test

Run the bundled input.nfp4_QH_warm_start quick-start case: solve, write the wout file, and plot it (into ./vmex_test/ or --outdir).

--version

Print the package version.

Free-boundary routing

For LFREEB = T decks:

  • a readable MGRID_FILE runs the free-boundary solver with the VMEC2000 console output (In VACUUM block, VACUUM PRESSURE TURNED ON banner) and free-boundary wout metadata (nextcur/extcur/curlabel/ mgrid_mode);

  • a missing mgrid file falls back to a fixed-boundary solve with a warning (VMEC2000 behavior, dropped by VMEC++);

  • MGRID_FILE = 'DIRECT_COILS' (or the --coils flag) builds the external field from an ESSOS coils file (essos.coils.Coils): the coils are tabulated into an in-memory mgrid (Coils.to_mgrid) and read back as an vmex.core.mgrid.MgridField (requires ESSOS).

Known divergences of the current free-boundary lane: it is single-grid (only the final NS_ARRAY stage runs; multi-stage decks print a note), and the NESTOR potential is not yet exported to the wout potsin/xmpot/ xnpot/*_sur variables (written as netCDF fill). An NITER-exhausted free-boundary run still writes the wout (VMEC2000 behavior) and exits with ier_flag = 2.

Exit codes (zero-crash policy)

Every failure maps to a typed vmex.core.errors.VmecError; the CLI prints the VMEC2000 werror message plus a one-line hint and exits with the matching ier_flag code (0 on success, 2 for “MORE ITERATIONS REQUIRED”, etc.). There are no raw tracebacks in normal operation.