trex-notation 0.1.0__tar.gz

trex_notation-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ilia Kevlishvili
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

trex_notation-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: trex-notation
+Version: 0.1.0
+Summary: T-REX — Trans-pair Relations EXpression for coordination topology
+Author-email: Ilia Kevlishvili <ilia_kevlishvili@baylor.edu>
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12
+Requires-Dist: pydantic>=2
+Requires-Dist: ruamel.yaml
+Requires-Dist: networkx
+Requires-Dist: numpy
+Requires-Dist: rdkit==2025.3.5
+Dynamic: license-file
+
+# 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:
+```bash
+git clone https://github.com/iliak14/trex.git
+cd trex
+```
+
+2. Create the environment:
+```bash
+conda env create -f environment.yml
+conda activate trex
+```
+
+3. Install using pip:
+```bash
+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
+```python
+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
+```python
+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
+```python
+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](https://www.rdkit.org/) — cheminformatics toolkit
+- [NumPy](https://numpy.org/) — numerical computing
+- [NetworkX](https://networkx.org/) — graph algorithms
+- [Pydantic](https://docs.pydantic.dev/) (v2) — data validation
+- [ruamel.yaml](https://yaml.readthedocs.io/) — YAML parsing
+- [Typer](https://typer.tiangolo.com/) — CLI framework
+
+## License
+
+This project is licensed under the MIT License.
+
+## Citation
+
+If you use T-REX in your research, please cite:
+```bibtex
+@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](https://doi.org/10.26434/chemrxiv-2025-7s3gx)

trex_notation-0.1.0/README.md

@@ -0,0 +1,159 @@
+# 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:
+```bash
+git clone https://github.com/iliak14/trex.git
+cd trex
+```
+
+2. Create the environment:
+```bash
+conda env create -f environment.yml
+conda activate trex
+```
+
+3. Install using pip:
+```bash
+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
+```python
+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
+```python
+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
+```python
+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](https://www.rdkit.org/) — cheminformatics toolkit
+- [NumPy](https://numpy.org/) — numerical computing
+- [NetworkX](https://networkx.org/) — graph algorithms
+- [Pydantic](https://docs.pydantic.dev/) (v2) — data validation
+- [ruamel.yaml](https://yaml.readthedocs.io/) — YAML parsing
+- [Typer](https://typer.tiangolo.com/) — CLI framework
+
+## License
+
+This project is licensed under the MIT License.
+
+## Citation
+
+If you use T-REX in your research, please cite:
+```bibtex
+@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](https://doi.org/10.26434/chemrxiv-2025-7s3gx)

trex_notation-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "trex-notation"
+version = "0.1.0"
+description = "T-REX — Trans-pair Relations EXpression for coordination topology"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [{name="Ilia Kevlishvili", email="ilia_kevlishvili@baylor.edu"}]
+dependencies = ["typer>=0.12","pydantic>=2","ruamel.yaml","networkx","numpy","rdkit==2025.3.5"]
+
+
+[tool.black]
+line-length = 88
+target-version = ["py39"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+ignore = ["E402"]                 # keep if you have local imports to avoid cycles
+
+[tool.ruff.lint.per-file-ignores]
+"trex/__init__.py" = ["F401"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "lf"
+skip-magic-trailing-comma = false
+

trex_notation-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

trex_notation-0.1.0/trex/__init__.py

@@ -0,0 +1,13 @@
+# trex/__init__.py
+from .model import LigandPayload, MapSite, TrexFull, TrexMin
+
+# New public helper (supersedes the old canonicalize_smiles_with_map)
+# from .smiles_canon import canonical_smiles_and_maps
+
+__all__ = [
+    "TrexMin",
+    "TrexFull",
+    "LigandPayload",
+    "MapSite",
+    #    "canonical_smiles_and_maps",
+]

trex_notation-0.1.0/trex/canon.py

@@ -0,0 +1,40 @@
+from collections import Counter
+
+from .model import TrexMin
+from .registry import Registry
+
+
+def canonicalize_min(t: TrexMin, reg: Registry) -> TrexMin:
+    dent = Counter()
+    for i, j in t.pairs:
+        dent[i] += 1
+        dent[j] += 1
+    for i in t.singles:
+        dent[i] += 1
+
+    props = []
+    for idx, tok in enumerate(t.ligands, start=1):
+        li = reg.get(tok)
+        charge = li.charge
+        mw = li.mw_monoiso or 0.0
+        sign_rank = 0 if charge < 0 else (1 if charge == 0 else 2)
+        props.append((idx, tok, dent[idx], abs(charge), sign_rank, mw))
+
+    # priority: dent ↓, |charge| ↓, sign (anion<neutral<cation), MW ↓, token ↑
+    order = [p[0] for p in sorted(props, key=lambda p: (-p[2], -p[3], p[4], -p[5], p[1]))]
+    remap = {old: new for new, old in enumerate(order, start=1)}
+
+    ligs = [t.ligands[i - 1] for i in order]
+    pairs = sorted({tuple(sorted((remap[i], remap[j]))) for (i, j) in t.pairs})
+    singles = sorted({remap[i] for i in t.singles})
+
+    return TrexMin(
+        metal=t.metal,
+        ox=t.ox,
+        spin=t.spin,
+        ligands=ligs,
+        pairs=pairs,
+        singles=singles,
+        G=t.G,
+        X=t.X,
+    )