Local inference

Documentation to run models on-premises

The Ersilia Model Hub is conveniently offered as a python package through PyPi and CondaForge, and each model is individually packaged as a Docker container.

Installation in Linux/MacOS

Ersilia is only maintained for Linux and Mac Operating Systems. If you work in Windows please use a Windows Subsystem Linux.

Prerequisites

• Python: we maintain Ersilia for Python 3.8 and above. Please make sure you have a compatible Python version installed on your computer. Visit the official Python site to learn more.

• Conda: ensure either Anaconda or Miniconda are available in your system. This is the command to install it in Ubuntu (the command may be different if you do not use Ubuntu):

mkdir -p ~/miniconda3
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda3/miniconda.sh
bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3
rm -rf ~/miniconda3/miniconda.sh
~/miniconda3/bin/conda init bash
~/miniconda3/bin/conda init zsh

• Docker: Docker containers are an excellent way to share applications and simplify the management of system requirements and configurations. Please install Docker to ensure that all our AI/ML assets will work smoothly in your local device.

Install from PyPi

# install ersilia from PyPi in an independent conda environment
conda create -n ersilia python=3.12
conda activate ersilia
pip install ersilia

Install from CondaForge

# install ersilia from CondaForge in an independent conda environment
conda create -n ersilia python=3.12
conda activate ersilia
conda install -c conda-forge ersilia

Once the Ersilia Model Hub is installed, test that it works by running the --help command:

ersilia --help

Model Usage

You can explore the available models through our website or by running the following command in the CLI:

# display ready to use models with its eos identifier and title
ersilia catalog --hub --more

Each model is identified by:

• EOS-ID: eos[1-9][a-z0-9]{3}

• Slug: 1-3 word reference for the model

• Title: brief description of the model

Additionally, each model is assiciated a "Task" and "Output" labels (e.g. Regression and Score, respectively) as well as "Input" and "Output" shapes (e.g. Single and Single, respectively).

Throughout this documentation, we will use the model eos2r5a (retrosynthetic-accessibility) as an example. This model has been incorporated from the paper Retrosynthetic accessibility score (RAscore) – rapid machine learned synthesizability classification from AI driven retrosynthetic planning by Thakkar et al, 2021. The RA score is particularly useful to pre-screen large libraries of compounds, for example those produced by generative models. RA scores lie in the [0,1] range; higher values indicate greater confidence that a compound is synthetically accessible.

To use a model, there are a few basic commands:

ersilia fetch eos2r5a
ersilia serve eos2r5a
ersilia run -i input.csv -o output.csv
ersilia close

The fetch command will download the model from DockerHub. Please make sure to have Docker active in your system before fetching a model. The serve command will bring the model alive anytime you want to use it. With the run command, you can make predictions by specifying the input and output files. Finally, close the model.

If you serve a model that is not available locally, Ersilia will try to fetch it automatically, from DockerHub first and then defaulting to S3 if Docker is not active. Alternatively, models can be fetched from Github as well.

Input and output

The Ersilia Model Hub takes chemical structures as input, which should be specified as SMILES strings. To obtain the SMILES string of your compounds, you can use resources like PubChem.

The SMILES can be passed directly to the CLI:

# Halicin
ersilia run -i "C1=C(SC(=N1)SC2=NN=C(S2)N)[N+](=O)[O-]"

You can make multiple predictions in batch mode. This is typically much faster than running predictions one by one in a loop:

# Halicin and Ibuprofen
ersilia run -i "['C1=C(SC(=N1)SC2=NN=C(S2)N)[N+](=O)[O-]','CC(C)CC1=CC=C(C=C1)C(C)C(=O)O']"

The easiest, though, is to provide an input file instead. A simple .csv file with one column is sufficient.

input.csv

C1=C(SC(=N1)SC2=NN=C(S2)N)[N+](=O)[O-]
CC(C)CC1=CC=C(C=C1)C(C)C(=O)O

# predict using an input file
ersilia run -i input.csv

By default, predictions are returned in the standard output of the terminal. We favour the widely used JSON format because it offers great flexibility and interoperability. However, many of the model APIs return an output that can be naturally expressed in tabular format, for example, in a CSV file. If this is what you want, simply specify an output file with the .csv extension.

# save output in a CSV file
ersilia run -i input.csv -o output.csv

Other interesting commands

You can also get more information through the model card:

# display model card using ersilia identifier
ersilia catalog --card eos2r5a

Delete model

If you are sure you don't want to use a model anymore, you may want to remove it from your computer. This includes deleting all model files and specific dependencies:

# delete model
ersilia delete retrosynthetic-accessibility
# or use the eos identifier
ersilia delete eos2r5a

As a Python package

Models can be fetched from the Ersilia Model Hub, served, and run as a Python package. The main class is called ErsiliaModel:

# import main class
from ersilia import ErsiliaModel
# instantiate the model
mdl = ErsiliaModel("retrosynthetic-accessibility")

Then, you can perform the same actions as in the CLI. To serve:

# serve model
mdl.serve()

To make predictions for Halicin and Ibuprofen:

# Halicin and Ibuprofen
input = [
    "C1=C(SC(=N1)SC2=NN=C(S2)N)[N+](=O)[O-]",
    "CC(C)CC1=CC=C(C=C1)C(C)C(=O)O"
]
# predict
mdl.run(input, output='./output.csv')

To close the model:

# close model
mdl.close()

Using the with statement

A more concise way to run prediction would be to use the with clause:

# use with statement
with ErsiliaModel("retrosynthetic-accessibility") as mdl:
    mdl.run(input, output='./output.csv')