Conformers

AMS’s Conformers is a flexible tool for conformers generation.

This page documents the PLAMS interface to Conformers. For a description of the capabilities and options of the Conformers tool, see the documentation in the AMS user manual.

See also

The conformers generation example in the Examples section of the PLAMS manual.

ConformersJob

Technical

Import these classes from scm.conformers, not scm.plams !

from scm.conformers import ConformersJob, ConformersResults

The ConformersJob class, which derives from SingleJob class, can be used to set up and run a Conformers calculation.

The input options for the Conformers tool (described here) can be specified in the input.ams branch of a setting object. See the Conformers Generation example.

class ConformersJob(name='conformers', molecule=None, **kwargs)

_result_type

alias of scm.conformers.plams.interface.ConformersResults

__init__(name='conformers', molecule=None, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

check()

Check if the calculation was successful.

This method can be overridden in concrete subclasses of SingleJob. It should return a boolean value. The definition here serves as a default, to prevent crashing if a subclass does not define its own check(). It always returns True.

Warning

This method is meant for internal usage and should not be explicitly called in your script (but it can be overridden in subclasses). Manually calling check() is not thread safe. For a thread safe function to evaluate the state of your job please use ok()

get_input()

Generate the input file. Abstract method.

This method should return a single string with the full content of the input file. It should process information stored in the input branch of job settings and in the molecule attribute.

get_runscript()

Generate the runscript. Abstract method.

This method should return a single string with the runscript contents. It can process information stored in runscript branch of job settings. In general the full runscript has the following form:

[first line defined by job.settings.runscript.shebang]

[contents of job.settings.runscript.pre, when present]

[value returned by get_runscript()]

[contents of job.settings.runscript.post, when present]

When overridden, this method should pay attention to .runscript.stdout_redirect key in job’s settings.

classmethod load_external(path, settings=None, molecule=None, finalize=False, jobname=None)

Load an external job from path.

class ConformersResults(*args, **kwargs)

A specialized Results subclass for accessing the results of ConformersJob. Conformers are sorted by energy, from lowest to highest.

__init__(*args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

rkfpath()

Absolute path to the ‘conformers.rkf’ results file

get_lowest_conformer()

Return the conformer with the lowest energy

get_conformers()

Return a list containing all conformers found. The conformers are sorted according to their energy, the first element being the lowest energy conformer.

get_relative_energies(unit='au')

Return the relative energies of the conformers i.e. the energy of the conformer minus the energy of the lowest conformer found. This list is sorted according to the energy of the conformers, the first element corresponding to the lowest energy conformer. So, by definition, the first element will have an energy of 0.

get_energies(unit='au')

Return the energies of the conformers. This list is sorted according to the energy of the conformers, the first element corresponding to the lowest energy conformer.

get_lowest_energy(unit='au')

Return the energy of the lowest-energy conformer.

get_boltzmann_distribution(temperature)

Return the Boltzmann distribution at a given temperature: exp^(E_i/kB*temperature) / (sum_j exp^(E_j/kB*temperature)), where E_i is the energy of conformer i. This list is sorted according to the energy of the conformers, the first element corresponding to the lowest energy (and highest probability) conformer. The temperature is in Kelvin.

__str__()

Return str(self).

collect()

Collect files present in the job folder.

Use parent method from Results to get a list of all files in the results folder. Then instantiate self.rkf to be a KFFile instance for the main conformers.rkf output file. Also instantiate self._conformers to be a Conformers instance built from it.

This method is called automatically during the final part of the job execution and there is no need to call it manually.

The plot_conformers() function (from scm.conformers.plams.plot import plot_conformers) lets you plot some example conformers in a Jupyter notebook:

plot_conformers(job, indices=None, temperature=298, unit='kcal/mol', lowest=True)

Function for plotting conformers in a Jupyter notebook

job: ConformersJob

Finished ConformersJob

indices: None, int or list of int

If None, will plot at most 3 conformers.

If int, will plot at most the given number of conformers.

If list of int (zero-based indices), plot those conformers.

temperature: float

Temperature for relative population (printed above the figure).

unit: str

Unit for relative energies (printed above the figure)

lowest: bool

Only used if indices is an integer. If True, plot the N lowest energy conformers. If False, plot conformers evenly distributed from the most stable to the least stable.