Awesome

ChemTSv2

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:

[!NOTE] ARM architecture, e.g., Apple Silicon, is not currently supported

1. python: 3.11
2. rdkit: 2023.9.1
3. tensorflow: 2.14.1
4. pyyaml
5. pandas: 2.1.3
6. joblib
7. mpi4py: 3.1.5 (for massive parallel mode)

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:

If you can use/prepare a server with MPI environment, please follow the (a) instruction; otherwise, please follow the (b) instruction.

(a) Installation on a server WITH a MPI environment

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

(b) Installation on a server WITHOUT a MPI environment

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.reward 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:

chemtsv2 -c config/setting.yaml

ChemTSv2 with massive parallel mode :airplane:

mpiexec -n 4 chemtsv2-mp --config config/setting_mp.yaml

ChemTSv2 with Docker

docker build -t chemtsv2:1.0.0 .
docker run -u $(id -u):$(id -g) \
           --rm \
           --mount type=bind,source=./,target=/app/ \
           chemtsv2:1.0.0 \
           chemtsv2 -c config/setting.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.

chemtsv2 -c config/setting.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 train_model/train_RNN.py and train_model/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 model_setting.yaml. And then, run the following command:

cd train_model/
python train_RNN.py -c 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 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.

Contact :pushpin:

• Shoichi Ishida (ishida.sho.nm@yokohama-cu.ac.jp)
• Kei Terayama (terayama@yokohama-cu.ac.jp).