Project Structure

This page documents the physical layout of the OpenPhase distribution and of a typical user simulation built against it. The trees below mirror the actual repository; use them as a map when you go looking for sources, headers, examples, or build outputs.

Distribution root

OpenPhase/
├── include/            # Public header files (library API)
├── src/                # Core source implementation
├── external/           # Vendored third-party dependencies
├── mpi_wrapper/        # Thin MPI wrapper library
├── examples/           # Ready-to-run example simulations
├── benchmarks/         # Validation / performance test cases
├── pythonbindings/     # Optional Python interface
├── documentation/      # User Manual sources, figures, PDFs
├── scripts/            # Helper scripts (build, packaging)
├── cmake/              # CMake modules and BuildInfo.h template
├── lib/                # Built library artefacts (populated by build)
├── obj/                # Object files (serial build)
├── objmpi/             # Object files (MPI build)
│
├── CMakeLists.txt      # CMake build definition
├── CMakePresets.json   # Windows / Intel oneAPI presets
├── Makefile            # Top-level GNU Make entry point
├── Makefile.defs       # Shared compiler flags for user Makefiles
├── Doxyfile            # Doxygen configuration
├── OpenPhaseBuildH5.sh # Convenience script for HDF5 builds
├── INSTALL             # Plain-text installation summary
├── README.md           # Project overview
├── AUTHORS             # Contributor list
├── COPYRIGHT           # Copyright notice
├── LICENSE             # GNU GPL v3
└── System-requirements # Platform / dependency summary

Source code — src/

The top level of src/ holds the per-module .cpp files; sub-folders group the larger module families, and mirror the header layout under include/.

src/
├── AdvectionHR.cpp
├── BoundaryConditions.cpp
├── Composition.cpp
├── ConsoleOutput.cpp
├── Crystallography.cpp
├── DoubleObstacle.cpp
├── DrivingForce.cpp
├── ElasticProperties.cpp
├── ElasticitySolverSpectral.cpp
├── ElectricalPotential.cpp
├── EquilibriumPartitionDiffusionBinary.cpp
├── FileInterface.cpp
├── FractureField.cpp
├── Globals.cpp
├── GridParameters.cpp
├── H5Interface.cpp
├── HeatDiffusion.cpp
├── HeatSources.cpp
├── Initializations.cpp
├── InterfaceDiffusion.cpp
├── InterfaceProperties.cpp
├── InterfaceRegularization.cpp
├── MassDensity.cpp
├── MechanicalLoads.cpp
├── MetaData.cpp
├── MovingFrame.cpp
├── Noise.cpp
├── Nucleation.cpp
├── OPObject.cpp
├── Orientations.cpp
├── PhaseField.cpp
├── RunTimeControl.cpp
├── Settings.cpp
├── Stabilization.cpp
├── SymmetryVariants.cpp
├── Temperature.cpp
├── TextOutput.cpp
├── Tools.cpp
├── UserDrivingForce.cpp
├── VTK.cpp
├── Velocities.cpp
│
├── Containers/         # Small container types (EulerAngles, Quaternion, …)
├── Electrics/          # ElectricProperties, ElectricSolverSpectral
├── FluidDynamics/      # FlowSolverLBM, BenziGas, VanDerWaalsGas, interactions
├── GrandPotential/     # Grand-potential solver + phase-density variants
├── InterfaceProperties/# Anisotropy model hooks
├── Magnetism/          # MagneticProperties, LinearMagneticSolver
├── ReactiveFlows/      # FlowMixture, SpeciesTransport, EnergyTransport, …
├── Thermodynamics/     # ThermodynamicPhase, SublatticeModel
└── Tools/              # AnalysisSintering, MicrostructureAnalysis, TimeInfo, …

Header files — include/

include/ mirrors src/ one-to-one. Pairs you will reach for frequently:

Header	Module
Settings.h	Global configuration
RunTimeControl.h	Time-stepping and output cadence
GridParameters.h	Grid size, spacing, interface width
BoundaryConditions.h	Face-level boundary conditions
PhaseField.h	Core phase-field storage + increments
InterfaceProperties.h	Interface energy / mobility models
DoubleObstacle.h	Curvature-driven increment kernel
Temperature.h	Temperature field and control modes
Composition.h	Concentration field storage

Plus sub-folders that match src/: Containers/, Electrics/, FluidDynamics/, GrandPotential/, InterfaceProperties/, Magnetism/, NumericalMethods/, ReactiveFlows/, Thermodynamics/, Tools/.

Examples — examples/

Each example is a self-contained simulation: one .cpp, one .opi, one Makefile, one README. The shipping set covers the main application domains:

examples/
├── AdditiveNiAl/                # Additive manufacturing
├── EutecticII/                  # Eutectic solidification
├── FacetedGG/                   # Faceted grain growth
├── Flow/                        # Single-phase flow
├── Foam/                        # Foam microstructure
├── HeatDiffusion/               # Thermal simulation
├── LatentHeat/                  # Latent-heat release
├── LiquidPhaseSintering/        # Liquid-phase sintering
├── LiquidPhaseSinteringLarge/
├── MeltingFe/                   # Iron melting
├── NormalGG/                    # Normal grain growth (starter example)
├── Pearlite/                    # Pearlite formation
├── Plagioclase/                 # Mineral phase transformation
├── PrecipitationNiTi/           # Precipitation in Ni-Ti
├── ReactiveFlow/                # Combustion / reactive flow
├── SolidPhaseSintering/         # Solid-state sintering
├── SolidificationFe/            # Fe solidification
├── SolidificationFeC/           # Fe-C solidification (binary)
├── SolidificationMgAl/          # Mg-Al solidification
├── SolidificationNiAl/          # Ni-Al solidification
├── Superalloys/                 # Superalloy microstructure
├── ThermalCompressibleFlow/     # Thermally compressible flow
│
├── CMakeLists.txt               # CMake build for all examples
└── Makefile                     # Make build for all examples

A typical example directory looks like NormalGG:

examples/NormalGG/
├── NormalGG.cpp         # Simulation driver
├── ProjectInput.opi     # Simulation parameters
├── Makefile             # Builds against ../../lib/libOpenPhase
└── README               # What the example demonstrates

Benchmarks — benchmarks/

Regression and validation cases. The make test target (CMake build) runs them. Representative entries:

benchmarks/
├── AnisotropyTest/
├── ElasticForceDensityTest/
├── EshelbyTest/
├── GPAdvectionTest/
├── InterfaceDiffusionJunction/
├── InterfaceDiffusionVolumeConservation/
├── LBCapillaryBridge/
├── LBGravity/
├── LinearSystemSolver/
├── MagnetoactiveElastomerLinear/
├── MultiJunction2D/
├── MultiJunction3D/
├── CMakeLists.txt
└── Makefile

Build artefacts

make populates lib/, obj/, and (for MPI builds) objmpi/:

lib/
├── libOpenPhase.so         # Shared library (default)
└── libOpenPhase.a          # Static library (if ENABLE_DYNAMIC_LIBS=OFF)

obj/        # Per-translation-unit object files, serial build
objmpi/     # Per-translation-unit object files, MPI build

cmake --build . instead puts everything under build/<preset>/, with the examples and benchmarks built alongside.

A user simulation

A simulation that uses OpenPhase has the same three-file skeleton as each shipped example:

MyApplication/
├── ProjectInput.opi     # Configuration (required)
├── Main.cpp             # Time-loop program (required)
├── Makefile             # Builds against libOpenPhase (required)
│
├── VTK/                 # Output — .vts / .pvts for ParaView
├── RawData/             # Output — binary restart snapshots
├── TextData/            # Output — CSV statistics
│
└── scripts/             # Optional post-processing (Python, Gnuplot, …)

Output folders are created automatically at runtime if the corresponding paths are declared via $VTKDir, $RAWDir, $InputRAWDir, $DATADir in the @Settings block — see Settings.

ProjectInput.opi anatomy

Every .opi file is divided into sections introduced by a @ heading. Every parameter line follows the same syntax:

$<Keyword>    Free-form human-readable comment            : <value>

Keys are case-sensitive; the : separates the human-readable comment from the value that the module parses. The list of sections and keywords is authoritative in the module pages — this page only summarises the most common.

Section	Module	Purpose
@RunTimeControl	RunTimeControl	Time-step schedule, output cadence, units, restart.
@GridParameters	GridParameters	Nx, Ny, Nz, dx, IWidth, Bcells, MPI decomposition.
@Settings	Settings	Phase list ($Phase_<n>, $State_<n>) and output directories.
@BoundaryConditions	BoundaryConditions	$BC0X … $BCNZ.
@InterfaceProperties	InterfaceProperties	$EnergyModel_<a>_<b>, $Sigma_<a>_<b>, $MobilityModel_<a>_<b>, $Mu_<a>_<b>, anisotropy parameters.
@Composition	Composition	$RefElement_<α>, $C0_<α>_<Comp>, stoichiometric flags.
@Temperature	Temperature	$T0, $ControlMode_<n>, $LatentHeatMode, gradient.
Domain-specific blocks	per module	See the corresponding module page for every $Token.

Illustrative excerpt from examples/NormalGG/ProjectInput.opi:

@RunTimeControl

$SimTtl   Simulation Title                          : Normal grain growth
$nSteps   Number of Time Steps                      : 2000
$FTime    Output to disk every (tSteps)             : 100
$STime    Output to screen every (tSteps)           : 100
$dt       Initial Time Step                         : 1e-5
$nOMP     Number of OpenMP Threads                  : 1

@GridParameters

$Nx       System Size in X Direction                : 101
$Ny       System Size in Y Direction                : 101
$Nz       System Size in Z Direction                : 1
$dx       Grid Spacing                              : 1e-6
$IWidth   Interface Width (in grid points)          : 5.0

@Settings

$Phase_0  Name of Phase 0                           : Phase1

@InterfaceProperties

$EnergyModel_0_0    Interface energy model          : ISO
$Sigma_0_0          Interface energy                : 0.24
$MobilityModel_0_0  Interface mobility model        : ISO
$Mu_0_0             Interface mobility              : 1.0e-7

Note: the @ block names and the $ keys inside them must be spelled exactly as the module expects. The authoritative reference is the src/<Module>.cpp ReadInput implementation; the Modules pages transcribe those keys faithfully.