Merge pull request #4729 from markdewing/orb_rot_doc

Add orbital rotation documentation

docs/intro_wavefunction.rst

@@ -912,6 +912,68 @@ the associated CSF, and the excitation degree relative to the first determinant.
   scf    2022200000000000000000000000000000000000000000000000000000
   excitation degree  2
 
+.. _orbitalrotation:
+
+Orbital Rotation
+----------------
+Orbital rotation mixes orbitals between those occupied by electrons and those unoccupied by electrons.
+Because it changes the orbitals, a well-chosen optimized orbital rotation can improve the trial wavefunction for VMC,
+can change the nodal structure, and can potentially improve the fixed-node DMC energy.
+
+Combining orbitals is complicated by the need to maintain the normalization of the
+orbitals.
+A rotation matrix will preserve the normalization of the vectors in linear combinations.
+However the entries in a rotation matrix are not independent.
+A rotation matrix can alternatively be expressed as the matrix exponential of a skew-symmetric matrix.
+The entries in that skew-symmetric matrix are independent and can form an independent set of optimizable parameters.
+
+Optimizable orbitals are given in the input file by enclosing an SPO
+in an `rotated_sposet` element.  The `determinant` element `id` attribute should reference the name of the rotated sposet.
+
+The `rotated_sposet` element requires use of the updated `sposet_collection` style.
+
+``rotated_sposet`` element:
+
+.. _Table_rotated_sposet:
+.. table::
+
+     +-----------------+--------------------------+
+     | Parent elements | ``sposet_collection``    |
+     +-----------------+--------------------------+
+     | Child elements  | ``sposet``, ``opt_vars`` |
+     +-----------------+--------------------------+
+
+Attribute:
+
++-----------------+----------+----------+---------+-------------------------+
+| Name            | Datatype | Values   | Default | Description             |
++=================+==========+==========+=========+=========================+
+| ``name``        | Text     |          |         | Name of rotated SPOSet  |
++-----------------+----------+----------+---------+-------------------------+
+
+.. code-block::
+   :caption: Orbital Rotation XML element.
+   :name: Listing 1
+
+   <sposet_collection ...>
+     <rotated_sposet name="rot_spo">
+       <sposet name="spo" size="8">
+         ...
+       </sposet>
+     </rotated_sposet>
+   </sposet_collection>
+   <determinantset>
+     <slaterdeterminant>
+       <determinant sposet="rot_spo"/>
+       <determinant sposet="rot_spo"/>
+     </slaterdeterminant>
+   </determinantset>
+
+
+The `opt_vars` element can be used to specify initial rotation parameters.
+The parameters are given as a space-separated list of numbers in the element text.
+The length of this list must match the expected number of rotation parameters.
+
 .. _backflow:
 
 Backflow Wavefunctions