read_in {
-- options
}
- Returns:
a system object.
A generic system, including atoms and molecules, can be specified by providing a file containing information about the single-particle basis set and the one- and two-body integrals between these basis functions. This file is in FCIDUMP format [Knowles89], which can be produced by several quantum chemistry packages including MOLPRO, Q-Chem (via additions from Alex Thom) and PSI4 (via a plugin from James Spencer). See generating_integrals
for more details.
sys
type: system object produced by a previous call.
Optional.
If provided, a previously created system object is updated with the new settings supplied, otherwise a new system object is created.
electrons
type: integer.
Optional. If specified, then
ms
must be specified.Number of electrons in the unit cell. If not provided, the value in the FCIDUMP file is used.
ms
type: integer.
Optional. If specified, then
electrons
must be specified.Set the spin polarisation of the system in units of electron spin (i.e. a single electron can take values 1 or -1). If not provided, the value in the FCIDUMP file is used.
sym
type: integer or string.
Optional. Default:
aufbau
.Set the symmetry of the system if a reference determinant is not provided. This can be set to:
- An integer specifying the index of a specific irreducible representation from the FCIDUMP file; see the output produced by creating a system for possible values.
aufbau
. Uses the symmetry of a determinant selected using the Aufbau principle.tot_sym
. Uses the totally symmetric representation, whatever its index may be.;
Lz
type: boolean.
Optional. Default: false.
If true, enable Lz symmetry. See below for details.
int_file
type: string.
Optional. Default: 'FCIDUMP'.
Specify the FCIDUMP file containing the integrals and information relating to the single-particle basis. For details of the format see
fcidump_format
. This can also be an HDF5 file previously produced by HANDE from a FCIDUMP via thewrite_read_in_system
function (seeutils_hdf5_system_dump
), which is both more compact in size and considerably faster to process.dipole_int_file
type: string.
Optional. No default.
Specify a FCIDUMP-like file containing the dipole integrals, i.e. ⟨i|x|i⟩, in a given direction.
Not currently used.
CAS
type: 2D-vector of integers.
Optional. No default.
If specified, then the basis set is restricted to a given complete active space, whereby
CAS = {N,M}
corresponds to allowing only N electrons to be distributed among 2M spin orbitals. Any additional electrons are 'frozen' (i.e. forced to be in the lowest spin orbitals) and any additional high-energy spin orbitals are removed from the basis set.Warning
This functionality is not compatible with reading from an HDF5 file; to use a CAS in combination with HDF5 initialisation, create the HDF5 file using a system with the desired CAS.
verbose
type: boolean.
Optional. Default: true.
Print out the single-particle basis set.
complex
type: boolean.
Optional. Default: false.
Specify if the calculation should use complex dynamics in any calculation performed, and if the FCIDUMP supplied is complex-formatted. Currently compatible with fci, fciqmc, ccmc and dmqmc (including ip-dmqmc) calculations.
max_integral_chunk
type: integer
Optional. Default 231 − 1.
Maximum number of MPI objects to broadcast in a single call for two body integrals. Above this value a contiguous MPI type is used instead.
Warning
This functionality is included only for ease of testing. It should not be used for production calculations.
For cylindrically symmetrical systems, the Lz (z-component of orbital angular momentum) operator commutes with the Hamiltonian, and this can be a convenient symmetry to conserve. Lz is measured in units of ℏ. Normal FCIDUMP files do not contain orbitals which are eigenfunctions of the Lz operator, so they must be transformed using post-processing.
SYMLZ give the eigenvalue of Lz (the ml value). Orbitals with defined values of Lz are likely to be complex-valued, but luckily the integrals involving them are not, so althoughthe FCIDUMP file must be translated, it still retains the same format (see comments in src/read_in.F90
, src/molecular_integrals.F90
and fcidump_format
for details if you wish to create FCIDUMP files by other means).
The FCIDUMP file header format has been modified to include additional parameters: SYML, and SYMLZ which have a list of values, one for each orbital.
SYML gives the magnitude of L for the orbital if known (or -20 if not) but is not used.
Note
There is a tool provided in tools/fcidump/lz_fcidump.py
that can generate Lz-transformed FCIDUMPs from PySCF calculations. To run this script, you need to:
- compile the
lz_transform.f90
Fortran script, - have PySCF,
- install a Python package called
f90nml
.
See the comments within the Python script for further help.
Warning
These transformed integral files require you to enforce Lz symmetry and will produce incorrect results if you do not.