Read/write LAMMPS molecule templates

doc/index.html

@@ -53,9 +53,11 @@
       <ul class="goog-toc" style="list-style: none;">
         <li class="goog-toc"><a href="#TOC-readlammpsdata-file-name-atom-style"><strong>4.1 </strong>readlammpsdata &lt;file name&gt; [&lt;atom style&gt;]</a></li>
         <li class="goog-toc"><a href="#TOC-writelammpsdata-file-name-atom-styl"><strong>4.2 </strong>writelammpsdata &lt;file name&gt; [typelabels] [&lt;atom style&gt;]</a></li>
-        <li class="goog-toc"><a href="#TOC-readvarxyz-file-name-"><strong>4.3 </strong>readvarxyz &lt;file name&gt;</a></li>
-        <li class="goog-toc"><a href="#TOC-writevarxyz-file-name-selmod-sel-fi"><strong>4.4 </strong>writevarxyz &lt;file name&gt; [selmod &lt;sel&gt;] [first|last|step &lt;frame]</a></li>
-        <li class="goog-toc"><a href="#TOC-writegmxtop-file-name-"><strong>4.5 </strong>writegmxtop &lt;file name&gt;</a></li>
+        <li class="goog-toc"><a href="#TOC-readlammpsmol-file-name"><strong>4.3 </strong>readlammpsmol &lt;file name&gt; </a></li>
+        <li class="goog-toc"><a href="#TOC-writelammpsmol-file-name"><strong>4.4 </strong>writelammpsmol &lt;file name&gt; [typelabels]</a></li>
+        <li class="goog-toc"><a href="#TOC-readvarxyz-file-name-"><strong>4.5 </strong>readvarxyz &lt;file name&gt; [first|last|step &lt;frame] </a></li>
+        <li class="goog-toc"><a href="#TOC-writevarxyz-file-name-selmod-sel-fi"><strong>4.6 </strong>writevarxyz &lt;file name&gt; [selmod &lt;sel&gt;] [first|last|step &lt;frame]</a></li>
+        <li class="goog-toc"><a href="#TOC-writegmxtop-file-name-"><strong>4.7 </strong>writegmxtop &lt;file name&gt;</a></li>
       </ul>
     </li>
     <li class="goog-toc"><a href="#TOC-Utility-Functions"><strong>5 </strong>Utility Functions</a>
@@ -100,10 +102,7 @@ <h3><a name="TOC-Scope-and-usage"></a>Scope and usage</h3>
       larger systems by replicating a given unitcell.</p>
 
 <h3><a name="TOC-Version"></a>Version</h3>
-<p align="justify">This documentation describes version 1.10 of the topotools plugin.
-This is the final version of this plugin unless a new maintainer is found. If you
-are interested in maintaining TopoTools, please contact the original author,
-Axel Kohlmeyer via email. </p>
+<p align="justify">This documentation describes the version of the topotools plugin that is displayed in the title.</p>
 <h3><a name="TOC-Main-command-interface"></a>Main command interface</h3>
 <p align="justify">This is the <i>middleware</i> part of the package that provides abstract operations on top of the low-level API. This is modeled after the example of the internal <code>mol</code> or <code>molinfo</code> commands, or the <code>pbc</code> command from the PBCTools package to provide a somewhat consistent interface to the functionality. All command lines start with the <tt>topo</tt> keyword and then take a subcommand name to determine the actual functionality that is requested.</p>
 <div class="sites-codeblock sites-codesnippet-block"><code>topo &lt;command&gt; [args...] &lt;flags&gt;</code></div>
@@ -208,7 +207,11 @@ <h4><a name="TOC-readlammpsdata-file-name-atom-style"></a>readlammpsdata &lt;fil
 <p align="justify">Read in atom coordinates, properties, bond, angle, dihedral and other related topology info from a <a href="https://docs.lammps.org/read_data.html" target="_blank" rel="nofollow">LAMMPS</a> data file, i.e. a file suitable for the <code>read_data</code> command. This can be used to check a data file for its validity, for manipulations from within VMD, or to generate a .psf file to be used for visualization of <code>.dcd</code> or <code>.xtc</code> format trajectory files in VMD. The 'atom style' is the value given to the <code>atom_style</code> command in the LAMMPS input file (by default TopoTools will try to infer the atom style from information embedded in the data file as comments; if no such hints are present, it will use 'full'). This subcommand creates a new molecule in VMD and returns its molecule id or -1 in case of failure. The -sel parameter is currently ignored.</p>
 <h4><a name="TOC-writelammpsdata-file-name-atom-styl"></a>writelammpsdata &lt;file name&gt; [typelabels] [&lt;atom style&gt;]</h4>
 <p align="justify">Write out atom coordinates, properties, bond, angle, dihedral and other related topology info stored inside VMD to a <a href="https://docs.lammps.org/read_data.html" target="_blank" rel="nofollow">LAMMPS</a> data file, i.e. a file suitable for the <code>read_data</code> command. Using the optional 'typelabels' flag will trigger writing a data file with typelabel support requiring LAMMPS version 15Sep2022 or later.  By default a traditional data file with numerical types will be written.  This this way VMD can be used to build LAMMPS input with Tcl scripting and convert existing inputs from other MD codes to be used in LAMMPS. For some examples, please see the <a href="https://sites.google.com/site/akohlmey/software/topotools/tutorial-introduction">TopoTools tutorials</a>. The 'atom style' is the value you want to give to the <code>atom_style</code> command in the LAMMPS input file (default is 'full'). Only data that is present will be written and non-zero box sizes are required.</p>
-<h4><a name="TOC-readvarxyz-file-name-"></a>readvarxyz &lt;file name&gt;</h4>
+<h4><a name="TOC-readlammpsmol-file-name"></a>readlammpsmol &lt;file name&gt; </h4>
+<p align="justify">Read in atom coordinates, properties, bond, angle, dihedral and other related topology info from a <a href="https://docs.lammps.org/molecule.html" target="_blank" rel="nofollow">LAMMPS</a> molecule template file, i.e. a file suitable for the <code>molecule</code> command. This can be used to check a molecule template for its validity (e.g. for fixes that utilize molecule templates), or for manipulations from within VMD. This subcommand creates a new molecule in VMD and returns its molecule id or -1 in case of failure. The -sel parameter is currently ignored.</p>
+<h4><a name="TOC-writelammpsmol-file-name"></a>writelammpsmol &lt;file name&gt; [typelabels]</h4>
+<p align="justify">Write out atom coordinates, properties, bond, angle, dihedral and other related topology info stored inside VMD to a <a href="https://docs.lammps.org/molecule.html" target="_blank" rel="nofollow">LAMMPS</a> molecule template file, i.e. a file suitable for the <code>molecule</code> command. Using the optional 'typelabels' flag will trigger writing a molecule template file with typelabel support requiring LAMMPS version 15Sep2022 or later. By default a traditional molecule template with numerical types will be written. This way VMD can be used to build LAMMPS input with Tcl scripting and convert existing inputs from other MD codes to be used in LAMMPS. Only data that is present will be written.</p>
+<h4><a name="TOC-readvarxyz-file-name-"></a>readvarxyz &lt;file name&gt; [first|last|step &lt;frame]</h4>
 <p align="justify">Read in an xyz-format trajectory file (in xmol style) with a varying number of atoms per frame. This format is normally not supported in VMD and the script circumvents the restriction by automatically adding a sufficient number of dummy particles. Whether an atom is actually present in a given frame or not is flagged by the value of the corresponding <code>user</code> field, which is set to either <code>1.0</code> or <code>-1.0</code>, respectively. For efficiency reasons the atoms are sorted by type, thus atom order and bonding is not preserved. This subcommand creates a new molecule and returns its molecule id or -1, in case of failure.</p>
 <h4><a name="TOC-writevarxyz-file-name-selmod-sel-fi"></a>writevarxyz &lt;file name&gt; [selmod &lt;sel&gt;] [first|last|step &lt;frame]</h4>
 <div>Write out an xyz-format trajectory file with a varying number of atoms per frame. This is the counterpart to the readvarxyz subcommand. The optional selection string defines how atoms for each frame have to be selected. If not given, as selection string of "user &gt; 0" is assumed.</div>