csp5 0.2.8

CSP5: pip-installable NMR predictor for 13C and 1H.

CSP5

CSP5 is a pip-installable NMR predictor package with:

• batched 13C and 1H prediction
• prediction from precomputed geometries
• shift matching utilities with dp (default), scipy, and murty (k-best)

Bundled defaults:

• 13C model: CSP5-13C (model_id: csp5-13c)
• 1H model: CSP5-1H (model_id: csp5-1h)

Install

Requires Python 3.9 or newer.

pip install CSP5

Prediction CLI

In interactive terminals, csp5 prints status lines to stderr before and after prediction. If a run is slow, it prints an additional note that first invocation can take longer while dependencies and model weights initialize, plus periodic "still working" updates during long runs. Use --no-status to silence them.

From SMILES

csp5 --smiles "CCO" --nucleus 1H
csp5 --smiles-file smiles.txt --nucleus 13C --batch-size 64

From precomputed geometries (parquet structures dataset)

Input dataset requirements:

• required columns: smiles, molblock
• optional columns: conformer_rank, conformer_id, energy, energy_method

Predict only rank-0 conformers:

csp5 \
  --structures-path /path/to/structures.parquet \
  --conformer-rank 0 \
  --nucleus 1H \
  --batch-size 64

Predict using all conformers in the dataset:

csp5 \
  --structures-path /path/to/structures.parquet \
  --use-all-conformers \
  --nucleus 13C

Prediction Python API

from csp5 import predict_smiles, predict_structures, predict_sdf

# Standard SMILES mode
res = predict_smiles(["CCO", "c1ccccc1"], nucleus="1H", batch_size=32)
print(res.predictions.head())

# Precomputed-geometry parquet mode
res2 = predict_structures(
    "/path/to/structures.parquet",
    nucleus="1H",
    conformer_rank=0,
    use_all_conformers=False,
)

# Precomputed-geometry SDF mode
res3 = predict_sdf("/path/to/embedded.sdf", nucleus="13C")

Matching CLI

csp5-match expects one shift per line in each file.

Default fast path (dp)

csp5-match \
  --predicted-file predicted.txt \
  --experimental-file experimental.txt \
  --solver dp

SciPy Hungarian option

csp5-match \
  --predicted-file predicted.txt \
  --experimental-file experimental.txt \
  --solver scipy

Murty k-best option

csp5-match \
  --predicted-file predicted.txt \
  --experimental-file experimental.txt \
  --solver murty \
  --k-best-policy clip \
  --k-best 25 \
  --temperature 0.5 \
  --mae-delta-threshold 0.2

Matching Python API

from csp5 import match_shifts

pred = [7.35, 7.30, 1.25]
exp = [7.34, 7.31, 1.20]

# DP (default)
r1 = match_shifts(pred, exp, solver="dp")

# SciPy Hungarian
r2 = match_shifts(pred, exp, solver="scipy")

# Murty k-best
r3 = match_shifts(pred, exp, solver="murty", k_best=10, k_best_policy="clip")
print(r3.assignment_entropy, r3.num_competing_assignments)

Solver Notes

• dp is the default and is intended for the standard 1D shift objective.
• scipy uses Hungarian assignment on the full padded cost matrix.
• murty is the k-best solver; use this when you need assignment ambiguity analysis.
• For murty, k_best_policy="clip" (default) returns all feasible unique assignments when k_best is larger than what exists. Use k_best_policy="strict" to fail instead.
• dp and scipy are top-1 only (k_best must be 1).

Output Notes

• Prediction failures are returned explicitly (failures) with reason tags.
• Prediction output always includes nucleus, model_id, and model_name.
• For structures-mode predictions, conformer metadata columns are propagated when available.