updated docs and README files for examples

INSTALL.md

@@ -218,6 +218,8 @@ prerequisites can be installed using Homebrew (or XCODE).
 However the anaconda version of python and pip is also available for mac OS,
 and it may be more reliable than the python version
 included with XCODE or Homebrew.
+*(Note: BASH can be installed using 3rd-party tools like "brew"
+if it is not included with the operating system by default.)*
 
 ## WINDOWS installation suggestions
 

doc/moltemplate_manual_src/moltemplate_manual.tex

@@ -1583,7 +1583,7 @@ \subsection{Coordinate generation}
 wat3    = new SPCE.move(6.2068, 0.00, 0.00)
 wat4    = new SPCE.move(9.3102, 0.00, 0.00)
   :           :
-wat1000 = new SPCE.move(31.034, 31.034, 31.034)
+wat1000 = new SPCE.move(27.9306, 27.9306, 27.9306)
 \end{verbatim}
 Specifying geometry this way is tedious.
 Alternatively, moltemplate has simple commands for arranging multiple 
@@ -1739,11 +1739,13 @@ \subsection{Visualization using VMD \& topotools}
 read the short VMD tutorial in appendix \ref{sec:vmd_advanced}.
 
 \textit{(Note:
-As of 2019-9-03, 
+As of 2022-8-11,
 VMD does not have built-in support for exotic atom\_styles 
-such as ellipsoids and dipoles, but their are 3rd-party scripts, plugins 
-and settings you can use. Search the VMD and LAMMPS mailing lists 
-for help.})
+such as ellipsoids and dipoles.
+VMD also cannot be used to display simulations
+containing atoms or bonds which are created and destroyed.
+I recommend using OVITO \cite{OVITO}
+instead of VMD for these kinds of simulations.)}
 
 
 

examples/all_atom/force_field_AMBER/waterTIP3P+isobutane/README.md

@@ -3,12 +3,18 @@ Isobutane and water phase separation example
 A mixture of two small organic molecules using the *AMBER/GAFF* force field.  In this example, the water molecules were initially arranged in a rectangular lattice.  The isobutane molecules were also arranged in a lattice, and were shifted to avoid overlap with the water molecules. *(Alternatively, you can create a single lattice and specify the number of isobutane and water molecules you want in it using moltemplate's "new random([],[])" command, which is explained in [the manual](https://moltemplate.org/doc/moltemplate_manual.pdf#subsubsection.8.9.1).  This gives you more control over the concentration of each ingredient.  You can also use PACKMOL to create random mixtures of molecules.)*  The two types of molecules phase separate over the course of a few hundred ps.  The GAFF parameters are applied only to the isobutane molecule.  (The water molecule paramters are defined explicitly in the "force_fields/tip3p_2004.lt" file distributed with moltemplate.)
 
 
-#### Images
+### Images
 
 <img src="images/isobutane.jpg" width=110> <img src="images/plus.svg" height=80> <img src="images/water.jpg" width=110> <img src="images/rightarrow.svg" height=80> <img src="images/water+isobutane_t=0_LR.jpg" width=150> <img src="images/rightarrow.svg" height=80> <img src="images/water+isobutane_t=840ps_LR.jpg" width=150>
 
-The number of molecules, positions, and simulation box size can be controlled by editing the [system.lt file](moltemplate_files/system.lt).  The simulation contitions can be controlled by editing the [run.in.npt file](run.in.npt).
+### Video
+
+https://www.youtube.com/watch?v=yIX017PUCLs
+
 
+### Details
+
+The number of molecules, positions, and simulation box size can be controlled by editing the [system.lt file](moltemplate_files/system.lt).  The simulation contitions can be controlled by editing the [run.in.npt file](run.in.npt).
 
 ### *WARNING: The atomic charges in this examples are not correct*
 

examples/all_atom/force_field_OPLSAA/functionalized_nanotubes_NH2/README_visualize.txt

@@ -67,7 +67,14 @@ d) Try entering these commands:
 
     pbc wrap -sel type=1 -all -centersel type=2 -center com
 
-4) Optional: If you like, change the atom types in the PSF file so
+4)
+    You should check if your periodic boundary conditions are too small.
+    To do that:
+       select Graphics->Representations menu option
+       click on the "Periodic" tab, and
+       click on the "+x", "-x", "+y", "-y", "+z", "-z" checkboxes.
+
+5) Optional: If you like, change the atom types in the PSF file so
    that VMD recognizes the atom types, use something like:
 
 sed -e 's/   1    1      /   C    C      /g' < system.psf > temp1.psf

examples/all_atom/force_field_explicit_parameters/nanotube+water/README.md

@@ -5,15 +5,34 @@ Nanotube water capillary system
 
 <img src="images/graphene_unit_cell.jpg" width=110> <img src="images/rightarrow.svg" height=80> <img src="images/nanotube+walls_side_nopbc_LR.jpg" width=140> <img src="images/plus.svg" height=80> <img src="images/water_side_nopbc_LR.jpg" width=140> <img src="images/rightarrow.svg" height=80> <img src="images/nanotube+walls+water_side_pbc_t=0ps_LR.jpg" height=170> <img src="images/rightarrow.svg" height=80> <img src="images/nanotube+walls+water_side_pbc_t=305ps_LR.jpg" height=170>
 
+#### Video
+
+https://www.youtube.com/watch?v=U_-KUIuttfM
+
+
 ### Details
 
 This is a small version of a carbon-nanotube, water capillary system, inspired by this paper:
 [Laurent Joly, J. Chem. Phys. 135(21):214705 (2011)](https://doi.org/10.1063/1.3664622)
 
 To investigate the behavior from that paper, it might be a good idea to increase the size of the water reservoir, the spacing between the walls, and the size of the system in the X and Y directions.
 
+Note that there are two ways to run this simulation,
+at constant volume or at constant pressure.
+(In the video above the simulation was run at constant volume.)
+
+
 ### Requirements
-To run this system at constant pressure, it might help to compile LAMMPS with the optional RIGID package, and apply "fix rigid" on the carbon atoms. (The use of fix rigid for this purpose is controversial.  See the [run.in.npt](run.in.npt) file for more details.)  Running at NVT defintely does not require this.
+
+*To run this system at constant pressure,
+LAMMPS must be compiled with the "RIGID" package enabled.
+So if LAMMPS generates the following error:
+"rigid: Unknown fix", then you must follow
+[these instructions](https://lammps.sandia.gov/doc/Build_package.html),
+and recompile LAMMPS.
+(Running simulations containing immobile objects at constant pressure in
+LAMMPS is complicated.  See the "run.in.npt" file for details.)*
+
 
 ### Notes:
 

examples/all_atom/force_field_explicit_parameters/nanotube+water/README_visualize.txt

@@ -67,7 +67,14 @@ d) Try entering these commands:
 
     pbc wrap -sel type=1 -all -centersel type=2 -center com
 
-4) Optional: If you like, change the atom types in the PSF file so
+4)
+    You should check if your periodic boundary conditions are too small.
+    To do that:
+       select Graphics->Representations menu option
+       click on the "Periodic" tab, and
+       click on the "+x", "-x", "+y", "-y", "+z", "-z" checkboxes.
+
+5) Optional: If you like, change the atom types in the PSF file so
    that VMD recognizes the atom types, use something like:
 
 sed -e 's/   1    1      /   C    C      /g' < system.psf > temp1.psf

examples/coarse_grained/DNA_models/dsDNA_only/2strands/3bp_2particles/README.md

@@ -1,20 +1,24 @@
 3bp2p DNA model
 ===============
 
-### Warning: This is an unpublished DNA model
-
-This DNA example was intended to be used in a publication.
-We released these files to the public in order to accompany this publication,
-but that publication was indefinitely delayed.  However this DNA model has been
-[carefully parameterized](simple_dna_example/moltemplate_files/deriving_force_field_parameters)
+The moltemplate examples in this directory
+all use the "3bp2p" model
+(3 base-pairs per 2 beads)
+which has an explicit double-helical shape.
+This coarse-graind DNA model has been
+[parameterized](simple_dna_example/moltemplate_files/deriving_force_field_parameters)
 and
 [tested](simple_dna_example#features).
+It should be noted that there are much simpler
+coarse-graind DNA models available with
+similar mechanical properties.
+
+
+### Prerequisites
 
-If you want to use this model that's fine.
-If you feel like collaborating with us, that's great.
-But since I released the files by mistake, you are not obligated to do that.
-These files are impossible to retract.
-I just don't want to surprise you later if we publish a paper with
-this model later on.  (I'll post a link to it here when that happens.)
+LAMMPS must be compiled with the "MOLECULE" AND "EXTRA-MOLECULE"
+packages enabled.  If LAMMPS generates the following error:
+"dihedral_style spherical: Unknown dihedral style", then you must follow
+[these instructions](https://lammps.sandia.gov/doc/Build_package.html),
+and recompile LAMMPS.
 
--Andrew 2020-12-30

examples/coarse_grained/DNA_models/dsDNA_only/2strands/3bp_2particles/confined_viral_DNA/README.md

@@ -93,7 +93,8 @@ the group of atoms that is supplied to the integrator.  (For details, see
 
 ##    Prerequisites
 
-LAMMPS must be compiled with the "MOLECULE" AND "USER-MISC" packages enabled.
+LAMMPS must be compiled with the "MOLECULE" AND "EXTRA-MOLECULE"
+packages enabled.
 If you receive this error message (or something similar):
 "dihedral_style spherical: Unknown dihedral style", then you must follow
 [these instructions](https://lammps.sandia.gov/doc/Build_package.html),

examples/coarse_grained/DNA_models/dsDNA_only/2strands/3bp_2particles/simple_dna_example/README.md

@@ -32,8 +32,8 @@ Geometrical and mechanical properties of this DNA model (simulated at T=300K) ar
 
 ##    Prerequisites
 
-LAMMPS must be compiled with the "MOLECULE" AND "USER-MISC" packages enabled.
-If you receive this error message (or something similar):
+LAMMPS must be compiled with the "MOLECULE" AND "EXTRA-MOLECULE"
+packages enabled.  If LAMMPS generates the following error:
 "dihedral_style spherical: Unknown dihedral style", then you must follow
 [these instructions](https://lammps.sandia.gov/doc/Build_package.html),
 and recompile LAMMPS.

examples/coarse_grained/DNA_models/dsDNA_only/2strands/3bp_2particles/twist_motor_supercoiling/README.md

@@ -27,8 +27,11 @@ https://www.youtube.com/watch?v=xU2QzDDmuyA
 
 ##    Prerequisites
 
-LAMMPS must be compiled with the "MOLECULE" AND "USER-MISC" packages enabled.
-(https://lammps.sandia.gov/doc/Build_package.html)
+LAMMPS must be compiled with the "MOLECULE" AND "EXTRA-MOLECULE"
+packages enabled.  If LAMMPS generates the following error:
+"dihedral_style spherical: Unknown dihedral style", then you must follow
+[these instructions](https://lammps.sandia.gov/doc/Build_package.html),
+and recompile LAMMPS.
 
 It also requires that the "fix twist" feature has been enabled in LAMMPS.
 (As of 2019-5-05, you must download "fix_twist.cpp" and "fix_twist.h" from

examples/coarse_grained/DNA_models/dsDNA_only/twistable_Kratky-Porod/42bp_3particles/nucleoid_Ccrescentus_DNA_only/README.md

@@ -119,7 +119,7 @@ new feature of LAMMPS called "fix twist".  (See "prerequisites" section.)
 
 ## Prerequisites
 
-LAMMPS must be compiled with the "MOLECULE" AND "USER-MISC" packages enabled.
+LAMMPS must be compiled with the "MOLECULE" AND "EXTRA-PAIR" packages enabled.
 (https://docs.lammps.org/Build_package.html)
 
 It also requires that the "fix twist" feature has been enabled in LAMMPS.

examples/coarse_grained/DNA_models/dsDNA_only/twistable_Kratky-Porod/42bp_3particles/twist_motor_supercoiling/README.md

@@ -51,7 +51,7 @@ Note: The polymer shown in some of these videos ("3bp2p") is different than the
 
 ##    Prerequisites
 
-LAMMPS must be compiled with the "MOLECULE" AND "USER-MISC" packages enabled.
+LAMMPS must be compiled with the "MOLECULE" AND "EXTRA-PAIR" packages enabled.
 (https://docs.lammps.org/Build_package.html)
 
 It also requires that the "fix twist" feature has been enabled in LAMMPS.

examples/coarse_grained/membrane_examples/MARTINI_examples/DPPC_bilayer_formation_PACKMOL/README.md

@@ -5,6 +5,12 @@ This example of the formation of a coarse-grained DPPC lipid-bilayer uses the Ma
 ### Images
 <img src="images/DPPC_martini_LR.jpg" height=110> <img src="images/plus.svg" height=80> <img src="images/water_martini_LR.jpg" width=70> <img src="images/rightarrow.svg" height=80> <img src="images/t=0_after_minimization_LR.jpg" width=170> <img src="images/rightarrow.svg" height=80> <img src="images/t=6ns_300K_NPT_LR.jpg" width=170> <img src="images/rightarrow.svg" height=80> <img src="images/t=13ns_450K_NVT_LR.jpg" width=170> <img src="images/rightarrow.svg" height=80> <img src="images/t=26ns_300K_NPT_LR.jpg" width=170>
 
+#### Video
+
+https://www.youtube.com/watch?v=vi5mYiWJRzc
+
+### Details
+
 The simulation size and number of lipids and water molecules is specified in the [mix_lipids+water.inp](./packmol_files/mix_lipids+water.inp) and [system.lt](./moltemplate_files/system.lt) files.  (The numbers in these files must agree.)  The simulation contitions can be controlled by editing the [run.in.anneal](run.in.anneal) and [run.in.nvt](run.in.nvt) files.
 
 

examples/coarse_grained/simple_examples/2bead_heteropolymer/README.md

@@ -0,0 +1,33 @@
+2-bead Heteropolymer Example
+====================
+
+#### Images
+
+<img src="images/monomer_H.png" height=70> <img src="images/plus.svg" height=80>
+<img src="images/monomer_P.png" height=70> <img src="images/rightarrow.svg" height=80>
+<img src="images/polymer_LR.png" width=180> <img src="images/rightarrow.svg" height=80>
+
+<img src="images/trajectory.png" width=650>
+
+This directory contains an example of a couarse-grained (vaguely protein-like)
+heteropolymer consisting of 14 residues, each of which has 2 particles
+(one backbone bead, CA, one residue bead, R).
+There are 27 copies of this polymer in the simulation.
+
+There are two types of residues, H and P.
+The sidechain beads from the H residue
+are attracted to each other ("HR", orange).
+All other particles are repulsive.
+
+### Instructions 
+Instructions on how to build LAMMPS input files and
+run a short simulation are provided in other README files.
+
+#### Step 1) README_setup.sh
+This file explains how to use moltemplate.sh to build the files that
+LAMMPS needs.
+
+#### Step 2) README_run.sh
+This file explains how to use LAMMPS to run a simulation using the
+files you created in step 1.
+

examples/coarse_grained/simple_examples/2bead_polymer/README.md

@@ -0,0 +1,30 @@
+2-bead Heteropolymer Example
+====================
+
+#### Images
+
+<img src="images/2bead_monomer.jpg" height=70> <img src="images/rightarrow.svg" height=80>
+<img src="images/2bead_polymer_LR.jpg" height=70> <img src="images/rightarrow.svg" height=80>
+<img src="images/2bead_polymer_array3x3x3_LR.jpg" width=160> <img src="images/rightarrow.svg" height=80>
+<img src="images/2bead_t=4850000_LR.jpg" width=160>
+
+
+This directory contains an example of a couarse-grained (vaguely protein-like)
+heteropolymer consisting of 14 residues, each of which has 2 particles
+(one backbone bead, CA, one residue bead, R).
+The "R" beads are attracted to each other.
+There are 27 copies of this polymer in the simulation.
+
+
+### Instructions 
+Instructions on how to build LAMMPS input files and
+run a short simulation are provided in other README files.
+
+#### Step 1) README_setup.sh
+This file explains how to use moltemplate.sh to build the files that
+LAMMPS needs.
+
+#### Step 2) README_run.sh
+This file explains how to use LAMMPS to run a simulation using the
+files you created in step 1.
+