OpenPFC documentation

OpenPFC is an MPI-parallel C++ framework for phase-field crystal and related spectral phase-field models on structured grids. 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
Verify a clone and dependency stack	Start here	Quick start
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
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
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
Broad build/run/integration overview	quickstart.md
Exact CMake option defaults	reference/build_options.md
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.

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.