pkasolver predicts microstate pKa values of small molecules using Graph Isomorphism Networks (GINs). It provides a Python API, a command-line interface, and Jupyter notebooks.
Based on the publication: Improving Small Molecule pKa Prediction Using Transfer Learning with Graph Neural Networks — Mayr et al., 2022.
Note on models: Due to the restrictive licence of Schrödinger's Epik, the transfer-learned model (pkasolver-epik) cannot be distributed. The model shipped with this package (pkasolver-lite) was trained without the Epik transfer learning step. See the publication for a discussion of the accuracy differences.
Tip: For large-scale usage, clone with
--depth 1to avoid downloading the full git history (which contains legacy large files):git clone --depth 1 https://github.com/mayrf/pkasolver
uv is the fastest way to get started:
pip install uv # or: curl -LsSf https://astral.sh/uv/install.sh | sh
uv pip install pkasolverOr install from source:
git clone --depth 1 https://github.com/mayrf/pkasolver
cd pkasolver
uv pip install -e ".[dev]"pip install pkasolverFrom source:
pip install -e ".[dev]"git clone --depth 1 https://github.com/mayrf/pkasolver
cd pkasolver
conda env create -f devtools/conda-envs/test_env.yaml
conda activate pka_prediction
pip install -e .pkasolver automatically uses a GPU if one is available. PyTorch supports both
CUDA (NVIDIA) and ROCm (AMD) through the same torch.cuda.is_available() API.
CUDA:
# Install PyTorch with CUDA 12.1 support, then install pkasolver
pip install torch --index-url https://download.pytorch.org/whl/cu121
pip install pkasolverROCm:
pip install torch --index-url https://download.pytorch.org/whl/rocm6.0
pip install pkasolverTo force CPU inference regardless of available hardware:
from pkasolver.query import QueryModel
model = QueryModel(device="cpu")A flake.nix is provided with CPU, CUDA, and ROCm development shells:
nix develop # CPU dev shell (default)
nix develop .#cuda # CUDA dev shell
nix develop .#rocm # ROCm dev shellfrom rdkit import Chem
from pkasolver.query import calculate_microstate_pka_values, draw_pka_map
mol = Chem.MolFromSmiles("CC(=O)O") # acetic acid
states = calculate_microstate_pka_values(mol)
for state in states:
print(f"pKa = {state.pka:.2f} ± {state.pka_stddev:.2f}")
# Draw annotated structure (returns PIL Image in scripts, displays in notebooks)
img = draw_pka_map(states)
img.save("pka_map.png")from rdkit import Chem
from pkasolver.query import QueryModel, calculate_microstate_pka_values
# Load model once (25-model ensemble by default)
model = QueryModel()
mol = Chem.MolFromSmiles("c1ccncc1") # pyridine
states = calculate_microstate_pka_values(mol, query_model=model)
for state in states:
print(f" pKa = {state.pka:.2f} ± {state.pka_stddev:.2f}")
print(f" Protonated: {Chem.MolToSmiles(state.protonated_mol)}")
print(f" Deprotonated: {Chem.MolToSmiles(state.deprotonated_mol)}")
print(f" Site index: {state.reaction_center_idx}")Faster inference with fewer models:
# Use 1 model for quick screening (less accurate, much faster)
model = QueryModel(num_models=1)For processing many molecules, use calculate_pka_batch which loads the model once
and handles per-molecule errors gracefully (no silent hangs):
from pkasolver.query import QueryModel, calculate_pka_batch
smiles_list = [
"CC(=O)O", # acetic acid
"c1ccncc1", # pyridine
"C1CCNCC1", # piperidine
"Cc1ccccc1", # toluene (no ionizable group)
]
model = QueryModel()
results = calculate_pka_batch(smiles_list, query_model=model)
for smi, states in zip(smiles_list, results):
if states is None:
print(f"{smi}: failed")
elif len(states) == 0:
print(f"{smi}: no ionizable groups")
else:
pkas = [f"{s.pka:.2f}" for s in states]
print(f"{smi}: pKa = {', '.join(pkas)}")From an SDF file:
from rdkit import Chem
from pkasolver.query import QueryModel, calculate_microstate_pka_values
model = QueryModel()
with open("library.sdf", "rb") as fh:
suppl = Chem.ForwardSDMolSupplier(fh, removeHs=True)
for mol in suppl:
if mol is None:
continue
states = calculate_microstate_pka_values(mol, query_model=model)
for s in states:
print(Chem.MolToSmiles(mol), s.pka)pKa map — annotated structure at pH 7 with pKa values at each ionizable site:
from pkasolver.query import draw_pka_map
img = draw_pka_map(states, size=(600, 600))
img.save("pka_map.png")
# In Jupyter: display(img)Reaction diagram — grid of protonated/deprotonated pairs with equilibrium arrows:
from pkasolver.query import draw_pka_reactions
svg = draw_pka_reactions(states, height=300, write_png_to_file="reactions.png")
# In Jupyter: display(svg)Predict from SMILES (stdout table):
pkasolver predict --smiles "CC(=O)O"Predict to CSV:
pkasolver predict --smiles "c1ccncc1" --output pyridine.csvBatch predict from SDF:
pkasolver predict --sdf my_library.sdf --output results.csvFast mode (single model):
pkasolver predict --smiles "CC(=O)O" --num-models 1Draw pKa map:
pkasolver draw --smiles "CC(=O)O" --output pka_map.pngDraw reaction pairs:
pkasolver draw --smiles "c1ccncc1" --reactions --output pyridine_reactions.pngGPU inference:
pkasolver predict --smiles "CC(=O)O" --device cudaTraining scripts, data preparation, and evaluation notebooks live in a separate repository:
github.com/wiederm/pkasolver-data
That repository contains:
- Python scripts to prepare training data (SDF → PyG dataset)
- Model training scripts with hyperparameter configuration
- Evaluation notebooks reproducing the plots from the publication
- Notes on reproducing the Epik transfer learning dataset (requires Schrödinger licence)
This project is licensed under the MIT License — see LICENSE.md for details.
Copyright (c) 2022, Fritz Mayr, Oliver Wieder, Marcus Wieder, Thierry Langer
Project based on the Computational Molecular Science Python Cookiecutter version 1.4.