sdfrust 0.5.0__tar.gz → 0.6.0__tar.gz

{sdfrust-0.5.0 → sdfrust-0.6.0}/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-02-19
+
+### Added
+
+- Graph adjacency infrastructure (`AdjacencyList`) with O(1) neighbor lookups and degree computation
+- Atom valence and hydrogen count: `atom_degree()`, `implicit_hydrogen_count()`, `total_hydrogen_count()` with default valence table for ~20 elements
+- SSSR ring perception via spanning-tree + GF(2) linear independence: `sssr()`, `ring_sizes()`, `smallest_ring_size()`
+- Hybridization inference from bond topology: `atom_hybridization()`, `all_hybridizations()` (S/SP/SP2/SP3/SP3D/SP3D2)
+- Aromaticity perception: two-stage (trust file annotations + Hückel 4n+2 rule on SSSR rings) with support for pyrrole, furan, thiophene
+- Conjugation detection: aromatic bonds, SP2-SP2 single bonds, unsaturated bond chains
+- OGB-compatible GNN featurizer: `ogb_atom_features()` [N, 9], `ogb_bond_features()` [E, 3], `ogb_graph_features()` with directed edge index
+- ECFP/Morgan fingerprints: `ecfp()` bit vector, `ecfp_counts()` hash map, Tanimoto similarity — first pure-Rust implementation
+- Gasteiger-Marsili partial charges: PEOE iterative algorithm with ~15 atom type parameters
+- CIP chirality perception: `atom_chirality()`, `all_chiralities()` with R/S determination from 3D signed volume
+- Bond inference from 3D coordinates: `infer_bonds()`, `infer_bonds_with_config()` using covalent radii
+- Cutoff-based neighbor list for 3D GNNs: `neighbor_list()` with directed edges and distances (geometry feature)
+- Bond angle and dihedral angle computation: `bond_angle()`, `dihedral_angle()`, `all_bond_angles()`, `all_dihedral_angles()` (geometry feature)
+- Python bindings for all new ML features with NumPy array outputs (`get_ogb_atom_features_array()`, `get_ecfp_array()`, `get_gasteiger_charges_array()`)
+- Python examples: format conversion, batch analysis, geometry operations, ML features
+- Rust example: `examples/ml_features.rs`
+
 ## [0.5.0] - 2026-02-17
 
 ### Added
@@ -54,7 +75,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Molecule methods: `formula()`, `centroid()`, `translate()`, `neighbors()`, `element_counts()`
 - Memory-efficient streaming iterator for large multi-molecule files
 
-[Unreleased]: https://github.com/HFooladi/sdfrust/compare/v0.5.0...HEAD
+[Unreleased]: https://github.com/HFooladi/sdfrust/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/HFooladi/sdfrust/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/HFooladi/sdfrust/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/HFooladi/sdfrust/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/HFooladi/sdfrust/compare/v0.2.0...v0.3.0

{sdfrust-0.5.0 → sdfrust-0.6.0}/Cargo.lock

@@ -58,9 +58,9 @@ checksum = "843867be96c8daad0d758b57df9392b6d8d271134fce549de6ce169ff98a92af"
 
 [[package]]
 name = "bumpalo"
-version = "3.19.1"
+version = "3.20.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5dd9dc738b7a8311c7ade152424974d8115f2cdad61e8dab8dac9f2362298510"
+checksum = "5c6f81257d10a0f602a294ae4182251151ff97dbb504ef9afcdda4a64b24d9b4"
 
 [[package]]
 name = "bytemuck"
@@ -827,7 +827,7 @@ dependencies = [
 
 [[package]]
 name = "sdfrust"
-version = "0.5.0"
+version = "0.6.0"
 dependencies = [
  "criterion",
  "flate2",
@@ -839,7 +839,7 @@ dependencies = [
 
 [[package]]
 name = "sdfrust-python"
-version = "0.5.0"
+version = "0.6.0"
 dependencies = [
  "numpy",
  "pyo3",

{sdfrust-0.5.0 → sdfrust-0.6.0}/Cargo.toml

@@ -4,7 +4,7 @@ resolver = "2"
 
 [package]
 name = "sdfrust"
-version = "0.5.0"
+version = "0.6.0"
 edition = "2024"
 rust-version = "1.85"
 authors = ["Hosein Fooladi"]

{sdfrust-0.5.0 → sdfrust-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sdfrust
-Version: 0.5.0
+Version: 0.6.0
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: MIT License
@@ -237,6 +237,26 @@ mol.add_bond(sdfrust.Bond(0, 2, sdfrust.BondOrder.single()))
 sdfrust.write_sdf_file(mol, "water.sdf")
 ```
 
+## Examples
+
+The `examples/` directory contains runnable scripts demonstrating real-world usage:
+
+| Script | Description |
+|--------|-------------|
+| [`basic_usage.py`](examples/basic_usage.py) | Core API: parsing, writing, atoms, bonds, descriptors, NumPy |
+| [`format_conversion.py`](examples/format_conversion.py) | Multi-format detection, XYZ parsing, SDF/MOL2 conversion, round-trips |
+| [`batch_analysis.py`](examples/batch_analysis.py) | Drug library processing: filtering, sorting, Lipinski analysis |
+| [`geometry_analysis.py`](examples/geometry_analysis.py) | 3D geometry: distance matrices, RMSD, rotation, transforms |
+
+```bash
+cd sdfrust-python
+maturin develop --features numpy,geometry
+python examples/basic_usage.py
+python examples/format_conversion.py
+python examples/batch_analysis.py
+python examples/geometry_analysis.py
+```
+
 ## Performance
 
 sdfrust is implemented in Rust for maximum performance. Benchmarks show it is

{sdfrust-0.5.0 → sdfrust-0.6.0}/README.md

@@ -16,6 +16,9 @@ A fast, pure-Rust parser for SDF (Structure Data File), MOL2, and XYZ chemical s
 - **Python Bindings**: First-class Python API with NumPy integration
 - **Streaming Parsing**: Memory-efficient iteration over large files
 - **Molecular Descriptors**: MW, exact mass, ring count, rotatable bonds, and more
+- **ML-Ready Featurization**: OGB-compatible GNN features, ECFP fingerprints, Gasteiger charges
+- **Chemical Perception**: SSSR rings, aromaticity (Hückel 4n+2), hybridization, conjugation
+- **3D GNN Support**: Cutoff-based neighbor lists, bond/dihedral angles for SchNet/DimeNet/GemNet
 - **High Performance**: ~220,000 molecules/sec (4-7x faster than RDKit)
 - **Real-World Validated**: 100% success rate on PDBbind 2024 dataset (27,670 ligand SDF files)
 
@@ -27,7 +30,7 @@ Add to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-sdfrust = "0.5"
+sdfrust = "0.6"
 ```
 
 ### Python
@@ -198,6 +201,90 @@ mol.atoms_by_element("C")
 mol.bonds_by_order(BondOrder::Double)
 ```
 
+## ML-Ready Features
+
+sdfrust provides chemical perception and featurization for molecular ML — compute features in Rust, output NumPy arrays for PyTorch/JAX.
+
+### OGB GNN Featurization
+
+```rust
+use sdfrust::featurize::ogb;
+
+let graph = ogb::ogb_graph_features(&mol);
+// graph.atom_features: [N, 9] - atomic_num, chirality, degree, charge, num_hs, radical, hybridization, aromatic, in_ring
+// graph.bond_features: [2E, 3] - bond_type, stereo, conjugated
+// graph.edge_src, graph.edge_dst: directed edge index
+```
+
+```python
+# Python: direct NumPy arrays for PyTorch Geometric
+atom_feats = mol.get_ogb_atom_features_array()  # np.array [N, 9]
+bond_feats = mol.get_ogb_bond_features_array()  # np.array [E, 3]
+graph = mol.ogb_graph_features()                 # dict with edge_src, edge_dst
+```
+
+### ECFP/Morgan Fingerprints
+
+```rust
+use sdfrust::fingerprints::ecfp;
+
+let fp = ecfp::ecfp(&mol, 2, 2048);  // ECFP4, 2048 bits
+let similarity = fp.tanimoto(&other_fp);
+```
+
+```python
+fp = mol.ecfp(radius=2, n_bits=2048)       # List[bool]
+fp_array = mol.get_ecfp_array()             # np.array (2048,)
+sim = mol.tanimoto_similarity(other_mol)    # float
+```
+
+### Gasteiger Partial Charges
+
+```rust
+use sdfrust::descriptors::gasteiger_charges;
+
+let charges = gasteiger_charges(&mol);  // Vec<f64>
+```
+
+```python
+charges = mol.gasteiger_charges()           # List[float]
+charges_array = mol.get_gasteiger_charges_array()  # np.array (N,)
+```
+
+### Chemical Perception
+
+```rust
+use sdfrust::descriptors::{sssr, all_aromatic_atoms, all_hybridizations, all_conjugated_bonds};
+
+let rings = sssr(&mol);                         // SSSR ring perception
+let aromatic = all_aromatic_atoms(&mol);         // Hückel 4n+2 aromaticity
+let hybs = all_hybridizations(&mol);             // SP/SP2/SP3
+let conjugated = all_conjugated_bonds(&mol);     // Bond conjugation
+```
+
+```python
+rings = mol.sssr()                    # List of ring atom lists
+aromatic = mol.all_aromatic_atoms()   # List[bool]
+hybs = mol.all_hybridizations()       # List[str]
+conj = mol.all_conjugated_bonds()     # List[bool]
+```
+
+### 3D GNN Features (geometry feature)
+
+```rust
+use sdfrust::geometry::{neighbor_list, all_bond_angles, all_dihedral_angles};
+
+let nl = neighbor_list(&mol, 5.0);         // Cutoff-based neighbor list
+let angles = all_bond_angles(&mol);         // Bond angles for DimeNet
+let dihedrals = all_dihedral_angles(&mol);  // Dihedral angles for GemNet
+```
+
+```python
+nl = mol.neighbor_list(cutoff=5.0)         # dict: edge_src, edge_dst, distances
+angles = mol.all_bond_angles()              # dict: triplets, angles
+dihedrals = mol.all_dihedral_angles()       # dict: quadruplets, angles
+```
+
 ## Supported Formats
 
 | Format | Read | Write |
@@ -262,6 +349,35 @@ sdfrust.write_sdf_auto_file(mol, path)  # Auto-select V2000/V3000
 sdfrust.write_sdf_file_multi(mols, path)
 ```
 
+### ML Feature Methods (on Molecule)
+
+```python
+# Chemical perception
+mol.sssr()                           # SSSR rings
+mol.all_aromatic_atoms()             # Aromaticity
+mol.all_hybridizations()             # Hybridization
+mol.all_conjugated_bonds()           # Conjugation
+
+# ML features
+mol.ogb_atom_features()              # [N, 9] OGB features
+mol.ogb_bond_features()              # [E, 3] OGB features
+mol.ogb_graph_features()             # Full graph dict
+mol.ecfp(radius=2, n_bits=2048)      # ECFP bit vector
+mol.tanimoto_similarity(other)       # Tanimoto coefficient
+mol.gasteiger_charges()              # Partial charges
+
+# NumPy arrays (with numpy feature)
+mol.get_ogb_atom_features_array()    # np.array [N, 9]
+mol.get_ogb_bond_features_array()    # np.array [E, 3]
+mol.get_ecfp_array()                 # np.array (n_bits,)
+mol.get_gasteiger_charges_array()    # np.array (N,)
+
+# 3D features (with geometry feature)
+mol.neighbor_list(cutoff=5.0)        # Neighbor list dict
+mol.bond_angle(i, j, k)             # Angle in radians
+mol.dihedral_angle(i, j, k, l)      # Dihedral in radians
+```
+
 ### Classes
 
 - `Molecule`: Main molecular container

sdfrust-0.6.0/examples/ml_features.rs

@@ -0,0 +1,233 @@
+//! ML-ready feature computation example for sdfrust
+//!
+//! Demonstrates:
+//! - OGB-compatible GNN atom and bond featurization
+//! - ECFP/Morgan fingerprints and Tanimoto similarity
+//! - Gasteiger partial charges
+//! - Ring perception (SSSR), aromaticity, hybridization, conjugation
+//! - Valence and hydrogen count
+//!
+//! Run with: cargo run --example ml_features
+
+use sdfrust::descriptors::{
+    all_aromatic_atoms, all_aromatic_bonds, all_conjugated_bonds, all_hybridizations,
+    all_total_hydrogen_counts, gasteiger_charges, sssr,
+};
+use sdfrust::featurize::ogb;
+use sdfrust::fingerprints::ecfp;
+use sdfrust::graph::AdjacencyList;
+use sdfrust::{Atom, Bond, BondOrder, Molecule};
+
+fn make_benzene() -> Molecule {
+    let mut mol = Molecule::new("benzene");
+    let coords: [(f64, f64); 6] = [
+        (1.21, 0.70),
+        (1.21, -0.70),
+        (0.00, -1.40),
+        (-1.21, -0.70),
+        (-1.21, 0.70),
+        (0.00, 1.40),
+    ];
+    for (i, &(x, y)) in coords.iter().enumerate() {
+        mol.atoms.push(Atom::new(i, "C", x, y, 0.0));
+    }
+    for i in 0..6 {
+        mol.bonds
+            .push(Bond::new(i, (i + 1) % 6, BondOrder::Aromatic));
+    }
+    mol
+}
+
+fn make_ethanol() -> Molecule {
+    let mut mol = Molecule::new("ethanol");
+    mol.atoms.push(Atom::new(0, "C", -0.001, 1.086, 0.008));
+    mol.atoms.push(Atom::new(1, "C", 0.002, -0.422, 0.002));
+    mol.atoms.push(Atom::new(2, "O", 1.210, -0.907, -0.003));
+    mol.atoms.push(Atom::new(3, "H", 1.020, 1.465, 0.001));
+    mol.atoms.push(Atom::new(4, "H", -0.536, 1.449, -0.873));
+    mol.atoms.push(Atom::new(5, "H", -0.523, 1.437, 0.902));
+    mol.atoms.push(Atom::new(6, "H", -0.524, -0.785, 0.891));
+    mol.atoms.push(Atom::new(7, "H", -0.510, -0.793, -0.884));
+    mol.atoms.push(Atom::new(8, "H", 1.192, -1.870, -0.003));
+    mol.bonds.push(Bond::new(0, 1, BondOrder::Single));
+    mol.bonds.push(Bond::new(1, 2, BondOrder::Single));
+    mol.bonds.push(Bond::new(0, 3, BondOrder::Single));
+    mol.bonds.push(Bond::new(0, 4, BondOrder::Single));
+    mol.bonds.push(Bond::new(0, 5, BondOrder::Single));
+    mol.bonds.push(Bond::new(1, 6, BondOrder::Single));
+    mol.bonds.push(Bond::new(1, 7, BondOrder::Single));
+    mol.bonds.push(Bond::new(2, 8, BondOrder::Single));
+    mol
+}
+
+fn make_aspirin() -> Molecule {
+    // Simplified aspirin (just the ring + functional groups, no H)
+    let mut mol = Molecule::new("aspirin");
+    // Benzene ring: C0-C5
+    for i in 0..6 {
+        mol.atoms.push(Atom::new(i, "C", 0.0, 0.0, 0.0));
+    }
+    for i in 0..6 {
+        let order = if i % 2 == 0 {
+            BondOrder::Double
+        } else {
+            BondOrder::Single
+        };
+        mol.bonds.push(Bond::new(i, (i + 1) % 6, order));
+    }
+    // Carboxylic acid: C6(=O7)-O8
+    mol.atoms.push(Atom::new(6, "C", 0.0, 0.0, 0.0));
+    mol.atoms.push(Atom::new(7, "O", 0.0, 0.0, 0.0));
+    mol.atoms.push(Atom::new(8, "O", 0.0, 0.0, 0.0));
+    mol.bonds.push(Bond::new(0, 6, BondOrder::Single));
+    mol.bonds.push(Bond::new(6, 7, BondOrder::Double));
+    mol.bonds.push(Bond::new(6, 8, BondOrder::Single));
+    // Ester: O9-C10(=O11)-C12
+    mol.atoms.push(Atom::new(9, "O", 0.0, 0.0, 0.0));
+    mol.atoms.push(Atom::new(10, "C", 0.0, 0.0, 0.0));
+    mol.atoms.push(Atom::new(11, "O", 0.0, 0.0, 0.0));
+    mol.atoms.push(Atom::new(12, "C", 0.0, 0.0, 0.0));
+    mol.bonds.push(Bond::new(3, 9, BondOrder::Single));
+    mol.bonds.push(Bond::new(9, 10, BondOrder::Single));
+    mol.bonds.push(Bond::new(10, 11, BondOrder::Double));
+    mol.bonds.push(Bond::new(10, 12, BondOrder::Single));
+    mol
+}
+
+fn main() {
+    println!("=== sdfrust ML Features Example ===\n");
+
+    // --- 1. Ring Perception & Aromaticity ---
+    println!("--- Ring Perception & Aromaticity ---\n");
+    let benzene = make_benzene();
+    let rings = sssr(&benzene);
+    println!("Benzene SSSR: {} ring(s)", rings.len());
+    for (i, ring) in rings.iter().enumerate() {
+        println!(
+            "  Ring {}: atoms {:?} (size {})",
+            i,
+            ring.atoms,
+            ring.atoms.len()
+        );
+    }
+
+    let aromatic_atoms = all_aromatic_atoms(&benzene);
+    println!("Aromatic atoms: {:?}", aromatic_atoms);
+
+    let aromatic_bonds = all_aromatic_bonds(&benzene);
+    println!("Aromatic bonds: {:?}", aromatic_bonds);
+    println!();
+
+    // --- 2. Hybridization ---
+    println!("--- Hybridization ---\n");
+    let ethanol = make_ethanol();
+    let hybs = all_hybridizations(&ethanol);
+    for (i, hyb) in hybs.iter().enumerate() {
+        let elem = &ethanol.atoms[i].element;
+        println!("  Atom {} ({}): {:?}", i, elem, hyb);
+    }
+    println!();
+
+    // --- 3. Conjugation ---
+    println!("--- Conjugation ---\n");
+    let aspirin = make_aspirin();
+    let conjugated = all_conjugated_bonds(&aspirin);
+    for (i, &conj) in conjugated.iter().enumerate() {
+        let bond = &aspirin.bonds[i];
+        println!(
+            "  Bond {} ({}-{}): conjugated={}",
+            i, bond.atom1, bond.atom2, conj
+        );
+    }
+    println!();
+
+    // --- 4. Hydrogen Counts ---
+    println!("--- Hydrogen Counts ---\n");
+    let h_counts = all_total_hydrogen_counts(&ethanol);
+    for (i, &count) in h_counts.iter().enumerate() {
+        let elem = &ethanol.atoms[i].element;
+        println!("  Atom {} ({}): {} total H", i, elem, count);
+    }
+    println!();
+
+    // --- 5. OGB GNN Features ---
+    println!("--- OGB GNN Features ---\n");
+    let atom_feats = ogb::ogb_atom_features(&benzene);
+    println!("Benzene atom features [N={}, F=9]:", atom_feats.num_atoms);
+    for (i, feat) in atom_feats.features.iter().enumerate() {
+        println!("  Atom {}: {:?}", i, feat);
+    }
+
+    let bond_feats = ogb::ogb_bond_features(&benzene);
+    println!("\nBenzene bond features [E={}, F=3]:", bond_feats.num_bonds);
+    for (i, feat) in bond_feats.features.iter().enumerate() {
+        println!("  Bond {}: {:?}", i, feat);
+    }
+
+    let graph = ogb::ogb_graph_features(&benzene);
+    println!(
+        "\nFull graph: {} atoms, {} directed edges",
+        graph.atom_features.num_atoms,
+        graph.edge_src.len()
+    );
+    println!();
+
+    // --- 6. ECFP Fingerprints ---
+    println!("--- ECFP Fingerprints ---\n");
+    let fp_benzene = ecfp::ecfp(&benzene, 2, 2048);
+    let fp_ethanol = ecfp::ecfp(&ethanol, 2, 2048);
+    println!(
+        "Benzene ECFP4: {} bits set / {}",
+        fp_benzene.num_on_bits(),
+        fp_benzene.n_bits
+    );
+    println!(
+        "Ethanol ECFP4: {} bits set / {}",
+        fp_ethanol.num_on_bits(),
+        fp_ethanol.n_bits
+    );
+    println!("Benzene density: {:.4}", fp_benzene.density());
+    println!(
+        "Tanimoto(benzene, ethanol): {:.4}",
+        fp_benzene.tanimoto(&fp_ethanol)
+    );
+    println!(
+        "Tanimoto(benzene, benzene): {:.4}",
+        fp_benzene.tanimoto(&fp_benzene)
+    );
+
+    // Count fingerprint
+    let counts = ecfp::ecfp_counts(&benzene, 2);
+    println!(
+        "\nBenzene ECFP4 count fingerprint: {} unique features",
+        counts.counts.len()
+    );
+    println!();
+
+    // --- 7. Gasteiger Charges ---
+    println!("--- Gasteiger Charges ---\n");
+    let charges = gasteiger_charges(&ethanol);
+    for (i, &charge) in charges.iter().enumerate() {
+        let elem = &ethanol.atoms[i].element;
+        println!("  Atom {} ({}): charge = {:+.4}", i, elem, charge);
+    }
+    println!();
+
+    // --- 8. Graph Adjacency ---
+    println!("--- Graph Adjacency ---\n");
+    let adj = AdjacencyList::from_molecule(&ethanol);
+    for i in 0..3 {
+        let elem = &ethanol.atoms[i].element;
+        let neighbors = adj.neighbor_atoms(i);
+        println!(
+            "  Atom {} ({}): degree={}, heavy_degree={}, neighbors={:?}",
+            i,
+            elem,
+            adj.degree(i),
+            adj.heavy_degree(i),
+            neighbors
+        );
+    }
+
+    println!("\n=== Example Complete ===");
+}

{sdfrust-0.5.0 → sdfrust-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "sdfrust"
-version = "0.5.0"
+version = "0.6.0"
 description = "Fast Rust-based SDF, MOL2, and XYZ molecular structure file parser"
 authors = [
     {name = "Hosein Fooladi", email = "hosein@example.com"}

{sdfrust-0.5.0 → sdfrust-0.6.0}/sdfrust-python/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "sdfrust-python"
-version = "0.5.0"
+version = "0.6.0"
 edition = "2021"
 rust-version = "1.70"
 authors = ["Hosein Fooladi"]

{sdfrust-0.5.0 → sdfrust-0.6.0}/sdfrust-python/README.md

@@ -206,6 +206,26 @@ mol.add_bond(sdfrust.Bond(0, 2, sdfrust.BondOrder.single()))
 sdfrust.write_sdf_file(mol, "water.sdf")
 ```
 
+## Examples
+
+The `examples/` directory contains runnable scripts demonstrating real-world usage:
+
+| Script | Description |
+|--------|-------------|
+| [`basic_usage.py`](examples/basic_usage.py) | Core API: parsing, writing, atoms, bonds, descriptors, NumPy |
+| [`format_conversion.py`](examples/format_conversion.py) | Multi-format detection, XYZ parsing, SDF/MOL2 conversion, round-trips |
+| [`batch_analysis.py`](examples/batch_analysis.py) | Drug library processing: filtering, sorting, Lipinski analysis |
+| [`geometry_analysis.py`](examples/geometry_analysis.py) | 3D geometry: distance matrices, RMSD, rotation, transforms |
+
+```bash
+cd sdfrust-python
+maturin develop --features numpy,geometry
+python examples/basic_usage.py
+python examples/format_conversion.py
+python examples/batch_analysis.py
+python examples/geometry_analysis.py
+```
+
 ## Performance
 
 sdfrust is implemented in Rust for maximum performance. Benchmarks show it is

sdfrust-0.6.0/sdfrust-python/examples/README.md

@@ -0,0 +1,134 @@
+# sdfrust Python Examples
+
+This directory contains example scripts demonstrating the Python API.
+
+## Setup
+
+Before running examples, build and install the Python bindings:
+
+```bash
+cd sdfrust-python
+uv venv .venv --python 3.11
+source .venv/bin/activate
+uv pip install maturin numpy pytest
+maturin develop --features numpy
+```
+
+## Running Examples
+
+```bash
+# From sdfrust-python directory
+python examples/basic_usage.py
+python examples/format_conversion.py
+python examples/batch_analysis.py
+
+# Geometry examples require the geometry feature
+maturin develop --features numpy,geometry
+python examples/geometry_analysis.py
+```
+
+## Examples Overview
+
+### basic_usage.py
+
+Core functionality covering:
+
+- **Parsing SDF files**: Load molecules from V2000 and V3000 SDF files
+- **Parsing SDF strings**: Parse inline SDF content
+- **Creating molecules**: Build molecules programmatically with atoms and bonds
+- **Atom access**: Read atom properties, filter by element, calculate distances
+- **Bond access**: Work with bond orders, stereochemistry, and connectivity
+- **Molecular descriptors**: Calculate MW, exact mass, ring count, rotatable bonds
+- **Geometry operations**: Centroid calculation, translation, centering
+- **Properties**: Read/write SDF data block properties
+- **Multi-molecule files**: Iterate over files with multiple molecules
+- **Writing SDF**: Export molecules to V2000 or V3000 format
+- **MOL2 parsing**: Read TRIPOS MOL2 format files
+- **V3000 format**: Work with extended SDF format
+- **NumPy integration**: Get/set coordinates as NumPy arrays
+- **Ring detection**: Identify atoms and bonds in rings
+- **Charged atoms**: Handle formal charges
+
+### format_conversion.py
+
+Multi-format detection, parsing, and conversion:
+
+- **Format detection**: Identify SDF V2000, V3000, and MOL2 from content (`detect_format()`)
+- **Auto-detection parsing**: Parse any format with one function (`parse_auto_file()`)
+- **XYZ parsing**: Single and multi-molecule XYZ files, streaming with `iter_xyz_file()`
+- **SDF → MOL2 conversion**: Convert molecules with round-trip verification
+- **MOL2 → SDF conversion**: Convert molecules with round-trip verification
+- **Batch conversion**: Write multi-molecule SDF and MOL2 files (`write_sdf_file_multi()`, `write_mol2_file_multi()`)
+- **Gzip support**: Check runtime feature availability (`gzip_enabled()`)
+
+### batch_analysis.py
+
+Compound library processing with real drug molecules:
+
+- **Library loading**: Parse multi-molecule SDF with summary table
+- **Streaming iteration**: Memory-efficient processing with `iter_sdf_file()`
+- **MW filtering**: Filter by molecular weight range, write subsets
+- **Descriptor sorting**: Rank molecules by MW and heavy atom count
+- **Element composition**: Compare C/H/O/N/S counts across molecules
+- **Bond profiles**: Compare single/double/aromatic bond distributions
+- **Lipinski analysis**: Apply Rule of Five criteria using SDF properties
+- **Finding extremes**: Identify molecules with most atoms, highest MW, most rings
+
+### geometry_analysis.py
+
+3D geometry operations (requires `--features geometry`):
+
+- **Distance matrix**: Pairwise distances, closest/farthest atom pairs
+- **Bond length analysis**: Extract actual bond lengths by bond type
+- **RMSD comparison**: Compare identical, translated, and perturbed molecules
+- **Rotation**: Axis-angle rotation with distance preservation verification
+- **Combined transforms**: Rotation matrix + translation
+- **NumPy analysis**: Bounding box, spatial extent, radius of gyration
+- **Conformer comparison**: Perturb coordinates, center, compare RMSD
+
+### Example Data
+
+The `data/` directory contains real drug molecules downloaded from PubChem:
+
+- `ibuprofen.sdf` — NSAID (CID 3672, 33 atoms)
+- `dopamine.sdf` — Neurotransmitter (CID 681, 22 atoms)
+- `cholesterol.sdf` — Steroid (CID 5997, 74 atoms)
+- `drug_library.sdf` — Combined multi-molecule file (6 drugs)
+
+## Quick Reference
+
+```python
+import sdfrust
+
+# Parse files
+mol = sdfrust.parse_sdf_file("molecule.sdf")
+mol = sdfrust.parse_mol2_file("molecule.mol2")
+mol = sdfrust.parse_sdf_auto_file("molecule.sdf")  # Auto-detect V2000/V3000
+
+# Parse strings
+mol = sdfrust.parse_sdf_string(sdf_content)
+mol = sdfrust.parse_mol2_string(mol2_content)
+
+# Create molecule
+mol = sdfrust.Molecule("my_molecule")
+mol.add_atom(sdfrust.Atom(0, "C", 0.0, 0.0, 0.0))
+mol.add_bond(sdfrust.Bond(0, 1, sdfrust.BondOrder.single()))
+
+# Basic properties
+print(mol.name, mol.num_atoms, mol.num_bonds)
+print(mol.formula())
+print(mol.molecular_weight())
+
+# Iterate large files efficiently
+for mol in sdfrust.iter_sdf_file("large_library.sdf"):
+    process(mol)
+
+# Write files
+sdfrust.write_sdf_file(mol, "output.sdf")
+sdf_str = sdfrust.write_sdf_string(mol)
+
+# NumPy integration
+coords = mol.get_coords_array()  # shape (N, 3)
+mol.set_coords_array(new_coords)
+atomic_nums = mol.get_atomic_numbers()
+```