ChemLogic

Chemlogic is a Neurosymbolic GNN framework designed for interpretable molecular property prediction. It integrates relational logic syntax with graph neural networks to encode functional groups and structural patterns as learnable rules.

Built on PyNeuraLogic.

Read the paper: TBD

Install

pip install ChemLogic

For experiment tracking with hyperparameter tuning (Optuna + MLflow):

pip install ChemLogic[experiments]

Dependencies

ChemLogic requires Python 3.11 and Java >=1.8. For visualization graphviz is required.

All dependencies are listed in pyproject.toml.

Usage

Usage examples can be found in notebooks and experiments folders.

from chemlogic.utils.Pipeline import Pipeline

# Built-in dataset
pipeline = Pipeline("mutagen", "gnn", param_size=4, layers=2)
train_loss, test_loss, auroc, _ = pipeline.train_test_cycle()

# Custom SMILES — task inferred from labels (floats → regression, {0,1} ints → classification)
pipeline = Pipeline(
    "my_assay", "gnn", param_size=8, layers=2,
    smiles_list=df["SMILES"],
    labels=df["target"],
)
train_loss, test_loss, r2, _ = pipeline.train_test_cycle(epochs=200)

# Chemical knowledge base
pipeline = Pipeline(
    "mutagen", "sgn", param_size=4, layers=2,
    chem_rules=True,  # hydroxyl, carbonyl, halogens, nitro, amines, ...
    subgraphs=True,   # cycles, paths, y-shapes, circular fingerprints, ...
)

# Atom, bond, and graph-level features
pipeline = Pipeline(
    "my_assay", "gnn", param_size=8, layers=2,
    smiles_list=df["SMILES"], labels=df["target"],
    atom_features="all",
    bond_features="all",
    graph_features={"num_atoms": df["num_atoms"], "logP": df["logP"]},
)

# Multi-class — integers 0..N-1 are ambiguous, pass task= explicitly
pipeline = Pipeline(
    "my_assay", "gnn", param_size=8, layers=2,
    smiles_list=df["SMILES"], labels=df["activity_class"],
    task="multi_class", num_outputs=3,
)

# Architecture modes
from chemlogic.utils.Pipeline import ArchitectureType

pipeline = Pipeline(
    "mutagen", "rgcn", param_size=4, layers=2,
    chem_rules=(False, True, False, False, False),  # oxygen groups only
    architecture=ArchitectureType.CCD,
)
pipeline.template.draw()  # requires graphviz

# Checkpointing and inference
pipeline.save_checkpoint("checkpoints/run1")

pipeline = Pipeline.from_checkpoint("checkpoints/run1")
predictions = pipeline.inference(["CCO", "c1ccccc1", "CC(=O)O"])

How it works

A molecule is translated into logical atoms encoding atom and bond types. Background knowledge rules (functional groups, ring patterns, and substructures) are matched against these atoms to derive higher-level representations. The result is passed through message-passing GNN rules, all expressed in the same differentiable relational logic.

GNN message-passing is expressed directly as logic rules. Each node aggregates representations of connected nodes via variable substitutions over the graph.

The background knowledge can be integrated in three modes: BARE runs GNN and KB independently as a baseline; Chemical Concept Encoder (CCE) feeds KB-derived representations into the GNN input (enhances performance - something like featurization); Chemical Concept Decoder (CCD) passes GNN output through the KB (enhances explainability). After training in CCD mode, each functional group rule carries a scalar weight that directly quantifies its contribution to the prediction.

Models

Key	Model	Paper
gnn	Standard GNN with edge features	Scarselli et al., 2009
rgcn	Relational GCN (typed edges)	Schlichtkrull et al., 2017
kgnn / kgnn_local	Higher-order GNN (k-GNN)	Morris et al., 2021
ego	Ego-centric GNN	Sandfelder et al., 2021
sgn	Subgraph Network	Xuan et al., 2021
diffusion	Diffusion CNN	Atwood & Towsley, 2016
cw	CW-Network	Bodnar et al., 2022

Datasets

Name	Source	Size	Task
mutagen	TUD	183	Mutagenicity
ptc / ptc_fr / ptc_mm / ptc_fm	TUD	336–351	Toxicity
dhfr	TUD	393	DHFR inhibition
er	TUD	446	Estrogen receptor binding
blood_brain_barrier	TDC	2030	BBB penetration
skin_reaction	TDC	404	Skin sensitization
oral_bioavailability	TDC	640	Oral bioavailability
carcinogenous	TDC	280	Carcinogenicity
pampa_permeability	TDC	2034	Membrane permeability
human_intestinal_absorption	TDC	578	Intestinal absorption
p_glycoprotein_inhibition	TDC	1218	P-gp inhibition
cyp2c9_substrate / cyp2d6_substrate / cyp3a4_substrate	TDC	667–670	CYP substrates
anti_sarscov2_activity	TDC	1484	SARS-CoV-2 activity

Any SMILES list or DataFrame works as a custom dataset.

Results

Performance across datasets and architecture modes (BARE / CCE / CCD):

Project structure

• datasets — datasets encoded in relational format; includes TUD and TDC datasets and a custom SMILES dataset converter
• models — GNN architectures
• knowledge_base — functional groups and subgraph patterns

Documentation

• SPEC.md — API reference and configuration details
• DESIGN.md — architecture and design rationale
• REQUIREMENTS.md — functional and non-functional requirements

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines on how to get started.

License

This project is licensed under the MIT License.