keep applying comments

Author: simongravelle

docs/sphinx/source/tutorial1/tutorial.rst

@@ -694,6 +694,14 @@ The equal-style ``variables`` are expressions evaluated
 during the run and return a number.  Here, they are defined to count  
 the number of atoms of a specific group within the ``cyl_in`` region.
 
+.. admonition:: Note
+    :class: non-title-info
+        
+    The ``n1_in`` and ``n2_in`` defined above are
+    equal-style variables, which evaluate a numerical expression using the
+    ``count()`` function.  Other common LAMMPS variable types include
+    atom-style, index, and loop.
+
 In addition to counting the atoms in each region, we will also extract  
 the coordination number of type 2 atoms around type 1 atoms.  The  
 coordination number measures the number of type 2 atoms near  
@@ -823,7 +831,7 @@ expected during mixing.  This can be observed using the entry
 
 ..  container:: figurelegend
 
-    Figure: a) Evolution of the numbers :math:`N_\text{1, in}$` and :math:`N_\text{2, in}` of atoms
+    Figure: a) Evolution of the numbers :math:`N_\text{1, in}` and :math:`N_\text{2, in}` of atoms
     of types 1 and 2, respectively, within the ``cyl_in`` region as functions
     of time :math:`t`.  b) Evolution of the coordination number :math:`C_{1-2}`
     (compute ``sumcoor12``) between atoms of types 1 and 2.

docs/sphinx/source/tutorial2/tutorial.rst

@@ -162,6 +162,13 @@ corresponding to the following: :math:`x < x_\text{min}` (``rbot``, for region
 bottom), :math:`x_\text{min} > x > x_\text{max}` (``rmid``, for region middle),  
 and :math:`x > x_\text{max}` (``rtop``, for region top).
 
+.. admonition:: Note
+    :class: non-title-info
+
+    So far, variables have been referenced dynamically during the run using
+    the ``v_`` prefix, which evaluates the variable as it evolves over time.
+    Here, a dollar sign ($) is used to reference the variable at the time the script is read.
+
 Finally, let us define 3 groups of atoms corresponding to the atoms
 in each of the 3 regions by adding to **unbreakable.lmp**
 just before the ``run 0`` command:

docs/sphinx/source/tutorial4/tutorial.rst

@@ -371,7 +371,7 @@ images of the system, you will notice that the atoms and molecules are moving to
 System equilibration
 --------------------
 
-Let us equilibrate further the entire system by letting both fluid and piston
+Let us equilibrate further the entire system by letting both fluid and wall
 relax at ambient temperature.  Here, the commands are written within the same
 **equilibrate.lmp** file, right after the ``reset_timestep`` command.
 
@@ -400,6 +400,14 @@ for the trajectory visualization:
 The ``undump`` command is used to cancel the previous ``dump`` command.
 Then, a new ``dump`` command with a larger dumping period is used.
 
+.. admonition:: Note
+    :class: non-title-info
+        
+    Just like the ``undump`` command can cancel an active ``dump``, other
+    objects defined in a LAMMPS input script can be cancelled when no longer needed. 
+    For example, you can use ``unfix`` to remove a previously defined ``fix``, and
+    ``uncompute`` to delete a ``compute``.
+
 To monitor the system equilibration, let us print the distance between
 the two walls.  Add the following lines to **equilibrate.lmp**:
 
@@ -527,7 +535,10 @@ The ``setforce`` commands cancel the forces on ``walltop`` and
 ``wallbot``.  As a result, the atoms in these two groups will not
 experience any forces from the rest of the system.  Consequently, in the absence of
 external forces, these atoms will conserve the initial velocities imposed by the
-two ``velocity`` commands.
+two ``velocity`` commands.  As seen previously, although the
+forces on these atoms are set to zero, the ``fix setforce`` still stores the
+forces acting on the group before cancellation, which can later be extracted
+for analysis (see below).
 
 Finally, let us generate images of the systems and print the values of the
 forces exerted by the fluid on the walls, as given by ``f_mysf1[1]``
@@ -544,8 +555,9 @@ and ``f_mysf2[1]``.  Add these lines to **shearing.lmp**:
     thermo_style custom step temp etotal f_mysf1[1] f_mysf2[1]
 
 Let us also extract the density and velocity profiles using
-the ``chunk/atom`` and ``ave/chunk`` commands.  These commands are
-used to divide the system into bins and return the desired quantities, here the velocity
+the ``chunk/atom`` and ``ave/chunk`` commands.  These
+commands discretize the simulation domain into spatial bins and compute and output
+average properties of the atoms belonging to each bin, here the velocity
 along :math:`x` (``vx``) within the bins.  Add the following lines to **shearing.lmp**:
 
 .. code-block:: lammps

docs/sphinx/source/tutorial5/tutorial.rst

@@ -30,8 +30,9 @@ and a **.data** file is imported by the ``read_data`` command.
 .. include:: ../shared/needhelp.rst
 
 The initial topology given by |silica_data_5|
-is a small amorphous silica structure.  This structure was created using a force field called
-Vashishta :cite:`vashishta1990interaction`.  If you open the **silica.data**
+is a small amorphous silica structure.  This structure was generated in a prior
+simulation using the Vashishta force field :cite:`vashishta1990interaction`.
+If you open the **silica.data**
 file, you will find in the ``Atoms`` section that all silicon atoms have a
 charge of :math:`q = 1.1\,\text{e}`, and all oxygen atoms have a charge of :math:`q = -0.55\,\text{e}`.
 
@@ -66,6 +67,15 @@ low and the high cutoffs, respectively, and :math:`1.0 \text{e} -6` is the toler
 i.e., the precision to which the atomic charges are equilibrated during the
 charge equilibration process.
 
+.. admonition:: Note
+    :class: non-title-info
+        
+    The ``pair_style reaxff`` command optionally accepts a control file,
+    which defines control variables such as
+    global parameters of the ReaxFF potential, as well as performance and output settings. 
+    If no control file is provided, as in this tutorial, LAMMPS uses its default values,
+    which correspond to those in Adri van Duin's original stand-alone ReaxFF code :cite:`van2001reaxff`.
+
 The ``maxiter`` sets an upper limit to the number of attempts to
 equilibrate the charge.
 
@@ -121,6 +131,13 @@ We can generate histograms of the charges for each atom type using
     fix myhis1 grpSi ave/histo 10 500 5000 -1.5 2.5 1000 v_vq file relax-Si.histo mode vector
     fix myhis2 grpO ave/histo 10 500 5000 -1.5 2.5 1000 v_vq file relax-O.histo mode vector
 
+The ``fix ave/histo`` command samples values
+over a group of atoms and builds a histogram over a specified range divided into
+bins.  In this tutorial, it is used to monitor the charge distributions
+of silicon and oxygen atoms.  The parameters ``10 500 5000`` specify how often
+the histogram is updated and averaged, ``-1.5 2.5`` set the value range, 
+``1000`` is the number of bins, and ``v\_vq`` is the variable being histogrammed.
+
 We can also use the ``fix reaxff/species`` to evaluate what species are
 present within the simulation.  It will be useful later when the system is deformed,
 and bonds are broken:
@@ -143,6 +160,13 @@ density of the system:
 
     write_data relax.data
 
+.. admonition:: Note
+    :class: non-title-info
+
+    With the `aniso` keyword, the three dimensions of the simulation
+    box can change independently.  This is particularly relevant for solids and other
+    systems where anisotropic stresses may develop.
+
 Run the **relax.lmp** file using LAMMPS.  As seen from **relax.species**,
 only one species is detected, called ``O384Si192``, representing the entire system.
 
@@ -246,7 +270,7 @@ Nosé-Hoover thermostat without a barostat:
     timestep 0.5
 
 Here, no barostat is used because the change in the box volume will be imposed
-by the ``fix deform``.
+by the ``fix deform``, see below.
 
 Let us run for 5000 steps without deformation, then apply the ``fix deform``
 to progressively elongate the box along the :math:`x`-axis during 25000 steps.  Add
@@ -262,6 +286,10 @@ the following line to **deform.lmp**:
 
     write_data deform.data
 
+The ``fix deform`` command applies a continuous deformation
+by elongating the simulation box along the x-axis at a constant engineering
+shear strain rate, specified by ``erate``, of :math:`5 \times 10^{-5}~\text{fs}^{-1}`.
+
 Run the **deform.lmp** file using LAMMPS.  During the deformation, the charge
 values progressively evolve until the structure eventually breaks down.  After the
 structure breaks down, the charges equilibrate near new average values that differ

docs/sphinx/source/tutorial6/introduction.rst

@@ -15,6 +15,6 @@ grand canonical Monte Carlo simulations to compute the adsorption of water
 molecules in cracked silica material.  This tutorial
 illustrates the use of the grand canonical ensemble in molecular simulation, an
 open ensemble where the number of atoms or molecules in the simulation box can vary.
-By employing the grand canonical ensemble, we will set the chemical
-potential of water within a nanoporous :math:`\text{SiO}_2` structure.
+By employing the grand canonical ensemble, we simulate water in a nanoporous
+:math:`\text{SiO}_2` structure at a specified chemical potential.
 

docs/sphinx/source/tutorial6/tutorial.rst

@@ -122,7 +122,7 @@ generally suitable for a solid phase.
 
 Run the simulation using LAMMPS.  From the ``Charts`` window, the temperature
 evolution can be observed, showing that it closely follows the desired annealing procedure.
-The evolution of the box dimensions over time confirms that the box deformed during the
+The evolution of the box dimensions over time confirms that the box is deforming during the
 last stage of the simulation.  After the simulation completes, the final LAMMPS topology
 file called **generate.data** will be located next to **generate.lmp**.
 
@@ -184,12 +184,20 @@ the **cracking.lmp** file:
 
     write_data cracking.data
 
-The ``fix nvt`` command is employed to control the temperature of the system.
+The ``fix nvt`` command integrates the Nosé-Hoover equations
+of motion and is employed to control the temperature of the system.
 As observed from the generated images, the atoms
 progressively adjust to the changing box dimensions.  At some point,
 bonds begin to break, leading to the appearance of
 dislocations.
 
+.. admonition:: Note
+    :class: non-title-info
+
+    Although the Nosé-Hoover equations were originally formulated to sample the
+    NVT ensemble, using the ``fix nvt`` command does not guarantee that 
+    a simulation actually samples the NVT ensemble.
+
 .. figure:: figures/cracked-dark.png
     :class: only-dark
     :alt: Amorphous cracked silica block
@@ -418,9 +426,15 @@ Carlo steps.  Add the following lines into **gcmc.lmp**:
     variable tfac equal 5.0/3.0
     fix fgcmc H2O gcmc 100 100 0 0 65899 300 -0.5 0.1 mol h2omol tfac_insert ${tfac} shake shak full_energy pressure 100
 
+The ``fix gcmc`` command performs grand canonical Monte Carlo
+moves to insert, delete, or swap molecules. Here, 100 attempts are made every
+100 steps.  The ``mol h2omol`` keyword specifies the
+molecule type being inserted/deleted, while ``shake shak`` enforces rigid
+molecular constraints during these moves. With the ``pressure 100`` keyword,
+a fictitious reservoir with a pressure of 100 atmospheres is used.
 The ``tfac_insert`` option ensures the correct estimate for the temperature
 of the inserted water molecules by taking into account the internal degrees of
-freedom.  Here, 100 insertion and deletion attemps are made every 100 steps.
+freedom.
 
 .. admonition:: Note
     :class: non-title-info
@@ -439,6 +453,9 @@ Finally, let us print some information and run for 25 ps:
 
     run 25000
 
+The ``f_`` keywords extract the Monte Carlo move statistics output by the
+``fix gcmc`` command.
+
 .. admonition:: Note
     :class: non-title-info
 

docs/sphinx/source/tutorial7/tutorial.rst

@@ -84,6 +84,12 @@ following lines to **free-sampling.lmp**:
     mass * 39.95
     pair_coeff * * ${epsilon} ${sigma}
 
+.. admonition:: Note
+    :class: non-title-info
+
+    In the ``pair_coeff`` command, the first two asterisks
+    ``* *`` indicate that the parameters apply to all atom types in the simulation.
+
 The variables :math:`U_0`, :math:`\delta`, and :math:`x_0`, defined in the previous subsection, are
 used here to create the repulsive potential, restricting the atoms from exploring
 the center of the box:
@@ -215,6 +221,10 @@ Add the following line to **free-sampling.lmp**:
 
     run 2000000
 
+Here, the ``chunk/atom`` command discretizes the simulation
+domain into spatial bins of size 2~\AA{} along the :math:`x` direction,
+and the ``ave/chunk`` command computes and outputs the number density of
+atoms within each bin to the file **free-sampling.dat**.}
 The step count is reset to 0 using ``reset_timestep`` to synchronize it
 with the output times of ``fix density/number``.  Run the simulation using
 LAMMPS.

docs/sphinx/source/tutorial8/introduction.rst

@@ -16,4 +16,6 @@ protocol is used to simulate the polymerization of styrene monomers, and the
 polymerization reaction is tracked over time :cite:`gissinger2017polymer,
 gissinger2020reacter, gissinger2024molecular`. In contrast to AIREBO
 :ref:`carbon-nanotube-label` and ReaxFF :ref:`reactive-silicon-dioxide-label`,
-the REACTER protocol relies on the use of a *classical* force field.
+the REACTER protocol relies on the use of a *classical* force field
+that does not inherently model bond formation or breaking, but instead couples
+with an external algorithm to simulate polymerization reactions.

docs/sphinx/source/tutorial8/tutorial.rst

@@ -24,6 +24,8 @@ following content corresponding to **mixing.lmp**:
 The ``class2`` styles compute a 6/9 Lennard-Jones potential :cite:`sun1998compass`.
 The ``class2`` bond, angle, dihedral, and improper styles are used as
 well, see the documentation for a description of their respective potentials.
+The ``tail yes`` option adds long-range van der Waals tail corrections to the
+energy and pressure.
 The ``mix sixthpower`` imposes the following mixing rule for the calculation
 of the cross coefficients:
 
@@ -279,6 +281,13 @@ based on the atom map **M-M.rxnmap**.  Implementation details about each reactio
 such as the reaction distance cutoffs and the frequency with which to search for
 reaction sties, are also specified in this command.
 
+.. admonition:: Note
+    :class: non-title-info
+
+    The ``fix nve/limit`` command Newton's equations of motion
+    while limiting the maximum displacement of atoms per timestep.  This is
+    useful for preventing atoms from moving too far due to large forces.
+
 .. figure:: figures/REACT-composite-dm.png
     :class: only-dark
     :alt: Evolution of reacting species