Skip to content

Commit fef22eb

Browse files
committed
ensured consistency of tutorial 1
1 parent 62b2de8 commit fef22eb

File tree

1 file changed

+60
-33
lines changed

1 file changed

+60
-33
lines changed

docs/sphinx/source/tutorial1/tutorial.rst

Lines changed: 60 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -117,6 +117,9 @@ slab geometries.
117117

118118
<a href="https://docs.lammps.org" target="_blank">documentation</a>
119119

120+
System definition
121+
-----------------
122+
120123
The next step is to create the simulation box and populate it with
121124
atoms. Modify the ``System definition`` category of
122125
**initial.lmp** as shown below:
@@ -134,14 +137,18 @@ The first line, ``region simbox (...)``, defines a region named
134137
from -20 to 20 units along all three spatial dimensions. The second
135138
line, ``create_box 2 simbox``, initializes a simulation box based
136139
on the region ``simbox`` and reserves space for two types of atoms.
137-
In LAMMPS, an atom *type* represents a group of atoms that
138-
interact using the same set of force field parameters (here, the Lennard-Jones
139-
parameters).
140+
In LAMMPS, every atom is assigned an atom type property. This property selects which force
141+
field parameters (here, the Lennard-Jones parameters, :math:`\epsilon_{ij}`
142+
and :math:`\sigma_{ij}`) are applied to each pair of atoms via the pair_coeff
143+
command (see below). We discuss in :ref:`carbon-nanotube-label` how this applies to
144+
many-body pair styles, and in :ref:`all-atoms-label` how this applies to
145+
Coulomb interactions.
140146

141147
.. admonition:: Note
142148
:class: non-title-info
143149

144-
From this point on, any command referencing an atom type larger than 2
150+
From this point on, the number of atom types is *locked
151+
in*, and any command referencing an atom type larger than 2
145152
will trigger an error. While it is possible to allocate more atom
146153
types than needed, you must assign a mass and provide force field
147154
parameters for each atom type. Failing to do so will cause LAMMPS to
@@ -154,14 +161,15 @@ can be changed to produce different sequences of random numbers and,
154161
consequently, different initial atom positions. The fourth line adds
155162
100 atoms of type 2. Both ``create_atoms`` commands use the
156163
optional argument ``overlap 0.3``, which enforces a minimum
157-
distance of 0.3 units between the randomly placed atoms. This
164+
distance of 0.3 length units between the randomly placed atoms. This
158165
constraint helps avoid close contacts between atoms, which can lead
159-
to excessively large forces and simulation instability. Each atom created in
160-
LAMMPS is automatically assigned a unique atom ID, which serves as a numerical
161-
identifier to distinguish individual atoms throughout the simulation.
162-
Atom IDs by default have the range from 1 to the total number of atoms,
163-
but this is not enforced. Deleting atoms, for example, causes *holes* in the list
164-
of atom IDs.
166+
to excessively large forces and simulation instability.
167+
Each created atom in LAMMPS is automatically
168+
assigned a unique atom ID, which serves as a numerical
169+
identifier to distinguish individual atoms throughout the
170+
simulation. Atom IDs by default have the range from 1 to
171+
the total number of atoms, but this is not enforced.Deleting atoms, for example,
172+
causes *holes* in the list of atom IDs.
165173

166174
.. admonition:: Note
167175
:class: non-title-info
@@ -204,19 +212,19 @@ to :math:`r_c = 4.0` length units :cite:`wang2020lennard,fischer2023history`:
204212
where :math:`r` is the inter-particle distance, :math:`\epsilon_{ij}` is
205213
the depth of the potential well that determines the interaction strength, and
206214
:math:`\sigma_{ij}` is the distance at which the potential energy equals zero.
207-
The indexes :math:`i` and :math:`j` refer to pairs of particle types.
215+
The indices :math:`i` and :math:`j` refer to pairs atoms with the corresponding atom types.
208216
The fourth line, ``pair_coeff 1 1 1.0 1.0``, specifies the
209217
Lennard-Jones coefficients for interactions between pairs of atoms
210-
of type 1: the energy parameter :math:`\epsilon_{11} = 1.0` and
218+
that both have atom type 1: the energy parameter :math:`\epsilon_{11} = 1.0` and
211219
the distance parameter :math:`\sigma_{11} = 1.0`. Similarly, the last line
212220
sets the Lennard-Jones coefficients for interactions between atoms
213221
of type 2, :math:`\epsilon_{22} = 0.5`, and :math:`\sigma_{22} = 3.0`.
214222

215223
.. admonition:: Note
216224
:class: non-title-info
217225

218-
By default, LAMMPS calculates the cross coefficients for different atom
219-
types using geometric average: :math:`\epsilon_{ij} = \sqrt{\epsilon_{ii} \epsilon_{jj}}`,
226+
By default, LAMMPS calculates the mixed force field coefficients for different
227+
atom types using geometric averages: :math:`\epsilon_{ij} = \sqrt{\epsilon_{ii} \epsilon_{jj}}`,
220228
:math:`\sigma_{ij} = \sqrt{\sigma_{ii} \sigma_{jj}}`. In the present case,
221229
:math:`\epsilon_{12} = \sqrt{1.0 \times 0.5} = 0.707`, and
222230
:math:`\sigma_{12} = \sqrt{1.0 \times 3.0} = 1.732`. Other rules
@@ -249,11 +257,16 @@ the post-run summary and statistics output.
249257
.. admonition:: Note
250258
:class: non-title-info
251259

252-
The *thermodynamic information* printed by LAMMPS refers to instantaneous values
253-
of thermodynamic properties at the specified steps, not cumulative averages.
260+
The *thermodynamic information* printed by LAMMPS
261+
using ``thermo_style custom`` keywords refers to instanta-
262+
neous values of the specified thermodynamic properties
263+
at each output step, not cumulative averages. However,
264+
LAMMPS also allows to reference a wide variety of custom data from
265+
compute styles, fix styles, and variables.
266+
These can be used for on-the-fly analysis, including cumulative and sliding-window averages.
254267

255268
You can now run LAMMPS (basic commands for running LAMMPS
256-
are provided in :ref:`running-lammps-label`.
269+
are provided in :ref:`running-lammps-label`).
257270
The simulation should finish quickly.
258271

259272
With the default settings, LAMMPS--GUI will open two windows: one
@@ -283,18 +296,19 @@ following ``minimize`` command:
283296
# 5) Run
284297
minimize 1.0e-6 1.0e-6 1000 10000
285298
286-
This tells LAMMPS to perform an energy minimization of the system.
299+
This tells LAMMPS to perform an iterative energy minimization of the system.
287300
Specifically, LAMMPS will compute the forces on all atoms and then update their
288301
positions according to a selected algorithm, aiming to reduce
289302
the potential energy. By default, LAMMPS uses the conjugate gradient (CG)
290303
algorithm :cite:`hestenes1952methods`. The simulation will stop as soon
291-
as the minimizer algorithm cannot find a way to lower the potential
292-
energy. Note that, except for trivial systems, minimization algorithms will find a
304+
as one of the four minimizer criteria is met. LAMMPS will then report which stopping criterion
305+
was satisfied, along with selected system properties at both the initial
306+
and final steps. Note that, except for trivial systems, minimization algorithms will find a
293307
local minimum rather than the global minimum.
294308

295309
Run the minimization and observe that LAMMPS-GUI captures the output
296310
and updates the chart in real time. This run executes quickly (depending
297-
on your computer's capabilities), but LAMMPS-GUI may fail to capture some
311+
on your computer's capabilities), and thus LAMMPS-GUI may fail to capture some
298312
of the thermodynamic data. In that
299313
case, use the ``Preferences`` dialog to reduce the data update
300314
interval and switch to single-threaded, unaccelerated execution in the
@@ -377,14 +391,14 @@ the value of the ``timestep`` and the number of steps for the
377391
this ensemble, the system does not exchange energy with anything
378392
outside the simulation box.
379393

380-
Run the simulation using LAMMPS. Initially, there is no equilibrium
381-
between potential and kinetic energy, as the potential energy
394+
Run the simulation using LAMMPS. Initially, the system is
395+
not equilibrated, as the potential energy
382396
decreases while the kinetic energy increases. After approximately
383397
40000 steps, the values for both kinetic and potential energy
384398
plateau, indicating that the system has reached equilibrium, with
385399
the total energy fluctuating around a certain constant value.
386400

387-
Now, we change the ``Run`` section to (note the smaller number of
401+
Now, we change the second ``Run`` section to (note the smaller number of
388402
MD steps):
389403

390404
.. code-block:: lammps
@@ -658,7 +672,7 @@ have noticed that some atoms left their original region during
658672
minimization. To start the simulation from a clean slate, with only
659673
atoms of type 2 inside the cylinder and atoms of type 1 outside the
660674
cylinder, let us delete the misplaced atoms by adding the following
661-
commands to **improved.md.lmp**:
675+
commands to the ``System definition`` category to **improved.md.lmp**:
662676

663677
.. code-block:: lammps
664678
@@ -743,13 +757,26 @@ in a ``thermo_style custom`` command (see below).
743757
.. admonition:: Note
744758
:class: non-title-info
745759

746-
LAMMPS ``compute`` commands can produce three kinds of data: scalars (single values),
747-
vectors (one-dimensional arrays), or arrays (two-dimensional tables).
748-
When referencing results of a compute, you can use indices: for example,
749-
``c\_mycompute`` refers to the entire scalar, vector, or array, and
750-
``c\_mycompute[1]`` refers to its first element (in case of vector or array).
751-
In general, *consumer* commands can only work with certain data types,
752-
check the documentation of each command to ensure compatibility.
760+
LAMMPS ``compute`` commands can produce
761+
a wide variety of data and one can identify the category from the
762+
name of the compute style: global data (no suffix), local data
763+
(/local suffix), per-atom data (/atom suffix), per-chunk data
764+
(/chunk suffix), per-gridpoint data (/grid suffix). In the example
765+
above, the ``compute coord/atom`` produces per-atom data, which
766+
is used as input for ``compute reduce`` which returns global
767+
data. For global data three kinds of data exists: scalars (single
768+
values), vectors (one-dimensional arrays), or arrays
769+
(two-dimensional tables). When referencing results of a compute,
770+
you can use indices: for example, ``c_mycompute`` refers to
771+
the entire scalar, vector, or array, and ``c_mycompute[1]``
772+
refers to its first element (in case of vector or array). In some
773+
cases also wildcards like "*" can be used to, for instance, refer to all elements
774+
of a vector instead of having specify all elements individually.
775+
In general, *consumer* commands (fix styles or dump styles,
776+
variables, or other compute styles) can only work with certain data
777+
types or need to have keywords set to select which data to use.
778+
You need to check the documentation of each command to ensure
779+
compatibility.
753780

754781
.. admonition:: Note
755782
:class: non-title-info

0 commit comments

Comments
 (0)