LCPQ/quantum_package
10
0
Fork 0
mirror of https://github.com/LCPQ/quantum_package synced 2024-06-02 11:25:26 +02:00
Code Issues Releases Wiki Activity

Working on doc

Browse Source
This commit is contained in:
Anthony Scemama 2018-11-23 18:01:22 +01:00
parent 1ac2423571
commit b8d97dc5a5
12 changed files with 235 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/source/_static/links.rst
View File

@ -63,8 +63,12 @@
.. |MRCC| replace:: :abbr:`MRCC (Multi-Reference Coupled Cluster)`
.. |MRPT| replace:: :abbr:`MRPT (Multi-Reference Perturbation Theory)`
.. |PT2| replace:: :abbr:`PT2 (Second order perturbative correction)`
.. |QMC| replace:: :abbr:`QMC (Quantum Monte Carlo)`
.. |SCF| replace:: :abbr:`SCF (Self Consistent Field)`
.. |CASSCF| replace:: |CAS| - |SCF|
.. |FCIQMC| replace:: |FCI| - |QMC|
.. |kalpha| replace:: :math:`|\alpha \rangle`
.. |H| replace:: :math:`\hat H`
.. |Psi| replace:: :math:`|\Psi \rangle`
.. |S^2| replace:: :math:`\widehat{S^2}`

6
docs/source/index.rst
View File

@ -22,13 +22,11 @@
:hidden:
users_guide/quickstart
users_guide/configure
users_guide/interfaces
users_guide/qp_*
users_guide/excited_states
users_guide/natural_orbitals
users_guide/plugins
users_guide/excited_states
users_guide/interfaces
users_guide/index

6
docs/source/modules/determinants.rst
View File

@ -15,19 +15,19 @@ Contains everything for the computation of the Hamiltonian in the basis of Slate
EZFIO parameters
----------------
.. option:: N_det_max
.. option:: n_det_max
Maximum number of determinants in the wave function
Default: 1000000
.. option:: N_det_max_full
.. option:: n_det_max_full
Maximum number of determinants where |H| is fully diagonalized
Default: 1000
.. option:: N_states
.. option:: n_states
Number of states to consider

95
docs/source/modules/fci.rst
View File

@ -10,7 +10,9 @@ FCI
Selected Full Configuration Interaction.
The program start with a single determinant, or with the wave function in the |EZFIO| database if :option:`determinants read_wf` is |true|. Then, it will iteratively:
The :command:`FCI` program starts with a single determinant, or with the wave
function in the |EZFIO| database if :option:`determinants read_wf` is |true|.
Then, it will iteratively:
* Select the most important determinants from the external space and add them to the
internal space
@ -23,13 +25,98 @@ The program start with a single determinant, or with the wave function in the |E
The number of selected determinants at each iteration will be such that the
size of the wave function will double at every iteration.
size of the wave function will double at every iteration. If :option:`determinants
s2_eig` is |true|, then the number of selected determinants will be 1.5x the
current number, and then all the additional determinants will be added.
By default, the program will stop when more than one million determinants have
been selected, or when the |PT2| energy is below :math:`10^{-4}`.
The variational and |PT2| energies of the iterations are stored in the
|EZFIO| database, in the :ref:`IterativeSave` module.
Computation of the |PT2| energy
-------------------------------
At each iteration, the |PT2| energy is computed considering the Epstein-Nesbet
zeroth-order Hamiltonian:
.. math::
E_{\text{PT2}} = \sum_{ \alpha }
\frac{|\langle \Psi_S | \hat{H} | \alpha \rangle|^2}
{E - |\langle \alpha | \hat{H} | \alpha \rangle}
where the |kalpha| determinants are generated by applying all the single and
double excitation operators to all the determinants of the wave function
:math:`\Psi_G`.
When the hybrid-deterministic/stochastic algorithm is chosen
(default), :math:`Psi_G = \Psi_S = \Psi`, the full wavefunction expanded in the
internal space.
When the deterministic algorithm is chosen (:option:`perturbation do_pt2`
is set to |false|), :math:`Psi_G` is a truncation of |Psi| using
:option:`determinants threshold_generators`, and :math:`Psi_S` is a truncation
of |Psi| using :option:`determinants threshold_selectors`, and re-weighted
by :math:`1/\langle \Psi_s | \Psi_s \rangle`.
At every iteration, while computing the |PT2|, the variance of the wave
function is also computed:
.. math::
\sigma^2 & = \langle \Psi | \hat{H}^2 | \Psi \rangle -
\langle \Psi | \hat{H} | \Psi \rangle^2 \\
& = \sum_{i \in \text{FCI}}
\langle \Psi | \hat{H} | i \rangle
\langle i | \hat{H} | \Psi \rangle -
\langle \Psi | \hat{H} | \Psi \rangle^2 \\
& = \sum_{ \alpha }
\langle |\Psi | \hat{H} | \alpha \rangle|^2.
The expression of the variance is the same as the expression of the |PT2|, with
a denominator of 1. It measures how far the wave function is from the |FCI|
solution. Note that the absence of denominator in the Heat-Bath selected |CI|
method is selection method by minimization of the variance, whereas |CIPSI| is
a selection method by minimization of the energy.
If :option:`perturbation do_pt2` is set to |false|, then the stochastic
|PT2| is not computed, and an approximate value is obtained from the |CIPSI|
selection. The calculation is faster, but the extrapolated |FCI| value is
less accurate. This way of running the code should be used when the only
goal is to generate a wave function, as for using |CIPSI| wave functions as
trial wave functions of |QMC| calculations for example.
The :command:`PT2` program reads the wave function of the |EZFIO| database
and computes the energy and the |PT2| contribution.
State-averaging
---------------
Extrapolated |FCI| energy
-------------------------
An estimate of the |FCI| energy is computed by extrapolating
.. math::
E=E_\text{FCI} - \alpha\, E_\text{PT2}
This extrapolation is done for all the requested states, and excitation
energies are printed as energy differences between the extrapolated
energies of the excited states and the extrapolated energy of the ground
state.
The extrapolations are given considering the 2 last points, the 3 last points, ...,
the 7 last points. The extrapolated value should be chosen such that the extrpolated
value is stable with the number of points.
EZFIO parameters

4
docs/source/modules/perturbation.rst
View File

@ -80,7 +80,7 @@ EZFIO parameters
Default: True
.. option:: PT2_max
.. option:: pt2_max
The selection process stops when the largest |PT2| (for all the state) is lower
@ -88,7 +88,7 @@ EZFIO parameters
Default: 0.0001
.. option:: PT2_relative_error
.. option:: pt2_relative_error
Stop stochastic |PT2| when the relative error is smaller than `PT2_relative_error`

40
docs/source/users_guide/excited_states.rst
View File

@ -1,33 +1,29 @@
Excited states
==============
.. TODO
It is possible to run excited states calculations with the quantum package. To
do this, set the ``n_states`` variable in the ``Determinants`` section to the
number of requested states. The selection criterion will be the maximum of the
selection criteria for each state. If the Davidson diagonalization has
difficulties to converge, increase the ``n_states_diag`` variable in the
``Davidson`` section.
do this, set :option:`determinants n_states` to the number of requested states.
The selection criterion will be the maximum of the selection criteria for each
state. If the Davidson diagonalization has difficulties to converge, increase
the :option:`davidson n_states_diag` value.
When computing multiple states, it is good to have the ``s2_eig`` flag of the
``Determinants`` section set to ``true``. This will force the Davidson algorithm to
choose only vectors with a value of S^2 equal to the ``expected_s2``.
When computing multiple states, it is good to have the :option:`determinants
s2_eig` flag |true|. This will force the Davidson algorithm to choose only
vectors with a value of |S^2| equal to :option:`determinants expected_s2`.
Otherwise, different spin states will come out in the diagonalization.
The Quantum Package doesn't take account of the symmetry. Due to numerical
noise, excited states of different symmetries may enter in the calculation.
Note that it is possible to make state-average calculation of states with
different symmetries and/or different spin multiplicities.
The |qp| doesn't take account of the symmetry. Due to numerical noise, excited
states of different symmetries may enter in the calculation. Note that it is
possible to make state-average calculation of states with different symmetries
and/or different spin multiplicities.
To include excited state of all possible symmetries, a simple trick is to
run a preliminary multi-state CIS calculation, and then running the selected
FCI restarting from the CIS states, setting the ``read_wf`` flag of the
``Determinants`` section to ``true``.
To include excited state of all possible symmetries, a simple trick is to
run a preliminary multi-state |CIS| calculation using the :ref:`CIS` program,
and then running the selected |FCI| restarting from the |CIS| states, setting
:option:`determinants read_wf` to |true|.
Usually, it is good practice to use state-averaged MOs so that all states have
MOs of comparable quality. For example, when searching for a singly excited
state, one can use state-average natural orbitals of a preliminary CIS
calculation.
Usually, it is good practice to use state-averaged natural |MOs| so that all
states have |MOs| of comparable quality. This allows for a faster convergence
of excitation energies.

11
docs/source/users_guide/index.rst Normal file
View File

@ -0,0 +1,11 @@
Index of commands
=================
.. toctree::
:maxdepth: 1
:glob:
configure
qp_*

15
docs/source/users_guide/interfaces.rst
View File

@ -9,8 +9,8 @@ A few interfaces to external codes are available.
----------
`GAMESS`_ / Gaussian
Using the resultsFile Python library, the geometr and molecular orbitals can be read.
This is useful to make calculations with CAS-SCF orbitals
Using the |resultsFile| Python library, the geometry and |MOs| can be read.
This is useful to make calculations with |CASSCF| orbitals
|qp| -> \*
----------
@ -19,11 +19,12 @@ A few interfaces to external codes are available.
3D plots of Molecular Orbitals
FCIDUMP
Interface with the FCI-QMC program `NECI`_, or the semi-stochastic Heat-Bath CI
program `Dice`_.
Interface with the |FCI| - |QMC| program `NECI`_, or the semi-stochastic
Heat-Bath |CI| program `Dice`_.
`QMCPack`_ / `CHAMP <https://www.utwente.nl/en/tnw/ccp/research/CHAMP.html>`_ / `QMC=Chem`_
Trial wave functions can be used for Quantum Monte Carlo, with or without pseudo-potentials.
These interfaces are provided as `external plugins`_.
`QMCPack`_ / `CHAMP <https://www.utwente.nl/en/tnw/ccp/research/CHAMP.html>`_ /
`QMC=Chem`_
Trial wave functions can be used for |QMC|, with or without pseudo-potentials.
These interfaces are provided as `external plugins`_.

1
docs/source/users_guide/quickstart.rst
View File

@ -123,7 +123,6 @@ The estimated |FCI| energy of HCN is ``-93.0501`` au.
.. include:: /work.rst
* Interfaces : molden/fcidump
* Natural orbitals
* Parameters for Hartree-Fock
* Parameters for Davidson

6
src/Determinants/EZFIO.cfg
View File

@ -1,16 +1,16 @@
[N_det_max]
[n_det_max]
type: Det_number_max
doc: Maximum number of determinants in the wave function
interface: ezfio,provider,ocaml
default: 1000000
[N_det_max_full]
[n_det_max_full]
type: Det_number_max
doc: Maximum number of determinants where |H| is fully diagonalized
interface: ezfio,provider,ocaml
default: 1000
[N_states]
[n_states]
type: States_number
doc: Number of states to consider
interface: ezfio,provider,ocaml

95
src/FCI/README.rst
View File

@ -4,7 +4,9 @@ FCI
Selected Full Configuration Interaction.
The program start with a single determinant, or with the wave function in the |EZFIO| database if :option:`determinants read_wf` is |true|. Then, it will iteratively:
The :command:`FCI` program starts with a single determinant, or with the wave
function in the |EZFIO| database if :option:`determinants read_wf` is |true|.
Then, it will iteratively:
* Select the most important determinants from the external space and add them to the
internal space
@ -17,9 +19,94 @@ The program start with a single determinant, or with the wave function in the |E
The number of selected determinants at each iteration will be such that the
size of the wave function will double at every iteration.
size of the wave function will double at every iteration. If :option:`determinants
s2_eig` is |true|, then the number of selected determinants will be 1.5x the
current number, and then all the additional determinants will be added.
By default, the program will stop when more than one million determinants have
been selected, or when the |PT2| energy is below :math:`10^{-4}`.
The variational and |PT2| energies of the iterations are stored in the
|EZFIO| database, in the :ref:`IterativeSave` module.
Computation of the |PT2| energy
-------------------------------
At each iteration, the |PT2| energy is computed considering the Epstein-Nesbet
zeroth-order Hamiltonian:
.. math::
E_{\text{PT2}} = \sum_{ \alpha }
\frac{|\langle \Psi_S | \hat{H} | \alpha \rangle|^2}
{E - \langle \alpha | \hat{H} | \alpha \rangle}
where the |kalpha| determinants are generated by applying all the single and
double excitation operators to all the determinants of the wave function
:math:`\Psi_G`.
When the hybrid-deterministic/stochastic algorithm is chosen
(default), :math:`Psi_G = \Psi_S = \Psi`, the full wavefunction expanded in the
internal space.
When the deterministic algorithm is chosen (:option:`perturbation do_pt2`
is set to |false|), :math:`Psi_G` is a truncation of |Psi| using
:option:`determinants threshold_generators`, and :math:`Psi_S` is a truncation
of |Psi| using :option:`determinants threshold_selectors`, and re-weighted
by :math:`1/\langle \Psi_s | \Psi_s \rangle`.
At every iteration, while computing the |PT2|, the variance of the wave
function is also computed:
.. math::
\sigma^2 & = \langle \Psi | \hat{H}^2 | \Psi \rangle -
\langle \Psi | \hat{H} | \Psi \rangle^2 \\
& = \sum_{i \in \text{FCI}}
\langle \Psi | \hat{H} | i \rangle
\langle i | \hat{H} | \Psi \rangle -
\langle \Psi | \hat{H} | \Psi \rangle^2 \\
& = \sum_{ \alpha }
\langle |\Psi | \hat{H} | \alpha \rangle|^2.
The expression of the variance is the same as the expression of the |PT2|, with
a denominator of 1. It measures how far the wave function is from the |FCI|
solution. Note that the absence of denominator in the Heat-Bath selected |CI|
method is selection method by minimization of the variance, whereas |CIPSI| is
a selection method by minimization of the energy.
If :option:`perturbation do_pt2` is set to |false|, then the stochastic
|PT2| is not computed, and an approximate value is obtained from the |CIPSI|
selection. The calculation is faster, but the extrapolated |FCI| value is
less accurate. This way of running the code should be used when the only
goal is to generate a wave function, as for using |CIPSI| wave functions as
trial wave functions of |QMC| calculations for example.
The :command:`PT2` program reads the wave function of the |EZFIO| database
and computes the energy and the |PT2| contribution.
State-averaging
---------------
Extrapolated |FCI| energy
-------------------------
An estimate of the |FCI| energy is computed by extrapolating
.. math::
E=E_\text{FCI} - \alpha\, E_\text{PT2}
This extrapolation is done for all the requested states, and excitation
energies are printed as energy differences between the extrapolated
energies of the excited states and the extrapolated energy of the ground
state.
The extrapolations are given considering the 2 last points, the 3 last points, ...,
the 7 last points. The extrapolated value should be chosen such that the extrpolated
value is stable with the number of points.

4
src/Perturbation/EZFIO.cfg
View File

@ -4,14 +4,14 @@ doc: If `True`, compute the |PT2| contribution
interface: ezfio,provider,ocaml
default: True
[PT2_max]
[pt2_max]
type: PT2_energy
doc: The selection process stops when the largest |PT2| (for all the state) is lower
than `pt2_max` in absolute value
interface: ezfio,provider,ocaml
default: 0.0001
[PT2_relative_error]
[pt2_relative_error]
type: Normalized_float
doc: Stop stochastic |PT2| when the relative error is smaller than `PT2_relative_error`
interface: ezfio,provider,ocaml