From da1be29278a7a9e623fdd76478cd572a789f77f5 Mon Sep 17 00:00:00 2001
From: "Steven J. Plimpton" <sjplimp@singsing.sandia.gov>
Date: Tue, 24 Jul 2018 14:31:55 -0600
Subject: [PATCH] 2nd try at incremental doc page reorg, Section_tools

---
 doc/src/Manual.txt |   4 +-
 doc/src/Tools.txt  | 527 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 529 insertions(+), 2 deletions(-)
 create mode 100644 doc/src/Tools.txt

diff --git a/doc/src/Manual.txt b/doc/src/Manual.txt
index e69797d9ec..d6d46570c1 100644
--- a/doc/src/Manual.txt
+++ b/doc/src/Manual.txt
@@ -116,7 +116,7 @@ it gives quick access to documentation for all LAMMPS commands.
    Section_howto
    Section_example
    Section_perf
-   Section_tools
+   Tools
    Section_modify
    Section_python
    Section_errors
@@ -210,7 +210,7 @@ END_RST -->
   6.27 "Drude induced dipoles"_howto_27 :ule,b
 "Example problems"_Section_example.html :l
 "Performance & scalability"_Section_perf.html :l
-"Additional tools"_Section_tools.html :l
+"Auxiliary tools"_Tools.html :l
 "Modifying & extending LAMMPS"_Section_modify.html :l
   10.1 "Atom styles"_mod_1 :ulb,b
   10.2 "Bond, angle, dihedral, improper potentials"_mod_2 :b
diff --git a/doc/src/Tools.txt b/doc/src/Tools.txt
new file mode 100644
index 0000000000..8fc371c4ef
--- /dev/null
+++ b/doc/src/Tools.txt
@@ -0,0 +1,527 @@
+"Previous Section"_Section_perf.html - "LAMMPS WWW Site"_lws - "LAMMPS
+Documentation"_ld - "LAMMPS Commands"_lc - "Next
+Section"_Section_modify.html :c
+
+<!-- future sequence of sections:
+"Previous Section"_Python.html - "LAMMPS WWW Site"_lws -
+"LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next
+Section"_Modify.html :c
+-->
+
+:link(lws,http://lammps.sandia.gov)
+:link(ld,Manual.html)
+:link(lc,Commands.html#comm)
+
+:line
+
+Auxiliary tools :h3
+
+LAMMPS is designed to be a computational kernel for performing
+molecular dynamics computations.  Additional pre- and post-processing
+steps are often necessary to setup and analyze a simulation.  A list
+of such tools can be found on the "LAMMPS webpage"_lws at these links:
+
+"Pre/Post processing"_http://lammps.sandia.gov/prepost.html
+"Offsite LAMMPS packages & tools"_http://lammps.sandia.gov/offsite.html
+"Pizza.py toolkit"_pizza :ul
+
+The last link for "Pizza.py"_pizza is a Python-based tool developed at
+Sandia which provides tools for doing setup, analysis, plotting, and
+visualization for LAMMPS simulations.
+
+"link(pizza,http://pizza.sandia.gov)
+:link(python,http://www.python.org)
+
+Additional tools included in the LAMMPS distribution are described on
+this page.
+
+Note that many users write their own setup or analysis tools or use
+other existing codes and convert their output to a LAMMPS input format
+or vice versa.  The tools listed here are included in the LAMMPS
+distribution as examples of auxiliary tools.  Some of them are not
+actively supported by the LAMMPS developers, as they were contributed
+by LAMMPS users.  If you have problems using them, we can direct you
+to the authors.
+
+The source code for each of these codes is in the tools sub-directory
+of the LAMMPS distribution.  There is a Makefile (which you may need
+to edit for your platform) which will build several of the tools which
+reside in that directory.  Most of them are larger packages in their
+own sub-directories with their own Makefiles and/or README files.
+
+"amber2lmp"_#amber
+"binary2txt"_#binary
+"ch2lmp"_#charmm
+"chain"_#chain
+"colvars"_#colvars
+"createatoms"_#createatoms
+"doxygen"_#doxygen
+"drude"_#drude
+"eam database"_#eamdb
+"eam generate"_#eamgn
+"eff"_#eff
+"emacs"_#emacs
+"fep"_#fep
+"i-pi"_#ipi
+"ipp"_#ipp
+"kate"_#kate
+"lmp2arc"_#arc
+"lmp2cfg"_#cfg
+"matlab"_#matlab
+"micelle2d"_#micelle
+"moltemplate"_#moltemplate
+"msi2lmp"_#msi
+"phonon"_#phonon
+"polybond"_#polybond
+"pymol_asphere"_#pymol
+"python"_#pythontools
+"reax"_#reax_tool
+"smd"_#smd
+"vim"_#vim
+"xmgrace"_#xmgrace :ul
+
+:line
+:line
+
+amber2lmp tool :h4,link(amber)
+
+The amber2lmp sub-directory contains two Python scripts for converting
+files back-and-forth between the AMBER MD code and LAMMPS.  See the
+README file in amber2lmp for more information.
+
+These tools were written by Keir Novik while he was at Queen Mary
+University of London.  Keir is no longer there and cannot support
+these tools which are out-of-date with respect to the current LAMMPS
+version (and maybe with respect to AMBER as well).  Since we don't use
+these tools at Sandia, you'll need to experiment with them and make
+necessary modifications yourself.
+
+:line
+
+binary2txt tool :h4,link(binary)
+
+The file binary2txt.cpp converts one or more binary LAMMPS dump file
+into ASCII text files.  The syntax for running the tool is
+
+binary2txt file1 file2 ... :pre
+
+which creates file1.txt, file2.txt, etc.  This tool must be compiled
+on a platform that can read the binary file created by a LAMMPS run,
+since binary files are not compatible across all platforms.
+
+:line
+
+ch2lmp tool :h4,link(charmm)
+
+The ch2lmp sub-directory contains tools for converting files
+back-and-forth between the CHARMM MD code and LAMMPS.
+
+They are intended to make it easy to use CHARMM as a builder and as a
+post-processor for LAMMPS. Using charmm2lammps.pl, you can convert a
+PDB file with associated CHARMM info, including CHARMM force field
+data, into its LAMMPS equivalent. Support for the CMAP correction of
+CHARMM22 and later is available as an option. This tool can also add
+solvent water molecules and Na+ or Cl- ions to the system.
+Using lammps2pdb.pl you can convert LAMMPS atom dumps into PDB files.
+
+See the README file in the ch2lmp sub-directory for more information.
+
+These tools were created by Pieter in't Veld (pjintve at sandia.gov)
+and Paul Crozier (pscrozi at sandia.gov) at Sandia.
+
+CMAP support added and tested by Xiaohu Hu (hux2 at ornl.gov) and
+Robert A. Latour (latourr at clemson.edu), David Hyde-Volpe, and
+Tigran Abramyan, (Clemson University) and
+Chris Lorenz (chris.lorenz at kcl.ac.uk), King's College London.
+
+:line
+
+chain tool :h4,link(chain)
+
+The file chain.f creates a LAMMPS data file containing bead-spring
+polymer chains and/or monomer solvent atoms.  It uses a text file
+containing chain definition parameters as an input.  The created
+chains and solvent atoms can strongly overlap, so LAMMPS needs to run
+the system initially with a "soft" pair potential to un-overlap it.
+The syntax for running the tool is
+
+chain < def.chain > data.file :pre
+
+See the def.chain or def.chain.ab files in the tools directory for
+examples of definition files.  This tool was used to create the
+system for the "chain benchmark"_Section_perf.html.
+
+:line
+
+colvars tools :h4,link(colvars)
+
+The colvars directory contains a collection of tools for postprocessing
+data produced by the colvars collective variable library.
+To compile the tools, edit the makefile for your system and run "make".
+
+Please report problems and issues the colvars library and its tools
+at: https://github.com/colvars/colvars/issues
+
+abf_integrate:
+
+MC-based integration of multidimensional free energy gradient
+Version 20110511
+
+Syntax: ./abf_integrate < filename > \[-n < nsteps >\] \[-t < temp >\] \[-m \[0|1\] (metadynamics)\] \[-h < hill_height >\] \[-f < variable_hill_factor >\] :pre
+
+The LAMMPS interface to the colvars collective variable library, as
+well as these tools, were created by Axel Kohlmeyer (akohlmey at
+gmail.com) at ICTP, Italy.
+
+:line
+
+createatoms tool :h4,link(createatoms)
+
+The tools/createatoms directory contains a Fortran program called
+createAtoms.f which can generate a variety of interesting crystal
+structures and geometries and output the resulting list of atom
+coordinates in LAMMPS or other formats.
+
+See the included Manual.pdf for details.
+
+The tool is authored by Xiaowang Zhou (Sandia), xzhou at sandia.gov.
+
+:line
+
+doxygen tool :h4,link(doxygen)
+
+The tools/doxygen directory contains a shell script called
+doxygen.sh which can generate a call graph and API lists using
+the "Doxygen software"_http://doxygen.org.
+
+See the included README file for details.
+
+The tool is authored by Nandor Tamaskovics, numericalfreedom at googlemail.com.
+
+:line
+
+drude tool :h4,link(drude)
+
+The tools/drude directory contains a Python script called
+polarizer.py which can add Drude oscillators to a LAMMPS
+data file in the required format.
+
+See the header of the polarizer.py file for details.
+
+The tool is authored by Agilio Padua and Alain Dequidt: agilio.padua
+at univ-bpclermont.fr, alain.dequidt at univ-bpclermont.fr
+
+:line
+
+eam database tool :h4,link(eamdb)
+
+The tools/eam_database directory contains a Fortran program that will
+generate EAM alloy setfl potential files for any combination of 16
+elements: Cu, Ag, Au, Ni, Pd, Pt, Al, Pb, Fe, Mo, Ta, W, Mg, Co, Ti,
+Zr.  The files can then be used with the "pair_style
+eam/alloy"_pair_eam.html command.
+
+The tool is authored by Xiaowang Zhou (Sandia), xzhou at sandia.gov,
+and is based on his paper:
+
+X. W. Zhou, R. A. Johnson, and H. N. G. Wadley, Phys. Rev. B, 69,
+144113 (2004).
+
+:line
+
+eam generate tool :h4,link(eamgn)
+
+The tools/eam_generate directory contains several one-file C programs
+that convert an analytic formula into a tabulated "embedded atom
+method (EAM)"_pair_eam.html setfl potential file.  The potentials they
+produce are in the potentials directory, and can be used with the
+"pair_style eam/alloy"_pair_eam.html command.
+
+The source files and potentials were provided by Gerolf Ziegenhain
+(gerolf at ziegenhain.com).
+
+:line
+
+eff tool :h4,link(eff)
+
+The tools/eff directory contains various scripts for generating
+structures and post-processing output for simulations using the
+electron force field (eFF).
+
+These tools were provided by Andres Jaramillo-Botero at CalTech
+(ajaramil at wag.caltech.edu).
+
+:line
+
+emacs tool :h4,link(emacs)
+
+The tools/emacs directory contains a Lips add-on file for Emacs that
+enables a lammps-mode for editing of input scripts when using Emacs,
+with various highlighting options setup.
+
+These tools were provided by Aidan Thompson at Sandia
+(athomps at sandia.gov).
+
+:line
+
+fep tool :h4,link(fep)
+
+The tools/fep directory contains Python scripts useful for
+post-processing results from performing free-energy perturbation
+simulations using the USER-FEP package.
+
+The scripts were contributed by Agilio Padua (Universite Blaise
+Pascal Clermont-Ferrand), agilio.padua at univ-bpclermont.fr.
+
+See README file in the tools/fep directory.
+
+:line
+
+i-pi tool :h4,link(ipi)
+
+The tools/i-pi directory contains a version of the i-PI package, with
+all the LAMMPS-unrelated files removed.  It is provided so that it can
+be used with the "fix ipi"_fix_ipi.html command to perform
+path-integral molecular dynamics (PIMD).
+
+The i-PI package was created and is maintained by Michele Ceriotti,
+michele.ceriotti at gmail.com, to interface to a variety of molecular
+dynamics codes.
+
+See the tools/i-pi/manual.pdf file for an overview of i-PI, and the
+"fix ipi"_fix_ipi.html doc page for further details on running PIMD
+calculations with LAMMPS.
+
+:line
+
+ipp tool :h4,link(ipp)
+
+The tools/ipp directory contains a Perl script ipp which can be used
+to facilitate the creation of a complicated file (say, a lammps input
+script or tools/createatoms input file) using a template file.
+
+ipp was created and is maintained by Reese Jones (Sandia), rjones at
+sandia.gov.
+
+See two examples in the tools/ipp directory.  One of them is for the
+tools/createatoms tool's input file.
+
+:line
+
+kate tool :h4,link(kate)
+
+The file in the tools/kate directory is an add-on to the Kate editor
+in the KDE suite that allow syntax highlighting of LAMMPS input
+scripts.  See the README.txt file for details.
+
+The file was provided by Alessandro Luigi Sellerio
+(alessandro.sellerio at ieni.cnr.it).
+
+:line
+
+lmp2arc tool :h4,link(arc)
+
+The lmp2arc sub-directory contains a tool for converting LAMMPS output
+files to the format for Accelrys' Insight MD code (formerly
+MSI/Biosym and its Discover MD code).  See the README file for more
+information.
+
+This tool was written by John Carpenter (Cray), Michael Peachey
+(Cray), and Steve Lustig (Dupont).  John is now at the Mayo Clinic
+(jec at mayo.edu), but still fields questions about the tool.
+
+This tool was updated for the current LAMMPS C++ version by Jeff
+Greathouse at Sandia (jagreat at sandia.gov).
+
+:line
+
+lmp2cfg tool :h4,link(cfg)
+
+The lmp2cfg sub-directory contains a tool for converting LAMMPS output
+files into a series of *.cfg files which can be read into the
+"AtomEye"_http://mt.seas.upenn.edu/Archive/Graphics/A visualizer.  See
+the README file for more information.
+
+This tool was written by Ara Kooser at Sandia (askoose at sandia.gov).
+
+:line
+
+matlab tool :h4,link(matlab)
+
+The matlab sub-directory contains several "MATLAB"_matlabhome scripts for
+post-processing LAMMPS output.  The scripts include readers for log
+and dump files, a reader for EAM potential files, and a converter that
+reads LAMMPS dump files and produces CFG files that can be visualized
+with the "AtomEye"_http://mt.seas.upenn.edu/Archive/Graphics/A
+visualizer.
+
+See the README.pdf file for more information.
+
+These scripts were written by Arun Subramaniyan at Purdue Univ
+(asubrama at purdue.edu).
+
+:link(matlabhome,http://www.mathworks.com)
+
+:line
+
+micelle2d tool :h4,link(micelle)
+
+The file micelle2d.f creates a LAMMPS data file containing short lipid
+chains in a monomer solution.  It uses a text file containing lipid
+definition parameters as an input.  The created molecules and solvent
+atoms can strongly overlap, so LAMMPS needs to run the system
+initially with a "soft" pair potential to un-overlap it.  The syntax
+for running the tool is
+
+micelle2d < def.micelle2d > data.file :pre
+
+See the def.micelle2d file in the tools directory for an example of a
+definition file.  This tool was used to create the system for the
+"micelle example"_Section_example.html.
+
+:line
+
+moltemplate tool :h4,link(moltemplate)
+
+The moltemplate sub-directory contains a Python-based tool for
+building molecular systems based on a text-file description, and
+creating LAMMPS data files that encode their molecular topology as
+lists of bonds, angles, dihedrals, etc.  See the README.TXT file for
+more information.
+
+This tool was written by Andrew Jewett (jewett.aij at gmail.com), who
+supports it.  It has its own WWW page at
+"http://moltemplate.org"_http://moltemplate.org.
+
+:line
+
+msi2lmp tool :h4,link(msi)
+
+The msi2lmp sub-directory contains a tool for creating LAMMPS template
+input and data files from BIOVIA's Materias Studio files (formerly Accelrys'
+Insight MD code, formerly MSI/Biosym and its Discover MD code).
+
+This tool was written by John Carpenter (Cray), Michael Peachey
+(Cray), and Steve Lustig (Dupont). Several people contributed changes
+to remove bugs and adapt its output to changes in LAMMPS.
+
+This tool has several known limitations and is no longer under active
+development, so there are no changes except for the occasional bugfix.
+
+See the README file in the tools/msi2lmp folder for more information.
+
+:line
+
+phonon tool :h4,link(phonon)
+
+The phonon sub-directory contains a post-processing tool useful for
+analyzing the output of the "fix phonon"_fix_phonon.html command in
+the USER-PHONON package.
+
+See the README file for instruction on building the tool and what
+library it needs.  And see the examples/USER/phonon directory
+for example problems that can be post-processed with this tool.
+
+This tool was written by Ling-Ti Kong at Shanghai Jiao Tong
+University.
+
+:line
+
+polybond tool :h4,link(polybond)
+
+The polybond sub-directory contains a Python-based tool useful for
+performing "programmable polymer bonding".  The Python file
+lmpsdata.py provides a "Lmpsdata" class with various methods which can
+be invoked by a user-written Python script to create data files with
+complex bonding topologies.
+
+See the Manual.pdf for details and example scripts.
+
+This tool was written by Zachary Kraus at Georgia Tech.
+
+:line
+
+pymol_asphere tool :h4,link(pymol)
+
+The pymol_asphere sub-directory contains a tool for converting a
+LAMMPS dump file that contains orientation info for ellipsoidal
+particles into an input file for the "PyMol visualization
+package"_pymolhome or its "open source variant"_pymolopen.
+
+:link(pymolhome,http://www.pymol.org)
+:link(pymolopen,http://sourceforge.net/scm/?type=svn&group_id=4546)
+
+Specifically, the tool triangulates the ellipsoids so they can be
+viewed as true ellipsoidal particles within PyMol.  See the README and
+examples directory within pymol_asphere for more information.
+
+This tool was written by Mike Brown at Sandia.
+
+:line
+
+python tool :h4,link(pythontools)
+
+The python sub-directory contains several Python scripts
+that perform common LAMMPS post-processing tasks, such as:
+
+extract thermodynamic info from a log file as columns of numbers
+plot two columns of thermodynamic info from a log file using GnuPlot
+sort the snapshots in a dump file by atom ID
+convert multiple "NEB"_neb.html dump files into one dump file for viz
+convert dump files into XYZ, CFG, or PDB format for viz by other packages :ul
+
+These are simple scripts built on "Pizza.py"_pizza modules.  See the
+README for more info on Pizza.py and how to use these scripts.
+
+:line
+
+reax tool :h4,link(reax_tool)
+
+The reax sub-directory contains stand-alond codes that can
+post-process the output of the "fix reax/bonds"_fix_reax_bonds.html
+command from a LAMMPS simulation using "ReaxFF"_pair_reax.html.  See
+the README.txt file for more info.
+
+These tools were written by Aidan Thompson at Sandia.
+
+:line
+
+smd tool :h4,link(smd)
+
+The smd sub-directory contains a C++ file dump2vtk_tris.cpp and
+Makefile which can be compiled and used to convert triangle output
+files created by the Smooth-Mach Dynamics (USER-SMD) package into a
+VTK-compatible unstructured grid file.  It could then be read in and
+visualized by VTK.
+
+See the header of dump2vtk.cpp for more details.
+
+This tool was written by the USER-SMD package author, Georg
+Ganzenmuller at the Fraunhofer-Institute for High-Speed Dynamics,
+Ernst Mach Institute in Germany (georg.ganzenmueller at emi.fhg.de).
+
+:line
+
+vim tool :h4,link(vim)
+
+The files in the tools/vim directory are add-ons to the VIM editor
+that allow easier editing of LAMMPS input scripts.  See the README.txt
+file for details.
+
+These files were provided by Gerolf Ziegenhain (gerolf at
+ziegenhain.com)
+
+:line
+
+xmgrace tool :h4,link(xmgrace)
+
+The files in the tools/xmgrace directory can be used to plot the
+thermodynamic data in LAMMPS log files via the xmgrace plotting
+package.  There are several tools in the directory that can be used in
+post-processing mode.  The lammpsplot.cpp file can be compiled and
+used to create plots from the current state of a running LAMMPS
+simulation.
+
+See the README file for details.
+
+These files were provided by Vikas Varshney (vv0210 at gmail.com)
-- 
GitLab