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 associated to a Task e.g. Regression, an Output, e.g. Score and an Output Shape e.g Single, or List.

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.

Ersilia only accepts an input file in csv format, with one column and a header. Predictions are returned in tabular format as either .csv or .h5 depending on what is specified by the user:

input.csv

smiles
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 and output 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 commands mirror the Command Line Interface for simplicity:

from ersilia.api import Model

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

mdl = Model(model="eos3b5e")
mdl.fetch()
mdl.serve()
df = mdl.run(input_list)
mdl.close()

Or, more succinctly, if the model is already fetched:

from ersilia.api import Model

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

with Model("eos3b5e") as mdl:
    df = mdl.run(input_list)