CyRxnOpt

CyRxnOpt provides a single interface to use many reaction optimization algorithms.

Numerous cutting-edge machine learning algorithms have been developed in recent years for efficiently optimizing chemical processes. While many are open-source, evaluating and applying them to chemical processes remains challenging due to varying, non-standard implementations and interfaces. CyRxnOpt has been developed as a general, Python-based interface to install, use, and switch between reaction optimization algorithms under a single software interface. By integrating optimizers with the CyRxnOpt interface, many state-of-the-art reaction optimization algorithms can be more easily used in other software and workflows.

Installation

Prerequisites

• Python 3.9 to operate with all supported optimizers. Some algorithms may function on higher Python versions as well.
• Project dependencies, as well as other project details, can be found in the pyproject.toml file's dependencies list of the [project] section, typically automatically installed with the package.
• Optional dependency groups for development-related activities like building documentation and running tests can be found in the [dependency-groups] section of pyproject.toml, installed with pip install --group <group_name>.

Installation

CyRxnOpt is a Python-based library available for installation from PyPI using pip:

pip install cyrxnopt

Or manually inside the cloned repository with:

pip install .

Further instructions can be found in the documentation.

Usage

CyRxnOpt provides the cyrxnopt command with a collection of subcommands to perform the different steps listed below. After installation, use cyrxnopt --help to learn more about behavior and options available for each command.

Installing an Optimizer

The first thing to do when using CyRxnOpt is to create an experiment directory. The experiment directory will contain the optimizer installation, optimizer configuration files, reaction data, and other auxiliary files needed over the course of an optimization. By default, an instance of the optimization algorithm will be installed in each experiment directory to provide a snap shot of the software used at the time of the experiment. Sometimes these duplicate installations can become too large, so it is also possible to provide an alternative installation location for an algorithm, provided it was put there using the following cyrxnopt install command so it has the correct structure.

An optimizer can be installed using the cyrxnopt install command. Using a supported optimizer name, the cyrxnopt install command will install the given optimization algorithm into a subdirectory to be used by future commands. The following command installs the Nelder-Mead Simplex algorithm (NMSimplex), a classic, local optimization technique applied in early reaction optimization studies.

# Create the directory to use as an example experimental location
mkdir ./examples

# Installs the Nelder-Mead Simplex algorithm inside of the directory
# `./examples/nmsimplex_example`
cyrxnopt install nmsimplex -l ./examples/nmsimplex_example

Configuring an Optimizer

Once we have the NMSimplex algorithm installed, we can set up the directory to store data related to a reaction optimization campaign. This data starts with the specific configuration of the optimizer. At a minimum, this includes the reaction parameters that the optimizer should change, parameter boundaries, the maximum number of reactions to attempt (budget), and the optimization direction (maximize or minimize).

To create a default configuration file, use the cyrxnopt config-init command. This will create a default config.json file at the given experiment directory, in this example, ./examples/nmsimplex_example.

cyrxnopt config-init nmsimplex -l ./examples/nmsimplex_example

Let's say we make a copy of config.json at ./examples/nmsimplex_example/my_config.json and change some options in the file:

{
    "continuous_feature_names": [
        "f1", "f2"
    ],
    "continuous_feature_bounds": [
        [0, 10], [10, 80]
    ],
    "continuous_feature_resolutions": [
        1, 5
    ],
    "budget": 100,
    "direction": "min",
    "param_init": [2, 30],
    "xatol": 1e-08,
    "display": false,
    "server": false
}

We then use the cyrxnopt config command to configure NMSimplex for our experiment based on the options in the modified my_config.json file.

# If not already there
cd ./examples/nmsimplex_example

cyrxnopt config nmsimplex -c my_config.json

The behavior of cyrxnopt config will vary per optimizer being used. Some optimizers require additional files that are created here, but for NMSimplex the formatting is simply checked to make sure the settings can be properly read during usage.

Training an Optimizer

Once the optimizer is configured, if training is needed, the cyrxnopt train command can be run for interactive training. A default of 20 training steps are used, which can be changed with the -t flag. This is not needed for the NMSimplex algorithm, resulting in a no-op if cyrxnopt train is called.

# If not already there
cd ./examples/nmsimplex_example

# Begin training loop
# Implicitly uses the 'config.json' created from 'cyrxnopt config' command above
cyrxnopt train nmsimplex -t 20

Optimizing a Function

Once trained, the interactive optimization loop can be run with cyrxnopt predict.

# If not already there
cd ./examples/nmsimplex_example

# Begin optimization loop
# Implicitly uses the 'config.json' created from 'cyrxnopt config' command above
cyrxnopt predict nmsimplex

API Usage

For API usage, see API Reference.

Making Changes & Contributing

This project enforces formatting and style using pre-commit and uses tox for project automation. Please make sure to install these before making any changes.

# Clone the repo
git clone https://github.com/RxnRover/CyRxnOpt cyrxnopt

# Install dev prerequisites
cd cyrxnopt
pip install pre-commit tox

# Install pre-commit hooks
pre-commit install

A list of useful commands are provided via tox (run with tox r -e <command>), and can be listed at any time using tox l in a terminal.

Paper

Comprehensive comparisons of optimization algorithms are crucial for researchers to make informed decisions about which algorithm will perform best for their process, but there is little information comparing how each algorithm performs on differing chemical processes. To demonstrate the use and flexibility of CyRxnOpt, it was used to access four optimization algorithms and benchmark their performance on standard optimization functions and reaction models built from experimental datasets, providing a benchmarking framework which we plan to expand to more optimization algorithms.

ChemRxiv Preprint: https://doi.org/10.26434/chemrxiv.15001645/v1

Please cite preprint as: Zachery Crandall, Dulitha P. Kulathunga, Lun An, et al. CyRxnOpt: Generalized Interface for Benchmarking Reaction Optimization Algorithms. ChemRxiv. 06 April 2026. DOI: https://doi.org/10.26434/chemrxiv.15001645/v1

Note

This project has been set up using PyScaffold 4.3.1. For details and usage information on PyScaffold see pyscaffold.