Metadata-Version: 2.4
Name: cosmolkit
Version: 0.5.1rc2
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Dist: numpy>=1.23
Summary: Python bindings for the COSMolKit Rust-native cheminformatics toolkit
Keywords: cheminformatics,molecular-informatics,rust,rdkit,molecular-modeling
Author: COSMolKit Contributors
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://kit.cosmol.org/
Project-URL: Homepage, https://tools.cosmol.org/
Project-URL: Issues, https://github.com/cosmol-studio/COSMolKit/issues
Project-URL: Repository, https://github.com/cosmol-studio/COSMolKit
Project-URL: Rust API, https://docs.rs/cosmolkit
Project-URL: Technical overview, https://tools.cosmol.org/rust-cheminformatics

# COSMolKit — Rust-native cheminformatics toolkit

<p align="center">
  <a href="https://github.com/cosmol-studio/COSMolKit/actions/workflows/coverage.yml">
    <img src="https://github.com/cosmol-studio/COSMolKit/actions/workflows/coverage.yml/badge.svg" alt="coverage workflow badge"/>
  </a>
  <a href="https://app.codecov.io/gh/cosmol-studio/COSMolKit">
    <img src="https://codecov.io/gh/cosmol-studio/COSMolKit/branch/main/graph/badge.svg" alt="codecov badge"/>
  </a>
  <a href="https://crates.io/crates/cosmolkit">
    <img src="https://img.shields.io/crates/v/cosmolkit.svg" alt="crates.io badge"/>
  </a>
  <a href="https://docs.rs/cosmolkit/latest/cosmolkit/">
    <img src="https://img.shields.io/docsrs/cosmolkit" alt="docs.rs badge"/>
  </a>
  <a href="https://pypi.org/project/cosmolkit/">
    <img src="https://img.shields.io/pypi/v/cosmolkit.svg" alt="pypi badge"/>
  </a>
  <a href="https://www.npmjs.com/package/@cosmol-studio/cosmolkit">
    <img src="https://img.shields.io/npm/v/@cosmol-studio/cosmolkit.svg" alt="npm badge"/>
  </a>
  <a href="LICENSE">
    <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license badge"/>
  </a>
</p>

[COSMolKit](https://github.com/cosmol-studio/COSMolKit) is a Rust-native cheminformatics and structural biology toolkit with first-class Python and JavaScript/TypeScript bindings. It provides molecular graph operations, SMILES/SMARTS and molecular file workflows, 2D depiction, native 3D conformer generation, UFF/MMFF optimization, fingerprints, molecular descriptors, InChI, batch processing, and protein structure APIs. Selected workflows are also available directly in the browser through the [COSMolKit Web Tools](https://tools.cosmol.org/tools).


For supported cheminformatics operations, RDKit-compatible behavior is treated as the correctness floor. COSMolKit uses boundary-scoped parity claims: a feature is considered parity-covered only when its documented reference surface passes the required exact or numerical comparisons. Fixed reference oracles, source-backed implementations where reference semantics require them, committed regression corpora, and explicit capability boundaries are used together; aggregate success rates or approximate similarity are not treated as substitutes for behavioral parity.

COSMolKit combines a native Rust API with Python interfaces for scientific and machine-learning workflows and JavaScript/TypeScript interfaces for browser applications. Molecular graphs, coordinates, fingerprints, bounds matrices, and structural data integrate with NumPy, PyTorch and JavaScript typed arrays.

## COSMolKit

The current chemistry reference is RDKit **2026.09.1** (Python distribution
`2026.9.1`). See the [upstream-diff audit](dev/source_provenance/rdkit_2026_03_6_to_2026_09_1.md)
for the exact revision and upstream-diff scope.

- **Modular Rust architecture:** separate crates own model values and domain
  algorithms; `cosmolkit` remains the public entry point and molecule runtime.
- **Cargo features:** select functionality such as `core`, `bio`,
  `fingerprints`, or `reaction`; prerequisites are included. Default is `full`;
  see the [Rust feature guide](crates/cosmolkit/README.md#cargo-features).
- **WebAssembly support:** run the same Rust chemistry engine in the browser
  through JavaScript bindings, without a separate algorithm implementation.
- **One API, three languages:** shared operations, defaults, results, and error
  categories, with idiomatic names for Rust, Python, and JavaScript. See
  [Public API Design](dev/public_api_design.md) for cross-language naming rules
  and shared API contracts.

Each public API is one logical entry with three projections:

| Logical name | Rust | Python | JavaScript |
|---|---|---|---|
| `from_smiles` | `Molecule::from_smiles` | `Molecule.from_smiles` | `Molecule.fromSmiles` |
| `molecular_weight` | `mol.molecular_weight()` | `mol.molecular_weight()` | `mol.molecularWeight()` |
| `to_smiles` | `mol.to_smiles()` | `mol.to_smiles()` | `mol.toSmiles()` |
| `with_hydrogens` | `mol.with_hydrogens()` | `mol.with_hydrogens()` | `mol.withHydrogens()` |
| `tpsa` | `mol.tpsa()` | `mol.tpsa()` | `mol.tpsa()` |

Learn once, then move between Python notebooks, native Rust applications, and
browser-based JavaScript without relearning the chemistry API.

## Documentation

* Python documentation: https://kit.cosmol.org/python
* JavaScript documentation: https://kit.cosmol.org/javascript
* Rust documentation: https://docs.rs/cosmolkit/latest/cosmolkit/
* Interactive Web Tools: https://tools.cosmol.org/tools

<!--
## Validation Status

COSMolKit treats parity as **source-backed semantic equivalence within explicitly documented boundaries**, not as statistical agreement of final outputs. Compatibility-critical chemistry is implemented as a line-by-line, source-backed port with explicit operation contracts and traceable correspondence to pinned upstream code. Validation corpora verify that port; they are not used to iteratively tune heuristic reimplementations until outputs happen to agree.

Validation of **COSMolKit 0.5.1-rc.2 against RDKit 2026.09.1** covers
**180,000 ChEMBL 37 source records** across completed task runs, with
**220,258,878 matching observations** and **zero unresolved mismatches**.
Conformer and CIP checks have passed revalidation. All numerical comparisons
are **bit-exact**, without tolerances. Timeouts and incomplete task groups are
recorded separately, not counted as matches. Million-scale coverage remains
pending. See [`VALIDATION.md`](VALIDATION.md) for functional coverage, profile
boundaries and completed verification results.
-->

## Installation

```bash
# Rust
cargo add cosmolkit

# Python
pip install cosmolkit

# JavaScript/TypeScript (browser or bundler)
npm install @cosmol-studio/cosmolkit
```

The npm package defaults to `full`; [smaller feature combinations](wasm/README.md#install)
are published as separate packages.

## Core Concepts

- **Value-style molecules:** methods such as `with_hydrogens()`,
  `without_hydrogens()`, `with_kekulized_bonds()`, and `with_2d_coordinates()` return new molecule values, keeping topology-changing operations explicit and preventing derived chemistry state from being silently invalidated.
- **Explicit mutation:** in-place `Molecule` operations always end with `_`.
  The trailing underscore has no other public `Molecule` meaning.
- **Explicit errors:** invalid input and unsupported behavior are surfaced as
  errors instead of silent fallbacks.
- **Batch-native processing:** `MoleculeBatch` keeps input order, supports
  structured per-record failures, and can run batch transforms and exports with
  configurable parallelism.
- **Array-friendly data access:** coordinates, bounds matrices, fingerprints,
  and graph features are exposed through NumPy and JavaScript typed arrays.
- **Source-backed 3D workflows:** conformer generation and UFF/MMFF
  optimization are available through the Python and JavaScript APIs, and atom chiral
  tags can be assigned from a selected 3D conformer with pinned-RDKit parity.

### Value-Style Transformations

Normal molecule operations return new objects and do not mutate their inputs.
This follows the same explicit-dataflow direction as modern dataframe libraries:
users can reason about each transformation as a new value while COSMolKit can
share unchanged internal storage efficiently.

```python
import cosmolkit as ck

mol = ck.mol_from_smiles("CCO")
mol_h = mol.with_hydrogens()

assert mol is not mol_h
```

## Python Quick Start

```python
import cosmolkit as ck

mol = ck.mol_from_smiles("c1ccccc1O")
mol_2d = mol.with_2d_coordinates()

print(mol_2d.to_smiles())
print(mol_2d.coordinates_2d())

mol_3d = mol.with_hydrogens().with_3d_conformer()
print(mol_3d.coordinates_3d())

svg = mol_2d.to_svg(width=400, height=300)
mol_2d.write_png("phenol.png", width=400, height=300)

fp = mol.fingerprint_morgan()
print(fp.on_bits())

atom_pair = mol.fingerprint_atom_pair()
print(atom_pair.on_bits())

layered = mol.fingerprint_layered()
print(layered.on_bits())

pattern = mol.fingerprint_pattern()
print(pattern.on_bits())

stereoisomers = list(ck.mol_from_smiles("FC(Cl)Br").enumerate_stereoisomers())
print([isomer.to_smiles() for isomer in stereoisomers])

batch = (
    ck.mols_from_smiles_list(
        ["CCO", "c1ccccc1", "CC(=O)O"],
    )
    .with_parallel_jobs(8)
    .with_progress_bar(False)
)

prepared = batch.with_hydrogens().with_2d_coordinates()
print(prepared.valid_mask())
print(prepared.to_smiles_list())

prepared.write_images("molecule_images")
```

## JavaScript Quick Start

Initialize the WASM module once. Value-style transforms leave their input
unchanged; call `free()` when WASM objects are no longer needed.

```js
import init, * as ck from "@cosmol-studio/cosmolkit";

await init();

const mol = ck.Molecule.fromSmiles("c1ccccc1O");
const mol2d = mol.with2dCoordinates();
const fp = mol.fingerprintMorgan();
const batch = ck.MoleculeBatch.fromSmilesList(["CCO", "c1ccccc1", "CC(=O)O"]);

console.log(mol.toSmiles(), mol.molecularWeight());
console.log(mol2d.toSvg(400, 300));
console.log(fp.onBits());
console.log(batch.toSmilesList());

batch.free();
fp.free();
mol2d.free();
mol.free();
```

See the [JavaScript guide](https://kit.cosmol.org/javascript) for browser/CDN
initialization and more examples.

## Protein Structures

Use `BioStructure` for complete PDB/mmCIF structural data, including modeled
proteins, nucleic acids, ligands, waters, entities, models, and metadata. Use
`Protein` only when an amino-acid-only projection is intended.

```python
import cosmolkit as ck
from pathlib import Path

structure = ck.BioStructure.from_pdb(Path("complex.pdb").read_text())
print(structure.num_models(), structure.num_chains(), structure.num_atoms())

# Structural format conversion remains on the complete structural value.
mmcif_text = structure.to_mmcif()
roundtrip = ck.BioStructure.from_mmcif(mmcif_text)
print(roundtrip.num_atoms())
```

This example reads your `complex.pdb` file.

The protein projection is explicit and leaves the full structure available:

```python
protein = structure.protein()

print(protein.num_chains())
print(protein.num_residues())
print(protein.num_atoms())

```

## SDF and Dataset Workflows

`SdfDataset` builds a lightweight index of SDF record byte ranges, so individual
records and chunks can be read without loading an entire file into memory.
Molfile-only readers such as `Molecule.read_mol()` follow RDKit
`MolFromMolBlock` boundaries: they stop after the first `M  END` line and leave
trailing SDF data fields to the SDF APIs.

```python
import cosmolkit as ck

dataset = ck.SdfDataset.open("library.sdf")
print(len(dataset))

record = dataset[0]
mol = record.molecule()

for batch in dataset.batches(size=1024, errors="keep", n_jobs=8):
    smiles = batch.to_smiles_list()
```

This example reads your `library.sdf` file.

## Conformer Generation And Optimization

```python
import cosmolkit as ck

mol = ck.mol_from_smiles("CC(=O)NC").with_hydrogens()

params = ck.EmbedParams(random_seed=0xF00D, num_threads=1)

embedded = mol.with_3d_conformer(params)
print(len(embedded.conformers_3d()))
print(embedded.coordinates_3d())

multi = mol.with_3d_conformers(5, params)
print(len(multi.conformers_3d()))

uff = embedded.uff_force_field()
print(uff.energy())
outcome = uff.minimize_(max_iterations=200)
print(uff.energy())

mmff = embedded.mmff_force_field()
print(mmff.energy())
outcome = mmff.minimize_(max_iterations=200)
print(mmff.energy())
```

`with_3d_conformer()` uses source-backed distance-geometry embedding for trusted
molecular graphs: molecules without explicit hydrogens are embedded as heavy-atom-only
conformers instead of failing or automatically adding hydrogens. Calling
`with_hydrogens()` first is recommended for all-atom geometry, force-field
optimization, and hydrogen-bond-sensitive workflows. Coordinate-only inputs
such as XYZ blocks do not contain a bond topology and are not valid ETKDG
inputs until a trusted graph has been constructed.

## Feature Areas

- Molecular graph construction and inspection
- SMILES parsing and writing
- MOL/SDF reading and writing
- MOL2 reading with RDKit-style `Mol2ParserParams`
- XYZ block reading
- Four scalar InChI APIs with exact source-defined official-C/RDKit parity and structured errors
- Source-backed 3D atom-chiral-tag assignment
- Typed potential-stereo analysis and lazy, source-ordered stereoisomer
  enumeration with exhaustive, bounded random, uniqueness, enhanced-group,
  and optional embedding controls
- Hydrogen transforms and Kekulization
- Sanitization and chemistry problem detection
- Source-backed Rust tautomer enumeration, canonical selection, scoring,
  callbacks, current and V1 transform catalogs, and ordered result provenance
- 2D coordinate generation and SVG/PNG depiction
- Native 3D conformer generation with DG/KDG/ETDG/ETKDG parameter presets
- Read-only molecular alignment/RMSD measurement and explicit value-style or
  trailing-underscore coordinate alignment
- UFF/MMFF optimization of generated or imported 3D conformers
- Morgan, MACCS, RDKit topological, Avalon, Pattern, AtomPair, and Topological Torsion
  fingerprints for the validated exact-parity branches, including sparse/count
  forms, provenance, tautomer-aware Pattern hashing, 2D/3D AtomPair distances,
  and ordered batch execution
- Source-backed RDKit Layered fingerprint 0.7.0 with all six active layers,
  roots, masks, seeded atom counts, and ordered batch execution; this family
  retains upstream's experimental classification
- Distance-geometry bounds matrices
- Substructure matching and SMARTS parse metadata
- Ordered batch transforms and exports
- Python pickle round-tripping for `Molecule`
- Complete PDB/mmCIF `BioStructure` parsing, Gemmi-aligned mmCIF writing,
  protein projections, and explicit structure-to-molecule conversion
- Support-status metadata for public features

## Design Principles

COSMolKit aims to be Python- and JavaScript-friendly, batch-friendly, and
suitable for scientific and browser workflows.

- Correctness comes before breadth.
- Public transforms use value semantics.
- Mutation-capable workflows are explicit.
- **Fail-closed capability boundaries:** a separately named capability outside
  documented support returns a structured error rather than fabricated
  chemistry. This is an API design rule, not an accepted mismatch within a
  supported feature.
- RDKit-parity behavior is the correctness floor for supported
  cheminformatics features.
- High-throughput APIs should preserve input order and expose per-record
  failures.
- Reference semantics come before heuristic approximation; semantic debt is treated as a correctness risk.

## Examples

Python examples live in `python/examples/`; JavaScript examples live in
[`wasm/examples/vanilla/`](wasm/examples/vanilla/).
For the current InChI interface, see
[`python/examples/inchi_roundtrip.py`](python/examples/inchi_roundtrip.py).

## Development

Small focused Rust test filters may use the default debug profile while
iterating:

```bash
cargo test -p cosmolkit-core <test-filter>
```

Daily checks and local parity runs use the optimized `dev-test` profile, with
runtime strict checks enabled on `cosmolkit`:

```bash
cargo test -p cosmolkit-core --profile dev-test
cargo test -p cosmolkit --profile dev-test --features op-contracts-strict
```

Detached core algorithms have no runtime-check features. `op-contracts-strict`
enables operation contracts and runtime invariants on `cosmolkit` independently
of the build profile. Distribution builds use `--release` with fat LTO and
one codegen unit; daily `dev-test` builds avoid that overhead.

## Functionality

Status labels:

- ✅ stable public functionality within its documented supported scope
- 🧪 public experimental feature; available, but its behavior or API may change

The ✅ status applies to the documented COSMolKit scope. It does not claim that
every API or input branch from an upstream reference library is implemented;
separately named upstream capabilities outside that scope are not represented
as implemented. Every path inside a parity-covered boundary is still required
to match; individual failing rows cannot be reclassified as out of scope.

### Chemistry Core

Goal: keep the supported molecular core correct before expanding breadth.

- ✅ Molecule, atom, and bond graph model
- ✅ SMILES parsing
- ✅ SMILES writing with RDKit-style writer options for supported branches
- ✅ Ring perception, valence handling, aromaticity, and Kekulization
- ✅ Hydrogen addition and removal
- ✅ Sanitization for supported chemistry workflows
- ✅ Tautomer enumeration, canonical selection, scoring, and source-defined
  stereochemistry and isotopic-hydrogen options
- ✅ Stereochemistry inspection for supported atom and bond states
- ✅ Typed potential-stereo analysis and lazy stereoisomer enumeration through
  the pinned RDKit Python behavior, including arbitrary-width counts, seeded
  random generation, enhanced stereo groups, uniqueness, and optional embedding
- ✅ Atom chiral-tag assignment from selected 3D conformers, with a designated
  77-case full-state special-regression matrix for `assignChiralTypesFrom3D`
- ✅ Distance-geometry bounds matrices
- ✅ Native 3D conformer generation and UFF/MMFF post-optimization for
  supported molecules
- ✅ `Molecule.to_inchi()`, `Molecule.to_inchi_key()`, `inchi_to_key()`, and
  `Molecule.from_inchi()` for source-defined behavior; official-C undefined
  allocation behavior returns a structured error
- ✅ Source-backed Morgan, MACCS, RDKFingerprint/topological, Avalon, Pattern,
  AtomPair, and Topological Torsion fingerprints for their validated
  exact-parity branches, including typed provenance, count/bit forms,
  tautomer-aware Pattern hashing, 2D/3D AtomPair distances, Tanimoto
  similarity, and ordered batch execution
- 🧪 Source-backed RDKit Layered fingerprint `0.7.0`, including all six active
  layers, roots, masks, seeded counts, and ordered batch execution; upstream
  classifies this fingerprint family as experimental
- ✅ Substructure matching and Python SMARTS parse metadata
- ✅ Molecular descriptors: weight/formula, H-bond and Lipinski counts,
  Crippen/TPSA/QED, connectivity Chi, Hall-Kier/Kappa/Phi, ring and stereo
  counts, MQN, Labute ASA, and SlogP/SMR VSA for the documented parameter space

### File I/O and Depiction

Goal: make common molecule import, export, and visualization workflows usable
from Python and JavaScript.

- ✅ MOL/SDF reading
- ✅ MOL2 reading
- ✅ XYZ block reading
- ✅ SDF dataset indexing for large files
- ✅ SDF writing for supported V2000/V3000 branches
- ✅ PDB block to molecule conversion
- ✅ mmCIF block to molecule conversion through the same molecule-conversion
  profile
- ✅ 2D coordinate generation
- ✅ SVG drawing
- ✅ PNG export
- ✅ RDKit-style visual parity testing for supported depiction output
- ✅ 3D conformer generation and embedding APIs

### Batch-Native Workflows

Goal: make high-throughput molecule preparation and export a core product
identity.

- ✅ Ordered `MoleculeBatch.from_smiles_list()`
- ✅ Batch transforms for sanitization, hydrogens, Kekulization, and 2D
  coordinates
- ✅ Configurable parallelism with `with_parallel_jobs()`
- ✅ Configurable progress display with `with_progress_bar()`
- ✅ Per-record errors, valid masks, and error reports
- ✅ Batch SMILES, image, and SDF export paths
- ✅ Golden parity tests for parallel batch behavior

### Protein and Structural Biology

Goal: provide practical Biopython-like structure workflows without forcing users
through low-level structural tables.

- ✅ `Protein.from_pdb()` / `Protein.from_mmcif()` high-level entry points
- ✅ `BioStructure.from_pdb()` / `BioStructure.from_mmcif()` complete-structure
  entry points and mixed-structure hierarchy traversal
- ✅ Protein chain, residue, and atom iteration
- ✅ Protein-only projection from broader structural data
- ✅ PDB/mmCIF structural parsing
- ✅ Gemmi-aligned `BioStructure` mmCIF serialization and file writing
- ✅ Structural selection and chain/residue/atom traversal

### Python API and ML Readiness

Goal: expose verified molecular behavior through a practical Python interface.

- ✅ Stable value-style mutation contract for public molecule transformations
- ✅ Graph, coordinate, fingerprint, descriptor, and bounds-matrix accessors
- ✅ Python examples for drawing, SDF-to-SMILES, pickle round-tripping, batch
  processing, and proteins
- ✅ Type stubs and documentation coverage
- ✅ NumPy fingerprint vectors and batch matrices

### Browser and Deployment

Goal: make validated COSMolKit functionality usable without requiring a local Python or Rust installation.

* ✅ [COSMolKit Web Tools](https://tools.cosmol.org/tools) for browser-based molecular workflows
* ✅ Browser-native deployment of selected COSMolKit functionality through WebAssembly
* ✅ Generated JavaScript/TypeScript API with prebuilt feature combinations

## Acknowledgments

COSMolKit includes Rust ports of code and algorithms from:

- [RDKit](https://github.com/rdkit/rdkit)
- [Gemmi](https://github.com/project-gemmi/gemmi)

## License

COSMolKit is licensed under the [MIT License](LICENSE). Vendored sources and
externally derived test fixtures retain their upstream copyright and license
terms as documented beside those files.

