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 Python Examples collection.


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 "Settings" object. See the
conformers generation example.

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

   _result_type

      alias of "ConformersResults"

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

   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.

      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.

      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)

   rkfpath()

      Absolute path to the 'conformers.rkf' results file

      Return type:
         str

   get_lowest_conformer()

      Return the conformer with the lowest energy

      Return type:
         *Molecule*

   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.

      Return type:
         *List*[*Molecule*]

   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.

      Return type:
         *List*[float]

   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.

      Return type:
         *List*[float]

   get_lowest_energy(unit='au')

      Return the energy of the lowest-energy conformer.

      Return type:
         float

   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.

      Return type:
         *List*[float]

   __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, **view_kwargs)

   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.

   view_kwargs: kwargs
      Keyword arguments passed to the PLAMS "view" function.

   Parameters:
      **job** (*ConformersJob*) --
