78{
79 libMesh::out <<
"This example solves the Cahn-Hillard equation with chemical potential f:\n"
80 << " u_t = \\div(M(u)\\grad f(u))\n"
81 << "Here we have\n"
82 << " u, -1 <= u <= 1 -- relative concentration (difference of two concentrations in a binary mixture) \n"
83 << " M, M >= 0 -- mobility of the mixture\n"
84 << " f = \\delta E/\\delta u -- variational derivative of the free energy functional E\n"
85 << " E = \\int[\\kappa/2 |\\grac u|^ + g(u)]\n"
86 << "where the gradient term is the interfacial energy density with \\kappa quantifying the energy of the interface,\n"
87 << "and g(u) is the bulk energy density\n"
88 << " g(u) = \\theta L(u) + \\theta_c W(u),\n"
89 << "L(u) is the (optional, in this model) logarithmic term corresponding to the entropy of the mixture:\n"
90 << " L(u) = (\\theta/2)[(1+u)\\ln((1+u)/2) + (1-u)\\ln((1-u)/2)],\n"
91 << "where \\theta is related to the Boltzmann factor k_B T - a proxy for the absolute temperature T.\n"
92 << "L can be optionally approximated ('truncated') using a quadratic or a cubic polynomial on [-1,1]\n"
93 << "W(u) is the (optional, in this model) potential promoting demixing. It can take the form of \n"
94 << "a 'double well' potential\n"
95 << " W(u) = \\theta_c (u^4/4 - u^2/2),\n"
96 << " or \n"
97 << "a 'double obstacle' potential\n"
98 << " W(u) = (\\theta_c/2)(1-u^2),\n"
99 << "where \\theta_c is the critical 'temperature'.\n"
100 << "Finally, mobility M can be constant of 'degenerate', by which we mean that M is varying with u and \n"
101 << "vanishing (degenerating) whenever u reaches critical values +1 or -1:\n"
102 << " M(u) = 1.0\n"
103 << " or\n"
104 << " M(u) = (1.0 - u^2)\n"
105 << "Degenerate mobility should generally be used only in conjunction with logarithmic free energy terms.\n\n"
106 << "The equation is solved on a periodic domain (in 1D, 2D or 3D)\n"
107 << "using a Galerkin formulation with C^1 elements approximating the H^2_{per} function space.\n\n"
108 << "\n-----------\n"
109 << "COMPILING: "
110 << "\n-----------\n"
111 << "Compile as follows (assuming libmesh has been built): \n"
112 << "METHOD=<method> make \n"
113 << "where <method> is dbg or opt.\n"
114 << "\n-----------\n"
115 << "HELP: "
116 << "\n-----------\n"
117 << "Print this help message:\n"
118 << argv[0] << " --help\n"
119 << "\n-----------\n"
120 << "RUNNING: "
121 << "\n-----------\n"
122 << "Run in serial with PETSc-3.4 and above as follows:\n"
123 << "\n"
124 << argv[0] << "\n"
125 << " [--verbose] dim=<1|2|3> N=<number_of_linear_elements> \n"
126 << " kappa=<kappa_value> growth=<yes|no> degenerate=<yes|no> [--cahn-hillard] \n"
127 << " [--netforce] energy=<double_well|double_obstacle|log_double_well|log_double_obstacle> log_truncation_order=<2|3> \n"
128 << " theta=<theta_value> theta_c=<theta_c_value> \n"
129 << " initial_state=<ball|rod|strip> initial_center='x [y [z]]' initial_width=<width> \n"
130 << " min_time=<initial_time> max_time=<final_time> dt=<timestep_size> crank_nicholson_weight=<between_0_and_1> \n"
131 << " output_base=<base_filename> output_dt=<output_timestep_size> [-snes_type vinewtonrsls | vinewtonssls] \n"
132 << "(with PETSc-3.3 use -snes_type virs | viss).\n"
133 << argv[0] << " --verbose \n"
134 << "is a pretty good start.\n"
135 << "\nModeling a 1D system with 2D or 3D (for a strip the second and third components of the center are immaterial):\n"
136 << argv[0]<< " --verbose dim=1 N=1024 initial_state=strip initial_center=0.5 initial_width=0.1 dt=1e-10 max_time=1e-6\n"
137 << argv[0]<< " --verbose dim=2 N=64 initial_state=strip initial_center=0.5 initial_width=0.1 dt=1e-10 max_time=1e-6 \n"
138 << argv[0]<< " --verbose dim=3 N=32 initial_state=strip initial_center=0.5 initial_width=0.1 dt=1e-10 max_time=1e-6 \n"
139 << "\n"
140 << "Modeling a 2D system with 3D (for a rod the third component of the center is immaterial) \n"
141 << argv[0]<< " --verbose dim=2 N=64 initial_state=rod initial_center='0.5 0.5' initial_width=0.1 dt=1e-10 max_time=1e-6 \n"
142 << argv[0]<< " --verbose dim=3 N=32 initial_state=rod initial_center='0.5 0.5' initial_width=0.1 dt=1e-10 max_time=1e-6 \n"
143 << "\n"
144 << "A 3D system with an initial ball in the center\n"
145 << argv[0] << " --verbose dim=3 N=32 initial_state=ball initial_center='0.5 0.5 0.5' initial_width=0.1 dt=1e-10 max_time=1e-6 \n"
146 << "\n"
147 << "Add -snes_type vinewtonrsls to run the variational inequality version that ensures the solution is between -1.0 and 1.0 at all times.\n"
148 << "If using PETSc-3.3, run with -snes_type virs.\n"
149 << "\n"
150 << std::endl;
151}
