added documentation for amber2lt.py

doc/doc_amber2lt.md

@@ -0,0 +1,119 @@
+amber2lt.py
+===========
+
+*amber2lt.py* is a program for converting AMBER FRCMOD and DAT files
+into moltemplate (LT) file format.
+
+## *WARNING: ALPHA SOFTWARE. THIS SOFTWARE IS EXPERIMENTAL AS OF 2022-8-24*
+
+
+## Usage:
+
+```
+amber2lt.py \
+  --in AMBER_FILE \
+  --name FORCE_FIELD_NAME \
+  [--out MOLTEMPLATE_FILE.lt]
+```
+
+## Examples
+
+### Example 1
+
+Convert the GAFF force field from a file named "gaff.dat"
+into moltemplate format ("gaff.lt")
+
+```
+amber2lt.py --in gaff.dat --name GAFF --out gaff.lt
+```
+
+### Example 2:
+
+Convert an FRCMOD file generated by AmberTools named "benzene.frcmod"
+into moltemplate format:
+
+```
+amber2lt.py --in benzene.frcmod --name MY_FORCE_FIELD >> my_force_field.lt
+```
+
+
+
+
+## Arguments
+
+
+### --in AMBER_FILE
+
+Specify the name of the AMBER force-field file you want to convert
+(eg. "gaff.dat" or "benzene.frcmod").
+*If omitted, the terminal (stdin) is used by default.*
+
+
+### --out MOLTEMPLATE_FILE.lt
+
+Specify the name of the moltemplate file (LT file) you want to create.
+(eg. "gaff.lt").
+*If omitted, the terminal (stdout) is used by default.*
+
+
+### --name FORCE_FIELD_NAME
+
+The name of force field you want to create.
+(This is not necessarily the same as the file name containing the force field.)
+Suppose the name of the force field is "GAFF".  Later on, when you define
+molecules that use this force field, you will refer to it this way
+"MoleculeName inherits GAFF {..."
+
+## Optional Arguments
+
+AMBER .DAT and FRCMOD files are divided into multiple sections containing
+mass, bond, angle, dihedral, improper, and nonbonded (pair) interactions.
+Unfortunately, available documentation describing the file format
+is somewhat ambiguous about where these sections begin and end.
+The "amber2lt.py" attempts to guess where each section is,
+however it sometimes fails.  When this happens, the conversion will fail.
+You can get around this problem by manually dividing the original file
+into seperate files containing only the lines of text that are relevant
+for that section.  Then you can pass these files individually to
+the *amber2lt.py* program using the following arguments:
+
+### --mass mass.txt
+### --bond bond.txt
+### --angle angle.txt
+### --dihedral dihedral.txt
+### --improper improper.txt
+### --pair pair.txt
+
+Once you have specified the text in these files, the "amber2lt.py"
+usually succeeds in the conversion.
+Each file must not contain any blank lines or irrelevant text.
+
+*Note that if you supply one of these arguments, you must supply all of them.*
+
+
+## Python API
+
+It is possible to access the functionality of *amber2lt.py* from 
+within python.  Example:
+
+```python
+import moltemplate
+# Open the file you want to convert
+with open('gaff.dat', 'r') as file_in:
+    lines_in = file_in.readlines()
+# Now create a new moltemplate file
+lines_out = ConvertAmber2Lt(object_name, lines_in)
+# Write the contents of the new file
+with open('gaff.lt', 'w') as file_out:
+    file_out.write(''.join(output_lines))
+# Alternatively, if you have loaded each section of the the AMBER file into
+# different lists of lines (eg "lines_mass", "lines_bond", ...)
+# then you can do the conversion this way:
+# lines_out = ConvertAmberSections2Lt(object_name,
+#                                     lines_mass,
+#                                     lines_bond,
+#                                     lines_angle,
+#                                     lines_dihedral,
+#                                     lines_improper,
+#                                     lines_pair)
+```