### Table of Contents

- Introduction
- Core features
- Getting started
- Internal units and conventions
- Input files
- Input file tags
- al6xxx_kmc
- alchemy
- atoms
- atomswap
- barostat
- beads
- bias
- bosons
- cell
- checkpoint
- constrained_dynamics
- constraint
- csolver
- dmd
- dynamics
- ensemble
- ffcavphsocket
- ffcommittee
- ffdebye
- ffdmd
- fflj
- ffplumed
- ffsgdml
- ffsocket
- ffyaff
- file
- force
- forcefield
- forces
- frequencies
- gle
- h0
- init_cell
- initialize
- instanton
- labels
- masses
- metad
- momenta
- motion
- neb_optimizer
- normal_modes
- normalmodes
- optimizer
- output
- p_ramp
- planetary
- positions
- prng
- properties
- remd
- scp
- simulation
- smotion
- string_optimizer
- system
- system_template
- t_ramp
- thermostat
- trajectory
- velocities
- vibrations

- Output files
- Output file tags
- Distributed execution
- A simple tutorial
- Frequently asked questions
- Troubleshooting
- Contributing
- Bibliography

### Search

# Input file tags¶

This chapter gives a complete list of the tags that can be specified in the xml input file, along with the hierarchy of objects. Note that every xml input file must start with the root tag . See the accompanying “help.xml” file in the “doc/help_files” directory to see the recommended input file structure.

Each section of this chapter describes one of the major input classes
used in the i-PI initialization. These sections will start with some
normal text which describes the function of this class in detail. After
this the attributes of the tag will be listed, enclosed within a frame
for clarity. Finally, the fields contained within the tag will be listed
in alphabetical order, possibly followed by their attributes.
**Attribute** names will be bold and **field** names both bold and
underlined. *Other supplementary information* will be in small font and
italicized.

## al6xxx_kmc¶

Holds all the information for the KMC dynamics, such as timestep, rates and barriers that control it.

### ATTRIBUTES¶

modeThe KMC algorithm to be used

dtype: string

options: [‘rfkmc’]

default: rfkmc

### FIELDS¶

Option for geometry optimization step

nstepThe number of optimization steps.

dtype: integer

default: 10

a0FCC lattice parameter

dtype: float

dimension: length

default: 1.0

diffusion_barrier_alBarrier for vacancy diffusion in pure Al.

dtype: float

dimension: energy

default: 0.01

diffusion_prefactor_alPrefactor for vacancy diffusion in pure Al.

dtype: float

dimension: frequency

default: 2.4188843e-05

diffusion_barrier_mgBarrier for vacancy-assisted diffusion of Mg.

dtype: float

dimension: energy

default: 0.0

diffusion_prefactor_mgPrefactor for vacancy-assisted diffusion of Mg.

dtype: float

dimension: frequency

default: 0.0

diffusion_barrier_siBarrier for vacancy-assisted diffusion of Si.

dtype: float

dimension: energy

default: 0.0

diffusion_prefactor_siPrefactor for vacancy-assisted diffusion of Si.

dtype: float

dimension: frequency

default: 0.0

nevalThe number of parallel force evaluators.

dtype: integer

default: 4

ncellThe number of repeat cells in each direction.

dtype: integer

default: 4

nvacThe number of vacancies.

dtype: integer

default: 4

nsiThe number of silicon atoms.

dtype: integer

default: 4

nmgThe number of magnesium atoms.

dtype: integer

default: 4

idxThe position of the atoms on the lattice, relative to the canonical ordering.

dtype: integer

default: [ ]

tottimeTotal KMC time elapsed

dtype: float

dimension: time

default: 0.0

ecache_fileFilename for storing/loading energy cache

dtype: string

default:

qcache_fileFilename for storing/loading positions cache

dtype: string

default:

max_cache_lenMaximum cache length before oldest entry is deleted

dtype: integer

default: 1000

## alchemy¶

Holds all the information for doing Monte Carlo alchemical exchange moves.

### ATTRIBUTES¶

mode

dtype: string

options: [‘dummy’]

default: dummy

### FIELDS¶

namesThe names of the atoms to be to exchanged, in the format [name1, name2, … ].

dtype: string

default: [ ]

nxcThe average number of exchanges per step to be attempted

dtype: float

default: 1

ealcThe contribution to the conserved quantity for the alchemical exchanger

dtype: float

default: 0.0

## atoms¶

Deals with a single replica of the system or classical simulations.

### FIELDS¶

natomsThe number of atoms.

dtype: integer

default: 0

qThe positions of the atoms, in the format [x1, y1, z1, x2, … ].

dtype: float

dimension: length

default: [ ]

pThe momenta of the atoms, in the format [px1, py1, pz1, px2, … ].

dtype: float

dimension: momentum

default: [ ]

mThe masses of the atoms, in the format [m1, m2, … ].

dtype: float

dimension: mass

default: [ ]

namesThe names of the atoms, in the format [name1, name2, … ].

dtype: string

default: [ ]

## atomswap¶

Holds all the information for doing Monte Carlo atom swap moves.

### ATTRIBUTES¶

modeDummy attribute, does nothing.

dtype: string

options: [‘dummy’]

default: dummy

### FIELDS¶

namesThe names of the atoms to be to exchanged, in the format [name1, name2, … ].

dtype: string

default: [ ]

nxcThe average number of exchanges per step to be attempted

dtype: float

default: 1

ealcThe contribution to the conserved quantity for the atom swapper

dtype: float

default: 0.0

## barostat¶

Simulates an external pressure bath.

### ATTRIBUTES¶

modeThe type of barostat. ‘isotropic’ implements the Bussi-Zykova-Parrinello barostat [doi:10.1063/1.3073889] that isotropically scales the volume while sampling the isothermal isobaric ensemble. The implementation details are given in [doi:10.1016/j.cpc.2013.10.027]. ‘sc-isotropic’ implements the same for Suzuki-Chin path integral molecular dynamics [10.1021/acs.jctc.8b01297]. This barostat is suitable for simulating liquids. ‘flexible’ implements the path integral version of the Martyna-Tuckerman-Tobias-Klein barostat which incorporates full cell fluctuations while sampling the isothermal isobaric ensemble [doi:10.1063/1.478193]. This is suitable for anisotropic systems such as molecular solids. ‘anisotropic’ implements the Raiteri-Gale-Bussi barostat which enables cell fluctuations at constant external stress [10.1088/0953-8984/23/33/334213]. It is suitable for simulating solids at given external (non-diagonal) stresses and requires specifying a reference cell for estimating strain. Note that this ensemble is valid only within the elastic limit of small strains. For diagonal stresses (or external pressures) the ‘flexible’ and the ‘anisotropic’ modes should give very similar results. ‘dummy’ barostat does not do anything.

dtype: string

options: [‘dummy’, ‘isotropic’, ‘flexible’, ‘anisotropic’, ‘sc-isotropic’]

default: dummy

### FIELDS¶

The thermostat for the cell. Keeps the cell velocity distribution at the correct temperature. Note that the ‘pile_l’, ‘pile_g’, ‘nm_gle’ and ‘nm_gle_g’ options will not work for this thermostat.

tauThe time constant associated with the dynamics of the piston.

dtype: float

dimension: time

default: 1.0

pMomentum (or momenta) of the piston.

dtype: float

dimension: momentum

default: [ ]Reference cell for Parrinello-Rahman-like barostats. Should be roughly equal to the mean size of the cell averaged over the trajectory. Sampling might be inaccurate if the difference is too large.

dtype: float

dimension: length

default:[0. 0. 0. 0. 0. 0. 0. 0. 0.]

hfixA list of the cell entries that should be held fixed (xx, yy, zz, xy, xz, yz). ‘offdiagonal’ is an alias for xy, xz, yz.

dtype: string

default: [ ]

## beads¶

Describes the bead configurations in a path integral simulation.

### ATTRIBUTES¶

natomsThe number of atoms.

dtype: integer

default: 0

nbeadsThe number of beads.

dtype: integer

default: 0

### FIELDS¶

qThe positions of the beads. In an array of size [nbeads, 3*natoms].

dtype: float

dimension: length

default: [ ]

pThe momenta of the beads. In an array of size [nbeads, 3*natoms].

dtype: float

dimension: momentum

default: [ ]

mThe masses of the atoms, in the format [m1, m2, … ].

dtype: float

dimension: mass

default: [ ]

namesThe names of the atoms, in the format [name1, name2, … ].

dtype: string

default: [ ]

## bias¶

Deals with creating all the necessary forcefield objects.

### FIELDS¶

The class that deals with how each forcefield contributes to the overall potential, force and virial calculation.

## bosons¶

Deals with the specification of which atoms are have bosonic indistinguishability. The specified atoms participate in exchange interaction, which forms ring polymers that combine several particles together. The algorithm scales quadratically with the number of atoms and linearly with the number of beads. The implementation is based on Hirshberg et al.’s doi:10.1073/pnas.1913365116 and Feldman and Hirshberg’s doi:10.1063/5.0173749.

*dtype*: string

### ATTRIBUTES¶

shapeThe shape of the array.

dtype: tuple

default: (0,)

modeIf ‘mode’ is ‘manual’, then the array is read in directly, then reshaped according to the ‘shape’ specified in a row-major manner. If ‘mode’ is ‘file’ then the array is read in from the file given.

dtype: string

options: [‘manual’, ‘file’]

default: manual

idIf ‘id’ is ‘index’, then bosonic atoms are specified a list of indices (zero-based). If ‘id’ is ‘label’ then specify a list of labels.

dtype: string

options: [‘index’, ‘label’]

default: index

## cell¶

Describes with the cell parameters. Takes as array which can be used to initialize the cell vector matrix. N.B.: the cell parameters are stored with the lattice vectors in the columns, and the cell must be oriented in such a way that the array is upper-triangular (i.e. with the first vector aligned along x and the second vector in the xy plane).

*dtype*: float

*dimension*: length

### ATTRIBUTES¶

unitsThe units the input data is given in.

dtype: string

default: automatic

shapeThe shape of the array.

dtype: tuple

default: (0,)

modeIf ‘mode’ is ‘manual’, then the array is read in directly, then reshaped according to the ‘shape’ specified in a row-major manner. If ‘mode’ is ‘file’ then the array is read in from the file given.

dtype: string

options: [‘manual’, ‘file’]

default: manual

## checkpoint¶

This class defines how a checkpoint file should be output. Optionally, between the checkpoint tags, you can specify one integer giving the current step of the simulation. By default this integer will be zero.

*dtype*: integer

### ATTRIBUTES¶

filenameA string to specify the name of the file that is output. The file name is given by ‘prefix’.’filename’ + format_specifier. The format specifier may also include a number if multiple similar files are output.

dtype: string

default: restart

strideThe number of steps between successive writes.

dtype: integer

default: 1

overwriteThis specifies whether or not each consecutive checkpoint file will overwrite the old one.

dtype: boolean

default: True

## constrained_dynamics¶

Holds all the information for the MD integrator, such as timestep, the thermostats and barostats that control it.

### ATTRIBUTES¶

modeThe ensemble that will be sampled during the simulation.

dtype: string

options: [‘nve’, ‘nvt’]

default: nve

splittingThe integrator used for sampling the target ensemble.

dtype: string

options: [‘obabo’, ‘baoab’]

default: baoab

### FIELDS¶

The thermostat for the atoms, keeps the atom velocity distribution at the correct temperature.

Simulates an external pressure bath.

timestepThe time step.

dtype: float

dimension: time

default: 1.0

nmtsNumber of iterations for each MTS level (including the outer loop, that should in most cases have just one iteration).

dtype: integer

default: [ ]

nsteps_oThe number of sub steps used in the evolution of the thermostat (used in function step_Oc). Relevant only for GLE thermostats

dtype: integer

default: 1

nsteps_geoThe number of sub steps used in the evolution of the geodesic flow (used in function step_Ag).

dtype: integer

default: 1Define a numerical method for computing the projection operators associated with the constraint.

Define a constraint to be applied onto atoms

## constraint¶

Generic input value

### ATTRIBUTES¶

modeThe type of constraint.

dtype: string

options: [‘distance’, ‘angle’, ‘eckart’, ‘multi’, ‘multi’]

default: distance

### FIELDS¶

atomsList of atoms indices that are to be constrained.

dtype: integer

default: [ ]

valuesList of constraint lengths.

dtype: float

dimension: length

default: [ ]One or more constraints that have to be considered coupled

## csolver¶

Holds all parameters for the numerical method used to solve the contraint.

### FIELDS¶

toleranceTolerance value used in the Quasi-Newton iteration scheme.

dtype: float

default: 0.0001

maxitMaximum number of steps used in the Quasi-Newton iteration scheme.

dtype: integer

default: 1000

norm_orderOrder of norm used to determine termination of the Quasi-newton iteration.

dtype: integer

default: 2

## dmd¶

DrivenMD with external time-dependent driving potential

### FIELDS¶

dmdffList of names of forcefields that should do driven MD. Accepts ffdmd forcefield types. Currently implemented (2021) for ffdmd only the driving potential similar to the one described in Bowman, .., Brown JCP 119, 646 (2003).

dtype: string

default: [ ]

## dynamics¶

Holds all the information for the MD integrator, such as timestep, the thermostats and barostats that control it.

### ATTRIBUTES¶

modeThe ensemble that will be sampled during the simulation. nve: constant-energy-volume; nvt: constant-temperature-volume; npt: constant-temperature-pressure(isotropic); nst: constant-temperature-stress(anisotropic); sc: Suzuki-Chin high-order NVT; scnpt: Suzuki-Chin high-order NpT; nvt-cc: constrained-centroid NVT;

dtype: string

options: [‘nve’, ‘nvt’, ‘npt’, ‘nst’, ‘sc’, ‘scnpt’, ‘nvt-cc’]

default: nve

splittingThe Louiville splitting used for sampling the target ensemble.

dtype: string

options: [‘obabo’, ‘baoab’]

default: obabo

### FIELDS¶

The thermostat for the atoms, keeps the atom velocity distribution at the correct temperature.

Simulates an external pressure bath.

timestepThe time step.

dtype: float

dimension: time

default: 1.0

nmtsNumber of iterations for each MTS level (including the outer loop, that should in most cases have just one iteration).

dtype: integer

default: [ ]

## ensemble¶

Holds all the information that is ensemble specific, such as the temperature and the external pressure.

### FIELDS¶

temperatureThe temperature of the system.

dtype: float

dimension: temperature

default: -1.0

pressureThe external pressure.

dtype: float

dimension: pressure

default: -12345.0

stressThe external stress.

dtype: float

dimension: pressure

default:[-12345. -0. -0. -0. -12345. -0. -0. -0. -12345.]

eensThe ensemble contribution to the conserved quantity.

dtype: float

dimension: energy

default: 0.0Deals with creating all the necessary forcefield objects.

bias_weightsBias weights.

dtype: float

default: [ ]

hamiltonian_weightsHamiltonian weights.

dtype: float

default: [ ]

timeThe internal time for this system

dtype: float

dimension: time

default: 0.0

## ffcavphsocket¶

A cavity molecular dynamics driver for vibraitonal strong coupling. In the current implementation, only a single cavity mode polarized along the x and y directions is coupled to the molecules. Check https://doi.org/10.1073/pnas.2009272117 and also examples/lammps/h2o-cavmd/ for details.

### ATTRIBUTES¶

modeSpecifies whether the driver interface will listen onto a internet socket [inet] or onto a unix socket [unix].

dtype: string

options: [‘unix’, ‘inet’]

default: inet

matchingSpecifies whether requests should be dispatched to any client, automatically matched to the same client when possible [auto] or strictly forced to match with the same client [lock].

dtype: string

options: [‘auto’, ‘any’, ‘lock’]

default: auto

nameMandatory. The name by which the forcefield will be identified in the System forces section.

dtype: string

pbcApplies periodic boundary conditions to the atoms coordinates before passing them on to the driver code.

dtype: boolean

default: True

threadedWhether the forcefield should use a thread loop to evaluate, or work in serial. Should be set to True for FFSockets

dtype: boolean

default: True

### FIELDS¶

charge_arrayThe partial charges of all the atoms, in the format [Q1, Q2, … ].

dtype: float

dimension: length

default: [ ]

apply_photonDetermines if additional photonic degrees of freedom is included or not.

dtype: boolean

default: False

E0The value of varepsilon (effective light-matter coupling strength) in atomic units.

dtype: float

default: 0.0

omega_cThis gives the cavity photon frequency at normal incidence.

dtype: float

dimension: frequency

default: 0.01

ph_repIn the current implementation, two energy-degenerate photon modes polarized along x and y directions are coupled to the molecular system. If ‘loose’, the cavity photons polarized along the x, y directions are represented by two ‘L’ atoms; the x dimension of the first ‘L’ atom is coupled to the molecules, and the y dimension of the second ‘L’ atom is coupled to the molecules. If ‘dense’, the cavity photons polarized along the x, y directions are represented by one ‘L’ atom; the x and y dimensions of this ‘L’ atom are coupled to the molecules.

dtype: string

options: [‘loose’, ‘dense’]

default: loose

addressThis gives the server address that the socket will run on.

dtype: string

default: localhost

portThis gives the port number that defines the socket.

dtype: integer

default: 65535

slotsThis gives the number of client codes that can queue at any one time.

dtype: integer

default: 4

exit_on_disconnectDetermines if i-PI should quit when a client disconnects.

dtype: boolean

default: False

timeoutThis gives the number of seconds before assuming a calculation has died. If 0 there is no timeout.

dtype: float

default: 0.0

latencyThe number of seconds the polling thread will wait between exhamining the list of requests.

dtype: float

default: 0.0001

offsetA constant offset that is subtracted from the forcefield energy. Useful when there is a large core energy contribution that is constant throughout a simulation and hides significant changes in the 10th digit.

dtype: float

dimension: energy

default: 0.0

parametersThe parameters of the force field

dtype: dictionary

default: { }

activelistList with indexes of the atoms that this socket is taking care of. Default: [-1] (corresponding to all)

dtype: integer

default:[-1]

## ffcommittee¶

Combines multiple forcefields to build a committee model, that can be used to compute uncertainty-quantified machine-learning models. Each forcefield can be any of the other FF objects, and each should be used with a client that generates a slightly different estimation of energy and forces. These are averaged, and the mean used as the actual forcefield. Statistics about the distribution are also returned as extras fields, and can be printed for further postprocessing. It is also possible for a single FF object to return a JSON-formatted string containing entries committee_pot, committee_force and committee_virial, that contain multiple members at once. These will be unpacked and combined with whatever else is present. Also contains options to use it for uncertainty estimation and for active learning in a ML context, based on a committee model. Implements the approaches discussed in [Musil et al.](http://doi.org/10.1021/acs.jctc.8b00959) and [Imbalzano et al.](http://doi.org/10.1063/5.0036522)

### ATTRIBUTES¶

nameMandatory. The name by which the forcefield will be identified in the System forces section.

dtype: string

pbcApplies periodic boundary conditions to the atoms coordinates before passing them on to the driver code.

dtype: boolean

default: True

threadedWhether the forcefield should use a thread loop to evaluate, or work in serial

dtype: boolean

default: False

### FIELDS¶

latencyThe number of seconds the polling thread will wait between exhamining the list of requests.

dtype: float

default: 0.0001

offsetA constant offset that is subtracted from the forcefield energy. Useful when there is a large core energy contribution that is constant throughout a simulation and hides significant changes in the 10th digit.

dtype: float

dimension: energy

default: 0.0

parametersThe parameters of the force field

dtype: dictionary

default: { }

activelistList with indexes of the atoms that this socket is taking care of. Default: [-1] (corresponding to all)

dtype: integer

default:[-1]

weightsList of weights to be given to the forcefields. Defaults to 1 for each FF. Note that the components are divided by the number of FF, and so the default corresponds to an average.

dtype: float

default: [ ]

alphaScaling of the variance of the model, corresponding to a calibration of the error

dtype: float

default: 1.0

baseline_nameName of the forcefield object that should be treated as the baseline for a weighted baseline model.

dtype: string

default:

baseline_uncertaintyCorresponds to the expected error of the baseline model. This represents the error on the TOTAL potential energy of the simulation.

dtype: float

dimension: energy

default: -1.0

active_threshThe uncertainty threshold for active learning. Structure with an uncertainty above this value are printed in the specified output file so they can be used for active learning.

dtype: float

dimension: energy

default: 0.0

active_outputOutput filename for structures that exceed the accuracy threshold of the model, to be used in active learning.

dtype: string

default: active_output

parse_jsonTell the model whether to parse extras string looking for committee values of potential, forces, and virials. Default: false.

dtype: boolean

default: FalseDeals with the assigning of force calculation jobs to different driver codes, and collecting the data, using a socket for the data communication.

Simple, internal LJ evaluator without cutoff, neighbour lists or minimal image convention. Expects standard LJ parameters, e.g. { eps: 0.1, sigma: 1.0 }.

Harmonic energy calculator

Direct PLUMED interface

Uses a Yaff force field to compute the forces.

A SGDML energy calculator

## ffdebye¶

Harmonic energy calculator

### ATTRIBUTES¶

nameMandatory. The name by which the forcefield will be identified in the System forces section.

dtype: string

pbcApplies periodic boundary conditions to the atoms coordinates before passing them on to the driver code.

dtype: boolean

default: True

threadedWhether the forcefield should use a thread loop to evaluate, or work in serial

dtype: boolean

default: False

### FIELDS¶

hessianSpecifies the Hessian of the harmonic potential. Default units are atomic. Units can be specified only by xml attribute. Implemented options are: ‘atomic_unit’, ‘ev/ang^2’

dtype: float

dimension: hessian

default: [ ]

x_referenceMinimum-energy configuration for the harmonic potential

dtype: float

dimension: length

default: [ ]

v_referenceZero-value of energy for the harmonic potential

dtype: float

dimension: energy

default: 0.0

latencyThe number of seconds the polling thread will wait between exhamining the list of requests.

dtype: float

default: 0.0001

offsetA constant offset that is subtracted from the forcefield energy. Useful when there is a large core energy contribution that is constant throughout a simulation and hides significant changes in the 10th digit.

dtype: float

dimension: energy

default: 0.0

parametersThe parameters of the force field

dtype: dictionary

default: { }

activelistList with indexes of the atoms that this socket is taking care of. Default: [-1] (corresponding to all)

dtype: integer

default:[-1]

## ffdmd¶

Simple, internal DMD evaluator without without neighbor lists, but with PBC. Expects coupling elements (n*(n-1)/2 of them), oscillating frequency and time step.

### ATTRIBUTES¶

nameMandatory. The name by which the forcefield will be identified in the System forces section.

dtype: string

pbc

dtype: boolean

default: True

threadedWhether the forcefield should use a thread loop to evaluate, or work in serial

dtype: boolean

default: False

### FIELDS¶

dmd_couplingSpecifies the coupling between atom pairs (should be size N*(N-1)/2 ordered c21, c32, c31, c43, c42, c41 etc. – in atomic units!)

dtype: float

default: [ ]

dmd_freqFrequency of the oscillation of the time-dependent term

dtype: float

dimension: frequency

default: 0.0

dmd_dtTime step of the oscillating potential. Should match time step of simulation

dtype: float

dimension: time

default: 0.0

dmd_stepThe current step counter for dmd.

dtype: integer

default: 0

latencyThe number of seconds the polling thread will wait between exhamining the list of requests.

dtype: float

default: 0.0001

offset

dtype: float

dimension: energy

default: 0.0

parametersThe parameters of the force field

dtype: dictionary

default: { }

activelist

dtype: integer

default:[-1]

## fflj¶

Simple, internal LJ evaluator without cutoff, neighbour lists or minimal image convention. Expects standard LJ parameters, e.g. { eps: 0.1, sigma: 1.0 }.

### ATTRIBUTES¶

nameMandatory. The name by which the forcefield will be identified in the System forces section.

dtype: string

pbc

dtype: boolean

default: True

threadedWhether the forcefield should use a thread loop to evaluate, or work in serial

dtype: boolean

default: False

### FIELDS¶

latencyThe number of seconds the polling thread will wait between exhamining the list of requests.

dtype: float

default: 0.0001

offset

dtype: float

dimension: energy

default: 0.0

parametersThe parameters of the force field

dtype: dictionary

default: { }

activelist

dtype: integer

default:[-1]

## ffplumed¶

Direct PLUMED interface

### ATTRIBUTES¶

nameMandatory. The name by which the forcefield will be identified in the System forces section.

dtype: string

pbc

dtype: boolean

default: True

threadedWhether the forcefield should use a thread loop to evaluate, or work in serial

dtype: boolean

default: False

### FIELDS¶

This describes the location to read the reference structure file from.

dtype: string

default:

plumeddatThe PLUMED input file

dtype: string

default: plumed.dat

plumedstepThe current step counter for PLUMED calls

dtype: integer

default: 0

latencyThe number of seconds the polling thread will wait between exhamining the list of requests.

dtype: float

default: 0.0001

offset

dtype: float

dimension: energy

default: 0.0

parametersThe parameters of the force field

dtype: dictionary

default: { }

activelist

dtype: integer

default:[-1]

## ffsgdml¶

A SGDML energy calculator

### ATTRIBUTES¶

nameMandatory. The name by which the forcefield will be identified in the System forces section.

dtype: string

pbc

dtype: boolean

default: True

threadedWhether the forcefield should use a thread loop to evaluate, or work in serial

dtype: boolean

default: False

### FIELDS¶

sGDML_modelThis gives the file name of the sGDML model.

dtype: string

latencyThe number of seconds the polling thread will wait between exhamining the list of requests.

dtype: float

default: 0.0001

offset

dtype: float

dimension: energy

default: 0.0

parametersThe parameters of the force field

dtype: dictionary

default: { }

activelist

dtype: integer

default:[-1]

## ffsocket¶

Deals with the assigning of force calculation jobs to different driver codes, and collecting the data, using a socket for the data communication.

### ATTRIBUTES¶

modeSpecifies whether the driver interface will listen onto a internet socket [inet] or onto a unix socket [unix].

dtype: string

options: [‘unix’, ‘inet’]

default: inet

matchingSpecifies whether requests should be dispatched to any client, automatically matched to the same client when possible [auto] or strictly forced to match with the same client [lock].

dtype: string

options: [‘auto’, ‘any’, ‘lock’]

default: auto

nameMandatory. The name by which the forcefield will be identified in the System forces section.

dtype: string

pbc

dtype: boolean

default: True

threadedWhether the forcefield should use a thread loop to evaluate, or work in serial. Should be set to True for FFSockets

dtype: boolean

default: True

### FIELDS¶

addressThis gives the server address that the socket will run on.

dtype: string

default: localhost

portThis gives the port number that defines the socket.

dtype: integer

default: 65535

slotsThis gives the number of client codes that can queue at any one time.

dtype: integer

default: 4

exit_on_disconnectDetermines if i-PI should quit when a client disconnects.

dtype: boolean

default: False

timeoutThis gives the number of seconds before assuming a calculation has died. If 0 there is no timeout.

dtype: float

default: 0.0

latencyThe number of seconds the polling thread will wait between exhamining the list of requests.

dtype: float

default: 0.0001

offset

dtype: float

dimension: energy

default: 0.0

parametersThe parameters of the force field

dtype: dictionary

default: { }

activelist

dtype: integer

default:[-1]

## ffyaff¶

Uses a Yaff force field to compute the forces.

### ATTRIBUTES¶

nameMandatory. The name by which the forcefield will be identified in the System forces section.

dtype: string

pbc

dtype: boolean

default: True

threadedWhether the forcefield should use a thread loop to evaluate, or work in serial

dtype: boolean

default: False

### FIELDS¶

yaffparaThis gives the file name of the Yaff input parameter file.

dtype: string

default: parameters.txt

yaffsysThis gives the file name of the Yaff input system file.

dtype: string

default: system.chk

yafflogThis gives the file name of the Yaff output log file.

dtype: string

default: yaff.log

rcutThis gives the real space cutoff used by all pair potentials in atomic units.

dtype: float

default: 18.89726133921252

alpha_scaleThis gives the alpha parameter in the Ewald summation based on the real-space cutoff: alpha = alpha_scale / rcut. Higher values for this parameter imply a faster convergence of the reciprocal terms, but a slower convergence in real-space.

dtype: float

default: 3.5

gcut_scaleThis gives the reciprocale space cutoff based on the alpha parameter: gcut = gcut_scale * alpha. Higher values for this parameter imply a better convergence in the reciprocal space.

dtype: float

default: 1.1

skinThis gives the skin parameter for the neighborlist.

dtype: integer

default: 0

smooth_eiThis gives the flag for smooth truncations for the electrostatic interactions.

dtype: boolean

default: False

reci_eiThis gives the method to be used for the reciprocal contribution to the electrostatic interactions in the case of periodic systems. This must be one of ‘ignore’ or ‘ewald’. The ‘ewald’ option is only supported for 3D periodic systems.

dtype: string

default: ewald

latencyThe number of seconds the polling thread will wait between exhamining the list of requests.

dtype: float

default: 0.0001

offset

dtype: float

dimension: energy

default: 0.0

parametersThe parameters of the force field

dtype: dictionary

default: { }

activelist

dtype: integer

default:[-1]

## file¶

This is the class to initialize from file.

*dtype*: string

### ATTRIBUTES¶

modeThe input data format. ‘xyz’ and ‘pdb’ stand for xyz and pdb input files respectively. ‘chk’ stands for initialization from a checkpoint file. ‘ase’ is to read a file with the Atomic Simulation Environment

dtype: string

options: [‘xyz’, ‘pdb’, ‘chk’, ‘ase’]

default: chk

beadThe index of the bead for which the value will be set. If a negative value is specified, then all beads are assumed.

dtype: integer

default: -1

cell_unitsThe units for the cell dimensions.

dtype: string

default: automatic

## force¶

The class that deals with how each forcefield contributes to the overall potential, force and virial calculation.

### ATTRIBUTES¶

nbeadsIf the forcefield is to be evaluated on a contracted ring polymer, this gives the number of beads that are used. If not specified, the forcefield will be evaluated on the full ring polymer.

dtype: integer

default: 0

weightA scaling factor for this forcefield, to be applied before adding the force calculated by this forcefield to the total force.

dtype: float

default: 1.0

fd_epsilonThe finite displacement to be used for calculaing the Suzuki-Chin contribution of the force. If the value is negative, a centered finite-difference scheme will be used. [in bohr]

dtype: float

default: -0.001

nameAn optional name to refer to this force component.

dtype: string

default:

forcefieldMandatory. The name of the forcefield this force is referring to.

dtype: string

default:

### FIELDS¶

mts_weightsThe weight of force in each mts level starting from outer.

dtype: float

dimension: force

default:[1.]

force_extrasA list of quantities that should be extracted from the ‘extra’ string returned by the forcefield, that are then treated the same way as energy or forces – that is treated as a numerical, physical quantity, interpolated when changing the number of PI replicas. Same quantities from different force components are summed as well. The names should correspond to entries in the JSON-formatted extra string.

dtype: string

default: [ ]

## forcefield¶

Base forcefield class that deals with the assigning of force calculation jobs and collecting the data.

### ATTRIBUTES¶

nameMandatory. The name by which the forcefield will be identified in the System forces section.

dtype: string

pbc

dtype: boolean

default: True

threadedWhether the forcefield should use a thread loop to evaluate, or work in serial

dtype: boolean

default: False

### FIELDS¶

latencyThe number of seconds the polling thread will wait between exhamining the list of requests.

dtype: float

default: 0.0001

offset

dtype: float

dimension: energy

default: 0.0

parametersThe parameters of the force field

dtype: dictionary

default: { }

activelist

dtype: integer

default:[-1]

## forces¶

Deals with creating all the necessary forcefield objects.

### FIELDS¶

The class that deals with how each forcefield contributes to the overall potential, force and virial calculation.

## frequencies¶

Provides a compact way of specifying the ring polymer frequencies

*dtype*: float

*dimension*: frequency

### ATTRIBUTES¶

unitsThe units the input data is given in.

dtype: string

default: automatic

shapeThe shape of the array.

dtype: tuple

default: (0,)

modeIf ‘mode’ is ‘manual’, then the array is read in directly, then reshaped according to the ‘shape’ specified in a row-major manner. If ‘mode’ is ‘file’ then the array is read in from the file given.

dtype: string

options: [‘manual’, ‘file’]

default: manual

styleSpecifies the technique to be used to calculate the dynamical masses. ‘rpmd’ simply assigns the bead masses the physical mass. ‘manual’ sets all the normal mode frequencies except the centroid normal mode manually. ‘pa-cmd’ takes an argument giving the frequency to set all the non-centroid normal modes to. ‘wmax-cmd’ is similar to ‘pa-cmd’, except instead of taking one argument it takes two ([wmax,wtarget]). The lowest-lying normal mode will be set to wtarget for a free particle, and all the normal modes will coincide at frequency wmax.

dtype: string

options: [‘pa-cmd’, ‘wmax-cmd’, ‘manual’, ‘rpmd’]

default: rpmd

## gle¶

This is the class to initialize the thermostat (ethermo and fictitious momenta).

*dtype*: string

### ATTRIBUTES¶

mode‘chk’ stands for initialization from a checkpoint file. ‘manual’ means that the value to initialize from is giving explicitly as a vector.

dtype: string

options: [‘chk’, ‘manual’]

default: manual

## h0¶

Describes with the cell parameters. Takes as array which can be used to initialize the cell vector matrix. N.B.: the cell parameters are stored with the lattice vectors in the columns, and the cell must be oriented in such a way that the array is upper-triangular (i.e. with the first vector aligned along x and the second vector in the xy plane).

*dtype*: float

*dimension*: length

### ATTRIBUTES¶

unitsThe units the input data is given in.

dtype: string

default: automatic

shapeThe shape of the array.

dtype: tuple

default: (0,)

mode

dtype: string

options: [‘manual’, ‘file’]

default: manual

## init_cell¶

This is the class to initialize cell.

*dtype*: string

### ATTRIBUTES¶

modeThis decides whether the system box is created from a cell parameter matrix, or from the side lengths and angles between them. If ‘mode’ is ‘manual’, then ‘cell’ takes a 9-elements vector containing the cell matrix (row-major, lattice vectors stored in columns). The 1st element define lattice vector a, the 2nd, 5th elements define lattice vector b, and the 3rd, 6th, 9th elements define lattice vector c. The other elements are ignored, as the cell must be aligned so that it is upper triangular. If ‘mode’ is ‘abcABC’, then ‘cell’ takes an array of 6 floats, the first three being the length of the sides of the system parallelopiped, and the last three being the angles (in degrees) between those sides. Angle A corresponds to the angle between sides b and c, and so on for B and C. If mode is ‘abc’, then this is the same as for ‘abcABC’, but the cell is assumed to be orthorhombic. ‘pdb’ and ‘chk’ read the cell from a PDB or a checkpoint file, respectively.

dtype: string

options: [‘manual’, ‘pdb’, ‘chk’, ‘abc’, ‘abcABC’]

default: manual

## initialize¶

Specifies the number of beads, and how the system should be initialized.

### ATTRIBUTES¶

nbeadsThe number of beads. Will override any provision from inside the initializer. A ring polymer contraction scheme is used to scale down the number of beads if required. If instead the number of beads is scaled up, higher normal modes will be initialized to zero.

dtype: integer

### FIELDS¶

Initializes atomic positions. Will take a ‘units’ attribute of dimension ‘length’

dtype: stringInitializes atomic velocities. Will take a ‘units’ attribute of dimension ‘velocity’

dtype: stringInitializes atomic momenta. Will take a ‘units’ attribute of dimension ‘momentum’

dtype: stringInitializes atomic masses. Will take a ‘units’ attribute of dimension ‘mass’

dtype: stringInitializes atomic labels

dtype: stringInitializes the configuration of the cell. Will take a ‘units’ attribute of dimension ‘length’

dtype: stringInitializes everything possible for the given mode. Will take a ‘units’ attribute of dimension ‘length’. The unit conversion will only be applied to the positions and cell parameters. The ‘units’ attribute is deprecated. Append a ‘quantity{units}’ to the comment line of the xyz or to the ‘TITLE’ tag of a pdb.

dtype: stringInitializes the additional momenta in a GLE thermostat.

dtype: string

## instanton¶

A class for instanton calculations

### ATTRIBUTES¶

modeDefines whether it is an instanton rate or instanton tunneling splitting calculaion

dtype: string

options: [‘rate’, ‘splitting’]

default: rate

### FIELDS¶

tolerancesConvergence criteria for optimization.

biggest_stepThe maximum step size during the optimization.

dtype: float

default: 0.4

old_posThe previous step positions during the optimization.

dtype: float

dimension: length

default: [ ]

old_potThe previous step potential energy during the optimization

dtype: float

dimension: energy

default: [ ]

old_forceThe previous step force during the optimization

dtype: float

dimension: force

default: [ ]

optThe geometry optimization algorithm to be used. For small system sizes nichols is recomended. Lanczos is tailored for big bigger than nbeads*natoms >~38*64. NR works in both cases given that the initial guess is close to the optimized geometry. Finally lbfgs is used for tunneling splitting calculations.

dtype: string

options: [‘nichols’, ‘NR’, ‘lbfgs’, ‘lanczos’, ‘None’]

default: None

max_eEvaluate the forces in a reduced ring polymer such that the potential energy between consecutive replicas is smaller that the provided value.

dtype: float

dimension: energy

default: 0.0

max_msEvaluate the forces in a reduced ring polymer such that that mass-scaled distance in a.u. between consecutive replicas is smaller that the provided value.

dtype: float

default: 0.0

discretizationAllows to specified non uniform time discretization as proposed in J. Chem. Phys. 134, 184107 (2011)

dtype: float

default: [ ]

alt_outAlternative output:Prints different formatting of outputs for geometry, hessian and bead potential energies. All quantities are also accessible from typical i-pi output infrastructure. Default to 1, which prints every step. -1 will suppress the output (except the last one). Any other positive number will set the frequency (in steps) with which the quantities are written to file. The instanton geometry is printed in xyz format and the distances are in angrstroms The hessian is printed in one line with the following format: h1_1,h2_1,…,hN_1, h2_2,h2_2,hN_2, …. ,h1_d,h2_d,…,hN_d. Where N represents the total number of replicas, d the number of dimension of each replica (3*n_atoms) and hi_j means the row j of the physical hessian corresponding to the replica i. The physical hessian uses a convention according to the positions convention used in i-pi. Example of 2 particles, the first two rows of the physical hessian reads: ‘H_x1_x1, H_x1_y1, H_x1_z1, H_x1_x2, H_x1_y2,H_x1_z2’ ‘H_x2_x1, H_x2_y1, H_x2_z1, H_x2_x2, H_x2_y2,H_x2_z2’

dtype: integer

default: 1

prefixPrefix of the output files.

dtype: string

default: instanton

deltaInitial stretch amplitude.

dtype: float

default: 0.1

hessian_initHow to initialize the hessian if it is not fully provided.

dtype: string

options: [‘true’, ‘false’]

default: false

hessian(Approximate) Hessian.

dtype: float

default: [ ]

hessian_updateHow to update the hessian after each step.

dtype: string

options: [‘powell’, ‘recompute’]

default: powell

hessian_asrRemoves the zero frequency vibrational modes depending on the symmetry of the system.

dtype: string

options: [‘none’, ‘poly’, ‘crystal’]

default: none

qlist_lbfgsList of previous position differences for L-BFGS, if known.

dtype: float

default: [ ]

glist_lbfgsList of previous gradient differences for L-BFGS, if known.

dtype: float

default: [ ]

old_directionThe previous direction in a CG or SD optimization.

dtype: float

default: [ ]

scale_lbfgsScale choice for the initial hessian. 0 identity. 1 Use first member of position/gradient list. 2 Use last member of position/gradient list.

dtype: integer

default: 2

corrections_lbfgsThe number of past vectors to store for L-BFGS.

dtype: integer

default: 20

ls_optionsOptions for line search methods. Includes: tolerance: stopping tolerance for the search, iter: the maximum number of iterations, step: initial step for bracketing, adaptive: whether to update initial step.

energy_shiftSet the zero of energy.

dtype: float

dimension: energy

default: 0.0

hessian_finalDecide if we are going to compute the final big-hessian by finite difference.

dtype: string

options: [‘false’, ‘true’]

default: false

## labels¶

This is the class to initialize atomic labels.

*dtype*: string

### ATTRIBUTES¶

modeThe input data format. ‘xyz’ and ‘pdb’ stand for xyz and pdb input files respectively. ‘ase’ is to read a file with the Atomic Simulation Environment. ‘chk’ stands for initialization from a checkpoint file. ‘manual’ means that the value to initialize from is giving explicitly as a vector.

dtype: string

options: [‘manual’, ‘xyz’, ‘pdb’, ‘ase’, ‘chk’]

default: chk

indexThe index of the atom for which the value will be set. If a negative value is specified, then all atoms are assumed.

dtype: integer

default: -1

beadThe index of the bead for which the value will be set. If a negative value is specified, then all beads are assumed.

dtype: integer

default: -1

## masses¶

This is the class to initialize atomic masses.

*dtype*: string

### ATTRIBUTES¶

modeThe input data format. ‘xyz’ and ‘pdb’ stand for xyz and pdb input files respectively. ‘ase’ is to read a file with the Atomic Simulation Environment. ‘chk’ stands for initialization from a checkpoint file. ‘manual’ means that the value to initialize from is giving explicitly as a vector.

dtype: string

options: [‘manual’, ‘xyz’, ‘pdb’, ‘ase’, ‘chk’]

default: chk

indexThe index of the atom for which the value will be set. If a negative value is specified, then all atoms are assumed.

dtype: integer

default: -1

beadThe index of the bead for which the value will be set. If a negative value is specified, then all beads are assumed.

dtype: integer

default: -1

## metad¶

MetaDynamics

### FIELDS¶

metaffList of names of forcefields that should do metadynamics.

dtype: string

default: [ ]

use_energyTransfer the potential energy value to PLUMED to use as a collective variable. Can only be used with classical simulations because it requires a rather hacky mechanism to transfer the energy of the system to the forcefield.

dtype: boolean

default: False

## momenta¶

This is the class to initialize momenta.

*dtype*: string

### ATTRIBUTES¶

modeThe input data format. ‘xyz’ and ‘pdb’ stand for xyz and pdb input files respectively. ‘chk’ stands for initialization from a checkpoint file. ‘manual’ means that the value to initialize from is giving explicitly as a vector. ‘thermal’ means that the data is to be generated from a Maxwell-Boltzmann distribution at the given temperature.

dtype: string

options: [‘manual’, ‘xyz’, ‘pdb’, ‘ase’, ‘chk’, ‘thermal’]

default: chk

indexThe index of the atom for which the value will be set. If a negative value is specified, then all atoms are assumed.

dtype: integer

default: -1

bead

dtype: integer

default: -1

## motion¶

Allow chosing the type of calculation to be performed. Holds all the information that is calculation specific, such as geometry optimization parameters, etc.

### ATTRIBUTES¶

modeHow atoms should be moved at each step in the simulatio. ‘replay’ means that a simulation is replayed from trajectories provided to i-PI.

dtype: string

options: [‘vibrations’, ‘minimize’, ‘replay’, ‘neb’, ‘string’, ‘dynamics’, ‘constrained_dynamics’, ‘t_ramp’, ‘p_ramp’, ‘alchemy’, ‘atomswap’, ‘planetary’, ‘instanton’, ‘al-kmc’, ‘dummy’, ‘scp’, ‘normalmodes’, ‘multi’]

### FIELDS¶

fixcomThis describes whether the centre of mass of the particles is fixed.

dtype: boolean

default: True

fixatomsIndices of the atmoms that should be held fixed.

dtype: integer

default: [ ]Option for geometry optimization

Option for NEB optimization

Option for String minimal-energy path optimization

Option for (path integral) molecular dynamics

Option for constrained classical molecular dynamics

This describes the location to read a trajectory file from. Replay syntax allows using some POSIX wildcards in the filename of trajectory files. If symbols ?*[] are found in a filename, the code expects to find exactly Nbeads files that match the provided pattern. Bead indices will be read from the files, and the files will be ordered ascendingly by their bead indices. Wildcarded files are expected to be in the folder where the simulation runs.

dtype: string

default:Option for phonon computation

Option for solving the vibrational Schroedinger’s equations in normal mode coordinates.

Option for self consistent phonons computation

Option for alchemical exchanges

Option for Monte Carlo atom swap

Option for temperature ramp

Option for pressure ramp

Option for Instanton optimization

Option for Al-6xxx KMC

Option for planetary model calculator

A motion class that can be included as a member of a ‘multi’ integrator.

## neb_optimizer¶

Contains the required parameters for performing nudged elastic band (NEB) calculations

### ATTRIBUTES¶

modeThe geometry optimization algorithm to optimize NEB path

dtype: string

options: [‘bfgstrm’, ‘damped_bfgs’, ‘fire’]

default: fire

### FIELDS¶

tolerancesTolerance criteria to stop NEB optimization. If you work with DFT, do not use these defaults.

old_coordThe previous position in an optimization step.

dtype: float

dimension: length

default: [ ]

full_forceThe previous full-dimensional force in an optimization step.

dtype: float

dimension: force

default: [ ]

full_potsPrevious physical potentials of all beads.

dtype: float

dimension: energy

default: [ ]

old_nebpotentialPrevious NEB potential energy, which includes spring energy.

dtype: float

default: [ ]

old_nebgradientThe previous gradient including NEB spring forces.

dtype: float

default: [ ]

old_directionThe previous direction.

dtype: float

default: [ ]

biggest_stepThe maximum atomic displacement in a single step of optimizations within NEB procedure. If requested step is larger, it will be downscaled so that maximal atomic displacement won’t exceed biggest_step.

dtype: float

dimension: length

default: 0.5

scale_lbfgsScale choice for the initial hessian. 0 identity. 1 Use first member of position/gradient list. 2 Use last member of position/gradient list.

dtype: integer

default: 2

hessian_bfgsApproximate Hessian for damped_BFGS, if known.

dtype: float

default: [ ]

qlist_lbfgsList of previous position differences for L-BFGS, if known.

dtype: float

default: [ ]

glist_lbfgsList of previous gradient differences for L-BFGS, if known.

dtype: float

default: [ ]

corrections_lbfgsThe number of past vectors to store for L-BFGS.

dtype: integer

default: 5

dtmax_fireMaximum time interval per step for FIRE.

dtype: float

default: 1.0

v_fireCurrent velocity for FIRE

dtype: float

default: [ ]

alpha_firevelocity mixing factor for FIRE

dtype: float

default: 0.1

N_down_fireconsecutive steps in downhill dierction for FIRE

dtype: integer

default: 0

N_up_fireconsecutive steps in uphill direction

dtype: integer

default: 0

dt_firetime per step

dtype: float

default: 0.1

endpointsGeometry optimization of endpoints (not implemented yet)

springUniform or variable spring constants along the elastic band

tangentHow to calculate tangents: simple averaging from the original 1998 paper, or the improved tangent estimate from J. Chem. Phys. 113, 9978 (2000)

dtype: string

options: [‘plain’, ‘improved’]

default: improved

stageStage of the NEB pipeline: optimization of endpoints, NEB itself, climbing image

dtype: string

options: [‘endpoints’, ‘neb’, ‘climb’]

default: neb

use_climbUse climbing image NEB or not

dtype: boolean

default: False

climb_beadThe index of the climbing bead.

dtype: integer

default: -1

## normal_modes¶

Deals with the normal mode transformations, including the adjustment of bead masses to give the desired ring polymer normal mode frequencies if appropriate. Takes as arguments frequencies, of which different numbers must be specified and which are used to scale the normal mode frequencies in different ways depending on which ‘mode’ is specified.

### ATTRIBUTES¶

transformSpecifies whether to calculate the normal mode transform using a fast Fourier transform or a matrix multiplication. For small numbers of beads the matrix multiplication may be faster.

dtype: string

options: [‘fft’, ‘matrix’]

default: fft

propagatorHow to propagate the free ring polymer dynamics. Cayley transform is not exact but is strongly stable and avoid potential resonance issues. A bab scheme performs numerical verlet type propagation. All three options work for distinguishable particles. Only the bab propagator can be used with bosonic particles.

dtype: string

options: [‘exact’, ‘cayley’, ‘bab’]

default: exact

### FIELDS¶

Specifies normal mode frequencies for a (closed path) calculation

dtype: float

dimension: frequency

default: [ ]

open_pathsIndices of the atoms whose path should be opened (zero-based).

dtype: integer

default: [ ]Specify which atoms are bosons.

dtype: string

default: [ ]

nmtsThe number of iterations to perform one bab step.

dtype: integer

default: 10

## normalmodes¶

Vibrational self-consistent field class. Approximates the vibrational eigenstates and eigenvalues of a system by performing a normal mode expansion of the potential energy surface.

### ATTRIBUTES¶

modeThe algorithm to be used: independent mode framework (imf) and vibrational self consistent field (vscf).

dtype: string

options: [‘imf’, ‘vscf’]

default: imf

### FIELDS¶

prefixPrefix of the output files.

dtype: string

default:

asrRemoves the zero frequency vibrational modes depending on the symmetry of the system for general polyatomic molecules, and periodic crystal structures.

dtype: string

options: [‘none’, ‘poly’, ‘crystal’]

default: none

dynmatPortion of the dynamical matrix known to the current point in the calculation.

dtype: float

default: [ ]

nprimNumber of primitive unit cells in the simulation cell.

dtype: float

default: 1.0

fnmrmsFraction of harmonic RMS displacement used to sample along normal mode.

dtype: float

default: 1.0

nevibMultiple of harm vibr energy up to which BO surface is sampled.

dtype: float

default: 25.0

nintIntegration points for Hamiltonian matrix elements.

dtype: integer

default: 101

pair_rangeThe range of pair combinations of normal modes to be considered.

dtype: integer

default: [ ]

nbasisNumber of SHO states used as basis for anharmonic wvfn.

dtype: integer

default: 10

athreshConvergence threshold for absolute error in vibr free energy per degree of freedom.

dtype: float

dimension: energy

default: 3.6749322e-06

ethreshConvergence thresh for fractional error in vibr free energy.

dtype: float

default: 0.01

alphaThe fraction of mean field potential to mix with the result of the previous SCF iteration.

dtype: float

default: 1.0

nkbtThreshold for (e - e_gs)/(kB T) of vibr state to be incl in the VSCF and partition function.

dtype: float

default: 4.0

nexcMinimum number of excited n-body states to calculate (also in MP2 correction).

dtype: integer

default: 5

mptwoFlag determining whether MP2 correction is calculated.

dtype: boolean

default: False

solveFlag determining whether the VSCF mean field Schroedinger’s equation is solved.

dtype: boolean

default: False

gridFlag determining whether the coupling potential is gridded or not.

dtype: boolean

default: True

print_mftpotFlag determining whether MFT potentials are printed to file.

dtype: boolean

default: False

print_1b_mapFlag determining whether the independent mode potentials are printed to file.

dtype: boolean

default: False

print_2b_mapFlag determining whether the two body mapped coupling potentials are printed to file.

dtype: boolean

default: False

print_vib_densityFlag determining whether the vibrational density (psi**2) are printed to file.

dtype: boolean

default: False

threebodyFlag determining whether three-mode coupling terms are accounted for.

dtype: boolean

default: False

nparallelThe number of forces evaluations per i-PI step.

dtype: integer

default: 1

## optimizer¶

A Geometry Optimization class implementing most of the standard methods

### ATTRIBUTES¶

modeThe geometry optimization algorithm to be used

dtype: string

options: [‘sd’, ‘cg’, ‘bfgs’, ‘bfgstrm’, ‘lbfgs’, ‘damped_bfgs’]

default: lbfgs

### FIELDS¶

ls_options“Options for line search methods. Includes: tolerance: stopping tolerance for the search (as a fraction of the overall energy tolerance), iter: the maximum number of iterations, step: initial step for bracketing, adaptive: whether to update initial step.

exit_on_convergenceTerminates the simulation when the convergence criteria are met.

dtype: boolean

default: True

tolerancesConvergence criteria for optimization. Default values are extremely conservative. Set them to appropriate values for production runs.

biggest_stepThe maximum step size for (L)-BFGS line minimizations.

dtype: float

default: 100.0

scale_lbfgsScale choice for the initial hessian. 0 identity. 1 Use first member of position/gradient list. 2 Use last member of position/gradient list.

dtype: integer

default: 2

corrections_lbfgsThe number of past vectors to store for L-BFGS.

dtype: integer

default: 6

old_posThe previous positions in an optimization step.

dtype: float

dimension: length

default: [ ]

old_potThe previous potential energy in an optimization step.

dtype: float

dimension: energy

default: [ ]

old_forceThe previous force in an optimization step.

dtype: float

dimension: force

default: [ ]

old_directionThe previous direction in a CG or SD optimization.

dtype: float

default: [ ]

invhessian_bfgsApproximate inverse Hessian for BFGS, if known.

dtype: float

default: [ ]

hessian_trmApproximate Hessian for trm, if known.

dtype: float

default: [ ]

tr_trmThe trust radius in trm.

dtype: float

dimension: length

default: [ ]

qlist_lbfgsList of previous position differences for L-BFGS, if known.

dtype: float

default: [ ]

glist_lbfgsList of previous gradient differences for L-BFGS, if known.

dtype: float

default: [ ]

## output¶

This class defines how properties, trajectories and checkpoints should be output during the simulation. May contain zero, one or many instances of properties, trajectory or checkpoint tags, each giving instructions on how one output file should be created and managed.

### ATTRIBUTES¶

prefixA string that will be prepended to each output file name. The file name is given by ‘prefix’.’filename’ + format_specifier. The format specifier may also include a number if multiple similar files are output.

dtype: string

default: i-pi

### FIELDS¶

Each of the properties tags specify how to create a file in which one or more properties are written, one line per frame.

dtype: stringEach of the trajectory tags specify how to create a trajectory file, containing a list of per-atom coordinate properties.

dtype: stringEach of the checkpoint tags specify how to create a checkpoint file, which can be used to restart a simulation.

dtype: integer

## p_ramp¶

PressureRamp Motion class. It just updates the ensemble pressure in steps, between the indicated values, and then holds to the highest value. It should typically be combined with a dynamics class and barostats, using a MultiMotion.

### FIELDS¶

p_startInitial pressure

dtype: float

dimension: pressure

default: 1.0

p_endFinal pressure

dtype: float

dimension: pressure

default: 1.0

logscaleChange pressure on a logarihthmic scale.

dtype: boolean

default: False

total_stepsTotal number of steps for the ramp

dtype: integer

default: 0

current_stepCurrent step along the ramp

dtype: integer

default: 0

## planetary¶

Holds all the information for the planetary model frequency matrix calculator.

### ATTRIBUTES¶

modeThe constrained-centroid sampling mode.

dtype: string

options: [‘md’]

default: md

### FIELDS¶

The thermostat for the atoms, keeps the atom velocity distribution at the correct temperature.

timestepThe time step.

dtype: float

dimension: time

default: 1.0

nmtsNumber of iterations for each MTS level (including the outer loop, that should in most cases have just one iteration).

dtype: integer

default: [ ]

nsamplesNumber of samples to accumulate for each planetary step.

dtype: integer

default: 0

strideHow often the planetary calculation should actually be triggered.

dtype: integer

default: 1

nbeadsNumber of beads for centroid-constrained dynamics (default same as master trajectory)

dtype: integer

default: -1

screenScreening parameter for path-integral frequency matrix.

dtype: float

dimension: length

default: 0.0

## positions¶

This is the class to initialize positions.

*dtype*: string

### ATTRIBUTES¶

modeThe input data format. ‘xyz’ and ‘pdb’ stand for xyz and pdb input files respectively. ‘ase’ is to read a file with the Atomic Simulation Environment. ‘chk’ stands for initialization from a checkpoint file. ‘manual’ means that the value to initialize from is giving explicitly as a vector.

dtype: string

options: [‘manual’, ‘xyz’, ‘pdb’, ‘ase’, ‘chk’]

default: chk

index

dtype: integer

default: -1

bead

dtype: integer

default: -1

## prng¶

Deals with the pseudo-random number generator.

### FIELDS¶

seedThis is the seed number used to generate the initial state of the random number generator.

dtype: integer

default: 123456

stateGives the state vector for the random number generator. Avoid directly modifying this unless you are very familiar with the inner workings of the algorithm used.

dtype: integer

default: [ ]

has_gaussDetermines whether there is a stored gaussian number or not. A value of 0 means there is none stored.

dtype: integer

default: 0

gaussThe stored Gaussian number.

dtype: float

default: 0.0

set_posGives the position in the state array that the random number generator is reading from.

dtype: integer

default: 0

## properties¶

This class deals with the output of properties to one file. Between each property tag there should be an array of strings, each of which specifies one property to be output.

*dtype*: string

### ATTRIBUTES¶

shapeThe shape of the array.

dtype: tuple

default: (0,)

mode

dtype: string

options: [‘manual’, ‘file’]

default: manual

filenameA string to specify the name of the file that is output. The file name is given by ‘prefix’.’filename’ + format_specifier. The format specifier may also include a number if multiple similar files are output.

dtype: string

default: out

strideThe number of steps between successive writes.

dtype: integer

default: 1

flushHow often should streams be flushed. 1 means each time, zero means never.

dtype: integer

default: 1

## remd¶

Replica Exchange

### FIELDS¶

strideEvery how often to try exchanges (on average).

dtype: float

default: 1.0

krescaleRescale kinetic energy upon exchanges.

dtype: boolean

default: True

swapfileFile to keep track of replica exchanges

dtype: string

default: remd_idx

repindexList of current indices of the replicas compared to the starting indices

dtype: integer

default: [ ]

## scp¶

Self-consistent phonons class. It variationally optimizes the free energy to calculate the best harmonic approximation to a system.

### ATTRIBUTES¶

modeThe statistics to be used in the calculation of the free energy. Quantum (qn) or classical (cl) Boltzmann statistics.

dtype: string

options: [‘qn’, ‘cl’]

default: qn

### FIELDS¶

prefixPrefix of the output files.

dtype: string

default:

asrThe method used to project out zero modes coming from continuous symmetries: crystal removes the three translational modes; molecule removes the three rotational modes in addition to the translational ones. none keeps all the modes.

dtype: string

options: [‘none’, ‘crystal’, ‘poly’]

default: none

random_typeChooses the type of random numbers.

dtype: string

options: [‘sobol’, ‘pseudo’, ‘file’]

default: pseudo

displace_modeThe type of optimisation strategy for obtaining the mean position. sd stands for a steepest descent algorithm. ik stands for a Newton-Raphson scheme that requires the inverse of the force constant matrix iK. nmik stands for a Newton-Raphson scheme that only displaces along normal modes directions with statistically significant forces. rnmik same as nmik but performs several optimization steps using a reweighted sampling.

dtype: string

options: [‘ik’, ‘sd’, ‘nmik’, ‘rnmik’]

default: nmik

dynmatThe dynamical matrix of the trial Hamiltonian.

dtype: float

default: [ ]

max_stepsMaximum number of Monte carlo steps per SCP iteration.

dtype: integer

max_iterMaximum number of SCP iterations.

dtype: integer

default: 1

tauStep size along the gradient for the sd displace_mode

dtype: float

default: 1.0

wthresholdThreshold on minimum Boltzmann weights before more statistics must be accumulated.

dtype: float

default: 0.9

precheckFlag for checking statistical significance of forces before optimisation of mean position.

dtype: boolean

default: True

checkweightsFlag for checking Boltzmann weights for whether more statistics are required.

dtype: boolean

default: True

chopThreshold below which frequencies are set to zero.

dtype: float

default: 1e-09

nparallelThe number of Monte Carlo forces to be evaluated (in parallel) per i-PI step.

dtype: integer

default: 1

batch_weight_exponentThe exponent used to suppress low batch weights.

dtype: integer

default: 1

## simulation¶

This is the top level class that deals with the running of the simulation, including holding the simulation specific properties such as the time step and outputting the data.

### ATTRIBUTES¶

verbosityThe level of output on stdout.

dtype: string

options: [‘quiet’, ‘low’, ‘medium’, ‘high’, ‘debug’]

default: medium

threadingWhether multiple-systems execution should be parallel. Makes execution non-reproducible due to the random number generator being used from concurrent threads.

dtype: boolean

default: True

modeWhat kind of simulation should be run.

dtype: string

options: [‘md’, ‘static’]

default: md

safe_strideConsistent simulation states will be saved every this number of steps. Saving state entails a small overhead, so you may want to set this to the smallest output frequency in your simulation to make i-PI faster. Use at your own risk!

dtype: integer

default: 1

floatformatA format for all printed floats.

dtype: string

default: %16.8e

### FIELDS¶

Deals with the pseudo-random number generator.

This class defines how properties, trajectories and checkpoints should be output during the simulation. May contain zero, one or many instances of properties, trajectory or checkpoint tags, each giving instructions on how one output file should be created and managed.

stepThe current simulation time step.

dtype: integer

default: 0

total_stepsThe total number of steps that will be done. If ‘step’ is equal to or greater than ‘total_steps’, then the simulation will finish.

dtype: integer

default: 1000

total_timeThe maximum wall clock time (in seconds).

dtype: float

default: 0Options for a ‘super-motion’ step between system replicas

This is the class which holds all the data which represents a single state of the system.

Generic input value

Deals with the assigning of force calculation jobs to different driver codes, and collecting the data, using a socket for the data communication.

Simple, internal LJ evaluator without cutoff, neighbour lists or minimal image convention. Expects standard LJ parameters, e.g. { eps: 0.1, sigma: 1.0 }.

Simple, internal DMD evaluator without without neighbor lists, but with PBC. Expects coupling elements (n*(n-1)/2 of them), oscillating frequency and time step.

Harmonic energy calculator

Direct PLUMED interface

Uses a Yaff force field to compute the forces.

Combines multiple forcefields to build a committee model, that can be used to compute uncertainty-quantified machine-learning models. Each forcefield can be any of the other FF objects, and each should be used with a client that generates a slightly different estimation of energy and forces. These are averaged, and the mean used as the actual forcefield. Statistics about the distribution are also returned as extras fields, and can be printed for further postprocessing. It is also possible for a single FF object to return a JSON-formatted string containing entries committee_pot, committee_force and committee_virial, that contain multiple members at once. These will be unpacked and combined with whatever else is present. Also contains options to use it for uncertainty estimation and for active learning in a ML context, based on a committee model. Implements the approaches discussed in [Musil et al.](http://doi.org/10.1021/acs.jctc.8b00959) and [Imbalzano et al.](http://doi.org/10.1063/5.0036522)

A SGDML energy calculator

A cavity molecular dynamics driver for vibraitonal strong coupling. In the current implementation, only a single cavity mode polarized along the x and y directions is coupled to the molecules. Check https://doi.org/10.1073/pnas.2009272117 and also examples/lammps/h2o-cavmd/ for details.

## smotion¶

Allow chosing the type of smotion to be performed. Holds all the information that is calculation specific, such as replica exchange parameters, etc.

### ATTRIBUTES¶

modeKind of smotion which should be performed.

dtype: string

options: [‘dummy’, ‘remd’, ‘metad’, ‘dmd’, ‘multi’]

### FIELDS¶

## string_optimizer¶

Contains the required parameters for performing string minimal energy path optimization.

### ATTRIBUTES¶

modeThe geometry optimization algorithm to optimize MEP string

dtype: string

options: [‘sd’, ‘cg’, ‘bfgs’, ‘bfgstrm’, ‘damped_bfgs’, ‘lbfgs’, ‘fire’, ‘euler’]

default: bfgstrm

### FIELDS¶

tolerancesTolerance criteria to stop String optimization. If you work with DFT, do not use these defaults.

old_coordThe previous position in an optimization step.

dtype: float

dimension: length

default: [ ]

full_forceThe previous full-dimensional force in an optimization step.

dtype: float

dimension: force

default: [ ]

full_potsPrevious physical potentials of all beads.

dtype: float

dimension: energy

default: [ ]

old_stringpotentialPrevious string potential energy.

dtype: float

default: [ ]

old_stringgradientThe previous gradient of the string.

dtype: float

default: [ ]

old_directionThe previous direction.

dtype: float

default: [ ]

biggest_stepThe maximum atomic displacement in a single step of optimizations within String MEP procedure. If requested step is larger, it will be downscaled so that maximal atomic displacement won’t exceed biggest_step.

dtype: float

dimension: length

default: 0.5

scale_lbfgs

dtype: integer

default: 2

hessian_bfgsApproximate Hessian for damped_BFGS, if known.

dtype: float

default: [ ]

qlist_lbfgsList of previous position differences for L-BFGS, if known.

dtype: float

default: [ ]

glist_lbfgsList of previous gradient differences for L-BFGS, if known.

dtype: float

default: [ ]

corrections_lbfgsThe number of past vectors to store for L-BFGS.

dtype: integer

default: 5

tr_trmStarting value for the trust radius for BFGSTRM.

dtype: float

dimension: length

default:[1.]

dtmax_fireMaximum time interval per step for FIRE.

dtype: float

default: 1.0

v_fireCurrent velocity for FIRE

dtype: float

default: [ ]

alpha_firevelocity mixing factor for FIRE

dtype: float

default: 0.1

N_down_fireconsecutive steps in downhill dierction for FIRE

dtype: integer

default: 0

N_up_fireconsecutive steps in uphill direction

dtype: integer

default: 0

dt_firetime per step

dtype: float

default: 0.1

endpointsGeometry optimization of endpoints (not implemented yet)

stageStage of the String pipeline: optimization of the endpoints, string opt., climbing image opt.

dtype: string

options: [‘endpoints’, ‘string’, ‘climb’]

default: string

use_climbUse climbing image String MEP or not

dtype: boolean

default: False

climb_beadThe index of the climbing bead.

dtype: integer

default: -1

## system¶

This is the class which holds all the data which represents a single state of the system.

### ATTRIBUTES¶

prefixPrepend this string to output files generated for this system.

dtype: string

default:

### FIELDS¶

Specifies the number of beads, and how the system should be initialized.

Deals with creating all the necessary forcefield objects.

Holds all the information that is ensemble specific, such as the temperature and the external pressure.

Allow chosing the type of calculation to be performed. Holds all the information that is calculation specific, such as geometry optimization parameters, etc.

Describes the bead configurations in a path integral simulation.

Deals with the normal mode transformations, including the adjustment of bead masses to give the desired ring polymer normal mode frequencies if appropriate. Takes as arguments frequencies, of which different numbers must be specified and which are used to scale the normal mode frequencies in different ways depending on which ‘mode’ is specified.

Describes with the cell parameters. Takes as array which can be used to initialize the cell vector matrix. N.B.: the cell parameters are stored with the lattice vectors in the columns, and the cell must be oriented in such a way that the array is upper-triangular (i.e. with the first vector aligned along x and the second vector in the xy plane).

dtype: float

dimension: length

default:[0. 0. 0. 0. 0. 0. 0. 0. 0.]

## system_template¶

Generic input value

### FIELDS¶

templateA string that will be read verbatim containing the model for a system to be generated

dtype: string

labelsA list of strings that should be substituted in the template to create multiple systems

dtype: string

instanceA list of strings that should the labels creating one system instance

dtype: string

## t_ramp¶

TemperatureRamp Motion class. It just updates the ensemble temperature in steps, between the indicated temperatures, and then holds to the highest value. It should typically be combined with a dynamics class and thermostats, using a MultiMotion.

### FIELDS¶

t_startInitial temperature

dtype: float

dimension: energy

default: 1.0

t_endFinal temperature

dtype: float

dimension: energy

default: 1.0

logscaleChange temperature on a logarihthmic scale.

dtype: boolean

default: False

total_stepsTotal number of steps for the ramp

dtype: integer

default: 0

current_stepCurrent step along the ramp

dtype: integer

default: 0

## thermostat¶

Simulates an external heat bath to keep the velocity distribution at the correct temperature.

### ATTRIBUTES¶

modeThe style of thermostatting. ‘langevin’ specifies a white noise langevin equation to be attached to the cartesian representation of the momenta. ‘svr’ attaches a velocity rescaling thermostat to the cartesian representation of the momenta. Both ‘pile_l’ and ‘pile_g’ attaches a white noise langevin thermostat to the normal mode representation, with ‘pile_l’ attaching a local langevin thermostat to the centroid mode and ‘pile_g’ instead attaching a global velocity rescaling thermostat. ‘gle’ attaches a coloured noise langevin thermostat to the cartesian representation of the momenta, ‘nm_gle’ attaches a coloured noise langevin thermostat to the normal mode representation of the momenta and a langevin thermostat to the centroid and ‘nm_gle_g’ attaches a gle thermostat to the normal modes and a svr thermostat to the centroid. ‘cl’ represents a modified langevin thermostat which compensates for additional white noise from noisy forces or for dissipative effects. ‘ffl’ is the fast-forward langevin thermostat, in which momenta are flipped back whenever the action of the thermostat changes its direction. ‘multiple’ is a special thermostat mode, in which one can define multiple thermostats _inside_ the thermostat tag.

dtype: string

options: [‘’, ‘langevin’, ‘svr’, ‘pile_l’, ‘pile_g’, ‘gle’, ‘nm_gle’, ‘nm_gle_g’, ‘cl’, ‘ffl’, ‘multi’]

### FIELDS¶

ethermoThe initial value of the thermostat energy. Used when the simulation is restarted to guarantee continuity of the conserved quantity.

dtype: float

dimension: energy

default: 0.0

tauThe friction coefficient for white noise thermostats.

dtype: float

dimension: time

default: 0.0

pile_lambdaScaling for the PILE damping relative to the critical damping. (gamma_k=2*lambda*omega_k

dtype: float

default: 1.0

pile_centroid_tOption to set a different centroid temperature wrt. that of the ensemble. Only used if value other than 0.0.

dtype: float

dimension: temperature

default: 0.0

AThe friction matrix for GLE thermostats.

dtype: float

dimension: frequency

default: [ ]

CThe covariance matrix for GLE thermostats.

dtype: float

dimension: temperature

default: [ ]

sInput values for the additional momenta in GLE.

dtype: float

dimension: ms-momentum

default: [ ]

intauThe inherent noise time scale for compensating langevin thermostats.

dtype: float

dimension: time

default: 0.0

idtauThe inherent dissipation time scale for compensating langevin thermostats.

dtype: float

dimension: time

default: 0.0

apatThe time scale for automatic adjustment of CL thermostat’s parameters.

dtype: float

dimension: time

default: 0.0

flipFlipping type for ffl thermostat (‘soft’, ‘hard’, ‘rescale’, ‘none’)

dtype: string

default: rescaleThe thermostat for the atoms, keeps the atom velocity distribution at the correct temperature.

## trajectory¶

This class defines how one trajectory file should be output. Between each trajectory tag one string should be given, which specifies what data is to be output.

*dtype*: string

### ATTRIBUTES¶

filenameA string to specify the name of the file that is output. The file name is given by ‘prefix’.’filename’ + format_specifier. The format specifier may also include a number if multiple similar files are output.

dtype: string

default: traj

strideThe number of steps between successive writes.

dtype: integer

default: 1

formatThe output file format.

dtype: string

options: [‘xyz’, ‘pdb’, ‘ase’]

default: xyz

cell_unitsThe units for the cell dimensions.

dtype: string

default:

beadPrint out only the specified bead. A negative value means print only one every -(bead) beads, e.g. -2 means print just the even beads, -4 one every four and so on.

dtype: integer

default: -1

flushHow often should streams be flushed. 1 means each time, zero means never.

dtype: integer

default: 1

extra_typeWhat extra to print from the different extra strings.

dtype: string

default: raw

## velocities¶

This is the class to initialize velocities.

*dtype*: string

### ATTRIBUTES¶

modeThe input data format. ‘xyz’ and ‘pdb’ stand for xyz and pdb input files respectively. ‘chk’ stands for initialization from a checkpoint file. ‘manual’ means that the value to initialize from is giving explicitly as a vector. ‘thermal’ means that the data is to be generated from a Maxwell-Boltzmann distribution at the given temperature.

dtype: string

options: [‘manual’, ‘xyz’, ‘pdb’, ‘ase’, ‘chk’, ‘thermal’]

default: chk

index

dtype: integer

default: -1

bead

dtype: integer

default: -1

## vibrations¶

Dynamical matrix Class. It calculates phonon modes and frequencies in solids as well as normal vibrational modes and frequencies of aperiodic systems.

### ATTRIBUTES¶

modeThe algorithm to be used: finite differences (fd), normal modes finite differences (nmfd), and energy-scaled normal mode finite differences (enmfd).

dtype: string

options: [‘fd’, ‘nmfd’, ‘enmfd’]

default: fd

### FIELDS¶

pos_shiftThe finite displacement in position used to compute derivative of force.

dtype: float

default: 0.01

energy_shiftThe finite displacement in energy used to compute derivative of force.

dtype: float

default: 0.0

output_shiftShift by the dynamical matrix diagonally before outputting.

dtype: float

default: 0.0

prefixPrefix of the output files.

dtype: string

default: phonons

asrRemoves the zero frequency vibrational modes depending on the symmerty of the system.

dtype: string

options: [‘none’, ‘poly’, ‘lin’, ‘crystal’]

default: none

dynmatPortion of the dynamical matrix known up to now.

dtype: float

default: [ ]

refdynmatPortion of the refined dynamical matrix known up to now.

dtype: float

default: [ ]