sci-form

High-performance 3D molecular conformer generation and quantum-chemistry-inspired property computation, written in pure Rust.

Generates chemically valid 3D coordinates from SMILES strings with RDKit-quality accuracy (ETKDGv2), and provides a full suite of computational chemistry tools: Extended Hückel Theory, electrostatic potentials, density of states, population analysis, molecular alignment, force field energy evaluation (UFF + MMFF94), partial charges, SASA, and materials framework assembly.

Native bindings for Rust, Python, TypeScript/JavaScript (WASM), and a cross-platform CLI.

Features

Conformer Generation

• ETKDGv2 Distance Geometry — CSD torsion preferences (846 SMARTS patterns), matches RDKit accuracy
• 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
• Full chemical coverage — organics, stereocenters, macrocycles, fused rings, metals, halogens (He→Bi)

Quantum Chemistry (EHT)

• Extended Hückel Theory — Wolfsberg-Helmholtz Hamiltonian, Löwdin orthogonalization, HOMO/LUMO gaps
• Mulliken & Löwdin population analysis — atomic orbital contributions per atom
• Molecular dipole moment — bond dipoles + lone-pair contributions in Debye
• Volumetric orbital grids — STO-3G basis, chunked evaluation for large molecules, marching cubes isosurfaces
• Density of States — total DOS + per-atom PDOS with Gaussian smearing, JSON export, MSE metric

Experimental RHF Engine

• Isolated experimental_2 namespace — next-generation Roothaan-Hall RHF engine without affecting stable APIs
• Analytical Gaussian integrals — overlap, kinetic, nuclear attraction, core Hamiltonian, and two-electron ERIs
• SCF with DIIS + parallel ERI — deterministic RHF/STO-3G workflow with rayon acceleration for the expensive $O(N^4)$ step
• Experimental spectroscopy stack — prototype sTDA UV-Vis, GIAO-like NMR shielding, and semi-numerical IR/Hessian workflows
• GPU-oriented architecture — WGSL shader stubs, orbital grid evaluation, and marching-cubes rendering pipeline prepared for future wgpu enablement

Electrostatics & Surface

• Electrostatic Potential (ESP) — Coulomb grid from Mulliken charges, color mapping (red/white/blue), .cube export
• Parallel ESP — rayon-accelerated grid computation (parallel feature)
• Solvent-Accessible Surface Area (SASA) — Shrake-Rupley algorithm, Fibonacci sphere, Bondi radii, parallelized per-atom evaluation
• Gasteiger-Marsili partial charges — 6-iteration electronegativity equalization

Parallel Computation

• Automatic rayon thread pool — all compute functions (DOS, ESP SASA, population, dipole, etc.) parallelized with work-stealing queue
• Zero-configuration — no API changes needed; parallelization enabled by default via parallel feature
• Intra-library parallelism — grid point loops, per-atom evaluation, force field term accumulation all use par_iter()
• CPU-aware workload balancing — handles small molecules (sequential) and large molecules (parallel) automatically

Force Fields

• UFF — Universal Force Field for 50+ element types (including transition metals Ti–Zn, Pd, Pt, Au)
• MMFF94 — Merck force field (stretch, bend, torsion, van der Waals, electrostatics via 14-7 potential)
• BFGS / L-BFGS minimizers — dense BFGS for small molecules, L-BFGS for large systems

Molecular Alignment

• Kabsch alignment — SVD-based optimal rotation, minimizes RMSD
• Quaternion alignment — Coutsias 2004 4×4 eigenproblem (faster for large molecules)
• RMSD computation — after optimal superposition

Materials

• Periodic unit cells — lattice parameters (a, b, c, α, β, γ) to Cartesian tensor
• Secondary Building Units (SBUs) — node/linker topology with coordination sites
• Framework assembly — MOF-type crystal structure generation from SBUs + topology

Platform

• 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 parser and substructure matcher; 60+ bracket elements

Quick Start

Rust

[dependencies]
sci-form = "0.2"
# For parallel batch + ESP:
sci-form = { version = "0.2", features = ["parallel"] }

use sci_form::{embed, compute_charges, compute_esp, compute_dos, compute_population};

// 3D conformer
let result = sci_form::embed("CCO", 42);
println!("Atoms: {}, Time: {:.1}ms", result.num_atoms, result.time_ms);

// Gasteiger–Marsili charges
let charges = sci_form::compute_charges("CCO").unwrap();
println!("Charges: {:?}", charges.charges);

// EHT → population analysis
let mol = sci_form::parse("CCO").unwrap();
let elements: Vec<u8> = /* ... */ vec![8, 6, 6, 1, 1, 1, 1, 1, 1];
let positions: Vec<[f64; 3]> = /* ... from result.coords */ vec![];
let pop = sci_form::compute_population(&elements, &positions).unwrap();
println!("HOMO: {:.3} eV", pop.homo_energy);

// ESP grid
let esp = sci_form::compute_esp(&elements, &positions, 0.5, 3.0).unwrap();

// DOS / PDOS
let dos = sci_form::compute_dos(&elements, &positions, 0.2, -20.0, 5.0, 200).unwrap();
println!("HOMO–LUMO gap: {:.3} eV", dos.homo_lumo_gap.unwrap_or(0.0));

→ Full Rust API reference · Guide

Python

pip install sciforma

import sci_form

# 3D conformer
result = sci_form.embed("CCO")
print(f"Atoms: {result.num_atoms}, Time: {result.time_ms:.1f}ms")

# Batch
results = sci_form.embed_batch(["CCO", "c1ccccc1", "CC(=O)O"])

# Gasteiger charges
charges = sci_form.compute_charges("CCO")
print(charges["charges"])  # per-atom charges

# EHT + population analysis
elements = [8, 6, 6, 1, 1, 1, 1, 1, 1]
positions = [[0.0, 0.0, 0.0], ...]   # from result.coords
pop = sci_form.compute_population(elements, positions)
print(f"HOMO: {pop['homo_energy']:.3f} eV")

# DOS / PDOS
dos = sci_form.compute_dos(elements, positions, sigma=0.2, e_min=-20.0, e_max=5.0, n_points=200)
print(f"Gap: {dos['homo_lumo_gap']:.3f} eV")

→ Full Python API reference · Guide

TypeScript / JavaScript (WASM)

npm install sci-form-wasm

import init, {
  embed, embed_coords_typed,
  compute_esp_grid_typed, compute_esp_grid_info,
  eht_calculate, eht_orbital_mesh, eht_orbital_grid_typed,
  compute_charges, compute_dos
} from 'sci-form-wasm';

await init();

// Conformer as JSON
const result = JSON.parse(embed('CCO', 42));
console.log(result.num_atoms);

// Typed-array conformer (faster, no JSON overhead)
const coords: Float64Array = embed_coords_typed('CCO', 42);

// EHT calculation
const eht = JSON.parse(eht_calculate('[6,8,6,1,1,1,1,1,1]', coords.toString(), 1.75));
console.log(`HOMO: ${eht.homo_energy} eV, LUMO: ${eht.lumo_energy} eV`);

// Orbital isosurface mesh
const mesh = JSON.parse(eht_orbital_mesh('[6,8,6,1,1,1,1,1,1]', coords.toString(), 1.75, 0, 0.02));
// mesh.vertices, mesh.normals, mesh.indices

// ESP grid (typed array)
const espData: Float64Array = compute_esp_grid_typed('CCO', 42, 0.5, 3.0);
const espInfo = JSON.parse(compute_esp_grid_info('CCO', 42, 0.5, 3.0));
console.log(`Grid: ${espInfo.nx}×${espInfo.ny}×${espInfo.nz}`);

// DOS
const dos = JSON.parse(compute_dos('[6,8,6,1,1,1,1,1,1]', coords.toString(), 0.2, -20.0, 5.0, 200));

→ Full TypeScript API reference · Guide

CLI

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"

# Gasteiger charges
sci-form charges "CCO"

# UFF energy
sci-form energy "CCO" --coords coords.json

# Version / features
sci-form info

Prebuilt binaries available at GitHub Releases:

→ Full CLI reference · Guide

Experimental Engine

The repository now includes an isolated experimental quantum-chemistry stack under sci_form::experimental_2.

Phase Status

Current Practical Status

• Stable production APIs remain unchanged; the experimental work is isolated in experimental_2
• Real acceleration today is CPU parallelism via rayon in the ERI build path
• GPU execution is not enabled yet; phase1_gpu_infrastructure currently exposes a CPU fallback plus WGSL-ready interfaces
• The main known scientific limitation is absolute RHF/STO-3G total energy scaling in the experimental engine; comparative gaps and regression behavior are the primary validation target today

Validation Snapshot

The experimental stack is covered by dedicated regression suites:

# Build all library + test targets
cargo check --tests

# Base experimental regression suite
cargo test --test regression test_experimental_comparison -- --nocapture

# Extended complex-molecule battery (fast active tests)
cargo test --test regression test_extended_molecules -- --nocapture

# Heavy experimental benchmarks and long-running tests
cargo test --release --test regression test_extended_molecules -- --include-ignored

Current verified results on this repository state:

More detailed coverage notes live in TESTING.md, and the broader project plan remains in ROADMAP.md.

Benchmark Results

Conformer Generation — Diverse Molecules (131 molecules, all functional groups)

RDKit Comparison — Heavy-atom pairwise-distance RMSD

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

Module Overview

Sub-modules

The Conformer Pipeline

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 (846 patterns)
9. Validation → Tetrahedral centers, planarity, double-bond geometry

See the algorithm documentation for mathematical derivations and 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 && ./build.sh --web-only --web-features "parallel experimental-gpu"

# With parallel feature
cargo build --release --features parallel

Testing

# All unit tests
cargo test --lib

# Smoke battery (CI gate)
cargo test --release --test ci -- --nocapture

# Full integration suites
cargo test --release --test regression -- --nocapture
cargo test --release --test analysis -- --nocapture
cargo test --release --test debug -- --nocapture
cargo test --release --test benchmarks -- --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