linearscript 3.1.3

SCRIPT : A deterministic, RDKit-independent molecular notation with 100% round-trip stereo parity, materials science extensions, biopolymer support, and formal LALR grammar.

SCRIPT (Structural Chemical Representation In Plain Text)

A deterministic, 1-to-1 canonical molecular notation system designed to solve the ambiguity of SMILES.

SCRIPT is a next-generation cheminformatics engine and text notation designed from the ground up for strict mathematical determinism. Whether you are generating datasets for machine learning, encoding complex macrocycles, or standardizing molecular databases, SCRIPT ensures that every unique molecular graph maps strictly to one and only one text representation.

Powered by a robust context-free grammar and a lightweight, RDKit-independent core, it eliminates the need for expensive post-hoc sanitization or canonicalization loops—it is canonical by design.

🚀 Why SCRIPT?

SCRIPT is a completely new chemistry notation—not a modification of SMILES or InChI. It is a deterministic 1-to-1 canonical notation built from scratch with a strict context-free grammar and a Sandhi state machine that eliminates ambiguity entirely.

Unlike SMILES, which can represent a single molecule in dozens of valid ways (e.g., Aspirin can be written in over 50 valid SMILES strings), SCRIPT uses a deterministic Sandhi state machine to ensure a 1-to-1 mapping between a molecular graph and its text representation.

Aspirin in SMILES:  CC(=O)Oc1ccccc1C(=O)O  (one of many valid forms)
Aspirin in SCRIPT:  CC(=O)OC:C:C:C:C:C&6:C(=O)O  (always and only this)

✨ Key Capabilities

• Canonical by Design: DFS + Morgan ranking guarantees 100% canonical strings.
• RDKit-Free Core: Parse, validate, and manipulate molecular graphs without heavy cheminformatics dependencies.
• Topologically Complete: Natively encodes complex bridged polycycles and macrocycles using flat-history topological offsets.
• Advanced Chemistry: Full support for organometallics (dative/haptic/coordinate bonds), alloys with fractional occupancies (<~0.9>), and electronic/excited states (<s:3>, <*>).
• Materials & Surfaces: Natively encode crystallographic contexts ([[Rutile]]) and surface chemistry interfaces (|).
• Biopolymers: Built-in grammar for peptide and nucleic acid chains ({A.G.S}).
• Chemical Reactions: Robust multi-component reaction representation (R>>P).

📦 Installation

# Core engine (no RDKit required)
pip install linearscript

# Full suite with RDKit bridge for SMILES interoperability
pip install linearscript[rdkit]

💻 Quick Start

Parse and Canonicalize

from script.parser import SCRIPTParser
from script.canonical import SCRIPTCanonicalizer

parser = SCRIPTParser()
# Parse from a SMILES-style input (SCRIPT is backwards compatible with basic SMILES)
result = parser.parse("CC(=O)Oc1ccccc1C(=O)O")

mol = result["molecule"]
print(f"Atoms: {len(mol.atoms)}, Bonds: {len(mol.bonds)}")

# Generate the 1-to-1 unique canonical SCRIPT string
canon = SCRIPTCanonicalizer().canonicalize_core(mol)
print(canon)  # Output: CC(=O)OC:C:C:C:C:C&6:C(=O)O

RDKit Interoperability

from rdkit import Chem
from script.rdkit_bridge import SCRIPTFromMol, MolFromSCRIPT

# Convert RDKit Mol to SCRIPT
mol = Chem.MolFromSmiles("CN1CCC[C@H]1c2cccnc2")
script_str = SCRIPTFromMol(mol)

# Convert SCRIPT back to RDKit Mol
mol_back = MolFromSCRIPT(script_str)

🆕 Latest Updates

• Bridged Macrocycle Support: Replaced topological stack depths with deterministic flat-history linear offsets, ensuring 100% round-trip fidelity for complex bridged rings (e.g. norbornane, cyclic peptides).
• E/Z Stereocenter Resolution: Enhanced bond token parsing to fully capture and resolve double bond stereochemistry geometry (\C=C\).
• CIP-Anchored Parity: Hardened stereochemical parity between the DFS string traversal space and RDKit's internal numerical index space.

📚 Documentation & Source

For full documentation, advanced usage tutorials, materials science examples, and the complete grammar specification, please visit the GitHub Repository.

📄 License

MIT with Commons Clause. Free for academic and non-commercial use. Commercial licensing available separately.

---

Developed by SCRIPT Development Team.
GitHub: sangeet01/script