trex-notation 0.1.0

T-REX — Trans-pair Relations EXpression for coordination topology

T-REX: Trans-Pairs Relations EXpression

T-REX is a modular string notation and Python library designed for the representation, manipulation, and canonicalization of Transition Metal Complexes (TMCs).

Unlike standard SMILES which often struggle with the dynamic coordination spheres of metals, T-REX explicitly encodes the metal center, oxidation state, ligand payloads (SMILES/SELFIES), and the geometric trans-pair relations of the coordination sphere.

Key Features

• 3D to String: Convert XYZ coordinates into T-REX strings with automatic ligand detection, charge estimation (EHT), and geometric classification. (xyz_to_trex.py)
• String to Graph: Deterministic conversion of T-REX strings into RDKit Mol objects, preserving dative bonds and adding virtual "trans" edges. (trex2mol.py)
• Canonicalization: Robust canonicalization handling ligand permutations, internal ligand symmetry (graph & ECFP), and stereoisomer equivalence. (canon_full.py)
• Chirality Detection: Metal-centered chirality computation supporting both point-central (@/@@) and helical (Δ/Λ) chirality across tetrahedral, trigonal bipyramidal, square pyramidal, and octahedral geometries. (chirality.py)
• Enumeration: Combinatorial generation of all valid stereoisomers for a given coordination formula. (enumerate_trex.py)
• Isomer Classification: Classify pairs of complexes as identical, enantiomers, coordination isomers, geometric isomers, and more. (isomer_compare.py)

Stand-alone Scripts

• Generative ligand substitution: Generate novel structures through ligand substitution based on ligand topology matching: (build_indices_and_parents.py > enumerate_children_mp.py > dedupe_canonical_batch.py)
• Graph Neural Networks: GNNs using T-REX (MPNN.py — standard message passing neural network. HyperMPNN.py — hybrid message passing neural network with hyperedges)

Installation

Prerequisites

T-REX relies on RDKit. It is recommended to use Conda/Mamba.

Installation

1. Clone the repository:

git clone https://github.com/iliak14/trex.git
cd trex

2. Create the environment:

conda env create -f environment.yml
conda activate trex

3. Install using pip:

pip install -e .

T-REX String Format

A T-REX string is a pipe-delimited sequence of blocks:

HEAD | L=[ ligands ] | MAP:{ topology } | G:geometry | X:chirality

• HEAD — metal symbol, oxidation state, and optional spin-multiplicity: Fe{+3} or Co{+3,S=1}
• L=[...] — comma-separated ligand payloads, each prefixed by type (e.g., SMILES:, SELFIES:, INCHI:, or TOKEN:).
• MAP:{...} — trans-pairs as (site_a, site_b) and singletons after ;. Each site is lig_index:atom_index (1-based).
• G: — optional geometry flag (O = octahedral, sqpl = square planar, sqpy = square pyramidal, trbp = trigonal bipyramidal, etc.)
• X: — optional chirality flag (@, @@, Δ, Λ)

Examples

Square planar Pt(II) with two ammine and two chlorido ligands, where NH₃ and Cl⁻ are trans to each other:

Pt{+2} | L=[ SMILES:[Cl-], SMILES:[Cl-], SMILES:N, SMILES:N ] | MAP:{ (1:1, 3:1), (2:1, 4:1) }

Octahedral Fe(III) hexachlorido:

Fe{+3} | L=[ SMILES:[Cl-], SMILES:[Cl-], SMILES:[Cl-], SMILES:[Cl-], SMILES:[Cl-], SMILES:[Cl-] ] | MAP:{ (1:1, 2:1), (3:1, 4:1), (5:1, 6:1) } | G:O

Octahedral Co(III) tris(ethylenediamine) with bidentate ligands:

Co{+3} | L=[ SMILES:NCCN, SMILES:NCCN, SMILES:NCCN ] | MAP:{ (1:1, 2:1), (1:4, 3:1), (2:4, 3:4) } | G:O

Quick Start

Parsing a T-REX string

from trex.parse_full import parse_trex_full

trex_string = "Pt{+2} | L=[ SMILES:[Cl-], SMILES:[Cl-], SMILES:N, SMILES:N ] | MAP:{ (1:1, 3:1), (2:1, 4:1) }"

t = parse_trex_full(trex_string)
print(t.metal)           # Pt
print(t.ox)              # 2
print(t.cn())            # 4
print(t.get_geo_type())  # sqpl

Canonicalizing a T-REX string

from trex.parse_full import canonicalize_trex_full_string

raw = "Pt{+2} | L=[ SMILES:N, SMILES:N, SMILES:[Cl-], SMILES:[Cl-] ] | MAP:{ (1:1, 3:1), (2:1, 4:1) }"
canonical = canonicalize_trex_full_string(raw)
print(canonical)
# Pt{+2} | L=[ SMILES:[Cl-], SMILES:[Cl-], SMILES:N, SMILES:N ] | MAP:{ (1:1, 3:1), (2:1, 4:1) }

Converting XYZ to T-REX

from trex.xyz_to_trex import xyz_to_trex

trex_string = xyz_to_trex("complex.xyz")

Chirality Detection

T-REX handles two fundamentally different types of metal-centered chirality.

Point-Central Chirality (@ / @@)

Point chirality arises in all-monodentate complexes when no two equivalent ligands can be swapped by a symmetry operation. T-REX uses the determinant method: four coordination sites are selected according to geometry-specific rules and their signed volume (the scalar triple product) determines handedness.

Achirality conditions are checked per geometry before computing:

• Tetrahedral — achiral if any two sites are equivalent
• Trigonal bipyramidal — achiral if the axial trans partners are equivalent, or if any two equatorial sites are equivalent
• Square pyramidal — achiral if any trans partners within a pair are equivalent, or if the two basal pairs are equivalent (i.e. mirror plane not going through a site)
• Octahedral — achiral if any trans partners within a pair are equivalent, or if a set of two pairs are equivalent

Helical Chirality (Δ / Λ)

Helical chirality is relevant for multidentate octahedral complexes where point-central chirality is absent (e.g., all sites may be equivalent) but a propeller-like twist exists. T-REX supports three cases:

• Tris-bidentate [M(L∩L)₃] — always helically chiral. Uses the propeller method: each chelate's bite vector forms a blade, and the twist of these blades around the pseudo-C₃ axis determines Δ or Λ.
• Cis-bis-bidentate [M(L∩L)₂X₂] — helically chiral when the two monodentate ligands are cis to each other (i.e. two bidentates are not on the same plane).
• Fac-fac bis-tridentate [M(L∩L∩L)₂] — helically chiral when both tridentates adopt facial coordination (no internal trans pairs). Computed by measuring the twist angle between the two triangular faces.

The compute_chirality() function is the main entry point: it checks point-central chirality first, then falls back to helical chirality, returning @, @@, Δ, Λ, or None.

Dependencies

• RDKit — cheminformatics toolkit
• NumPy — numerical computing
• NetworkX — graph algorithms
• Pydantic (v2) — data validation
• ruamel.yaml — YAML parsing
• Typer — CLI framework

License

This project is licensed under the MIT License.

Citation

If you use T-REX in your research, please cite:

@article{kevlishvili2025trex,
  title   = {Taming {T-REX}: A Canonical Language for Geometry-Aware Generative Design of Transition Metal Complexes},
  author  = {Kevlishvili, Ilia},
  journal = {ChemRxiv},
  year    = {2025},
  doi     = {10.26434/chemrxiv-2025-7s3gx}
}

Kevlishvili, I. "Taming T-REX: A Canonical Language for Geometry-Aware Generative Design of Transition Metal Complexes." ChemRxiv, 2025. DOI: 10.26434/chemrxiv-2025-7s3gx