Tour of main types

This page maps the primary OpenPFC concepts to their responsibilities, headers, and runnable examples. It is a lookup-oriented bridge between tutorials and the generated API reference, not an exhaustive inventory of implementation types.

For dependency rules, read architecture.md. For configuration-driven application wiring, read app_pipeline.md.

Core spectral workflow

        flowchart LR
  Domain --> Decomposition --> FFT
  FFT --> Model --> Simulator
  Time --> Simulator
  FieldModifier --> Simulator
  Simulator --> ResultsWriter
  Configuration --> App --> SpectralSimulationSession --> Simulator
    

The shortest useful mental model is:

1. Domain describes the global grid.

2. Decomposition partitions it across MPI ranks.

3. an FFT implementation transforms local field data;

4. Model defines the physics update;

5. Simulator coordinates time, modifiers, model steps, and writers;

6. App and SpectralSimulationSession build that stack from configuration.

Stable concepts at a glance

Type or concept	Responsibility	Primary header	Start with
Domain	Global grid size, spacing, origin, and periodicity	openpfc/kernel/data/domain.hpp	examples/02_domain_decomposition.cpp
Box3i	Inclusive integer bounds for local or transformed regions	openpfc/kernel/data/box.hpp	examples/02_domain_decomposition.cpp
Decomposition	MPI partition and per-rank inbox/outbox geometry	openpfc/kernel/decomposition/decomposition.hpp	examples/03_parallel_fft.cpp
IFFT / CpuFft	Distributed forward/backward transforms through HeFFTe	openpfc/kernel/fft/fft.hpp	examples/03_parallel_fft.cpp
Model	Physics fields, initialization, and time-step update	openpfc/kernel/simulation/model.hpp	examples/04_diffusion_model.cpp
Time	Start, stop, step size, current time, and save cadence	openpfc/kernel/simulation/time.hpp	examples/time.cpp
Simulator	Coordinates modifiers, model steps, time, and result output	openpfc/kernel/simulation/simulator.hpp	examples/05_simulator.cpp
FieldModifier	Initial conditions and boundary-condition-style updates	openpfc/kernel/simulation/field_modifier.hpp	examples/10_ui_register_ic.cpp
ResultsWriter	Stable interface for persisted simulation fields	openpfc/kernel/simulation/results_writer.hpp	examples/11_write_results.cpp
pfc::ui::App<Model>	Loads JSON/TOML and runs a configured application	openpfc/frontend/ui/app.hpp	apps/ and tutorials/custom_app_minimal.md
SpectralCpuStack	Owns the CPU domain, decomposition, FFT, fields, and time stack	openpfc/frontend/ui/spectral_cpu_stack.hpp	user_guide/app_pipeline.md
SpectralSimulationSession	Owns model and simulator state around a spectral stack	openpfc/frontend/ui/spectral_simulation_session.hpp	user_guide/app_pipeline.md

Use the integrated C++ API reference for exact constructors, overloads, namespaces, and member documentation.

Data and execution

OpenPFC separates logical fields from execution and memory backends.

Concept	Role	Location
Field / local field containers	Associate local values with domain and decomposition information	kernel/data, kernel/field
DataBuffer	Own host or device storage selected by backend type	kernel/execution, GPU specializations under runtime/
execution spaces	Select serial, OpenMP, CUDA, or HIP execution	kernel/execution, runtime/cuda, runtime/hip
memory spaces	Express host versus device residency	kernel/execution, runtime/cuda, runtime/hip
views and parallel_for	Backend-oriented access and iteration	kernel/execution and runtime specializations
deep_copy and mirrors	Move or expose data across memory spaces	kernel/execution and runtime specializations

GPU execution requires a matching CUDA or HIP build and the corresponding runtime headers. Build decisions are documented in ../hpc/gpu_path_decision.md.

Finite-difference types

Finite-difference applications choose a field/halo layout according to whether the data must also remain FFT-compatible.

Concept	Use
in-place halo exchange	Compact FD-only arrays whose boundary slabs may hold ghosts
separated halo exchange	FFT-safe core arrays with separate face buffers
PaddedBrick<T>	Owned cells plus a contiguous ghost ring for direct stencil indexing
sparse halo exchange	Explicit remote-index lists and structured separated halos
FD gradients and stencils	Per-cell differential operators and reusable coefficients

Start with examples/15_finite_difference_heat.cpp and ../concepts/halo_exchange.md.

Configuration and extension catalogs

The frontend maps configuration names to concrete behavior through catalogs and wiring helpers.

Concept	Responsibility
parameter metadata and validation	Check required keys, types, bounds, units, and typical values
field-modifier catalog	Map configuration names to initial/boundary modifier factories
results-writer catalog	Map fields[].writer names to writer factories
JSON wiring context/session	Hold the objects required to connect configuration to a simulator
spectral stack factory	Merge backend and HeFFTe plan options into a concrete FFT stack

These are extension mechanisms rather than first-day concepts. Follow ../tutorials/custom_app_minimal.md and ../extending_openpfc/README.md before using them directly.

Advanced subsystems

OpenPFC also contains stable subsystem contracts that are best learned from their focused documentation rather than from one expanding type table.

Subsystem	Read
time integration and adaptive stepping	simulation stepper headers and generated API reference
solver contracts and spectral diagonal solves	solver headers under kernel/simulation and unit tests
checkpoint state and atomic publication	docs/development/checkpoint_state_capture.md and checkpoint_publish.md
profiling sessions and export	../hpc/performance_profiling.md
profiling file schema	../hpc/profiling_export_schema.md
result formats	../user_guide/io_results.md
binary field layout	binary_field_io_spec.md

Application-private workspaces and temporary migration adapters are intentionally excluded from this page. They remain discoverable through their application headers, tests, and generated API documentation without becoming part of the core learning path.

Find a runnable example

Goal	Example or guide
inspect domain decomposition	02_domain_decomposition
perform a distributed FFT	03_parallel_fft
implement a small spectral model	04_diffusion_model
understand simulator orchestration	05_simulator
register a custom initial condition	10_ui_register_ic
write result files	11_write_results
inspect a Cahn-Hilliard workflow	12_cahn_hilliard
add a custom field initializer	14_custom_field_initializer
run finite differences with halos	15_finite_difference_heat
add a coordinate system	17_custom_coordinate_system

The complete catalog and suggested curriculum are in examples_catalog.md.

See also

• ../learning_paths.md — role-based reading order

• ../concepts/spectral_stack.md — spectral data flow

• ../user_guide/app_pipeline.md — configuration to Simulator

• api_examples_walkthrough.md — curated API examples

• ../getting_started/01-basics/README.md — out-of-tree consumer tutorial

• ../extending_openpfc/README.md — extension checklist