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