vimol 0.1.3__tar.gz → 0.1.6__tar.gz

vimol-0.1.6/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: vimol
+Version: 0.1.6
+Summary: A terminal molecular viewer and editor using the Kitty graphics protocol
+Author: vimol contributors
+License-Expression: MIT
+Keywords: molecular,viewer,editor,terminal,kitty,chemistry,visualization,xyz,pdb,sdf,cli,tui
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Topic :: Multimedia :: Graphics :: Viewers
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Requires-Dist: moderngl>=5.6
+Requires-Dist: numba>=0.59
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Provides-Extra: align
+Requires-Dist: scipy>=1.4; extra == "align"
+Dynamic: license-file
+
+# vimol
+
+A molecular viewer and editor that runs **in your terminal**. Open an `.xyz`,
+`.pdb`, `.mol` or `.sdf` file and get a shaded, rotatable, editable 3D
+structure right where you are already working — over SSH, in tmux, beside your
+editor.
+
+```bash
+pip install vimol
+vimol molecule.xyz
+```
+
+![C60 spinning in the terminal, rendered by vimol](https://raw.githubusercontent.com/hanimustafa/vimol/main/docs/media/spin.gif)
+
+That is the C60 bundled with vimol, which `vimol` opens with no arguments.
+Drag to rotate, scroll to zoom, option-drag empty space to pan, hover an atom
+to identify it, `?` for every binding.
+
+You need Python 3.8 or newer and a terminal that speaks the
+[Kitty graphics protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol/) —
+**kitty, Ghostty or WezTerm**. Rendering is pure software, with an OpenGL path
+used automatically where a GPU is available. MIT licensed.
+
+## Proteins out of bare coordinates
+
+![vimol opening a bare xyz protein and switching to the lettered residue view](https://raw.githubusercontent.com/hanimustafa/vimol/main/docs/media/protein.gif)
+
+An `.xyz` file has no residue names, no atom names and no chains. vimol finds
+the backbone anyway, opens the file as a ribbon, and on `6` letters every
+residue onto it. The trp-cage above is PDB 1RIJ stripped to bare coordinates,
+which vimol reads back as `ALQELLGQWLKDGGPSSGRPPPS` — character for character
+the sequence in that entry.
+
+## Overlays and RMSD
+
+![vimol overlaying 72 CREST conformers on a reference structure and reporting each RMSD](https://raw.githubusercontent.com/hanimustafa/vimol/main/docs/media/align.gif)
+
+Open several files, or a trajectory, and every structure lands in one session,
+overlaid and colour-coded down the left. `r` aligns the whole overlay onto the
+active structure and reports each RMSD in a column beside the list — above, a
+chignolin crystal structure and 72 CREST conformers of it. `R` runs the same
+fit on only the atoms you pick.
+
+## Editing
+
+![vimol growing a methyl group onto threonine's side-chain hydroxyl](https://raw.githubusercontent.com/hanimustafa/vimol/main/docs/media/methyl.gif)
+
+Editing is on by default. Click a hydrogen to grow a fragment in its place, a
+heavy atom to swap the element, empty space to start something new — one click
+turns threonine into O-methylthreonine. Bonds, deletion, clash cleanup, undo
+and save are a keystroke each.
+
+## As a library
+
+![a C60 painted into the middle of a terminal by three lines of vimol](https://raw.githubusercontent.com/hanimustafa/vimol/main/docs/media/library.png)
+
+Three lines put a molecule anywhere on the screen:
+
+```python
+import os, vimol
+
+scene = vimol.Scene(vimol.load("c60.xyz"), 640, 380)   # render it off-screen
+scene.style.transparent = True                         # let the terminal through
+os.write(1, b"\x1b[6;19H" + scene.to_kitty())          # paint at row 6, col 19
+```
+
+`scene.render()` hands you the pixels as a numpy array instead and
+`scene.to_png()` writes a file. To let the reader turn the molecule,
+`MoleculeWidget` takes the input events you hand it and leaves the loop to you;
+`examples/embed_demo.py` is a complete host application built that way.
+
+## Reference
+
+| Key | Does |
+|---|---|
+| Drag / arrows / `hjkl` | rotate |
+| Wheel, `+` `-` | zoom |
+| Right or middle drag | pan |
+| `[` `]` | roll |
+| `1` `2` `3` `4` | ball-and-stick, space-filling, licorice, wireframe |
+| `5` `6` | ribbon, lettered residues (proteins) |
+| `f` `z` | re-fit, reset the view |
+| `m` | measure — click 2, 3 or 4 atoms for distance, angle, dihedral |
+| `a` `x` `c` `u` `s` | append, delete, cleanup clashes, undo, save |
+| `r` `R` | align an overlay, or align on picked atoms |
+| `Shift+S` | ready-made selections: backbone, heavy atoms, ring system |
+| `A` `n` `p` | add a file, next and previous structure |
+| `Tab` | focus the structure list |
+| `d` `g` `t` `ctrl-t` | depth cue, hi-quality, transparent background, theme |
+| `?` `q` | help, quit |
+
+```bash
+vimol traj.xyz --spin --style spacefill   # spin a trajectory, space-filling
+vimol protein.pdb --style glyph           # lettered residues on a ribbon
+vimol a.xyz b.pdb --style ribbon          # overlay two proteins
+```
+
+Several files always open in ball-and-stick, so pass `--style ribbon` for
+proteins. Also `--backend cpu|gl|auto`, `--theme dark|light|auto`,
+`--rotate YAW PITCH`, `--frame N`, `--background`,
+`--transparent`/`--opaque`, `--atom-scale`, `--bond-radius`,
+`--no-depth-cue`, `--no-bonds`, `--bond-tolerance`, `--list-formats`.
+`pip install vimol[align]` adds scipy, which speeds up subset alignment.
+
+The protein, alignment and editing animations are recorded by
+`scripts/record_demos.py`.

vimol-0.1.6/README.md

@@ -0,0 +1,106 @@
+# vimol
+
+A molecular viewer and editor that runs **in your terminal**. Open an `.xyz`,
+`.pdb`, `.mol` or `.sdf` file and get a shaded, rotatable, editable 3D
+structure right where you are already working — over SSH, in tmux, beside your
+editor.
+
+```bash
+pip install vimol
+vimol molecule.xyz
+```
+
+![C60 spinning in the terminal, rendered by vimol](https://raw.githubusercontent.com/hanimustafa/vimol/main/docs/media/spin.gif)
+
+That is the C60 bundled with vimol, which `vimol` opens with no arguments.
+Drag to rotate, scroll to zoom, option-drag empty space to pan, hover an atom
+to identify it, `?` for every binding.
+
+You need Python 3.8 or newer and a terminal that speaks the
+[Kitty graphics protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol/) —
+**kitty, Ghostty or WezTerm**. Rendering is pure software, with an OpenGL path
+used automatically where a GPU is available. MIT licensed.
+
+## Proteins out of bare coordinates
+
+![vimol opening a bare xyz protein and switching to the lettered residue view](https://raw.githubusercontent.com/hanimustafa/vimol/main/docs/media/protein.gif)
+
+An `.xyz` file has no residue names, no atom names and no chains. vimol finds
+the backbone anyway, opens the file as a ribbon, and on `6` letters every
+residue onto it. The trp-cage above is PDB 1RIJ stripped to bare coordinates,
+which vimol reads back as `ALQELLGQWLKDGGPSSGRPPPS` — character for character
+the sequence in that entry.
+
+## Overlays and RMSD
+
+![vimol overlaying 72 CREST conformers on a reference structure and reporting each RMSD](https://raw.githubusercontent.com/hanimustafa/vimol/main/docs/media/align.gif)
+
+Open several files, or a trajectory, and every structure lands in one session,
+overlaid and colour-coded down the left. `r` aligns the whole overlay onto the
+active structure and reports each RMSD in a column beside the list — above, a
+chignolin crystal structure and 72 CREST conformers of it. `R` runs the same
+fit on only the atoms you pick.
+
+## Editing
+
+![vimol growing a methyl group onto threonine's side-chain hydroxyl](https://raw.githubusercontent.com/hanimustafa/vimol/main/docs/media/methyl.gif)
+
+Editing is on by default. Click a hydrogen to grow a fragment in its place, a
+heavy atom to swap the element, empty space to start something new — one click
+turns threonine into O-methylthreonine. Bonds, deletion, clash cleanup, undo
+and save are a keystroke each.
+
+## As a library
+
+![a C60 painted into the middle of a terminal by three lines of vimol](https://raw.githubusercontent.com/hanimustafa/vimol/main/docs/media/library.png)
+
+Three lines put a molecule anywhere on the screen:
+
+```python
+import os, vimol
+
+scene = vimol.Scene(vimol.load("c60.xyz"), 640, 380)   # render it off-screen
+scene.style.transparent = True                         # let the terminal through
+os.write(1, b"\x1b[6;19H" + scene.to_kitty())          # paint at row 6, col 19
+```
+
+`scene.render()` hands you the pixels as a numpy array instead and
+`scene.to_png()` writes a file. To let the reader turn the molecule,
+`MoleculeWidget` takes the input events you hand it and leaves the loop to you;
+`examples/embed_demo.py` is a complete host application built that way.
+
+## Reference
+
+| Key | Does |
+|---|---|
+| Drag / arrows / `hjkl` | rotate |
+| Wheel, `+` `-` | zoom |
+| Right or middle drag | pan |
+| `[` `]` | roll |
+| `1` `2` `3` `4` | ball-and-stick, space-filling, licorice, wireframe |
+| `5` `6` | ribbon, lettered residues (proteins) |
+| `f` `z` | re-fit, reset the view |
+| `m` | measure — click 2, 3 or 4 atoms for distance, angle, dihedral |
+| `a` `x` `c` `u` `s` | append, delete, cleanup clashes, undo, save |
+| `r` `R` | align an overlay, or align on picked atoms |
+| `Shift+S` | ready-made selections: backbone, heavy atoms, ring system |
+| `A` `n` `p` | add a file, next and previous structure |
+| `Tab` | focus the structure list |
+| `d` `g` `t` `ctrl-t` | depth cue, hi-quality, transparent background, theme |
+| `?` `q` | help, quit |
+
+```bash
+vimol traj.xyz --spin --style spacefill   # spin a trajectory, space-filling
+vimol protein.pdb --style glyph           # lettered residues on a ribbon
+vimol a.xyz b.pdb --style ribbon          # overlay two proteins
+```
+
+Several files always open in ball-and-stick, so pass `--style ribbon` for
+proteins. Also `--backend cpu|gl|auto`, `--theme dark|light|auto`,
+`--rotate YAW PITCH`, `--frame N`, `--background`,
+`--transparent`/`--opaque`, `--atom-scale`, `--bond-radius`,
+`--no-depth-cue`, `--no-bonds`, `--bond-tolerance`, `--list-formats`.
+`pip install vimol[align]` adds scipy, which speeds up subset alignment.
+
+The protein, alignment and editing animations are recorded by
+`scripts/record_demos.py`.

{vimol-0.1.3 → vimol-0.1.6}/src/vimol/__init__.py

@@ -36,7 +36,7 @@ from . import select
 from .structures import StructureSet, Structure, Transform, AlignmentResult
 from .align import kabsch, superpose, permutation_search, subset_search
 
-__version__ = "0.1.3"
+__version__ = "0.1.6"
 
 __all__ = [
     "Molecule", "VectorField", "Camera", "Renderer", "Style", "Scene", "MoleculeWidget",

vimol-0.1.6/src/vimol/cistrans.py

@@ -0,0 +1,266 @@
+"""Cis/trans classification of peptide and peptoid backbone bonds.
+
+A peptide bond's rotation is described by the omega dihedral,
+``Cα(i)-C(i)-N(i+1)-Cα(i+1)``: near 0° it is cis, near 180° trans. This is
+the same walk :func:`vimol.select.peptide_motifs` already builds for the
+ribbon/RMSD backbone presets, and it does not depend on where a residue's
+side chain attaches -- a peptoid's N-substituted backbone (no amide H) is
+the same N-Cα-C path a peptide's is, so no separate peptoid handling is
+needed here.
+"""
+from __future__ import annotations
+
+import math
+import re
+from typing import List, Optional, Sequence, Tuple
+
+from .editor import measure_value
+from .molecule import Molecule
+# The private variant: classification needs the bond graph alongside the
+# runs to notice a cyclic backbone's ring-closing peptide bond, which the
+# public runs-only view cannot express.
+from .select import _peptide_motifs, ring_systems
+
+# |omega| below this is cis, at or above it is trans -- the standard
+# literature convention, and a strict binary split with no third bucket.
+_CIS_MAX_ABS_OMEGA = 90.0
+
+# A ring system at least this big, carrying amides, makes the molecule a
+# macrocycle: a cyclic peptide/peptoid, where the ring's own amides are the
+# conformational question and the exocyclic tail is noise. Twelve is the
+# usual line between an ordinary ring and a macrocycle, and it sits well
+# clear of proline's pyrrolidine (5) and of the 6-membered diketopiperazine
+# that a cyclic dipeptide forms -- both of which stay on the linear path,
+# where the head-to-tail closure already handles them.
+_MACROCYCLE_MIN_ATOMS = 12
+
+# Boltzmann population of each classification across a multi-frame file,
+# weighted by the energy in each frame's XYZ comment line. Energies are
+# always read as Hartree (the convention CREST/xtb/ORCA write when the
+# comment is a bare or labeled electronic energy) -- there is deliberately
+# no unit auto-detection: a silently wrong unit produces a distribution that
+# still looks plausible (collapsed onto one conformer, or smeared flat),
+# so getting it wrong is worse than not offering the feature at all.
+TEMPERATURE_K = 298.15
+_KB_HARTREE_PER_K = 3.166811563e-6
+_KT_HARTREE = _KB_HARTREE_PER_K * TEMPERATURE_K
+
+# A bare float is CREST's own convention (the whole comment IS the energy).
+_BARE_FLOAT_RE = re.compile(r"^[+-]?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?$")
+# "energy", "energy:", "energy=", "E", "E=" ... followed by the number --
+# the xtb/ORCA-style labeled convention.
+_LABELED_ENERGY_RE = re.compile(
+    r"(?:^|\s)(?:energy|e)\s*[:=]?\s*([+-]?\d+\.\d+(?:[eE][+-]?\d+)?)",
+    re.IGNORECASE)
+# Fallback: a decimal-point number anywhere in the comment (excludes bare
+# integers like a model/frame index, which a comment often also carries).
+_DECIMAL_RE = re.compile(r"[+-]?\d+\.\d+(?:[eE][+-]?\d+)?")
+
+
+def parse_energy(comment: str) -> Optional[float]:
+    """Pull one energy value out of an XYZ comment line, or ``None``.
+
+    Three conventions, tried in order of confidence: the whole comment is
+    the number (CREST); a label ("energy"/"E", "=" or ":" optional)
+    precedes it (xtb, ORCA); or exactly one decimal number appears
+    anywhere in the comment. Two or more equally plausible numbers with no
+    label to disambiguate them is not a confident read -- ``None``, same
+    as a comment with no number at all.
+    """
+    text = comment.strip()
+    if not text:
+        return None
+    if _BARE_FLOAT_RE.match(text):
+        return float(text)
+    labeled = _LABELED_ENERGY_RE.search(text)
+    if labeled:
+        return float(labeled.group(1))
+    decimals = _DECIMAL_RE.findall(text)
+    if len(decimals) == 1:
+        return float(decimals[0])
+    return None
+
+
+def boltzmann_breakdown(classifications: Sequence[str],
+                        energies_hartree: Sequence[float],
+                        min_pct: float = 1.0) -> List[Tuple[str, float]]:
+    """Boltzmann-weighted population of each distinct classification string.
+
+    ``classifications`` and ``energies_hartree`` are parallel, one pair per
+    frame -- every frame must already have a real (non-``None``)
+    classification and energy; filtering that is the caller's job, not
+    this function's. Weights are relative to the group's own minimum
+    energy (numerically stable, and the group's reference point is the
+    only one that matters for population *within* the group). Returns
+    ``(classification, percentage)`` pairs, rounded to nothing here (the
+    caller rounds for display), sorted by descending population, with
+    anything under ``min_pct`` dropped -- population that round to 100%
+    across the survivors is not guaranteed, by design.
+    """
+    if not classifications or len(classifications) != len(energies_hartree):
+        return []
+    e_min = min(energies_hartree)
+    weights = [math.exp(-(e - e_min) / _KT_HARTREE) for e in energies_hartree]
+    total = sum(weights)
+    populations: dict = {}
+    for cls, w in zip(classifications, weights):
+        populations[cls] = populations.get(cls, 0.0) + w
+    breakdown = [(cls, 100.0 * w / total) for cls, w in populations.items()]
+    breakdown = [item for item in breakdown if item[1] >= min_pct]
+    breakdown.sort(key=lambda item: item[1], reverse=True)
+    return breakdown
+
+
+def _amide_ring_systems(molecule: Molecule, neighbors, symbols, carbonyls):
+    """Macrocyclic ring systems, each with the amide C-N bonds inside it.
+
+    Returns ``[(ring_atoms, [(carbonyl_C, amide_N), ...]), ...]``, only for
+    systems of at least :data:`_MACROCYCLE_MIN_ATOMS` atoms that actually
+    carry an amide. The size test alone is not enough: a steroid or a
+    porphyrin is a big ring system with no amide in it, and restricting a
+    peptide's classification to one of those would report nothing at all.
+
+    Built from the ``neighbors`` the motif walk already returned, so a
+    frame is never bond-perceived twice -- this runs over every frame of a
+    multi-thousand-frame ensemble on one keypress.
+    """
+    systems = []
+    for ring in ring_systems(neighbors):
+        if len(ring) < _MACROCYCLE_MIN_ATOMS:
+            continue
+        inside = set(ring)
+        amides = []
+        for carbon in ring:
+            # The motif walk's own carbonyl verdict, not a second opinion:
+            # a rule of "terminal oxygen" would also accept a hydroxyl and
+            # read hydrogen-free threonine's C-OH as an amide.
+            if carbon not in carbonyls:
+                continue
+            amides.extend((carbon, n) for n in neighbors[carbon]
+                          if symbols[n] == "N" and n in inside)
+        if amides:
+            systems.append((inside, amides))
+    return systems
+
+
+def _ring_omega_atoms(carbon: int, nitrogen: int, ring, neighbors):
+    """The two Cα-side atoms of a ring amide no motif pair describes.
+
+    Each is the bond partner's *other* neighbour inside the ring. Ambiguity
+    is refused rather than guessed: in a proline fused into a macrocycle the
+    nitrogen has two ring neighbours (Cα and Cδ), and picking Cδ would flip
+    c and t on exactly the residue whose cis state people care about. Those
+    bonds are motif pairs anyway, and are classified as such before this is
+    ever reached.
+
+    KNOWN GAP: refusing drops that amide from the string entirely, which is
+    the same silent class-merge that including the lactam exists to
+    prevent. Reaching it needs a non-motif amide sitting at a ring fusion
+    point, which nothing seen so far does -- but a third state would be
+    honester than omission if something ever gets there.
+    """
+    carbon_side = [x for x in neighbors[carbon] if x in ring and x != nitrogen]
+    nitrogen_side = [x for x in neighbors[nitrogen] if x in ring and x != carbon]
+    if len(carbon_side) != 1 or len(nitrogen_side) != 1:
+        return None
+    return carbon_side[0], nitrogen_side[0]
+
+
+def classify_cis_trans(molecule: Molecule) -> Optional[str]:
+    """One ``c``/``t`` character per peptide bond, chain by chain.
+
+    A linear chain of N residues yields N-1 characters, one per
+    Cα(i)-C(i)-N(i+1) junction; a *cyclic* chain yields N, the extra one
+    for the ring-closing bond back from the last residue's carbonyl to the
+    first residue's nitrogen -- omitting it would silently merge cyclic
+    conformers that differ only in that omega. Multiple chains (a real
+    chain break, not just a gap in the file) join with ``/``, in the order
+    the motif walk returns them. A chain of a single residue has no
+    peptide bond to classify and is dropped; ``None`` means nothing in the
+    molecule survived that filter.
+
+    A MACROCYCLE is classified on its ring alone (see
+    :data:`_MACROCYCLE_MIN_ATOMS`). In a cyclic peptide it is the ring's
+    amides that are the conformational question; a pendant tail's omegas
+    are a separate, largely independent story, and letting them into the
+    same string makes every Boltzmann class a product of the two. The ring
+    string covers every amide in the ring, including a side-chain lactam
+    that no backbone walk passes through -- that bond closes the ring, and
+    dropping it would merge conformers differing only there.
+    """
+    runs, neighbors, symbols, carbonyls = _peptide_motifs(molecule)
+
+    def omega_char(ca_i: int, c_i: int, n_j: int, ca_j: int) -> str:
+        omega = measure_value(molecule, (ca_i, c_i, n_j, ca_j))
+        return ("c" if omega is not None and abs(omega) < _CIS_MAX_ABS_OMEGA
+                else "t")
+
+    macrocycles = _amide_ring_systems(molecule, neighbors, symbols, carbonyls)
+    if macrocycles:
+        chains = []
+        for ring, amides in macrocycles:
+            # Motif pairs first, in backbone order -- they carry real Cα
+            # atoms, and their order is the one a chemist reads the ring
+            # in. Whatever is left (a lactam) follows by atom index. The
+            # order must come from topology alone: rotating the string to
+            # some "canonical" start chosen by its own c/t values would
+            # collapse cttt and tctt into one Boltzmann class.
+            chars, done = [], set()
+            for run in runs:
+                for (_n_i, ca_i, c_i, _o_i), (n_j, ca_j, _c_j, _o_j) in zip(run, run[1:]):
+                    if (c_i, n_j) in amides and (c_i, n_j) not in done:
+                        done.add((c_i, n_j))
+                        chars.append(omega_char(ca_i, c_i, n_j, ca_j))
+                if len(run) < 2:
+                    continue
+                first_n, first_ca = run[0][0], run[0][1]
+                last_ca, last_c = run[-1][1], run[-1][2]
+                if (last_c, first_n) in amides and (last_c, first_n) not in done:
+                    done.add((last_c, first_n))
+                    chars.append(omega_char(last_ca, last_c, first_n, first_ca))
+            for carbon, nitrogen in sorted(set(amides) - done):
+                ends = _ring_omega_atoms(carbon, nitrogen, ring, neighbors)
+                if ends is not None:
+                    chars.append(omega_char(ends[0], carbon, nitrogen, ends[1]))
+            if chars:
+                chains.append("".join(chars))
+        if chains:
+            return "/".join(chains)
+
+    chains = []
+    for run in runs:
+        if len(run) < 2:
+            continue
+        chars = [omega_char(ca_i, c_i, n_j, ca_j)
+                 for (_n_i, ca_i, c_i, _o_i), (n_j, ca_j, _c_j, _o_j)
+                 in zip(run, run[1:])]
+        first_n, first_ca = run[0][0], run[0][1]
+        last_ca, last_c = run[-1][1], run[-1][2]
+        if first_n in neighbors[last_c]:
+            chars.append(omega_char(last_ca, last_c, first_n, first_ca))
+        chains.append("".join(chars))
+    if not chains:
+        return None
+    return "/".join(chains)
+
+
+def macrocycle_size(molecule: Molecule) -> Optional[int]:
+    """Atom count of the macrocycle a classification is restricted to, if
+    any -- what the viewer tells the user so a string that got shorter does
+    not read as a regression.
+
+    This counts the fused ring SYSTEM, not a single cycle: a proline in the
+    ring shares its N-Cα bond with the pyrrolidine, so the two fuse and the
+    count runs three past the macrocycle's own size. Hence the viewer says
+    "N ring atoms" and not "N-membered", which would be a claim about a
+    cycle and would be wrong exactly there.
+    """
+    runs, neighbors, symbols, carbonyls = _peptide_motifs(molecule)
+    if not runs:
+        return None
+    systems = _amide_ring_systems(molecule, neighbors, symbols, carbonyls)
+    return max((len(ring) for ring, _amides in systems), default=None)
+
+
+__all__ = ["classify_cis_trans", "macrocycle_size", "parse_energy",
+           "boltzmann_breakdown", "TEMPERATURE_K"]