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 Job 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 Job 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 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.Python_Nproc = 4 # Maximum number of parallel processes
>>> settings.RunInfo.Steps = [1, 2, 3] # The default

>>> # 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)

Create the full ACErxn Settings object from an incomplete Settings object, by adding default values. The only required entry is settings.qmengine.

  • settings – Optional PLAMS Settings object containing ACE input settings. By default self.settings is used.
run(jobrunner=None, jobmanager=None, **kwargs)

Runs the ACErxn task and returns an ACErxnResults object.

  • jobrunner – A PLAMS JobRunner object. If not provided, the PLAMS default JobRunner is used.
  • jobmanager – A PLAMS JobManager object. Generally should not be provided, as it is always safest to use the default JobManager.


This method calls the run_job method of the jobmanager, which creates a separate thread for the process. This thread will not be restricted the semaphore, so that all jobrunner.maxjobs geometry optimization subprocesses can be run simultaneously (they will be restricted by the semaphore).


Load intermediates from RKF file

  • path – Path to the RKF files of the intermediates from a previous run (plams_workdir/acerxn/acerxn.results)

Load a reaction network, with the corresponding intermediates, from RKF file.

  • path – Path to the RKF files of the intermediates from a previous run (plams_workdir/acerxn/acerxn.results)

Set the reaction network

  • network – ACErxnNetwork object

Put together a complete input file in AMS format

  • frozen_bonds – Optional list of lists of tuples of two integers. Only required if the fragments in the Reactant object have not yet been guessed. The tuples represent a bond between active atoms in a submolecule that can never be broken [[(0,1),(1,2)], [[0,1]]].
classmethod read(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

Write the results of a run to RKF