ChemTSv2

[!IMPORTANT] Major Version Upgrade
ChemTSv2 has been updated to v2.0.0, introducing breaking changes to the import paths of key classes. If you're upgrading from v1.x.x, please update and review your custom reward, filter, policy files accordingly:

# v1.x.x
from chemtsv2.reward import Reward
from filter.filter import Filter
from policy.policy import Policy

# v2.x.x
from chemtsv2.abc import Reward, Filter, Policy

ChemTSv2¹ is a refined and extended version of ChemTS² and MPChemTS³. The original implementations are available at https://github.com/tsudalab/ChemTS and https://github.com/yoshizoe/mp-chemts, respectively.

ChemTSv2 provides:

• easy-to-run interface by using only a configuration file
• easy-to-define framework for users' any reward function, molecular filter, and tree policy
• various usage examples in the GitHub repository

How to setup :pushpin:

Requirements :memo:

ChemTSv2 with single process mode :red_car:

cd YOUR_WORKSPACE
python3.11 -m venv .venv
source .venv/bin/activate
pip install --upgrade chemtsv2

ChemTSv2 with massive parallel mode :airplane:

cd YOUR_WORKSPACE
python3.11 -m venv .venv
source .venv/bin/activate
pip install --upgrade chemtsv2[mp]

conda create -n mpchem python=3.11 -c conda-forge
# swith to the `mpchem` environment
conda install -c conda-forge openmpi cxx-compiler mpi mpi4py=3.1.5
pip install --upgrade chemtsv2

How to run ChemTSv2 :pushpin:

1. Clone this repository and move into it

git clone git@github.com:molecule-generator-collection/ChemTSv2.git
cd ChemTSv2

2. Prepare a reward file

Please refer to reward/README.md. An example of reward definition for LogP maximization task is as follows.

from rdkit.Chem import Descriptors
import numpy as np
from chemtsv2.abc import Reward

class LogP_reward(Reward):
    def get_objective_functions(conf):
        def LogP(mol):
            return Descriptors.MolLogP(mol)
        return [LogP]
    
    def calc_reward_from_objective_values(objective_values, conf):
        logp = objective_values[0]
        return np.tanh(logp/10)

3. Prepare a config file

The explanation of options are described in the Support option/function section. The prepared reward file needs to be specified in reward_setting. For details, please refer to a sample file (config/setting.yaml). If you want to pass any value to calc_reward_from_objective_values (e.g., weights for each value), add it in the config file.

4. Generate molecules

ChemTSv2 with single process mode :red_car:

# Run via CLI
chemtsv2 -c config/setting.yaml

# Run directly
python chemtsv2/cli/run.py -c config/setting.yaml 

ChemTSv2 with massive parallel mode :airplane:

# Run via CLI
mpiexec -n 4 chemtsv2-mp --config config/setting_mp.yaml

# Run directly
mpiexec -n 4 python -m mpi4py chemtsv2/cli/run_mp.py -c config/setting_mp.yaml

Example usage :pushpin:

Support option/function :pushpin:

• :white_check_mark: indicates that the option/function is supported.
• :heavy_check_mark: indicates that the option/function is partially supported.
• :beginner: indicates that the option/function is beta version.
• :white_large_square: indicates that the option/function is NOT supported.

Filter functions are described in filter/README.md.

Advanced usage :pushpin:

Extend user-specified SMILES

You can extend the SMILES string you input. In this case, you need to put the atom you want to extend at the end of the string and run ChemTS with --input_smiles argument as follows.

# Single process mode
chemtsv2 -c config/setting.yaml --input_smiles 'C1=C(C)N=CC(N)=C1C'

# Massive parallel mode
mpiexec -n 4 chemtsv2-mp -c config/setting_mp.yaml --input_smiles 'C1=C(C)N=CC(N)=C1C'

Specify the last atom of SMILES string using OpenBabel

OpenBabel can be used to rearrange a SMILES string so that the specified atom comes last. For example, if you want to rearrange Br in NC1=CC(Br)=CC=C1 to the last position, run the following command:

# obabel -:"<SMILES>" -osmi -xl <atom no.>
# Atom numbers correspond to the order of atoms in an input SMILES string.
# In this example, `Br` appears fifth, so we specify `5` as a <atom no.>.
obabel -:"NC1=CC(Br)=CC=C1" -osmi -xl 5
# output: Nc1cc(ccc1)Br

Please refer to the official documentation for detailed usage.

Train RNN models using your own dataset

If you want to use the RNN models trained on your own datasets, use chemtsv2-train-rnn command and config/rnn_model_setting.yaml to train the models. You need to prepare a dataset that only contains SMILES string and modify the path in dataset key in rnn_model_setting.yaml. And then, run the following command:

chemtsv2-train-rnn -c config/rnn_model_setting.yaml

Please note that the current version of ChemTSv2 does not support the change for RNN model structures, and users can only change the parameters described in rnn_model_setting.yaml.

Once you train the RNN model, specify the path to the checkpoint and token files in model_setting and token keys in ChemTSv2 config files to run ChemTSv2 with your own RNN model.

GPU acceleration

If you want to use GPU, run ChemTS with --gpu GPU_ID argument as follows.

chemtsv2 -c config/setting.yaml --gpu 0

If you want to use GPU only for reward calculations, run ChemTSv2 with --gpu and --use_gpu_only_reward arguments as follows.

chemtsv2 -c config/setting_gnina_singularity.yaml --gpu 0 --use_gpu_only_reward

How to cite

@article{Ishida2023,
  doi = {10.1002/wcms.1680},
  url = {https://doi.org/10.1002/wcms.1680},
  year = {2023},
  month = jul,
  publisher = {Wiley},
  author = {Shoichi Ishida and Tanuj Aasawat and Masato Sumita and Michio Katouda and Tatsuya Yoshizawa and Kazuki Yoshizoe and Koji Tsuda and Kei Terayama},
  title = {ChemTSv2: Functional molecular design using de novo molecule generator},
  journal = {{WIREs} Computational Molecular Science}
}

License :pushpin:

This package is distributed under the MIT License.