OpenPFC documentation

OpenPFC is an MPI-parallel C++ framework for partial differential equations on structured grids. Spectral and finite-difference discretizations share MPI domain decomposition; spectral transforms use HeFFTe. Phase-field crystal models are the origin of the project and one application family, not the architectural boundary. The framework can be used in two ways:

• run one of the config-driven applications under apps/; or

• link the installed OpenPFC::openpfc library from another CMake project.

This is the maintained OpenPFC documentation site. Hand-written Markdown and the generated C++ API reference share one navigation tree and search index. Doxygen extracts source-level API information as XML; Sphinx, MyST, and Breathe render the final site.

Start by goal

Goal	Start here	Continue with
Run a first model and inspect its results	Start here	Native CLI guide
Verify a clone and dependency stack	Source-build check	Quick start
Compile a model or run a catalogued case	Native command-line workflow	HPC operator guide
Understand what each application solves	Applications catalog (research)	Applications overview
Run an existing application	Run simulations	Applications, configuration
Add or change physics	Extend the physics	Architecture, extension guide
Integrate the library	Integrate the library	Quick-start CMake example, API reference
Qualify homogeneous Dirichlet Q1 FEM/GMG on CPU/MPI	Nodal Dirichlet multigrid	Existing periodic numerics limits
Run on a cluster	HPC operator guide	Slurm day one, GPU decision guide
Decide whether OpenPFC fits	When to use OpenPFC	Numerical limits

Documentation structure

Area	Purpose	Entry point
concepts/	Stable mental models and architecture	Architecture, spectral stack, halo exchange
tutorials/	Guided, end-to-end learning	Tutorials
recipes/	Short copy-paste procedures	Recipes
user_guide/	Running applications, configuration, and output	Applications
hpc/ and lumi_slurm/	Cluster operation and site guidance	HPC operator guide
extending_openpfc/	Adding models and extension points	Extension guide
reference/	Lookup tables and file-format contracts	Main types, CMake options
api/	Generated declarations, overloads, namespaces, and source comments	C++ API reference
science/	Scientific context and model limitations	Tungsten quicklook
development/ and adr/	Maintainer guidance and decisions	Contributing to docs, ADRs
archive/	Historical 0.2 planning documents	Archive
workshop/	Multi-session teaching material	Workshop

Canonical ownership

Documentation is easier to maintain when each fact has one primary home:

Information	Canonical location
Supported dependency and toolchain setup	INSTALL.md
First successful build and run	start_here_15_minutes.md
0.1 → 0.2 API replacement list	MIGRATION_0.1_to_0.2.md
Broad build/run/integration overview	quickstart.md
Exact CMake option defaults	reference/build_options.md
Installed SDK identity and compatibility	Build manifest and consumer probe
JSON/TOML configuration keys	reference/spectral_app_config_reference.md
Application inventory	user_guide/applications.md
Example inventory	reference/examples_catalog.md
Public API signatures	api/index.md and public headers
Common failures	troubleshooting.md
Release-visible changes	CHANGELOG.md

Other pages should link to these sources instead of copying long option lists, API examples, or troubleshooting sections.

Runtime coupled field stepping describes owned-cell CPU RK stages, collective rejection and accepted-state integrity.

Implicit interfaces evaluate a static plane, sphere, or rotated ellipsoid on the Cartesian grid and integrate the two sides of a cut cell without replacing that grid.

Prose and generated API

Use narrative pages to understand workflows, concepts, trade-offs, and operational procedures. Use the generated API section for exact declarations and source-level Doxygen comments. The type tour connects common names to their layer, header, runnable example, and generated reference.

Both forms are rendered by Sphinx. MyST reads the Markdown tree, while Breathe imports Doxygen XML into the same site. This gives users one navigation model, one search index, one theme, and one published artifact.

Versioning and reproducibility

The documentation on master describes the development branch. For a tagged release, read the documentation from the same tag. Record the OpenPFC commit or release tag together with the HeFFTe and MPI versions used for a reproducible simulation. See documentation versioning.

Contributing

Code contributions are described in CONTRIBUTING.md. Documentation-specific structure, preview commands, and checks are described in Contributing to documentation.

Matrix-free Krylov solvers describes GMRES, flexible right preconditioning, true residual admission and the explicit SPD CG path.

Inexact Newton describes forcing tolerances, line search, trial rollback and the residual-based FFT adapter.

Structured multigrid describes volume-weighted transfers, coarse operators, nullspaces and the replicated MPI limitation.

Runnable Quarto chapters: OpenPFC by example.