Output formats¶
FACS writes native continuum text and HDF5/NetCDF results. The browser also offers continuum JSON. Optional Floquet scans can be saved as separate text or embedded in binary files. Plot filters and later form edits do not change the saved calculation.
Native output¶
Native builds enable binary output when the NetCDF C library with NetCDF-4
support is installed. CMake finds its package configuration or pkg-config
entry. Set -DFACS_ENABLE_NETCDF=OFF to build without it. The numerical
library has no NetCDF dependency; browser exports use bundled Wasm libraries.
The output suffix selects the format: .h5 and .hdf5 select HDF5; .nc
and .nc4 select NetCDF. Both use the same NetCDF-4-compatible HDF5 encoding.
Other suffixes keep the text format. Use --output-format text|hdf5|netcdf
to override the suffix, or auto to infer it.
./build/debug/facs equilibrium.g --model coupled --omega-max 0.5 -n 3 \
-o continuum.nc --include-floquet
./build/debug/facs equilibrium.g --model coupled --omega-max 0.5 -n 3 \
--period-integrated-alfvenicity -o continuum.h5 --include-floquet
--include-floquet embeds sampled scans in the binary result. Omit it to
save only the continuum and surface metadata. The separate
--floquet-output option continues to write text. Exporting
binary data does not enable either period measure; each requires its own flag.
Files store all three Alfvénicity measures, surface coordinates and safety factor,
typed solver settings, and optional matrix invariants and signed exponents.
See the binary schema and library writer
for the data layout, normalizations, missing-value rules, and FACS::io API.
Continuum text¶
The continuum file written by -o starts with the equilibrium poloidal flux
at the wall, then a comment # label_kind continuum_line for coupled runs
or # label_kind continuum_zone for scalar runs. A # line_method comment
records the grouping rule. Each coupled row starts
with n line_index, followed by groups of
rho_t omega alfvenicity, where rho_t = sqrt(psi_t/psi_t_wall) and omega
uses v_{A,0}/R_0. This Alfvénicity is the local effective-energy
measure (CSSC), computed for every coupled point without a separate export flag.
Alfvénic-only rows start with
n continuum_zone, followed by rho_t omega pairs. Readers must select the
point format for the calculation type.
After parallel surface solves, FACS assigns line IDs in radial order. A rank
keeps its ID while it remains present on consecutive surfaces. If it
vanishes, that segment ends; if it returns, it gets a new ID. Thus
line_index identifies a contiguous rank segment and can differ from the
rank after a gap. Text and JSON rows cannot bridge a missing surface.
Rank grouping preserves frequencies and multiplicities and adds no ODE
integrations. It follows frequency order through crossings, so a line can
change polarization. Energy and amplitude Alfvénicities remain
available for coloring and do not affect the connections. These segment IDs
are not poloidal mode numbers or Floquet bands. Saved output records
line_method="frequency_rank" (JSON uses line-method); see
the grouping algorithm and
the binary schema.
Continuum JSON¶
The browser JSON download also keeps the effective-energy measure,
regardless of the display selection. Coupled records contain line-index;
scalar records contain continuum-zone. Coupled points contain
[rho_t, omega, alfvenicity]; Alfvénic-only points contain [rho_t, omega].
Unresolved character is nan in the text file and null in JSON.
Floquet text¶
Use --floquet-output PATH to export each sampled frequency and
its Floquet analysis. A directory path selects the filename
floquet-analysis-<g-file name>.
The first line is sound_continuum 0 for Alfvénic only or sound_continuum 1
for coupled waves. Each following line stores one radial position in radial
order, starting with entry_count rho_t, then the entries below. Every complex
value uses two fields, Re Im. Numbers use enough digits to round-trip a double;
this does not increase the calculation's precision.
| Calculation | Fields in each entry | Numeric fields |
|---|---|---|
| Alfvénic only | omega TrM nu_1 nu_2 |
6 |
| Coupled | omega A B mu_1 mu_2 nu_1 nu_2 nu_3 nu_4 alpha_cssc_a alpha_cssc_b alpha_falessi_a alpha_falessi_b alpha_average_a alpha_average_b |
21 |
Here A = TrM, B is the second characteristic coefficient, and
mu = lambda + 1/lambda is a reciprocal trace. Frequencies use v_A,0/R_0
units. Exponents follow reciprocal-pair order: (nu_a, -nu_a) for Alfvénic
only and (nu_a, -nu_a, nu_b, -nu_b) for coupled waves. Scalar exponents keep
their band index; coupled representatives satisfy 0 <= Re(nu) <= 1/2.
The six appended real fields give all three Alfvénicities in reciprocal-pair
order, a then b. A stable pair and its conjugate share each value.
Unresolved values are nan; Falessi values are also nan when disabled or
for unstable pairs. Enable them with --period-integrated-alfvenicity.
Averaged-energy fields require --period-averaged-alfvenicity. Earlier
coupled text files had 19 fields (without the third definition) or 15
(without any Alfvénicity fields); the Python reader accepts both.
Scalar records keep six fields and describe purely Alfvénic waves.
The browser's Analysis → Text download writes this format for all saved
surfaces, regardless of which modes or surface the figures show.
Python plots¶
Install the Python dependencies, then plot a native coupled continuum with its sampled Floquet analysis:
python3 -m pip install -r script/requirements.txt
python3 script/plot_facs.py continuum continuum.txt --analysis floquet-analysis.txt \
--color-by local --rho-t 0.4 -o continuum.png
python3 script/plot_facs.py analysis floquet-analysis.txt --rho-t 0.4 \
--theme dark -o stability.pdf
Figures use the web app's light/dark colors, stability regions, and signed
Floquet curves. Native text needs --model coupled or --model alfven when
no analysis file supplies the model. Browser JSON records the model in its
line labels.
PNG, PDF, and SVG exports are supported. See Python tools
for filtering, limits, and the reusable reader and plotting APIs.
Example: Python spectrum and diagnostics.
For binary files, install script/requirements-binary.txt. Their model,
settings, and optional embedded scans are read automatically:
python3 -m pip install -r script/requirements-binary.txt
python3 script/plot_facs.py continuum continuum.nc --color-by local -o continuum.png
python3 script/plot_facs.py continuum continuum.h5 --color-by period-integrated -o falessi.pdf
Period-integrated plots use values saved by a run with
--period-integrated-alfvenicity.
Binary schema¶
FACS schema version 4 stores a calculation in NetCDF-4-compatible HDF5.
The .nc, .nc4, .h5, and .hdf5 extensions use the same encoding.
HDF5 datasets correspond to NetCDF variables; NetCDF supplies dimension
scales. All floating data use IEEE float64, with NaN as _FillValue.
Metadata and settings¶
The root attributes are format="FACS", schema_version=4,
producer_version, model="alfven" or "alfven_sound", and four int8
flags: falessi_enabled, averaged_enabled, floquet_included, and complete. A reader must
check the schema version and require complete=1. An interrupted export
can leave an incomplete file.
/run/toroidal_mode[mode] is an int32 array. /run holds these typed
attributes after argument defaults have been applied:
| Attribute | Type | Meaning |
|---|---|---|
psi_ratio |
float64 | Resolved poloidal flux cutoff relative to wall flux, including conversion from --rho-max. |
radial_grid_num |
int32 | Requested radial resolution; 0 selects an adaptive grid. |
omega_grid_num |
int32 | Coupled uniform count, or the effective fallback count for adaptive sampling. |
max_omega_value |
float64 | Global dimensionless frequency cutoff. |
max_continuum_zone |
int32 | Scalar zone cap; 0 selects the frequency cutoff. |
adiabatic_index |
float64 | Ratio of specific heats. |
adaptive_omega_grid |
int8 | Adaptive coupled frequency scan flag. |
refine_coupled_roots |
int8 | Full coupled root refinement flag. |
thread_count_requested |
int32 | Requested threads; 0 selects automatically. |
thread_count_used |
int32 | Actual worker count. |
input_file |
text | Input filename supplied by the application. |
compute_backend_requested |
text | Requested calculation backend. |
compute_backend |
text | Accepted backend; mixed means CPU and GPU supplied accepted surfaces. |
scan_precision |
text | float64, float32, paired-f32, or mixed. |
approximate |
int8 | 1 when an approximate GPU backend supplied accepted surfaces. |
frequency_normalization |
text | Omega = omega_physical * R0 / v_A0. |
poloidal_coordinate |
text | boozer_theta. |
cssc_definition |
text | Local signed channel energies at θ=0, compared by absolute value. |
average_definition |
text | Signed channel energies averaged over the full θ period, then compared by absolute value. |
falessi_definition |
text | CFC amplitude fraction evaluated in θ with the squared Jacobian-ratio kernel. |
The saved settings use effective solver values. The CLI default
--omega-samples 0 records adaptive_omega_grid=1 and omega_grid_num=1025
for coupled runs. A positive count records adaptive_omega_grid=0 and that
uniform count. The CLI sentinel zero is never passed to the coupled sampler.
These values and coordinates support analysis and plotting. They do not store the full equilibrium or a density needed to recover physical frequency. See WebGPU metadata for fallback conventions.
Surfaces and continuum¶
surface indexes calculation surfaces in their original order. Equal radii
remain separate surfaces. line indexes continuum lines sorted by
(n,line_index). Ambiguous connections start new line IDs. point indexes
their concatenated points. All indices and starts are zero-based.
| Path | Shape | Type |
|---|---|---|
/equilibrium/psi_wall |
scalar | float64 |
/surfaces/rho_t |
[surface] |
float64 |
/surfaces/psi_over_psi_wall |
[surface] |
float64 |
/surfaces/q |
[surface] |
float64 |
/continuum/n, /continuum/line_index |
[line] |
int32 |
/continuum/point_start, /continuum/point_count |
[line] |
int64 |
/continuum/surface_index |
[point] |
int64 |
/continuum/omega |
[point] |
float64 |
/continuum/alfvenicity_cssc |
[point] |
float64 |
/continuum/alfvenicity_falessi |
[point] |
float64 |
/continuum/alfvenicity_average |
[point] |
float64 |
psi_wall is the outward normalized poloidal wall flux,
psi_p_wall/(R0^2 abs(B0)). The plotted radius is
rho_t=sqrt(psi_t/psi_t_wall). psi_over_psi_wall uses poloidal flux;
q retains its sign. omega is the global dimensionless frequency Ω,
normalized to v_A0/R0. Each numeric variable has units and long_name
attributes explaining its convention.
For line i, slice point arrays from point_start[i] to
point_start[i]+point_count[i]. Recover radii with
surfaces/rho_t[continuum/surface_index]. /continuum has index_base=0
and label_kind="continuum_zone" for scalar waves or "continuum_line"
for coupled waves. Scalar line_index stores the continuum zone. Coupled
line_index is a nonnegative ID for a contiguous frequency-rank segment,
assigned separately for each n. The lowest root joins the lowest on the
next surface, the second joins the second, and so on. A missing rank ends
its segment; a returning rank gets a new ID. Consequently line_index need
not equal the frequency rank after a gap.
The /continuum/line_method text attribute records "frequency_rank" for
coupled runs and "continuum_zone" for scalar runs. Earlier schema-3 files
may omit it; the reader returns line_method=None. The attribute distinguishes
the grouping rule without changing the schema layout. Text stores it in a
# line_method comment; JSON uses line-method. Frequency-rank lines
can change polarization at a crossing. Alfvénicity controls optional coloring,
not the grouping. See the grouping algorithm.
Version 1 used /continuum/label and label_kind="frequency_rank" for
coupled output. Version 2 used branch_index, band_index, and
label_kind="floquet_branch_band". Python readers accept all four versions:
new curve IDs and old ranks are integers; version-2 coupled labels remain
(b,j) tuples. Legacy unresolved pairs remain separate rows. Floquet scan
arrays keep their per-sample reciprocal-trace order in all four versions.
Optional Floquet analysis¶
When floquet_included=1, /floquet holds a concatenated scan array and
per-surface starts and counts. Counts can be zero. The sample grid can
differ between surfaces; no padding or interpolation is applied.
Variable under /floquet |
Shape | Type |
|---|---|---|
sample_start, sample_count |
[surface] |
int64 |
sign |
[sign=2], values +1,-1 |
int32 |
omega, A, B |
[sample] |
float64 |
nu_real, nu_imag |
[sample,pair,sign] |
float64 |
mu_real, mu_imag |
[sample,pair] |
float64 |
alfvenicity_cssc, alfvenicity_falessi, alfvenicity_average |
[sample,pair] |
float64 |
There is one reciprocal pair for scalar waves and two for coupled waves.
The stored ν values follow the solver: scalar exponents retain band indices;
coupled representatives are folded. The last dimension stores explicit
+nu,-nu partners, including signed imaginary parts and signed zero.
Pair order follows each sample's reciprocal traces, without physical branch
tracking or further phase folding.
A=tr(M), B=((tr M)^2-tr(M^2))/2, and mu=lambda+1/lambda for the
one-period fundamental matrix M. Scalar conventions are B=NaN,
mu=A+i0, and CSSC Alfvénicity 1 for a pure Alfvénic wave.
Continuum and scan arrays keep three independent measures:
| Field | Definition | Availability |
|---|---|---|
alfvenicity_cssc |
Local effective energy at θ=0 (default) | Always computed; scalar convention is 1. |
alfvenicity_falessi |
Period-integrated amplitude | Requires --period-integrated-alfvenicity. |
alfvenicity_average |
Period-averaged effective energy | Requires --period-averaged-alfvenicity. |
The /run definition attributes record each formula and normalization.
Both optional arrays contain NaN when disabled or for scalar runs. When
enabled, NaN means unavailable or unresolved. The two period measures share
one propagation pass when both flags are set. Falessi evaluates the
continuum-flux-coordinate norm on the existing Boozer θ grid over [0,2*pi] with
\(W=(J_\theta/J_\eta)^2\propto|\nabla\psi|^{-4}\).
Earlier files contain an unweighted θ norm under the same field name;
their /run/falessi_definition attribute records that earlier formula.
Schema 4 adds the average arrays and flag and restores local CSSC values.
Readers require those new fields in schema 4. Schemas 1–3 without an average
return NaN for the third definition. Some schema-3 files instead stored
averaged CSSC values, identified by a /run/cssc_definition beginning
|<E_A>|. For coupled files, Python returns those values as
alfvenicity_average and fills the unavailable local values with NaN.
Scalar CSSC remains 1. Earlier text/JSON lacks this metadata, so the reader
preserves its energy column without inferring a definition.
Browser downloads¶
The browser uses the same writer in a separate Wasm worker. Choose Continuum → NetCDF/HDF5 for continuum and surface data, or Analysis → NetCDF/HDF5 to include every saved scan. JSON continuum and text analysis remain available from the same control.
The export keeps the original calculation surface indices, mode-group order, and empty scans. The plots may merge repeated radii or hide modes; those display choices do not change the file. Settings come from the completed run, with the requested and actual thread counts recorded separately. File export performs no integrations and never enables a period measure.
Library writer¶
Link FACS::io and include output_file.h. Construct facs::OutputFile
with the path, SolverSettings, toroidal modes, optional source filename,
and whether to include scans. For scans, set capture_scan=true. Call
append_surface from surface_ordered, then call finish(result). For scan
export, do not set surface_ready: that callback takes diagnostic ownership
before surface_ordered. The writer streams each scan and retains only
surface fluxes and continuum surface indices.
Calls into NetCDF are serialized across writers. finish checks writes and
close; destruction closes an unfinished file without marking it complete.
The numerical FACS::lib target has no NetCDF dependency.