diff --git a/docs/source/_static/links.rst b/docs/source/_static/links.rst index af14380c..2f646e80 100644 --- a/docs/source/_static/links.rst +++ b/docs/source/_static/links.rst @@ -64,6 +64,7 @@ .. |MRPT| replace:: :abbr:`MRPT (Multi-Reference Perturbation Theory)` .. |PT2| replace:: :abbr:`PT2 (Second order perturbative correction)` .. |QMC| replace:: :abbr:`QMC (Quantum Monte Carlo)` +.. |rst| replace:: :abbr:`RST (ReStructured Text)` .. |SCF| replace:: :abbr:`SCF (Self Consistent Field)` .. |CASSCF| replace:: |CAS| - |SCF| .. |FCIQMC| replace:: |FCI| - |QMC| @@ -74,3 +75,6 @@ .. |S^2| replace:: :math:`\widehat{S^2}` .. |true| replace:: ``true`` .. |false| replace:: ``false`` +.. |README| replace:: :file:`README.rst` +.. |NEED| replace:: :file:`NEED` + diff --git a/docs/source/auto_generate.py b/docs/source/auto_generate.py index 5175cb86..25e30b80 100755 --- a/docs/source/auto_generate.py +++ b/docs/source/auto_generate.py @@ -5,7 +5,7 @@ import os import ConfigParser -def generate(abs_module): +def generate_modules(abs_module, entities): MODULE = os.path.split(abs_module)[-1] module = MODULE.lower() if module == "dummy": @@ -36,12 +36,112 @@ def generate(abs_module): default = "" rst += [ ".. option:: %s\n"%(section), doc, default ] + providers = [] + subroutines = [] + for k in entities: + e = entities[k] + if e["module"] == module: + if "/" not in e["file"] and e["file"] != "ezfio_interface.irp.f": + if e["type"] == 's': + subroutines.append(e) + elif e["type"] == 'p': + providers.append(e) + + if providers: + rst += [ "", "Providers", "---------", "" ] + for p in providers: + rst += [ """ +.. option:: %s + + .. code:: text + + %s + + File: %s + + %s + + +""" % ( p["name"], + "\n ".join(p["decl"]), + p["file"], + " ".join(p["doc"]).replace(".br","\n"), + ) ] + + + rst_file = os.path.join('modules',module+".rst") with open(rst_file,'w') as f: f.write("\n".join(rst)) +def generate_providers(abs_module): + + MODULE = os.path.split(abs_module)[-1] + module = MODULE.lower() + if module == "dummy": + return + + files = {} + entities = {} + mandir = os.path.join(abs_module,'IRPF90_man') + if not os.path.exists(mandir): + return {} + + for f in os.listdir(mandir): + + filename = os.path.join(mandir,f) + if f not in files: + files[f] = 0 + name = f.split('.')[0] + with open(filename, 'r') as f: + state = 0 + entity = { "decl": [], "doc": [] , + "name": name , "module": module } + for line in f.readlines(): + line = line.strip() + if line.startswith(".SH Declaration"): + state = 1 + continue + elif line.startswith(".nf"): continue + elif line.startswith(".ni"): continue + elif line.startswith(".P"): continue + if line.startswith(".SH Description"): + state = 2 + continue + elif line.startswith(".SH File"): + state = 3 + continue + if line.startswith(".SH Need"): + break + if line.startswith(".SH Instability"): + break + if line.startswith(".SH Call"): + break + + if state == 1: + entity["decl"] += [ line ] + if line.startswith("subroutine") \ + or line.startswith("function ") \ + or " function " in line: + entity["type"] = 's' + else: + entity["type"] = 'p' + elif state == 2: + entity["doc"] += [ line ] + elif state == 3: + if line.startswith(".br"): + continue + entity["file"] = line + + entities [ entity["name"] ] = entity + + return entities + + + + def main(): if "QP_ROOT" in os.environ: @@ -51,11 +151,15 @@ def main(): SRC = os.path.join(QP_ROOT, "src") - + entities = {} for abs_module in os.listdir(SRC): abs_module = os.path.join(SRC,abs_module) if os.path.exists( os.path.join(abs_module, "README.rst") ): - generate(abs_module) + read_entities = generate_providers(abs_module) + if read_entities: + for k in read_entities: + entities[k] = read_entities[k] + generate_modules(abs_module,entities) if __name__ == '__main__': main() diff --git a/docs/source/modules/.gitignore b/docs/source/modules/.gitignore new file mode 100644 index 00000000..e69de29b diff --git a/docs/source/modules/fci.rst b/docs/source/modules/fci.rst index a0d32bd1..c52650f2 100644 --- a/docs/source/modules/fci.rst +++ b/docs/source/modules/fci.rst @@ -47,7 +47,7 @@ zeroth-order Hamiltonian: E_{\text{PT2}} = \sum_{ \alpha } \frac{|\langle \Psi_S | \hat{H} | \alpha \rangle|^2} - {E - |\langle \alpha | \hat{H} | \alpha \rangle} + {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 @@ -131,3 +131,241 @@ EZFIO parameters Calculated |FCI| energy + |PT2| + + +Providers +--------- + + +.. option:: pt2_e0_denominator + + .. code:: text + + double precision, allocatable :: pt2_e0_denominator (N_states) + + File: energy.irp.f + + E0 in the denominator of the PT2 + + + + +.. option:: pt2_u_0 + + .. code:: text + + double precision, allocatable :: pt2_w (N_det_generators) + double precision, allocatable :: pt2_cw (0:N_det_generators) + double precision :: pt2_w_t + double precision :: pt2_u_0 + integer, allocatable :: pt2_n_0 (pt2_N_teeth+1) + + File: pt2_stoch_routines.irp.f + + + + + + +.. option:: pt2_r + + .. code:: text + + integer, allocatable :: pt2_j (N_det_generators) + integer, allocatable :: pt2_r (N_det_generators) + + File: pt2_stoch_routines.irp.f + + + + + + +.. option:: pt2_w + + .. code:: text + + double precision, allocatable :: pt2_w (N_det_generators) + double precision, allocatable :: pt2_cw (0:N_det_generators) + double precision :: pt2_w_t + double precision :: pt2_u_0 + integer, allocatable :: pt2_n_0 (pt2_N_teeth+1) + + File: pt2_stoch_routines.irp.f + + + + + + +.. option:: pt2_u + + .. code:: text + + double precision, allocatable :: pt2_u (N_det_generators) + + File: pt2_stoch_routines.irp.f + + + + + + +.. option:: pt2_j + + .. code:: text + + integer, allocatable :: pt2_j (N_det_generators) + integer, allocatable :: pt2_r (N_det_generators) + + File: pt2_stoch_routines.irp.f + + + + + + +.. option:: pt2_f + + .. code:: text + + integer, allocatable :: pt2_f (N_det_generators) + integer :: pt2_n_tasks_max + + File: pt2_stoch_routines.irp.f + + + + + + +.. option:: pt2_cw + + .. code:: text + + double precision, allocatable :: pt2_w (N_det_generators) + double precision, allocatable :: pt2_cw (0:N_det_generators) + double precision :: pt2_w_t + double precision :: pt2_u_0 + integer, allocatable :: pt2_n_0 (pt2_N_teeth+1) + + File: pt2_stoch_routines.irp.f + + + + + + +.. option:: pt2_w_t + + .. code:: text + + double precision, allocatable :: pt2_w (N_det_generators) + double precision, allocatable :: pt2_cw (0:N_det_generators) + double precision :: pt2_w_t + double precision :: pt2_u_0 + integer, allocatable :: pt2_n_0 (pt2_N_teeth+1) + + File: pt2_stoch_routines.irp.f + + + + + + +.. option:: pt2_n_tasks + + .. code:: text + + integer :: pt2_n_tasks + + File: pt2_stoch_routines.irp.f + + Number of parallel tasks for the Monte Carlo + + + + +.. option:: pt2_n_0 + + .. code:: text + + double precision, allocatable :: pt2_w (N_det_generators) + double precision, allocatable :: pt2_cw (0:N_det_generators) + double precision :: pt2_w_t + double precision :: pt2_u_0 + integer, allocatable :: pt2_n_0 (pt2_N_teeth+1) + + File: pt2_stoch_routines.irp.f + + + + + + +.. option:: pt2_n_tasks_max + + .. code:: text + + integer, allocatable :: pt2_f (N_det_generators) + integer :: pt2_n_tasks_max + + File: pt2_stoch_routines.irp.f + + + + + + +.. option:: pt2_n_teeth + + .. code:: text + + integer :: pt2_n_teeth + integer :: pt2_mindetinfirstteeth + + File: pt2_stoch_routines.irp.f + + + + + + +.. option:: initialize_pt2_e0_denominator + + .. code:: text + + logical :: initialize_pt2_e0_denominator + + File: energy.irp.f + + If true, initialize pt2_E0_denominator + + + + +.. option:: pt2_mindetinfirstteeth + + .. code:: text + + integer :: pt2_n_teeth + integer :: pt2_mindetinfirstteeth + + File: pt2_stoch_routines.irp.f + + + + + + +.. option:: pt2_stoch_istate + + .. code:: text + + integer :: pt2_stoch_istate + + File: pt2_stoch_routines.irp.f + + State for stochatsic PT2 + + diff --git a/docs/source/modules/hartree_fock.rst b/docs/source/modules/hartree_fock.rst index c9f73694..d594b412 100644 --- a/docs/source/modules/hartree_fock.rst +++ b/docs/source/modules/hartree_fock.rst @@ -95,3 +95,315 @@ EZFIO parameters If |true|, skip the (inactive+core) --> (active) and the (active) --> (virtual) orbital rotations within the |SCF| procedure Default: False + + +Providers +--------- + + +.. option:: fock_matrix_mo_alpha + + .. code:: text + + double precision, allocatable :: fock_matrix_mo_alpha (mo_tot_num,mo_tot_num) + + File: Fock_matrix.irp.f + + Fock matrix on the MO basis + + + + +.. option:: extrapolate_fock_matrix + + .. code:: text + + subroutine extrapolate_Fock_matrix( & + error_matrix_DIIS,Fock_matrix_DIIS, & + Fock_matrix_AO_,size_Fock_matrix_AO, & + iteration_SCF,dim_DIIS & + ) + + File: Roothaan_Hall_SCF.irp.f + + Compute the extrapolated Fock matrix using the DIIS procedure + + + + +.. option:: fock_matrix_ao_alpha + + .. code:: text + + double precision, allocatable :: fock_matrix_ao_alpha (ao_num,ao_num) + double precision, allocatable :: fock_matrix_ao_beta (ao_num,ao_num) + + File: Fock_matrix.irp.f + + Alpha Fock matrix in AO basis set + + + + +.. option:: hf_energy + + .. code:: text + + double precision :: hf_energy + + File: Fock_matrix.irp.f + + Hartree-Fock energy + + + + +.. option:: fock_matrix_diag_mo + + .. code:: text + + double precision, allocatable :: fock_matrix_mo (mo_tot_num,mo_tot_num) + double precision, allocatable :: fock_matrix_diag_mo (mo_tot_num) + + File: Fock_matrix.irp.f + + Fock matrix on the MO basis. For open shells, the ROHF Fock Matrix is + | F-K | F + K/2 | F | |---------------------------------| | F + K/2 | F | F - K/2 | |---------------------------------| | F | F - K/2 | F + K | + F = 1/2 (Fa + Fb) + K = Fb - Fa + + + + + +.. option:: fock_matrix_ao_beta + + .. code:: text + + double precision, allocatable :: fock_matrix_ao_alpha (ao_num,ao_num) + double precision, allocatable :: fock_matrix_ao_beta (ao_num,ao_num) + + File: Fock_matrix.irp.f + + Alpha Fock matrix in AO basis set + + + + +.. option:: hf_density_matrix_ao + + .. code:: text + + double precision, allocatable :: hf_density_matrix_ao (ao_num,ao_num) + + File: HF_density_matrix_ao.irp.f + + S^{-1}.P.S^{-1} where P = C.C^t + + + + +.. option:: fps_spf_matrix_ao + + .. code:: text + + double precision, allocatable :: fps_spf_matrix_ao (AO_num,AO_num) + + File: DIIS.irp.f + + Commutator FPS - SPF + + + + +.. option:: threshold_diis_nonzero + + .. code:: text + + double precision :: threshold_diis_nonzero + + File: DIIS.irp.f + + If threshold_DIIS is zero, choose sqrt(thresh_scf) + + + + +.. option:: ao_bi_elec_integral_alpha + + .. code:: text + + double precision, allocatable :: ao_bi_elec_integral_alpha (ao_num,ao_num) + double precision, allocatable :: ao_bi_elec_integral_beta (ao_num,ao_num) + + File: Fock_matrix.irp.f + + Alpha Fock matrix in AO basis set + + + + +.. option:: eigenvectors_fock_matrix_ao + + .. code:: text + + double precision, allocatable :: eigenvalues_fock_matrix_ao (AO_num) + double precision, allocatable :: eigenvectors_fock_matrix_ao (AO_num,AO_num) + + File: DIIS.irp.f + + Eigenvalues and eigenvectors of the Fock matrix over the AO basis + + + + +.. option:: fock_matrix_mo_beta + + .. code:: text + + double precision, allocatable :: fock_matrix_mo_beta (mo_tot_num,mo_tot_num) + + File: Fock_matrix.irp.f + + Fock matrix on the MO basis + + + + +.. option:: eigenvectors_fock_matrix_mo + + .. code:: text + + double precision, allocatable :: diagonal_fock_matrix_mo (mo_tot_num) + double precision, allocatable :: eigenvectors_fock_matrix_mo (ao_num,mo_tot_num) + + File: diagonalize_fock.irp.f + + Diagonal Fock matrix in the MO basis + + + + +.. option:: fock_matrix_mo + + .. code:: text + + double precision, allocatable :: fock_matrix_mo (mo_tot_num,mo_tot_num) + double precision, allocatable :: fock_matrix_diag_mo (mo_tot_num) + + File: Fock_matrix.irp.f + + Fock matrix on the MO basis. For open shells, the ROHF Fock Matrix is + | F-K | F + K/2 | F | |---------------------------------| | F + K/2 | F | F - K/2 | |---------------------------------| | F | F - K/2 | F + K | + F = 1/2 (Fa + Fb) + K = Fb - Fa + + + + + +.. option:: fps_spf_matrix_mo + + .. code:: text + + double precision, allocatable :: fps_spf_matrix_mo (mo_tot_num,mo_tot_num) + + File: DIIS.irp.f + + Commutator FPS - SPF in MO basis + + + + +.. option:: diagonal_fock_matrix_mo_sum + + .. code:: text + + double precision, allocatable :: diagonal_fock_matrix_mo_sum (mo_tot_num) + + File: diagonalize_fock.irp.f + + diagonal element of the fock matrix calculated as the sum over all the interactions with all the electrons in the RHF determinant diagonal_Fock_matrix_mo_sum(i) = sum_{j=1, N_elec} 2 J_ij -K_ij + + + + +.. option:: hf_density_matrix_ao_alpha + + .. code:: text + + double precision, allocatable :: hf_density_matrix_ao_alpha (ao_num,ao_num) + + File: HF_density_matrix_ao.irp.f + + S^{-1}.P_alpha.S^{-1} + + + + +.. option:: hf_density_matrix_ao_beta + + .. code:: text + + double precision, allocatable :: hf_density_matrix_ao_beta (ao_num,ao_num) + + File: HF_density_matrix_ao.irp.f + + S^{-1}.P_beta.S^{-1} + + + + +.. option:: eigenvalues_fock_matrix_ao + + .. code:: text + + double precision, allocatable :: eigenvalues_fock_matrix_ao (AO_num) + double precision, allocatable :: eigenvectors_fock_matrix_ao (AO_num,AO_num) + + File: DIIS.irp.f + + Eigenvalues and eigenvectors of the Fock matrix over the AO basis + + + + +.. option:: ao_bi_elec_integral_beta + + .. code:: text + + double precision, allocatable :: ao_bi_elec_integral_alpha (ao_num,ao_num) + double precision, allocatable :: ao_bi_elec_integral_beta (ao_num,ao_num) + + File: Fock_matrix.irp.f + + Alpha Fock matrix in AO basis set + + + + +.. option:: fock_matrix_ao + + .. code:: text + + double precision, allocatable :: fock_matrix_ao (ao_num,ao_num) + + File: Fock_matrix.irp.f + + Fock matrix in AO basis set + + + + +.. option:: diagonal_fock_matrix_mo + + .. code:: text + + double precision, allocatable :: diagonal_fock_matrix_mo (mo_tot_num) + double precision, allocatable :: eigenvectors_fock_matrix_mo (ao_num,mo_tot_num) + + File: diagonalize_fock.irp.f + + Diagonal Fock matrix in the MO basis + + diff --git a/docs/source/programmers_guide/index.rst b/docs/source/programmers_guide/index.rst index b33dde58..2bb06e7e 100644 --- a/docs/source/programmers_guide/index.rst +++ b/docs/source/programmers_guide/index.rst @@ -1,7 +1,9 @@ -================ -Index of Modules -================ +===================== +Index for programmers +===================== +Index of Modules +---------------- .. toctree:: :maxdepth: 1 @@ -10,3 +12,23 @@ Index of Modules /modules/* +Index of Providers +------------------ + +.. toctree:: + :maxdepth: 1 + :glob: + + /providers/* + + +Index of Subroutines/Functions +------------------------------ + +.. toctree:: + :maxdepth: 1 + :glob: + + /subroutines/* + + diff --git a/docs/source/programmers_guide/programming.rst b/docs/source/programmers_guide/programming.rst index 49cfeb52..01e62b94 100644 --- a/docs/source/programmers_guide/programming.rst +++ b/docs/source/programmers_guide/programming.rst @@ -1,11 +1,78 @@ +======================= Programming in the |qp| ======================= -To program in the |qp|, it is required that you are familiar with -the `IRPF90`_ code generator. A gitbook can be found -`here `_. +To program in the |qp|, it is required that you are familiar with the |IRPF90| +code generator. A GitBook can be found `here `_, +and programmers are encouraged to visit this manual. + +|IRPF90| make programming very simple. The only information a programmer needs +in order to write a new program is the name of the required |IRPF90| entities +which may already exist in other modules. For example, writing a program which +prints the Hartree-Fock energy is as simple as: + +.. code:: irpf90 + + program print_hf_energy + implicit none + BEGIN_DOC + ! Program which prints the Hartree-Fock energy + ! to the standard output + END_DOC + print *, 'HF energy = ', HF_energy + end +The only required information was the existence of a provider for +:command:`hf_energy`. A detailed list of all the providers, subroutines +and functions of the |qp| can be found in the appendix of this manual. + + + +Architecture +============ + +As |IRPF90| is used, the programmer doesn't have a full control of the sequence +of instructions in the produced Fortran code. This explains why the input data +is stored in a database rather than in sequential text files. Indeed, the +programmer can't know by advance in which order the files will be read, so a +simple random access to persistent data is needed. The |EZFIO| library generator +is a practical answer to this problem. + +The |qp| uses a collection of programs inter-operating together. Each of these +programs is reading and/or modifying information in the |EZFIO| database. +This is done mostly using the command line or scripting. + +.. important:: + + Each command modifies the state of the |EZFIO| database, so running twice the + same program on the same database may have different behaviors because of the + state of the database. For reproducibility, users are encouraged to run scripts + where a fresg new |EZFIO| database is created at the beginning of the + script. This way of running the |qp| makes calculations reproducible. + + +The computational part |qp| is organized in **modules**. A module is a +directory which contains multiple |IRPF90| files, a |README| and a |NEED| file. + +The |README| file contains documentation about the module, that is +automatically included in the documentation of the |qp|. The documentation is +generated by the `Sphinx documentation builder `_, +and it should be written using the |rst| format. + +The |NEED| file contains the list of the modules which are needed for the +current module. When a module is needed, it means that all the |IRPF90| files +it contains should be included in the current module. This is done +automatically during the building process, by creating symbolic links in the +current directory. + +To compile the program, the |Ninja| build system is used, and all the building +process is fully automated such that the programmer will never have to modify a +file by hand. Running :command:`ninja` inside a module will compile only the +module, and running :command:`ninja` at the root of the |qp| will build all the +modules, as well as the tools. + +.. cache compile .. interface AOs / MOs => resultsFile .. interface integrals => AO / MO .. interface integrals MO => FCIDUMP