Getting started

Installation

Install hofmann from PyPI:

pip install hofmann

For ASE interoperability (optional):

pip install "hofmann[ase]"

For pymatgen interoperability (optional):

pip install "hofmann[pymatgen]"

For animation export (optional):

pip install "hofmann[animation]"

For development (tests + docs):

pip install "hofmann[all]"

Requirements

Python 3.11+
numpy >= 1.24
matplotlib >= 3.7
scipy >= 1.10
ase >= 3.22 (optional, for from_ase())
pymatgen >= 2024.1.1 (optional, for from_pymatgen())
imageio >= 2.30 (optional, for render_animation())
imageio-ffmpeg >= 0.5 (optional, for MP4 output via render_animation())

Rendering from an XBS file

The XBS .bs file format describes atoms, species styles, and bond rules in a simple text format (see XBS file format).

from hofmann import StructureScene

scene = StructureScene.from_xbs("ch4.bs")
scene.render_mpl("ch4.svg")

The output format is inferred from the file extension: .svg, .pdf, and .png are all supported.

Rendering from ASE

If you have ASE installed, you can build a scene directly from an Atoms object:

from ase.build import bulk
from hofmann import StructureScene, BondSpec

atoms = bulk("Si", "diamond", a=5.43)
bonds = [BondSpec(species=("Si", "Si"), max_length=2.8)]
scene = StructureScene.from_ase(atoms, bonds)
scene.render_mpl("si.pdf")

Both periodic and non-periodic Atoms objects are supported. For periodic systems, fractional coordinates are wrapped into the unit cell automatically. For non-periodic systems (molecules), Cartesian positions are stored directly.

See from_ase() for full details.

Rendering from pymatgen

If you have pymatgen installed, you can build a scene directly from a Structure object:

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"), max_length=2.8)]
scene = StructureScene.from_pymatgen(structure, bonds)
scene.render_mpl("si.pdf")

See from_pymatgen() for full details on periodic boundary condition expansion and polyhedra support. Partial-occupancy and solid-solution sites pass through automatically – see Partial and mixed occupancy.