Dynsight: Unified Trajectory Analysis Tool

• Dynsight is an open-source Python platform designed for unified analysis of trajectory data from both simulations and experiments, addressing fragmentation in many-body system studies.
• It streamlines workflows by integrating trajectory ingestion, descriptor construction, and unsupervised clustering using established tools like MDAnalysis, YOLO, DScribe, and trackpy.
• The platform employs advanced descriptors (LENS, SOAP, TimeSOAP) and Onion Clustering to extract physically relevant insights and improve reproducibility through comprehensive workflow logging.

Searching arXiv for the Dynsight paper to ground the article in the latest published description. Dynsight is an open-source Python platform for end-to-end analysis of trajectory data from both simulations and experiments. It was developed to address a fragmentation problem in the study of complex many-body systems composed of dynamically interacting units—atoms, molecules, colloids, particles, or larger objects—where extracting physical insight from raw trajectories commonly requires multiple separate steps and multiple separate tools. The platform unifies trajectory ingestion or reconstruction, descriptor construction, statistical and machine-learning analysis, visualization, and workflow logging within a common Python framework, with the explicit aim of supporting “trajectory-to-insight” workflows across different spatial and temporal scales (Martino et al., 27 Oct 2025).

1. Scope and conceptual basis

Dynsight is designed around a general abstraction: if a system can be represented as trajectories of interacting units, then advanced descriptors and analysis methods developed in molecular simulation can be reused more broadly. In this formulation, the central technical object is not a specific particle type or imaging modality, but the time-resolved trajectory itself. This permits a common treatment of systems whose trajectories are already available from simulation files and systems whose trajectories must first be reconstructed from experimental video (Martino et al., 27 Oct 2025).

The platform organizes trajectory analysis into three stages. The first is object identification and tracking when needed. The second is conversion of trajectories into descriptors or time-series representations that are easier to analyze than raw coordinates alone. The third is extraction of physically meaningful information through denoising, dimensionality reduction, clustering, visualization, and post hoc statistical analysis. The paper frames this organization as a response to a practical obstacle: before Dynsight, these operations were often scattered across different codes, data formats, and user interfaces.

A recurring theme in the platform’s design is generality across scales. The authors explicitly position descriptors such as LENS, SOAP, and TimeSOAP as sufficiently abstract to characterize systems at “virtually any scale,” provided that local environments and their temporal evolution can be represented from trajectories. This suggests a transfer of methodology from atomistic simulation to mesoscopic and macroscopic particle systems without changing the overall analysis logic.

2. Workflow architecture and software structure

Architecturally, Dynsight centers on a small set of Python object types in dynsight.trajectory. The Trj class stores a many-body trajectory as an MDAnalysis.Universe, providing the core representation for simulation-like data and interoperability with MDAnalysis tooling. Methods of Trj generate descriptor objects of type Insight. An Insight stores a descriptor as a NumPy array of shape (n_{\text{atoms}}, n_{\text{frames}}, n_{\text{components}}). Clustering outputs are stored in ClusterInsight, whose labels are a NumPy array of shape (n_{\text{atoms}}, n_{\text{frames}}) and which includes plotting and file I/O methods (Martino et al., 27 Oct 2025).

The resulting dataflow is unified: simulation or tracked video trajectories are converted into Trj; Trj produces descriptor Insight objects; Insight objects can be transformed into reduced or smoothed Insight objects or clustered into ClusterInsight; and ClusterInsight can then be rendered as plots, colored trajectories, or archived outputs. This object-oriented layering is central to the platform’s attempt to reduce the programming overhead normally associated with interfacing heterogeneous trajectory-analysis components.

The principal modules described for the platform are summarized below.

Module	Role	Representative functionality
dynsight.trajectory	Main analysis classes	Trj, Insight, ClusterInsight
dynsight.vision	Object detection from experimental videos	YOLO-based detection
dynsight.track	Particle linking and trajectory reconstruction	trackpy-based linking
dynsight.analysis	Post-processing and statistics	denoising, $g(r)$, entropy, information gain
dynsight.logger	Workflow provenance and export	human-readable logs, archive generation

The method inventory exposed in the paper is explicit. From Trj to Insight, Dynsight currently provides get_coord_number(), get_coordinates(), get_lens(), get_soap(), get_orientational_op(), and get_velocity_alignment(). From Insight to Insight, it provides get_angular_velocity(), spatial_average(), and get_tica(). From Insight to ClusterInsight, it provides get_onion() and get_onion_smooth().

The software relies on established Python libraries rather than reimplementing their core functionality. The paper explicitly cites MDAnalysis for trajectory representation, NumPy for descriptor arrays, DScribe for SOAP calculation, deeptime for tICA, YOLO through the ultralytics ecosystem for object detection, and trackpy for linking detections into trajectories. This integration strategy is integral to the platform’s role as a workflow layer rather than as a monolithic replacement for all underlying methods.

3. Trajectory acquisition from simulation and experiment

For simulation data, Dynsight can ingest trajectories directly. Because Trj is based on MDAnalysis.Universe, trajectory formats supported by MDAnalysis are relevant to the platform’s input layer. The paper gives a concrete example using .xtc trajectories and .gro topologies: $r_{\mathrm{cut}}$1 This simulation pathway bypasses the detection-and-tracking front end and enters directly at the descriptor-construction stage (Martino et al., 27 Oct 2025).

For experimental data, Dynsight provides an explicit trajectory-extraction pipeline through dynsight.vision and dynsight.track. The vision module uses convolutional-neural-network object detection from the YOLO ecosystem to detect particles or objects in video frames. To support specialized scientific imagery, the platform includes a standalone GUI web application called label_tool, which allows manual annotation of representative target particles in selected frames. These annotations are used to generate a synthetic dataset by redistributing labeled particles across artificial images for initial training. The detector is then improved through an iterative detect-and-retrain procedure applied to the experimental video itself.

Once framewise detections are available, the dynsight.track module uses trackpy to assign a unique ID to each detected particle and to link detections across consecutive frames, thereby reconstructing individual 2D trajectories. In the platform’s overall logic, this is the bridge from raw experimental video to analyzable time-resolved particle motion. Experimental input is thus video frame data; the output of vision is detected object positions; and the output of track is a set of linked particle trajectories with unique IDs.

The paper emphasizes that this front end is presently a specific implementation rather than an exhaustive solution. In version 2025.8.27, vision and track implement the described single-particle or single-object detection and tracking workflow, while additional detection and tracking methods are presented as future extensions.

4. Descriptor layer and trajectory representations

The representational core of Dynsight is the construction of “single-particle descriptors,” defined as scalar or vector quantities for each particle over time. These descriptors map raw coordinates, velocities, and local environments into forms better suited to detecting order, fluctuations, transitions, and dynamical domains. In the platform’s design, descriptor generation is the principal abstraction layer connecting raw trajectories to downstream inference (Martino et al., 27 Oct 2025).

A central descriptor is LENS, “Local Environments and Neighbors Shuffling.” LENS is a dynamical descriptor that monitors changes in the immediate neighborhood of each particle over time, capturing local rearrangements such as neighbor exchanges, local fluidization, interface motion, or collective local fluctuations. The paper emphasizes that LENS is permutationally variant but structurally invariant, which makes it useful for detecting local dynamical fluctuations and rare or collective events rather than static structural motifs. In Dynsight, it is computed with Trj.get_lens().

Another major descriptor is SOAP, “Smooth Overlap of Atomic Positions,” computed through the external DScribe package and exposed via Trj.get_soap(). SOAP is a high-dimensional structural descriptor of the local neighborhood around a central particle. It encodes relative spatial arrangements into a smooth representation of local density and order or disorder, thereby embedding local geometry, symmetry, and radial or angular structure into a vectorial spectrum.

Built on SOAP is TimeSOAP, a time-dependent descriptor that tracks temporal changes in the SOAP spectrum. The paper describes TimeSOAP as structurally variant and permutationally invariant, complementary to LENS. If LENS captures dynamic reshuffling of neighbors, TimeSOAP captures structural changes in the high-dimensional local environment. TimeSOAP can be computed through Insight.get_angular_velocity() or dynsight.soap.timesoap().

Dynsight also includes more conventional observables: coordination number via Trj.get_coord_number(), coordinates via Trj.get_coordinates(), local orientational order parameter via Trj.get_orientational_op(), and local velocity alignment via Trj.get_velocity_alignment(). The orientational order parameter is linked in the paper to hexatic order work, while velocity alignment is described as inspired by collective motion analyses such as Vicsek-type systems.

The framework is explicitly extensible. Users can add new scalar or vector single-particle quantities and wrap them as new Insight objects. This is significant because it makes the descriptor layer a stable interface for method development: new descriptors can enter the existing analysis chain without requiring a redesign of the overall workflow.

5. Analysis, clustering, and statistical inference

Dynsight’s third stage consists of extracting physically meaningful or statistically meaningful information from descriptor time series. One component is denoising and preprocessing. The analysis module includes a spatial denoising or spatial averaging approach inspired by prior work cited by the authors. In workflow terms, descriptors can be smoothed over neighboring particles to improve signal-to-noise while preserving physical locality, for example through Insight.spatial_average(trj=..., r_cut=..., num_processes=...). The paper identifies $r_{\mathrm{cut}}$ as the neighborhood cutoff radius used in such operations and gives an example with r_cut=7.5, corresponding to a local-environment cutoff distance (Martino et al., 27 Oct 2025).

A second component is dimensionality reduction. Dynsight implements time-lagged independent component analysis, tICA, using the deeptime package and exposes it through Insight.get_tica(). The role of tICA in the platform is to simplify the treatment of high-dimensional descriptor trajectories, especially for descriptors such as SOAP, while preserving slow collective dynamical modes.

A third component is unsupervised clustering, with Onion Clustering as the main built-in method. Onion Clustering is presented as central to the Dynsight approach for “single-point time-series” analysis. Its formal control parameter is the time resolution $\Delta t$, which sets the temporal coarse-graining applied to a time series of total length $\tau$. The method scans multiple values of $\Delta t$, determines how many statistically robust microscopic dynamical domains can be distinguished at each resolution, and visualizes the outcome in an “Onion plot.” This plot reports the number of identified environments and the amount of unclassified data as a function of $\Delta t$. Unclassified points at a given resolution are interpreted in the paper as fluctuations occurring faster than the chosen $\Delta t$. By scanning $\Delta t$, Dynsight identifies an “optimal” time resolution defined as the one that maximizes statistically robust subdivision into the largest number of microscopic environments. Onion Clustering is available via Insight.get_onion() and Insight.get_onion_smooth().

The analysis module also provides post-analysis statistical measures. These include the radial distribution function $g(r)$, Shannon entropy, sample entropy, and information gain due to clustering. Within the paper’s formulation, $g(r)$ serves as a pair-correlation observable, while the entropy and information-gain quantities extend the framework from structural and dynamical characterization to information-theoretic summaries of the resulting time-series representations.

The clustering and statistics layer is paired with visualization utilities. The paper mentions ClusterInsight.plot_output(), Onion plots, kernel density estimation visualizations of descriptor distributions, and colored trajectory exports. For example, clustering output can be exported as a colored .xyz trajectory.

6. Applications, reproducibility, and current limitations

The paper provides two explicit case studies. One is a water/ice coexistence molecular dynamics trajectory, used to demonstrate the core workflow: loading oxygen trajectories from XTC and GRO files, computing LENS with a chosen cutoff, performing spatial averaging, and applying Onion Clustering. The reported outputs include an Onion plot showing the number of identified environments versus $r_{\mathrm{cut}}$0, clustered LENS time series with kernel density estimation, and trajectory snapshots colored by detected clusters. The second case study concerns an experimental video of Quincke rollers, a colloidal active matter system, where label_tool, vision, and track are used to detect and track particles from processed video frames. Together, these examples illustrate the software’s intended unification of simulation and experiment within one analysis chain (Martino et al., 27 Oct 2025).

The platform’s reproducibility layer is implemented in dynsight.logger. This module records human-readable logs of analyses and can automatically generate standardized archives containing relevant data and metadata. The paper states that these archives are intended to be immediately depositable in repositories such as Zenodo and to support FAIR principles. This places Dynsight beyond a pure analysis library: it also operates as a provenance and packaging layer for sharable computational workflows.

Availability and installation are straightforward. Dynsight is open source under the MIT license, hosted on GitHub at https://github.com/GMPavanLab/dynsight, published on PyPI, and documented at https://dynsight.readthedocs.io. Installation is performed with: $r_{\mathrm{cut}}$2

The paper makes qualitative rather than heavily quantitative claims about performance. It describes Onion Clustering as efficient and statistically robust, particularly for identifying sparse or hidden fluctuations, and it argues that Dynsight streamlines workflows, enhances accessibility, improves reproducibility, and reduces fragmentation. At the same time, it explicitly does not provide numerical runtime benchmarks, memory scaling laws, or direct head-to-head timing comparisons against other software packages. Noise-filtering tools are described as still being optimized, and the current release is presented as a starting point rather than a closed final suite. A plausible implication is that Dynsight should be understood less as a fixed end-state package than as an extensible platform architecture for advanced trajectory analysis across simulated and experimentally resolved systems.