Reactions Discovery in Python (PLAMS)
*************************************

An example of how to use Reactions Discovery with Python (PLAMS) can
be found in the Python Examples documentation.

The "scm.reactions_discovery.plams_job" Python module contains the
below classes.

class ReactionsDiscoveryResults(job)

   Results class for ReactionsDiscoveryJob

   get_errormsg()

      Returns the error message of this calculation if any were
      raised.

      Returns:
         String containing the error message.

      Return type:
         str

   get_md_jobs()

      Returns the AMSJobs used during the calculation.

      Returns:
         List of AMSJobs used during the calculation.

      Return type:
         List[AMSJob]

   rkfpath()

      Returns path to reactions_discovery.rkf

      Returns:
         Path to reactions_discovery.rkf

      Return type:
         str

   get_network_rd()

      Returns the reaction network represented by Reactions Discovery
      CombinedMol and CombinedReaction classes.

      Raises:
         **KFError** -- If the KF file associated with this result
         does not contain the required information.

      Returns:
         Graph representing the reaction network, a dictionairy of
         categories and lists of CombinedMol, a dictionairy of
         categories and CombinedReaction and a list of categories.

      Return type:
         Tuple[DiGraph, Dict[str, List[CombinedMol]], Dict[int,
         CombinedReaction], List[str]]

   get_network()

      Returns the reaction network represented by a DiGraph and a
      dictionairy of lists of PLAMS molecules.
         Each key in the dictionary is a category.

      Returns:
         graph of the reaction network, dictionary of categories and
         lists of Molecules, and a list of categories.

      Return type:
         Tuple[DiGraph, Dict[str, List[Molecule]], List[str]]

   get_num_md_simulations()

      Returns the number of MD simulations used during the Molecular
      Dynamics stage.

      Raises:
         **KFError** -- If the KF file associated with this result
         does not contain the right information.

      Returns:
         The number of MD simulations used during the Molecular
         Dynamics stage.

      Return type:
         int

class ReactionsDiscoveryJob(name='reactions_discovery_job', driver=None, settings=None, molecule=None, **kwargs)

   PLAMS Job class for running Reactions Discovery.

   This class inherits from the PLAMS SingleJob class. For usage, see
   the SingleJob documentation.

   If you supply a Settings object to the constructor, it will be
   converted to a PISA (Python Input System for AMS) object.

   Attributes:

   * "input": an alias for self.settings.input

   * "builder": an alias for
     self.settings.input.MolecularDynamics.BuildSystem

   __init__(name='reactions_discovery_job', driver=None, settings=None, molecule=None, **kwargs)

      Initialize the ReactionsDiscoveryJob.

      name : str
         The name of the job

      driver : scm.input_classes.drivers.ReactionsDiscovery
         PISA object describing the input to the ReactionsDiscovery
         program

      settings: scm.plams.Settings
         All settings for the job. Input settings in the PLAMS
         settings format under "settings.input" are automatically
         converted to the PISA format. You can specify
         "settings.runscript.nproc" to set the total number of cores
         to run on.

      molecule: scm.plams.Molecule or Dict[str, scm.plams.Molecule]
         Two possibilities:

         * "molecule" is of type Molecule - it should then be the
           *complete* system as a PLAMS Molecule . Cannot be combined
           with the "driver.input.MolecularDynamics.BuildSystem" or
           "settings.input.ams.MolecularDynamics.BuildSystem". It will
           be written to the main System block in the input.

         * "molecule" is a dictionary with string keys and Molecule
           values - the keys should then be given in the "driver.inpu
           t.MolecularDynamics.BuildSystem.Molecule[i].SystemID" input
           option. The molecules will then be used to build the system
           before the MD.

   classmethod from_rkf(path)

      Initialize a job from a reactions_discovery.rkf file.

      Parameters:
         **path** (*str*) -- Path to a reactions_discovery.rkf file

      Returns:
         A new ReactionsDiscoveryJob instance based on the information
         found in path.

      Return type:
         ReactionsDiscoveryJob

   classmethod from_input(text_input)

      Initialize a job from text input.

      Parameters:
         **text_input** (*str*) -- A multiline text input

      Returns:
         A ReactionsDiscoveryJob

      Return type:
         ReactionsDiscoveryJob

   static _extract_mol_from_pisa(pisa)

      Remove a molecule from a System block in the ReactionsDiscovery
      PISA object and return it as molecule(s)

   get_errormsg()

      Returns the contents of the jobname.err file if it exists. If
      the file does not exist an empty string is returned.

      Returns:
         The error message

      Return type:
         str

   get_runscript()

      Generates the runscript. Use
      "self.settings.runscript.preamble_lines = ['line1', 'line2']" or
      similarly for "self.settings.runscript.postamble_lines" to set
      custom settings.

      "self.settings.runscript.nproc" controls the total number of
      cores to run on.

   check()

      Returns True if "NORMAL TERMINATION" is given in the General
      section of reactions_discovery.rkf, AND all molecular dynamics
      jobs also have finished successfully.

   ok()

      Synonym for check()

   get_md_jobs()

      Returns: List of AMSJob

   property input

      PISA format input

   classmethod load_external(path, finalize=False)

      Load a previous ReactionsDiscovery job from disk.

      Parameters:
         * **path** (*Union**[**str**, **Path**]*) -- A reactions
           discovery results folder.

         * **finalize** (*bool**, **optional*) -- See SingleJob,
           defaults to False

      Raises:
         **FileError** -- When the path does not exist.

      Returns:
         An initialized ReactionsDiscoveryJob

      Return type:
         ReactionsDiscoveryJob

   get_input()

      Obtain the input string used to run the Reactions Discovery
      workflow script.

      Returns:
         An input string.

      Return type:
         str
