Recipes

These recipe workflows are shipped with PLAMS and can be imported directly. Each recipe includes details and API documentation.

COSMO-RS Compound

Generate .coskf files equivalent to AMS GUI task “COSMO-RS Compound”.

Use this recipe when you want an easy Python interface for generating COSMO-RS compound files (.coskf) from one or many input structures.

class ADFCOSMORSCompoundJob(molecule, coskf_name=None, coskf_dir=None, preoptimization=None, singlepoint=False, settings=None, mol_info=None, hbc_from_MESP=False, **kwargs)

A class for performing the equivalent of Task: COSMO-RS Compound in the AMS GUI

Parameters:

molecule – a PLAMS Molecule

Keyword Arguments:

• coskf_name – A name for the generated .coskf file. If nothing is specified, the name of the job will be used.

• coskf_dir – The directory in which to place the generated .coskf file. If nothing is specified, the file will be put in the plams directory corresponding to the job.

• preoptimization – If None, do not preoptimize with a fast engine priori to the optimization with ADF. Otherwise, it can be one of ‘UFF’, ‘GAFF’, ‘GFNFF’, ‘GFN1-xTB’, ‘ANI-2x’, ‘M3GNet-UP-2022’. Note that you need valid licenses for ForceField or DFTB or MLPotential to use these preoptimizers.

• singlepoint (bool) – Run a singlepoint in gasphase and with solvation to generate the .coskf file on the given Molecule. (no geometry optimization). Cannot be combined with preoptimization.

• settings (Settings) – A Settings object. settings.runscript.nproc, settings.input.adf.custom_options. If ‘adf’ is in settings.input it should be provided without the solvation block.

• mol_info (dict) – an optional dictionary containing information will be written to the Compound Data section within the COSKF file.

• hbc_from_MESP (bool) – Defaults to False. Performs DENSF analysis to determine the hydrogen bond center (HBC) used in COSMOSAC-DHB-MESP.

• name – an optional name for the calculation directory

Example

mol = from_smiles('O')
job = ADFCOSMORSCompoundJob(
    molecule = mol,
    preoptimization = 'UFF',
    coskf_dir = 'coskfs',
    coskf_name = 'Water',
    name = 'H2O',
    mol_info = {'CAS':'7732-18-5'}
)
job.run()
print(job.results.coskfpath())

_result_type

alias of ADFCOSMORSCompoundResults

static _get_radii()

Method to get the atomic radii from solvent.txt (for some elements the radii are instead the Klamt radii)

Return type:

Dict[str, float]

static adf_settings(solvation, settings=None, elements=None, atomic_ion=False)

Returns ADF settings with or without solvation

If solvation == True, then also include the solvation block.

Parameters:

• solvation (bool) –

• elements (List[str] | None) –

• atomic_ion (bool) –

Return type:

Settings

static convert_to_coskf(rkf_path, coskf_name, plams_dir, coskf_dir=None, mol_info=None, densf_path=None)

Convert an adf.rkf file into a .coskf file

Parameters:

• rkf_path (str) – absolute path to adf.rkf

• coskf_name (str) – the name of the .coskf file

• plams_dir (str) – plamsjob path to write out the .coskf file

• coskf_dir (Optional[str]) – additional path to store the .coskf file

• mol_info (Optional[Dict[str, Union[float, int, str]]]) – Optional information to write out in the “Compound Data” section of the .coskf file

• densf_path (Optional[str]) – path to the densf output .t41 file

Return type:

None

static update_hbc_to_coskf(coskf, visulization=False)

Determine the hydrogen bond center for existing COSKF file

Parameters:

• coskf (str) – Existing COSKF file

• visulization (bool) – Visulization of hydrogen bond center

Return type:

None

class ADFCOSMORSCompoundResults(job)

Results class for ADFCOSMORSCompoundJob

Parameters:

job (Job) –

coskfpath()

Returns the path to the resulting .coskf

get_main_molecule()

Returns the optimized molecule

get_input_molecule()

Returns the input molecule

get_sigma_profile(subsection='profil')

Returns the sigma profile of the molecule. For more details see CRSResults.get_sigma_profile.

Parameters:

subsection (str) –

COSMO-RS Conformers

Build customizable conformer workflows that end in ADF/COSMO calculations for COSMO-RS.

This recipe builds a configurable conformer-generation pipeline and produces .coskf files for the selected conformers.

class ADFCOSMORSConfJob(molecule, conf_gen=None, first_filter=None, additional=None, final_filter=None, adf_singlepoint=False, initial_conformers=500, coskf_dir=None, coskf_name=None, mol_info=None, hbc_from_MESP=False, **kwargs)

Multi-step conformer workflow for generating COSMO-RS .coskf files:

job_0: initial conformer generation
(default RDKit generator or user-provided conf_gen)
  |-- apply first_filter (if provided)
  v
job_i: optional refinement stages from additional
(for each (Settings, Filter) tuple, e.g. DFTB)
  |-- apply its filter after each stage
  v
adf_gas_job: gas-phase ADF conformer job
  |-- if adf_singlepoint=True: single-point only
  v
final_filter_job: apply final_filter (if provided)
  v
Branch on hbc_from_MESP:
  |-- False: replay_job -> COSMO results (.coskf)
  `-- True: per conformer job_cosmo + job_densf
        `-> COSMO + hydrogen bond center (.coskf)

Parameters:

• molecule – Input PLAMS molecule.

• conf_gen – User-provided job for initial conformer generation.

• initial_conformers – Number of conformers generated by the default conf_gen (RDKit). Defaults to 500.

• first_filter – Filter applied after initial conformer generation.

• additional – Optional extra conformer-refinement stages and their filters (e.g., with a fast engine such as DFTB).

• final_filter – Filter applied after gas-phase ADF conformer generation.

• adf_singlepoint – If True, run gas-phase ADF conformer jobs without optimization. Defaults to False.

• hbc_from_MESP – If True, determine the hydrogen-bond center (hbc) via DENSF analysis (COSMOSAC-DHB-MESP). Defaults to False.

• coskf_dir – Output directory for generated .coskf files.

• coskf_name – Base filename for conformers (e.g., {coskf_name}_{i}.coskf). Default to conformer.

• mol_info – Extra metadata written to “Compound Data” (e.g. IUPAC, CAS, SMILES and Other Name).

• name – Optional PLAMS job name. Default to plams.

_result_type

alias of ADFCOSMORSConfResults

new_children()

Generate new children jobs.

This method is useful when some of children jobs are not known beforehand and need to be generated based on other children jobs, like for example in any kind of self-consistent procedure.

The goal of this method is to produce a new portion of children jobs. Newly created jobs should be returned in a container compatible with self.children (e.g. list for list, dict for dict). No adjustment of newly created jobs’ parent attribute is needed. This method cannot modify _active_children attribute.

The method defined here is a default template, returning None, which means no new children jobs are generated and the entire execution of the parent job consists only of running jobs initially found in self.children. To modify this behavior you can override this method in a MultiJob subclass or you can use one of Binding decorators, just like with Prerun and postrun methods.

prerun()

Actions to take before the actual job execution.

This method is initially empty, it can be defined in subclasses or directly added to either the whole class or a single instance using Binding decorators.

postrun()

Actions to take just after the actual job execution.

This method is initially empty, it can be defined in subclasses or directly added to either the whole class or a single instance using Binding decorators.

class ADFCOSMORSConfFilter(max_num_confs=None, max_energy_range=None)

This class allows the user to specify criteria on which to filter sets of conformers.

Parameters:

• max_num_confs (int | None) – The maximum number of conformers to bring forward to the next step. These are automatically ordered by energy, so the first n lowest energy structures are carried carried forward to the next step.

• max_energy_range (float | None) – The maximum allowable difference (in kcal/mol) between the lowest energy conformer and the highest energy conformer that will be carried forward. For example, for a max_energy_range of 2 kcal/mol and a lowest energy structure of 1 kcal/mol, any structure with an energy above 3 (1+2) kcal/mol will be filtered out.

class ADFCOSMORSConfResults(job)

Parameters:

job (Job) –

MD Jobs

Convenience job classes for MD simulation setup, restart/spawning, and common trajectory analyses.

These classes wrap common AMS MolecularDynamics patterns (NVE/NVT/NPT), restarts and spawned ensembles, plus trajectory analysis jobs.

class AMSMDJob(velocities=None, timestep=None, samplingfreq=None, nsteps=None, checkpointfrequency=None, engineresultsfreq=None, writevelocities=None, writebonds=None, writemolecules=None, writecharges=None, writeenginegradients=None, calcpressure=None, molecule=None, temperature=None, thermostat=None, tau=None, thermostat_region=None, pressure=None, barostat=None, barostat_tau=None, scale=None, equal=None, constantvolume=None, binlog_time=None, binlog_pressuretensor=None, binlog_dipolemoment=None, _enforce_thermostat=False, _enforce_barostat=False, **kwargs)

molecule: Molecule

The initial structure

name: str

The name of the job

settings: Settings

Settings for the job. You should normally not populate neither settings.input.ams.MolecularDynamics nor settings.input.ams.Task

velocities: float or AMSJob or str (path/to/ams.rkf) or 2-tuple (path/to/ams.rkf, frame-number)

If float, it is taken as the temperature. If AMSJob or str, the velocities are taken from the EndVelocities section of the corresponding ams.rkf file. If 2-tuple, the first item must be a path to an ams.rkf, and the second item an integer specifying the frame number - the velocities are then read from History%Velocities(framenumber).

timestep: float

Timestep

samplingfreq: int

Sampling frequency

nsteps: int

Length of simulation

Trajectory options:

checkpointfrequency: int

How frequently to write MDStep*.rkf checkpoint files

writevelocitiesbool

Whether to save velocities to ams.rkf (needed for example to restart from individual frames or to calculate velocity autocorrelation functions)

writebonds: bool

Whether to save bonds to ams.rkf

writemolecules: bool

Whether to write molecules to ams.rkf

writeenginegradients: bool

Whether to save engine gradients (negative of atomic forces) to ams.rkf

Thermostat (NVT, NPT) options:

thermostat: str

‘Berendsen’ or ‘NHC’

tau: float

Thermostat time constant (fs)

temperature: float or tuple of floats

Temperature (K). If a tuple/list of floats, the Thermostat.Duration option will be set to evenly divided intervals.

thermostat_region: str

Region for which to apply the thermostat

Barostat (NPT) options:

barostat: str

‘Berendsen’ or ‘MTK’

barostat_tau: float

Barostat time constant (fs)

pressure: float

Barostat pressure (pascal)

equal: str

‘XYZ’ etc.

scale: str

‘XYZ’ etc.

constantvolume: bool

Constant volume?

Other options:

calcpressure: bool

Whether to calculate pressure for each frame.

binlog_time: bool

Whether to log the time at every timestep in the BinLog section on ams.rkf

binlog_pressuretensor: bool

Whether to log the pressure tensor at every timestep in the BinLog section on ams.rkf

Parameters:

• samplingfreq (int) –

• nsteps (int) –

• molecule (Molecule | Dict[str, Molecule] | ChemicalSystem | Dict[str, ChemicalSystem] | None) –

• temperature (float) –

get_velocities_from(other_job, frame=None, update_molecule=True)

Function to update the InitialVelocities block in self. It is normally not needed, instead use the e.g. AMSNVEJob.restart_from() function.

This function can be called in prerun() methods for MultiJobs

classmethod restart_from(other_job, frame=None, settings=None, use_prerun=False, **kwargs)

other_job: AMSJob

The job to restart from.

frame: int

Which frame to read the structure and velocities from. If None, the final structure and end velocities will be used (section Molecule and MDResults%EndVelocities)

settings: Settings

Settings that override any other settings. All settings from other_job (e.g. the engine settings) are inherited by default but they can be overridden here.

use_prerun: bool

If True, the molecule and velocities will only be read from other_job inside the prerun() method. Set this to True to prevent PLAMS from waiting for other_job to finish as soon as the new job is defined.

kwargs: many options

See the docstring for AMSMDJob.

class AMSNVEJob(**kwargs)

A class for running NVE MD simulations

class AMSNVTJob(**kwargs)

A class for running NVT MD simulations

class AMSNPTJob(**kwargs)

A class for running NPT MD simulations

class AMSNPTResults(*args, **kwargs)

Parameters:

• args (Any) –

• kwargs (Any) –

get_equilibrated_molecule(equilibration_fraction=0.667, return_index=False)

Discards the first equilibration_fraction of the trajectory. Calculates the average density of the rest. Returns the molecule with the closest density to the average density among the remaining trajectory.

class AMSNVESpawnerJob(previous_job, n_nve=1, name='nvespawnerjob', **kwargs)

A class for running multiple NVE simulations with initial structures/velocities taken from an NVT trajectory. The NVT trajectory must contain the velocities!

__init__(previous_job, n_nve=1, name='nvespawnerjob', **kwargs)

previous_job: AMSJob

An AMSJob with an MD trajectory. Must contain velocities (WriteVelocities Yes). Note that the trajectory should have been equilibrated before it starts.

n_nveint

The number of NVE simulations to spawn

All other settings can be set as for an AMSNVEJob (e.g. nsteps).

prerun()

Constructs the children jobs

class AMSMDScanDensityJob(molecule, scan_density_upper=1.4, startstep=None, **kwargs)

A class for scanning the density using MD Deformations

Parameters:

molecule (Molecule | Dict[str, Molecule] | ChemicalSystem | Dict[str, ChemicalSystem] | None) –

class AMSMSDJob(previous_job=None, max_correlation_time_fs=10000, start_time_fit_fs=2000, atom_indices=None, **kwargs)

A convenient class wrapping around the trajectory analysis MSD tool

Parameters:

• max_correlation_time_fs (float) –

• start_time_fit_fs (float) –

• atom_indices (List[int]) –

__init__(previous_job=None, max_correlation_time_fs=10000, start_time_fit_fs=2000, atom_indices=None, **kwargs)

previous_job: AMSJob

An AMSJob with an MD trajectory. Note that the trajectory should have been equilibrated before it starts.

max_correlation_time_fs: float

Maximum correlation time in femtoseconds

start_time_fit_fsfloat

Smallest correlation time for the linear fit

atom_indicesList[int]

If None, use all atoms. Otherwise use the specified atom indices (starting with 1)

kwargs: dict

Other options to AMSAnalysisJob

Parameters:

• max_correlation_time_fs (float) –

• start_time_fit_fs (float) –

• atom_indices (List[int] | None) –

get_input()

Generate the input file

prerun()

Constructs the final settings

postrun()

Creates msd.txt, fit_msd.txt, and D.txt

class AMSRDFJob(previous_job=None, atom_indices=None, atom_indices_to=None, rmin=0.5, rmax=6.0, rstep=0.1, **kwargs)

__init__(previous_job=None, atom_indices=None, atom_indices_to=None, rmin=0.5, rmax=6.0, rstep=0.1, **kwargs)

previous_job: AMSJob

AMSJob with finished MD trajectory.

atom_indices: List[int]

Atom indices (starting with 1). If None, calculate RDF from all atoms.

atom_indices_to: List[int]

Atom indices (starting with 1). If None, calculate RDF to all atoms.

rmin: float

Minimum distance (angstrom)

rmax: float

Maximum distance (angstrom)

rstep: float

Bin width for the histogram (angstrom)

get_input()

Generate the input file

prerun()

Creates the final settings. Do not call or override this method.

postrun()

Creates rdf.txt. Do not call or override this method.

class AMSVACFJob(previous_job=None, max_correlation_time_fs=5000, max_freq=5000, atom_indices=None, **kwargs)

A class for calculating the velocity autocorrelation function and its power spectrum

__init__(previous_job=None, max_correlation_time_fs=5000, max_freq=5000, atom_indices=None, **kwargs)

previous_job: AMSJob

An AMSJob with an MD trajectory. Note that the trajectory should have been equilibrated before it starts.

max_correlation_time_fs: float

Maximum correlation time in femtoseconds

max_freq: float

The maximum frequency for the power spectrum in cm^-1

atom_indices: List[int]

Atom indices (starting with 1). If None, use all atoms.

get_input()

Generate the input file

prerun()

Creates final settings

postrun()

Creates vacf.txt and power_spectrum.txt

class AMSViscosityFromBinLogJob(previous_job=None, **kwargs)

A convenient class wrapping around the trajectory analysis ViscosityFromBinLog tool. Only runs with default input options (max correlation time 10% of the total trajectory).

__init__(previous_job=None, **kwargs)

previous_job: AMSJob

An AMSJob with an MD trajectory. Note that the trajectory should have been equilibrated before it starts. It must have been run with the BinLog%PressureTensor option set.

kwargs: dict

Other options to AMSAnalysisJob

get_input()

Generate the input file

prerun()

Constructs the final settings

postrun()

Creates viscosity_integral, fit_viscosity_integral, and viscosity.txt

ADF Fragment

Run fragment-based ADF analysis as a dedicated multi-job workflow.

This recipe orchestrates two fragment calculations and one full-system ADF calculation and exposes energy-decomposition and related properties through a dedicated results class.

class ADFFragmentJob(fragment1=None, fragment2=None, fragment1_opt=None, fragment2_opt=None, full_settings=None, frag1_settings=None, frag2_settings=None, **kwargs)

Subclass of MultiJob for ADF fragment calculations.

_result_type

alias of ADFFragmentResults

prerun()

Prepare the fragments and the full calculation.

classmethod load_external(path, jobname=None)

Load the results of the ADFFragmentJob job from an external path.

Parameters:

• path (str) – The path to the job. It should at least have the subfolders ‘frag1’, ‘frag2’ and ‘full’.

• jobname (str, optional) – The name of the job. Defaults to None.

Returns:

The job with the loaded results.

Return type:

ADFFragmentJob

class ADFFragmentResults(job)

Parameters:

job (Job) –

check()

Check if the calculation finished successfully.

Overwriting the method of MultiJob because it only checks if the job finished, not how it finished.

get_properties()

Redirect to AMSResults of the full calculation.

get_main_molecule()

Redirect to AMSResults of the full calculation.

get_input_molecule()

Redirect to AMSResults of the full calculation.

get_energy(unit='au')

Redirect to AMSResults of the full calculation.

get_dipole_vector(unit='au')

Redirect to AMSResults of the full calculation.

get_energy_decomposition(unit='au')

Get the energy decomposition of the fragment calculation.

Parameters:

unit (str, optional) – The unit of the energy. Defaults to ‘au’.

Returns:

The energy decomposition.

Return type:

Dict[str, float]

get_nocv_eigenvalues()

Get the NOCV eigenvalues of the full calculation.

Return type:

List[float] | Tuple[List[float], List[float]]

check_nocv_eigenvalues()

Basic NOCV check.

The eigenvalue #i should be equal to -eigenvalue #-i.

Returns:

True if the check passes, False otherwise.

Return type:

bool

get_nocv_orbital_interaction(unit='kcal/mol')

Get the NOCV orbital interactions of the full calculation.

Return type:

List[float] | Tuple[List[float]]

BAND Fragment

Run BAND energy decomposition workflows for periodic systems with optional NOCV analysis.

This recipe extends the fragment approach to periodic BAND systems and supports NOCV workflows via NOCVBandFragmentJob.

class BANDFragmentJob(fragment1=None, fragment2=None, fragment1_opt=None, fragment2_opt=None, full_settings=None, frag1_settings=None, frag2_settings=None, **kwargs)

_result_type

alias of BANDFragmentResults

prerun()

Creates the fragment jobs.

Return type:

None

new_children()

After the first round, add the full job to the children list.

Return type:

None | List[AMSJob]

classmethod load_external(path, jobname=None)

Load the results of the BANDFragmentJob job from an external path.

Parameters:

• path (str) – The path to the job. It should at least have the subfolders ‘frag1’, ‘frag2’ and ‘full’.

• jobname (str, optional) – The name of the job. Defaults to None.

Returns:

The job with the loaded results.

Return type:

BANDFragmentJob

class BANDFragmentResults(job)

Subclass of ADFFragmentResults for BAND calculations.

Parameters:

job (Job) –

get_energy_decomposition(unit='au')

Get the energy decomposition of the fragment calculation.

Parameters:

unit (str, optional) – The unit of the energy. Defaults to ‘au’.

Returns:

The energy decomposition.

Return type:

Dict[str, float]

class NOCVBandFragmentJob(nocv_settings=None, **kwargs)

_result_type

alias of BANDFragmentResults

new_children()

After the first round, add the full job to the children list. After the second round, add the NOCV job to the children list.

Return type:

None | List[AMSJob]

classmethod load_external(path, jobname=None)

Load the results of the BANDFragmentJob job from an external path.

Parameters:

• path (str) – The path to the job. It should at least have the subfolders ‘frag1’, ‘frag2’, ‘full’ and ‘NOCV’.

• jobname (str, optional) – The name of the job. Defaults to None.

Returns:

The job with the loaded results.

Return type:

NOCVBandFragmentJob

Reorganization Energy

Compute Marcus reorganization energies using four coordinated AMS calculations.

The workflow evaluates energies at optimized geometries of two electronic states and combines them into the reorganization energy used in Marcus theory.

class ReorganizationEnergyJob(molecule, common_settings, settings_state_A, settings_state_B, **kwargs)

A class for calculating the reorganization energy using AMS. Given two states, A and B, the reorganization energy is defined as follows:

reorganization energy = E(state B at optimal geometry for state A) - E(state A at optimal geometry for state A) + E(state A at optimal geometry for state B) - E(state B at optimal geometry for state B)

This job will run two geometry optimizations and two single point calculations.

_result_type

alias of ReorganizationEnergyResults

class ReorganizationEnergyResults(job)

Results class for reorganization energy.

Parameters:

job (Job) –

ADFNBO

Extend ADF runs with NBO6/gennbo execution through an AMS job wrapper.

ADFNBOJob extends the regular AMS/ADF runscript to execute adfnbo and gennbo6 while ensuring required ADF input is present.

class ADFNBOJob(molecule=None, *args, **kwargs)

Parameters:

• molecule (Molecule | Dict[str, Molecule] | ChemicalSystem | Dict[str, ChemicalSystem] | None) –

• args (Any) –

• kwargs (Any) –

prerun()

Actions to take before the actual job execution.

This method is initially empty, it can be defined in subclasses or directly added to either the whole class or a single instance using Binding decorators.

pyAHFCDOS

Compute vibronic density of states from two vibronic spectra at AH-FC level.

The FCFDOS class combines absorption and emission vibronic data to build a DOS profile with configurable broadening.

class FCFDOS(absrkf, emirkf, absele=0.0, emiele=0.0)

A class for calculating the convolution of two FCF spectra

dos(lineshape='GAU', HWHM=100.0)

Calculate density of states by computing the overlap of the two FCF spectra The two spectra are broadened using the chosen lineshape and Half-Width at Half-Maximum in cm-1

convolute(spc, stick, lineshape=None, HWHM=None)

Convolute stick spectrum with the chosen width and lineshape lineshape : Can be Gaussian or Lorentzian HWHM : expressed in cm-1

trapezoid(spc)

Integrate spectrum using the trapezoid rule

ADFVibronicDOS

Practical ADF workflow that uses AH-FC vibronic spectra to build a DOS profile.

This workflow runs the vibronic calculations and then applies FCFDOS to produce and analyze the vibronic density of states.

class FCFDOS(absrkf, emirkf, absele=0.0, emiele=0.0)

A class for calculating the convolution of two FCF spectra

dos(lineshape='GAU', HWHM=100.0)

Calculate density of states by computing the overlap of the two FCF spectra The two spectra are broadened using the chosen lineshape and Half-Width at Half-Maximum in cm-1

convolute(spc, stick, lineshape=None, HWHM=None)

Convolute stick spectrum with the chosen width and lineshape lineshape : Can be Gaussian or Lorentzian HWHM : expressed in cm-1

trapezoid(spc)

Integrate spectrum using the trapezoid rule