Library API¶
CMake consumers can add this repository with add_subdirectory and link
FACS::lib. It supplies the public include paths, C++20, and thread support.
Include solver.h and use facs::Solver::calculate with an equilibrium,
typed facs::SolverSettings, and a toroidal-mode list. calculate_gfile
accepts a g-file stream. Both return mode lines and calculation statistics;
optional callbacks provide progress, owned worker previews, and ordered
surface exports. The core target has no argument parser or browser code.
The separate FACS::app target shares argument and file handling between
the two applications.
Reuse an equilibrium¶
Solver::prepare_gfile(stream) constructs an immutable shared equilibrium
for reuse with several settings. Include equilibrium.h and pass
*equilibrium to calculate. Preparation uses the same parser and grids as
calculate_gfile and shares its g-file mutex.
SolverCallbacks::equilibrium_ready can retain the immutable equilibrium
created by calculate_gfile. It runs on that method's caller thread, after
construction and before continuum sampling. The callback does not imply
that the later calculation succeeds.
Set SolverSettings::rho_max to limit the normalized toroidal-flux radius.
When present, it overrides psi_ratio; SolverResult::psi_ratio reports the
resolved poloidal-flux cutoff. SolverResult::psi_max remains the wall flux.
Callbacks and concurrency¶
A solver handles one calculation at a time. Worker previews may arrive concurrently; ordered callbacks run on the calling thread. G-file calculations serialize because libmeq uses a shared timer and prints equilibrium diagnostics.
For streamed binary exports, use the library writer.
Custom equilibria¶
Custom equilibria that enable period-integrated amplitude must supply
normalized_flux_gradient(psi, theta), the positive angular shape of
|grad psi| with a finite axis limit. A common surface factor cancels.
NumericEquilibrium supplies |grad psi| / sqrt(2*psi) and its Miller-axis limit.
Floquet solutions¶
Include floquet_solutions.h to sample full Floquet fields on an existing
coefficient grid with facs::sample_scalar_floquet_solutions or
facs::sample_coupled_floquet_solutions. Each call integrates the identity
fundamental matrix once, saves its position rows, and transforms them with
the final monodromy eigenvectors. An optional observer receives the identity
rows at node zero and the position rows at every later node. The returned
profiles include both endpoints and satisfy f(2π) = λ f(0), with
λ = exp(2π i ν). Unresolved profiles have empty field arrays.
GEQDSK conventions¶
GEQDSK input uses the producer named in the first-line metadata to infer its
coordinate convention: CHEASE defaults to COCOS 2; EFIT and unknown producers
use the EFIT conventions, with current, flux and q signs selecting COCOS 1,
3, 5 or 7. A header tag such as COCOS=11 or COCOS_OUT=11 takes precedence.
For direct libmeq use, data.read(stream, Cocos(11)) overrides the header.
Producer detection is a guess; specify the index for files exported in another
convention. See libmeq's convention and unit rules.
libmeq converts the physics to COCOS 2; mode numbers refer to those coordinates. FACS uses outward-increasing radial flux divided by R_axis²|B_axis| while retaining signed q and coupling. This supports either current direction and either toroidal-field direction, including files that store full poloidal flux instead of flux divided by 2π.