tetramol 0.0.1__tar.gz

tetramol-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Andreas V. Copan
+
+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.

tetramol-0.0.1/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: tetramol
+Version: 0.0.1
+Author: Andreas V. Copan
+Author-email: Andreas V. Copan <avcopan@uga.edu>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: automol>=0.0.28
+Requires-Dist: numpy>=2
+Requires-Dist: py3dmol>=2.5
+Requires-Dist: scipy>=1.13
+Requires-Dist: xyzrender>=0.3.8
+Requires-Python: >=3.13
+Project-URL: Repository, https://github.com/avcopan/tetramol
+Project-URL: Documentation, https://avcopan.github.io/tetramol/
+Description-Content-Type: text/markdown
+
+# tetramol
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![Pixi Badge](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/prefix-dev/pixi/main/assets/badge/v0.json)](https://pixi.sh)
+[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
+[![Typing: ty](https://img.shields.io/badge/typing-ty-EFC621.svg)](https://github.com/astral-sh/ty)
+[![Copier](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-grayscale-border.json)](https://github.com/copier-org/copier)
+
+Idealized molecular structures for illustrations, rendered as SVGs with
+[xyzrender](https://github.com/aligfellow/xyzrender).
+
+Atoms are placed on a tetrahedral "diamond" grid, with ideal bond lengths (1.1 Å to
+hydrogen, 1.5 Å otherwise) and angles (arccos(-1/3) ≈ 109.47°), so neighboring
+centers are always staggered. This is meant for clean, schematic pictures, not for
+real geometries.
+
+## Installation
+
+```sh
+pixi run init      # first time only
+pixi run local start   # use the local ../automol checkout (see below)
+```
+
+tetramol depends on [automol](https://github.com/avcopan/automol) (from the `avcopan`
+conda channel) for geometry handling, and on xyzrender (from PyPI) for rendering.
+To develop against a local automol checkout next to this repository, toggle it with
+`pixi run local start` and `pixi run local stop`.
+
+## Usage
+
+```python
+from automol import geom
+from tetramol import Builder, orient, render
+
+b = Builder(up=(0, 1, 0), left=(-1, 0, 0))  # y is up the page, z toward you
+c = b.add("C")  # the first atom goes at the origin
+n = b.add("N", c, toward=(0, 1, 0))  # bond through the slot closest to a direction
+b.add("C", c, toward=(-1, 0, 0))  # ... or through a slot by index: b.add("C", c, 2)
+b.add_hydrogens(avoid=(0, 0, -1))  # fill valences; N's lone pair points back
+geo = b.geometry()  # an automol Geometry
+
+rot = orient(geo)  # optional: rotate by hand in the browser,
+geo = geom.rotate(geo, rot)  # ... and apply the rotation
+render(geo, "drawing.svg")
+```
+
+Each atom has four slots, one per tetrahedral direction, and bonded atoms bond back
+through the same slot, which fills in the diamond lattice. Use `automol.geom` for
+anything off the grid (e.g. `geom.rotate(geo, rot, origin=..., keys=[...])`).
+
+To draw an umbrella inversion, `b.umbrella_image(n)` adds the mirror image of the
+branch on atom `n` (through the plane of its parent bond, perpendicular to its lone
+pair), keeping both, so that one side can be faded afterwards.
+
+Drawings live in [`drawings/`](https://github.com/avcopan/tetramol/tree/main/drawings), one folder per molecule.
+
+## Contributing
+
+Pull requests are welcome. For major changes, please open an issue first
+to discuss what you would like to change.
+
+## Credits
+
+This package was created with [copier](https://copier.readthedocs.io/) and the [avcopan/copier-pixi-python](https://github.com/avcopan/copier-pixi-python) project template.

tetramol-0.0.1/README.md

@@ -0,0 +1,64 @@
+# tetramol
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![Pixi Badge](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/prefix-dev/pixi/main/assets/badge/v0.json)](https://pixi.sh)
+[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
+[![Typing: ty](https://img.shields.io/badge/typing-ty-EFC621.svg)](https://github.com/astral-sh/ty)
+[![Copier](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-grayscale-border.json)](https://github.com/copier-org/copier)
+
+Idealized molecular structures for illustrations, rendered as SVGs with
+[xyzrender](https://github.com/aligfellow/xyzrender).
+
+Atoms are placed on a tetrahedral "diamond" grid, with ideal bond lengths (1.1 Å to
+hydrogen, 1.5 Å otherwise) and angles (arccos(-1/3) ≈ 109.47°), so neighboring
+centers are always staggered. This is meant for clean, schematic pictures, not for
+real geometries.
+
+## Installation
+
+```sh
+pixi run init      # first time only
+pixi run local start   # use the local ../automol checkout (see below)
+```
+
+tetramol depends on [automol](https://github.com/avcopan/automol) (from the `avcopan`
+conda channel) for geometry handling, and on xyzrender (from PyPI) for rendering.
+To develop against a local automol checkout next to this repository, toggle it with
+`pixi run local start` and `pixi run local stop`.
+
+## Usage
+
+```python
+from automol import geom
+from tetramol import Builder, orient, render
+
+b = Builder(up=(0, 1, 0), left=(-1, 0, 0))  # y is up the page, z toward you
+c = b.add("C")  # the first atom goes at the origin
+n = b.add("N", c, toward=(0, 1, 0))  # bond through the slot closest to a direction
+b.add("C", c, toward=(-1, 0, 0))  # ... or through a slot by index: b.add("C", c, 2)
+b.add_hydrogens(avoid=(0, 0, -1))  # fill valences; N's lone pair points back
+geo = b.geometry()  # an automol Geometry
+
+rot = orient(geo)  # optional: rotate by hand in the browser,
+geo = geom.rotate(geo, rot)  # ... and apply the rotation
+render(geo, "drawing.svg")
+```
+
+Each atom has four slots, one per tetrahedral direction, and bonded atoms bond back
+through the same slot, which fills in the diamond lattice. Use `automol.geom` for
+anything off the grid (e.g. `geom.rotate(geo, rot, origin=..., keys=[...])`).
+
+To draw an umbrella inversion, `b.umbrella_image(n)` adds the mirror image of the
+branch on atom `n` (through the plane of its parent bond, perpendicular to its lone
+pair), keeping both, so that one side can be faded afterwards.
+
+Drawings live in [`drawings/`](https://github.com/avcopan/tetramol/tree/main/drawings), one folder per molecule.
+
+## Contributing
+
+Pull requests are welcome. For major changes, please open an issue first
+to discuss what you would like to change.
+
+## Credits
+
+This package was created with [copier](https://copier.readthedocs.io/) and the [avcopan/copier-pixi-python](https://github.com/avcopan/copier-pixi-python) project template.

tetramol-0.0.1/pyproject.toml

@@ -0,0 +1,95 @@
+[project]
+name = "tetramol"
+version = "0.0.1"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = [
+    "automol>=0.0.28",
+    "numpy>=2",
+    "py3dmol>=2.5",
+    "scipy>=1.13",
+    "xyzrender>=0.3.8",
+]
+requires-python = ">= 3.13"
+
+[[project.authors]]
+name = "Andreas V. Copan"
+email = "avcopan@uga.edu"
+
+[project.urls]
+Repository = "https://github.com/avcopan/tetramol"
+Documentation = "https://avcopan.github.io/tetramol/"
+
+[build-system]
+build-backend = "uv_build"
+requires = ["uv_build"]
+
+[tool.ruff]
+extend-exclude = [".claude"]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "COM812",
+    "TID252",
+    "D203",
+    "D213",
+    "CPY001",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**.py" = [
+    "S101",
+    "PLR2004",
+]
+"drawings/**.py" = [
+    "INP001",
+    "F401",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ty.environment]
+python = ".pixi/envs/test/bin/python"
+
+[tool.ty.src]
+include = [
+    "src",
+    "tests",
+]
+
+[tool.importlinter]
+root_package = "tetramol"
+
+[[tool.importlinter.contracts]]
+name = "Module Layering"
+type = "layers"
+layers = [
+    "tetramol.draw",
+    "tetramol.build",
+    "tetramol.grid",
+]
+
+[tool.pytest.ini_options]
+testpaths = [
+    "tests",
+    "src",
+]
+addopts = [
+    "--doctest-modules",
+    "--cov=tetramol",
+    "--cov-report=term-missing",
+    "--cov-report=html",
+]
+doctest_optionflags = "NORMALIZE_WHITESPACE"
+
+[tool.coverage.run]
+branch = true
+source = ["tetramol"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true
+fail_under = 80

tetramol-0.0.1/pyproject.toml.orig

@@ -0,0 +1,89 @@
+[project]
+name = "tetramol"
+version = "0.0.1"
+readme = "README.md"  # the PyPI page
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Andreas V. Copan", email = "avcopan@uga.edu"}]
+dependencies = [
+    "automol>=0.0.28",
+    "numpy>=2",
+    "py3dmol>=2.5",
+    "scipy>=1.13",
+    "xyzrender>=0.3.8",
+]
+requires-python = ">= 3.13"
+
+[project.urls]
+Repository = "https://github.com/avcopan/tetramol"
+Documentation = "https://avcopan.github.io/tetramol/"
+
+[build-system]
+build-backend = "uv_build"
+requires = ["uv_build"]
+
+# Ruff configurations
+[tool.ruff]
+extend-exclude = [".claude"]  # vendored agent skills
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "COM812",   # missing trailing comma (handled by format)
+    "TID252",   # relative import
+    "D203",     # conflict: incorrect blank line before class (uses D211 instead)
+    "D213",     # conflict: multi-line summary second line (uses D212 instead)
+    "CPY001",   # copyright notice
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**.py" = ["S101", "PLR2004"]  # assert, magic values
+# Drawing scripts: not a package, and `orient` is imported for interactive use
+"drawings/**.py" = ["INP001", "F401"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+# Ty configurations
+[tool.ty.environment]
+python = ".pixi/envs/test/bin/python"
+
+[tool.ty.src]
+include = [
+    "src",
+    "tests",
+]
+
+# Import-linter configurations
+[tool.importlinter]
+root_package = "tetramol"
+
+[[tool.importlinter.contracts]]
+name = "Module Layering"
+type = "layers"
+layers = [
+    "tetramol.draw",
+    "tetramol.build",
+    "tetramol.grid",
+]
+
+# Pytest configurations
+[tool.pytest.ini_options]
+testpaths = ["tests", "src"]
+addopts = [
+    "--doctest-modules",
+    "--cov=tetramol",
+    "--cov-report=term-missing",
+    "--cov-report=html",
+]
+doctest_optionflags = "NORMALIZE_WHITESPACE"
+
+# Pytest-cov configurations
+[tool.coverage.run]
+branch = true
+source = ["tetramol"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true
+fail_under = 80

tetramol-0.0.1/src/tetramol/__init__.py

@@ -0,0 +1,22 @@
+"""tetramol: idealized molecules on a tetrahedral grid, for illustrations."""
+
+__version__ = "0.0.1"
+
+from . import draw, grid
+from .build import VALENCES, Builder
+from .draw import STYLE, orient, render
+from .grid import TETRAHEDRAL_ANGLE, XH_LENGTH, XY_LENGTH, tetrahedral_basis
+
+__all__ = [
+    "STYLE",
+    "TETRAHEDRAL_ANGLE",
+    "VALENCES",
+    "XH_LENGTH",
+    "XY_LENGTH",
+    "Builder",
+    "draw",
+    "grid",
+    "orient",
+    "render",
+    "tetrahedral_basis",
+]

tetramol-0.0.1/src/tetramol/build.py

@@ -0,0 +1,313 @@
+"""Build idealized molecules on a tetrahedral grid."""
+
+from collections.abc import Collection, Sequence
+
+import numpy as np
+from automol import Geometry, geom
+from automol.utils import element
+from numpy.typing import ArrayLike
+
+from .grid import XH_LENGTH, XY_LENGTH, tetrahedral_basis
+
+VALENCES = {
+    "H": 1,
+    "B": 3,
+    "C": 4,
+    "N": 3,
+    "O": 2,
+    "F": 1,
+    "Si": 4,
+    "P": 3,
+    "S": 2,
+    "Cl": 1,
+    "Br": 1,
+    "I": 1,
+}
+"""Default number of bonds to each element, used by `Builder.add_hydrogens`."""
+
+_CLASH_DISTANCE = 0.5
+
+
+class Builder:
+    """Build a molecule atom by atom on a tetrahedral grid.
+
+    Every atom has four bond slots, one per direction of the
+    `tetrahedral_basis`. Bonded atoms have opposite parities: an atom of parity
+    +1 bonds along the basis directions, and one of parity -1 along their
+    negatives. A child added through slot ``i`` therefore bonds back to its
+    parent through its own slot ``i``. Filling in carbons gives the diamond
+    lattice, and neighboring centers are always staggered.
+
+    Example:
+        A C-N bond pointing up, with a methyl group to the left of the carbon:
+
+        >>> b = Builder(up=(0, 0, 1), left=(-1, 0, 0))
+        >>> c = b.add("C")
+        >>> n = b.add("N", c, toward=(0, 0, 1))
+        >>> c2 = b.add("C", c, toward=(-1, 0, 0))
+        >>> b.add_hydrogens()
+        [3, 4, 5, 6, 7, 8, 9]
+        >>> b.geometry().symbols
+        ['C', 'N', 'C', 'H', 'H', 'H', 'H', 'H', 'H', 'H']
+    """
+
+    def __init__(
+        self,
+        up: ArrayLike = (0.0, 0.0, 1.0),
+        left: ArrayLike = (-1.0, 0.0, 0.0),
+        *,
+        xh_length: float = XH_LENGTH,
+        xy_length: float = XY_LENGTH,
+    ) -> None:
+        """Start an empty molecule.
+
+        Args:
+            up: Direction of slot 0 for the first atom (see `tetrahedral_basis`).
+            left: Direction in the plane of slots 0 and 1 for the first atom.
+            xh_length: Bond length to hydrogen, in Angstroms.
+            xy_length: Bond length between heavy atoms, in Angstroms.
+        """
+        self.basis = tetrahedral_basis(up, left)
+        self.xh_length = xh_length
+        self.xy_length = xy_length
+        self.symbols: list[str] = []
+        self.positions: list[np.ndarray] = []
+        self.parities: list[int] = []
+        self.bonds: list[dict[int, int]] = []  # slot -> neighbor, per atom
+        self.parents: list[int | None] = []
+
+    @property
+    def atom_count(self) -> int:
+        """Number of atoms."""
+        return len(self.symbols)
+
+    def slot_direction(self, key: int, slot: int) -> np.ndarray:
+        """Get the unit direction of a slot of an atom.
+
+        Args:
+            key: Atom index.
+            slot: Slot index, from 0 to 3.
+
+        Returns:
+            The direction.
+        """
+        return self.parities[key] * self.basis[slot]
+
+    def open_slots(self, key: int) -> list[int]:
+        """List the empty slots of an atom.
+
+        Args:
+            key: Atom index.
+
+        Returns:
+            The empty slots, in order.
+        """
+        return [s for s in range(4) if s not in self.bonds[key]]
+
+    def add(
+        self,
+        symbol: str,
+        parent: int | None = None,
+        slot: int | None = None,
+        *,
+        toward: ArrayLike | None = None,
+        length: float | None = None,
+    ) -> int:
+        """Add an atom.
+
+        Args:
+            symbol: Atomic symbol.
+            parent: Atom to bond to. Must be `None` for the first atom, which
+                goes at the origin.
+            slot: Slot of `parent` to bond through. If neither this nor
+                `toward` is given, use the first empty slot.
+            toward: Direction to bond in. The empty slot of `parent` closest
+                to this direction is used.
+            length: Bond length. Defaults to `xh_length` for bonds to hydrogen
+                and `xy_length` otherwise.
+
+        Returns:
+            Index of the new atom.
+
+        Raises:
+            ValueError: If the parent, slot, or position is invalid.
+        """
+        symbol = element.symbol(symbol)
+        if parent is None:
+            if self.atom_count:
+                msg = "Only the first atom can be added without a parent."
+                raise ValueError(msg)
+            return self._append(symbol, np.zeros(3), parity=1)
+
+        slot = self._choose_slot(parent, slot, toward)
+        if length is None:
+            has_h = "H" in (symbol, self.symbols[parent])
+            length = self.xh_length if has_h else self.xy_length
+        position = self.positions[parent] + length * self.slot_direction(parent, slot)
+        self._check_clash(position)
+
+        key = self._append(symbol, position, parity=-self.parities[parent])
+        self.parents[key] = parent
+        self.bonds[parent][slot] = key
+        self.bonds[key][slot] = parent
+        return key
+
+    def add_hydrogens(
+        self,
+        keys: Collection[int] | None = None,
+        *,
+        avoid: ArrayLike | None = None,
+    ) -> list[int]:
+        """Fill atoms up to their default valence (see `VALENCES`) with hydrogens.
+
+        Args:
+            keys: Atoms to fill. Defaults to all heavy atoms.
+            avoid: When an atom needs fewer hydrogens than it has empty slots
+                (e.g. an amine nitrogen), leave the slots closest to this
+                direction empty. By default, the last empty slots are left.
+
+        Returns:
+            Indices of the new hydrogens.
+        """
+        if keys is None:
+            keys = [k for k, s in enumerate(self.symbols) if s != "H"]
+
+        added = []
+        for key in keys:
+            count = VALENCES[self.symbols[key]] - len(self.bonds[key])
+            slots = self.open_slots(key)
+            if avoid is not None:
+                slots.sort(key=lambda s: np.dot(self.slot_direction(key, s), avoid))
+            added.extend(self.add("H", key, s) for s in slots[: max(count, 0)])
+        return added
+
+    def geometry(self, *, charge: int = 0, spin: int | None = None) -> Geometry:
+        """Get the geometry.
+
+        Args:
+            charge: Charge.
+            spin: Number of unpaired electrons. Defaults to the lowest spin
+                consistent with the electron count (0 or 1).
+
+        Returns:
+            The geometry.
+        """
+        if spin is None:
+            spin = (sum(map(element.number, self.symbols)) - charge) % 2
+        return Geometry(
+            symbols=self.symbols,
+            coordinates=np.reshape(self.positions, (-1, 3)),
+            charge=charge,
+            spin=spin,
+        )
+
+    def umbrella_image(
+        self,
+        key: int,
+        keys: Sequence[int] | None = None,
+        *,
+        geo: Geometry | None = None,
+        normal: ArrayLike | None = None,
+    ) -> tuple[Geometry, list[int]]:
+        """Add the mirror image of a branch, e.g. to draw an umbrella inversion.
+
+        The branch is reflected through a plane that contains the bond from
+        `key` to its parent, and that is perpendicular to the empty slot of
+        `key` (its lone pair). This swaps the sides of the substituents and
+        the lone pair, as in the inversion of an amine. Both the branch and its
+        image are kept, so one can be faded afterwards.
+
+        Args:
+            key: Center of the branch, e.g. an amine nitrogen.
+            keys: Atoms to reflect. Defaults to everything bonded beyond `key`,
+                away from its parent.
+            geo: Geometry to add the image to, e.g. one that already has other
+                images. Defaults to `geometry()`. Its first atoms must be the
+                builder's.
+            normal: Normal of the mirror plane through `key`, overriding the
+                default.
+
+        Returns:
+            The geometry with the image atoms appended, and their indices.
+
+        Raises:
+            ValueError: If `key` has no parent, or, without `normal`, doesn't
+                have exactly one empty slot.
+        """
+        parent = self.parents[key]
+        if parent is None:
+            msg = f"Atom {key} has no parent, so there is no bond to mirror about."
+            raise ValueError(msg)
+        if normal is None:
+            empty = self.open_slots(key)
+            if len(empty) != 1:
+                msg = (
+                    f"Atom {key} has empty slots {empty}; the mirror plane needs "
+                    "exactly one (or pass `normal`)."
+                )
+                raise ValueError(msg)
+            axis = self.positions[parent] - self.positions[key]
+            axis /= np.linalg.norm(axis)
+            lone_pair = self.slot_direction(key, empty[0])
+            normal = lone_pair - np.dot(lone_pair, axis) * axis
+
+        keys = self._branch(key) if keys is None else list(keys)
+        geo = self.geometry() if geo is None else geo
+        image = geom.reflect(
+            geom.select_atoms(geo, keys), normal, origin=self.positions[key]
+        )
+        image_keys = list(range(geo.atom_count, geo.atom_count + len(keys)))
+        return geom.join([geo, image]), image_keys
+
+    def _branch(self, key: int) -> list[int]:
+        """List the atoms bonded beyond `key`, away from its parent."""
+        seen = {key, self.parents[key]}
+        branch, stack = [], [key]
+        while stack:
+            for nbr in self.bonds[stack.pop()].values():
+                if nbr not in seen:
+                    seen.add(nbr)
+                    branch.append(nbr)
+                    stack.append(nbr)
+        return sorted(branch)
+
+    def _append(self, symbol: str, position: np.ndarray, parity: int) -> int:
+        """Append an atom and return its index."""
+        self.symbols.append(symbol)
+        self.positions.append(position)
+        self.parities.append(parity)
+        self.bonds.append({})
+        self.parents.append(None)
+        return self.atom_count - 1
+
+    def _choose_slot(
+        self, parent: int, slot: int | None, toward: ArrayLike | None
+    ) -> int:
+        """Choose an empty slot of `parent` by index or direction."""
+        if not 0 <= parent < self.atom_count:
+            msg = f"No atom {parent} in a molecule of {self.atom_count} atoms."
+            raise ValueError(msg)
+        if slot is not None and toward is not None:
+            msg = "Give either a slot or a direction (`toward`), not both."
+            raise ValueError(msg)
+
+        open_slots = self.open_slots(parent)
+        if not open_slots:
+            msg = f"Atom {parent} has no empty slots."
+            raise ValueError(msg)
+        if toward is not None:
+            dirs = [self.slot_direction(parent, s) for s in open_slots]
+            return open_slots[int(np.argmax(np.dot(dirs, toward)))]
+        if slot is None:
+            return open_slots[0]
+        if slot not in open_slots:
+            msg = f"Slot {slot} of atom {parent} is not empty (empty: {open_slots})."
+            raise ValueError(msg)
+        return slot
+
+    def _check_clash(self, position: np.ndarray) -> None:
+        """Raise `ValueError` if `position` is on top of an existing atom."""
+        for key, other in enumerate(self.positions):
+            if np.linalg.norm(position - other) < _CLASH_DISTANCE:
+                msg = f"Position {position} is occupied by atom {key}."
+                raise ValueError(msg)

tetramol-0.0.1/src/tetramol/draw.py

@@ -0,0 +1,167 @@
+"""Orient and render geometries as illustrations."""
+
+import json
+import threading
+import webbrowser
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+
+import py3Dmol
+import xyzrender
+from automol import Geometry, geom
+from scipy.spatial.transform import Rotation
+
+STYLE = xyzrender.build_config(
+    "flat",
+    orient=False,
+    atom_scale=3,
+    bond_width=25,
+    bond_color="#000000",
+    atom_stroke_width=3,
+    hy=True,
+    bo=False,
+    fog=False,
+)
+"""House style: flat atoms with black bonds, drawn as oriented (no auto-rotation)."""
+
+
+def render(
+    geo: Geometry,
+    out: str | Path | None = None,
+    *,
+    config: xyzrender.RenderConfig = STYLE,
+) -> xyzrender.SVGResult:
+    """Render a geometry as an SVG, looking down the z axis (x right, y up).
+
+    Args:
+        geo: Geometry.
+        out: Output path. The suffix is replaced with ``.svg``.
+        config: xyzrender configuration.
+
+    Returns:
+        The SVG, which displays inline in Jupyter-like REPLs.
+    """
+    return geom.render_svg(geo, out=out, config=config)
+
+
+def orient(geo: Geometry, *, port: int = 0) -> Rotation:
+    """Rotate a geometry by hand in the browser and get the rotation.
+
+    This opens the geometry in py3Dmol in a web browser. Rotate the molecule
+    with the mouse, then click "Done". The view matches `render`: both look
+    down the z axis with x to the right and y up.
+
+    The rotation is also printed as code, to paste into a drawing script so that
+    it reproduces the orientation without the viewer.
+
+    Args:
+        geo: Geometry.
+        port: Port for the local server behind the page. The default (0) picks a
+            free port.
+
+    Returns:
+        The rotation, to apply with ``automol.geom.rotate(geo, rot)``.
+    """
+    server, result = serve_orient_page(geo, port=port)
+    url = f"http://localhost:{server.server_address[1]}"
+    print(f"Orient the molecule at {url}, then click Done.")  # noqa: T201
+    webbrowser.open(url)
+    try:
+        while not result:
+            threading.Event().wait(0.2)
+    finally:
+        server.shutdown()
+        server.server_close()
+
+    rot = Rotation.from_quat(result[0])
+    quat = ", ".join(f"{x:.6f}" for x in rot.as_quat())
+    print(f"rot = Rotation.from_quat([{quat}])")  # noqa: T201
+    return rot
+
+
+# Browser viewer: py3Dmol can't send data back to Python, so serve the page from
+# a local server, and have it post the view quaternion from 3Dmol.js
+# (`viewer.getView()` -> [x, y, z, zoom, qx, qy, qz, qw]) back when done
+_PAGE = """<!DOCTYPE html>
+<html>
+<head><title>tetramol: orient</title></head>
+<body style="margin: 0; font-family: sans-serif;">
+<div style="padding: 8px; display: flex; gap: 16px; align-items: center;">
+  <button id="done" style="font-size: 1.2em;">Done</button>
+  <span>Rotate with the mouse, then click Done. Quaternion:
+  <code id="quat">0, 0, 0, 1</code></span>
+</div>
+{viewer_html}
+<script>
+$3Dmolpromise.then(function() {{
+  const viewer = viewer_{uniqueid};
+  const quat = () => viewer.getView().slice(4);
+  const show = () => {{
+    document.getElementById("quat").textContent =
+      quat().map((x) => x.toFixed(4)).join(", ");
+  }};
+  viewer.setViewChangeCallback(show);
+  document.getElementById("done").onclick = () => {{
+    fetch("/done", {{method: "POST", body: JSON.stringify(quat())}}).then(() => {{
+      document.body.innerHTML = "<p style='padding: 8px'>Done. Close this tab.</p>";
+    }});
+  }};
+}});
+</script>
+</body>
+</html>
+"""
+
+
+def orient_page(geo: Geometry) -> str:
+    """Make the web page for orienting a geometry in the browser.
+
+    Args:
+        geo: Geometry.
+
+    Returns:
+        HTML for a page with a py3Dmol viewer and a "Done" button, which posts
+        the view quaternion ``[qx, qy, qz, qw]`` as JSON to ``/done``.
+    """
+    view = py3Dmol.view(width="100%", height="90vh")
+    geom.view(geo, view=view)
+    viewer_html = view.write_html()
+    return _PAGE.format(viewer_html=viewer_html, uniqueid=view.uniqueid)
+
+
+def serve_orient_page(
+    geo: Geometry, *, port: int = 0
+) -> tuple[ThreadingHTTPServer, list]:
+    """Serve the orientation page from a local server, in a background thread.
+
+    Args:
+        geo: Geometry.
+        port: Port to serve on. The default (0) picks a free port.
+
+    Returns:
+        The server, and a list that receives the view quaternion when the page
+        posts it. The server shuts itself down after that.
+    """
+    page = orient_page(geo).encode()
+    result: list = []
+
+    class Handler(BaseHTTPRequestHandler):
+        def do_GET(self) -> None:
+            self.send_response(200)
+            self.send_header("Content-Type", "text/html; charset=utf-8")
+            self.end_headers()
+            self.wfile.write(page)
+
+        def do_POST(self) -> None:
+            length = int(self.headers.get("Content-Length", 0))
+            result.append(json.loads(self.rfile.read(length)))
+            self.send_response(200)
+            self.end_headers()
+            threading.Thread(target=self.server.shutdown).start()
+
+        def log_message(self, format: str, *args: object) -> None:  # noqa: A002
+            pass
+
+    server = ThreadingHTTPServer(("localhost", port), Handler)
+    threading.Thread(target=server.serve_forever, daemon=True).start()
+    return server, result

tetramol-0.0.1/src/tetramol/grid.py

@@ -0,0 +1,59 @@
+"""The tetrahedral grid: ideal bond directions, angles, and lengths."""
+
+import numpy as np
+from numpy.typing import ArrayLike
+from scipy.spatial.transform import Rotation
+
+TETRAHEDRAL_ANGLE = float(np.arccos(-1 / 3))
+"""The ideal tetrahedral angle, arccos(-1/3) (about 109.47 degrees), in radians."""
+
+XH_LENGTH = 1.1
+"""Ideal bond length to hydrogen, in Angstroms."""
+
+XY_LENGTH = 1.5
+"""Ideal bond length between heavy atoms, in Angstroms."""
+
+
+def tetrahedral_basis(
+    up: ArrayLike = (0.0, 0.0, 1.0), left: ArrayLike = (-1.0, 0.0, 0.0)
+) -> np.ndarray:
+    """Get the four bond directions of a tetrahedral grid.
+
+    Direction 0 points along `up`. Direction 1 lies in the plane of `up` and
+    `left`, on the side of `left`. Directions 2 and 3 follow by rotating
+    direction 1 about `up` by 120 and 240 degrees (counterclockwise, looking
+    down from the tip of `up`).
+
+    Args:
+        up: Direction 0.
+        left: Direction in the plane of directions 0 and 1. Only its component
+            perpendicular to `up` matters.
+
+    Returns:
+        Unit vectors, one per row, shape ``(4, 3)``. Each pair makes the
+        tetrahedral angle.
+
+    Raises:
+        ValueError: If `up` is zero or `left` is parallel to `up`.
+
+    Example:
+        >>> basis = tetrahedral_basis()
+        >>> basis.round(6).tolist()[:2]
+        [[0.0, 0.0, 1.0], [-0.942809, 0.0, -0.333333]]
+    """
+    up = _unit(up, "up")
+    left = np.asarray(left, dtype=float)
+    side = _unit(left - np.dot(left, up) * up, "left perpendicular to up")
+    v1 = -up / 3 + 2 * np.sqrt(2) / 3 * side
+    rot = Rotation.from_rotvec(2 * np.pi / 3 * up)
+    return np.array([up, v1, rot.apply(v1), rot.inv().apply(v1)])
+
+
+def _unit(vec: ArrayLike, name: str) -> np.ndarray:
+    """Normalize a vector, raising `ValueError` if it is zero."""
+    vec = np.asarray(vec, dtype=float)
+    norm = np.linalg.norm(vec)
+    if np.isclose(norm, 0.0):
+        msg = f"Vector {name} must be non-zero, got {vec}."
+        raise ValueError(msg)
+    return vec / norm