VizChemoton

VizChemoton enables the visualization and interaction of chemical reaction network results generated by Chemoton. More specifically, it provides:

1️⃣ Standalone HTML for visualizing and interacting with reaction networks (see example)
2️⃣ Interoperable reaction data in CSV (reactions) and JSON (compounds) formats for downstream machine learning applications
3️⃣ Compound search via SMILES and InChIKeys within the reaction network and public databases (PubChem, ChEMBL, and ChEBI)
4️⃣ Interface reaction data with cheminformatics applications

The image above shows which type of visualization (network on the left, structure on the right) the HTML file permits

Table of Contents

1. Introduction to Chemoton
2. Introduction to amk-tools
3. VizChemoton Code Overview
4. Dependencies
5. Installation
6. Usage of the HTML Files
7. References
8. Support and Contact

---

1. Context: introduction to Chemoton

The research group of Markus Reiher at ETH Zürich has developed the software enviroment SCINE ("Software for Chemical Interaction Networks")[1] which pursues the performance of quantum chemical calculations with special focus on algorithmic stability, automation, interactivity, efficiency and error control. In this context, Chemoton is the SCINE module in charge of constructing CRNs in a fully automated fashion based on first-principles.[2]

The reaction network results from Chemoton can be visualized with the graphical user interface developed in the same SCINE framework, named Heron.[3] This GUI has many functionalities beyond visualization, such as monitoring and steering the exploration, as well as creating json files to make the whole process reproducible.

Here we offer a complementary visualization tool aimed at providing an interactive visualization of the CRN without any previous dependencies. We highlight, however, that VizChemoton is just meant for creating a light-weight and convenient visualization format of the CRN, thus making it easily accessible to the scientific community.

2. Context: introduction to amk-tools

The research group of Carles Bo at ICIQ (Tarragona, Spain) developed a library, named amk-tools allowing the reading, processing and visualizing the reaction networks[4] constructed by AutoMeKin, an automated reaction discovery program developed by Emilio Martinez Nuñez (Galicia, Spain).[5]

Here we tailor the application of amk-tools to the visualization of CRNs constructed with Chemoton.

3. VizChemoton Code Overview

In the following diagram we describe the modules that VizChemoton uses to generate the .html file. The full workflow starts from querying the MongoDB (1) using the SCINE modules (2) to obtain the reactions and compounds of the reaction network. Because querying the MongoDB might be a time-consuming step, we have enabled the option to export the network as a .json file, so that for future runs, the network can be directly imported (a). The reaction and compounds data are also stored in a .csv and .json files respectively (b). This allows importing the reaction and compound data without querying MongoDB nor the SCINE dependencies. To generate the visualization of the network, the amk-tools is called (4) which ultimately writes the .html file (5).

Notice that the chemical data present in the network.html can also be converted into pairs of input-ouput files using json2orca (c) so that the data can be uploaded in the FAIR repository ioChem-BD (d). In section 5 we show how network.html and data in ioChem-BD complement each other.

4. Dependencies

Dependencies are detailed in the requirements.txt file. We recommend adjusting the SCINE versions according to the versions that were used to run the reaction network exploration.

5. Installation

Here we provide a short installation guide for VizChemoton based on using a Python environment.

# Initialize a Python environment
# Tested with Python 3.8 and 3.10
python3 -m venv env4vizchemoton
cd env4vizchemoton
source bin/activate

# Install Chemoton
git clone https://github.com/qcscine/chemoton.git
cd chemoton
# depending on the Chemoton version that was used for the exploration
git checkout 3.1.0 
python3 -m pip install -r requirements.txt
python3 -m pip install .
cd ..

# Install VizChemoton
git clone https://github.com/petrusen/vizchemoton.git
cd vizchemoton
python3 -m pip install -r ./requirements.txt
python3 -m pip install .

6. Example

Before running the code, the user should edit the config.yaml to tailor the application of VizChemoton to the given specific system. Even so, the default config.yaml is set to that the user can run VizChemoton just out-of-the-box with the data in the ./vizchemoton/resources folder.

# Activate Python environment 
cd <path-to-enviroment>/env4vizchemoton
source ./bin/activate

# Edit the config file
vi config.yaml

# Run the code of this repository (at the /vizchemoton level) to obtain the JSON, CSV and HTML.
python3 -m vizchemoton

# Alternatively, it is also possible to pass the YAML as an argument
python3 -m vizchemoton config_test_crn.yaml

The code renders a .html file, with the path and name specified by the user, which contains the compounds and reactions of the reaction network.

6.1 Search for a compound

Double-clicking the .html file will open a dashboard similar to the diagram below, where we have depicted the description of the main built-in functionalities. The current version supports searches by SMILES, even though we recommend doing the search with InChIKeys to circumvent SMILES' noncanonical nature.

6.2 Search in ioChem-BD FAIR repository

If the reader wishes to find the quantum chemistry input file for a specific molecule in the network, we recommend using the Find module of

ioChem-BD. The diagram below shows the three steps: (1) select search by structure, (2) draw the chemical structure that you are interested in, (3) if Results is greater than 0 press the button go. This will redirect you to the Browse module, where all the calculations involving the drawn structure will be listed. Next, you should search on the right-side of the screen the box named Author, and click the name Enric Petrus. The Title name of the searched structure will be the same as the one in the network html file.

How to Cite

When publishing results generated with VizChemoton, we kindly request you to cite the original article and the corresponding release in Zenodo:

E. Petrus, D. Garay-Ruiz, T. Weymuth, M. Reiher, T. Hofstetter. ChemRxiv, 2026 DOI

References

1. T. Weymuth, J. P. Unsleber, P. L. Türtscher, M. Steiner, J.-G. Sobez, C. H. Müller, M. Mörchen, V. Klasovita, S. A. Grimmel, M. Eckhoff, K.-S. Csizi, F. Bosia, M. Bensberg, M. Reiher, J. Chem. Phys., 2024, 160, 222501.
2. a) Gregor N. Simm, Markus Reiher. J. Chem. Theory Comput. 2017, 13, 12, 6108-6119. b) Jan P. Unsleber, Stephanie A. Grimmel, Markus Reiher. J. Chem. Theory Comput. 2022, 18, 9, 5393-5409
3. C. H. Müller, M. Steiner, J. P. Unsleber, T. Weymuth, M. Bensberg, K.-S. Csizi, M. Mörchen, P. L. Türtscher, M. Reiher, J. Phys. Chem. A, 2024, 128, 9028−9044. (DOI: 10.48550/arXiv.2406.09541)
4. Diego Garay-Ruiz, Moises Alvarez-Moreno, Carles Bo, Emilio Martinez-Nunez. ACS Phys. Chem Au 2022, 2, 3, 225-236.
5. E. Martínez-Núñez, G. L. Barnes, D. R. Glowacki, S. Kopec, D. Peláez, A. Rodríguez, R. Rodríguez-Fernández, R. J. Shannon, J. J. P. Stewart, P. G. Tahoces, S. A. Vazquez, J. Comput. Chem. 2021, 42(28), 2036.

Support and Contact

Should you find any problem or bug, please write a short message to enric.petrus@eawag.ch