Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog.

[1.11.0] - 2026-10-23

Added

  • Trajectory.transition_events() returns every transition of an atom between sites, as a TransitionEvents (exported from site_analysis, with TransitionEvent): the frame (from 0) and timestep label at which it is counted in its new site, the earliest frame, and its label, from which it stayed in that site (earlier than its frame only with commitment), the atom index and the sites it left and entered, as integer arrays. Indexing with an integer gives one TransitionEvent; a slice or mask, such as events[events.to_site == k], gives the selected transitions. The events are derived from the stored trajectory, so they agree with it and with site.transitions (#90, #91).

  • Trajectory.geometric_trajectory gives the site each atom was inside at each timestep (Atom.geometric_trajectory for one atom, recorded only with commitment). With commitment this can differ from atoms_trajectory, which holds the committed sites; without commitment the two are the same (#91).

  • Trajectory.geometric_sites and Trajectory.committed_sites give each atom’s current geometric site (the site it is inside) and committed site, as lists (#91).

  • Face (exported from site_analysis), recording the two sites that share a face and its vertex atoms, stored as int (a Face raises TypeError for an index that is not a Python or numpy integer, including a bool); Trajectory.find_shared_faces(structure), Trajectory.shared_faces() and Trajectory.site_adjacency(). Shared faces are the vertex atoms (three or more) two polyhedral sites share under one lattice translation, found by the builder from the reference geometry (aligned when alignment is on) when every vertex atom of every site was mapped from the reference structure by a with_polyhedral_sites definition, and otherwise from the first structure analysed or by find_shared_faces. site_adjacency() returns which sites share a face, as a symmetric boolean scipy.sparse.csr_array indexed by site index. shared_faces() and site_adjacency() raise RuntimeError before the faces are found, and these methods and find_shared_faces raise TypeError for sites that are not polyhedral. find_shared_faces raises ValueError, keeping the earlier result, for sites that coincide, for a site that lies inside another, for a vertex index not less than the number of atoms and for non-finite vertex coordinates (#92).

  • PolyhedralSiteCollection.validate_atom_count(n_atoms) raises ValueError (“Site {index} has vertex index {k}, but the structure has {n} atoms”, naming the first such site in index order) for a polyhedral site with a vertex index not less than the number of atoms. PolyhedralSiteCollection.analyse_structure() (and so Trajectory.analyse_structure(), append_timestep() and trajectory_from_structures()), find_shared_faces(), sites_contain_points() and TrajectoryBuilder.build() (after it creates the atoms) call it (#92).

  • ReferenceBasedSites.mapped_reference_frac_coords() returns the reference fractional coordinates (aligned when alignment is on) of the reference atom mapped to each target atom, with NaN for target atoms that no site uses (#92).

  • PolyhedralSite.fix_triangles(all_frac_coords, lattice_matrix, shared_faces) fixes the triangles that bound a site from a structure, triangulating each face it shares by the face’s atoms alone, as PolyhedralSiteCollection.find_shared_faces() does for every site (#99).

Changed

  • PolyhedralSite now accepts any iterable of vertex indices, and raises ValueError for repeated or negative vertex indices and TypeError (“vertex index must be an integer, got …”) for vertex indices that are not integers, including bool; numpy integers are accepted and stored as Python int. Site.reset_index() now raises ValueError for a negative index (#92).

  • TrajectoryBuilder.build() now finds shared faces of polyhedral sites; for polyhedral sites from the reference workflow it reports duplicate sites as coincident (“Sites i and j coincide”) instead of “Duplicate sites”, raises for a site lying inside another (all its vertex atoms are vertices of the other under one lattice translation), and no longer rejects sites with the same vertex atoms in different periodic images (e.g. cubes in a cell two sites wide) (#92).

  • IndexMapper’s 1:1 mapping violation message now names one target atom and the two reference atoms mapped to it (#92).

  • ReferenceBasedSites (and so TrajectoryBuilder.build()) reports errors in finding and mapping coordination environments in one format: “Failed to find coordination environments for {centre} centres and {species} coordinating atoms: …” and “Failed to map coordination environments for {centre} centres and {species} coordinating atoms: …”, with a list of species joined with “, “. Previously the message said “centers” and showed a list of species in Python’s list format, and the mapping message named only target_species, if given (”… for [‘O’] species: …”). The mapping message now also covers the 1:1 mapping violation across calls (#92).

  • The TypeError that Trajectory raises for mixed site types now names the types (for example “A Trajectory cannot be initialised with mixed Site types: SphericalSite, VoronoiSite”). TrajectoryBuilder.build() raises it after it creates the atoms, so a build with mixed site types and no mobile species reports the missing species first. This replaces build()’s own “Cannot mix site types: …” check, which compared only the first site of each site definition and ran before the atoms were created (#92).

  • TrajectoryBuilder aligns the reference to the target once per build, shared by all reference-based site definitions, instead of once per definition; results are unchanged (#92).

  • Trajectory.analyse_structure() (and so append_timestep() and trajectory_from_structures()) now raises ValueError (“Site {index} has vertex index {k}, but the structure has {n} atoms”) for a structure with fewer atoms than a polyhedral site’s vertex indices need. Previously it raised IndexError only if an atom’s site search reached that site, and otherwise gave no error (#92).

  • ReferenceBasedSites keeps one reference-to-target mapping across its create_polyhedral_sites and create_dynamic_voronoi_sites calls, and so TrajectoryBuilder across a build’s site definitions, and raises ValueError (“1:1 mapping violation”) for a call that conflicts with it (see “Mapping Conflicts” in the reference workflow guide). Previously this passed silently (#92).

  • A new Trajectory resets its atoms and sites, so any trajectories, recent-site histories, committed sites and transition counts they hold from an earlier analysis are cleared. Each atom’s current site and coordinates are unset until the first structure is analysed, so atom.frac_coords is unavailable straight after build(). Previously only each atom’s committed site was cleared. Because the site search ranks candidate sites by their transition counts, reused overlapping sites may now be assigned differently.

  • With commitment, atom.in_site is now always the site the atom is inside in the most recently analysed structure. Previously append_timestep() replaced it with the committed site, which is atom.committed_site. Trajectory.geometric_sites gives in_site for every atom and Trajectory.committed_sites the committed sites.

  • PolyhedralSite and DynamicVoronoiSite now raise ValueError (“reference_center must be three finite numbers, got …”) when created with a reference centre that is not three finite numbers, and keep the reference centre as their own float array. Previously PolyhedralSiteCollection raised ValueError (“reference centre of site {index} must be three finite numbers, …”) for such a polyhedral site, and a dynamic Voronoi site accepted it. SphericalSite now raises its ValueError (“frac_coords must be three finite numbers, got …”) for a non-numeric centre too, which previously raised numpy’s ValueError or TypeError (#102).

  • Polyhedral sites and dynamic Voronoi sites without a reference centre now raise ValueError (“frac_coords must be finite”) for non-finite vertex or reference atom coordinates when they are assigned (PolyhedralSite.assign_vertex_coords(), contains_point() after notify_structure_changed(), and DynamicVoronoiSite.calculate_centre()), as sites with a reference centre do. Previously a polyhedral site raised scipy’s ValueError (“Points cannot contain NaN”) on its first frame and, with numba, contained no atoms on later frames without an error, and a dynamic Voronoi site got a NaN centre (#102).

  • A polyhedral site is now the polyhedron bounded by a fixed set of triangles over its vertices: the convex hull of its vertices, with each face it shares with another site triangulated by a rule that depends only on the face’s atoms, so that both sites give the face the same triangles and face-sharing sites fill the space between them. A point is inside a site when it is inside one of the tetrahedra joining the site’s centre (the mean of its vertex coordinates) to its triangles; the test is the same with and without numba, with identical results. The triangles are fixed when the shared faces are found, from the same coordinates, or, for a site outside a collection that has found them (including a site restored with from_dict()), from the convex hull of its vertices in the first frame it is tested in. Without numba, containment no longer uses the Delaunay tessellation (PolyhedralSite.delaunay still gives it). On the Li6PS5Cl tutorial trajectory, per-frame analysis takes about the same time with numba and about 20% less without; finding the shared faces, which now also fixes the triangles, takes about 0.1 s longer for its 1056 sites, once per trajectory (#99).

  • PolyhedralSiteCollection.analyse_structure() (and so Trajectory.analyse_structure(), append_timestep() and trajectory_from_structures()) and PolyhedralSiteCollection.sites_contain_points() now find the shared faces, and fix the triangles, from the structure if none have been found, and raise the errors find_shared_faces() raises (#99).

  • find_shared_faces() warns (UserWarning) when the faces it finds differ from those found before, with the numbers of faces added and removed, and replaces them as before (#99).

  • Finding the shared faces (in TrajectoryBuilder.build(), find_shared_faces() or on the first analysis) now raises ValueError, naming the two sites, for shared atoms that cannot be triangulated identically on both sites (“cannot be triangulated identically”): three shared atoms that are not a triangle of the site’s convex hull, atoms that are part of a larger face, or a face of four or more atoms whose atoms, ordered by angle around their best-fit plane, do not follow the face’s outline on the hull. It raises RuntimeError, naming the site, for a site whose vertices are degenerate or whose triangles do not enclose its centre, as when the fan of a strongly bent shared face folds through the centre of a thin site. Overlapping polyhedral sites are not supported: sites that interpenetrate may raise one of these errors, or may be analysed with an atom inside both going to the first site tested (#99).

  • Containment raises RuntimeError (“polyhedron is too distorted for its triangles to enclose its centre”, naming the site and its vertex atoms) when a polyhedral site is tested in a frame in which its centre is not strictly on the inner side of every triangle’s plane (#99).

  • PolyhedralSite.contains_point() now raises ValueError (“point must be three finite numbers”) for a point that is not three finite numbers, with and without numba, and accepts the point as a list or tuple as well as an array. Previously a non-finite point returned False, and with numba a point with two components read past the end of the array and a point with four components ignored the fourth (#99).

  • PolyhedralSite.vertex_coords is now a read-only property: assigning to it raises AttributeError. Use PolyhedralSite.assign_vertex_coords() (#99).

  • Polyhedral site vertex coordinates are now wrapped into the cell before they are unwrapped, so sites without reference centres unwrap from the wrapped coordinates whatever periodic image the input is in (#99).

Deprecated

  • The pbc_images argument of PolyhedralSite.contains_point() and contains_atom() is deprecated and ignored, and issues a DeprecationWarning: the site now tests the images of the point itself, so the result no longer depends on which images a caller passes. It will be removed in version 2.0 (#102).

  • Trajectory.atom_sites is deprecated in favour of Trajectory.geometric_sites (or Trajectory.committed_sites) and issues a FutureWarning. It keeps its previous values (the committed sites with commitment, otherwise the sites the atoms are inside) and will be removed in version 2.0.

  • Polyhedral and dynamic Voronoi sites without a reference centre are deprecated, and will be removed in version 2.0 with the spread-based unwrapping they use, which gives wrong results without error for sites that span more than half the cell along an axis and in thin or skewed cells, and with the slower polyhedral site search used when any site lacks a reference centre. These issue a FutureWarning at the caller’s line, saying what to use instead; behaviour is otherwise unchanged (#101):

    • PolyhedralSite and DynamicVoronoiSite created without reference_center (usually the position of the site’s central atom);

    • use_reference_centers=False in TrajectoryBuilder.with_polyhedral_sites(), TrajectoryBuilder.with_dynamic_voronoi_sites(), create_trajectory_with_polyhedral_sites(), create_trajectory_with_dynamic_voronoi_sites(), ReferenceBasedSites.create_polyhedral_sites() and ReferenceBasedSites.create_dynamic_voronoi_sites();

    • SiteFactory.create_polyhedral_sites() and SiteFactory.create_dynamic_voronoi_sites() without reference_centers;

    • PolyhedralSite.sites_from_vertex_indices() and DynamicVoronoiSite.sites_from_reference_indices(), which create sites from indices alone, in favour of TrajectoryBuilder (or the site constructors with reference_center);

    • PolyhedralSite.from_dict() and DynamicVoronoiSite.from_dict() for a dict without a reference centre.

    Each call warns once, however many sites it creates.

Removed

  • FaceTopologyCache in site_analysis.polyhedral_site, the helper that cached the triangles of a site’s convex hull for the numba containment test. Containment now uses each site’s fixed triangles (#92, #99).

Fixed

  • mic_distance now raises ValueError, naming the argument, for a point that does not have shape (3,), a lattice matrix that does not have shape (3, 3), a point or lattice matrix that is not finite, and a lattice matrix that is singular, nearly singular or extremely elongated, as paired_mic_distances already did. SphericalSite.contains_point() and contains_atom(), and so the spherical site search and commitment in Trajectory, raise for these inputs. Previously a point with two components or a lattice matrix with two rows gave a plausible but wrong distance with numba (and IndexError without), and a non-finite point or a singular lattice gave NaN, so contains_point() returned False whatever the radius.

  • TrajectoryBuilder.build() no longer reuses the atoms created by a failed build, so a rebuild uses the current mobile species and structure (#92).

  • Polyhedral sites and dynamic Voronoi sites with reference centres now unwrap their vertices (or reference atoms) to the periodic image nearest the centre, exactly in any cell, including strongly skewed ones, and when the centre and the atom coordinates are more than one cell apart (for example a reference structure, or a target frame, with fractional coordinates outside the unit cell, with alignment off); previously some vertices were unwrapped to the wrong image, so polyhedral sites could miss atoms and shared faces, and dynamic Voronoi site centres could be wrong. The vertex coordinates of polyhedral sites, with or without reference centres, are now translated by whole cells so that their lowest coordinate is in [0, 1) on every frame. Where two or more images are equally near the centre, the same one is kept whichever periodic image the vertex is given in; previously the first of the 27 shifts searched was kept. Unwrapping now raises ValueError for vertex coordinates that are not shaped (N, 3) or not finite, a reference centre that is not three finite numbers, a vertex 2**52 cells or more from the centre, and a lattice matrix that is not a finite (3, 3) matrix or is singular, nearly singular or extremely elongated; previously such input gave wrong or non-finite vertices without an error of its own (#92, #102).

  • Polyhedral sites now contain the points inside them however many cells their unwrapped vertices span, as they can in unreduced or strongly sheared cells, and PolyhedralSite.contains_point() accepts a point in any periodic image. Previously only the point and its images one cell along each positive axis were tested, so atoms in a site whose vertices reach beyond two cells along an axis could be missed, as could points given outside the unit cell. A site whose vertices span more than 1000 cells, counted over the three axes, as a small site can in an extremely skewed or unreduced cell, raises ValueError (“Site N (vertices […]): vertices span … cells along the lattice axes …”) from contains_point(), and so from Trajectory.analyse_structure(), instead of testing them all (#102).

  • Structure alignment (StructureAligner.align(), and so TrajectoryBuilder.with_structure_alignment()) now moves each candidate translation along the minimum-image displacements to the nearest target atoms, exactly in any cell. Previously it used the displacements nearest in fractional coordinates, so in strongly skewed or unreduced cells it could fail to superimpose structures that superimpose, raising ValueError, or return a translation that fits worse than the best (#102).

  • PolyhedralSite.as_dict()/from_dict() and DynamicVoronoiSite.as_dict()/from_dict() now save and restore reference_center; previously a reloaded site had none and fell back to the spread-based unwrapping (#102).

  • Face-sharing polyhedral sites no longer leave gaps (with numba) or overlap (without numba) at bent faces of four or more atoms, and the two backends now agree. Previously, with numba, each site was bounded by the triangles of its own convex hull in the first frame it was tested in, so two sites could split a shared face along different diagonals, leaving a gap between them; without numba, each site was the convex hull of its vertices in each frame (from their Delaunay tessellation), so both sites could contain the space on either side of a shared face that is not flat (#99).

  • PolyhedralSite.vertex_coords, as_dict(), delaunay and centre now always reflect the current frame’s coordinates. Previously they returned the previous frame’s coordinates (or None) after notify_structure_changed() until a containment test (#99).

  • A polyhedral site notified of a frame with non-finite vertex coordinates now raises ValueError on every containment test and every read of vertex_coords until it is given another frame, and coordinates assigned with assign_vertex_coords() after notify_structure_changed() replace the notified ones. Previously the first test raised and later tests used the previous frame’s coordinates, and the notified coordinates replaced the assigned ones on the next test.

  • PolyhedralSite.from_dict() now restores vertex_coords as a float array, so a site restored from a dict that has been through JSON (with list coordinates) can test containment. Previously it raised a numba TypingError or a numpy TypeError.

[1.10.0] - 2026-10-12

Added

  • PeriodicNeighbourIndex (site_analysis.neighbour_search), a KD-tree neighbour search for periodic cells, including non-orthogonal ones. query_within() finds the points within a cutoff of each query point, and query_nearest() finds the nearest point. Its distances are exact minimum-image distances in any cell.

  • site_analysis.distances.paired_mic_distances(), for exact minimum-image distances between given pairs of points. It raises ValueError for non-finite input or a lattice matrix that is singular, nearly so, or extremely elongated (an edge more than 2**50, about 1e15, times the cell’s narrowest perpendicular width), and gives the same distances with and without numba.

Changed

  • Finding coordination environments (get_coordination_indices()), checking reference structures, mapping atoms between structures (IndexMapper, site_index_mapping()), calculating species distances (calculate_species_distances()), and Voronoi and dynamic Voronoi site assignment now use PeriodicNeighbourIndex instead of computing every pairwise distance. Their memory use now scales with the number of atoms rather than its square, and they are much faster for large systems. Results are unchanged, except in thin or strongly skewed cells, where they are now exact (see Fixed).

  • When they search for neighbours, each of these now raises ValueError for non-finite coordinates, coordinates not shaped (N, 3), or a lattice matrix that is singular, extremely elongated, non-finite or not shaped (3, 3). Previously such input could give meaningless results without an error.

  • Spherical site collections, and polyhedral site collections whose sites all have reference centres (the default from TrajectoryBuilder), now check the sites left after an atom’s recent sites and learned transitions in order of the Cartesian minimum-image distance of their centres (for polyhedral sites, their reference centres) from the atom, rather than the fractional distance from the atom’s most recent site, which is approximate for cells that are not cubic. Atoms with no recent site start with this ranking, rather than with the nearest site and its learned transitions. Rankings are computed with PeriodicNeighbourIndex when needed, rather than stored for every site, so their memory no longer scales with the square of the number of sites. Assignment now raises ValueError for a singular or non-finite lattice matrix, or for non-finite coordinates, when an atom’s search reaches this ranking.

  • In these collections, where two or more overlapping sites contain an atom, and none is one of its recent sites or a learned transition destination from its most recent site, the atom now goes to the one whose centre (for polyhedral sites, reference centre) is nearest to it, so assignments can differ from earlier versions. This includes atoms at the first timestep, which have no recent sites. Re-analysing the Li6PS5Cl tutorial trajectory (a cubic cell) with overlapping spherical sites of radius 1.5 Å changes 4.4% of assignments; more may change in cells that are not cubic, where the old ranking was further from the true distances. Assignments to sites that do not overlap are unchanged.

  • Spherical site collections no longer check sites whose centres are further from an atom than the largest site radius, once its recent sites and learned transitions have been checked. Results are unchanged, and assignment is much faster when many atoms are outside every site.

  • SphericalSite.rcut and SphericalSite.frac_coords are now read-only, and a SphericalSite keeps its own copy of the centre, which cannot be changed in place. Code that assigns to rcut or frac_coords, or changes frac_coords in place, must now create a new SphericalSite instead. SphericalSite raises ValueError for a negative or NaN radius, or a centre that is not three finite numbers.

  • construct_neighbouring_sites compares only sites that share a vertex, so for typical structures it takes time linear in the number of sites, instead of comparing every pair of sites.

  • Site collections keep their own copy of the list of sites they are given, so changing that list afterwards no longer changes the collection.

  • PolyhedralSiteCollection raises ValueError for a site whose reference centre is not three finite numbers. Previously, such a centre was accepted.

  • Trajectory.sites is now the site collection’s own list of sites, rather than the list passed in.

  • Minimum-image distances are faster in near-cubic cells, with and without numba: without numba, spherical site assignment takes less than half as long per frame on the Li6PS5Cl tutorial trajectory. Exact distances cost more in elongated, thin or strongly sheared cells, where long pairs need a search: in an orthorhombic 10 x 10 x 200 Å cell, random pairs take about twice as long with numba and ten times as long without. mic_distance() now gives the same distances with and without numba.

  • mic_distance() returns NaN for non-finite coordinates or a lattice matrix that is singular, nearly so, or extremely elongated. Previously, NaN coordinates gave inf with numba and NaN without, and a singular lattice gave a meaningless distance.

  • Structure alignment (TrajectoryBuilder.with_structure_alignment(), used by polyhedral and dynamic Voronoi sites) now finds origin offsets of any size between the reference and target structures, deterministically. It screens the translations that put a reference atom on one chosen target atom, one from each set related by a translational symmetry of the reference’s alignment atoms, and refines those that pass, best fit first. Previously the default optimiser (Nelder-Mead) started from zero and could settle on a wrong alignment, silently placing sites in the wrong positions, when the offset was more than about 1 Å; differential evolution was slow and not reproducible. Alignment now raises ValueError when no translation superimposes the structures; the reference workflow guide explains the causes and what to try. It also raises ValueError if the reference has coincident atoms of an alignment species, and accepts a single alignment species given as a string (in StructureAligner.align() and ReferenceBasedSites). Where the alignment atoms have translational symmetry, any of the equally good translations may be returned; they differ only in which index each site receives. StructureAligner.align() has a new signature: it takes the fractional coordinates and species of both structures and one lattice matrix, and returns the translation and the metrics instead of a translated structure, so code that calls it directly must be updated.

Deprecated

  • The align_metric, align_algorithm, align_minimizer_options and align_tolerance parameters of TrajectoryBuilder.with_structure_alignment(), create_trajectory_with_polyhedral_sites(), create_trajectory_with_dynamic_voronoi_sites() and ReferenceBasedSites have no effect and issue a FutureWarning: delete them from calls. They will be removed in version 2.0. align_metric='max_dist' (case-insensitively) now raises ValueError, since alignment always minimises the RMSD.

Removed

  • site_analysis.distances.all_mic_distances(), which computed the full matrix of minimum-image distances between two sets of points. Use PeriodicNeighbourIndex to find neighbours, or paired_mic_distances() for distances between given pairs of points.

Fixed

  • Minimum-image distances are now exact in any cell: mic_distance(), and through it and PeriodicNeighbourIndex the coordination environments, atom mapping, structure alignment, species distances, Voronoi and spherical site assignment and commitment that use them. Previously only the 27 periodic images nearest in fractional coordinates were checked, which could overestimate distances of at least 1.5 times the cell’s smallest perpendicular width in thin or strongly skewed cells (#84).

  • get_nearest_neighbour_indices() no longer raises when n_coord equals the number of atoms matching vertex_species. Previously, it raised a ValueError from numpy.

  • TrajectoryBuilder.with_min_atom_distance() now raises ValueError for NaN. Previously, NaN silently turned off the close-pair check.

  • site_index_mapping() now returns integer indices when nothing matches species1_filter. Previously, it returned an empty float array, which could not be used as indices.

  • StructureAligner.align() now raises ValueError when species is empty. Previously, the optimisation ran without any atoms to compare and failed with an unrelated error.

  • Site collections built from a generator or other iterator now hold all the sites. Previously, they silently held none.

[1.9.0] - 2026-10-05

Added

  • TransitionTable.normalise_rows() method for converting counts to row-normalised probabilities.

  • Spatial commitment (milestoning) for trajectories, with TrajectoryBuilder.with_commitment() and the commitment_radius argument to Trajectory. With commitment on, an atom moves to a new site only once it is in that site and within the commitment radius of its centre, and Atom.committed_site gives the site each atom is committed to.

  • Spatial commitment guide in documentation.

Changed

  • Minimum Python version bumped from 3.11 to 3.12 (NumPy 2.5 and SciPy 1.18 require Python 3.12).

  • Added Python 3.15 to CI test matrix.

  • Dev dependencies require mypy 2.4, scipy-stubs 1.18.1 and numba 0.68 or later, and mypy reports unused type: ignore comments.

  • Transitions are now recorded only by Trajectory.append_timestep() (and so Trajectory.trajectory_from_structures()), between successive assigned sites in each atom’s trajectory. Trajectory.analyse_structure() and SiteCollection.analyse_structure() now only assign atoms to sites: they no longer record transitions or update the recent-site history that orders the site search. Code that calls SiteCollection.analyse_structure() directly in a loop therefore no longer accumulates transition counts, and where sites overlap its assignments can differ. Previously, direct analyse_structure() calls between appended timesteps recorded transitions against the last appended timestep, so they could add transitions that do not appear in any atom’s trajectory and count the same hop more than once.

Removed

  • site_analysis.trajectory.update_occupation(), an unused module-level function. Use SiteCollection.update_occupation() instead.

  • Trajectory._normalise_counts(). Use TransitionTable.normalise_rows() instead.

Fixed

  • TrajectoryBuilder.with_voronoi_sites() now accepts a single label for all sites, as with_spherical_sites() does; previously each character of a string label was used as the label of one site. A list of labels must have one label per centre, otherwise ValueError is raised.

  • Site.reset(), and so Trajectory.reset(), now also clears Site.points. Previously, points recorded before a reset were kept.

  • Transitions through unassigned timesteps are now counted. An atom that moves from site A to site B via one or more timesteps in which it is not assigned to any site now records one A to B transition; previously none was recorded. For spherical-site and non-space-filling polyhedral-site analyses, transition counts may increase and derived quantities (e.g. Trajectory.transition_probabilities_by_site(), Site.most_frequent_transitions()) may change. Where sites overlap, site assignments (and so occupations, residence times, and transition counts) can also change, because recorded transitions affect the order in which candidate sites are checked.

  • The residence times and transitions tutorial normalises filtered transition counts, so the rows of the tables it shows sum to 1.

[1.8.0] - 2026-03-27

Added

  • TransitionTable.__str__() for formatted text display with auto-detected integer/float formatting.

  • TransitionTable._repr_html_() for automatic HTML table rendering in Jupyter notebooks.

  • Displaying Tables section in the transition tables guide.

Changed

  • Minimum Python version bumped from 3.10 to 3.11 (required by pymatgen-core).

  • Runtime dependency changed from pymatgen to pymatgen-core; full pymatgen moved to dev dependencies.

[1.7.0] - 2026-03-22

Added

  • Site.residence_times() method for computing per-atom consecutive-occupation run lengths from site trajectory data.

  • filter_length parameter for smoothing brief boundary-crossing artefacts before computing run lengths.

  • Trajectory.transition_counts_by_site(), Trajectory.transition_counts_by_label(), Trajectory.transition_probabilities_by_site(), and Trajectory.transition_probabilities_by_label() methods for aggregating per-site transition data.

  • TransitionTable class: a labelled square matrix with .matrix, .get(), .to_dict(), and .reorder() access patterns.

  • TransitionTable exported from top-level site_analysis package.

  • include_edge_runs parameter to control whether runs truncated by trajectory boundaries are included (excluded by default to avoid biasing towards shorter times).

  • TransitionTable.filter() method for filtering transitions by site label.

  • Residence time analysis guide in documentation.

  • site_analysis.distances module providing minimum-image convention distance functions (mic_distance, all_mic_distances, frac_to_cart) with optional numba acceleration, independent of pymatgen.

  • indices_for_species() helper in tools.py replacing structure.indices_from_symbol().

  • Builder validation: TrajectoryBuilder.build() now checks for same-species atom pairs in the reference structure closer than min_atom_distance (default 0.5), catching incorrect Wyckoff positions that produce duplicate sites. Configurable via .with_min_atom_distance().

  • Builder validation: post-build duplicate site detection for polyhedral and dynamic Voronoi sites (rejects sites sharing the same vertex/reference indices).

Changed

  • Pymatgen decoupling (#59): Structure and Lattice objects are now only used at public API boundaries (TrajectoryBuilder, analyse_structure, ReferenceBasedSites, StructureAligner.align). All internal computation operates on numpy arrays and lattice matrices. This is a purely internal refactoring — the public TrajectoryBuilder API is unchanged.

    • Atom.assign_coords() accepts a coordinate array instead of a Structure.

    • correct_pbc() and unwrap_vertices_to_reference_center() accept a lattice matrix instead of a Lattice.

    • assign_site_occupations() accepts a lattice matrix instead of a Structure across all site collection types.

    • SphericalSite.contains_point() and contains_atom() accept a lattice matrix instead of a Lattice.

    • PolyhedralSite.assign_vertex_coords() accepts arrays instead of a Structure.

    • DynamicVoronoiSite.calculate_centre() accepts arrays instead of a Structure.

    • calculate_species_distances(), site_index_mapping(), and get_coordination_indices() accept arrays instead of Structure objects.

    • StructureAligner optimisation loop no longer creates temporary Structure objects per iteration.

    • IndexMapper and CoordinationEnvironmentFinder extract arrays at their boundaries.

    • ReferenceBasedSites eagerly extracts arrays from both structures in its constructor.

  • Site.contains_point() and Site.contains_atom() base class signatures no longer use *args/**kwargs. Subclasses declare concrete keyword-only parameters, so invalid arguments raise TypeError immediately.

  • PriorityAssignmentMixin is now generic over site type (PriorityAssignmentMixin[SiteT]), so _get_priority_sites yields the concrete site type.

  • PolyhedralSite.contains_point() no longer accepts a structure parameter. Use notify_structure_changed() or assign_vertex_coords() to set vertex coordinates before calling.

  • PolyhedralSiteCollection.sites_contain_points() accepts arrays instead of a Structure, with length validation.

Fixed

  • Fixed type 2 (Mg) site Wyckoff position in argyrodite reference structure. The coordinate [0.23, 0.92, 0.09] was on the 96i general position, producing 384 duplicate sites. Replaced with [0.77, 0.585, 0.585] on the 48h special position.

  • Removed stale # type: ignore on scipy import (scipy-stubs now provides types).

  • Removed unused pymatgen imports from polyhedral_site.py, dynamic_voronoi_site.py, site_collection.py, site.py, and index_mapper.py.

  • Fixed get_vertex_indices deprecation warning referencing non-existent get_coordinating_indices (should be get_coordination_indices).

Performance

Benchmarked on Li6PS5Cl argyrodite (1056 sites, 192 mobile Li atoms, 140 MD frames):

Site type

Before (ms/frame)

After (ms/frame)

Speedup

Polyhedral

9.95

7.26

1.37x

Voronoi

7.35

3.28

2.24x

Dynamic Voronoi

7.86

3.59

2.19x

Spherical

4.79

1.70

2.82x

Speedups come from replacing pymatgen’s Cython lattice.get_all_distances with numba-accelerated all_mic_distances, and eliminating per-atom pymatgen PeriodicSite object creation in assign_coords.

[1.6.0] - 2026-03-01

Changed

  • Replaced deprecated tqdm_notebook with tqdm.auto, which auto-detects the environment (terminal, Jupyter notebook, Jupyter lab). The progress parameter on trajectory_from_structures is now a simple boolean.

  • Added PEP 561 py.typed marker for downstream type checking support.

  • Added types-tqdm dev dependency; removed inline # type: ignore on tqdm import.

  • Removed redundant mypy ignores for tqdm, pymatgen, and scipy (now covered by type stubs).

  • Added Python 3.14 to CI test matrix; separated mypy into its own CI job.

Removed

  • Removed progress='notebook' option from trajectory_from_structures (tqdm.auto handles environment detection automatically).

[1.5.0] - 2026-02-28

Changed

  • Extracted shared priority-based site assignment logic into PriorityAssignmentMixin, used by both PolyhedralSiteCollection and SphericalSiteCollection.

  • Improved priority heuristic for both site collections: tracks two recent distinct sites (catches bounce-back) and uses precomputed distance-ranked site ordering instead of neighbour-cutoff-based ordering. ~68% fewer containment checks and ~1.4x wall-clock speedup on argyrodite Li6PS5Cl trajectories.

  • Unified duplicated PBC correction logic into correct_pbc() in pbc_utils, used by both PolyhedralSite and DynamicVoronoiSite.

  • Dissolved containment.py: moved HAS_NUMBA to _compat.py, PBC shift updates to pbc_utils.py, and face topology cache into polyhedral_site.py.

Removed

  • Removed neighbour_cutoff parameter from SphericalSiteCollection (distance-ranked ordering replaces neighbour-based ordering).

  • Removed containment module (internals relocated; no public API change).

[1.4.0] - 2026-02-28

Changed

  • Batch vectorised centre calculation for DynamicVoronoiSite collections, grouped by reference count. After the first frame, incremental PBC shift updates avoid per-site O(27-image) unwrapping (~4x speedup on MD trajectories).

  • SiteCollection now owns site reset via reset(). Trajectory.reset() delegates to site_collection.reset(), ensuring collection-level caches are properly cleared.

[1.3.0] - 2026-02-27

Added

  • Optional Numba acceleration for polyhedral site containment testing (~7x speedup). Install with pip install site-analysis[fast].

Changed

  • Cached face topology with JIT-compiled surface normal queries, replacing per-timestep Delaunay construction.

  • Lazy vertex coordinate assignment defers PBC correction until a site is actually queried.

  • PBC image shift caching avoids the expensive 27-image distance search.

  • Per-atom PBC image computation (x_pbc computed once per atom per frame rather than once per atom-site pair).

  • algo parameter on contains_point/contains_atom is deprecated; algorithm is now selected automatically.

Fixed

  • Fixed use_reference_centers typo in PBC handling documentation.

[1.2.7] - 2026-02-21

Changed

  • Replaced deprecated typing imports (Optional, Union, List, etc.) with built-in equivalents.

  • Replaced defensive assert statements with proper exceptions (ValueError, TypeError, RuntimeError).

  • Standardised indentation to 4 spaces across all source files.

  • Removed redundant object inheritance from Atom and Trajectory.

  • Replaced type-narrowing hacks with annotations.

  • Consolidated lazy initialisation helpers in ReferenceBasedSites.

  • Use public assign_coords() API instead of accessing private Atom._frac_coords.

Fixed

  • Fixed StructureAligner._run_differential_evolution mutating the caller’s minimizer_options dict.

  • Fixed incorrect docstrings (typos, wrong default values, mismatched parameter names).

[1.2.6] - 2026-02-21

Fixed

  • Fixed float distance truncation in get_coordination_indices (neighbour distances were cast to int).

  • Fixed append_timestep dropping timestep t=0 (truthiness check treated 0 as falsy).

  • Fixed transitions from site index 0 not being recorded (truthiness check treated 0 as falsy).

  • Fixed contains_point_sn loop structure (inside.append() was inside the inner face loop).

  • Fixed Atom.from_dict crashing when frac_coords is absent.

  • Removed debug print statement from PolyhedralSite.__init__.

  • Removed dead code and variable shadowing in Trajectory.__init__.

  • Fixed x_pbc docstring (stated (9, 3) return shape; actual shape is (8, 3)).

[1.2.5] - 2026-01-17

Fixed

  • Fixed quickstart example to work out-of-the-box (#31).

  • Added example_data/XDATCAR with a minimal Li trajectory for the quickstart example.

  • Added helpful error message when mobile species is not found in structure.

[1.2.4] - 2025-09-01

Added

  • Trajectory.site_summaries() method returning structured summary statistics for all sites.

  • Trajectory.write_site_summaries(filename) method for exporting summaries to JSON.

  • Optional metrics parameter for selecting specific statistics (occupancy, transitions, etc.).

  • Numpy array inputs for PolyhedralSite.

  • Description label for tqdm progress output.

[1.2.1] - 2025-06-07

Changed

  • Optimised SphericalSiteCollection site assignment using the same priority-based algorithm introduced in 1.2.0, reducing complexity from O(N^2) to O(kN).

  • Configurable neighbour_cutoff parameter (default 10.0 A) for distance-based neighbour determination.

[1.2.0] - 2025-06-07

Added

  • most_frequent_transitions() method on Site class.

Changed

  • Optimised PolyhedralSiteCollection site assignment with a priority-based algorithm leveraging spatial relationships and learned transition patterns. 10x speedup for large systems (1440 sites).

[1.1.3] - 2025-06-06

Fixed

  • Fixed errors in PBC handling documentation.

[1.1.0] - 2025-06-06

Added

  • Reference-centre PBC unwrapping method that correctly handles coordination environments spanning more than half the simulation cell. This is now the default.

  • Previous spread-based method remains available via use_reference_centers=False.

  • PBC concepts documentation.

Fixed

  • Fixed bug in mapping central atom indices to coordination environments.

  • Fixed handling of unwrapped mobile atom coordinates.

[1.0.3] - 2025-06-03

Fixed

  • Fixed ImportError when importing ReferenceBasedSites.

[1.0.1] - 2025-06-03

Fixed

  • Fixed missing reference_workflow subpackage in PyPI distribution.

[1.0.0] - 2025-05-23

First stable release, accompanying the JOSS paper submission.

[0.5.0] - 2025-05-14

Changed

  • Refactored structure alignment for modularity.

  • Added global minimiser option (differential_evolution) for structure alignment.

  • Exposed alignment tolerance parameter in Trajectory Builder and Reference-Based Sites workflows.

  • Added comprehensive documentation.

[0.3.1] - 2025-05-09

Added

  • most_recent_site property on Atom for tracking last known site.

  • O(1) site lookup dictionary in SiteCollection.

Changed

  • Priority-based site checking in PolyhedralSiteCollection and SphericalSiteCollection (check most recent site first).

[0.3.0] - 2025-05-09

Changed

  • TrajectoryBuilder.build() now numbers generated sites from zero.

  • Multiple site definitions (of the same type) supported in a single trajectory.

  • Separated structure alignment from site mapping in the builder API.

  • Intelligent defaults for alignment and mapping species.

[0.2.0] - 2025-05-08

Added

  • Dynamic Voronoi site types.

  • ReferenceBasedSites workflow for generating sites from reference structures.

  • Trajectory builders.

Changed

  • Minimum Python version increased to 3.10.

  • Migrated to pyproject.toml.

[0.0.1] - 2020-04-21

Initial release.