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.