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

Datasets

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.