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.