Command-line guide

./build/debug/facs equilibrium.g --model coupled --omega-max 0.5 \
    --toroidal-modes 3,5 --output continuum.nc --include-floquet

Options

Option Meaning and default
--model alfven\|coupled Alfvén waves or coupled Alfvén–sound waves; default alfven.
--omega-max VALUE Frequency cutoff in units of v_A0/R0; required for coupled.
-m, --zone-max N Alfvén continuum-zone cutoff; default 2 when no frequency cutoff is supplied.
--psi-max VALUE Normalized poloidal-flux cutoff in (0,1]; default 0.8.
--rho-max VALUE Normalized toroidal-flux radius cutoff in (0,1]; an alternative to --psi-max.
--omega-samples N Coupled sampling: 0 selects adaptive sampling (default); N >= 2 selects exactly N uniform samples.
--radial-resolution N 0 selects adaptive radial sampling (default); a positive integer sets the prescribed grid resolution.
-n, --toroidal-modes LIST Comma-separated nonzero signed 32-bit integers; default 3,5.
-o, --output PATH Continuum output path; default continuum-INPUT_FILENAME.
--floquet-output PATH Separate text Floquet analysis; omitted by default.
--threads N Worker count; 0 chooses automatically (default).
--adiabatic-index VALUE Positive ratio of specific heats; default 5/3.
--refine-coupled-roots Refine every coupled root with direct matrix evaluations.
--period-integrated-alfvenicity Compute the optional period-integrated amplitude fraction; coupled only.
--period-averaged-alfvenicity Compute the optional period-averaged effective energy; coupled only.
--output-format auto\|text\|hdf5\|netcdf Select the output format; default auto uses the suffix.
--include-floquet Embed sampled scans in binary output.

--zone-max and --omega-max are mutually exclusive. The scalar model uses its own adaptive frequency sampler; --omega-samples controls coupled runs. The solver and Python plotting command share --model, --toroidal-modes, --omega-max, and --output. For signed lists, both accept --toroidal-modes -3,5 and --toroidal-modes=-3,5. Earlier option spellings have no compatibility aliases. Run facs --help for all options.

--rho-max uses the plotted radius, ρₜ = sqrt(ψₜ/ψₜ,wall). For example, --rho-max 0.9 limits the calculation to ρₜ ≤ 0.9. The solver inverts the equilibrium's toroidal flux to find the poloidal-flux cutoff; it does not assume ψₚ/ψₚ,wall = ρₜ². Supply either --rho-max or --psi-max, not both. Binary output records the resolved cutoff in run.psi_ratio.

Models and accuracy

The coupled model requires a positive --omega-max, in units of v_{A,0}/R_0. The g-file pressure sets the acoustic wave speed. Density stays uniform, as in the Alfvénic calculation. The ratio of specific heats defaults to 5/3; set it with --adiabatic-index. Each sampled surface must have positive pressure.

Coupled runs use adaptive frequency sampling by default. --omega-samples 0 starts from 129 seed nodes and refines near stability boundaries. If a scan would exceed 4,097 evaluations, it falls back to 1,025 uniform samples and reports the event. The seed and fallback counts are internal defaults. Adaptive Floquet exports retain each surface's variable point count.

Use --omega-samples N, with N >= 2, for exactly N equally spaced samples including zero and --omega-max. Counts of 1, negative values, and malformed integers are rejected. Root checks and optional refinement can evaluate extra matrices without changing the exported scan grid. The scalar model keeps its own adaptive sampler.

Both coupled scan modes cache matrices at their exact frequencies for reuse across all requested toroidal modes. Ordinary crossings use interpolation; --refine-coupled-roots evaluates them directly. A finite scan can miss narrow gaps, tangencies, or close modes. Compare denser scans and check angular convergence; the fixed 8,192-step grid also imposes a Verlet stability limit. See algorithms and numerical limits for the criteria, tolerances, and convergence checks.

Local effective-energy Alfvénicity is always available for coupled modes. The two period flags enable their respective measures; neither binary output nor --include-floquet enables them. See the definitions and output formats and plotting.

Threads and progress

Radial surfaces run concurrently. Set --threads N to use at most N calculation threads, including the calling thread. In native builds, the default, --threads 0, uses the hardware thread count, capped by the number of surfaces. Use --threads 1 for serial execution. The scheduler splits the ordered radial samples into one contiguous section per thread, balancing estimated work. Each thread processes its own section in order. When it has no unclaimed samples left, it helps other sections by claiming their unstarted samples. Each surface keeps its adaptive omega scan and all toroidal modes on one thread, sharing its matrix cache across modes.

Before starting these sections, FACS samples the Alfvénic and acoustic coefficients at eight angles per surface. Their phase span gives a rough omega scan count; root, coloring, and coefficient work add to the scheduling weight. This estimate runs no matrix integrations or pilot frequency scans. It guides scheduling and does not set the solver's sampling or accuracy. Narrow gaps and crossings can make the actual work differ substantially.

The progress display shows the estimated scan evaluations and remaining time. Time uses ordinary completed surfaces; before one finishes, it says "Estimating time". Later browser runs in the same page can reuse timings for the same solver mode, sampling mode, root-refinement setting, and actual thread count. The estimate follows the slowest unfinished section and updates when work moves between threads. A surface can exceed its prediction; the display then waits for a new timing instead of counting down to zero. One expensive surface cannot be divided among threads.

Progress uses one bar per calculation thread:

Thread 1: [#####-----------] 3/9, psi/psi_w = 0.1234, omega sample = 1467

The bar and fraction show completed and assigned radial samples. Both counts are padded to the width of the run's total radial count. Assigned totals move between threads when one helps another, so a bar can step back when its thread takes on more work. Flux and omega sample counts describe the last completed surface; -- means none has finished yet. Terminals update these lines in place with cursor controls. Redirected output, TERM=dumb, and terminals too small for the block receive a plain final snapshot. The browser updates the same lines above its output log.

Output files and Floquet exports retain radial order. Reported surface work times sum the time spent by all workers; the radial calculation timer reports wall time. The browser has a bounded pthread pool.