diff --git a/applications/dendriticSolidification/ICs_and_BCs.h b/applications/dendriticSolidification/ICs_and_BCs.h index 7d4badf43..4ed8ced90 100644 --- a/applications/dendriticSolidification/ICs_and_BCs.h +++ b/applications/dendriticSolidification/ICs_and_BCs.h @@ -24,8 +24,8 @@ double InitialCondition::value (const Point &p, const unsigned int com // Initial condition for the concentration field if (index == 0){ - double deltaV = userInputs.get_model_constant_double("deltaV"); - scalar_IC = -deltaV; + double delta = userInputs.get_model_constant_double("delta"); + scalar_IC = -delta; } // Initial condition for the order parameter field else if (index == 1) { diff --git a/applications/dendriticSolidification/customPDE.h b/applications/dendriticSolidification/customPDE.h index caf164a4d..a934dc938 100644 --- a/applications/dendriticSolidification/customPDE.h +++ b/applications/dendriticSolidification/customPDE.h @@ -40,9 +40,9 @@ class customPDE: public MatrixFreePDE // Model constants specific to this subclass // ================================================================ - double DV = userInputs.get_model_constant_double("DV"); + double D = userInputs.get_model_constant_double("D"); double W0 = userInputs.get_model_constant_double("W0"); - double deltaV = userInputs.get_model_constant_double("deltaV"); + double delta = userInputs.get_model_constant_double("delta"); double epsilonM = userInputs.get_model_constant_double("epsilonM"); double theta0 = userInputs.get_model_constant_double("theta0"); double mult = userInputs.get_model_constant_double("mult"); diff --git a/applications/dendriticSolidification/dendriticSolidification.pdf b/applications/dendriticSolidification/dendriticSolidification.pdf index 6475c4311..5bd106cb3 100644 Binary files a/applications/dendriticSolidification/dendriticSolidification.pdf and b/applications/dendriticSolidification/dendriticSolidification.pdf differ diff --git a/applications/dendriticSolidification/equations.h b/applications/dendriticSolidification/equations.h index 15c37928a..77b2648c4 100644 --- a/applications/dendriticSolidification/equations.h +++ b/applications/dendriticSolidification/equations.h @@ -5,7 +5,7 @@ // ================================================================================= void variableAttributeLoader::loadVariableAttributes(){ // Variable 0 - set_variable_name (0,"T"); + set_variable_name (0,"u"); set_variable_type (0,SCALAR); set_variable_equation_type (0,PARABOLIC); @@ -17,7 +17,7 @@ void variableAttributeLoader::loadVariableAttributes(){ set_need_gradient_residual_term (0,true); // Variable 1 - set_variable_name (1,"n"); + set_variable_name (1,"phi"); set_variable_type (1,SCALAR); set_variable_equation_type (1,PARABOLIC); @@ -50,9 +50,6 @@ void variableAttributeLoader::loadVariableAttributes(){ // equations (or parts of residual equations) can be written below in "residualRHS". -// Free energy expression (or rather, its derivative) - - // ================================================================================= // residualRHS @@ -68,54 +65,54 @@ template void customPDE::residualRHS(variableContainer > & variable_list, dealii::Point > q_point_loc) const { -// The temperature and its derivatives -scalarvalueType T = variable_list.get_scalar_value(0); -scalargradType Tx = variable_list.get_scalar_gradient(0); +// The temperature and its derivatives +scalarvalueType u = variable_list.get_scalar_value(0); +scalargradType ux = variable_list.get_scalar_gradient(0); -// The order parameter and its derivatives -scalarvalueType n = variable_list.get_scalar_value(1); -scalargradType nx = variable_list.get_scalar_gradient(1); +// The order parameter and its derivatives +scalarvalueType phi = variable_list.get_scalar_value(1); +scalargradType phix = variable_list.get_scalar_gradient(1); -// The order parameter chemical potential and its derivatives +// The order parameter chemical potential and its derivatives scalarvalueType mu = variable_list.get_scalar_value(2); -double lambdaV = (DV/0.6267/W0/W0); +// The coupling constant, determined from solvability theory +double lambda = (D/0.6267/W0/W0); -// Derivative of the free energy density with respect to n -scalarvalueType fnV = (-(n-constV(lambdaV)*T*(constV(1.0)-n*n))*(constV(1.0)-n*n)); +// Derivative of the free energy density with respect to phi +scalarvalueType f_phi = -(phi-constV(lambda)*u*(constV(1.0)-phi*phi))*(constV(1.0)-phi*phi); +// The azimuthal angle scalarvalueType theta; - -for (unsigned i=0; i< n.n_array_elements;i++){ - theta[i] = std::atan2(nx[1][i],nx[0][i]); +for (unsigned i=0; i< phi.n_array_elements;i++){ + theta[i] = std::atan2(phix[1][i],phix[0][i]); } // Anisotropic gradient energy coefficient, its derivative and square -scalarvalueType WV = (constV(W0)*(constV(1.0)+constV(epsilonM)*std::cos(constV(mult)*(theta-constV(theta0))))); -scalarvalueType WTV = (constV(W0)*(-constV(epsilonM)*constV(mult)*std::sin(constV(mult)*(theta-constV(theta0))))); -scalarvalueType tauV = (WV*WV); - - +scalarvalueType W = constV(W0)*(constV(1.0)+constV(epsilonM)*std::cos(constV(mult)*(theta-constV(theta0)))); +scalarvalueType W_theta = constV(-W0)*(constV(epsilonM)*constV(mult)*std::sin(constV(mult)*(theta-constV(theta0)))); +scalarvalueType tau = W/constV(W0); +// The anisotropy term that enters in to the residual equation for mu scalargradType aniso; -aniso[0] = -WV*WV*nx[0]+WV*WTV*nx[1]; -aniso[1] = -WV*WV*nx[1]-WV*WTV*nx[0]; +aniso[0] = W*W*phix[0]-W*W_theta*phix[1]; +aniso[1] = W*W*phix[1]+W*W_theta*phix[0]; // Define required residuals -scalarvalueType rTV = (T-constV(0.5)*mu*constV(userInputs.dtValue)/tauV); -scalargradType rTxV = (constV(-DV*userInputs.dtValue)*Tx); -scalarvalueType rnV = (n-constV(userInputs.dtValue)*mu/tauV); -scalarvalueType rmuV = (fnV); +scalarvalueType ruV = (u+constV(0.5)*mu*constV(userInputs.dtValue)/tau); +scalargradType ruxV = (constV(-D*userInputs.dtValue)*ux); +scalarvalueType rphiV = (phi+constV(userInputs.dtValue)*mu/tau); +scalarvalueType rmuV = (-f_phi); scalargradType rmuxV = (-aniso); -// Residuals for the equation to evolve the concentration -variable_list.set_scalar_value_residual_term(0,rTV); -variable_list.set_scalar_gradient_residual_term(0,rTxV); +// Residuals for the equation to evolve the concentration +variable_list.set_scalar_value_residual_term(0,ruV); +variable_list.set_scalar_gradient_residual_term(0,ruxV); -// Residuals for the equation to evolve the order parameter -variable_list.set_scalar_value_residual_term(1,rnV); +// Residuals for the equation to evolve the order parameter +variable_list.set_scalar_value_residual_term(1,rphiV); -// Residuals for the equation to evolve the order parameter chemical potential +// Residuals for the equation to evolve the order parameter chemical potential variable_list.set_scalar_value_residual_term(2,rmuV); variable_list.set_scalar_gradient_residual_term(2,rmuxV); diff --git a/applications/dendriticSolidification/parameters.in b/applications/dendriticSolidification/parameters.in index fb15d14d7..06b1cdeca 100644 --- a/applications/dendriticSolidification/parameters.in +++ b/applications/dendriticSolidification/parameters.in @@ -1,4 +1,4 @@ -# Parameter list for the Allen-Cahn example application +# Parameter list for the dendriticSolidification example application # Refer to the PRISMS-PF manual for use of these parameters in the source code. # ================================================================================= @@ -44,7 +44,7 @@ set Max refinement level = 6 set Min refinement level = 0 # Set the fields used to determine the refinement using their index. -set Refinement criteria fields = n +set Refinement criteria fields = phi # Set the maximum and minimum value of the fields where the mesh should be refined set Refinement window max = 0.9999 @@ -83,8 +83,8 @@ set Number of time steps = 25000 # 1.5 on the top and bottom for variable 'n' in 2D # set Boundary condition for variable n = NATURAL, NATURAL, DIRICHLET: 1.5, DIRICHLET: 1.5 -set Boundary condition for variable T = DIRICHLET: -0.75 # equal to -deltaV -set Boundary condition for variable n = NATURAL +set Boundary condition for variable u = DIRICHLET: -0.75 # equal to -deltaV +set Boundary condition for variable phi = NATURAL set Boundary condition for variable mu = NATURAL # ================================================================================= @@ -97,13 +97,13 @@ set Boundary condition for variable mu = NATURAL # where [symmetry] is ISOTROPIC, TRANSVERSE, ORTHOTROPIC, or ANISOTROPIC. # Heat diffusion constant -set Model constant DV = 1.0, DOUBLE +set Model constant D = 1.0, DOUBLE # Isotropic gradient energy coefficient set Model constant W0 = 1.0, DOUBLE # Undercooling -set Model constant deltaV = 0.75, DOUBLE +set Model constant delta = 0.75, DOUBLE # Anisotropy paramter set Model constant epsilonM = 0.05, DOUBLE @@ -126,12 +126,18 @@ set Output condition = EQUAL_SPACING set Number of outputs = 10 # The number of time steps between updates being printed to the screen -set Skip print steps = 1000 +set Skip print steps = 1 #1000 # ================================================================================= # Set the checkpoint/restart parameters # ================================================================================= - +# Whether to start this simulation from the checkpoint of a previous simulation set Load from a checkpoint = false + +# Type of spacing between checkpoints ("EQUAL_SPACING", "LOG_SPACING", "N_PER_DECADE", +# or "LIST") set Checkpoint condition = EQUAL_SPACING -set Number of checkpoints = 10 + +# Number of times the creates checkpoints (total number for "EQUAL_SPACING" +# and "LOG_SPACING", number per decade for "N_PER_DECADE", ignored for "LIST") +set Number of checkpoints = 2 diff --git a/applications/dendriticSolidification/tex_files/dendriticSolidification.pdf b/applications/dendriticSolidification/tex_files/dendriticSolidification.pdf deleted file mode 100644 index 6475c4311..000000000 Binary files a/applications/dendriticSolidification/tex_files/dendriticSolidification.pdf and /dev/null differ diff --git a/applications/dendriticSolidification/tex_files/dendriticSolidification.tex b/applications/dendriticSolidification/tex_files/dendriticSolidification.tex index 6b0dfa65a..5c7aaa00c 100644 --- a/applications/dendriticSolidification/tex_files/dendriticSolidification.tex +++ b/applications/dendriticSolidification/tex_files/dendriticSolidification.tex @@ -183,6 +183,8 @@ This example application implements a simple model of dendritic solidification based on the CHiMaD Benchmark Problem 3, itself based on the model given in the following article: \\ ``Multiscale Finite-Difference-Diffusion-Monte-Carlo Method for Simulating Dendritic Solidification'' by M. Plapp and A. Karma, \emph{Journal of Computational Physics}, 165, 592-619 (2000) +This example application examines the non-isothermal solidification of a pure substance. The simulation starts with a circular solid seed in a uniformly undercooled liquid. As this seed grows, two variables are tracked, an order parameter, $\phi$, that denotes whether the material a liquid or solid and a nondimensional temperature, $u$. The crystal structure of the solid is offset from the simulation frame for generality and to expose more readily any effects of the mesh on the dendrite shape. + \section{Governing Equations} Consider a free energy density given by: @@ -199,14 +201,14 @@ \section{Governing Equations} \end{equation} where $\lambda$ is a dimensionless coupling constant. The gradient energy coefficient, $W$, is given by \begin{equation} -W = W_0 [1+\epsilon_m \cos[m(\theta-\theta_0)]] +W(\theta) = W_0 [1+\epsilon_m \cos[m(\theta-\theta_0)]] \end{equation} -where, $W_0$, $\epsilon_m$, and $\theta_0$ are constants and $\theta$ is the in-plane azimuthal angle, where $\tan(\theta) = \frac{n_y}{n_x}$, where $n_y$ and $n_x$ are components of the normal vector $\hat{n} = \frac{\nabla \phi}{|\nabla \phi|}$. +where, $W_0$, $\epsilon_m$, and $\theta_0$ are constants and $\theta$ is the in-plane azimuthal angle, where $\tan(\theta) = \frac{\partial \phi}{\partial y} / \frac{\partial \phi}{\partial x}$. The evolution equations are: \begin{gather} -\frac{\partial u}{\partial t} = - \frac{\delta \Pi}{\delta \phi} = D \nabla^2 u + \frac{1}{2} \tau(\hat{n}) \frac{\partial \phi}{\partial t} \\ -\tau(\hat{n}) \frac{\partial \phi}{\partial t} = \frac{\partial f}{\partial \phi} + \frac{\partial}{\partial x} \left[ |\nabla \phi|^2 W(\hat{n}) \frac{\partial W(\hat{n})}{\partial \left( \frac{\partial \phi}{\partial x} \right)} \right] \hat{x} + \frac{\partial}{\partial y} \left[ |\nabla \phi|^2 W(\hat{n}) \frac{\partial W(\hat{n})}{\partial \left( \frac{\partial \phi}{\partial y} \right)} \right] \hat{y} +\frac{\partial u}{\partial t} = D \nabla^2 u + \frac{1}{2} \frac{\partial \phi}{\partial t} \\ +\tau(\hat{n}) \frac{\partial \phi}{\partial t} = -\frac{\partial f}{\partial \phi} + \nabla \cdot \left[W^2(\theta) \nabla \phi \right]+ \frac{\partial}{\partial x} \left[ |\nabla \phi|^2 W(\theta) \frac{\partial W(\theta)}{\partial \left( \frac{\partial \phi}{\partial x} \right)} \right] + \frac{\partial}{\partial y} \left[ |\nabla \phi|^2 W(\theta) \frac{\partial W(\theta)}{\partial \left( \frac{\partial \phi}{\partial y} \right)} \right] \end{gather} where \begin{gather} @@ -216,35 +218,48 @@ \section{Governing Equations} The governing equations can be written more compactly using the variable $\mu$, the driving force for the phase transformation: \begin{gather} -\frac{\partial u}{\partial t} = D \nabla^2 u - \frac{\mu}{\tau} \\ +\frac{\partial u}{\partial t} = D \nabla^2 u + \frac{\mu}{2 \tau} \\ \tau(\hat{n}) \frac{\partial \phi}{\partial t} = \mu \\ -\mu = \left(\frac{\partial f}{\partial \phi}\right) - \nabla \cdot \left[\left(W^2 \frac{\partial \phi}{\partial x} - W \frac{\partial W}{\partial u} \frac{\partial \phi}{\partial y}\right)\hat{x} + \left(W^2 \frac{\partial \phi}{\partial y} + W \frac{\partial W}{\partial u} \frac{\partial \phi}{\partial x}\right) \hat{y} \right] +\mu = -\frac{\partial f}{\partial \phi} + \nabla \cdot \left[W^2(\theta) \nabla \phi \right]+ \frac{\partial}{\partial x} \left[ |\nabla \phi|^2 W(\theta) \frac{\partial W(\theta)}{\partial \left( \frac{\partial \phi}{\partial x} \right)} \right] + \frac{\partial}{\partial y} \left[ |\nabla \phi|^2 W\theta) \frac{\partial W(\theta)}{\partial \left( \frac{\partial \phi}{\partial y} \right)} \right] \end{gather} +The $\frac{\partial W(\theta)}{\partial \left( \frac{\partial \phi}{\partial x} \right)}$ and $\frac{\partial W(\theta)}{\partial \left( \frac{\partial \phi}{\partial y} \right)}$ expressions can be evaluated using the chain rule, using $\theta$ as an intermediary (i.e. $\frac{\partial W(\theta)}{\partial \left( \frac{\partial \phi}{\partial x} \right)}=\frac{\partial W(\theta)}{\partial \theta} \frac{\partial \theta}{\partial \left( \frac{\partial \phi}{\partial x} \right)}$ and $\frac{\partial W(\theta)}{\partial \left( \frac{\partial \phi}{\partial y} \right)}=\frac{\partial W(\theta)}{\partial \theta} \frac{\partial \theta}{\partial \left( \frac{\partial \phi}{\partial y} \right)}$). Also, the last two terms can be expressed using a divergence operator, allowing them to be grouped with the second term, which will simplify matters later. Carrying out these transformations yields: +\begin{multline} +\mu = \left[ \phi - \lambda u \left(1 - \phi^2 \right) \right] \left(1-\phi^2\right) + \nabla \cdot \bigg[\left(W^2 \frac{\partial \phi}{\partial x} + W_0 \epsilon_m m W(\theta) \sin \left[ m \left(\theta - \theta_0 \right) \right] \frac{\partial \phi}{\partial y}\right)\hat{x} \\ ++ \left(W^2 \frac{\partial \phi}{\partial y} -W_0 \epsilon_m m W(\theta) \sin \left[ m \left(\theta - \theta_0 \right) \right] \frac{\partial \phi}{\partial x}\right) \hat{y} \bigg] +\end{multline} + \section{Model Constants} $W_0$: Controls the interfacial thickness, default value of 1.0. \\ $\tau_0$: Controls the phase transformation kinetics, default value of 1.0. \\ $\epsilon_m$: T the strength of the anisotropy, default value of 0.05. \\ $D$: The thermal diffusion constant, default value of 1.0. \\ -$\Delta = \frac{T_m-T_0}{L/c_p}$: The level of undercooling, default value of 0.75. \\ -$\theta_0$ = The rotation angle of the anisotropy, default value of 0.125 ($\sim$7.16$^\circ$). +$\Delta: \frac{T_m-T_0}{L/c_p}$: The level of undercooling, default value of 0.75. \\ +$\theta_0$: The rotation angle of the anisotropy with respect to the simulation frame, default value of 0.125 ($\sim$7.2$^\circ$). \section{Time Discretization} Considering forward Euler explicit time stepping, we have the time discretized kinetics equation: \begin{gather} -u^{n+1} = \left(u^{n} - \frac{\mu^n \Delta t}{\tau}\right) + D \Delta t \nabla^2 u^n \\ -\phi^{n+1} = \left(\phi^n - \frac{\Delta t \mu^n}{\tau}\right) \\ - \mu^{n+1} = \left(\frac{\partial f^n}{\partial \phi}\right) - \nabla \cdot \left[\left(W^2 \frac{\partial \phi^n}{\partial x} - W \frac{\partial W}{\partial u^n} \frac{\partial \phi^n}{\partial y}\right)\hat{x} + \left(W^2 \frac{\partial \phi^n}{\partial y} + W \frac{\partial W}{\partial u} \frac{\partial \phi^n}{\partial x}\right) \hat{y} \right] +u^{n+1} = u^{n} + \Delta t \left( D \nabla^2 u^n + \frac{\mu^n}{2 \tau} \right) \\ +\phi^{n+1} = \phi^n + \frac{\Delta t \mu^n}{\tau} \end{gather} +\begin{multline} +\mu^{n+1} = \left[ \phi^n - \lambda u \left(1 - (\phi^n)^2 \right) \right] \left(1-(\phi^n)^2\right) + \nabla \cdot \bigg[\left(W^2 \frac{\partial \phi^n}{\partial x} + W_0 \epsilon_m m W(\theta^n) \sin \left[ m \left(\theta^n - \theta_0 \right) \right] \frac{\partial \phi^n}{\partial y}\right)\hat{x} \\ ++ \left(W^2 \frac{\partial \phi^n}{\partial y} -W_0 \epsilon_m m W(\theta^n) \sin \left[ m \left(\theta^n - \theta_0 \right) \right] \frac{\partial \phi^n}{\partial x}\right) \hat{y} \bigg] +\end{multline} \section{Weak Formulation} \begin{gather} -\int_{\Omega} w u^{n+1} ~dV = \int_{\Omega} w \underbrace{\left(u^{n} - \frac{\mu^n \Delta t}{\tau}\right)}_{r_u} + \nabla w \underbrace{(-D \Delta t \nabla u^n)}_{r_{ux}} ~dV \\ -\int_{\Omega} w \phi^{n+1} ~dV = \int_{\Omega} w \underbrace{\left(\phi^n - \frac{\Delta t \mu^n}{\tau}\right)}_{r_{\phi}} ~dV \\ -\int_{\Omega} w \mu^{n+1} ~dV = \int_{\Omega} w \underbrace{\left(\frac{\partial f^n}{\partial \phi}\right)}_{r_{\mu}} + \nabla w \cdot \underbrace{\left[\left(W^2 \frac{\partial \phi^n}{\partial x} - W \frac{\partial W}{\partial u^n} \frac{\partial \phi^n}{\partial y}\right)\hat{x} + \left(W^2 \frac{\partial \phi^n}{\partial y} + W \frac{\partial W}{\partial u} \frac{\partial \phi^n}{\partial x}\right) \hat{y} \right]}_{r_{\phi x}} ~dV -\end{gather} - +\int_{\Omega} w u^{n+1} ~dV = \int_{\Omega} w \underbrace{\left(u^{n} + \frac{\mu^n \Delta t}{2 \tau}\right)}_{r_u} + \nabla w \cdot \underbrace{(-D \Delta t \nabla u^n)}_{r_{ux}} ~dV \\ +\int_{\Omega} w \phi^{n+1} ~dV = \int_{\Omega} w \underbrace{\left(\phi^n + \frac{\Delta t \mu^n}{\tau}\right)}_{r_{\phi}} ~dV +\end{gather} \small +\begin{multline} +\int_{\Omega} w \mu^{n+1} ~dV = \int_{\Omega} w \underbrace{\left[ \phi^n - \lambda u \left(1 - (\phi^n)^2 \right) \right] \left(1-(\phi^n)^2\right)}_{r_{\mu}} \\ ++ \nabla w \cdot \underbrace{\bigg[-\left(W^2 \frac{\partial \phi^n}{\partial x} + W_0 \epsilon_m m W(\theta^n) \sin \left[ m \left(\theta^n - \theta_0 \right) \right] \frac{\partial \phi^n}{\partial y}\right)\hat{x} +- \left(W^2 \frac{\partial \phi^n}{\partial y} -W_0 \epsilon_m m W(\theta^n) \sin \left[ m \left(\theta^n - \theta_0 \right) \right] \frac{\partial \phi^n}{\partial x}\right) \hat{y} \bigg]}_{r_{\phi x}} ~dV +\end{multline} +\normalsize diff --git a/applications/precipitateEvolution/formulation_precipitateEvolution.pdf b/applications/precipitateEvolution/formulation_precipitateEvolution.pdf index c3c5cce01..ed7299858 100644 Binary files a/applications/precipitateEvolution/formulation_precipitateEvolution.pdf and b/applications/precipitateEvolution/formulation_precipitateEvolution.pdf differ diff --git a/applications/precipitateEvolution/parameters.in b/applications/precipitateEvolution/parameters.in index 0c2db1c66..4d08046a4 100644 --- a/applications/precipitateEvolution/parameters.in +++ b/applications/precipitateEvolution/parameters.in @@ -95,10 +95,16 @@ set Skip print steps = 1000 # ================================================================================= # Set the checkpoint/restart parameters # ================================================================================= - +# Whether to start this simulation from the checkpoint of a previous simulation set Load from a checkpoint = false + +# Type of spacing between checkpoints ("EQUAL_SPACING", "LOG_SPACING", "N_PER_DECADE", +# or "LIST") set Checkpoint condition = EQUAL_SPACING -set Number of checkpoints = 10 + +# Number of times the creates checkpoints (total number for "EQUAL_SPACING" +# and "LOG_SPACING", number per decade for "N_PER_DECADE", ignored for "LIST") +set Number of checkpoints = 2 # ================================================================================= # Set the boundary conditions diff --git a/applications/precipitateEvolution/precipitateEvolution.pdf b/applications/precipitateEvolution/precipitateEvolution.pdf deleted file mode 100644 index ed7299858..000000000 Binary files a/applications/precipitateEvolution/precipitateEvolution.pdf and /dev/null differ diff --git a/applications/preferential_nucleationModel/parameters.in b/applications/preferential_nucleationModel/parameters.in index bf2448e66..fd903702b 100644 --- a/applications/preferential_nucleationModel/parameters.in +++ b/applications/preferential_nucleationModel/parameters.in @@ -61,12 +61,32 @@ set Time step = 0.022 set Number of time steps = 100 # ================================================================================= -# Set the checkpoint/restart parameters +# Set the output parameters # ================================================================================= +# Type of spacing between outputs ("EQUAL_SPACING", "LOG_SPACING", "N_PER_DECADE", +# or "LIST") +set Output condition = EQUAL_SPACING + +# Number of times the program outputs the fields (total number for "EQUAL_SPACING" +# and "LOG_SPACING", number per decade for "N_PER_DECADE", ignored for "LIST") +set Number of outputs = 10 +# The number of time steps between updates being printed to the screen +set Skip print steps = 100 + +# ================================================================================= +# Set the checkpoint/restart parameters +# ================================================================================= +# Whether to start this simulation from the checkpoint of a previous simulation set Load from a checkpoint = false + +# Type of spacing between checkpoints ("EQUAL_SPACING", "LOG_SPACING", "N_PER_DECADE", +# or "LIST") set Checkpoint condition = EQUAL_SPACING -set Number of checkpoints = 10 + +# Number of times the creates checkpoints (total number for "EQUAL_SPACING" +# and "LOG_SPACING", number per decade for "N_PER_DECADE", ignored for "LIST") +set Number of checkpoints = 2 # ================================================================================= # Set the boundary conditions @@ -150,17 +170,3 @@ set Model constant wgb = 8.0, DOUBLE set Model constant gbll = 196, DOUBLE # Right limit set Model constant gbrl = 204, DOUBLE - -# ================================================================================= -# Set the output parameters -# ================================================================================= -# Type of spacing between outputs ("EQUAL_SPACING", "LOG_SPACING", "N_PER_DECADE", -# or "LIST") -set Output condition = EQUAL_SPACING - -# Number of times the program outputs the fields (total number for "EQUAL_SPACING" -# and "LOG_SPACING", number per decade for "N_PER_DECADE", ignored for "LIST") -set Number of outputs = 10 - -# The number of time steps between updates being printed to the screen -set Skip print steps = 100 diff --git a/prisms_pf_user_guide_files/logo.pdf b/prisms_pf_user_guide_files/logo.pdf new file mode 100644 index 000000000..590a4b857 Binary files /dev/null and b/prisms_pf_user_guide_files/logo.pdf differ diff --git a/prisms_pf_user_guide_files/prismspf_user_guide.pdf b/prisms_pf_user_guide_files/prismspf_user_guide.pdf deleted file mode 100644 index 01ec0cc98..000000000 Binary files a/prisms_pf_user_guide_files/prismspf_user_guide.pdf and /dev/null differ diff --git a/prisms_pf_user_guide_files/prismspf_user_guide.tex b/prisms_pf_user_guide_files/prismspf_user_guide.tex index 08b87c1da..81d29d0e6 100644 --- a/prisms_pf_user_guide_files/prismspf_user_guide.tex +++ b/prisms_pf_user_guide_files/prismspf_user_guide.tex @@ -59,23 +59,36 @@ \usepackage{amsmath} \usepackage{amsfonts} \usepackage{amssymb} +\usepackage{titling} + +\renewcommand\maketitlehooka{\null\mbox{}} +\renewcommand\maketitlehookd{\vfill\null} %%% The "real" document content comes below... -\title{PRISMS-PF User Guide (v2.0)} +\title{PRISMS-PF User Guide (v2.0.1)} \author{Stephen DeWitt (prismsphasefield.dev@umich.edu)} %\date{} % Activate to display a given date or no date (if empty), % otherwise the current date is printed - + \begin{document} -\maketitle +\pretitle{% + \begin{center} + \LARGE + \includegraphics[width=0.8\textwidth]{logo}\\[\bigskipamount] +} +\posttitle{\end{center}} + +\begin{titlingpage} +\maketitle +\end{titlingpage} \tableofcontents \clearpage \section{Overview} -PRISMS-PF is an open-source finite element simulation code with a focus on solving equations from phase field models. It is being developed as part of the PRISMS Center at the University of Michigan. PRISMS-PF is built on top of the popular and powerful deal.II finite element library. PRISMS-PF was developed to make high performance phase field simulation capabilities available to the wider scientific community with an easy-to-use and easy-to-learn interface. Benchmark tests show that even without its adaptive meshing capabilities PRISMS-PF is competitive with specialized finite difference codes written in Fortran with MPI parallelization in terms performance, and in some cases runs several times faster. PRISMS-PF can be used to solve a wide variety of systems of coupled parabolic partial differential equations (e.g. the diffusion equation) and elliptic partial differential equations (e.g. Poisson's equation). With PRISMS-PF, you have access to adaptive meshing and parallelization that has been demonstrated on over a thousand processors. Moreover, the matrix-free framework from deal.II allows much larger than typical finite element programs -- PRISMS-PF has been used for calculations with over one \emph{billion} degrees of freedom. +PRISMS-PF is an open-source finite element simulation framework with a focus on solving equations from phase field models. It is being developed as part of the PRISMS Center at the University of Michigan. PRISMS-PF is built on top of the popular and powerful deal.II finite element library. PRISMS-PF was developed to make high performance phase field simulation capabilities available to the wider scientific community with an easy-to-use and easy-to-learn interface. Benchmark tests show that even without its adaptive meshing capabilities PRISMS-PF is competitive with specialized finite difference codes written in Fortran with MPI parallelization in terms performance, and in some cases runs several times faster. PRISMS-PF can be used to solve a wide variety of systems of coupled parabolic partial differential equations (e.g. the diffusion equation) and elliptic partial differential equations (e.g. Poisson's equation). With PRISMS-PF, you have access to adaptive meshing and parallelization that has been demonstrated on over a thousand processors. Moreover, the matrix-free framework from deal.II allows much larger than typical finite element programs -- PRISMS-PF has been used for calculations with over one \emph{billion} degrees of freedom. This user guide starts with instructions for downloading PRISMS-PF and install the necessary prerequisites. Next are instructions for running the built-in example applications and visualizing the results. A detailed look at the input files follows, and the guide finishes with some instructions on how to create your own PRISMS-PF applications. @@ -573,6 +586,20 @@ \section{The Input File: parameters.in} \label{parameters} \end{tabular} \end{center} +\begin{center} + \begin{tabular}{ | p{0.2\textwidth} | p{0.17\textwidth} | p{0.08\textwidth} | p{0.1\textwidth} | p{0.3\textwidth} |} + \hline + \multicolumn{5}{|c|}{\textbf{Checkpoints (Optional)}} \\ + \hline + \hline + \emph{Name} & \emph{Options} & \emph{Required} & \emph{Default} & \emph{Description} \\ \hline + Load from a checkpoint & Boolean & no & false & Whether to start the simulation from the checkpoint of another simulation. See Note 2 below for the details of the checkpoint/restart system. \\ \hline + Checkpoint condition & EQUAL\_SPACING, LOG\_SPACING, N\_PER\_DECADE, LIST & no & EQUAL \_SPACING & This sets the spacing between the times the simulation outputs the model variables. EQUAL\_SPACING spaces them equally, LOG\_SPACING spaces them $10^{n/(outputs) \log(time steps)}$, N\_PER\_DECADE allows the user to set how many times the simulation outputs per power of ten iterations, and LIST outputs at a user-given list of time step numbers. \\ \hline + Number of checkpoints & Any non-negative integer & no & 1 & The number of inputs if the output condition is EQUAL\_SPACING. The number of outputs if the output condition is N\_PER\_DECADE. Ignored for the other output conditions. \\ \hline + List of time steps to save checkpoints & Comma-separated list of non-negative integers & no & 0 & The list of time steps to create checkpoints, used for the LIST output condition and ignored for the others. \\ \hline + \end{tabular} +\end{center} + \begin{center} \begin{tabular}{ | p{0.2\textwidth} | p{0.17\textwidth} | p{0.08\textwidth} | p{0.1\textwidth} | p{0.3\textwidth} |} \hline @@ -592,27 +619,27 @@ \section{The Input File: parameters.in} \label{parameters} \hline \hline \emph{Name} & \emph{Options} & \emph{Required} & \emph{Default} & \emph{Description} \\ \hline - Load initial conditions & Comma-separated list of booleans & no & false & One true/false flag for each variable for whether the initial condition should be loaded from a vtk file. Currently, only scalar fields can be read in. SSee Note 2 below for details. \\ \hline - Load parallel file & Comma-separated list of booleans & no & false & One true/false flag for each variable for whether each processor should read the initial conditions from a seperate file. See Note 2 below for details. \\ \hline - File names & Comma-separated list of strings & no & & The name of the vtk file to be read for each variable, ignored for variables where the initial conditions isn't read in from a file. Often, all of the variables will read from the same vtk file. See Note 2 below for details. \\ \hline - Variable names in the files & Comma-separated list of strings & no & & What each variable is named in the file being loaded. See Note 2 below for details. \\ \hline + Load initial conditions & Comma-separated list of booleans & no & false & One true/false flag for each variable for whether the initial condition should be loaded from a vtk file. Currently, only scalar fields can be read in. See Note 3 below for details. \\ \hline + Load parallel file & Comma-separated list of booleans & no & false & One true/false flag for each variable for whether each processor should read the initial conditions from a seperate file. See Note 3 below for details. \\ \hline + File names & Comma-separated list of strings & no & & The name of the vtk file to be read for each variable, ignored for variables where the initial conditions isn't read in from a file. Often, all of the variables will read from the same vtk file. See Note 3 below for details. \\ \hline + Variable names in the files & Comma-separated list of strings & no & & What each variable is named in the file being loaded. See Note 3 below for details. \\ \hline \end{tabular} \end{center} \begin{center} \begin{tabular}{ | p{0.2\textwidth} | p{0.17\textwidth} | p{0.08\textwidth} | p{0.1\textwidth} | p{0.3\textwidth} |} \hline - \multicolumn{5}{|c|}{\textbf{Nucleation (Optional}} \\ + \multicolumn{5}{|c|}{\textbf{Nucleation (Optional)}} \\ \hline \hline \emph{Name} & \emph{Options} & \emph{Required} & \emph{Default} & \emph{Description} \\ \hline - Nucleus semiaxes (x, y ,z) & Three positive real numbers & no & & The semiaxes of the ellipsoidal nuclei to be seeded. See Note 3 below for details. \\ \hline - Freeze zone semiaxes (x, y ,z) & Three positive real numbers & no & & The semiaxes for the ellipsoidal region where the nucleus is frozen after seeding. See Note 3 below for details. \\ \hline - Freeze time following nucleation & Any non-negative real number & no & 0 & The amount of time the nucleus is frozen after seeding. See Note 3 below for details. \\ \hline - Nucleation-free border thickness & Any non-negative real number & no & 0 & The size of the buffer region where nucleation is not allowed unless the boundary conditions are periodic. See Note 3 below for details. \\ \hline - Minimum allowed distance between nuclei & Any non-negative real number & no & 2$\times$ the largest nucleus semiaxis & The minimum allowed distance between nuclei centers during a single nucleation attempt. See Note 3 below for details. \\ \hline - Order parameter cutoff value & Any non-negative real number & no & 0.01 & The minimum allowed value of the sum of all nucleating variable fields where nucleation is allowed to occur. Implemented to prevent nucleation inside existing particles. See Note 3 below for details. \\ \hline - Time steps between nucleation attempts & Any positive integer & no & 100 & The number of time steps between nucleation attempts. See Note 3 below for details. \\ \hline + Nucleus semiaxes (x, y ,z) & Three positive real numbers & no & & The semiaxes of the ellipsoidal nuclei to be seeded. See Note 4 below for details. \\ \hline + Freeze zone semiaxes (x, y ,z) & Three positive real numbers & no & & The semiaxes for the ellipsoidal region where the nucleus is frozen after seeding. See Note 4 below for details. \\ \hline + Freeze time following nucleation & Any non-negative real number & no & 0 & The amount of time the nucleus is frozen after seeding. See Note 4 below for details. \\ \hline + Nucleation-free border thickness & Any non-negative real number & no & 0 & The size of the buffer region where nucleation is not allowed unless the boundary conditions are periodic. See Note 4 below for details. \\ \hline + Minimum allowed distance between nuclei & Any non-negative real number & no & 2$\times$ the largest nucleus semiaxis & The minimum allowed distance between nuclei centers during a single nucleation attempt. See Note 4 below for details. \\ \hline + Order parameter cutoff value & Any non-negative real number & no & 0.01 & The minimum allowed value of the sum of all nucleating variable fields where nucleation is allowed to occur. Implemented to prevent nucleation inside existing particles. See Note 4 below for details. \\ \hline + Time steps between nucleation attempts & Any positive integer & no & 100 & The number of time steps between nucleation attempts. See Note 4 below for details. \\ \hline \end{tabular} \end{center} @@ -623,7 +650,7 @@ \section{The Input File: parameters.in} \label{parameters} \hline \hline \emph{Name} & \emph{Options} & \emph{Required} & \emph{Default} & \emph{Description} \\ \hline - Model constant [constant name] & value followed by a comma then a type & no & & Sets the value of a constant defined for that particular application. The allowed types are DOUBLE, INT, BOOL, TENSOR, and [symmetry] ELASTIC CONSTANTS where [symmetry] is ISOTROPIC, TRANSVERSE, ORTHOTROPIC, or ANISOTROPIC. See Note 4 below for details. \\ \hline + Model constant [constant name] & value followed by a comma then a type & no & & Sets the value of a constant defined for that particular application. The allowed types are DOUBLE, INT, BOOL, TENSOR, and [symmetry] ELASTIC CONSTANTS where [symmetry] is ISOTROPIC, TRANSVERSE, ORTHOTROPIC, or ANISOTROPIC. See Note 5 below for details. \\ \hline \end{tabular} \end{center} @@ -648,15 +675,18 @@ \section{The Input File: parameters.in} \label{parameters} set Boundary condition for variable u, component y = PERIODIC \end{lstlisting} -\textbf{Note 2 (Loading Initial Conditions from File):} \\ +\textbf{Note 2 (Checkpoint/Restart):} \\ +The checkpoint/restart simulation allows one to continue from a previous simulation by loading the mesh and variable values from that previous simulation. One use of this system is to continue a simulation that stopped part of the way through, due to a hardware failure, running out of the allotted time on a cluster, etc. A second use is to use one simulation as the initial condition for another. Note that the simulated time carries over from the checkpoint. Thus if one ran a simulation to completion but wanted to see further evolution, one could load from the checkpoint created at the end of that simulation, but the desired number of time steps or simulation end time would have to be increased. Currently, the checkpoint system always read from files named ``restart.mesh'', ``restart.mesh.info'', and ``restart.time.info''. When a checkpoint is created, the previous checkpoint files have ``.old'' appended to their file names. To load from these older checkpoint files, the newer ones should be deleted (or moved) and the ``.old'' should be deleted from the names of the older files. An example of using the checkpoint/restart system can be seen in the `dendriticSolidification' application. + +\textbf{Note 3 (Loading Initial Conditions from File):} \\ Currently, initial conditions can only be read from vtk files (\emph{not} vtu files). Some variables can have initial conditions read from file and others can be specified in ICs\_and\_BCs.h in the same application. For each variable, the user must set whether the file(s) to be read are in serial format, where all processors read from the same file, or parallel format, where all processors read from different files. If parallel format is selected, the desired domain decomposition must between the files and the simulation to be run. For non-adaptive meshes this will be true if the same number of cores is the same between the simulation that generated the vtk files and the simulation reading the vtk files. For adaptive meshes, obtaining the same domain decomposition may be difficult and merging parallel vtk files into a single file is likely the best approach. This process is planned to be cleaner in future versions of PRISMS-PF. An example of loading inital conditions from file can be seen in the `allenCahn\_pfield' application. -\textbf{Note 3 (Nucleation):} \\ +\textbf{Note 4 (Nucleation):} \\ PRISMS-PF includes the capability for explicitly placing nuclei over the course of a simulation using an approach similar to the one described in the following publication: \\ Jokisaari, Permann, and Thornton, A nucleation algorithm for the coupled conserved-nonconserved phase field model, \emph{Computational Materials Science}, 112, (2016). \\ A nucleus of an non-conserved order parameter is placed within the computational domain determined by a probability given by the `getNucleationProbability' function in the `nucleation.h' file. The variables that are allowed to nucleate are specified in the `loadVariableAttributes' function in the `equations.h' file, as are the variable values needed to calculate the nucleation probability. The determination of when and where a nucleus should be seeded is determined in the core PRISMS-PF library, but the actual placement of the nucleus by modifying one of the model fields is expected to be performed in the `residualRHS' function in the `equations.h' file. The mobility for the nucleated field should be set to zero in the region surrounding the nucleus (the ``freeze zone'') for a specified amount of time (the ``freeze time''). Examples of nucleating particles can be found in the nucleationModel and preferential\_nucleationModel applications. -\textbf{Note 4 (Model constants):} \\ +\textbf{Note 5 (Model constants):} \\ Each application specifies its own set of model constants. These are most often used in the residual equations in the `equations.h' file, although they may also be used to specify initial conditions, non-uniform Dirichlet boundary conditions, nucleation probabilties, etc. Currently, five types of model constants are accepted: DOUBLE, INT, BOOL, TENSOR, and ELASTIC CONSTANTS. The use of these different types is as follows: \begin{itemize} \item DOUBLE: For individual real numbers @@ -1306,7 +1336,7 @@ \section{Tests} A summary of the tests will print to the screen. \section{Creating Custom Applications} -You can create your own PRISMS-PF applications by making simple modifications to the input files described in the previous section. To create a new application, simply create a new folder in the applications directory and copy the files from a related example application. \textbf{If the file ``CMakeCache.txt'' exists, delete it} (this file contains paths to the original application, and if left would cause the compiler to compile the code from the original application). Then, make your desired modifications (changing the initial or boundary conditions, changing the residual equations, etc.) and compile and run your application the same way you would one of the example applications. +You can create your own PRISMS-PF applications by making simple modifications to the input files described in the previous section. To create a new application, simply create a new folder in the applications directory and copy the files from a related example application. Currently, the new application folder must be in the applications directory, otherwise it will not be able to find the required files in the core PRISMS-PF library. \textbf{If the file ``CMakeCache.txt'' exists, delete it} (this file contains paths to the original application, and if left would cause the compiler to compile the code from the original application). Then, make your desired modifications (changing the initial or boundary conditions, changing the residual equations, etc.) and compile and run your application the same way you would one of the example applications. Once your have your own applications running, we'd love to help you share them with the community. Please contact us at prismsphasefield.dev@umich.edu if you need help using GitHub to generate a pull request so that we can add your work to the public repository. diff --git a/prismspf_user_guide.pdf b/prismspf_user_guide.pdf index 01ec0cc98..7a77111c2 100644 Binary files a/prismspf_user_guide.pdf and b/prismspf_user_guide.pdf differ diff --git a/version b/version index 4041a80a8..38f77a65b 100644 --- a/version +++ b/version @@ -1 +1 @@ -2.0.1 (pre) +2.0.1 diff --git a/version_changes.md b/version_changes.md index 74b86337a..effafceec 100644 --- a/version_changes.md +++ b/version_changes.md @@ -1,22 +1,25 @@ -# Version 2.0.1 (pre-release) -Minor update to v2.0, planned to be released in Fall 2017. So far the biggest change is the introduction of a checkpoint/restart system. +# Version 2.0.1 +Minor update to v2.0, planned to be released in Fall 2017. The biggest change is the introduction of a checkpoint/restart system. Added functionality: - A checkpoint/restart system has been added. It allows runs to be restarted if they fail or you want the run to continue for more simulated time. - The parser to load in VTK files for initial conditions has been generalized so that it can read files generated from ParaView Changes to the example applications: +- Fixed numerous errors in the documentation for the 'dendriticSolidification' app and edited the 'equations.h' file to use the notation from the documentation. - Fixed typos in the documentation for the 'coupledCahnHilliardAllenCahn' app. Bug fixes: - Fixed the subscriptor bug that appeared at the end of simulations in debug mode. +Other changes: +- Some minor updates to the user guide, including adding a new PRISMS-PF logo. + Known issues: - PFields only work for scalar fields and only work when the variable with index zero is a scalar field. - Postprocessing only works for scalar fields and only when the variable with index zero is a scalar field. -- The formulation file for the dendriticSolidifiation application may have errors. - An extraneous error can appear under the following circumstances: in debug mode, with multiple cores, with adaptive meshing, using deal.II v8.4.2 or earlier. The error message includes something similar to: "Called compress(VectorOperation::insert), but the element received from a remote processor, value -2.944283206211677e-10, does not match with the value -2.944283206213795e-10 on the owner processor 60". This is a deal.II issue that they fixed in v8.5 where the tolerance for comparing numbers between processors is too tight and can be triggered by standard round-off error. It doesn't effect simulation results. - + # Version 2.0: Major update to PRISMS-PF, released in August 2017. The core library is very similar to v1.2, but the user interface is substantially changed. Most importantly, input parameters are now read from a text file, instead of via #define statements. All of the individual interface changes are not listed here, see the User Guide for the new file structure and syntax.