FACS solver documentation

FACS computes the local Alfvénic continuum and the coupled Alfvénic–acoustic continuum of an axisymmetric equilibrium. It builds periodic coefficients on each flux surface, integrates their fundamental matrix, and finds the frequencies that satisfy the field-line phase condition.

Document Contents
Quick start Build, calculate a continuum, and plot the result.
Build and test Native and browser builds, dependencies, worker pool, and bundled equilibria.
Command line Options, sampling controls, threads, and progress.
Browser Setup, plots, zoom refinement, Floquet solutions, and screenshots.
Library API CMake targets, reusable equilibria, callbacks, and coordinate conventions.
Output formats Text, JSON, HDF5/NetCDF schema, downloads, and library writer.
Python and timing tools Readers, plotting APIs, and benchmark commands.
Theory Units, governing equations, Floquet spectra, boundary charts, and Alfvénicity.
Algorithms Equilibrium construction, coefficient caching, Verlet integration, scans, root refinement, and output.
Numerical details Grids, tolerances, stability checks, regression tests, convergence methods, and computational cost.
WebGPU GPU buffers, spline sampling, paired precision, fallback, rendering, and validation.
WebGPU measurements Dated timing comparisons, setup costs, memory use, and accuracy checks.
Deployment Cloudflare Pages builds, uploads, and GitHub Actions.

Start with the quick start, then choose the guide for your frontend. The theory and numerical pages describe the native and WebAssembly solver; the WebGPU guide states the approximate backends' limits.

Implementation map

Source Responsibility
equilibrium.h Normalized equilibrium fields, Fourier derivatives, axis limits, and continuum coefficients.
MagneticEquilibrium.h Flux contours and the Boozer grid.
util.h Real FFT and filtered angular derivatives.
integrator.h Shared fundamental-matrix integration.
Floquet.h Scalar coefficient cache, monodromy matrix, and full Floquet exponent.
floquet_curve.h Scalar adaptive frequency scan and mode refinement.
coupled_floquet.h Coupled matrices, reciprocal spectra, boundary eigenvectors, and Alfvénicity.
coupled_floquet_curve.h Coupled fixed scans, crossing checks, and rational-surface refinement.
solver.h Shared radial calculation, result aggregation, and progress callbacks.
output_file.h Optional native HDF5/NetCDF output writer.
cli/main.cpp Native entry point and terminal progress.
web/main.cpp Browser worker lifecycle and JavaScript bridge.
webgpu_solver.js GPU surface pipeline, batching, buffers, and fallback.
webgpu_coefficients.js GPU field-polynomial sampling.
plot_gpu.js GPU figure geometry and raster rendering.
lib/app/ Shared argument parsing and file handling.
coupled-test.cpp Analytic coupled spectra, close roots, multiplicity, and boundary cases.

The CLI uses double precision. Template tests also exercise single precision where the required root separation permits it. The native and browser builds share facs::Solver for CPU calculations.