v0.19.0

AtomData hardening and sparse assignment.

New features:

1. set_atom_data gains by_species and by_index keyword arguments for sparse per-atom metadata assignment. by_species maps species labels to values; by_index maps atom indices. Both can be combined in one call, with by_index taking precedence at overlapping atoms.

2. New select_by_species method filters a full-length per-atom array to keep only selected species, filling the rest with the appropriate missing sentinel.

3. StructureScene.species is now stored as a tuple, fixed at construction.

Breaking changes:

1. set_atom_data no longer accepts a dict as its positional values argument. Use by_index= instead.

2. Missing entries in sparse categorical atom data are now filled with None (object-dtype) instead of empty strings.

3. The AtomData container is no longer re-exported from hofmann or hofmann.model. The only supported way to obtain an instance is via scene.atom_data.

4. The atom_data property now returns a read-only Mapping view. Direct mutation raises TypeError or AttributeError.

5. 2-D atom data shape is now validated against len(scene.frames) at both write and render time.

See the changelog for details.

v0.18.0

Breaking changes:

1. AtomData exposes derived per-key metadata via read-only mapping attributes ranges and labels, replacing the previous global_range() and global_labels() methods. Callers migrate with a direct substitution: ad.global_range(key) becomes ad.ranges[key], and ad.global_labels(key) becomes ad.labels[key].

2. AtomData.__setitem__ rejects unsupported dtypes at assignment time with a clear ValueError. Supported dtypes are bool, integer, float, string, and object.

3. resolve_atom_colours is no longer part of the public API. Colour resolution goes through the StructureScene rendering methods.

See the changelog for details.

v0.17.0

Breaking change: StructureScene.atom_data arrays are now stored read-only. In-place mutation of a returned array (e.g. scene.atom_data["charge"][0] = 99) raises ValueError: assignment destination is read-only instead of silently bypassing shape validation and cache invalidation. Update values by building a new array and reassigning the key.

See the changelog for details.

v0.16.0

New light_direction parameter on RenderStyle controls the virtual light source for polyhedra face shading, specified in screen space. The default preserves existing behaviour; set an off-axis direction for visible face shading from top-down viewing angles.

See the changelog for details.

v0.15.1

Rendering now warns when a species has no AtomStyle. The warning lists all affected species.

See the changelog for details.

v0.15.0

What's new

• Interactive viewer: frame indicator (f), go-to-frame (g),
  set-step (s), and step-aware frame navigation.

• New StructureScene.render_animation() method for exporting
  trajectories as GIF or MP4 animations.

• atom_data is now a validated AtomData container that checks
  array shapes on assignment. It also accepts 2-D arrays of shape
  (n_frames, n_atoms) so that colourmap-based colouring can vary
  per frame in animations and the interactive viewer.

v0.14.2

• Fixed bond completion missing padding image atoms near cell boundaries. Padding atoms now get their full coordination shell, matching physical atoms.

v0.14.1

Bug fix

• Fixed cell edge lines being clipped at atoms that are not drawn. Atoms hidden by PolyhedronSpec.hide_centre, AtomStyle.visible=False, hide_vertices, or slab clipping no longer produce spurious gaps in cell outline edges. (#41)

v0.14.0

What's new

• Breaking: Frame now carries a lattice field (shape (3, 3) or None). The lattice field on StructureScene has been replaced by a read-only property that delegates to frames[0].lattice. Code that constructed a StructureScene with lattice=... should move the lattice onto each Frame instead. This correctly supports NPT (variable-cell) trajectories where the unit cell changes between frames. Rendering functions now resolve the lattice from the current frame, so cell edges, periodic bonds, and axes widgets update per frame.

• New from_ase() constructor and StructureScene.from_ase() classmethod for building scenes directly from ASE Atoms objects, without requiring pymatgen. Supports both periodic and non-periodic systems, single structures and trajectories (list[Atoms] or ase.io.Trajectory), and the same style, bond, polyhedra, and view options as from_pymatgen. ASE is available as an optional dependency: pip install "hofmann[ase]". from_ase() stores the lattice per frame, correctly supporting NPT trajectories where the cell changes between frames.

Install

pip install hofmann==0.14.0

v0.13.1

Documentation figures are now generated at Sphinx build time via a builder-inited hook, rather than being pre-generated and committed to the repository. This ensures figures always reflect the current rendering code.

• pymatgen is now included in the docs optional extra
• Set SKIP_IMAGE_GEN=1 to skip figure generation during rapid local iteration