Quick jobs
**********

Quick jobs that take 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: Molecule, model: str = 'UFF', settings: Settings | None = None, nproc: int = 1, maxiterations: int = 100) -> Molecule
preoptimize(molecule: Sequence[Molecule], model: str = 'UFF', settings: Settings | None = None, nproc: int = 1, maxiterations: int = 100) -> List[Molecule]

   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)

   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.

   Parameters:
      * **molecule** (*Molecule*) --

      * **density** (*float*) --

      * **step_size** (*int*) --

      * **model** (*str*) --

      * **settings** (*Settings** | **None*) --

      * **nproc** (*int*) --

      * **maxiterations** (*int*) --

   Return type:
      *Molecule*

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

   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.

   Parameters:
      * **molecule** (*Molecule*) --

      * **lattice** (*List**[**List**[**float**]**]*) --

      * **n_points** (*int** | **None*) --

      * **max_strain** (*float*) --

      * **model** (*str*) --

      * **settings** (*Settings** | **None*) --

      * **nproc** (*int*) --

      * **maxiterations** (*int*) --

   Return type:
      *Molecule* | None

shakemd(molecule, density=None, nsteps=4000, model='UFF', settings=None, nproc=1)

   Performs SHAKE MD simulation with all bonds fixed. If "density" is
   specified, a lattice deformation will also be applied.

   The temperature is 100 K and the time step 0.5 fs.

   Returns: a Molecule corresponding to the final MD step.

   molecule: Molecule
      The initial structure

   density: float, optional
      If specified, the molecule must have a 3D lattice. Target
      density in kg/m^3   (1000x the density in g/cm^3)

   nsteps: int
      Number of MD steps.

   model: str
      e.g. 'UFF'

   settings: Settings
      Engine settings (overrides "model")

   Parameters:
      * **molecule** (*Molecule*) --

      * **density** (*float** | **None*) --

      * **nsteps** (*int*) --

      * **model** (*str*) --

      * **settings** (*Settings** | **None*) --

      * **nproc** (*int*) --

   Return type:
      *Molecule*
