Add documentation of the structure builder

Describe the parameter file, starting geometries, planar and linear
molecules, symmetry (operations, point groups, inference of missing
atoms), the standard orientation of the result, the command line and
Python interfaces, and common problems. The examples are files under
docs/examples that are built by a test.

AI-assisted

Author: Krzmbrzl

README.md

@@ -10,6 +10,8 @@ This repository is structured in the following way:
   instructions.
 - `scripts`: This directory contains Python scripts that can be executed themselves to perform specific tasks. Some of these scripts may depend on the
   `koehnlab` package, so make sure you have set it up correctly.
+- `docs`: This directory contains documentation of the more involved tools, for example the [structure builder](docs/structure_builder.md) that
+  generates XYZ files from structure parameters.
 - `tests`: This directory contains (unit) tests for the provided functionality. You are encouraged to write test cases for your code to ensure that it
   works correctly and future changes won't break things. See the respective [README](tests/README.md) for more information on that.
 

docs/README.md

@@ -0,0 +1,5 @@
+# Documentation
+
+- [Structure builder](structure_builder.md): generating XYZ structures from bond lengths, angles and dihedral angles (including
+  planar/linear molecules, symmetry and the standard orientation of the result). The example files used in the documentation are in
+  [`examples/`](examples).

docs/examples/ammonia.txt

@@ -0,0 +1,8 @@
+# Ammonia (C3v). Only one N-H bond and one H-N-H angle are given, the others are equivalent by symmetry.
+N1 - H1 1.01
+N1 - H2
+N1 - H3
+H1 - N1 - H2 106.7
+
+@symmetry C3(z): H1->H2->H3      # rotation by 120 degrees about z moves H1 to H2, H2 to H3 and H3 to H1
+@symmetry sigma(y): H2<->H3      # mirror plane xz exchanges H2 and H3 (N and H1 stay where they are)

docs/examples/benzyne.txt

@@ -0,0 +1,22 @@
+# Benzyne (C2v, planar). C1 and C2 are the two dehydro carbons.
+# With @planar (or --planar) the molecule lies in the xy plane. The C2 axis (through the middle of C1-C2 and of C4-C5)
+# is the y axis, and the mirror plane perpendicular to the molecule is the yz plane (normal x).
+@planar
+
+C1 - C2 1.27067
+C2 - C3 1.39887
+C3 - C4 1.41259
+C4 - C5 1.41751
+C5 - C6                  # ring bonds without a value: equivalent to C3-C4 and C2-C3 by symmetry
+C6 - C1
+C3 - H1 1.09239
+C4 - H2 1.09507
+C5 - H3
+C6 - H4
+C1 - C2 - C3 126.41
+C2 - C3 - H1 126.37
+C3 - C4 - H2 118.85
+
+# Only the atoms that are exchanged are given, "..." lets the program infer the rest from the bonds
+@symmetry C2(y): C1<->C2, C3<->C6, ...
+@symmetry sigma(x): C1<->C2, C3<->C6, ...

docs/examples/butadiene.txt

@@ -0,0 +1,17 @@
+# trans-1,3-butadiene: planar, with the dihedral angle between the double bonds
+@planar
+
+C1 - C2 1.34          # double bonds
+C3 - C4 1.34
+C2 - C3 1.46          # single bond
+C1 - C2 - C3 123.5
+C2 - C3 - C4 123.5
+C1 - C2 - C3 - C4 180
+
+# hydrogens (connectivity only: their positions follow from the defaults)
+C1 - H1
+C1 - H2
+C2 - H3
+C3 - H4
+C4 - H5
+C4 - H6

docs/examples/co2.txt

@@ -0,0 +1,4 @@
+# Carbon dioxide: linear
+@linear
+O1 - C1 1.16
+C1 - O2 1.16

docs/examples/ethane_d3d.txt

@@ -0,0 +1,8 @@
+# Staggered ethane (D3d), to be used together with ethane_guess.xyz:
+#   build_structure.py -i ethane_d3d.txt -g ethane_guess.xyz -o ethane.xyz
+# Three parameters determine the whole molecule.
+C1 - C2 1.53
+C1 - H1 1.09
+H1 - C1 - C2 111
+
+@group D3d       # all symmetry operations of D3d; the starting geometry tells which atoms they exchange

docs/examples/ethane_guess.xyz

@@ -0,0 +1,10 @@
+8
+Rough staggered ethane in the standard frame of D3d (C3 axis along z, C2 axes along x); the labels are used by the parameter file
+C1  0.000000  0.000000  0.765000
+C2  0.000000  0.000000 -0.765000
+H1  0.883346  0.510000  1.160000
+H2 -0.883346  0.510000  1.160000
+H3  0.000000 -1.020000  1.160000
+H4  0.000000  1.020000 -1.160000
+H5 -0.883346 -0.510000 -1.160000
+H6  0.883346 -0.510000 -1.160000

docs/examples/water.txt

@@ -0,0 +1,4 @@
+# Water: two bond lengths and the angle between them
+O1 - H1 0.96
+O1 - H2 0.96
+H1 - O1 - H2 104.5