vimol 0.1.3__tar.gz → 0.1.4__tar.gz

vimol-0.1.4/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: vimol
+Version: 0.1.4
+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.4/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.4}/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.4"
 
 __all__ = [
     "Molecule", "VectorField", "Camera", "Renderer", "Style", "Scene", "MoleculeWidget",

vimol-0.1.4/src/vimol/cistrans.py

@@ -0,0 +1,142 @@
+"""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
+
+# |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
+
+# 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 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.
+    """
+    runs, neighbors, _symbols = _peptide_motifs(molecule)
+    chains = []
+
+    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")
+
+    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)
+
+
+__all__ = ["classify_cis_trans", "parse_energy", "boltzmann_breakdown", "TEMPERATURE_K"]