hofmann 0.1.0__tar.gz

hofmann-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT Licence
+
+Copyright (c) 2026 Benjamin J. Morgan
+
+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, sublicence, 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.

hofmann-0.1.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: hofmann
+Version: 0.1.0
+Summary: A modern Python reimagining of the XBS ball-and-stick crystal structure viewer
+Author-email: "Benjamin J. Morgan" <b.j.morgan@bath.ac.uk>
+License: MIT
+Project-URL: Homepage, https://github.com/bjmorgan/hofmann
+Project-URL: Documentation, https://hofmann.readthedocs.io
+Project-URL: Repository, https://github.com/bjmorgan/hofmann
+Project-URL: Issues, https://github.com/bjmorgan/hofmann/issues
+Keywords: crystallography,molecular-visualisation,ball-and-stick,xbs,matplotlib
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: scipy>=1.10
+Provides-Extra: pymatgen
+Requires-Dist: pymatgen>=2024.1.1; extra == "pymatgen"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=2.0; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints>=2.0; extra == "docs"
+Provides-Extra: all
+Requires-Dist: hofmann[dev,docs,pymatgen]; extra == "all"
+Dynamic: license-file
+
+# hofmann
+
+[![CI](https://github.com/bjmorgan/hofmann/actions/workflows/ci.yml/badge.svg)](https://github.com/bjmorgan/hofmann/actions/workflows/ci.yml)
+[![Documentation](https://readthedocs.org/projects/hofmann/badge/?version=latest)](https://hofmann.readthedocs.io/en/latest/)
+
+A modern Python reimagining of Methfessel's [XBS](https://www.ccl.net/cca/software/X-WINDOW/xbs/) ball-and-stick viewer (1995), named after [August Wilhelm von Hofmann](https://en.wikipedia.org/wiki/August_Wilhelm_von_Hofmann) who built the first ball-and-stick molecular models in 1865.
+
+hofmann renders crystal and molecular structures as depth-sorted ball-and-stick images with static, publication-quality vector output (SVG, PDF) via matplotlib.
+
+<p align="center">
+  <img src="docs/_static/llzo.svg" width="480" alt="LLZO garnet with ZrO6 polyhedra rendered with hofmann">
+</p>
+
+## Features
+
+- Static publication-quality output (SVG, PDF, PNG) via matplotlib
+- XBS `.bs` and `.mv` (trajectory) file formats
+- Optional pymatgen `Structure` interoperability
+- Periodic boundary conditions with automatic image expansion
+- Coordination polyhedra with configurable shading and slab clipping
+- Unit cell wireframe rendering
+- Interactive viewer with mouse rotation, zoom, and keyboard controls
+- Orthographic and perspective projection
+
+## Installation
+
+```bash
+pip install hofmann
+```
+
+For pymatgen interoperability:
+
+```bash
+pip install "hofmann[pymatgen]"
+```
+
+### Requirements
+
+- Python 3.11+
+- numpy >= 1.24
+- matplotlib >= 3.7
+- scipy >= 1.10
+- pymatgen >= 2024.1.1 (optional)
+
+## Quick start
+
+### From an XBS file
+
+```python
+from hofmann import StructureScene
+
+scene = StructureScene.from_xbs("structure.bs")
+scene.render_mpl("output.svg")
+```
+
+### From a pymatgen Structure
+
+```python
+from pymatgen.core import Lattice, Structure
+from hofmann import StructureScene, BondSpec
+
+lattice = Lattice.cubic(5.43)
+structure = Structure(
+    lattice, ["Si"] * 8,
+    [[0.0, 0.0, 0.0], [0.5, 0.5, 0.0],
+     [0.5, 0.0, 0.5], [0.0, 0.5, 0.5],
+     [0.25, 0.25, 0.25], [0.75, 0.75, 0.25],
+     [0.75, 0.25, 0.75], [0.25, 0.75, 0.75]],
+)
+
+bonds = [BondSpec(species=("Si", "Si"), min_length=0.0,
+                  max_length=2.8, radius=0.1, colour=0.5)]
+scene = StructureScene.from_pymatgen(structure, bonds, pbc=True)
+scene.render_mpl("si.pdf")
+```
+
+### Controlling the view
+
+```python
+scene.view.look_along([1, 1, 0])   # View along [110]
+scene.view.zoom = 1.5              # Zoom in
+scene.view.perspective = 0.3       # Mild perspective
+scene.render_mpl("rotated.svg")
+```
+
+### Interactive viewer
+
+```python
+view, style = scene.render_mpl_interactive()
+
+# Reuse the adjusted view for static output:
+scene.view = view
+scene.render_mpl("final.svg", style=style)
+```
+
+## Documentation
+
+Full documentation is available at [hofmann.readthedocs.io](https://hofmann.readthedocs.io/), covering:
+
+- [Getting started](https://hofmann.readthedocs.io/en/latest/getting-started.html) -- installation and first renders
+- [User guide](https://hofmann.readthedocs.io/en/latest/user-guide.html) -- views, render styles, bonds, polyhedra, unit cells
+- [Interactive viewer](https://hofmann.readthedocs.io/en/latest/interactive.html) -- mouse and keyboard controls
+- [XBS file format](https://hofmann.readthedocs.io/en/latest/xbs-format.html) -- `.bs` and `.mv` format reference
+- [API reference](https://hofmann.readthedocs.io/en/latest/api.html) -- full autodoc API
+
+## Licence
+
+MIT. See [LICENSE](LICENSE) for details.

hofmann-0.1.0/README.md

@@ -0,0 +1,108 @@
+# hofmann
+
+[![CI](https://github.com/bjmorgan/hofmann/actions/workflows/ci.yml/badge.svg)](https://github.com/bjmorgan/hofmann/actions/workflows/ci.yml)
+[![Documentation](https://readthedocs.org/projects/hofmann/badge/?version=latest)](https://hofmann.readthedocs.io/en/latest/)
+
+A modern Python reimagining of Methfessel's [XBS](https://www.ccl.net/cca/software/X-WINDOW/xbs/) ball-and-stick viewer (1995), named after [August Wilhelm von Hofmann](https://en.wikipedia.org/wiki/August_Wilhelm_von_Hofmann) who built the first ball-and-stick molecular models in 1865.
+
+hofmann renders crystal and molecular structures as depth-sorted ball-and-stick images with static, publication-quality vector output (SVG, PDF) via matplotlib.
+
+<p align="center">
+  <img src="docs/_static/llzo.svg" width="480" alt="LLZO garnet with ZrO6 polyhedra rendered with hofmann">
+</p>
+
+## Features
+
+- Static publication-quality output (SVG, PDF, PNG) via matplotlib
+- XBS `.bs` and `.mv` (trajectory) file formats
+- Optional pymatgen `Structure` interoperability
+- Periodic boundary conditions with automatic image expansion
+- Coordination polyhedra with configurable shading and slab clipping
+- Unit cell wireframe rendering
+- Interactive viewer with mouse rotation, zoom, and keyboard controls
+- Orthographic and perspective projection
+
+## Installation
+
+```bash
+pip install hofmann
+```
+
+For pymatgen interoperability:
+
+```bash
+pip install "hofmann[pymatgen]"
+```
+
+### Requirements
+
+- Python 3.11+
+- numpy >= 1.24
+- matplotlib >= 3.7
+- scipy >= 1.10
+- pymatgen >= 2024.1.1 (optional)
+
+## Quick start
+
+### From an XBS file
+
+```python
+from hofmann import StructureScene
+
+scene = StructureScene.from_xbs("structure.bs")
+scene.render_mpl("output.svg")
+```
+
+### From a pymatgen Structure
+
+```python
+from pymatgen.core import Lattice, Structure
+from hofmann import StructureScene, BondSpec
+
+lattice = Lattice.cubic(5.43)
+structure = Structure(
+    lattice, ["Si"] * 8,
+    [[0.0, 0.0, 0.0], [0.5, 0.5, 0.0],
+     [0.5, 0.0, 0.5], [0.0, 0.5, 0.5],
+     [0.25, 0.25, 0.25], [0.75, 0.75, 0.25],
+     [0.75, 0.25, 0.75], [0.25, 0.75, 0.75]],
+)
+
+bonds = [BondSpec(species=("Si", "Si"), min_length=0.0,
+                  max_length=2.8, radius=0.1, colour=0.5)]
+scene = StructureScene.from_pymatgen(structure, bonds, pbc=True)
+scene.render_mpl("si.pdf")
+```
+
+### Controlling the view
+
+```python
+scene.view.look_along([1, 1, 0])   # View along [110]
+scene.view.zoom = 1.5              # Zoom in
+scene.view.perspective = 0.3       # Mild perspective
+scene.render_mpl("rotated.svg")
+```
+
+### Interactive viewer
+
+```python
+view, style = scene.render_mpl_interactive()
+
+# Reuse the adjusted view for static output:
+scene.view = view
+scene.render_mpl("final.svg", style=style)
+```
+
+## Documentation
+
+Full documentation is available at [hofmann.readthedocs.io](https://hofmann.readthedocs.io/), covering:
+
+- [Getting started](https://hofmann.readthedocs.io/en/latest/getting-started.html) -- installation and first renders
+- [User guide](https://hofmann.readthedocs.io/en/latest/user-guide.html) -- views, render styles, bonds, polyhedra, unit cells
+- [Interactive viewer](https://hofmann.readthedocs.io/en/latest/interactive.html) -- mouse and keyboard controls
+- [XBS file format](https://hofmann.readthedocs.io/en/latest/xbs-format.html) -- `.bs` and `.mv` format reference
+- [API reference](https://hofmann.readthedocs.io/en/latest/api.html) -- full autodoc API
+
+## Licence
+
+MIT. See [LICENSE](LICENSE) for details.

hofmann-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hofmann"
+version = "0.1.0"
+description = "A modern Python reimagining of the XBS ball-and-stick crystal structure viewer"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+authors = [
+    {name = "Benjamin J. Morgan", email = "b.j.morgan@bath.ac.uk"},
+]
+keywords = ["crystallography", "molecular-visualisation", "ball-and-stick", "xbs", "matplotlib"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Chemistry",
+    "Topic :: Scientific/Engineering :: Visualization",
+]
+dependencies = [
+    "numpy>=1.24",
+    "matplotlib>=3.7",
+    "scipy>=1.10",
+]
+
+[project.urls]
+Homepage = "https://github.com/bjmorgan/hofmann"
+Documentation = "https://hofmann.readthedocs.io"
+Repository = "https://github.com/bjmorgan/hofmann"
+Issues = "https://github.com/bjmorgan/hofmann/issues"
+
+[project.optional-dependencies]
+pymatgen = ["pymatgen>=2024.1.1"]
+dev = ["pytest>=7.0", "pytest-cov>=4.0"]
+docs = [
+    "sphinx>=7.0",
+    "sphinx-rtd-theme>=2.0",
+    "sphinx-autodoc-typehints>=2.0",
+]
+all = ["hofmann[pymatgen,dev,docs]"]
+
+[tool.setuptools.package-data]
+hofmann = ["py.typed"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

hofmann-0.1.0/setup.cfg

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

hofmann-0.1.0/src/hofmann/__init__.py

@@ -0,0 +1,65 @@
+"""Hofmann: a modern Python reimagining of the XBS ball-and-stick viewer.
+
+Hofmann renders crystal and molecular structures as ball-and-stick images,
+with static publication-quality output via matplotlib.
+
+Example usage::
+
+    from hofmann import StructureScene
+
+    scene = StructureScene.from_xbs("structure.bs")
+    scene.render_mpl("output.svg")
+"""
+
+from hofmann.bonds import compute_bonds
+from hofmann.polyhedra import compute_polyhedra
+from hofmann.defaults import (
+    COVALENT_RADII,
+    ELEMENT_COLOURS,
+    default_atom_style,
+    default_bond_specs,
+)
+from hofmann.model import (
+    AtomStyle,
+    AxesStyle,
+    Bond,
+    BondSpec,
+    CellEdgeStyle,
+    Colour,
+    Frame,
+    Polyhedron,
+    PolyhedronSpec,
+    RenderStyle,
+    SlabClipMode,
+    StructureScene,
+    ViewState,
+    WidgetCorner,
+    normalise_colour,
+)
+from hofmann.scene import from_pymatgen, from_xbs
+
+__all__ = [
+    "AtomStyle",
+    "AxesStyle",
+    "Bond",
+    "BondSpec",
+    "CellEdgeStyle",
+    "COVALENT_RADII",
+    "Colour",
+    "ELEMENT_COLOURS",
+    "Frame",
+    "Polyhedron",
+    "PolyhedronSpec",
+    "RenderStyle",
+    "SlabClipMode",
+    "StructureScene",
+    "ViewState",
+    "WidgetCorner",
+    "compute_bonds",
+    "compute_polyhedra",
+    "default_atom_style",
+    "default_bond_specs",
+    "from_pymatgen",
+    "from_xbs",
+    "normalise_colour",
+]

hofmann-0.1.0/src/hofmann/bonds.py

@@ -0,0 +1,89 @@
+"""Bond computation from declarative BondSpec rules."""
+
+from fnmatch import fnmatch
+
+import numpy as np
+
+from hofmann.model import Bond, BondSpec
+
+
+def compute_bonds(
+    species: list[str],
+    coords: np.ndarray,
+    bond_specs: list[BondSpec],
+) -> list[Bond]:
+    """Compute bonds for a single frame based on bond specification rules.
+
+    For each pair of atoms (i < j), checks all bond specs in order to
+    find the first matching rule where the interatomic distance falls
+    within ``[min_length, max_length]``.
+
+    Species matching is pre-computed per spec so that the inner loop
+    over atom pairs is a vectorised numpy operation rather than
+    per-pair Python calls.
+
+    Args:
+        species: List of species labels, length ``n_atoms``.
+        coords: Coordinates array of shape ``(n_atoms, 3)``.
+        bond_specs: List of BondSpec rules to apply.
+
+    Returns:
+        List of Bond objects for all detected bonds.
+    """
+    if len(species) == 0 or len(bond_specs) == 0:
+        return []
+
+    coords = np.asarray(coords, dtype=float)
+    n_atoms = len(species)
+
+    # Vectorised pairwise distance matrix.
+    diff = coords[:, np.newaxis, :] - coords[np.newaxis, :, :]
+    dist_matrix = np.linalg.norm(diff, axis=2)
+
+    # Upper-triangle mask: only consider pairs (i < j).
+    upper = np.triu(np.ones((n_atoms, n_atoms), dtype=bool), k=1)
+
+    # Track which pairs have been claimed by an earlier spec.
+    claimed = np.zeros((n_atoms, n_atoms), dtype=bool)
+
+    # Pre-compute unique species for efficient matching.
+    unique_species = list(set(species))
+
+    bonds: list[Bond] = []
+
+    for spec in bond_specs:
+        # Determine which unique species match each side of the spec.
+        sp_a, sp_b = spec.species
+        match_a = {s for s in unique_species
+                   if fnmatch(s, sp_a)}
+        match_b = {s for s in unique_species
+                   if fnmatch(s, sp_b)}
+
+        # Boolean masks: which atoms match side a / side b.
+        mask_a = np.array([s in match_a for s in species])
+        mask_b = np.array([s in match_b for s in species])
+
+        # Species pair mask (symmetric matching): (a[i] & b[j]) | (b[i] & a[j]).
+        pair_mask = (
+            (mask_a[:, np.newaxis] & mask_b[np.newaxis, :])
+            | (mask_b[:, np.newaxis] & mask_a[np.newaxis, :])
+        )
+
+        # Distance filter.
+        dist_ok = (
+            (dist_matrix >= spec.min_length)
+            & (dist_matrix <= spec.max_length)
+        )
+
+        # Combine: upper triangle, species match, distance match, not claimed.
+        hits = upper & pair_mask & dist_ok & ~claimed
+
+        # Extract matching pairs.
+        ii, jj = np.nonzero(hits)
+        if len(ii) > 0:
+            claimed[ii, jj] = True
+            for idx in range(len(ii)):
+                i, j = int(ii[idx]), int(jj[idx])
+                bonds.append(Bond(i, j, float(dist_matrix[i, j]), spec))
+
+    return bonds