New descriptors and faster Insight loading

.gitignore

@@ -9,6 +9,7 @@ docs/source/_autosummary
 examples/onion_analysis/data.json
 examples/analysis_workflow/lens.json
 examples/analysis_workflow/onion.json
+examples/analysis_workflow/.oxygens.xtc_offsets.*
 examples/analysis_workflow/colored_trj.xyz
 examples/info_gain/trj_*.npy
 tests/systems/coex/.*

docs/source/_static/recipes/soap_dim_red.py

@@ -84,7 +84,7 @@ def compute_soap_tica(
         soap_path=soap_path,
     )
 
-    rel_times, _, tica_ds = dynsight.tica.many_body_tica(
+    rel_times, _, tica_ds = dynsight.descriptors.many_body_tica(
         soap.dataset,
         lag_time=lag_time,
         tica_dim=tica_dim,

docs/source/analysis.rst

@@ -3,17 +3,30 @@ analysis
 
 The ``analysis`` modulus contains functions for miscellaneous analyses on many-body trajectories. 
 
-Functions
----------
+
+Entropy
+-------
+
+The ``analysis`` module offers a variety of functions for entropy- and
+information-based calculations. 
 
 .. toctree::
   :maxdepth: 1
 
   compute_shannon <_autosummary/dynsight.analysis.compute_shannon>
+  compute_kl_entropy <_autosummary/dynsight.analysis.compute_kl_entropy>
+  compute_negentropy <_autosummary/dynsight.analysis.compute_negentropy>
   compute_entropy_gain <_autosummary/dynsight.analysis.compute_entropy_gain>
   compute_shannon_multi <_autosummary/dynsight.analysis.compute_shannon_multi>
   compute_entropy_gain_multi <_autosummary/dynsight.analysis.compute_entropy_gain_multi>
   sample_entropy <_autosummary/dynsight.analysis.sample_entropy>
+
+Other functions
+---------------
+
+.. toctree::
+  :maxdepth: 1
+
   compute_rdf <_autosummary/dynsight.analysis.compute_rdf>
   self_time_correlation <_autosummary/dynsight.analysis.self_time_correlation>
   cross_time_correlation <_autosummary/dynsight.analysis.cross_time_correlation>

docs/source/descriptors.rst

@@ -0,0 +1,50 @@
+Descriptors
+===========
+
+.. toctree::
+  :maxdepth: 1
+
+   SOAP <soap>
+   timeSOAP <time_soap>
+   LENS <lens>
+
+tICA
+----
+
+.. toctree::
+  :maxdepth: 1
+
+  many_body_tica <_autosummary/dynsight.descriptors.many_body_tica>
+
+tICA (time-lagged Independent Component Analysis) is a dimensionality reduction method. Time-series data are mapped to components characterizing the slowest processes, by maximizing the data correlation function at a given lag-time. 
+
+This module allows to perform tICA on trajectories from many-body systems, where the observables under analysis are single-particle descriptors, which should not be mixed within the tICs. 
+
+This module uses the TICA class from the deeptime.decomposition package (see the `documentation page <https://deeptime-ml.github.io/latest/notebooks/tica.html>`_).
+:mod:`deeptime` requires numpy <= 2.1. 
+
+
+Velocity alignment
+------------------
+
+.. toctree::
+  :maxdepth: 1
+
+  velocity_alignment <_autosummary/dynsight.descriptors.velocity_alignment>
+
+Computes the average velocity alignment between the central particle and the
+neighboring ones. The alignment is computed as the cosine between the velocities.
+Thus, the output is a number between 1 (perfect alignment) and -1 (perfect
+anti-alignment).
+
+Orinetational order parameter
+-----------------------------
+
+.. toctree::
+  :maxdepth: 1
+
+  orientational_order_param <_autosummary/dynsight.descriptors.orientational_order_param>
+
+Computes orientational order parameter for the neighbors of each atom in the
+trajectory. The output is a real number between 0 and 1, where 1 corresponds
+to a perfect order, and 0 to completely random positions.

docs/source/index.rst

@@ -1,15 +1,17 @@
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+
+   How to get started <trajectory>
+
 .. toctree::
    :hidden:
    :caption: dynsight
    :maxdepth: 2
 
-   trajectory <trajectory>
-   SOAP <soap>
-   timeSOAP <time_soap>
-   LENS <lens>
-   tICA <tica>
-   onion clustering <onion>
    vision <vision>
+   descriptors <descriptors>
+   onion clustering <onion>
    analysis <analysis>
    data processing <data_processing>
    HDF5er <hdf5er>

docs/source/soap_dim_red.rst

@@ -121,7 +121,7 @@ More details on the algorithm here:
 .. toctree::
   :maxdepth: 1
 
-  many_body_tica <_autosummary/dynsight.tica.many_body_tica>
+  many_body_tica <_autosummary/dynsight.descriptors.many_body_tica>
 
 This function takes as input a :class:`.trajectory.Trj` and all the relevant
 parameters, and performs the TICA of the corresponding SOAP dataset.
@@ -160,7 +160,7 @@ parameters, and performs the TICA of the corresponding SOAP dataset.
             soap_path=soap_path,
         )
 
-        rel_times, _, tica_ds = dynsight.tica.many_body_tica(
+        rel_times, _, tica_ds = dynsight.descriptors.many_body_tica(
             soap.dataset,
             lag_time=lag_time,
             tica_dim=tica_dim,

docs/source/trajectory.rst

@@ -1,19 +1,46 @@
-trajectory
-==========
+How to get started: the ``trajectory`` module
+=============================================
+
+The easiest way to use ``dynsight`` is via the ``trajectory`` module, which
+offers an object-oriented implementation of most of the functions and utilities,
+to facilitate the workflow of any analysis.
 
-This module offers an object-oriented implementation of the ``dynsight``
-utilities, to facilitate the workflow of any analysis.
 Moreover, the ``trajectory`` classes make it easier to save and share results,
-and have a built-in logging module.
+and has a built-in logging module.
 
 The :class:`.trajectory.Trj` class is a container for a MDAnalysis.Universe,
-which allows for the computation of all the descriptors implemented in ``dynsight``.
+which has methods for the computation of all the descriptors implemented in
+``dynsight``.
 
 These descriptors, as well as the output of subsequent analyses, are stored in
 :class:`.trajectory.Insight` or :class:`.trajectory.ClusterInsight` objects.
 
 We recommend the users, when possible, to write code using this module.
 
+As a minimal example, a typical code for the computation of the SOAP descriptor
+may look like this:
+
+.. code-block::
+
+    from pathlib import Path
+    from dynsight import Trj
+
+    traj_file = Path("path/to/the/traj.xtc")
+    topo_file = Path("path/to/the/traj.gro")
+
+    trj = Trj.init_from_xtc(
+        traj_file=traj_file,
+        topo_file=topo_file,
+    )  # This is a Trj object
+
+    soap = trj.get_soap(
+        r_cut=10.0,
+        n_max=4,
+        l_max=4
+    )  # This is an Insight object
+
+    soap_values = soap.dataset  # The np.ndarray with the computed values
+
 Complete examples can be found in the recipes section of this documentation. 
 
 Classes

examples/analysis_workflow.py

@@ -1,12 +1,12 @@
-"""Creating an example for the new trajectory module."""
+"""An example for the trajectory module."""
 
 from pathlib import Path
 
-from dynsight.trajectory import Insight, OnionInsight, Trj
+from dynsight.trajectory import Insight, OnionSmoothInsight, Trj
 
 
 def main() -> None:
-    """Creating an example for the new trajectory module."""
+    """An example for the trajectory module."""
     files_path = Path("analysis_workflow")
 
     # Create a Trj object
@@ -19,27 +19,25 @@ def main() -> None:
     # From here, we work with an Insight, containing data computed from a Trj
     lens_file = files_path / "lens.json"
     if lens_file.exists():
-        lens = Insight.load_from_json(lens_file)
+        lens = Insight.load_from_json(lens_file, mmap_mode="r")
     else:
         _, lens = trj.get_lens(r_cut=7.5)
         lens.dump_to_json(lens_file)
 
     # We can do spatial average on the computed LENS
     trj_lens = trj.with_slice(slice(0, -1, 1))
-    lens_smooth = lens.spatial_average(
-        trj=trj_lens, r_cut=7.5, num_processes=6
-    )
+    lens_aver = lens.spatial_average(trj=trj_lens, r_cut=7.5, num_processes=6)
 
     # And we can perform onion-clustering
-    lens_onion = lens_smooth.get_onion_smooth(delta_t=10)
+    lens_onion = lens_aver.get_onion_smooth(delta_t=10)
 
     lens_onion.plot_output(
-        file_path=files_path / "tmp_fig1.png",
-        data_insight=lens_smooth,
+        file_path=files_path / "fig1.png",
+        data_insight=lens_aver,
     )
     lens_onion.plot_one_trj(
-        file_path=files_path / "tmp_fig2.png",
-        data_insight=lens_smooth,
+        file_path=files_path / "fig2.png",
+        data_insight=lens_aver,
         particle_id=1234,
     )
     lens_onion.dump_colored_trj(
@@ -49,7 +47,9 @@ def main() -> None:
 
     # Save/load the Insight with all the results
     lens_onion.dump_to_json(files_path / "onion.json")
-    _ = OnionInsight.load_from_json(files_path / "onion.json")
+    _ = OnionSmoothInsight.load_from_json(
+        files_path / "onion.json", mmap_mode="r"
+    )
 
 
 if __name__ == "__main__":

src/dynsight/__init__.py

@@ -3,12 +3,12 @@
 from dynsight import (
     analysis,
     data_processing,
+    descriptors,
     hdf5er,
     lens,
     logs,
     onion,
     soap,
-    tica,
     trajectory,
     utilities,
     vision,
@@ -17,12 +17,12 @@
 __all__ = [
     "analysis",
     "data_processing",
+    "descriptors",
     "hdf5er",
     "lens",
     "logs",
     "onion",
     "soap",
-    "tica",
     "trajectory",
     "utilities",
     "vision",