PhaseField Class Reference

Guide: for the phase-field theory and time-loop patterns, see phase-field.md.

The PhaseField class stores and manipulates phase fields. It provides storages for the phase field variables, their derivatives and increments. It also stores physical properties of each individual phase-field assuming that each phase-field variable stands for an individual grain. For convenience the PhaseField class also stores thermodynamic phase fractions which are updated together with the phase fields.

The externally accessible 3D data storages in the PhaseField class are:

// Phase-field storage:
Storage3D< NodePF, 0 > Fields;
// Phase-field increments storage:
Storage3D< NodeAB<double,double>, 0 > FieldsDot;
// Phase-field storage for double resolution mode:
Storage3D< NodePF, 0 > FieldsDR; 
// Phase-field increments storage for double resolution mode:
Storage3D< NodeAB<double,double>, 0 > FieldsDotDR; 
// Phase-field storage for advection increments:
Storage3D< NodeA<double>,  0 > FieldsAdvectionDot; 
// Phase-field backup storage for advection:
Storage3D< NodePF, 0 > FieldsAdvectionBackup; 
// Thermodynamic phase fractions storage:
Storage3D< double, 1 > Fractions;

The storage implementation uses the Storage3D class to provide three-dimensional indexing of dynamically allocated arrays with a number of other access and manipulation methods. The data at a grid point level is stored in the so-called node-type storages. These are dynamic storages designed to hold only the locally existing entities, e.g. phase fields, their derivatives and increments, where only non-zero values are stored allowing to consider virtually unlimited number of phase-fields. The NodePF container holds phase fields and their first and second order derivatives in a compact structure. The NodeAB is designed to store two values attributed to two simultaneous phase field indices. Here it is used to store phase-field increments for a pair of phase fields according to the multi-phase-field method philosophy, where all phase-field changes are evaluated for a pair of phase fields, hence a two-index storage. The NodeA container stores single-indexed values and is used to store individual phase fields' advection increments if advection methods are used.

The methods typically called on the level of the executable program in the PhaseField class can be split into several categories:

Module setup methods

void Initialize(Settings& locSettings, std::string ObjectNameSuffix = "");

The method which allocates internal storages and sets default values to internal parameters.

void ReadInput(const std::string InputFileName);

The method, which reads class preferences from the input file.

void ReadInput(std::stringstream& inp);

The method, which reads class preferences from the input stream.

void ReadJSON(const std::string InputFileName);

The method, which reads class preferences from the JSON file.

The ASCII input of the PhaseField module starts with the corresponding section name

@PhaseField

and contains the following entries:

$ApplyConstraints
$ConsiderNucleusVolume
$NucleusVolumeFactor
$InterfaceNormalModel
$PhaseFieldLaplacianStencil
$PhaseFieldGradientStencil

The boolean ApplyConstraints parameter controls if the phase-field sum constraint

$$\begin{array}{}\text{(1)}& \sum _{\alpha }{\varphi }_{\alpha }^t=0\end{array}$$

and the phase-field value bounds $(0,1]$ are enforced at every time step $t$. If the ApplyConstraints parameter is set to true (default setting) the constraints are enforced, otherwise the constraints are ignored.

The boolean ConsiderNucleusVolume parameter enables the use of the nuclei volume relative to the critical nucleus volume to evaluate the local number of phase fields. The nuclei contribution to the local number of phase fields is counted with the factor $0\le v_{nuc}/v_{crit}\le 1$, where $v_{nuc}$ is the actual nucleus volume and $v_{crit}$ is the critical nucleus volume defined by the interface width for 1D, 2D and 3D simulations:

$$\begin{gathered} \begin{array}{}\text{(2)}& v_{crit}^{1\text{D}}=f_v\eta , \\ {v}_{crit}^{2\text{D}}=f_v\pi {\eta }^2, \\ {v}_{crit}^{3\text{D}}=f_v\frac{4}{3}\pi {\eta }^3,\end{array} \end{gathered}$$

where $\eta$ is the interface width and $f_v$ is the NucleusVolumeFactor, which controls the critical nucleus volume calculation (default value 1.0). The default value assumes that every nucleus transits from the nucleus state with reduced curvature consideration to the normal grain state with the full curvature consideration when its radius equals to the critical nucleus radius which is set to the interface width $\eta$. In some cases such choice may lead to excessively large nuclei resulting in simulation artefacts due to nuclei interaction in simulations with high nucleation density. In such cases $f_v<1.0$ can be used.

The InterfaceNormalModel parameter controls how the interface normals are evaluated in the simulation. There are two models to choose from:

• AverageGradient (default setting)
• WeightedGradient

The AverageGradient model uses the following equation to set the local interface normal, $\text{bold}{n}_{\alpha \beta }$, between the phase fields ${\varphi }_{\alpha }$ and ${\varphi }_{\beta }$:

$$\begin{array}{}\text{(3)}& \text{bold}{n}_{\alpha \beta }=\frac{\mathrm{\nabla }{\varphi }_{\beta }-\mathrm{\nabla }{\varphi }_{\alpha }}{||\mathrm{\nabla }{\varphi }_{\beta }-\mathrm{\nabla }{\varphi }_{\alpha }||},\end{array}$$

while the WeightedGradient uses the equation of the form

$$\begin{array}{}\text{(4)}& \text{bold}{n}_{\alpha \beta }=\frac{{\varphi }_{\alpha }\mathrm{\nabla }{\varphi }_{\beta }-{\varphi }_{\beta }\mathrm{\nabla }{\varphi }_{\alpha }}{||{\varphi }_{\alpha }\mathrm{\nabla }{\varphi }_{\beta }-{\varphi }_{\beta }\mathrm{\nabla }{\varphi }_{\alpha }||}.\end{array}$$

The equations above ensure that the interface normal vector, $\text{bold}{n}_{\alpha \beta }$, points outward from the region occupied by the phase field ${\varphi }_{\alpha }$ into the region occupied by the phase field ${\varphi }_{\beta }$. The major difference between the two models is their behavior in the triple and higher order junctions, where the weighted gradient approach produces smoothly varying normal vectors within the high order junctions but may run into accuracy limitations if both ${\varphi }_{\alpha }$ and ${\varphi }_{\beta }$ are very small. In the pairwise interfaces there is no difference in the result of the two models, though.

The PhaseFieldLaplacianStencil parameter sets the Laplacian stencil used in the the phase field equation. The available Laplacian models are

• Simple
• Isotropic (default setting)
• LB

The Simple model uses 3-point stencil in 1D, 5-point stencil in 2D and 7-point stencil in 3D to evaluate the Laplacian used in the phase-field equation calculation.

The Isotropic model uses 3-point stencil in 1D, 9-point isotropic stencil in 2D and 27-point stencil in 3D to evaluate the Laplacian.

The LB model uses the 3-point stencil in 1D, isotropic Laplacian stencils derived from the D2Q9 lattice Boltzmann stencil in 2D and D3Q27 stencil in 3D.

The PhaseFieldGradientStencil parameter sets the stencil for the evaluation of the phase-field gradients (default: "Isotropic"). The available gradient stencil choices are

• Simple
• Isotropic (default setting)
• LB

The Simple model uses 2-point nearest neighbour stencils for each gradient component in 1D, 2D and 3D cases.

The Isotropic model uses 2-point nearest neighbour stencil in 1D, 8-point isotropic stencil for each gradient component in 2D and 26-point stencil for each gradient component in 3D.

The LB model uses the 2-point stencil in 1D, isotropic 8-point stencil derived from the D2Q9 lattice Boltzmann stencil for each gradient component in 2D, and 26-point stencil derived from the D3Q27 lattice Boltzmann stencil for each gradient component in 3D.

Phase field manipulation methods

void NormalizeIncrements(const BoundaryConditions& BC, const double dt);

The NormalizeIncrements methods normalizes the pairwise phase-field increments ${\dot{\varphi }}_{\alpha \beta }$ such, that the resulting phase fields at the next time step, ${\varphi }_{\alpha }^{t+1}$ after subsequent call to MergeIncrements method are withing $(0,1]$ bounds and satisfy the sum constraint:

$$\begin{array}{}\text{(5)}& \sum _{\alpha }{\varphi }_{\alpha }^{t+1}=0,\end{array}$$

where

$$\begin{array}{}\text{(6)}& {\varphi }_{\alpha }^{t+1}={\varphi }_{\alpha }^t+\sum _{\beta \ne \alpha }{\dot{\varphi }}_{\alpha \beta }\ast \mathrm{\Delta }t.\end{array}$$

void MergeIncrements(const BoundaryConditions& BC,
                     const double dt,
                     const bool finalize = true,
                     const bool clear = true);

The MergeIncrements method merges the calculated phase-field increments, ${\dot{\varphi }}_{\alpha \beta }$, in the current time step into the phase fields, ${\varphi }_{\alpha }^t$, from the previous time step according to the equation above. It also evaluates derivatives of the new phase fields, ${\varphi }_{\alpha }^{t+1}$, sets interface flags, sets boundary conditions and updates local phase fractions. After this method is called the phase-field increments ${\dot{\varphi }}_{\alpha \beta }$ are erased.

Run time statistics output methods

// Print volume of all phase fields:
void PrintPFVolumes() const;
// Print the locally present phase fields and their values to the screen:
void PrintPointStatistics(const int x, const int y, const int z) const;
// Print volume fraction of all thermodynamic phases
void PrintVolumeFractions(void);
// Write volume fraction of all thermodynamic phases to the file <FileName>
void WriteVolumePercentages(const std::string& filename, double time,
                            char separator = ',') const;

void WriteGrainsVolume(int time_step, double time, std::string filename);   ///< Writes grains' volume in grid cells over time into a file
void WriteAverageVolume(const int tStep, const size_t PhaseIndex) const;    ///< Writes to the file the average volume of a given phase

Raw (binary) data input and output

bool Read(std::string FileName);

The method, which reads raw (binary) phase fields from the file named FileName. It requires call to FinalizeInitialization(const BoundaryConditions& BC) to calculate derivatives, set interface flags and boundary conditions.

bool Read(const Settings& locSettings,
         const BoundaryConditions& BC, 
         const int tStep) override;

The method, which reads raw (binary) phase fields from the file of specific time step tStep. The methods also evaluates phase-field derivatives, sets interface flags, sets boundary conditions and makes the PhaseField class ready for simulation.

bool ReadH5(const BoundaryConditions& BC, H5Interface& H5, const int tStep);

The method, which reads phase fields from the HDF5 file of specific time step tStep. The methods also evaluates phase-field derivatives, sets interface flags, sets boundary conditions and makes the PhaseField class ready for simulation.

bool Write(const std::string& FileName) const;

The method, which writes raw (binary) phase fields to the file FileName.

bool Write(const Settings& locSettings, const int tStep) const override;

The method, which writes raw (binary) phase fields to the file PhaseField_<tStep>.dat for the time step tStep.

void WriteH5(H5Interface& H5, const int tStep);

The method, which writes phase fields to the file in HDF5 format for the time step tStep.

Visualization data output

void WriteVTK(Settings& locSettings,
             const int tStep,
             const bool CurvatureOutput = false,
             const int precision = 16) const;

The method, which writes phase fields for visualization into the file in VTS format for the given time step tStep.

void WriteDistortedVTK(Settings& locSettings,
                       const ElasticProperties& EP,
                       const int tStep,
                       const bool CurvatureOutput = false,
                       const int precision = 16) const;

The method, which writes phase fields for visualization considering the domain distortion into the file in VTS format for the given time step tStep.