User input reference¶

Keywords without a default value are required.
Default values are either explicit or computed from the value of other keywords in the input.
Sections where all keywords have a default value can be omitted.
Predicates, if present, are the functions run to validate user input.

Keywords

world_prec:

Overall relative precision in the calculation.

Type float

Predicates

1.0e-10 < value < 1.0

world_size:

Total size of computational domain given as 2**(world_size). Always cubic and symmetric around the origin. Negative value means it will be computed from the molecular geometry.

Type int

Default -1

Predicates

value <= 10

world_unit:

Length unit for all coordinates given in user input. Everything will be converted to atomic units (bohr) before the main executable is launched, so the JSON input is always given in bohrs.

Type str

Default bohr

Predicates

value.lower() in ["bohr", "angstrom"]

world_origin:

Global gauge origin of the calculation.

Type List[float]

Default [0.0, 0.0, 0.0]

Predicates

len(value) == 3

Sections

Precisions:

Define specific precision parameters.

Keywords

exchange_prec:

Precision parameter used in construction of Exchange operators. Negative value means it will follow the dynamic precision in SCF.

Type float

Default -1.0

helmholtz_prec:

Precision parameter used in construction of Helmholtz operators. Negative value means it will follow the dynamic precision in SCF.

Type float

Default -1.0

poisson_prec:

Precision parameter used in construction of Poisson operators.

Type float

Default user['world_prec']

Predicates

1.0e-10 < value < 1.0

nuclear_prec:

Precision parameter used in smoothing and projection of nuclear potential.

Type float

Default user['world_prec']

Predicates

1.0e-10 < value < 1.0

Printer:

Define variables for printed output.

Keywords

print_level:

Level of detail in the written output. Level 0 for production calculations, negative level for complete silence.

Type int

Default 0

print_mpi:

Write separate output from each MPI to file called <file_name>-<mpi-rank>.out.

Type bool

Default False

print_prec:

Number of digits in property output (energies will get twice this number of digits).

Type int

Default 6

Predicates

0 < value < 10

print_width:

Line width of printed output (in number of characters).

Type int

Default 75

Predicates

50 < value < 100

print_constants:

Print table of physical constants used by MRChem.

Type bool

Default False

Plotter:

Give details regarding the density and orbital plots. Three types of plots are available, line, surface and cube, and the plotting ranges are defined by three vectors (A, B and C) and an origin (O): line: plots on line spanned by A, starting from O. surf: plots on surface spanned by A and B, starting from O. cube: plots on volume spanned by A, B and C, starting from O.

Keywords

path:

File path to plot directory.

Type str

Default plots

Predicates

value[-1] != '/'

type:

Type of plot: line (1D), surface (2D) or cube (3D).

Type str

Default cube

Predicates

value.lower() in ['line', 'surf', 'cube']

points:

Number of points in each direction on the cube grid.

Type List[int]

Default [20, 20, 20]

Predicates

all(p > 0 for p in value)
not (user['Plotter']['type'] == 'line' and len(value) < 1)
not (user['Plotter']['type'] == 'surf' and len(value) < 2)
not (user['Plotter']['type'] == 'cube' and len(value) < 3)

O:

Origin of plotting ranges.

Type List[float]

Default [0.0, 0.0, 0.0]

Predicates

len(value) == 3

A:

First boundary vector for plot.

Type List[float]

Default [1.0, 0.0, 0.0]

Predicates

len(value) == 3

B:

Second boundary vector for plot.

Type List[float]

Default [0.0, 1.0, 0.0]

Predicates

len(value) == 3

C:

Third boundary vector for plot.

Type List[float]

Default [0.0, 0.0, 1.0]

Predicates

len(value) == 3

MPI:

Define MPI related parameters.

Keywords

numerically_exact:

This will use MPI algorithms that guarantees that the output is invariant wrt the number of MPI processes.

Type bool

Default False

shared_memory_size:

Size (MB) of the MPI shared memory blocks of each shared function.

Type int

Default 10000

share_nuclear_potential:

This will use MPI shared memory for the nuclear potential.

Type bool

Default False

share_coulomb_potential:

This will use MPI shared memory for the Coulomb potential.

Type bool

Default False

share_xc_potential:

This will use MPI shared memory for the exchange-correlation potential.

Type bool

Default False

bank_size:

Number of MPI processes exclusively dedicated to manage orbital bank.

Type int

Default -1

Basis:

Define polynomial basis.

Keywords

order:

Polynomial order of multiwavelet basis. Negative value means it will be set automatically based on the world precision.

Type int

Default -1

type:

Polynomial type of multiwavelet basis.

Type str

Default interpolating

Predicates

value.lower() in ['interpolating', 'legendre']

Derivatives:

Define various derivative operators used in the code.

Keywords

kinetic:

Derivative used in kinetic operator.

Type str

Default abgv_55

h_b_dip:

Derivative used in magnetic dipole operator.

Type str

Default abgv_00

h_m_pso:

Derivative used in paramagnetic spin-orbit operator.

Type str

Default abgv_00

Molecule:

Define molecule.

Keywords

charge:

Total charge of molecule.

Type int

Default 0

multiplicity:

Spin multiplicity of molecule.

Type int

Default 1

Predicates

value > 0

translate:

Translate coordinates such that center of mass coincides with the global gauge origin.

Type bool

Default False

coords:

Coordinates in xyz format. Atoms can be given either using atom symbol or atom number

Type str

WaveFunction:

Define the wavefunction method.

Keywords

method:

Wavefunction method. See predicates for valid methods. hf, hartreefock and hartree-fock all mean the same thing, while lda is an alias for svwn5. You can set a non-standard DFT functional (e.g. varying the amount of exact exchange) by choosing dft and specifing the functional(s) in the DFT section below.

Type str

Predicates

value.lower() in ['core', 'hartree', 'hf', 'hartreefock', 'hartree-fock', 'dft', 'lda', 'svwn3', 'svwn5', 'pbe', 'pbe0', 'bpw91', 'bp86', 'b3p86', 'b3p86-g', 'blyp', 'b3lyp', 'b3lyp-g', 'olyp', 'kt1', 'kt2', 'kt3']

restricted:

Use spin restricted wavefunction.

Type bool

Default True

environment:

Set method for treatment of environment. none for vacuum calculation. PCM for Polarizable Continuum Model, which will activate the PCM input section for further parametrization options.

Type str

Default none

Predicates

value.lower() in ['none', 'pcm']

DFT:

Define the exchange-correlation functional in case of DFT.

Keywords

density_cutoff:

Hard cutoff for passing density values to XCFun.

Type float

Default 0.0

functionals:

List of density functionals with numerical coefficient. E.g. for PBE0 EXX 0.25, PBEX 0.75, PBEC 1.0, see XCFun documentation <https://xcfun.readthedocs.io/>_.

Type str

Default `` ``

spin:

Use spin separated density functionals.

Type bool

Default not(user['WaveFunction']['restricted'])

Properties:

Provide a list of properties to compute (total SCF energy and orbital energies are always computed).

Keywords

dipole_moment:

Compute dipole moment.

Type bool

Default True

quadrupole_moment:

Compute quadrupole moment. Note: Gauge origin dependent, should be used with translate = true in Molecule.

Type bool

Default False

polarizability:

Compute polarizability tensor.

Type bool

Default False

magnetizability:

Compute magnetizability tensor.

Type bool

Default False

nmr_shielding:

Compute NMR shielding tensor.

Type bool

Default False

geometric_derivative:

Compute geometric derivative.

Type bool

Default False

plot_density:

Plot converged electron density.

Type bool

Default False

plot_orbitals:

Plot converged molecular orbitals from list of indices, negative index plots all orbitals.

Type List[int]

Default []

ExternalFields:

Define external electromagnetic fields.

Keywords

electric_field:

Strength of external electric field.

Type List[float]

Default []

Predicates

len(value) == 0 or len(value) == 3

Polarizability:

Give details regarding the polarizability calculation.

Keywords

frequency:

List of external field frequencies.

Type List[float]

Default [0.0]

NMRShielding:

Give details regarding the NMR shileding calculation.

Keywords

nuclear_specific:

Use nuclear specific perturbation operator (h_m_pso).

Type bool

Default False

nucleus_k:

List of nuclei to compute. Negative value computes all nuclei.

Type List[int]

Default [-1]

Files:

Defines file paths used for program input/output. Note: all paths must be given in quotes if they contain slashes “path/to/file”.

Keywords

guess_basis:

File name for GTO basis set, used with gto guess.

Type str

Default initial_guess/mrchem.bas

guess_gto_p:

File name for paired orbitals, used with gto guess.

Type str

Default initial_guess/mrchem.mop

guess_gto_a:

File name for alpha orbitals, used with gto guess.

Type str

Default initial_guess/mrchem.moa

guess_gto_b:

File name for beta orbitals, used with gto guess.

Type str

Default initial_guess/mrchem.mob

guess_phi_p:

File name for paired orbitals, used with mw guess. Expected path is ``<path_orbitals>/phi_p_scf_idx_<0…Np>_<re/im>.mw

Type str

Default initial_guess/phi_p

guess_phi_a:

File name for alpha orbitals, used with mw guess. Expected path is ``<path_orbitals>/phi_a_scf_idx_<0…Na>_<re/im>.mw

Type str

Default initial_guess/phi_a

guess_phi_b:

File name for beta orbitals, used with mw guess. Expected path is ``<path_orbitals>/phi_b_scf_idx_<0…Nb>_<re/im>.mw

Type str

Default initial_guess/phi_b

guess_x_p:

File name for paired response orbitals, used with mw guess. Expected path is ``<path_orbitals>/x_p_rsp_idx_<0…Np>_<re/im>.mw

Type str

Default initial_guess/X_p

guess_x_a:

File name for alpha response orbitals, used with mw guess. Expected path is ``<path_orbitals>/x_a_rsp_idx_<0…Na>_<re/im>.mw

Type str

Default initial_guess/X_a

guess_x_b:

File name for beta response orbitals, used with mw guess. Expected path is ``<path_orbitals>/x_b_rsp_idx_<0…Nb>_<re/im>.mw

Type str

Default initial_guess/X_b

guess_y_p:

File name for paired response orbitals, used with mw guess. Expected path is ``<path_orbitals>/y_p_rsp_idx_<0…Np>_<re/im>.mw

Type str

Default initial_guess/Y_p

guess_y_a:

File name for alpha response orbitals, used with mw guess. Expected path is ``<path_orbitals>/y_a_rsp_idx_<0…Na>_<re/im>.mw

Type str

Default initial_guess/Y_a

guess_y_b:

File name for beta response orbitals, used with mw guess. Expected path is ``<path_orbitals>/y_b_rsp_idx_<0…Nb>_<re/im>.mw

Type str

Default initial_guess/Y_b

guess_cube_p:

File name for paired orbitals, used with cube guess. Expected path is ``<path_orbitals>/phi_p_scf_idx_<0…Np>_<re/im>.cube

Type str

Default initial_guess/phi_p

guess_cube_a:

File name for alpha orbitals, used with cube guess. Expected path is ``<path_orbitals>/phi_a>_scf_idx_<0…Na>_<re/im>.cube

Type str

Default initial_guess/phi_a

guess_cube_b:

File name for beta orbitals, used with cube guess. Expected path is ``<path_orbitals>/phi_b_scf_idx_<0…Nb>_<re/im>.cube

Type str

Default initial_guess/phi_b

cube_vectors:

Directory where cube vectors are stored for mrchem calculation.

Type str

Default cube_vectors/

SCF:

Includes parameters related to the ground state SCF orbital optimization.

Keywords

run:

Run SCF solver. Otherwise properties are computed on the initial orbitals.

Type bool

Default True

max_iter:

Maximum number of SCF iterations.

Type int

Default 100

kain:

Length of KAIN iterative history.

Type int

Default 5

rotation:

Number of iterations between each diagonalization/localization.

Type int

Default 0

localize:

Use canonical or localized orbitals.

Type bool

Default False

energy_thrs:

Convergence threshold for SCF energy.

Type float

Default -1.0

guess_prec:

Precision parameter used in construction of initial guess.

Type float

Default 0.001

Predicates

1.0e-10 < value < 1.0

guess_screen:

Screening parameter used in GTO evaluations, in number of standard deviations. Every coordinate beyond N StdDev from the Gaussian center is evaluated to zero. Note that too aggressive screening is counter productive, because it leads to a sharp cutoff in the resulting function which requires higher grid refinement. Negative value means no screening.

Type float

Default 12.0

start_prec:

Incremental precision in SCF iterations, initial value.

Type float

Default -1.0

final_prec:

Incremental precision in SCF iterations, final value.

Type float

Default -1.0

guess_type:

Type of initial guess for ground state orbitals. chk restarts a previous calculation which was dumped using the write_checkpoint keyword. This will load MRA and electron spin configuration directly from the checkpoint files, which are thus required to be identical in the two calculations. mw will start from final orbitals in a previous calculation written using the write_orbitals keyword. The orbitals will be re-projected into the new computational setup, which means that the electron spin configuration and MRA can be different in the two calculations. gto reads precomputed GTO orbitals (requires extra non-standard input files for basis set and MO coefficients). core and sad will diagonalize the Fock matrix in the given AO basis (SZ, DZ, TZ or QZ) using a Core or Superposition of Atomic Densities Hamiltonian, respectively.

Type str

Default sad_dz

Predicates

value.lower() in ['mw', 'chk', 'gto', 'core_sz', 'core_dz', 'core_tz', 'core_qz', 'sad_sz', 'sad_dz', 'sad_tz', 'sad_qz', 'sad_gto', 'cube']

write_checkpoint:

Write orbitals to disk in each iteration, file name <path_checkpoint>/phi_scf_idx_<0..N>. Can be used as chk initial guess in subsequent calculations. Note: must be given in quotes if there are slashes in the path “path/to/checkpoint”.

Type bool

Default False

path_checkpoint:

Path to checkpoint files during SCF, used with write_checkpoint and chk guess.

Type str

Default checkpoint

Predicates

value[-1] != '/'

write_orbitals:

Write final orbitals to disk, file name <path_orbitals>/phi_<p/a/b>_scf_idx_<0..Np/Na/Nb>. Can be used as mw initial guess in subsequent calculations.

Type bool

Default False

path_orbitals:

Path to where converged orbitals will be written in connection with the write_orbitals keyword. Note: must be given in quotes if there are slashes in the path “path/to/orbitals”.

Type str

Default orbitals

Predicates

value[-1] != '/'

orbital_thrs:

Convergence threshold for orbital residuals.

Type float

Default 10 * user['world_prec']

Response:

Includes parameters related to the response SCF optimization.

Keywords

run:

In which Cartesian directions to run response solver.

Type List[bool]

Default [True, True, True]

max_iter:

Maximum number of response iterations.

Type int

Default 100

kain:

Length of KAIN iterative history.

Type int

Default 5

property_thrs:

Convergence threshold for symmetric property. Symmetric meaning the property computed from the same operator as the response purturbation, e.g. for external magnetic field the symmetric property corresponds to the magnetizability (NMR shielding in non-symmetric, since one of the operators is external magnetic field, while the other is nuclear magnetic moment).

Type float

Default -1.0

start_prec:

Incremental precision in SCF iterations, initial value.

Type float

Default -1.0

final_prec:

Incremental precision in SCF iterations, final value.

Type float

Default -1.0

guess_prec:

Precision parameter used in construction of initial guess.

Type float

Default 0.001

Predicates

1.0e-10 < value < 1.0

guess_type:

Type of initial guess for response. none will start from a zero guess for the response functions. chk restarts a previous calculation which was dumped using the write_checkpoint keyword. mw will start from final orbitals in a previous calculation written using the write_orbitals keyword. The orbitals will be re-projected into the new computational setup.

Type str

Default none

Predicates

value.lower() in ['none', 'chk', 'mw']

write_checkpoint:

Write perturbed orbitals to disk in each iteration, file name <path_checkpoint>/<X/Y>_rsp_<direction>_idx_<0..N>. Can be used as chk initial guess in subsequent calculations.

Type bool

Default False

path_checkpoint:

Path to checkpoint files during SCF, used with write_checkpoint and chk guess.

Type str

Default checkpoint

Predicates

value[-1] != '/'

write_orbitals:

Write final perturbed orbitals to disk, file name <path_orbitals>/<X/Y>_<p/a/b>_rsp_<direction>_idx_<0..Np/Na/Nb>. Can be used as mw initial guess in subsequent calculations.

Type bool

Default False

path_orbitals:

Path to where converged orbitals will be written in connection with the write_orbitals keyword.

Type str

Default orbitals

Predicates

value[-1] != '/'

orbital_thrs:

Convergence threshold for orbital residuals.

Type float

Default 10 * user['world_prec']

localize:

Use canonical or localized unperturbed orbitals.

Type bool

Default user['SCF']['localize']

PCM:

Includes parameters related to the computation of the reaction field energy of a system in an environment within the Polarizable Continuum Model.

Sections

SCRF:

Parameters for the Self-Consistent Reaction Field optimization.

Keywords

max_iter:

Max number of iterations allowed in the nested procedure.

Type int

Default 100

dynamic_thrs:

Set the convergence threshold for the nested procedure. true will dynamically tighten the convergence threshold based on the absolute value of the latest orbital update as. When the orbitals are close to convergence (mo_residual < world_prec*10) the convergence threshold will be set equal to world_prec. false uses world_prec as convergence threshold throughout.

Type bool

Default True

optimizer:

Choose which function to use in the KAIN solver, the surface charge density (gamma) or the reaction potential (V_R).

Type str

Default potential

Predicates

value.lower() in ['density', 'potential']

density_type:

What part of the total molecular charge density to use in the algorithm. total uses the total charge density. nuclear uses only the nuclear part of the total charge density. electronic uses only the electronic part of the total charge density.

Type str

Default total

Predicates

value.lower() in ['total', 'nuclear', 'electronic']

kain:

Number of previous reaction field iterates kept for convergence acceleration during the nested precedure.

Type int

Default user['SCF']['kain']

Cavity:

Define the interlocking spheres cavity.

Keywords

mode:

Determines how to set up the interlocking spheres cavity. atoms: centers are taken from the molecular geometry, radii taken from tabulated data (van der Waals radius), and rescaled using the parameters alpha, beta and sigma (R_i <- alpha*R_i + beta*sigma). Default spheres can be modified and/or extra spheres added, using the $spheres section, see documentation. explicit: centers and radii given explicitly in the spheres block.

Type str

Default atoms

Predicates

value.lower() in ['atoms', 'explicit']

spheres:

This input parameter affects the list of spheres used to generate the cavity. In all cases, values for the radius, the radius scaling factor (alpha), the width (sigma), and the width scaling factor (beta) can be modified. If they are not specified their global default values are used. In atoms mode, we modify the default list of spheres, built with centers from the molecular geometry and radii from internal tabulated van der Waals values. To substitute a sphere, include a line like: $spheres i R [alpha] [beta] [sigma] $end to specify that the i atom in the molecule (0-based indexing) should use radius R instead of the pre-tabulated vdW radius. To add a sphere, include a line like: $spheres x y z R [alpha] [beta] [sigma] $end to specify that a sphere of radius R should be added at position (x, y, z). Spheres added in this way are not aware of their parent atom, if any. They will not contribute to the molecular gradient. In explicit mode, we build the complete sphere list from scratch. You can add a line like: $spheres x y z R [alpha] [beta] [sigma] $end to specify that a sphere of radius R should be added at position (x, y, z). Spheres added in this way are not aware of their parent atom, if any. They will not contribute to the molecular gradient. Alternatively, you can specify a line like: $spheres i R [alpha] [beta] [sigma] $end to specify that the i atom in the molecule (0-based indexing) should use radius R. Spheres added in this way are aware of their parent atom. They will contribute to the molecular gradient.

Type str

Default ````

alpha:

Scaling factor on the radius term for the cavity rescaling (R_i <- alpha*R_i + beta*sigma). Only used for the default vdW radii in atoms mode, not if explicit $spheres are given.

Type float

Default 1.1

beta:

Scaling factor on the boundary width term for the cavity rescaling (R_i <- alpha*R_i + beta*sigma). Only used for the default vdW radii in atoms mode, not if explicit $spheres are given.

Type float

Default 0.5

sigma:

Width of cavity boundary, smaller value means sharper transition.

Type float

Default 0.2

Permittivity:

Parameters for the permittivity function.

Keywords

epsilon_in:

Permittivity inside the cavity. 1.0 is the permittivity of free space, anything other than this is undefined behaviour.

Type float

Default 1.0

epsilon_out:

Permittivity outside the cavity. This is characteristic of the solvent used.

Type float

Default 1.0

formulation:

Formulation of the Permittivity function. Currently only the exponential is used.

Type str

Default exponential

Predicates

value.lower() in ['exponential']

Constants:

Physical and mathematical constants used by MRChem

Keywords

hartree2simagnetizability:

Conversion factor for magnetizability from atomic units to SI units (unit: J T^-2). Affected code: Printed value of the magnetizability property.

Type float

Default 78.9451185

light_speed:

Speed of light in atomic units (unit: au). Affected code: Relativistic Hamiltonians (ZORA, etc.)

Type float

Default 137.035999084

angstrom2bohrs:

Conversion factor for Cartesian coordinates from Angstrom to Bohr (unit: Å^-1). Affected code: Parsing of input coordinates, printed coordinates

Type float

Default 1.8897261246257702

hartree2kjmol:

Conversion factor from Hartree to kJ/mol (unit: kJ mol^-1). Affected code: Printed value of energies.

Type float

Default 2625.4996394798254

hartree2kcalmol:

Conversion factor from Hartree to kcal/mol (unit: kcal mol^-1). Affected code: Printed value of energies.

Type float

Default 627.5094740630558

hartree2ev:

Conversion factor from Hartree to eV (unit: ev). Affected code: Printed value of energies.

Type float

Default 27.211386245988

hartree2wavenumbers:

Conversion factor from Hartree to wavenumbers (unit: cm^-1). Affected code: Printed value of frequencies.

Type float

Default 219474.6313632

fine_structure_constant:

Fine-structure constant in atomic units (unit: au). Affected code: Certain magnetic interaction operators.

Type float

Default 0.0072973525693

electron_g_factor:

Electron g factor in atomic units (unit: au). Affected code: Certain magnetic interaction operators.

Type float

Default -2.00231930436256

dipmom_au2debye:

Conversion factor for dipoles from atomic units to Debye (unit: ?). Affected code: Printed value of dipole moments.

Type float

Default 2.5417464739297717