sci-form

High-performance 3D molecular conformer generation using ETKDG distance geometry, written in Rust.

Generates chemically valid 3D coordinates from SMILES strings, matching RDKit's ETKDGv2 quality while offering native bindings for Rust, Python, TypeScript/JavaScript (WASM), and a cross-platform CLI.

Features

• ETKDG Distance Geometry — Cambridge Structural Database torsion preferences (837 SMARTS patterns)
• High Accuracy — 0.00% heavy-atom RMSD > 0.5 Å vs RDKit on GDB-20 (2000 molecules, ensemble comparison)
• Fast — 60+ molecules/second in Rust, parallel batch processing via rayon
• Multi-platform — Rust lib, Python (PyO3), TypeScript/JS (WASM), CLI (Linux/macOS/Windows)
• Zero runtime dependencies — pure Rust, no C++ toolchain needed
• SMILES + SMARTS — full SMILES parser and SMARTS pattern matching engine

Installation

Rust

[dependencies]
sci-form = "0.1"

let result = sci_form::embed("CCO", 42);
println!("Atoms: {}, Coords: {:?}", result.num_atoms, result.coords);

→ Rust API docs · Full guide

Python

The Python package is published as sciforma on PyPI. The import name is sci_form.

pip install sciforma

import sci_form

result = sci_form.embed("CCO")            # seed=42 is default
print(f"Atoms: {result.num_atoms}, Time: {result.time_ms:.1f}ms")
positions = result.get_positions()        # list of (x, y, z) tuples

# Batch
results = sci_form.embed_batch(["CCO", "c1ccccc1", "CC(=O)O"])
for r in results:
    if r.is_ok():
        print(f"{r.smiles}: {r.num_atoms} atoms")

→ Full Python guide

TypeScript / JavaScript (Node.js + Browser)

The npm package is sci-form-wasm.

npm install sci-form-wasm

Node.js (CommonJS)

const sci = require('sci-form-wasm');
const result = JSON.parse(sci.embed('CCO', 42));
console.log(`Atoms: ${result.num_atoms}`);

ES Module / TypeScript

import init, { embed } from 'sci-form-wasm';
await init();
const result = JSON.parse(embed('CC(=O)O', 42));
console.log(`Atoms: ${result.num_atoms}`);

→ Full TypeScript guide

CLI

Download prebuilt binary from GitHub Releases:

Or install via cargo:

cargo install sci-form-cli

# Single molecule
sci-form embed "CCO" --format xyz

# Batch processing
sci-form batch -i molecules.smi -o output.sdf --format sdf --threads 8

# Parse only (no 3D)
sci-form parse "c1ccccc1"

# Show version / features
sci-form info

→ Full CLI guide

Benchmark Results

Diverse Molecules (131 molecules, all chemical functional groups)

RDKit Comparison (heavy-atom pairwise-distance RMSD)

GDB-20 Ensemble (2000 molecules × 10 seeds vs 21 RDKit seeds)

Algorithm

sci-form implements ETKDGv2 (Experimental Torsion Knowledge Distance Geometry):

1. SMILES Parsing → Molecular graph with atoms, bonds, hybridization
2. Bounds Matrix → 1-2, 1-3, 1-4, and VdW distance bounds from topology
3. Triangle Smoothing → Floyd-Warshall triangle inequality enforcement
4. Distance Picking → Random distances from smoothed bounds (MinstdRand)
5. Metric Matrix Embedding → Eigendecomposition → 4D coordinates
6. Bounds Force Field → BFGS minimization in 4D to satisfy distance constraints
7. Projection to 3D → Drop lowest-variance dimension
8. ETKDG 3D Refinement — Force field with CSD torsion preferences (837 patterns)
9. Validation — Tetrahedral centers, planarity, double-bond geometry

See the algorithm documentation for mathematical derivations and step-by-step diagrams.

Building from Source

# Library + CLI
cargo build --release

# Python bindings
cd crates/python && pip install maturin && maturin develop --release

# WASM bindings
cd crates/wasm && wasm-pack build --target bundler --release

Testing

# Unit tests
cargo test --lib

# Integration — diverse molecules
cargo test --release --test test_diverse_molecules -- --nocapture

# Integration — geometry quality (requires gdb20_reference.json, see scripts/)
cargo test --release --test test_geometry_quality -- --nocapture

# Integration — gradient correctness
cargo test --release --test test_gradient_check -- --nocapture

# Lint & format
cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings

Releasing a New Version

Use the provided bump script. It updates all version strings, commits, tags, and pushes:

# Auto-increment patch (0.1.7 → 0.1.8)
./scripts/bump_version.sh

# Set a specific version
./scripts/bump_version.sh 0.2.0

This updates versions in:

• Cargo.toml (root lib)
• crates/cli/Cargo.toml
• crates/python/Cargo.toml
• crates/wasm/Cargo.toml
• crates/python/pyproject.toml
• crates/wasm/pkg/package.json
• pkg/package.json & pkg-node/package.json

Then creates a vX.Y.Z git tag, which triggers the release workflow to publish to crates.io, PyPI, and npm automatically.

Required repository secrets:

License

MIT