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π.