3.5.2. ACErxnJob
****************

This class is a PLAMS-style job class that can run an ACErxn
calculation and return a reaction network.

class ACErxnJob(reactant, products, known_intermediates=None, name='acerxn', **kwargs)

   Class representing the ACErxn computational task.

   List of constructor arguments :

   * "reactant"            -- Reactant object

   * "products"            -- List of lists of PLAMS "Molecule"
     objects, one list for each possible product with the same
     stoichiometry as the reactant, and each "Molecule" object for
     each product summolecule. Can also be a single list of product
     molecules.

   * "known_intermediates" -- Optional list of lists of PLAMS
     "Molecule" objects, each list representing an intermediate with
     the same stoichiometry as the reactant, and each "Molecule"
     object representing one of the intermediate submolecules.

   * "settings"            -- A PLAMS "Settings" object with ACE
     keywords

   This class derives from the PLAMS "SingleJob" class.

   The ACErxn procedure consists of three steps, that by default will
   be performed consecutively.

   1. Intermediate generation: A set of intermediates is generated by
      enumeratively breaking and forming bonds in the reactant
      molecules.

   2. Network creation: The intermediates are connected by elementary
      reactions, using filters based on the number of broken and
      formed bonds.

   3. Network minimization: The most likely mechanisms from reactant
      to product are extracted, using shortest path algorithms.

   After running ACErxn the reaction network info and the
   intermediates are stored as RKF files in a results folder. Like any
   PLAMS SingleJob ACErxn generates a working folder with the default
   name plams_workdir. After running a single ACErxn job, the results
   folder is located inside this working folder, as
   plams_workdir/acerxn/acerxn.results.

   A simple example of use, for a unimolecular reaction:

      >>> from scm.plams import Molecule, Settings
      >>> from scm.plams import init, finish
      >>> from scm.acerxn import Reactant, ACErxnJob, default_settings

      >>> reactant_filenames = ['reactant.xyz']
      >>> product_filenames = ['product.xyz']

      >>> # Some user supplied info on the reactants
      >>> molcharges = [0]
      >>> active_atoms = [[0,12,13,15]]

      >>> # Create the reactant molecules and the Reactant object
      >>> reactants = [Molecule(fn) for fn in reactant_filenames]
      >>> reactant = Reactant(reactants, active_atoms, molcharges)
      >>> reactant.guess_fragments()

      >>> # Create the product molecules
      >>> products = [Molecule(fn) for fn in product_filenames]

      >>> # Set up the ACE job
      >>> job = ACErxnJob(reactant, products)

      >>> # Now run the first step
      >>> init()
      >>> result = job.run()
      >>> finish()

   In the above examples all the default settings were used. It is
   also possible to provide them as a PLAMS "Settings" object

      >>> # Create the settings object
      >>> settings = default_settings()
      >>> settings.BasicOptions.MaxJobs = 4 # Maximum number of parallel processes
      >>> settings.RunInfo.Steps = 'All'

      >>> # QM engine settings
      >>> engine_settings = Settings()
      >>> engine_settings.Mopac.Model = 'PM6'
      >>> settings.qmengine = engine_settings

      >>> # Set up the ACE job
      >>> job = ACErxnJob(reactant, products, settings=settings)

   _result_type

      alias of "ACErxnResults"

   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".

   get_input()

      Put together a complete input file in AMS format

   classmethod from_inputfile(infile, reactant=None)

      Read an ACErxn job from and AMS style input file

      * ''infile''   -- Can be either a file object, or a file name

      * "reactant" -- A complete Reactant object (including fragment
        data)

   classmethod load_external(path, settings=None, finalize=False, fmt='acerxn')

      Load an external job from *path*.

      In this context an "external job" is an execution of some
      external binary that was not managed by PLAMS, and hence does
      not have a ".dill" file. Here it is expected to be an RKF file
      created by ACErxnJob

      * "path" -- Can be either the folder containsing all the acerxn
        result RKF files, or the path to the main ams.rkf file

      * "fmt"  -- The format of the file to be found. Can currently
        only be 'acerxn', which means that RKF files created by
        ACErxnJob are expected
