1.. index:: fix msst
2
3fix msst command
4================
5
6Syntax
7""""""
8
9.. parsed-literal::
10
11   fix ID group-ID msst dir shockvel keyword value ...
12
13* ID, group-ID are documented in :doc:`fix <fix>` command
14* msst = style name of this fix
15* dir = *x* or *y* or *z*
16* shockvel = shock velocity (strictly positive, distance/time units)
17* zero or more keyword value pairs may be appended
18* keyword = *q* or *mu* or *p0* or *v0* or *e0* or *tscale* or *beta* or *dftb*
19
20  .. parsed-literal::
21
22       *q* value = cell mass-like parameter (mass\^2/distance\^4 units)
23       *mu* value = artificial viscosity (mass/length/time units)
24       *p0* value = initial pressure in the shock equations (pressure units)
25       *v0* value = initial simulation cell volume in the shock equations (distance\^3 units)
26       *e0* value = initial total energy (energy units)
27       *tscale* value = reduction in initial temperature (unitless fraction between 0.0 and 1.0)
28       *dftb* value = *yes* or *no* for whether using MSST in conjunction with DFTB+
29       *beta* value = scale factor for improved energy conservation
30
31Examples
32""""""""
33
34.. code-block:: LAMMPS
35
36   fix 1 all msst y 100.0 q 1.0e5 mu 1.0e5
37   fix 2 all msst z 50.0 q 1.0e4 mu 1.0e4  v0 4.3419e+03 p0 3.7797e+03 e0 -9.72360e+02 tscale 0.01
38   fix 1 all msst y 100.0 q 1.0e5 mu 1.0e5 dftb yes beta 0.5
39
40Description
41"""""""""""
42
43This command performs the Multi-Scale Shock Technique (MSST)
44integration to update positions and velocities each timestep to mimic
45a compressive shock wave passing over the system. See :ref:`(Reed) <Reed>`
46for a detailed description of this method.  The MSST varies the cell
47volume and temperature in such a way as to restrain the system to the
48shock Hugoniot and the Rayleigh line. These restraints correspond to
49the macroscopic conservation laws dictated by a shock
50front. *shockvel* determines the steady shock velocity that will be
51simulated.
52
53To perform a simulation, choose a value of *q* that provides volume
54compression on the timescale of 100 fs to 1 ps.  If the volume is not
55compressing, either the shock speed is chosen to be below the material
56sound speed or *p0* has been chosen inaccurately.  Volume compression
57at the start can be sped up by using a non-zero value of *tscale*\ . Use
58the smallest value of *tscale* that results in compression.
59
60Under some special high-symmetry conditions, the pressure (volume)
61and/or temperature of the system may oscillate for many cycles even
62with an appropriate choice of mass-like parameter *q*\ . Such
63oscillations have physical significance in some cases.  The optional
64*mu* keyword adds an artificial viscosity that helps break the system
65symmetry to equilibrate to the shock Hugoniot and Rayleigh line more
66rapidly in such cases.
67
68The keyword *tscale* is a factor between 0 and 1 that determines what
69fraction of thermal kinetic energy is converted to compressive strain
70kinetic energy at the start of the simulation.  Setting this parameter
71to a non-zero value may assist in compression at the start of
72simulations where it is slow to occur.
73
74If keywords *e0*, *p0*,or *v0* are not supplied, these quantities will
75be calculated on the first step, after the energy specified by
76*tscale* is removed.  The value of *e0* is not used in the dynamical
77equations, but is used in calculating the deviation from the Hugoniot.
78
79The keyword *beta* is a scaling term that can be added to the MSST
80ionic equations of motion to account for drift in the conserved
81quantity during long timescale simulations, similar to a Berendsen
82thermostat. See :ref:`(Reed) <Reed>` and :ref:`(Goldman) <Goldman2>` for more
83details.  The value of *beta* must be between 0.0 and 1.0 inclusive.
84A value of 0.0 means no contribution, a value of 1.0 means a full
85contribution.
86
87Values of shockvel less than a critical value determined by the
88material response will not have compressive solutions. This will be
89reflected in lack of significant change of the volume in the MSST.
90
91For all pressure styles, the simulation box stays orthogonal in shape.
92Parrinello-Rahman boundary conditions (tilted box) are supported by
93LAMMPS, but are not implemented for MSST.
94
95This fix computes a temperature and pressure and potential energy each
96timestep. To do this, the fix creates its own computes of style "temp"
97"pressure", and "pe", as if these commands had been issued:
98
99.. code-block:: LAMMPS
100
101   compute fix-ID_MSST_temp all temp
102   compute fix-ID_MSST_press all pressure fix-ID_MSST_temp
103
104   compute fix-ID_MSST_pe all pe
105
106See the :doc:`compute temp <compute_temp>` and :doc:`compute pressure
107<compute_pressure>` commands for details.  Note that the IDs of the
108new computes are the fix-ID + "_MSST_temp" or "MSST_press" or
109"_MSST_pe".  The group for the new computes is "all".
110
111----------
112
113The *dftb* keyword is to allow this fix to be used when LAMMPS is
114being driven by DFTB+, a density-functional tight-binding code. If the
115keyword *dftb* is used with a value of *yes*, then the MSST equations
116are altered to account for the electron entropy contribution to the
117Hugonio relations and total energy.  See :ref:`(Reed2) <Reed2>` and
118:ref:`(Goldman) <Goldman2>` for details on this contribution.  In this case,
119you must define a :doc:`fix external <fix_external>` command in your
120input script, which is used to callback to DFTB+ during the LAMMPS
121timestepping.  DFTB+ will communicate its info to LAMMPS via that fix.
122
123----------
124
125Restart, fix_modify, output, run start/stop, minimize info
126"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
127
128This fix writes the state of all internal variables to :doc:`binary
129restart files <restart>`.  See the :doc:`read_restart <read_restart>`
130command for info on how to re-specify a fix in an input script that
131reads a restart file, so that the operation of the fix continues in an
132uninterrupted fashion.
133
134The cumulative energy change in the system imposed by this fix is
135included in the :doc:`thermodynamic output <thermo_style>` keywords
136*ecouple* and *econserve*.  See the :doc:`thermo_style <thermo_style>`
137doc page for details.
138
139This fix computes a global scalar which can be accessed by various
140:doc:`output commands <Howto_output>`.  The scalar is the same
141cumulative energy change due to this fix described in the previous
142paragraph.  The scalar value calculated by this fix is "extensive".
143
144The progress of the MSST can be monitored by printing the global
145scalar and global vector quantities computed by the fix.
146
147As mentioned above, the scalar is the cumulative energy change due to
148the fix.  By monitoring the thermodynamic *econserve* output, this can
149be used to test if the MD timestep is sufficiently small for accurate
150integration of the dynamic equations.
151
152The global vector contains four values in the following order.  The
153vector values output by this fix are "intensive".
154
155[\ *dhugoniot*, *drayleigh*, *lagrangian_speed*,
156*lagrangian_position*]
157
1581. *dhugoniot* is the departure from the Hugoniot (temperature units).
1592. *drayleigh* is the departure from the Rayleigh line (pressure units).
1603. *lagrangian_speed* is the laboratory-frame Lagrangian speed (particle velocity) of the computational cell (velocity units).
1614. *lagrangian_position* is the computational cell position in the reference frame moving at the shock speed. This is usually a good estimate of distance of the computational cell behind the shock front.
162
163To print these quantities to the log file with descriptive column
164headers, the following LAMMPS commands are suggested:
165
166.. code-block:: LAMMPS
167
168   fix              msst all msst z
169   variable dhug    equal f_msst[1]
170   variable dray    equal f_msst[2]
171   variable lgr_vel equal f_msst[3]
172   variable lgr_pos equal f_msst[4]
173   thermo_style     custom step temp ke pe lz pzz econserve v_dhug v_dray v_lgr_vel v_lgr_pos f_msst
174
175Restrictions
176""""""""""""
177
178This fix style is part of the SHOCK package.  It is only enabled if
179LAMMPS was built with that package. See the :doc:`Build package
180<Build_package>` page for more info.
181
182All cell dimensions must be periodic. This fix can not be used with a
183triclinic cell.  The MSST fix has been tested only for the group-ID
184all.
185
186Related commands
187""""""""""""""""
188
189:doc:`fix nphug <fix_nphug>`, :doc:`fix deform <fix_deform>`
190
191Default
192"""""""
193
194The keyword defaults are q = 10, mu = 0, tscale = 0.01, dftb = no,
195beta = 0.0.  Note that p0, v0, and e0 are calculated on the first
196timestep.
197
198----------
199
200.. _Reed:
201
202**(Reed)** Reed, Fried, and Joannopoulos, Phys. Rev. Lett., 90, 235503
203(2003).
204
205.. _Reed2:
206
207**(Reed2)** Reed, J. Phys. Chem. C, 116, 2205 (2012).
208
209.. _Goldman2:
210
211**(Goldman)** Goldman, Srinivasan, Hamel, Fried, Gaus, and Elstner,
212J. Phys. Chem. C, 117, 7885 (2013).
213