Nucleation
Nucleus Representation
Each nucleus is represented explicitly as a data object containing:
- phase and parent phase identifiers,
- spatial position and orientation,
- effective radius,
- symmetry variant,
- timestamp of creation,
- local driving force measures.
This information is retained for:
- statistical analysis,
- restart capability,
- post-processing,
- debugging and method development.
Spatial Control of Nucleation
The nucleation module offers fine-grained spatial filtering.
Nuclei can be restricted to:
- bulk regions,
- grain boundaries,
- phase boundaries,
- triple or higher-order junctions,
- simulation domain boundaries.
This allows physically motivated studies such as:
- heterogeneous nucleation at interfaces,
- boundary-dominated transformations,
- surface-driven phase changes.
Size, Orientation, and Variants
Seed Size
The initial seed size is given as a diameter and can be assigned using:
- a fixed diameter,
- normal (Gaussian),
- Cauchy,
- uniform distributions,
- or derived implicitly from the interface width.
Internally the nucleus keeps its effective radius (half of the diameter).
This enables controlled sensitivity studies of curvature effects.
Orientation
Orientation assignment supports:
- inheritance from the parent grain,
- random orientations,
- fixed reference orientations.
The orientation logic is independent of crystallographic symmetry handling.
Variants
For transformations with multiple symmetry-related variants, the nucleation module can:
- randomly select variants,
- or choose the variant with the highest local driving force.
This makes the framework suitable for martensitic and symmetry-breaking transformations.
Shielding and Numerical Stability
To avoid numerical artifacts such as:
- overlapping nuclei,
- excessive curvature,
- unstable early growth,
the module enforces a shielding radius (in grid cells) between nucleation sites. The distance is wrapped across periodic boundaries only.
Additionally, a newly planted seed is kept only if its driving force exceeds the curvature pressure of the seed, with interface energy IWidth·dx, also in dual resolution) to overcome the numerical nucleation barrier of the diffuse interface. Otherwise the seed is removed and planted again at a later attempt.
Time Control
Nucleation attempts are performed at a configurable interval (NucleateEvery).
This allows:
- quasi-instantaneous nucleation,
- continuous nucleation over time,
- or sparse, event-driven nucleation scenarios.
Data Persistence and Restart
The nucleation state can be:
- written to binary raw data files or HDF5,
- restored during restarts, including the random generator states, so a restarted run continues exactly like an uninterrupted one,
- shifted or remeshed consistently with the simulation grid.
Seed positions, orientations, diameters and variant choices are drawn from the random engines by OpenPhase's own mapping and distributions, so the same RandomNumberSeed gives the same values with every compiler and C++ standard library (diameters up to the last bit of the system math functions), and 1D and 2D seed positions are projections of the 3D ones.
Checkpoints store the random seed in use and the number of values drawn from each random engine. A restart seeds the engines again and skips the drawn values, which restores their states exactly with every C++ standard library, so checkpoints can be restarted on any platform. The stored seed takes precedence over RandomNumberSeed in the input of the restarted run.
This makes nucleation fully compatible with:
- long-running simulations,
- checkpoint/restart workflows,
- adaptive domain modifications.
Extending the Nucleation Framework
The nucleation module is designed to be extensible.
Typical customization paths include:
- implementing new location filters,
- adding alternative size or orientation distributions,
- introducing custom variant selection logic,
- coupling nucleation probability to additional field variables.
All core logic is separated from numerical solvers, making it suitable for method development and experimentation.
Summary
The OpenPhase nucleation module provides:
- stochastic but reproducible nucleation,
- strong separation between nucleation and growth,
- flexible spatial and statistical control,
- full compatibility with restart and parallel workflows.
It is intended as a research-grade framework rather than a fixed physical model, enabling users to explore and implement nucleation concepts tailored to their specific scientific questions.
Usage
Input
Configuration lives in the @Nucleation block. Three global controls govern the attempt schedule; everything else is set per phase pair _<n>_<m>, meaning nucleation of phase n in the matrix phase m (for example _1_0 nucleates phase 1 in phase 0).
@Nucleation
$RandomNumberSeed Seed of the random generators : 1
$NucleateEvery Attempt nucleation every N steps : 100
$NumberOfAttempts Attempts to place each seed : 100
$Allowed_1_0 Allow nucleation of phase 1 in phase 0 : Yes
$SeedGenerationMode_1_0 : Static
$SeedLocationMode_1_0 Where phase 1 seeds may form in phase 0 : Bulk
$SeedInputMode_1_0 : SeedDensity
$SeedDensity_1_0 Seeds per volume of phase 0 (in 1/m^3) : 1.0e12
$DensityIsRelative_1_0 : Yes
$SeedActivationTmin_1_0 Needs domain max temperature >= this : 1000
$SeedActivationTmax_1_0 Needs domain min temperature <= this : 1500
$SeedShieldingRadius_1_0 Minimum seed distance (in grid cells) : 5
$SeedDiameterDistribution_1_0 : Normal
$SeedDiameterMean_1_0 Normal distribution mean (in m) : 1.0e-7
$SeedDiameterStandardDeviation_1_0 Normal distribution sigma (in m) : 2.0e-8
$SeedOrientationMode_1_0 : Random
$VariantsPerSeed_1_0 : 1
$SeedVariantsMode_1_0 : RandomKey (_<n>_<m>) | Values | Default and notes |
|---|---|---|
Allowed | Yes / No | No |
SeedGenerationMode | Static, Continuous | Static. Dynamic is not implemented yet. |
SeedLocationMode | Bulk, BulkAndGrainBoundaries, BulkAndInterfaces, GrainBoundaries (GB), PhaseBoundaries, Interfaces, Junctions, XBottom, XTop, YBottom, YTop, ZBottom, ZTop | Bulk. Seeds are placed only where the condition holds. Waiting seeds whose position no longer fulfills it (e.g. covered by a growing grain) are removed and replaced by new ones. |
SeedInputMode | SeedCount, SeedDensity | SeedDensity. Any other value stops the run. |
SeedCount | integer | Required for SeedCount: total number of requested seeds. |
SeedDensity | 1/m³ | Required for SeedDensity. |
DensityIsRelative | Yes / No | Yes: density per volume of phase m; No: per total volume. |
SeedActivationTmin, SeedActivationTmax | K | Required. Nucleation is active while the domain temperature range overlaps [SeedActivationTmin, SeedActivationTmax]; the temperature at the seed position is not checked. |
SeedShieldingRadius | grid cells | 5 |
SeedDiameterDistribution | None, FixedDiameter (FixedSize), Normal, Cauchy, Uniform | None: seed diameter equals the interface width. Read for solid phases only. |
SeedDiameterMean, SeedDiameterStandardDeviation | m | Normal. Draws outside mean ± 3σ (or below 0) are rejected; the mean may be negative to use the upper tail only. |
SeedDiameterMedian, SeedDiameterHalfWidth | m | Cauchy. Draws outside median ± 10 half widths (or below 0) are rejected. |
SeedDiameterMIN, SeedDiameterMAX | m | Uniform. |
SeedDiameter | m | FixedDiameter. Must be positive. |
SeedOrientationMode | Random, Parent, Reference | Required for solid phases. |
VariantsPerSeed | 1 … number of variants of phase n | 1. Read only if phase n has several variants. |
SeedVariantsMode | Random, LowestEnergy | Random. LowestEnergy keeps the variants with the highest driving force. |
The example uses SeedDensity and the Normal distribution. For the other modes, replace those keys with the ones listed in the table, e.g. SeedCount for SeedInputMode SeedCount. OpenPhase reads every $Key in the block, even after a #, so delete unused keys instead of commenting them out.
RandomNumberSeed of 0 or more gives reproducible runs, a negative value uses a time-based seed (shared by all MPI ranks).
Older key names (Location_, Density_, Nsites_, RelativeDensity_, RelDensity_, Distribution_, Center_, Deviation_, HalfWidth_, Orientation_, OrientationMode_, Tmin_, Tmax_, GenerationMode_, VariantsMode_, Variants_, ShieldingRadius_) are still read but print a deprecation warning. SeedRadius_, SeedRadiusMIN_, SeedRadiusMAX_, IMode_ and the FixedRadius distribution are no longer accepted. TrueRadius_ is no longer read: the seed reference volume always follows the interface width, and the drawn seed diameter only sets the survival threshold.
Output
Nucleus records — phase / parent identity, position, orientation, radius, creation time — are written to binary raw data files or HDF5 and reloaded during a restart, as described above. Planted nuclei are also listed in TextData/NucleationStatistics.csv (comma-separated, full precision).
Example
#include "Nucleation.h"
#include "Initializations.h"
Nucleation Nuc(OPSettings, InputFile);
for(RTC.tStep = RTC.tStart; RTC.tStep <= RTC.nSteps; RTC.IncrementTimeStep())
{
if (RTC.tStep % Nuc.NucleateEvery == 0)
{
Nuc.GenerateNucleationSites(Phi, Tx, BC, OPSettings);
Nuc.PlantNuclei(Phi, RTC.tStep);
}
// ... interface properties, phase-field increments, driving force ...
dG.Average(Phi, BC);
// Removes planted seeds whose driving force is too small to grow
Nuc.CheckNuclei(Phi, IP, dG, RTC.tStep);
// ... merge increments and the rest of the phase-field update ...
}GenerateNucleationSites takes the boundary conditions to know which directions are periodic; it does not set them. It also takes the settings, whose grid history maps already planted seeds to the current grid after remeshing, so the shielding distance stays correct.
See also: examples
In OpenPhase-main/examples/:
SolidificationFeC,SolidificationNiAl,SolidificationFe,PeritecticFeC— solidification examples that activate nucleation in the undercooled liquid.Martensite_C01…Martensite_C03,MartensiteTempering— martensite nucleation with symmetry variants.PrecipitationNiTi,TZP— nucleation of precipitates and transformation products in solids.
Dependencies
- PhaseField — target of planted seeds.
- Temperature —
$SeedActivationTmin/$SeedActivationTmaxgating. - InterfaceProperties — interface energy sets the minimum driving force a seed needs to survive.
- DrivingForce — checked by
CheckNuclei. - BoundaryConditions — periodicity used by the shielding distance.
- SymmetryVariants — variant rotation matrices.
- Orientations — stores the assigned orientation of each new grain.