Chemprop

Use this skill when working with Chemprop 2.2.3, a Python package and CLI for molecular property prediction with message passing neural networks. It helps future agents design Chemprop commands, validate molecular data, use trained checkpoints, build Python API workflows, handle reaction and atom/bond tasks, and troubleshoot uncertainty, conversion, and hyperparameter workflows without reopening the original source repository.

Fast Route

• For chemprop train commands, task/loss/metric choices, split handling, config files, ensembles, transfer/foundation flags, or training outputs, use training-cli.
• For chemprop predict, chemprop fingerprint, checkpoint/model-path handling, output formats, or learned representations, use prediction-fingerprints.
• For CSV/NPZ validation, SMILES/reaction columns, descriptors, atom/bond features, molecule featurizers, datasets, dataloaders, or split APIs, use data-featurization.
• For direct Python API model construction, public chemprop.data, chemprop.models, chemprop.nn, Lightning loops, save/load, metrics, and model components, use python-api-modeling.
• For reaction, multicomponent, MolAtomBond atom/bond targets, constraints, spectral tasks, and specialized molecular schemas, use specialized-molecular-tasks.
• For uncertainty estimation/calibration/evaluation, Ray Tune hpopt, conversion, transfer/foundation routing, and advanced interpretation workflows, use uncertainty-advanced.

Start Here

Chemprop exposes one console command with five subcommands:

chemprop --help
chemprop train --help
chemprop predict --help
chemprop fingerprint --help
chemprop convert --help
chemprop hpopt --help

For a minimal training command:

chemprop train --data-path data.csv --task-type regression --output-dir runs/regression_demo

For a minimal prediction command:

chemprop predict --test-path test.csv --model-paths runs/regression_demo/model_0/best.pt --output preds.csv

For a minimal fingerprint command:

chemprop fingerprint --test-path test.csv --model-paths model.pt --ffn-block-index 0 --output fps.csv

Installation And Environment Checks

Chemprop 2.2.3 requires Python >=3.11,<3.15. Core dependencies include PyTorch, Lightning, RDKit, NumPy, pandas, scikit-learn, SciPy, astartes, ConfigArgParse, rich, and descriptastorus. Optional workflows require extras:

• chemprop[hpopt] for Ray Tune hyperparameter optimization.
• chemprop[cuik_molmaker] for optional accelerated molecule featurization where supported.
• Notebook/docs/test extras only when developing or reproducing notebooks/tests.

Use the bundled environment check when an agent needs quick diagnostics:

python scripts/chemprop_environment_check.py

Read references/package-overview.md for installed-package facts, registries, CLI modes, and workflow ownership. Read references/troubleshooting.md for cross-cutting install/import/backend, CLI, and data issues. Read references/repo-provenance.md when deciding whether this skill is stale relative to a newer Chemprop checkout.

Common Decisions

User intent	First route	Key checks
Train a molecular regression/classification model	training-cli	CSV header, SMILES/target columns, task type, split design, output directory
Predict from an existing checkpoint	prediction-fingerprints	model path, matching data schema, output suffix, reaction/multicomponent flags
Debug data shape or feature files	data-featurization	CSV columns, NPZ row counts, descriptor/feature rank, component index alignment
Build Chemprop from Python	python-api-modeling	RDKit molecules, datapoints/datasets, predictor/loss compatibility, Lightning trainer
Use reaction, multicomponent, or atom/bond tasks	specialized-molecular-tasks	reaction mode, multiple SMILES columns, target lists, constraints, --reorder-atoms
Add uncertainty, hpopt, conversion, or foundation workflows	uncertainty-advanced	optional extras, compatible model task, calibration data, conversion featurizer mode

Public Runtime Boundaries

This skill is self-contained. It distills Chemprop source, docs, tests, examples, and installed-package inspection into bundled references and helper scripts. Do not require future agents to open the original Chemprop repository for normal usage. If a task asks to modify Chemprop itself, treat this skill as usage guidance and then inspect the active checkout normally.

Safety Defaults

• Use --accelerator cpu and --num-workers 0 for local smoke tests unless GPU/backends are intentionally selected.
• Prefer explicit --output-dir, --smiles-columns, --target-columns, and --task-type in generated commands.
• Start with small --epochs for data/schema smoke tests before real training.
• Validate CSV/NPZ shape issues with sub-skills/data-featurization/scripts/validate_chemprop_tabular_inputs.py before launching expensive runs.
• Do not run notebook-scale examples, hyperparameter optimization, or training-heavy native tests as quick checks unless the user asks for expensive validation.