Chython 3.0

Chython 3.0 is a ground-up rewrite built around a new arena-based compiled core. It delivers major performance improvements, a smaller and more predictable architecture, explicit mutation and repair workflows, and a redesigned API.

This is a breaking release: the Chython 2 API has been removed rather than deprecated.

Highlights

• A single compiled Cython extension: chython.core._core
• Contiguous arena storage for atoms and bonds
• Stable atom IDs that survive edits
• Explicit edit sessions for mutation
• Per-component canonicalization
• Compiled SMILES, SMARTS, isomorphism, ring, stereo, fingerprint, InChI, and PACH implementations
• Generated element, isotope, and valence tables
• Explicit handling of invalid or incomplete chemical input
• New layered architecture with enforced dependency boundaries
• Wheels for CPython 3.10–3.14 across Linux, macOS, and Windows

New compiled core

chython.core._core is Chython's only extension and is built as a single Cython translation unit. Atoms and bonds are stored in one contiguous arena buffer rather than Python dictionaries.

Atoms are addressed by stable IDs that survive edits. Atom-to-atom mapping is stored independently in map_number, so changing a mapping no longer requires renumbering the structure.

The compiled core includes:

• SMILES and SMARTS reading and writing
• Substructure search and isomorphism
• Ring perception
• Kekulization and Thiele aromatization
• Canonicalization
• Stereochemistry
• Linear and Morgan fingerprints
• InChI
• PACH

Canonical forms are computed per component. As a result, salts, formulations, and other dotted records scale with their individual components rather than with the size of the complete mixture.

Performance

The following results compare Chython 3.0 with Chython 2.24 on an Apple M4 Pro using Python 3.10.11.

The benchmark covers 21 public compounds and reports the fastest of 15 passes. Chython 2.24 runs in a separate isolated interpreter under -I, preventing either version from being measured against an already loaded copy of itself.

Reproduce the results with:

python bench/bench_release_3_0.py

The script launches Chython 2.24 separately and prints the comparison table.

Benchmark notes

The standardize row does not represent identical work in both versions. Chython 2.24 runs the complete repair pipeline, while Chython 3.0 runs one pass of that pipeline. The parse-and-canonicalize benchmark runs the full pipeline in both versions.

Speedup ratios should remain broadly comparable across systems. Absolute timings are specific to the benchmark machine.

Explicit mutation

Containers are sealed by default. Mutations must be performed inside an edit session:

with molecule.edit() as editor:
    ...

Derived data is recomputed when the session is sealed. This keeps cached and computed state synchronized without requiring callers to manage invalidation manually.

Input is preserved, not silently repaired

Readers no longer reject records solely because they are chemically invalid or incomplete.

Illegal valences, nonsensical charges, and underivable hydrogen counts are stored and logged. Unknown hydrogen counts use the reserved H_UNKNOWN value instead of silently becoming zero.

Chemical repair is an explicit post-processing step:

• kekule()
• standardize()
• fix_resonance()
• thiele()

Structures are refused only at boundaries where a valid chemical answer is required.

Generated chemical data

Element, isotope, and valence tables are generated as compiled C tables from:

• elements.tsv
• isotopes.tsv
• valence_rules.tsv

The test suite regenerates these tables from their TSV sources and verifies the results, preventing source data and generated code from drifting apart.

New package architecture

The package is organized into layers with enforced dependency direction:

• chemistry contains chemical knowledge and the passes that apply it.
• reactions contains SMIRKS templates, functional and protective-group corpora, and mapping reconstruction.
• formats, depict, and interop provide higher-level functionality.

Internal modules do not import the public façade, and dependencies do not reverse direction. Architectural tests enforce both rules.

Functionality is attached to the sealed container through injection rather than inheritance.

Breaking changes

Chython 3.0 removes the Chython 2 API. The following packages no longer exist:

• algorithms/
• containers/
• files/
• reactor/
• periodictable/
• utils/
• transformation/

Architectural tests ensure that these legacy names cannot become importable again.

Atom IDs and mapping

A Chython 2 remap() call becomes set_map_number() when it was used to change atom-to-atom mapping:

molecule.set_map_number(...)

There is no replacement when remap() was used only to renumber atoms. Chython 3.0 uses stable atom IDs and stores map_number separately.

SMARTS z3

Chython 2 and Chython 3 assign different meanings to z3. Review every use of z3 when porting SMARTS patterns.

Fingerprints

Fingerprint bits are not compatible with those generated by Chython 2.24. Recompute stored fingerprints and rebuild any indexes or models that depend on them.

Machine-learning interface

torch_device has been removed. The machine-learning surface now uses NumPy arrays.

CGR removal

CGRContainer has been removed. ReactionModelingView is the CGR-free interface consumed by chytorch.

Element classes

Metaclass-generated element classes have been removed. Element, isotope, and valence information now comes from generated compiled tables.

Chython 2 compatibility

Chython 2.24 is retained only as an out-of-process differential oracle for validation. Importing or consulting V2 from the Chython 3 runtime is not supported.

Installation

Install the core package with:

pip install chython

The core installation contains approximately 7.5 MB of runtime files, does not require NumPy, and includes built-in InChI support.

Prebuilt wheels are available for CPython 3.10–3.14 on:

• Linux x86-64
• Linux arm64
• macOS
• Windows

A source distribution is also available.

Fingerprints, array APIs, and machine-learning views require the optional ml dependencies:

pip install 'chython[ml]'

Documentation and validation

Documentation lives in docs/. Every Python example is executed as part of validation, and every figure is regenerated and compared with its committed version.

Chython 3.0 is covered by:

• 10,911 tests
• 3 minutes 17 seconds of test execution
• 91% coverage of the Python layers
• Differential suites against Chython 2.24 and RDKit

The compiled core is validated through behavioral agreement with the differential oracles rather than source-line coverage.

Chython 3.0 replaces the internals, execution model, and public API in one release. Existing applications should treat the upgrade as a migration rather than a drop-in version change.