.. _running:
Running TCHInt calculations
===========================
TCHInt can be used in two modes:
* Calculating a complete set of integrals for a given system.
* Calculating specific integrals on the fly using partially evaluated
integrals and resolution of identity, passing them to a calling
code.
The first mode can also be used for standalone calculation of 2-body
integrals of given potentials
Input files
^^^^^^^^^^^
Both the standalone program and the library use the following input
files at runtime, they have to be present in the working directory:
* ``input.molden``: The molden file containing the geometry, basis set
and MO coefficients. Symmetry is taken from the molden file.
* ``parameters.*``: parameter file for the Jastrow factor. Depending
on the factor, it comes with .casl (CASINO), .QMCJF (NTChem) or .at
(intrinsic) extension. Is not needed for 2-body potential integrals.
* ``tchint.json``: optional JSON file for configuring tchint. Has the
following entries:
* "mode": defines how the integrals shall be evaluated. The
available modes are:
* "direct" (default): Precompute all integrals and store them in
memory. The integrals are written to disk (see "storage" below)
and read back at repeated calls.
* "calc": Always use on-the-fly integration when passing integrals
to calling code. Partially evaluated precomputed components are
written to disk and reused if available (see "storage" below).
* "ri": Use resolution of identity (RI) or on-the-fly integration
when evaluating integrals for calling code, depending on the
integral. Partially evaluated precomputed components as well as
resolution of identity components are written to disk and reused
if available (see "storage" below).
* "grid_lvl": PySCF's grid density parameter, on a scale from `0`
(coarse, default) to `9` (fine). A value of `2` ought to be
accurate for most purposes.
* "grid_prune": PySCF's grid pruning type, which can be set to
`"none"` (default, recommended), `"nwchem"`, `"sg1"`, or
`"treutler"` for different pruning algorithms.
* "jastrow": Jastrow factor implementation, can be set to:
* "casino" (default): use the CASINO Jastrow factor included in
TCHInt. Requires the parameters in the ``parameters.casl`` file.
* "r4qmc": use the NTChem/R4QMC factor. This is not included in
TCHInt and requires linking with an installed NTChem library.
The parameters are read from the ``parameters.QMCJF`` file.
* "atomic": use the internal TCHInt Jastrow factor implementation,
requires the ``parameters.at`` parameter file, see
:ref:`intrinsic` for details.
* "none": use a dummy Jastrow factor implementation returning J=0,
equivalent to having no Jastrow factor; this is mainly useful
for debugging purposes.
* "lmat_sparse": whether to use sparse (`true`) or dense (`false`,
default) storage for the L matrix. The sparse storage
implementation uses twice as much memory per element as the
dense storage, so the L matrix should be <50% dense for the
sparse storage to provide a reduced memory footprint.
* "lmat_threshold": value below which L matrix elements are flushed
to zero (`1e-10` by default). NB, increasing this value will make
the L matrix sparser. This keyword has no effect on L matrices
loaded from HDF5 files - the sparsity is fixed by the value of
"lmat_threshold" when the file was generated.
* "ukmat_threshold": value below which U+K matrix elements are
flushed to zero (`1e-10` by default).
* "exclude_6index": whether to exclude integrals in the TCDUMP
where all 6 indices are distinct (`false` by default; i.e., these
integrals are included by default). Note that all integrals
connecting the reference determinant with its triple excitations
are always included in the TCDUMP regardless of the value of this
flag - in other words, integrals with 6 distinct indices 3 of which
have values less than or equal to the number of occupied spatial
orbitals are never omitted.
* "nelec": number of electrons in the system; set to `0` to
autodetect from molden file (`0` by default).
* "spin": number of up- minus number of down-spin electrons (`0` by
default if `nelec` is even, `1` if `nelec` is odd). Note that if
`nelec` is `0` then `spin` is also autodetected from the molden
file and the input value is ignored.
* "norb_freeze": number of low-energy *spatial* orbitals to freeze
and electrons *per spin* to remove (`0` by default).
* "norb_delete": number of high-energy *spatial* orbitals to delete
(`0` by default).
* "pbc": flags the use of periodic boundary conditions and contains
the following fields:
* "lattice": a set of *periodicity* vectors of size
*dimensionality* (these are both typically three) defining the
lattice vectors
* "units": can be set to `"bohr"` (default) or `"angstrom"`,
defining the units used for "lattice"
* "mesh": a set of 3 integers determining the number of
Monkhorst-Pack FFT-mesh points to use in each direction
* "grid_type": selects which integration grid to request from
PySCF - this can take the values `"becke"`, `"uniform"` or
`"molecular"`
* "integrals": calculate the integrals of a 2-body potential instead
of the transcorrelated Hamiltonian. Has two fields:
* "type": Type of the potential, available are `"yukawa"` and
`"erf"`. Has to be present to do the potential integration
* "tau": Parameter of the potential, defaults to `1.0`
* "storage": Set the format in which the full integrals are stored.
If not specified, the format is decided depending on which files
are present, or using the default value if no relevant files are
present. Available modes are:
* "hdf5": HDF5 format (requires building with HDF5 support, in
which case this is the default value of "storage"); precomputed
integrals are stored in `tcdump.h5` and intermediate integrals
and RI components are stored in `tcfactors.h5`.
* "ascii": ASCII format; precomputed integrals are stored in
`TCDUMP` and intermediate integrals and RI components are stored
in `tcfactors`.
* "write_bare_fcidump" : Toggles write of FCIDUMP.bare.
Defaults to false.
* "fcidump_storage": Set the format in which the 0/1/2-electron
integrals are stored. If not specified, the format is decided
depending on which files are present, or using the default value
if no relevant files are present. Available modes are:
* "ascii": ASCII format (default); bare integrals are read from
`FCIDUMP.bare` and trascorrelated integrals are read
from/written to `FCIDUMP`.
* "trexio.ascii": TREXIO in ASCII format (requires building with
TREXIO support); bare integrals are read from
`fcidump.bare.trexio`, and trascorrelated integrals are read
from/written to `fcidump.trexio`.
* "trexio.hdf5": TREXIO in HDF5 format (requires building with
TREXIO support, and having built TREXIO with HDF5 support); bare
integrals are read from `fcidump.bare.trexio.h5`, and
trascorrelated integrals are read from/written to
`fcidump.trexio.h5`.
* "xy_perf_level": integer determining which implementation of the
"integrals of the Jastrow factor" routine to use - can be either 0
for the unoptimized version or 1 for the optimized version
(default). In tests, level 1 appear to be the optimal choice
for code compiled with the Intel compiler against the Intel MKL
library; note however that level 0 has been found to be
advantageous if the GNU compiler and a generic BLAS library is
used.
* "kmat_perf_level": integer determining which implementation of the
K matrix evaluation routine to use - can be either 0 for the
unoptimized version or 1 for the optimized version (default).
* "lmat_perf_level": integer determining which implementation of the
L matrix evaluation routine to use - can be 0 for the unoptimized
version, 1 for an optimized version which uses memory
conservatively (default), or 2 for a fully optimized version with
significant memory requirements.
* "lmat_mean_field": Toggles use of mean-field approximation for
L matrix. Defaults to false. If true, mean-field contributions
are added to 0-, 1- and 2-body integrals before write of FCIDUMP.
The L matrix is never be explicitly evaluated and consequently
no TCDUMP will be generated.
* "spin_averaged_mean_field" : Toggles spin-averaged approximation
in mean-field approximation of the L matrix, i.e. use of closed
shell code even for open shell systems. Defaults to false.
* "lmat_mean_field_force_open_shell" : Forces use of open shell
code in mean-field approximation to L matrix even for closed shell
system. Defaults to false.
* "lmat_mean_field_dens_file" : File from which density for use
in mean-field approximation to the L matrix is to be read. Uses
Molpro matrop format. If not given, HF density is used.
* "lmat_mean_field_perf_level": integer determining which
implementation of the mean-field contraction routines to use - can
be 0 for the unoptimized version or 1 for the optimized version
(default).
* "mean_field_storage": Set the format in which the 0/1/2-electron
integrals after application of mean-field approximation to the
L matrix are stored. Defaults to ASCII format. Available modes are:
* "ascii": ASCII format (default); bare integrals are read from
`FCIDUMP.bare` and trascorrelated integrals are read
from/written to `FCIDUMP`.
* "npy" : NPY format; Header is written to FCIDUMP and integrals
are written to .npy files specified in HEADER.
* "npy_and_ascii" : NPY format and ASCII format; FCIDUMP includes
header specifying .npy files containing integrals as well as
integrals
* "norb_mean_field_freeze": number of low-energy *spatial* orbitals
to freeze and electrons *per spin* to remove (`0` by default)
after application of mean-field approximation to L matrix.
Incompatible with norb_freeze!=0 and norb_delete!=0.
* "kmat_save_memory": Boolean variable deciding whether to use a
memory-saving strategy for the evaluation of two-body integrals
which however doubles the number of Jastrow factor evaluations.
The default is `true`. This only has an effect on the unoptimized
routine, i.e., only when `"xy_perf_level": 0`.
* "auxbasis": Auxiliary basis set for resolution of identity (RI)
mode. Default is `"weigend"`.
* "lmat_4ind_buffer": Boolean variable determining whether to buffer
all 4-distinct-index 6-index matrices in dense storage in
on-the-fly operation modes. The default is `true`.
* "lmat_6ind_buffer_size": size in MiB per process of the sparse
hash-table buffer of 5- and 6-index integrals for on-the-fly
operation modes. Values <= 0 disable this buffer. The default is
`100`.
* "lmat_CS_rel_thres": magnitude of smallest Cauchy-Schwartz upper
bound of matrix element (relative to largest) to be calculated in
on-the-fly operation modes. Values <= 0 disable CS bound checks.
The default is `1e-7`.
* "lmat_CS_dump": whether to produce a dump of Cauchy-Schwartz upper
bound of L matrix elements to a file called `lmat_CS_dump.dat`.
The default is `false`.
* "lmat_hist": Boolean variable determining whether to produce a
file "lmat.hist" with histogram information of 6-index matrix
elements requested during an on-the-fly calculation. The default
is `false`.
* "memory_logfile": name of file to log memory allocations to.
The default is an empty string, which disables memory logging.
* "split_nodes": integer variable specifying how many "virtual
nodes" to split each physical node into. This is inteded for
debugging, enabling multi-node codepaths in single-node systems.
The default is `1`, which disables the functionality.
An example file to do resolution of identity with a cc-pVDZ auxiliary
basis set and an intrinsic Jastrow on a medium grid could look like
this:
.. code-block:: json
{
"jastrow" : "atomic" ,
"auxbasis": "cc-pVDZ",
"mode" : "ri" ,
"grid_lvl": 4
}
.. _intrinsic:
The intrinsic Jastrow implementation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
TCHInt comes with its own implementation of a Jastrow factor,
following a general polynomial form including electron-electron,
electron-nuclear and electron-electron-nuclear terms.
The corresponding parameter files have the following form:
.. code-block:: none
en_str
r_1 r_2 ...
ee_str
e_1 e_2 ...
n_1 m_1 l_1 c_1 at_1_1 at_2_1
...
n_N m_N l_N c_N at_1_N at_2_N
where ``en_str`` is a string determining the form of the electron-nuclear terms,
``ee_str`` is a string determining the form of the electron-electron terms,
``r_i`` are parameters for the effective nuclear-electron
distances and ``e_i`` the parameters for the effective nuclear-nuclear
distances. At the moment, the following forms are supported:
.. code-block:: none
polynomial
exponential
gaussian
erf
Alternatively, the first four lines may be replaced by a single line ``r e``.
In this case, it defaults exponential forms. Values of 0 lead to a polynomial
effective distance instead of the exponential form.
The exponents ``n_i`` and ``m_i`` are the electron-nuclear exponents,
the exponents ``l_i`` are those of the electron-electron factors and
the coefficients ``c_i`` are the coefficients of the ``i``-th term.
The electron-nuclear distances of term ``i`` refer to atoms ``at_1_i``
and ``at_2_i``, in the numbering of the ``input.molden`` file.