LCPQ/quantum_package
10
0
Fork 0
mirror of https://github.com/LCPQ/quantum_package synced 2024-12-31 00:25:57 +01:00
Code Issues Releases Wiki Activity

Added documentation and Makefile

Browse Source
This commit is contained in:
Anthony Scemama 2014-04-01 17:49:29 +02:00
parent 20e3488df7
commit 0c2db61521
13 changed files with 1109 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
.gitignore vendored Normal file
View File

@ -0,0 +1,3 @@
sci.rc
EZFIO
irpf90

27
Makefile Normal file
View File

@ -0,0 +1,27 @@
WWW_SERVER = http://qmcchem.ups-tlse.fr/files/scemama
IRPF90_TGZ = irpf90-latest-noarch-src.tar.gz
EZFIO_TGZ = EZFIO.latest.tar.gz
.PHONY: doc src
default: src
EZFIO:
$(info ===== Fetching EZFIO from the web =====)
@wget "$(WWW_SERVER)/$(EZFIO_TGZ)" || \
(echo Unable to download EZFIO : $(WWW_SERVER)/$(EZFIO_TGZ) ; exit 1)
@tar -zxf $(EZFIO_TGZ) && rm $(EZFIO_TGZ)
irpf90:
$(info ===== Fetching IRPF90 from the web =====)
@wget "$(WWW_SERVER)/$(IRPF90_TGZ)" || \
(echo Unable to download IRPF90 : $(WWW_SERVER)/$(IRPF90_TGZ) ; exit 1)
@tar -zxf $(IRPF90_TGZ) && rm $(IRPF90_TGZ)
$(MAKE) -C irpf90
doc:
$(MAKE) -C doc
src: irpf90 EZFIO
export SCI_ROOT=$$PWD ; \
$(MAKE) -C src

2
README.md
View File

@ -3,4 +3,6 @@ Quantum package
Set of quantum chemistry programs and libraries.
For more information, you can visit the
`wiki of the project <http://github.com/LCPQ/quantum_package/wiki>`_

1
doc/.gitignore vendored Normal file
View File

@ -0,0 +1 @@
build

154
doc/Makefile Normal file
View File

@ -0,0 +1,154 @@
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = build
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext default
default: html
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
clean:
-rm -rf $(BUILDDIR)/*
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/SelectedCI.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/SelectedCI.qhc"
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/SelectedCI"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/SelectedCI"
@echo "# devhelp"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."

156
doc/source/Intro.rst Normal file
View File

@ -0,0 +1,156 @@
============================================================
What is a selected CI caculation ? Some theoretical concepts
============================================================
Generalities
============
The selected CI algorithm can be seen as a way to compute the energies (and various properties) of a given number of eigenstates
of a given :term:`target space` (ex : CISD, CAS-CI, DDCI etc ...),
but by taking the freedom of splitting the wave function of the target space in term
of :term:`internal determinants` treated variationally and :term:`perturbers` treated perturbatively.
Why this freedom ? Because in a given :term:`target space` (except some really special cases) most of the information
is concentrated within a tiny fraction of the :term:`target wave function`, and the remaining part can be reasonabely estimated by perturbtation.
This splitting of the wave function is not done in one shot, it is done iteratively. The iterative procedure needs a :term:`stopping criterion` to end the calculation and to control the quality of the calculation.
This :term:`stopping criterion` can be for example the number of determinants in the :term:`intern space`,
or the value of the :term:`energetic perturbative correction` to estimate the importance of the perturbation, or the convergence of the :term:`estimated target energy`, or anything that can
be defined in terms of available informations during the calculation.
The heart of the selected CI algorithm is based on the CIPSI algorithm (ref Malrieu).
Selected CI in a few words
==========================
First you define a :term:`target space`. Once the target space is defined, you define the :term:`stopping criterion`.
After that, a starting wave function is chosen by the user (HF by default).
This starting wave function is the first :term:`Internal determinants` wave function.
After that, one would like to extend this :term:`Internal determinants` wave function by adding
some :term:`perturbers` determinants.
How do we select the good :term:`perturbers` ?
do while (:term:`stopping criterion` is reached)
1) Generates :term:`perturbers` determinants according to your chosen :term:`target space`.
:math:`\Rightarrow` generates a set of :term:`perturbers` :math:`\{|D_P\rangle\}`
2) The :term:`perturbers` importance are estimated by perturbation thanks to the current :term:`internal determinants`.
3) The most important of the :math:`\{|D_P\rangle\}` are chosen to enter in the :term:`internal determinants`.
4) You rediagonalize the H matrix with the previous set of :term:`internal determinants` and the chosen :term:`perturbers`.
:math:`\Rightarrow` create a new wave function and a new set of the :term:`internal determinants`
5) iterate
Once the iterative procedure is stopped, the :term:`internal determinants` wave function have a :term:`variational energy`,
and by adding the :term:`energetic perturbative correction` one have the :term:`estimated target energy`
which is an approximation of the :term:`target energy`. One should notice that if one takes
a :term:`stopping criterion` such as the all the determinants of the target space are in the :term:`intern space`,
the :term:`estimated target energy` is the :term:`target energy`.
If one is interested of how is built the selected CI wave function into more details, one can read the further section.
What is a selected CI iteration in practice (and some details)
==============================================================
From the previous section we have roughly seen how the selected CI works. Now, getting a bit more into details,
we will see what is done in practice during a selected CI iteration. To illustrate this, a simple CISD example wil be given.
The general picture
^^^^^^^^^^^^^^^^^^^
The :term:`target space` defines entirely the method that is going to be approximated, and the stopping criterion will be the only approximation.
This :term:`target space` can always be defined in terms of application of an :term:`H operator`
(with some :term:`excitation restrictions`) on a given set of determinants that we shall call the :term:`generators` determinants.
We call :term:`restricted H operator` this precise H operator.
The target space intirely defines the :term:`restricted H operator`.
The only flexibility is the perturbation theory to be used to estimate the coeficients of the :term:`perturbers`.
If the target space is just defines in term of a CI matrix to diagonalize, the standard :term:`Diagonalization EN EG` perturbation will be used.
If some other constraints are imposed in addition to the CI matrix
(e.g. some physical conditions of size extensivity such as in the :term:`CISD+SC2` method),
then the perturbation must be adapted to properly respect the :term:`target space`.
CISD : the :term:`target space` is here defined intirely by all the single and double excitations acting on the HF determinant.
So the :term:`generators` subset of determinants here is only the HF determinant and will not change along the iteration.
If some occupied orbitals are chosen to be frozen (no excitations from those orbitals)
or some virtuals are chosen to be deleted (no excitations going to these virtuals orbitals),
this constraint imposes the :term:`excitation restrictions`. So here the :term:`restricted H operator` will be all the single and double excitations except those involving either a frozen core orbital or a deleted virtual orbital.
Different choices of perturbation theory can be made for the CISD, but the standard :term:`Diagonalization EN EG` can be trustly used.
Once the :term:`target space` have been defined, what does in practice a selected CI iteration.
For the sake of simplicity, here we emphasize on the ground state :math:`| \psi_0 \rangle`. At a given iteration, one have a :term:`selected wave function` :math:`|\psi_0\rangle`, and the selected CI algorithm performs :
do G = 1, N_Generators
1) Apply the :term:`restricted H operator` on the :math:`|D_G \rangle` :term:`generators` determinant belonging to :math:`| \psi_0 \rangle`
:math:`\Rightarrow` generates a set of :term:`perturbers` :math:`|D_P\rangle`
2) Estimate the perturbative importance of each perturbers
:math:`\Rightarrow` example for the :term:`EN EG` perturbation theory
.. math::
c_{D_P}^0= \frac{ \sum_{S=1,N_{\rm selectors}} c_S^0 \langle D_S|H|D_P\rangle}{ \langle \psi_0 |H|\psi_0 \rangle - \langle D_P |H|D_P\rangle } \\
e_{D_P}^0= \frac{(\sum_{S=1,N_{\rm selectors}} c_S^0 \langle D_S|H|D_P\rangle) ^2}{\langle \psi_0 |H|\psi_0 \rangle - \langle D_P |H|D_P\rangle}
3) Keep the most important :term:`perturbers` :math:`|D_P \rangle`
:math:`\Rightarrow` they enter in the :term:`intern space`
4) Rediagonalize H within this new subset of determinants
:math:`\Rightarrow` better :term:`selected wave function`
5) Iterate
An important point here is that at a given iteration, the estimation of the perturbative coefficients of the :term:`perturbers`
depends on the quality of the :term:`selected wave function` .
As the iterations go on, the :term:`selected wave function` becomes closer
and closer to the :term:`target wave function`, and so the perturbative estimation of the :term:`perturbers` coefficients or energetic contribution becomes more and more precise.
CISD : At the first iteration, starting from the HF determinant :
1) By applying H on the :term:`generators` (HF) one generates all singles and doubles
2) For each :term:`perturbers` you estimate by perturbation its coefficient of energetic contribution.
i) Here the :term:`selectors` is only the HF determinant.
ii) If the :term:`Brillouin theorem` is respected, all the singles have zero coefficients since the :term:`selectors` here is only the HF determinant.
iii) The most important double excitations entered
iv) The :term:`energetic perturbative correction` is calculated
v) The :term:`estimated target energy` is just the sum of the HF energy and the :term:`energetic perturbative correction`
3) H is rediagonlaized in the new set of determinants : HF + the selected doubles
:math:`\Rightarrow` better :term:`variational energy` and :term:`selected wave function`
4) The :term:`generators` subset does not change.
At the second iteration :
1) By applying H on the :term:`generators` (still HF) one generates all singles and doubles
2) For each :term:`perturbers` you estimate by perturbation its coefficient of energetic contribution.
i) Here the :term:`selectors` is now HF + the previously selected doubles
:math:`\Rightarrow` the :term:`perturbers` now interact with all the previously selected doubles
:math:`\Rightarrow` better estimation of the coefficients of the :term:`perturbers`
:math:`\Rightarrow` the singles have non zero coefficients
ii) The most important :term:`perturbers` enter in the :term:`intern space`
iv) The :term:`energetic perturbative correction` is re estimated
v) The :term:`estimated target energy` is now the sum of the variational energy of the :term:`selected wave function` and the :term:`energetic perturbative correction`
:math:`\Rightarrow` better estimation of the :term:`target energy`
Iterate untill you reached the desired :term:`stopping criterion`

0
doc/source/_static/.empty Normal file
View File

228
doc/source/code_doc_intro.rst Normal file
View File

@ -0,0 +1,228 @@
=============================
The Documentation of the code
=============================
The heart of the problem : how do we compute the perturbation ?
===============================================================
In this section we will present the basic ideas of how do we compute any kind of perturbative quantity.
The main problem
^^^^^^^^^^^^^^^^
Consider a simple problem of perturbation theory in which you have a *general* multireference wave function :math:`| \psi \rangle`
(no trivial way to know the kind of relations between those determinants) :
.. math::
| \psi \rangle = \sum_{I=1,N_{det}} c_I | D_I \rangle
and you would like to compute its second order :term:`perturbative energetic correction`, which we can write like this for the sake of simplicity:
.. math::
E_{PT2} = \sum_{P \, \rm{that} \, \rm{are} \, \rm{not} \, \rm{in} \, | \psi \rangle } \frac{\langle \psi | H | D_P \rangle^2}{\Delta E_P}
and the :math:`\Delta E_P` will determine what kind of PT you use. Note that you must not double count a determinant :math:`| D_P \rangle` and that you must not count those which are in :math:`| \psi \rangle`.
What you have to do is to apply the :math:`H` operator on this :math:`| \psi \rangle` that would generate a lot of determinants :math:`|D \rangle`,
and you must find a way to see if :
#) the determinant :math:`|D \rangle` is in :math:`| \psi \rangle`
#) the determinant :math:`|D \rangle` have already been counted
How do we do in practice ? We apply :math:`H` succesively on each determinant of :math:`| \psi \rangle` and each :math:`H` application generates a lot of determinant :math:`|D \rangle`. For each determinants :math:`|D \rangle` we check with a very optimized subroutine if
#) :math:`|D\rangle` was a single or a double excitation respect to all the determinant on which we previously applyed :math:`H`
:math:`\Rightarrow` if it is the case then it have already been computed in the past and so we don't double count it.
#) :math:`|D\rangle` is already in the rest of the :math:`| \psi \rangle`
:math:`\Rightarrow` if it is the case you must not count it.
This subroutine (:samp:`connected_to_ref` ) is called a **HUGE** number of times and so it have been optimized in a proper way.
Its basis is the :samp:`popcnt` hardware instruction that figures in the :samp:`SSE4.2` releases of processors.
It allows to know how many bites are set to one in an integer within a few cycles of CPU.
By manipulation of bits masks you can easily extract the excitation degree between two determinants.
One interesting feature of this approach is that it is easily and efficiently parallelizable (which of cours have been done),
and you can easily reach an parallel efficiency of about :math:`95\%`.
The link between the perturbation and the selection
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In the selected CI algorithm you have general :math:`| \psi \rangle` multi determinantal wave function and you want to make it better
by proposing some new candidates to enter in this wave function.
Those candidates must of course not be already in :math:`| \psi \rangle` and since their are selected thanks to their perturbative properties (on the energy or on the coefficient), their are generated through some application of the :math:`H` operator. So we see that we have exactly the same kind of feature than in the perturbation.
How do we select the determinant in practice ? Exactly like we do the perturbation !
do G = 1, :term:`N_{Generators}`
#) We apply :math:`H` on one :term:`generators`
:math:`\Rightarrow` :math:`H|D_G \rangle = \sum_D \langle D | H |D_G \rangle |D \rangle`
#) For each determinant :math:`|D \rangle` we check if it could have been generated from previous :term:`generators` :math:`| D_{G'} \rangle`
:math:`\Rightarrow` If it is not the case we check if it belongs to :math:`| \psi \rangle`
#) We compute its perturbative property
#) If it is important we put it in a buffer of the potential candidates to the new set of :term:`internal determinants`
#) go to 1
enddo
So once you have applyed :math:`H` on all the :term:`generators`, you sort all the buffer of the candidates by their importance,
and after you pick up the most important ones, which will enter in the wave function and be diagonalized.
Just to be more precise, what we drescribe here is the standard CIPSI algorithm (which :term:`target space` is always the FCI). In practice, if you replace the :math:`H` operator by the :term:`restricted H operator` defined by the :term:`target` space you have exactly what is emplemented.
The typical feature of an iteration
===================================
An iteration of the selected CI program is always built in the same way. This can be resumed in the following simple tasks.
Iteration :
#) :term:`restricted H operator` applyed on the :term:`generators`
:math:`\Rightarrow` :term:`perturbativ action` (*e.g* Selection of some :term:`perturbers`, calculation of the :math:`E_{PT2}^m`, etc ...)
#) Some update induced by the :term:`perturbative action` (*e.g* diagonalization of the new :math:`H` matrix, etc ...)
#) Check the :term:`stopping criterion`
#) Update the :term:`generators` subset
#) Save restart data if needed
#) Iterate
To go into details we list the various available options for each task.
The :samp:`restricted_H_apply` like subroutines
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Here we enter into details on the part of the subroutines that is responsible for the :term:`restricted H operator` part of the tasks.
The general ideas
^^^^^^^^^^^^^^^^^
This subroutine takes in input a determinant (in term of an integer key) and some bits masks
that are used to restrict the excitations (see the :term:`excitations bits masks` and :term:`excitations restrictions`).
It generates the singles and doubles excitations from the input determinant and these :term:`excitations bits masks`.
This subroutine will be applyed on the :term:`generators` determinants to generate the :term:`perturbers`.
This subroutine in itself does not exist, it is just a skeleton that generates all possible singles and doubles.
As seen in the previsous section, once you apply :math:`H` on a given determinant, you will use the generated determinants
to do a certain number of things that deal with in general a perturbative quantity, this is the :term:`perturbative action`.
A way to resume what is done in the subroutine and to make a mental representation can be explained like this :
.. code-block:: fortran
subroutine restricted_H_apply(key_in)
do i = 1, available_holes(1)
do j = 1, available_holes(2)
do k = 1, available_particles(1)
do l = 1, available_particles(2)
! you generate some excitations on key_in that will generate some key_out
call excitation(i,j,k,l,key_in,key_out)
! you exploit key_out to do some perturbative work
call perturbative_action(key_out)
enddo
enddo
enddo
enddo
end
So we see that here once we have made an excitation on :samp:`key_in` that generates :samp:`key_out`,
we can do some work related to the :term:`perturbative action` on this :samp:`key_out`.
In this simple representation of the subroutine, there are some :samp:`available_holes` and :samp:`available_particle`.
This is due to the :term:`excitation restrictions` that are implicitly defined by the :term:`target space`,
and to the :term:`restricted orbitals` that are defined by the user.
In practice those :term:`excitation restrictions` are just the excitations that are going to be allowed to a given :term:`generator determinant`.
We do this by using some :term:`excitations bits masks`.
The :term:`excitation restrictions` and the :term:`restricted orbitals` are built thanks to the use of :term:`excitations bits masks`.
Available :term:`excitation restrictions`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The :term:`excitation restrictions` prohibits some kind of excitations because it is in the definition
of the :term:`target space` to avoid a certain class of excitation.
For instance, in the :term:`CAS+DDCI` method, you will apply all the single and double excitations on the top of the :term:`CAS wave function`.
After those :term:`excitation restrictions` defined by the :term:`target space`, there can be some kind of excitations that the user wishes to avoid.
For instance, within a :term:`CISD` or a :term:`CAS+DDCI` you can wish that all the excitations of the core electrons can be neglected,
or that there are some virtuals that are not relevant for a certain kind of correlation effects.
This restrictions are done in the program by defining some classes of orbitals that depend both on the method you would like to use,
and by the specific restrictions you would like to do on the top of that. So we see that there are classes of orbitals that depend on the method,
and other classes that can be defined for any class of method.
This classes are the the :term:`frozen occupied orbitals` and the :term:`deleted virtual orbitals` .
Available :term:`perturbative action`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
From what we saw previously, when an excitation is performed on a given :term:`generator`,
depending on the method defined by the user, different actions can be performed at that point of the calculation.
Nevertheless, all this actions here deal with the perturbation, that is why we called this step the :term:`perturbative action`.
The :term:`perturbative action` is very flexible. It consists in doing (or not) a certain kind of things.
When a given determinant :samp:`key_out` is generated, you can :
#) check if this determinants have to be taken into account (see :samp:`connected_to_ref` and :samp:`is_in_ref`)
#) compute its :term:`perturbative energetic contribution` and its :term:`perturbative coefficient` (see :term:`perturbation theory`)
#) use those perturbative quantities to do something that deals with it (see :term:`perturbative possibility` )
In principle, for each of those actions one would put a :samp:`if` statement and decline all the possible actions to do.
However, because there can exist a *lot* of possible action and because this loop is really intern, putting a lot of :samp:`if` statement
is not a good idea and will slow the code.
To avoid that we generate with a python script all possible subroutines corresponding to some actions, and the program will use the one
that will be defined by the method desired by the user. In this way there is no unnecessary tests in the intern loop, it done in the input.
The :term:`perturbative possibility`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Once you have compute the :term:`perturbative energetic contribution` and the :term:`perturbative coefficient` of a given :term:`perturber`,
you must use those quantities. Here is listed what is available :
#) accumulate it :term:`perturbative energetic contribution` to compute the :term:`Energetic perturbative correction`
#) accumulate it :term:`perturbative coefficient` to compute the :term:`first order perturbative norm`
#) put or not the :samp:`key_out` determinant in a buffer to select some new :term:`intenal determinants` see :term:`selection`
#) update the arrays of the :term:`correlation energy by holes and particles` (see :term:`CISD+SC2`)
#) dress all the diagonal matrix elements of the :term:`internal determiants` (see :term:`Dressed MRCI`)
Connected to ref / is in ref
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This subroutine takes in input a determinant (in term of an integer key), an array of determinants :samp:`keys` (containing :samp:`N_det` determinants)
and an integer :samp:`i_past` which is smaller or equal to :samp:`N_det`.
It checks if the input determinant is connected by the :math:`H` matrix to all the determinants in :samp:`keys` that are before :samp:`i_past`.
It also check if the input determinant is in the whole list of determinants :samp:`keys`.
In output you have an integer :samp:`c_ref` that have the following values :
#) 0 : the input determinant is not in :samp:`keys` and is not connected to any determinant
in :samp:`keys` that is before :samp:`i_past`.
#) +m : the input determinant is connected by the :math:`H` matrix to the *m* th determinant :samp:`keys`.
#) -m : the input determinant is already in :samp:`keys` and it is the *m* th determinant in :samp:`keys`

285
doc/source/conf.py Normal file
View File

@ -0,0 +1,285 @@
# -*- coding: utf-8 -*-
#
# Selected CI documentation build configuration file, created by
# sphinx-quickstart on Mon Feb 10 15:53:11 2014.
#
# This file is execfile()d with the current directory set to its containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import sys, os
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
# -- General configuration -----------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo', 'sphinx.ext.pngmath', 'sphinx.ext.mathjax', 'sphinx.ext.viewcode']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'Selected CI'
copyright = u'2014, Giner Emmanuel , Scemama Anthony'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '1.0'
# The full version, including alpha/beta/rc tags.
release = version+'.1'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = []
# The reST default role (used for this markup: `text`) to use for all documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# -- Options for HTML output ---------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'default'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'SelectedCIdoc'
# -- Options for LaTeX output --------------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#'preamble': '',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
('index', 'SelectedCI.tex', u'Selected CI Documentation',
u'Giner Emmanuel ', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
# If true, show page references after internal links.
#latex_show_pagerefs = False
# If true, show URL addresses after external links.
#latex_show_urls = False
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_domain_indices = True
# -- Options for manual page output --------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'selectedci', u'Selected CI Documentation',
[u'Giner Emmanuel '], 1)
]
# If true, show URL addresses after external links.
#man_show_urls = False
# -- Options for Texinfo output ------------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
('index', 'SelectedCI', u'Selected CI Documentation',
u'Giner Emmanuel ', 'SelectedCI', 'One line description of project.',
'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
#texinfo_appendices = []
# If false, no module index is generated.
#texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'
# -- Options for Epub output ---------------------------------------------------
# Bibliographic Dublin Core info.
epub_title = u'Selected CI'
epub_author = u'Giner Emmanuel '
epub_publisher = u'Giner Emmanuel '
epub_copyright = u'2014, Giner Emmanuel '
# The language of the text. It defaults to the language option
# or en if the language is not set.
#epub_language = ''
# The scheme of the identifier. Typical schemes are ISBN or URL.
#epub_scheme = ''
# The unique identifier of the text. This can be a ISBN number
# or the project homepage.
#epub_identifier = ''
# A unique identification for the text.
#epub_uid = ''
# A tuple containing the cover image and cover page html template filenames.
#epub_cover = ()
# HTML files that should be inserted before the pages created by sphinx.
# The format is a list of tuples containing the path and title.
#epub_pre_files = []
# HTML files shat should be inserted after the pages created by sphinx.
# The format is a list of tuples containing the path and title.
#epub_post_files = []
# A list of files that should not be packed into the epub file.
#epub_exclude_files = []
# The depth of the table of contents in toc.ncx.
#epub_tocdepth = 3
# Allow duplicate toc entries.
#epub_tocdup = True

25
doc/source/index.rst Normal file
View File

@ -0,0 +1,25 @@
.. Selected CI documentation master file, created by
sphinx-quickstart on Mon Feb 10 15:53:11 2014.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to Selected CI's documentation!
=======================================
Contents:
.. toctree::
:maxdepth: 1
install
Intro
code_doc_intro
wavefunction
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

40
doc/source/install.rst Normal file
View File

@ -0,0 +1,40 @@
============
Installation
============
Requirements
------------
* `GNU make <http://www.gnu.org/software/make>`_
* `The Intel Fortran Compiler with MKL <http://software.intel.com/en-us/fortran-compilers>`_
* `IRPF90 <http://irpf90.ups-tlse.fr>`_
* `EZFIO <http://ezfio.sourceforge.net>`_
Optional Requirements
---------------------
* `Sphinx <http://sphinx-doc.org/>`_ is used to build the documentation
Setup
-----
#) Run the :file:`setup_environment.sh` script. This will create the :file:`sci.rc` file
that contains all the environment variables ::
$ ./setup_environment.sh
#) Source this file into your shell ::
$ source sci.rc
#) Go into the :file:`src` directory and create the :file:`Makefile.config` file using the
:file:`Makefile.config.example` file as a template
#) Build the program ::
$ make
#) Build the documentation ::
$ make doc

169
doc/source/wavefunction.rst Normal file
View File

@ -0,0 +1,169 @@
=====================================
Selection, perturbation ... keywords
=====================================
.. |CISD| replace:: :abbr:`CISD (Configuration Interaction with Single and Double excitations)`
.. |HF| replace:: :abbr:`HF (Hartree Fock)`
.. |CAS-CI| replace:: :abbr:`CAS-CI (Complete Active Space Configuration Interaction)`
.. |DDCI| replace:: :abbr:`DDCI (Difference Dedicated Configuration Interaction)`
.. glossary::
:sorted:
Energetic perturbative correction
Corresponds to the correction to the energy at the second order of a given perturbtation theory
to a given state m.
By convention it noted :math:`E_{PT2}^m`
Variational energy
Corresponds to the variational energy of the :term:`selected wave function` for a given state .
By convention it noted :math:`E_{Var}^m` for the mth eigenvector.
.. math::
E_{Var}^m = \langle \psi_m |H|\psi_m \rangle
Estimated target energy
Corresponds to the estimation of the target energy for a given :term:`selected wave function` and a given state.
By convention it noted :math:`E_{Target}^m`.
Its mathematical expression is :
.. math::
E_{Target}^m = E_{Var}^m + E_{PT2}^m
Selected wave function
Corresponds to the wave function that have been previously selected for a given state m at a current iteration.
This wave function is defined by the set of the :term:`internal determinants` and by their coefficients
on the state m.
By convention it is noted :math:`|\psi_m\rangle`
.. math::
| \psi_m \rangle = \sum_{I=1,N_{selected}} c_I^m | D_I \rangle
EN EG
Stands for Eipstein Nesbet with EigenValues zeroth order energy perturbation theory.
It is a state specific 2nd order perturbation theory. Here m is the index of the eigenstate.
The :math:`H_0` of this PT is defined as the diagonal part of the Hamiltonian such as
the :math:`E_m` is equal to the average value of the Hamiltonian on the :term:`selected wave function`
and the :math:`E_P` is equal to the average value of the Hamiltonian on the :term:`perturbers`
This perturbation have bad formal properties but some nice numerical features of convergence.
From the definition, one get the first order coefficient and its related second order energetic contribution of a a perturber :
.. math::
c_{D_P}^m= \sum_{S=1,N_{\rm selectors}} \frac{c_S^m \langle D_S|H|D_P\rangle}{ \langle \psi_m |H|\psi_m \rangle - \langle D_P|H| D_P \rangle } \\
e_{D_P}^m= \frac{(\sum_{S=1,N_{\rm selectors}} c_S^m \langle D_S|H|D_P\rangle)^2}{\langle \psi_m |H|\psi_m \rangle - \langle D_P|H| D_P \rangle }
Stopping criterion
Condition decided by the user to stop the calculation.
This criterion might be on the :term:`Energetic perturbative correction`, on the number of :term:`internal determinants` N_selected_max
or on the stability of the :term:`estimated target energy`
The user can also send a Ctrl+C to stop the calculation, and it will kill itself properly, saving the datas that need to be saved.
Target wave function
Wave function of the :term:`target space`
Target space
Target of the CI calculation. Defining a method (CISD, CAS-CI and so on) is equivalent to define the :term:`target space`.
The target space defines the rules to define the :term:`Generators` ,
the rules of the :term:`excitation restrictions`,
and the perturbation theory to be used.
There are two type of methods/:term:`target space` proposed in the code :
#) the CAS-CI type methods where you do not restrict any kind of excitation degree within a given list of orbitals.
#) the singles and doubles excitations on the top of a given reference wave function (:term:`CISD`, :term:`CISD+SC2`, :term:`CAS+SD`, :term:`CAS+DDCI`, :term:`CAS+MRPT2`)
Their is a great difference between those two types of method in the way it is implemented.
In the CAS-CI method, when you have chosen an :term:`active space` (so a list of orbitals and electrons to make a FCI within this active space),
all the :term:`Internal determinants` that have been selected and that form the :term:`selected wave function`
can potentially be part of the :term:`generators`, by mean that the :term:`restricted H operator`
could be potentially applyed on all the :term:`internal determinants` to generate some other :term:`perturbers`.
In the singles and doubles excitation on the top of a given reference wave function, the subset of :term:`generators`
and so the rules to recognize them, is fixed at the begining of the method. Those :term:`generators` are precisely
all the determinants forming the :term:`reference wave function`.
There are the different :term:`target space` that are available :
#) :term:`CISD`
#) :term:`CISD+SC2`
#) :term:`CASCI`
#) :term:`CASCI+S`
#) :term:`CASCI+SD`
#) :term:`CASCI+DDCI`
#) :term:`CASCI+DDCI+(2h-2p)PT2`
#) :term:`CAS-CI+MRPT2`
Target energy
Energy of the target space.
H operator
Hamiltonian operator defined in terms of creation and anihilation operators in the spin orbital space.
Excitation restrictions
Restriction in the :term:`H operator` that the user imposes to define the target sapce.
For example :
1) If one freeze some core orbitals or delete some virtuals, it is an :term:`excitation restrictions`
2) If one prohibits the pure inactive double excitations in a CAS+SD one get a DDCI
3) any kind of restriction in the full application of the :term:`H operator`
Restricted H operator
:term:`H operator` taking into account the :term:`Excitation restrictions`
CISD+SC2
Method developped by JP. Malrieu that can be seen as a cheap approximation of the CCSD.
It makes a CISD size consistant and separable for closed shell systems.
It is based on a CISD calculation
where the diagonal part of the H matrix is dressed by the repeatable correlation energy previsously obtained.
So it is a CISD dressed by the disconnected triples and quadruples.
Generators
Set of generator determinants.
By convention a generator is written as :math:`|D_G\rangle` .
A generator determinant is a determinant on which
the :term:`restricted H operator` is being applied for the selection and/or the perturbation.
Internal determinants
Selected determinants in terms of integers keys.
By convention an Internal determinant is written as :math:`|D_I\rangle` .
By convention, the :term:`Generators` are at the begining of the array.
Intern space
Set of all the :term:`internal determinants`.
Perturbers
Determinants within the :term:`target space` but taht are not already included in the :term:`intern space`.
They are created from the :term:`Generators` that belongs :term:`Intern space` for a given :term:`selected wave function`.
By convention a perturber is written as :math:`|D_P\rangle`.
Selectors
Determinants that are used to compute the perturbative properties of the :term:`perturbers`.
By convention a selector is written as :math:`|D_S\rangle` .
The selectors are a subset of determinant of the total wave function (that is the :term:`Internal determinants`).
This subset contains at least the :term:`Generators` determinants.
The perturbative properties (energy, coefficient or else) of the :term:`perturbers` are calculated on all the :term:`selectors` :math:`|D_S\rangle`
.. math::
c_{D_S}= \sum_{S=1,N_{\rm selectors}} \frac{c_S\langle D_S|H|D_P\rangle}{\Delta E_{P,S}} \\
e_{D_S}= \frac{(\sum_{S=1,N_{\rm selectors}} c_S \langle D_S|H|D_P\rangle) ^2}{\Delta E_{P,S}}

19
setup_environment.sh Executable file
View File

@ -0,0 +1,19 @@
#!/bin/bash
SCI_ROOT=${PWD}
IRPF90=$(which irpf90)
if [[ -z ${IRPF90} ]] ;
then
make irpf90
IRPF90=${SCI_ROOT}/irpf90/bin/irpf90
fi
make EZFIO
cat << EOF > sci.rc
export IRPF90=${IRPF90}
export SCI_ROOT=${SCI_ROOT}
export PATH+=:${SCI_ROOT}/scripts
export PATH+=:${SCI_ROOT}/bin
EOF