From bc01ff40d7cfd6832fdfb70f528a001f5a2b7246 Mon Sep 17 00:00:00 2001 From: Anthony Scemama Date: Tue, 23 Oct 2018 23:37:51 +0200 Subject: [PATCH] User's guide --- TODO | 1 - docs/source/index.rst | 1 + docs/source/users_guide.rst | 172 ++++++++++++++++++++++++++++++++++++ 3 files changed, 173 insertions(+), 1 deletion(-) create mode 100644 docs/source/users_guide.rst diff --git a/TODO b/TODO index e080e748..e27411e6 100644 --- a/TODO +++ b/TODO @@ -40,6 +40,5 @@ * Programmers doc: - * Pointer to IRPF90 tutorial * Fetch all README.rst files, and IRP documentation via scripts to replace old README.rst * Example : Simple Hartree-Fock program from scratch diff --git a/docs/source/index.rst b/docs/source/index.rst index 5bee229a..734262d2 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -18,6 +18,7 @@ Quantum Package intro interfaces installation + users_guide benchmarks programming research diff --git a/docs/source/users_guide.rst b/docs/source/users_guide.rst new file mode 100644 index 00000000..abd0df0a --- /dev/null +++ b/docs/source/users_guide.rst @@ -0,0 +1,172 @@ +User's guide +============ + +The input data is stored in a `EZFIO`_ database. It is a hierarchical data +format which uses the hierarchy of the file system to organize the data, stored +in a directory. +To access the data in the EZFIO file, you can use the provided API (Fortran, +Python, OCaml or bash), or tools such as `qp_edit` provided with the Quantum +Package. The data in the EZFIO directory is stroed as plain text files, so +it can be read with a text editor. +To create an EZFIO directory from scratch, the `qp_create_ezfio_from_xyz` should +be used. + +qp_create_ezfio_from_xyz +------------------------ + +Usage :: + + qp_create_ezfio_from_xyz [FLAGS] (xyz_file|zmt_file) + +Flags :: + + -b string Name of basis set. + [-au] Input geometry is in atomic units. + [-c int] Total charge of the molecule. Default is 0. + [-cart] Compute AOs in the Cartesian basis set (6d, 10f, ...) + [-d float] Add dummy atoms. x * (covalent radii of the atoms) + [-m int] Spin multiplicity (2S+1) of the molecule. Default is 1. + [-o file] Name of the created EZFIO file. + [-p string] Name of the pseudopotential + [-build-info] print info about this build and exit + [-version] print the version of this build and exit + [-help] print this help text and exit + (alias: -?) + + +This command creates an EZFIO directory from a standard xyz file or from a +z-matrix file in Gaussian format. The basis set is defined as a single string +if all the atoms are taken from the same basis set, otherwise specific elements +can be defined as follows:: + + -b "cc-pcvdz | H:cc-pvdz | C:6-31g" + -b "cc-pvtz | 1,H:sto-3g | 3,H:6-31g" + +If a file with the same name as the basis set exists, this file will be read. +Basis set files should be given in GAMESS format. Otherwise, the basis set is +obtained from the local database of the Quantum Package. + +The same rules apply for pseudopotentials. + + +qp_set_mo_class +--------------- + +Usage :: + + qp_set_mo_class EZFIO_DIRECTORY + + +Flags :: + + [-act range] Range of active orbitals + [-core range] Range of core orbitals + [-del range] Range of deleted orbitals + [-inact range] Range of inactive orbitals + [-q] Query: print the current masks + [-virt range] Range of virtual orbitals + [-build-info] print info about this build and exit + [-version] print the version of this build and exit + [-help] print this help text and exit + (alias: -?) + +This command sets the orbital classes in an EZFIO directory. + +Core + MOs which are always doubly occupied + +Deleted + MOs which are never occupied + +Active + MOs in which any number of holes/particles can be made + +Inactive + MOs in which only holes can be made + +Virtual + MOs in which only particles can be made + +To avoid errors, all the MOs should be given a class. +The range of MOs are given like the ranges in SLURM commands. For example, +`"[36-53,72-107,126-131]"`. + +To quickly setup a frozen core calculation, the script `qp_set_frozen_core.py` +can be used:: + + qp_set_frozen_core.py EZFIO_DIRECTORY + +.. warning:: + For atoms on the right of the periodic table, `qp_set_frozen_core.py` will + work as expected. But for atoms on the left, a small core will be chosen. For + example, a carbon atom will have 2 core electrons, but a Lithium atom will have + zero. + + + +Excited states +-------------- + +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. + +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``. +Otherwise, different spin states will come out in the diagonalization. + +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 tp `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. + + + +Natural orbitals +---------------- + +To produce state-average natural orbitals, run + +``` +qp_run save_natorb file.ezfio +``` + +The MOs will be replaced, so the two-electron integrals and the wave function are invalidated as well. + + + +The QP doesn't take account of the symmetry. For reasons 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. + + +.. _EZFIO: http://gitlab.com/scemama/EZFIO + + + + + +.. important:: TODO + + .. include:: work.rst + + * qp_edit + * qp_run + * qp_convert + * Interfaces : molden/fcidump + * Natural orbitals + * Parameters for Hartree-Fock + * Parameters for Davidson + * Running in parallel + * Parameters for selection (Generators/selectors) +