Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add orbital rotation documentation #4729

Merged
merged 6 commits into from
Sep 19, 2023
Merged

Add orbital rotation documentation #4729

Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
33be2d3
Add oribital rotation documentation
markdewing Sep 13, 2023
30f8cc2
Fix attribute on rotated_sposet
markdewing Sep 13, 2023
5554e51
Document opt_vars element
markdewing Sep 13, 2023
a6cef56
Merge branch 'develop' into orb_rot_doc
ye-luo Sep 13, 2023
fcd15cd
Tweak description
prckent Sep 14, 2023
26abc43
Merge branch 'develop' into orb_rot_doc
ye-luo Sep 19, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 56 additions & 0 deletions docs/intro_wavefunction.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -912,6 +912,62 @@ 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, orbital rotation can change the nodal structure and 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 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`` |
+-----------------+-----------------------+

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 id="rot_spo">
Copy link
Contributor

@ye-luo ye-luo Sep 13, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Prefer name to id.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also missing rotation matrix input in the example?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What are you referring to by 'rotation matrix input'? This input starts off with no initial rotation. The 'opt_vars' element is only for testing. I could document it, but I don't want to put it in the example.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think 'opt_vars' is development only unless loading rotation parameters from optimization parameter h5 is the only supported way. Let first document it but not added to the example considering it is optional.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think anyone needs to specify initial rotations this way unless it's for testing. For using the results of an optimization run, it's better to load the results from the h5 file.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Specifying initial rotations is likely needed for testing, so we need this. The docs can simply state that.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i'll 3rd the need to document explicit rotation via xml. Handling h5 can be cumbersome if one wants to do anything other than load in a previously optimized set of parameters. As others have pointed out, this is especially useful for testing, but should also be compatible with production calculations.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The rotations given via opt_vars have limitations. They can't describe a full rotation - they only apply to the 'active' rotations (the ones with non-zero parameter derivatives). An arbitrary rotation either needs the full rotation matrix (global method) or a list of rotations (history list method), and those don't work with opt_vars.
Expanding opt_vars or adding new tags to handle these cases would be possible. My preference would be the script route, though. It would help to have some more concrete ideas for production uses cases (e.g., preferred to have the original coefficient file + XML with global rotation to communicate an optimized wavefunction, versus a rotated coefficient file, versus the original coefficient file + HDF file with rotation information (how it works now))

Copy link
Contributor

@jptowns jptowns Sep 15, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wait now I am confused. Isn't opt_vars specifying (some but not all) elements of the kappa matrix from which U=exp(-kappa)? Or are you pointing out that in general you can't completely specify an arbitrary transformation with the current <opt_vars> implementation? The latter is ok, imo. I just want to be able to poke orbitals without touching scripts or hdf5 files. I agree in production you'd have to rely on a more robust approach.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, opt_vars is a subset of the elements of the kappa matrix. And you need all the (strictly triangular) entries to specify an arbitrary rotation, which opt_vars does not provide. opt_vars is good for providing an initial rotation that moves the coefficient matrix away from the minimum in order to test the optimizer.

<sposet name="spo" size="8">
...
</sposet>
</rotated_sposet>
</sposet_collection>
<determinantset>
<slaterdeterminant>
<determinant sposet="rot_spo"/>
<determinant sposet="rot_spo"/>
</slaterdeterminant>
</determinantset>

.. _backflow:

Backflow Wavefunctions
Expand Down