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 aTransitionEvents(exported fromsite_analysis, withTransitionEvent): 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 oneTransitionEvent; a slice or mask, such asevents[events.to_site == k], gives the selected transitions. The events are derived from the stored trajectory, so they agree with it and withsite.transitions(#90, #91).Trajectory.geometric_trajectorygives the site each atom was inside at each timestep (Atom.geometric_trajectoryfor one atom, recorded only with commitment). With commitment this can differ fromatoms_trajectory, which holds the committed sites; without commitment the two are the same (#91).Trajectory.geometric_sitesandTrajectory.committed_sitesgive each atom’s current geometric site (the site it is inside) and committed site, as lists (#91).Face(exported fromsite_analysis), recording the two sites that share a face and its vertex atoms, stored asint(aFaceraisesTypeErrorfor an index that is not a Python or numpy integer, including abool);Trajectory.find_shared_faces(structure),Trajectory.shared_faces()andTrajectory.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 awith_polyhedral_sitesdefinition, and otherwise from the first structure analysed or byfind_shared_faces.site_adjacency()returns which sites share a face, as a symmetric booleanscipy.sparse.csr_arrayindexed by site index.shared_faces()andsite_adjacency()raiseRuntimeErrorbefore the faces are found, and these methods andfind_shared_facesraiseTypeErrorfor sites that are not polyhedral.find_shared_facesraisesValueError, 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)raisesValueError(“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 soTrajectory.analyse_structure(),append_timestep()andtrajectory_from_structures()),find_shared_faces(),sites_contain_points()andTrajectoryBuilder.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, asPolyhedralSiteCollection.find_shared_faces()does for every site (#99).
Changed
PolyhedralSitenow accepts any iterable of vertex indices, and raisesValueErrorfor repeated or negative vertex indices andTypeError(“vertex index must be an integer, got …”) for vertex indices that are not integers, includingbool; numpy integers are accepted and stored as Pythonint.Site.reset_index()now raisesValueErrorfor 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 soTrajectoryBuilder.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 onlytarget_species, if given (”… for [‘O’] species: …”). The mapping message now also covers the 1:1 mapping violation across calls (#92).The
TypeErrorthatTrajectoryraises 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 replacesbuild()’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).TrajectoryBuilderaligns 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 soappend_timestep()andtrajectory_from_structures()) now raisesValueError(“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 raisedIndexErroronly if an atom’s site search reached that site, and otherwise gave no error (#92).ReferenceBasedSiteskeeps one reference-to-target mapping across itscreate_polyhedral_sitesandcreate_dynamic_voronoi_sitescalls, and soTrajectoryBuilderacross a build’s site definitions, and raisesValueError(“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
Trajectoryresets 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, soatom.frac_coordsis unavailable straight afterbuild(). 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_siteis now always the site the atom is inside in the most recently analysed structure. Previouslyappend_timestep()replaced it with the committed site, which isatom.committed_site.Trajectory.geometric_sitesgivesin_sitefor every atom andTrajectory.committed_sitesthe committed sites.PolyhedralSiteandDynamicVoronoiSitenow raiseValueError(“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. PreviouslyPolyhedralSiteCollectionraisedValueError(“reference centre of site {index} must be three finite numbers, …”) for such a polyhedral site, and a dynamic Voronoi site accepted it.SphericalSitenow raises itsValueError(“frac_coords must be three finite numbers, got …”) for a non-numeric centre too, which previously raised numpy’sValueErrororTypeError(#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()afternotify_structure_changed(), andDynamicVoronoiSite.calculate_centre()), as sites with a reference centre do. Previously a polyhedral site raised scipy’sValueError(“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.delaunaystill 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 soTrajectory.analyse_structure(),append_timestep()andtrajectory_from_structures()) andPolyhedralSiteCollection.sites_contain_points()now find the shared faces, and fix the triangles, from the structure if none have been found, and raise the errorsfind_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 raisesValueError, 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 raisesRuntimeError, 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 raisesValueError(“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 returnedFalse, 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_coordsis now a read-only property: assigning to it raisesAttributeError. UsePolyhedralSite.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_imagesargument ofPolyhedralSite.contains_point()andcontains_atom()is deprecated and ignored, and issues aDeprecationWarning: 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_sitesis deprecated in favour ofTrajectory.geometric_sites(orTrajectory.committed_sites) and issues aFutureWarning. 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
FutureWarningat the caller’s line, saying what to use instead; behaviour is otherwise unchanged (#101):PolyhedralSiteandDynamicVoronoiSitecreated withoutreference_center(usually the position of the site’s central atom);use_reference_centers=FalseinTrajectoryBuilder.with_polyhedral_sites(),TrajectoryBuilder.with_dynamic_voronoi_sites(),create_trajectory_with_polyhedral_sites(),create_trajectory_with_dynamic_voronoi_sites(),ReferenceBasedSites.create_polyhedral_sites()andReferenceBasedSites.create_dynamic_voronoi_sites();SiteFactory.create_polyhedral_sites()andSiteFactory.create_dynamic_voronoi_sites()withoutreference_centers;PolyhedralSite.sites_from_vertex_indices()andDynamicVoronoiSite.sites_from_reference_indices(), which create sites from indices alone, in favour ofTrajectoryBuilder(or the site constructors withreference_center);PolyhedralSite.from_dict()andDynamicVoronoiSite.from_dict()for a dict without a reference centre.
Each call warns once, however many sites it creates.
Removed
FaceTopologyCacheinsite_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_distancenow raisesValueError, 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, aspaired_mic_distancesalready did.SphericalSite.contains_point()andcontains_atom(), and so the spherical site search and commitment inTrajectory, 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 (andIndexErrorwithout), and a non-finite point or a singular lattice gave NaN, socontains_point()returnedFalsewhatever 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
ValueErrorfor 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, raisesValueError(“Site N (vertices […]): vertices span … cells along the lattice axes …”) fromcontains_point(), and so fromTrajectory.analyse_structure(), instead of testing them all (#102).Structure alignment (
StructureAligner.align(), and soTrajectoryBuilder.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, raisingValueError, or return a translation that fits worse than the best (#102).PolyhedralSite.as_dict()/from_dict()andDynamicVoronoiSite.as_dict()/from_dict()now save and restorereference_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(),delaunayandcentrenow always reflect the current frame’s coordinates. Previously they returned the previous frame’s coordinates (or None) afternotify_structure_changed()until a containment test (#99).A polyhedral site notified of a frame with non-finite vertex coordinates now raises
ValueErroron every containment test and every read ofvertex_coordsuntil it is given another frame, and coordinates assigned withassign_vertex_coords()afternotify_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 restoresvertex_coordsas 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 numbaTypingErroror a numpyTypeError.
[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, andquery_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 raisesValueErrorfor 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 usePeriodicNeighbourIndexinstead 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
ValueErrorfor 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 withPeriodicNeighbourIndexwhen needed, rather than stored for every site, so their memory no longer scales with the square of the number of sites. Assignment now raisesValueErrorfor 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.rcutandSphericalSite.frac_coordsare now read-only, and aSphericalSitekeeps its own copy of the centre, which cannot be changed in place. Code that assigns torcutorfrac_coords, or changesfrac_coordsin place, must now create a newSphericalSiteinstead.SphericalSiteraisesValueErrorfor a negative or NaN radius, or a centre that is not three finite numbers.construct_neighbouring_sitescompares 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.
PolyhedralSiteCollectionraisesValueErrorfor a site whose reference centre is not three finite numbers. Previously, such a centre was accepted.Trajectory.sitesis 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 raisesValueErrorwhen no translation superimposes the structures; the reference workflow guide explains the causes and what to try. It also raisesValueErrorif the reference has coincident atoms of an alignment species, and accepts a single alignment species given as a string (inStructureAligner.align()andReferenceBasedSites). 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_optionsandalign_toleranceparameters ofTrajectoryBuilder.with_structure_alignment(),create_trajectory_with_polyhedral_sites(),create_trajectory_with_dynamic_voronoi_sites()andReferenceBasedSiteshave no effect and issue aFutureWarning: delete them from calls. They will be removed in version 2.0.align_metric='max_dist'(case-insensitively) now raisesValueError, 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. UsePeriodicNeighbourIndexto find neighbours, orpaired_mic_distances()for distances between given pairs of points.
Fixed
Minimum-image distances are now exact in any cell:
mic_distance(), and through it andPeriodicNeighbourIndexthe 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 whenn_coordequals the number of atoms matchingvertex_species. Previously, it raised aValueErrorfrom numpy.TrajectoryBuilder.with_min_atom_distance()now raisesValueErrorfor NaN. Previously, NaN silently turned off the close-pair check.site_index_mapping()now returns integer indices when nothing matchesspecies1_filter. Previously, it returned an empty float array, which could not be used as indices.StructureAligner.align()now raisesValueErrorwhenspeciesis 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 thecommitment_radiusargument toTrajectory. 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, andAtom.committed_sitegives 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: ignorecomments.Transitions are now recorded only by
Trajectory.append_timestep()(and soTrajectory.trajectory_from_structures()), between successive assigned sites in each atom’s trajectory.Trajectory.analyse_structure()andSiteCollection.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 callsSiteCollection.analyse_structure()directly in a loop therefore no longer accumulates transition counts, and where sites overlap its assignments can differ. Previously, directanalyse_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. UseSiteCollection.update_occupation()instead.Trajectory._normalise_counts(). UseTransitionTable.normalise_rows()instead.
Fixed
TrajectoryBuilder.with_voronoi_sites()now accepts a single label for all sites, aswith_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, otherwiseValueErroris raised.Site.reset(), and soTrajectory.reset(), now also clearsSite.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
pymatgentopymatgen-core; fullpymatgenmoved 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_lengthparameter 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(), andTrajectory.transition_probabilities_by_label()methods for aggregating per-site transition data.TransitionTableclass: a labelled square matrix with.matrix,.get(),.to_dict(), and.reorder()access patterns.TransitionTableexported from top-levelsite_analysispackage.include_edge_runsparameter 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.distancesmodule 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 intools.pyreplacingstructure.indices_from_symbol().Builder validation:
TrajectoryBuilder.build()now checks for same-species atom pairs in the reference structure closer thanmin_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()andunwrap_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()andcontains_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(), andget_coordination_indices()accept arrays instead of Structure objects.StructureAligneroptimisation loop no longer creates temporary Structure objects per iteration.IndexMapperandCoordinationEnvironmentFinderextract arrays at their boundaries.ReferenceBasedSiteseagerly extracts arrays from both structures in its constructor.
Site.contains_point()andSite.contains_atom()base class signatures no longer use*args/**kwargs. Subclasses declare concrete keyword-only parameters, so invalid arguments raiseTypeErrorimmediately.PriorityAssignmentMixinis now generic over site type (PriorityAssignmentMixin[SiteT]), so_get_priority_sitesyields the concrete site type.PolyhedralSite.contains_point()no longer accepts astructureparameter. Usenotify_structure_changed()orassign_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: ignoreon scipy import (scipy-stubs now provides types).Removed unused pymatgen imports from
polyhedral_site.py,dynamic_voronoi_site.py,site_collection.py,site.py, andindex_mapper.py.Fixed
get_vertex_indicesdeprecation warning referencing non-existentget_coordinating_indices(should beget_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_notebookwithtqdm.auto, which auto-detects the environment (terminal, Jupyter notebook, Jupyter lab). Theprogressparameter ontrajectory_from_structuresis now a simple boolean.Added PEP 561
py.typedmarker for downstream type checking support.Added
types-tqdmdev dependency; removed inline# type: ignoreon tqdm import.Removed redundant mypy ignores for
tqdm,pymatgen, andscipy(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 fromtrajectory_from_structures(tqdm.autohandles environment detection automatically).
[1.5.0] - 2026-02-28
Changed
Extracted shared priority-based site assignment logic into
PriorityAssignmentMixin, used by bothPolyhedralSiteCollectionandSphericalSiteCollection.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()inpbc_utils, used by bothPolyhedralSiteandDynamicVoronoiSite.Dissolved
containment.py: movedHAS_NUMBAto_compat.py, PBC shift updates topbc_utils.py, and face topology cache intopolyhedral_site.py.
Removed
Removed
neighbour_cutoffparameter fromSphericalSiteCollection(distance-ranked ordering replaces neighbour-based ordering).Removed
containmentmodule (internals relocated; no public API change).
[1.4.0] - 2026-02-28
Changed
Batch vectorised centre calculation for
DynamicVoronoiSitecollections, grouped by reference count. After the first frame, incremental PBC shift updates avoid per-site O(27-image) unwrapping (~4x speedup on MD trajectories).SiteCollectionnow owns site reset viareset().Trajectory.reset()delegates tosite_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_pbccomputed once per atom per frame rather than once per atom-site pair).algoparameter oncontains_point/contains_atomis deprecated; algorithm is now selected automatically.
Fixed
Fixed
use_reference_centerstypo in PBC handling documentation.
[1.2.7] - 2026-02-21
Changed
Replaced deprecated
typingimports (Optional,Union,List, etc.) with built-in equivalents.Replaced defensive
assertstatements with proper exceptions (ValueError,TypeError,RuntimeError).Standardised indentation to 4 spaces across all source files.
Removed redundant
objectinheritance fromAtomandTrajectory.Replaced type-narrowing hacks with annotations.
Consolidated lazy initialisation helpers in
ReferenceBasedSites.Use public
assign_coords()API instead of accessing privateAtom._frac_coords.
Fixed
Fixed
StructureAligner._run_differential_evolutionmutating the caller’sminimizer_optionsdict.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 toint).Fixed
append_timestepdropping timestept=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_snloop structure (inside.append()was inside the inner face loop).Fixed
Atom.from_dictcrashing whenfrac_coordsis absent.Removed debug
printstatement fromPolyhedralSite.__init__.Removed dead code and variable shadowing in
Trajectory.__init__.Fixed
x_pbcdocstring (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/XDATCARwith 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
metricsparameter for selecting specific statistics (occupancy, transitions, etc.).Numpy array inputs for
PolyhedralSite.Description label for
tqdmprogress output.
[1.2.1] - 2025-06-07
Changed
Optimised
SphericalSiteCollectionsite assignment using the same priority-based algorithm introduced in 1.2.0, reducing complexity from O(N^2) to O(kN).Configurable
neighbour_cutoffparameter (default 10.0 A) for distance-based neighbour determination.
[1.2.0] - 2025-06-07
Added
most_frequent_transitions()method onSiteclass.
Changed
Optimised
PolyhedralSiteCollectionsite 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
ImportErrorwhen importingReferenceBasedSites.
[1.0.1] - 2025-06-03
Fixed
Fixed missing
reference_workflowsubpackage 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_siteproperty onAtomfor tracking last known site.O(1) site lookup dictionary in
SiteCollection.
Changed
Priority-based site checking in
PolyhedralSiteCollectionandSphericalSiteCollection(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.
ReferenceBasedSitesworkflow 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.