Quick jobs

Quick jobs that take in a structure and return a modified structure. For example, the preoptimize() function lets you quickly optimize a molecule without storing any results on disk. This mimics the preoptimize function of the AMS GUI.

You can specify the model string as a shorthand for engine settings:

  • ‘UFF’: the UFF force field

  • ‘GFNFF’: the GFNFF force field

  • ‘ANI-2x’: The ANI-2X machine learning potential

Alternatively, you can specify settings which will override the model.

preoptimize(molecule, model='UFF', settings=None, nproc=1, maxiterations=100)[source]

Returns an optimized Molecule (or list of optimized molecules)

molecule: Molecule or list of Molecules

Molecule to optimize

model: str

Shorthand for some model, e.g. ‘UFF’

settings: Settings

Custom engine settings (overrides model)

nproc: int

Number of processes

maxiterations: int

Maximum number of iterations for the geometry optimization.

refine_density(molecule, density, step_size=50, model='UFF', settings=None, nproc=1, maxiterations=100)[source]

Performs a series of geometry optimizations with densities approaching density. This can be useful if you want to compress a system to a given density, but cannot just use apply_strain() (because apply_strain() also scales the bond lengths).

This function can be useful if for example packmol does not succeed to pack molecules with the desired density. Packmol can then generate a structure with a lower density, and this function can be used to increase the density to the desired value.

Returns: a Molecule with the requested density.

molecule: Molecule

The molecule must have a 3D lattice

density: float

Target density in kg/m^3 (1000x the density in g/cm^3)

step_size: float

Step size for the density (in kg/m^3). Set step_size to a large number to only use 1 step.

model: str

e.g. ‘UFF’

settings: Settings

Engine settings (overrides model)

maxiterations: int

maximum number of iterations for the geometry optimization.

refine_lattice(molecule, lattice, n_points=None, max_strain=0.15, model='UFF', settings=None, nproc=1, maxiterations=10)[source]

Returns a Molecule for which the lattice of the molecule is transformed to lattice, by performing short geometry optimizations (each for at most maxiterations) on gradually distorted lattices (linearly interpolating from the original lattice to the new lattice using n_points points).

This can be useful for transforming an orthorhombic box of a liquid into a non-orthorhombic box of a liquid, where the gradual transformation of the lattice ensures that the molecules do not become too distorted.

If init() has been called before calling this function, the job will be run in the current PLAMS working directory and will be deleted when the job finishes.

Returns: a Molecule with the requested lattice. If the refinement fails, None is returned.

molecule: Molecule

The initial molecule

lattice: list of list of float

List with 1, 2, or 3 elements. Each element is a list of float with 3 elements each. For example, lattice=[[10, 0, 0],[-5, 5, 0],[0, 0, 12]].

n_points: None or int >=2

Number of points used for the linear interpolation. If None, n_points will be chosen such that the maximum strain for any step is at most max_strain compared to the original lattice vector lengths.

max_strain: float

Only if n_points=None, use this value to determine the maximum allowed strain from one step to the next (as a fraction of the length of the original lattice vectors).

model: str

e.g. ‘UFF’

settings: Settings

Engine settings (overrides model)

nproc: int

Number of processes used by the job

maxiterations: int

maximum number of iterations for the geometry optimizations.