API Reference
This documentation provides users with the public APIs that they can use with AutoREACTER. AutoREACTER has 10 public user-facing API functions. From them, users only have to run 5 required functions, while the remaining 5 functions are optional.
Users must run the required functions in order. Some optional functions also have to be run only after a certain required function. The optional functions are there for users to visualize their molecules, functional groups, reactions, reaction templates, and non-reactants inside their system.
AutoREACTER accepts an input file path, initializes the session, and exposes methods to step through — or run end-to-end — the reaction-detection and simulation-preparation workflow. Intermediate images such as molecules, functional groups, reactions, reaction templates, and non-reactants are saved automatically to the session image directory.
Import AutoREACTER
import AutoREACTER as arx
Users can import AutoREACTER as arx so the code is shorter and the long module name is eliminated.
Required Functions in Order
Important: Users must run these functions in the following order.
1. Run AutoREACTER
arx.run("input.json")
This function does the initial processing of AutoREACTER. It clears out the necessary directories, initializes the session, calculates what functional groups are available, and detects what reactions are available based on the functional groups that are available.
This step also initializes the AutoREACTER environment and prepares the working directory for the current run.
After this function, users can optionally visualize molecules, functional groups, and detected reactions.
Optional functions available after arx.run(...):
arx.show_molecules()
arx.show_functional_groups()
arx.show_reactions()
2. Select Reactions
arx.select_reactions()
This function lets users select which reactions they want to process with AutoREACTER.
Users must run this function even if only one reaction is detected. If only one reaction is available, AutoREACTER will automatically proceed with that reaction after this function is called. If more than one reaction is found, the user is prompted to select which reactions to proceed with.
This function marks the select_reactions waterfall stage as complete.
After this function, users can optionally visualize the detected non-reactants.
Optional function available after arx.select_reactions():
arx.show_non_reactants()
3. Select Non-Reactants
arx.select_non_reactants()
This function lets users select which non-reactant molecules they want to include in the AutoREACTER workflow.
Users must run this function even if no non-reactants are detected. If non-reactants are found, the user is prompted to select which non-reactants they want to proceed with. If no non-reactants are found, this step is skipped automatically after the function is called.
A molecule can be treated as a non-reactant if:
The molecule does not qualify as a monomer.
The molecule qualifies as a monomer, but the user chooses not to include it in any selected reaction.
4. Prepare Reactions
arx.prepare_reactions()
This function prepares reaction templates from the selected reactions for downstream processing.
This function marks the reaction-template preparation stage as complete.
After this function, users can optionally visualize reaction templates.
Optional function available after arx.prepare_reactions():
arx.show_reaction_templates()
5. Process
arx.process()
This function executes the back-half of the AutoREACTER pipeline in one shot.
According to the docstring, this method runs reaction template preparation, 3D geometry setup, force-field generation through the LUNAR API, REACTER file building, and LAMMPS simulation writing.
This function should be run only after the required stages are completed:
arx.select_reactions()
arx.select_non_reactants()
arx.prepare_reactions()
If the required stages are not completed, AutoREACTER raises a RuntimeError.
Full Required Workflow
import AutoREACTER as arx
arx.run("input.json")
arx.select_reactions()
arx.select_non_reactants()
arx.prepare_reactions()
arx.process()
Optional Visualization Functions
The following functions are optional. They are provided so users can visualize molecules, functional groups, reactions, non-reactants, and reaction templates.
Show Molecules
Available after:
arx.run("input.json")
Usage:
arx.show_molecules()
This function returns a PIL/RDKit image grid of the initial molecules or monomers.
Returns:
Image
Show Functional Groups
Available after:
arx.run("input.json")
Usage:
arx.show_functional_groups()
This function returns an image grid with functional groups highlighted on each molecule.
If functional-group detection has not run yet, this function triggers functional-group detection automatically.
Returns:
Image
Show Reactions
Available after:
arx.run("input.json")
Usage:
arx.show_reactions()
This function returns an image grid showing the detected reactions.
If reaction detection has not run yet, this function triggers reaction detection automatically. Since reaction detection depends on functional-group detection, functional-group detection is also triggered if needed.
Returns:
Image
Show Non-Reactants
Available after:
arx.select_reactions()
Usage:
arx.show_non_reactants()
This function returns an image visualizing detected non-reactant species.
If non-reactant detection has not run yet, this function triggers the detection automatically. It also marks the non-reactant detection waterfall stage as complete.
Returns:
Image
Show Reaction Templates
Available after:
arx.prepare_reactions()
Usage:
arx.show_reaction_templates()
This function returns an image grid visualizing the reaction templates.
The highlight_type parameter can be used to visualize different parts of the reaction templates. Default type is "template"
arx.show_reaction_templates(highlight_type="template")
arx.show_reaction_templates(highlight_type="edge")
arx.show_reaction_templates(highlight_type="delete")
arx.show_reaction_templates(highlight_type="initiators")
Reaction Template Visualization Options
Visualize reaction templates with different highlighting options by setting the highlight_type parameter to one of the following values:
template: Highlights all structural changes in the reaction templates.edge: Highlights edge atoms of the templates.delete: Highlights removed components, if applicable.initiators: Highlights reaction initiator atoms.
The default value is:
highlight_type="template"
Returns:
Image
Summary of Public APIs
API |
Required or Optional |
When to Run |
|---|---|---|
|
Required |
First |
|
Required |
After |
|
Required |
After |
|
Required |
After |
|
Required |
Final required step |
|
Optional |
After |
|
Optional |
After |
|
Optional |
After |
|
Optional |
After |
|
Optional |
After |