Applications (apps/)

Full programs built when OpenPFC_BUILD_APPS=ON (default). They install under <prefix>/bin with cmake --install. Unlike examples/, each app here is meant as a model-specific executable with realistic usage (MPI, FD or spectral stacks, optional GPU).

User-facing overview and example commands: docs/user_guide/applications.md.

CMake wires subdirectories from apps/CMakeLists.txt in this order: tungsten, aluminumNew, cahn_hilliard, thin_film, surface_diffusion, kawahara, ehd_film, gradient_elasticity, higher_order_pfc, inverse_homogenization, incompressible_flow, polycrystal_shear, allen_cahn, alloy_dendrite_elastic, heat3d, wave2d, kobayashi, vlasov_maxwell, burgers.

For the nine JSON-session apps, ./scripts/openpfc apps lists presets and supported backends. Create a case with openpfc init CASE --app=NAME; see the CLI guide. Teaching drivers with positional arguments retain their app-specific commands.

What belongs here

examples/ are teaching examples, API demonstrations, verification prototypes, or deliberately bounded experiments. apps/ are maintained model executables with realistic usage. There is no fixed application count. A new directory is admitted when it has a clear reason to exist and meets the criteria below. An arbitrary count is not a reason to leave a worthwhile subject under examples/.

A new apps/<name> entry should satisfy most of the following:

  1. Distinct subject or workflow. It is a meaningful physical, mathematical, inverse, or computational application, not a renamed variant of an existing app. A new flag or extra binary on an existing model stays in that app.

  2. Reusable-platform consumer. Generic machinery the app discovers is promoted to the installed OpenPFC layer that owns it. The app includes its own headers and public OpenPFC headers. It does not depend on another application directory, and it does not recreate a shared apps/common (issue #65).

  3. Verification. It has quantitative correctness tests, or a bounded validation protocol appropriate to its model.

  4. Realistic execution path. It exercises OpenPFC as a usable application, not only as a tiny tutorial.

  5. Maintainable ownership. Model-specific physics, material data, cases, and interpretation stay in the app.

  6. Documentation. Equations, assumptions, supported backends, commands, and limitations are stated.

  7. No paper-count logic. An app does not need novelty or a publication story merely to justify useful engineering.

Generic numerics, runtime services, solvers, diagnostics, and I/O belong in installed OpenPFC modules. They are not hidden inside an app.

Catalog

Directory

Role

Config

Typical stack

tungsten/

Production-style 3D phase-field crystal (tungsten); JSON/TOML, validated params, field I/O

JSON / TOML (inputs_json/, inputs_toml/)

SpectralETDSession<TungstenPhysics, …>, spectral / HeFFTe, CPU + optional CUDA/HIP

aluminumNew/

Compact aluminum PFC sample (seed_grid_fcc)

JSON / TOML

SpectralETDSession<AluminumPhysics, …>, moving-frame mean-field ETD

cahn_hilliard/

Fe–Cr-like Cahn–Hilliard spinodal (\(k^4\) spectral ETD); optional coherent Vegard Green-operator coupling (cahn_hilliard_elastic, and cahn_hilliard_elastic_hip on the device solver)

JSON (inputs_json/)

SpectralETDSession<CahnHilliardPhysics, …>; CPU + optional HIP; elastic binaries reuse microelasticity.hpp

thin_film/

Lubrication dewetting / coating (\(k^4\) capillary + disjoining)

JSON (inputs_json/)

SpectralETDSession<ThinFilmPhysics, …>; CPU + optional HIP

surface_diffusion/

Mullins surface diffusion (exact \(k^4\) annealing)

JSON (inputs_json/)

SpectralETDSession<SurfaceDiffusionPhysics, …>; CPU + optional HIP

kawahara/

Kawahara capillary–gravity waves (odd-order \(ik^3\)/\(ik^5\))

JSON (inputs_json/)

SpectralETDSession<KawaharaPhysics, …>; CPU + optional HIP

ehd_film/

EHD film under a flexible plate (\(k^6\) bending lubrication)

JSON (inputs_json/)

SpectralETDSession<EhdFilmPhysics, …>; CPU + optional HIP

gradient_elasticity/

Strain-gradient elasticity (Helmholtz–Navier, 4th/6th order)

JSON (inputs_json/)

one-shot spectral \(2\times 2\) invert (not ETD); CPU + optional HIP

higher_order_pfc/

Eighth-order PFC correlation kernel (two-mode; \(k^8\) free energy, \(k^{10}\) conserved dynamics)

JSON (inputs_json/)

SpectralETDSession<HigherOrderPFCPhysics, …>; CPU + optional HIP

inverse_homogenization/

Periodic inverse homogenization (target \(C_H\); issue #161). PDE-constrained inverse design of a periodic microstructure, not another forward PDE demo. Forward \(C_H\), adjoint, Allen–Cahn inverse loop, CH process family, manufacturability, and 3-D cells are in tree.

CLI (--key=value)

Reuses openpfc/solvers/microelasticity/microelasticity.hpp (six imposed-strain FFT solves); CPU + optional HIP Green

allen_cahn/

2D Allen–Cahn demo; quick visual check

CLI only (no App JSON)

FD, separated halos, optional PNG; CPU + optional CUDA/HIP

alloy_dendrite_elastic/

Thermo-solutal-elastic alloy solidification (quantitative dilute-alloy phase field + anti-trapping + latent heat + eigenstrain microelasticity; FTA directional / bicrystal flags on the same binary)

CLI only (--key=value); CSV diagnostics

FD orders 2–14 via FDGradient, padded HaloExchange, spectral elastic solve on the same decomposition; CPU (+ optional HIP FD twin)

heat3d/

3D heat equation \(\partial_t u = D\Delta u\); five drivers from scratch → spectral implicit

CLI per binary

FD (orders 2–20), spectral pointwise RHS, spectral implicit Euler; OpenMP where enabled

wave2d/

2D acoustic wave as coupled first-order system; mixed periodic / physical y boundaries

CLI (+ optional --vtk on all variants)

FD (manual 2nd order or orders 2–20); CPU + optional CUDA/HIP

kobayashi/

Kobayashi dendritic phase field + temperature (periodic x,y); Julia kobayashi_v1-style FD

CLI; PNG snapshots of \(\phi\)

kobayashi_fd_manual (MPI halos); kobayashi_fd_openmp (torus wrap + OpenMP); CPU

vlasov_maxwell/

1D2V electromagnetic Vlasov–Maxwell (kinetic distribution on a 3-D phase-space grid, self-consistent Maxwell)

CLI only (--key=value); CSV diagnostics

Strang split: exact spectral \(x\)-shift, semi-Lagrangian velocity, exact ETD light wave; CPU + optional HIP

burgers/

Periodic viscous Burgers on one sine wave, compared across dealiased Fourier, conservative FD2 and monotone finite volume

CLI (--method, --N, --nu, --dt, --time)

SSP-RK3; ComplexLineFFT and fd::evaluate<2>; single-rank CPU

incompressible_flow/

Periodic 3-D incompressible Navier–Stokes. Taylor–Green, decaying homogeneous isotropic turbulence, and constant-power low-mode forcing on the same Fourier velocity. The 2-D vorticity–streamfunction prototype stays under examples/ns2d_vorticity/.

CLI (--case taylor-green, --case decaying-hit, --case forced-hit)

Installed Leray step, spectral / HeFFTe, CPU, distributed pencil

polycrystal_shear/

Periodic FCC polycrystal in finite-strain simple shear. The mid-plane scalar is the Frobenius norm of the deviator of the symmetric Piola stress.

CLI

Newton–GMRES, aluminum slip law, HeFFTe, CPU, MPI

Shared JSON vocabulary for spectral apps is summarized near the repo root in schema.json (see docs for normative references).

wave2d — coupled fields (reference for similar apps)

If you are adding another multi-field FD app (several prognostic variables updated together each step), wave2d is the smallest shipped example that does this cleanly.

Equations: the second-order wave equation \(u_{tt} = c^2 \Delta u\) is written as

\[ \partial_t u = v, \qquad \partial_t v = c^2 \Delta u \]

on an nz = 1 slab, periodic in \(x\) (MPI halos), with homogeneous Dirichlet or Neumann conditions on \(y\) (ghost correction after the periodic exchange).

Code layout (high level):

Piece

Location

Notes

Physics only (per-point RHS, \(c\), metric scaling)

wave2d/include/wave2d/wave_model.hpp

WaveLaplacian, WaveIncrements, WaveModel::rhs — same idea as heat3d’s HeatModel + grads struct, but for \((u,v)\) increments

Binaries

wave2d/CMakeLists.txt

wave2d_fd_manual, wave2d_fd; optional wave2d_cuda, wave2d_hip

BC / Laplacian wiring

wave_boundary.hpp, wave_step_separated.hpp, device_step.hpp, drivers under src/cpu/, src/cuda/, src/hip/

Mixed boundaries + VTK hooks

Binaries: wave2d_fd_manual (fixed second-order stencil), wave2d_fd (even orders 2–20), plus GPU twins when CUDA/HIP are enabled. Optional ParaView output: --vtk / --vtk-every.

Tests: ctest -R wave2d when tests are enabled (test_wave2d, and CPU–GPU parity tests if built).

For extending the framework in general: docs/extending_openpfc/README.md, docs/tutorials/custom_app_minimal.md, docs/user_guide/app_pipeline.md.