Livecoms reviewer comments

docs/sphinx/source/tutorial1/tutorial.rst

@@ -17,7 +17,7 @@ file **initial.lmp** in it, and open the file in the LAMMPS--GUI Editor window:
     # 1) Initialization
     # 2) System definition
     # 3) Settings
-    # 4) Visualization
+    # 4) Monitoring
     # 5) Run 
 
 .. admonition:: If you are not using LAMMPS-GUI
@@ -31,8 +31,8 @@ file **initial.lmp** in it, and open the file in the LAMMPS--GUI Editor window:
 Everything that appears after a hash symbol (#) is a comment
 and ignored by LAMMPS. These five categories are not required in every input script an do not
 necessarily need to be in that exact order.  For instance, the ``Settings``
-and the ``Visualization`` categories could be inverted, or
-the ``Visualization`` category could be omitted.  However, note that
+and the ``Monitoring`` categories could be inverted, or
+the ``Monitoring`` category could be omitted.  However, note that
 LAMMPS reads input files from top to bottom and processes each command
 *immediately*.  Therefore, the ``Initialization`` and
 ``System definition`` categories must appear at the top of the
@@ -61,6 +61,15 @@ so that the ``Initialization`` section appears as follows:
     atom_style atomic
     boundary p p p
 
+.. admonition:: Note
+    :class: non-title-info
+
+    Strictly speaking, none of the four commands specified in the
+    ``Initialization`` section are mandatory, as they correspond to the
+    default settings for their respective global properties.  However,
+    explicitly specifying these defaults is considered good practice to
+    avoid confusion when sharing input files with other LAMMPS users.
+
 The first line, ``units lj``, specifies the use of *reduced*  
 units, where all quantities are dimensionless.  This unit system is a  
 popular choice for simulations that explore general statistical  
@@ -86,19 +95,20 @@ slab geometries.
 .. admonition:: Note
     :class: non-title-info
 
-    Strictly speaking, none of the four commands specified in the
-    ``Initialization`` section are mandatory, as they correspond to the
-    default settings for their respective global properties.  However,
-    explicitly specifying these defaults is considered good practice to
-    avoid confusion when sharing input files with other LAMMPS users.
+    Each LAMMPS command is accompanied by extensive online |lammpsdocs|
+    that details the different options for that command.
+    From the LAMMPS--GUI editor buffer, you can access the documentation by  
+    right-clicking on a line containing a command (e.g., ``units lj``)  
+    and selecting ``View Documentation for `units'``.  This action  
+    should prompt your web browser to open the corresponding URL for the  
+    online manual.
 
-Each LAMMPS command is accompanied by extensive online |lammpsdocs|
-that details the different options for that command.
-From the LAMMPS--GUI editor buffer, you can access the documentation by  
-right-clicking on a line containing a command (e.g., ``units lj``)  
-and selecting ``View Documentation for `units'``.  This action  
-should prompt your web browser to open the corresponding URL for the  
-online manual.
+.. admonition:: Note
+    :class: non-title-info
+
+    Most LAMMPS commands have default settings that are applied if no value
+    is explicitly specified.  The defaults for each command are listed at the
+    bottom of its documentation page.
 
 .. |lammpsdocs| raw:: html
 
@@ -121,6 +131,9 @@ The first line, ``region simbox (...)``, defines a region named
 from -20 to 20 units along all three spatial dimensions.  The second  
 line, ``create_box 2 simbox``, initializes a simulation box based  
 on the region ``simbox`` and reserves space for two types of atoms.
+In LAMMPS, an atom *type* represents a group of atoms that
+interact using the same set of force field parameters (here, the Lennard-Jones
+parameters).
 
 .. admonition:: Note
     :class: non-title-info
@@ -132,8 +145,10 @@ on the region ``simbox`` and reserves space for two types of atoms.
     terminate with an error.
 
 The third line, ``create_atoms (...)``, generates 1500 atoms of  
-type 1 at random positions within the ``simbox`` region.  The  
-integer 34134 is a seed for the internal random number generator, which  
+type 1 at random positions within the ``simbox`` region.  Each atom created in
+LAMMPS is automatically assigned a unique atom ID, which serves as a numerical
+identifier to distinguish individual atoms throughout the simulation
+The integer 34134 is a seed for the internal random number generator, which  
 can be changed to produce different sequences of random numbers and,  
 consequently, different initial atom positions.  The fourth line adds  
 100 atoms of type 2.  Both ``create_atoms`` commands use the  
@@ -142,6 +157,13 @@ distance of 0.3 units between the randomly placed atoms.  This
 constraint helps avoid close contacts between atoms, which can lead  
 to excessively large forces and simulation instability.
 
+.. admonition:: Note
+    :class: non-title-info
+
+    Another way to define a system in LAMMPS, besides ``create_atoms``, is to
+    import an existing topology with ``read_data``, as shown
+    in :ref:`carbon-nanotube-label`.
+
 .. include:: ../shared/needhelp.rst
 
 Settings
@@ -189,19 +211,20 @@ of type 2, :math:`\epsilon_{22} = 0.5`, and :math:`\sigma_{22} = 3.0`.
     types using geometric average: :math:`\epsilon_{ij} = \sqrt{\epsilon_{ii} \epsilon_{jj}}`,
     :math:`\sigma_{ij} = \sqrt{\sigma_{ii} \sigma_{jj}}`.  In the present case,
     :math:`\epsilon_{12} = \sqrt{1.0 \times 0.5} = 0.707`, and
-    :math:`\sigma_{12} = \sqrt{1.0 \times 3.0} = 1.732`.
+    :math:`\sigma_{12} = \sqrt{1.0 \times 3.0} = 1.732`. Other rules
+    can be selected using the ``pair_modify`` command.
 
 Single-point energy
 -------------------
 
 The system is now fully parameterized, and the input is ready to compute
 forces.  Let us complete the two remaining categories,
-``Visualization`` and ``Run``, by adding the following lines
+``Monitoring`` and ``Run``, by adding the following lines
 to **initial.lmp**:
 
 .. code-block:: lammps
 
-    # 4) Visualization
+    # 4) Monitoring
     thermo 10
     thermo_style custom step etotal press
     # 5) Run
@@ -216,6 +239,12 @@ The ``run 0 post no`` command instructs LAMMPS to initialize forces and energy
 without actually running the simulation.  The ``post no`` option disables
 the post-run summary and statistics output.
 
+.. admonition:: Note
+    :class: non-title-info
+
+    The *thermodynamic information* printed by LAMMPS refers to instantaneous values
+    of thermodynamic properties at the specified steps, not cumulative averages.
+
 You can now run LAMMPS (basic commands for running LAMMPS
 are provided in :ref:`running-lammps-label`.
 The simulation should finish quickly.
@@ -274,7 +303,7 @@ initially positive potential energy is expected, as the atoms are
 created at random positions within the simulation box, with some in very
 close proximity to each other.  This proximity results in a large
 initial potential energy due to the repulsive branch of the
-Lennard-Jones potential [i.e., the term in :math:`1/r^{12}` in
+Lennard-Jones potential [i.e., the term :math:`1/r^{12}` in
 Eq. :eq:`eq_LJ`].  As the energy minimization progresses, the energy
 decreases - first rapidly - then more gradually, before plateauing at a
 negative value.  This indicates that the atoms have moved to reasonable
@@ -297,7 +326,7 @@ following lines immediately after the ``minimize`` command:
 .. code-block:: lammps
 
     # PART B - MOLECULAR DYNAMICS
-    # 4) Visualization
+    # 4) Monitoring
     thermo 50
     thermo_style custom step temp etotal pe ke press
 
@@ -311,7 +340,7 @@ command is introduced to specify the thermodynamic information LAMMPS should
 print during ``PART B``.  This adjustment is made because, during
 molecular dynamics, the system exhibits a non-zero temperature :math:`T` (and
 consequently a non-zero kinetic energy :math:`K`, keyword ``ke``), which are useful to monitor.
-The ``pe`` keyword represents the potential energy of the system, :math:`E`, such that
+The ``pe`` keyword represents the potential energy of the system, :math:`U`, such that
 :math:`U + K = E`.
 
 Then, add a second ``Run`` category by including the following
@@ -423,7 +452,7 @@ thermodynamic information.  To better follow the evolution of the system
 and visualize the trajectories of the atoms, let us print the positions
 of the atoms in a file at a regular interval.
 
-Add the following command to the ``Visualization`` section  
+Add the following command to the ``Monitoring`` section  
 of ``PART B`` of the **initial.lmp** file:
 
 .. code-block:: lammps
@@ -440,7 +469,7 @@ and adjust the visualization to your liking using the available buttons.
 Now you can copy the commands used to create this visualization to the  
 clipboard by either using the ``Ctrl-D`` keyboard shortcut or  
 selecting ``Copy dump image command`` from the ``File`` menu.  
-This text can be pasted into the ``Visualization`` section  
+This text can be pasted into the ``Monitoring`` section  
 of ``PART B`` of the **initial.lmp** file.  This may look like  
 the following:
 
@@ -496,7 +525,7 @@ commands in the ``System definition`` section:
     pair_style lj/cut 4.0
     pair_coeff 1 1 1.0 1.0
     pair_coeff 2 2 0.5 3.0
-    # 4) Visualization
+    # 4) Monitoring
     thermo 10
     thermo_style custom step etotal press
     # 5) Run
@@ -591,7 +620,7 @@ and **improved.min.lmp**:
     boundary p p p
     # 2) System definition
     # 3) Settings
-    # 4) Visualization
+    # 4) Monitoring
     # 5) Run
 
 Since we read most of the information from the data file, we don't need  
@@ -696,7 +725,7 @@ Finally, let us complete the script by adding the following lines to
 
 .. code-block:: lammps
 
-    # 4) Visualization
+    # 4) Monitoring
     thermo 1000
     thermo_style custom step temp pe ke etotal press v_n1_in v_n2_in c_sumcoor12
     dump viz all image 1000 myimage-*.ppm type type shiny 0.1 box no 0.01 view 0 0 zoom 1.8 fsaa yes size 800 800

docs/sphinx/source/tutorial2/tutorial.rst

@@ -357,6 +357,7 @@ from the typical dependency of bond energy with bond distance,
     The CNT starts deforming at :math:`t = 5\,\text{ps}`, and :math:`L_\text{cnt-0}` is the  
     CNT initial length.  b) Evolution of the total energy :math:`E` of the system with time :math:`t`.  
     Here, the potential is OPLS-AA, and the CNT is unbreakable.
+    The orange line shows the raw data, and the blue line represents a time-averaged curve.
 
 Importing YAML log file into Python
 -----------------------------------
@@ -400,6 +401,7 @@ the **unbreakable.yaml** file can then be used to plot the stress-strain curve.
     as a function of the strain, :math:`\Delta L_\text{cnt} = (L_\text{cnt}-L_\text{cnt-0})/L_\text{cnt-0}`,
     where :math:`L_\text{cnt}` is the CNT length and :math:`L_\text{cnt-0}` the CNT initial length.
     Here, the potential is OPLS-AA, and the CNT is unbreakable.
+    The orange line shows the raw data, and the blue line represents a time-averaged curve.
 
 Breakable bonds
 ===============
@@ -565,7 +567,8 @@ curve reveals a linear (elastic) regime where
     where :math:`F_\text{cnt}` is the force and :math:`A_\text{cnt}` the CNT surface area,
     as a function of the strain, :math:`\Delta L_\text{cnt} = (L_\text{cnt}-L_\text{cnt-0}/L_\text{cnt-0})`, where
     :math:`L_\text{cnt}` is the CNT length and :math:`L_\text{cnt-0}` the CNT initial length.
-    Here, the potential is AIREBO, and the CNT is breakable.
+    Here, the potential is AIREBO, and the CNT is breakable.  The orange line shows
+    the raw data, and the blue line represents a time-averaged curve.
 
 Tip: bonds representation with AIREBO
 -------------------------------------

docs/sphinx/source/tutorial3/tutorial.rst

@@ -35,7 +35,7 @@ angles, and dihedrals used in the simulation, here ``harmonic``.
 With the ``pair_style`` named ``lj/cut/coul/long``, atoms
 interact through both a Lennard-Jones (LJ) potential and Coulomb
 interactions.  The value of :math:`10\,\text{Å}` is the cutoff, and the
-``ewald`` command defines the long-range solver for the Coulomb
+``kspace_style`` command defines the long-range solver for the Coulomb
 interactions :cite:`ewald1921berechnung`.  Finally, the
 ``special_bonds`` command, which was already seen in
 :ref:`carbon-nanotube-label`, sets the LJ and Coulomb
@@ -163,30 +163,15 @@ Let us output the system into images by adding the following commands to **water
     acolor OW red acolor HW white &
     adiam OW 3 adiam HW 1.5
 
-Let us also extract the volume and density every 500 steps:
+Let us also extract the volume and density, among others, every 500 steps:
 
 .. code-block:: lammps
 
-    variable myvol equal vol
-    variable myoxy equal count(H2O)/3
-    variable NA equal 6.022e23
-    variable Atom equal 1e-10
-    variable M equal 0.018
-    variable rho equal ${myoxy}*${M}/(v_myvol*${NA}*${Atom}^3)
     thermo 500
-    thermo_style custom step temp etotal v_myvol v_rho
+    thermo_style custom step temp etotal volume density
 
-Here, several variables are defined and used for converting the units of the
-density in kg/mol:  The variable ``myoxy`` represents the number of
-atoms divided by 3,  which corresponds to the number of molecules, :math:`N_\text{H2O}`,
-and the variable ``myrho`` is the density in kg/mol:  
-
-.. math::
-
-    \rho = \dfrac{N_\text{H2O}}{V N_\text{A}},
-
-where :math:`V` is the volume in :math:`\text{m}^3`, :math:`N_\text{A}` the Avogadro number, and
-:math:`M = 0.018`\,kg/mol the molar mass of water.
+With the real units system, the volume is in :math:`Å^3`, and
+the density is in :math:`\text{g/cm}^3`.
 
 Finally, let us set the timestep to 1.0 fs, and run the simulation for 15 ps by
 adding the following lines into **water.lmp**:
@@ -315,10 +300,15 @@ the position :math:`(0, 0, 0)`:
 
     fix myrct PEG recenter 0 0 0 shift all
 
-Note that the ``recenter`` command has no impact on the dynamics,
-it simply repositions the frame of reference so that any drift of the
-system is ignored, which can be convenient for visualizing and analyzing
-the system.
+.. admonition:: Note
+    :class: non-title-info
+
+    Note that the ``recenter`` command has no impact on the dynamics,
+    it simply repositions the frame of reference so that any drift of the
+    system is ignored, which can be convenient for visualizing and analyzing
+    the system. However, be aware that using ``fix recenter`` can sometimes
+    mask underlying issues in the simulation, such as net momentum or the so-called
+    *flying ice cube syndrome* :cite:`wong2016good`.
 
 Let us create images of the systems:
 
@@ -418,7 +408,6 @@ constraints using the following commands:
 .. code-block:: lammps
 
     compute rgyr PEG gyration
-    compute prop PEG property/local dtype
     compute dphi PEG dihedral/local phi
 
 The radius of gyration can be directly printed with the ``thermo_style`` command:
@@ -427,7 +416,7 @@ The radius of gyration can be directly printed with the ``thermo_style`` command
 
     thermo_style custom step temp etotal c_rgyr
     thermo 250
-    dump mydmp all local 100 pull.dat index c_dphi c_prop
+    dump mydmp all local 100 pull.dat index c_dphi
 
 By contrast with the radius of gyration (compute ``rgyr``), the dihedral angle
 :math:`\phi` (compute ``dphi``) is returned as a vector by the ``compute dihedral/local``
@@ -514,11 +503,13 @@ named **pull.lammpstrj**, which can be opened in OVITO or VMD.
 .. admonition:: Note
     :class: non-title-info
 
-    Since the trajectory dump file does not contain information about
+    Since the default trajectory dump file does not contain information about
     topology and elements, it is usually preferred to first write out a
     data file and import it directly (in the case of OVITO) or convert it
     to a PSF file (for VMD).  This allows the topology to be loaded before
     *adding* the trajectory file to it.  When using LAMMPS--GUI,
     this process can be automated through the ``View in OVITO`` or
     ``View in VMD`` options in the ``Run`` menu.  Afterwards
-    only the trajectory dump needs to be added.
+    only the trajectory dump needs to be added.  Alternatively, the
+    ``dump custom`` command can be combined with ``dump`` command to
+    include element names in the dump file and simplify visualization.

docs/sphinx/source/tutorial4/tutorial.rst

@@ -35,6 +35,10 @@ These lines are used to define the most basic parameters, including the
 atom, bond, and angle styles, as well as interaction
 potential.  Here, ``lj/cut/tip4p/long`` imposes a Lennard-Jones potential with
 a cut-off at :math:`12\,\text{Å}` and a long-range Coulomb potential.
+The parameters ``O``, ``H``, ``O-H``, and ``H-O-H`` correspond
+respectively to the oxygens, hydrogens, O-H bonds, and H-O-H angle constraints of
+the water molecules; their definitions, provided by the ``labelmap`` commands,
+will be clarified below.
 
 .. include:: ../shared/needhelp.rst
 
@@ -168,7 +172,6 @@ must be located next to **create.lmp**. The **parameters.inc** file contains the
     mass Cl- 35.453
     mass WALL 26.9815
 
-
 Each ``mass`` command assigns a mass in g/mol to an atom type.
 The **parameters.inc** file also contains the pair coefficients:
 
@@ -190,10 +193,10 @@ types.  By default, LAMMPS calculates the pair coefficients for the
 interactions between atoms of different types (i and j) by using
 geometric average: :math:`\epsilon_{ij} = \sqrt{\epsilon_{ii} \epsilon_{jj}}`,
 :math:`\sigma_{ij} = \sqrt{\sigma_{ii} \sigma_{jj}}`.  However, if the default
-value of :math:`1.472\,\text{kcal/mol}` was used for :math:`\epsilon_\text{1-5}`,
+value of :math:`1.472\,\text{kcal/mol}` was used for :math:`\epsilon_\text{O-WALL}`,
 the solid walls would be extremely hydrophilic, causing the water
 molecules to form dense layers.  As a comparison, the water-water energy
-:math:`\epsilon_\text{1-1}` is only :math:`0.185199\,\text{kcal/mol}`.  Therefore,
+:math:`\epsilon_\text{O-O}` is only :math:`0.185199\,\text{kcal/mol}`.  Therefore,
 to make the walls less hydrophilic, the value of
 :math:`\epsilon_\text{O-WALL}` was reduced.
 
@@ -344,7 +347,7 @@ to **equilibrate.lmp**:
     thermo 1
     thermo_style custom step temp etotal press
 
-Let us perform an energy minization by adding the following lines to **equilibrate.lmp**:
+Let us perform an energy minimization by adding the following lines to **equilibrate.lmp**:
 
 .. code-block:: lammps
 
@@ -443,7 +446,8 @@ the end of the simulation.
 
     Figure: a) Pressure, :math:`p`, of the nanosheared electrolyte system as a function
     of the time, :math:`t`.  b) Distance between the walls, :math:`\Delta z`, as a
-    function of :math:`t`.
+    function of :math:`t`. The orange line shows the raw data, and the blue line
+    represents a time-averaged curve.
 
 Imposed shearing
 ----------------