dynasor 2.2__tar.gz → 2.4__tar.gz

{dynasor-2.2 → dynasor-2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dynasor
-Version: 2.2
+Version: 2.4
 Summary: Dynamical structure factors and correlation functions from molecular dynamics trajectories
 Author: The dynasor developer team
 Maintainer: The dynasor developer team
@@ -30,6 +30,19 @@ Requires-Dist: mdanalysis
 Requires-Dist: numba>=0.55
 Requires-Dist: numpy>=1.18
 Requires-Dist: pandas>=2.2
+Requires-Dist: scipy
+Provides-Extra: test
+Requires-Dist: coverage; extra == "test"
+Requires-Dist: flake8; extra == "test"
+Requires-Dist: phonopy; extra == "test"
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: xdoctest; extra == "test"
+Provides-Extra: documentation
+Requires-Dist: pydata-sphinx-theme; extra == "documentation"
+Requires-Dist: nbsphinx; extra == "documentation"
+Requires-Dist: sphinx-autodoc-typehints; extra == "documentation"
+Requires-Dist: sphinx-design; extra == "documentation"
+Requires-Dist: sphinx-sitemap; extra == "documentation"
 Dynamic: license-file
 
 dynasor
@@ -38,27 +51,34 @@ dynasor
 **dynasor** is a tool for calculating total and partial dynamic structure factors as well as related correlation functions from molecular dynamics (MD) simulations.
 By analyzing these functions one can access the dynamics of a system without resorting to perturbative approaches.
 Moreover by combining in particular the structure factor with the cross sections (or form factors) of, e.g., neutrons, X-rays or electrons, one can predict experimental spectra.
-The main input consists of a trajectory from a MD simulation, i.e., a file containing snapshots of the particle coordinates and optionally velocities, that correspond to consecutively and equally spaced points in (simulation) time.
+The main input consists of a trajectory from an MD simulation, i.e., a file containing snapshots of the particle coordinates and optionally velocities that correspond to consecutive, equally spaced points in simulation time.
 
-**dynasor** provides both python and a command line interface.
+**dynasor** provides both a Python interface and a command-line interface.
 The following snippet illustrates how one can calculate dynamic structure factors using the former.
 
 .. code-block:: python
 
+   from dynasor import Trajectory, compute_dynamic_structure_factors
+   from dynasor.qpoints import get_spherical_qpoints
+
    traj = Trajectory('dump.xyz', trajectory_format='extxyz')
-   q_points = generate_spherical_qpoints(traj.cell, q_max=20)
+   q_points = get_spherical_qpoints(traj.cell, q_max=20)
    sample = compute_dynamic_structure_factors(traj, q_points=q_points, dt=5, window_size=100)
-   sample.write_to_npy('test.npy')
+   sample.write_to_npz('test.npz')
 
 **dynasor** can be installed via `pip <https://pypi.org/project/dynasor/>`_ or `conda <https://anaconda.org/conda-forge/dynasor>`_.
-Please consult the `installation section of the user guide <https://dynasor.materialsmodeling.org/installation.html>`_ for details.
+Please consult the `installation section of the user guide <https://dynasor.materialsmodeling.org/get_started/installation.html>`_ for details.
 
-The full documentation can be found in the `user guide <http://dynasor.materialsmodeling.org/>`_.
+The full documentation can be found in the `user guide <https://dynasor.materialsmodeling.org/>`_.
 For questions and help please use the `dynasor discussion forum on matsci.org <https://matsci.org/dynasor>`_.
 **dynasor** and its development are hosted on `gitlab <https://gitlab.com/materials-modeling/dynasor>`_.
 
-When using **dynasor**  in your research please cite the following paper:
+When using **dynasor**  in your research please cite the following papers:
 
 | *Dynasor – A tool for extracting dynamical structure factors and current correlation functions from molecular dynamics simulations*
 | Erik Fransson, Mattias Slabanja, Paul Erhart, and Göran Wahnström
 | Advanced Theory and Simulations **4**, 2000240 (2021); DOI:`10.1002/adts.202000240 <https://doi.org/10.1002/adts.202000240>`_
+
+| *Dynasor 2: From simulation to experiment through correlation functions*
+| Esmée Berger, Erik Fransson, Fredrik Eriksson, Eric Lindgren, Göran Wahnström, Thomas Holm Rod, and Paul Erhart
+| Computer Physics Communications **316**, 109759 (2025); DOI: `10.1016/j.cpc.2025.109759 <https://doi.org/10.1016/j.cpc.2025.109759>`_

{dynasor-2.2 → dynasor-2.4}/README.rst

@@ -4,27 +4,34 @@ dynasor
 **dynasor** is a tool for calculating total and partial dynamic structure factors as well as related correlation functions from molecular dynamics (MD) simulations.
 By analyzing these functions one can access the dynamics of a system without resorting to perturbative approaches.
 Moreover by combining in particular the structure factor with the cross sections (or form factors) of, e.g., neutrons, X-rays or electrons, one can predict experimental spectra.
-The main input consists of a trajectory from a MD simulation, i.e., a file containing snapshots of the particle coordinates and optionally velocities, that correspond to consecutively and equally spaced points in (simulation) time.
+The main input consists of a trajectory from an MD simulation, i.e., a file containing snapshots of the particle coordinates and optionally velocities that correspond to consecutive, equally spaced points in simulation time.
 
-**dynasor** provides both python and a command line interface.
+**dynasor** provides both a Python interface and a command-line interface.
 The following snippet illustrates how one can calculate dynamic structure factors using the former.
 
 .. code-block:: python
 
+   from dynasor import Trajectory, compute_dynamic_structure_factors
+   from dynasor.qpoints import get_spherical_qpoints
+
    traj = Trajectory('dump.xyz', trajectory_format='extxyz')
-   q_points = generate_spherical_qpoints(traj.cell, q_max=20)
+   q_points = get_spherical_qpoints(traj.cell, q_max=20)
    sample = compute_dynamic_structure_factors(traj, q_points=q_points, dt=5, window_size=100)
-   sample.write_to_npy('test.npy')
+   sample.write_to_npz('test.npz')
 
 **dynasor** can be installed via `pip <https://pypi.org/project/dynasor/>`_ or `conda <https://anaconda.org/conda-forge/dynasor>`_.
-Please consult the `installation section of the user guide <https://dynasor.materialsmodeling.org/installation.html>`_ for details.
+Please consult the `installation section of the user guide <https://dynasor.materialsmodeling.org/get_started/installation.html>`_ for details.
 
-The full documentation can be found in the `user guide <http://dynasor.materialsmodeling.org/>`_.
+The full documentation can be found in the `user guide <https://dynasor.materialsmodeling.org/>`_.
 For questions and help please use the `dynasor discussion forum on matsci.org <https://matsci.org/dynasor>`_.
 **dynasor** and its development are hosted on `gitlab <https://gitlab.com/materials-modeling/dynasor>`_.
 
-When using **dynasor**  in your research please cite the following paper:
+When using **dynasor**  in your research please cite the following papers:
 
 | *Dynasor – A tool for extracting dynamical structure factors and current correlation functions from molecular dynamics simulations*
 | Erik Fransson, Mattias Slabanja, Paul Erhart, and Göran Wahnström
 | Advanced Theory and Simulations **4**, 2000240 (2021); DOI:`10.1002/adts.202000240 <https://doi.org/10.1002/adts.202000240>`_
+
+| *Dynasor 2: From simulation to experiment through correlation functions*
+| Esmée Berger, Erik Fransson, Fredrik Eriksson, Eric Lindgren, Göran Wahnström, Thomas Holm Rod, and Paul Erhart
+| Computer Physics Communications **316**, 109759 (2025); DOI: `10.1016/j.cpc.2025.109759 <https://doi.org/10.1016/j.cpc.2025.109759>`_

{dynasor-2.2 → dynasor-2.4}/dynasor/__init__.py

@@ -15,8 +15,10 @@ from .qpoints import (
 )
 from .sample import read_sample_from_npz
 from .trajectory import Trajectory
+from .modes.mode_projector import ModeProjector
+from .modes.project_modes import project_modes
 
-__version__ = '2.2'
+__version__ = '2.4'
 __all__ = [
     'compute_dynamic_structure_factors',
     'compute_spectral_energy_density',
@@ -25,4 +27,6 @@ __all__ = [
     'get_supercell_qpoints_along_path',
     'read_sample_from_npz',
     'Trajectory',
+    'ModeProjector',
+    'project_modes',
 ]

{dynasor-2.2 → dynasor-2.4}/dynasor/cli/main.py

@@ -11,24 +11,35 @@ from dynasor.correlation_functions import compute_dynamic_structure_factors
 from dynasor.post_processing import get_spherically_averaged_sample_binned
 
 
+def _parse_q_direction(value):
+    message = 'q-direction must contain three comma-separated numbers'
+    try:
+        direction = np.asarray(value.split(','), dtype=float)
+    except ValueError as error:
+        raise argparse.ArgumentTypeError(message) from error
+    if direction.size != 3:
+        raise argparse.ArgumentTypeError(message)
+    return direction
+
+
 def main():
 
     parser = argparse.ArgumentParser(
         description='dynasor is a simple tool for calculating total and partial dynamic structure'
         ' factors as well as current correlation functions from molecular dynamics simulations.'
-        ' The main input consists of a trajectory output from a MD simulation, i.e., a file'
+        ' The main input consists of trajectory output from an MD simulation, i.e., a file'
         ' containing snapshots of the particle coordinates and optionally velocities that'
         ' correspond to consecutive, equally spaced points in (simulation) time.'
         '\n'
         ' Dynasor has recently been updated. Some of the old options have new names and'
         ' some new options have been added. If your script has stopped working, check the'
         ' options with "dynasor --help". In addition, we would like to let you know that'
-        ' dynasor now has a Python interface, which gives you acces to more'
+        ' dynasor now has a Python interface, which gives you access to more'
         ' functionality and options.')
 
     iogroup = parser.add_argument_group(
         'Input/output options',
-        'Options controlling input and output, files and fileformats.')
+        'Options controlling input and output, files and file formats.')
     iogroup.add_argument(
         '-f', '--trajectory', type=str, metavar='TRAJECTORY_FILE',
         help='Molecular dynamics trajectory file to be analyzed.'
@@ -88,7 +99,7 @@ def main():
 
     qline = parser.add_argument_group('Line-style q-space sampling')
     qline.add_argument(
-        '--q-direction', metavar='QDIRECTION',
+        '--q-direction', metavar='QDIRECTION', type=_parse_q_direction,
         help='Direction along which to sample. QPOINTS points will be evenly placed between'
         ' 0,0,0 and QDIRECTION. Given as three comma separated values.')
     defval = 100
@@ -184,11 +195,11 @@ def main():
 
     # setup q-points
     if args.q_sampling == 'line':
-        q_dir = np.array(args.q_direction)
+        q_dir = args.q_direction
         n_qpoints = args.q_points
         q_points = np.array([i * q_dir for i in np.linspace(0, 1, n_qpoints)])
     elif args.q_sampling == 'isotropic':
-        q_points = get_spherical_qpoints(traj.cell, args.q_max, args.max_q_points)
+        q_points = get_spherical_qpoints(traj.cell, q_max=args.q_max, max_points=args.max_q_points)
 
     # run dynasor calculation
     sample = compute_dynamic_structure_factors(

{dynasor-2.2 → dynasor-2.4}/dynasor/core/reciprocal.py

@@ -28,7 +28,7 @@ def calc_rho_q(x, q):
 
 
 def calc_rho_j_q(x, v, q):
-    """As calc_rho_q, but calculate also velocities in q-space
+    """As calc_rho_q, but calculate also velocities in q-space.
     """
     assert x.shape == v.shape
 

{dynasor-2.2 → dynasor-2.4}/dynasor/core/rho_j_q_numba.py

@@ -20,29 +20,28 @@ import numba
 # Calling this instead of manually inlining it actually incurs a small
 # performance hit (<10%) with current numba (2023). It increases readability
 # though and will probably sort itself out with later numba versions
-@numba.njit(fastmath=True, nogil=True)
+@numba.njit(fastmath=True, nogil=True)  # pragma: no cover
 def dot(a, b):
     return a[0]*b[0] + a[1]*b[1] + a[2]*b[2]
 
 
 # fastmath True makes the summation fast and also speeds up exponentiation
-# nogil releases the python GIL, probably not neccesary here
-@numba.njit(fastmath=True, nogil=True)
+# nogil releases the Python GIL, although it is probably not necessary here
+@numba.njit(fastmath=True, nogil=True)  # pragma: no cover
 def rho_q_single(x: np.ndarray,
                  q: np.ndarray) -> complex:
-    """Calculates the density at a single q-point
+    """Calculates the density at a single q-point.
 
     Parameters
     ----------
     x
-        positions as a (N, 3) array
+        Positions as a `(N, 3)` array.
     q
-        single q point as a with shape (3,)
+        Single q point as a with shape `(3,)`.
 
     Returns
     -------
-    rho
-        complex density at the specified q-point
+        Complex density at the specified q-point.
     """
     Nx = len(x)
 
@@ -57,20 +56,20 @@ def rho_q_single(x: np.ndarray,
 
 
 # parallel enables the numba.prange directive
-@numba.njit(fastmath=True, nogil=True, parallel=True)
+@numba.njit(fastmath=True, nogil=True, parallel=True)  # pragma: no cover
 def rho_q(x: np.ndarray, q: np.ndarray, rho: np.ndarray):
-    """Calculates the fourier transformed density
+    """Calculates the fourier transformed density.
 
     The parallelization is over q-points. The density is calculated in-place.
 
     Parameters
     ----------
     x
-        the positions as a float array with shape (``Nx``, 3)
+        The positions as a float array with shape `(Nx, 3)`.
     q
-        the q points as a float array with shape (``Nq``, 3)
+        The q-points as a float array with shape `(Nq, 3)`.
     rho
-        density as a complex array of length ``Nq``
+        Density as a complex array of length `Nq`.
     """
 
     Nx = len(x)
@@ -85,7 +84,7 @@ def rho_q(x: np.ndarray, q: np.ndarray, rho: np.ndarray):
         rho[i] = rho_q_single(x, q[i])
 
 
-@numba.njit(fastmath=True, parallel=True, nogil=True)
+@numba.njit(fastmath=True, parallel=True, nogil=True)  # pragma: no cover
 def rho_j_q(x: np.ndarray, v: np.ndarray, q: np.ndarray,
             rho: np.ndarray, j_q: np.ndarray):
     """Calculates the fourier transformed density and current.
@@ -95,15 +94,15 @@ def rho_j_q(x: np.ndarray, v: np.ndarray, q: np.ndarray,
     Parameters
     ----------
     x
-        the positions as a float array with shape (``Nx``, 3)
+        The positions as a float array with shape `(Nx, 3)`.
     v
-        the velocities as a float array with shape (``Nx``, 3)
+        The velocities as a float array with shape `(Nx, 3)`.
     q
-        the q points as a float array with shape (``Nq``, 3)
+        The q-points as a float array with shape `(Nq, 3)`.
     rho
-        density as a complex array of length ``Nq``
+        Density as a complex array of length `Nq`.
     j_q
-        current as a complex array with shape (``Nq``, 3)
+        Current as a complex array with shape `(Nq, 3)`.
     """
 
     Nx = len(x)

dynasor-2.4/dynasor/core/time_averager.py

@@ -0,0 +1,103 @@
+import numpy as np
+from numpy.typing import NDArray
+
+
+def truncate_nans(data):
+    """
+    Truncate trailing time columns that contain NaN values.
+
+    The function assumes that the last axis of the array corresponds to
+    time and removes all columns from the first occurrence of a NaN
+    (in any row) to the end of the array.
+
+    This guarantees that the returned array contains **no NaN values**,
+    even if this means discarding some valid data points that appear
+    after a NaN in another row.
+
+    Parameters
+    ----------
+    data : array_like, shape (N, T)
+        Input array where rows represent independent signals (e.g. q-points)
+        and the last axis represents time.
+
+    Returns
+    -------
+    ndarray
+        Array truncated along the time axis such that no NaN values remain.
+        The returned array has the same number of rows as the input but may
+        have fewer time columns.
+
+    Notes
+    -----
+    Example::
+
+        [[1.0, 0.8, 0.7, 0.6, 0.5, 0.3, nan],
+         [1.0, 0.8, 0.7, 0.6, 0.5, nan, nan]]
+
+    becomes::
+
+        [[1.0, 0.8, 0.7, 0.6, 0.5],
+         [1.0, 0.8, 0.7, 0.6, 0.5]]
+
+    because the first NaN appears in column 5.
+    """
+
+    arr = np.asarray(data)
+    assert arr.ndim == 2
+
+    # Determine which time columns contain any NaN values
+    column_has_nan = np.any(np.isnan(arr), axis=0)
+
+    # Find the first column containing a NaN
+    nan_indices = np.where(column_has_nan)[0]
+
+    # No NaNs present, return array unchanged
+    if len(nan_indices) == 0:
+        return arr
+
+    # NaNs were found, Keep only the column without NaNs
+    first_nan_column = nan_indices[0]
+    return arr[:, :first_nan_column]
+
+
+class TimeAverager:
+    """Naive special purpose averager class used in dynasor to collect and time-average arrays
+    obtained from sliding time-window averaging.
+
+    It assists with keeping track of how many data samples have been added to each slot.
+
+    It will time-average arrays of shape ``(Nq, time_window)`` where ``Ǹq`` is the
+    number of q-points and ``time_window`` is the size of the time window.
+
+    Parameters
+    ----------
+    time_window
+        Size of the time window in which the time-average happens.
+    array_length
+        Length of the array to be averaged for each time-lag, i.e., number of q-points.
+    """
+
+    def __init__(self, time_window: int, array_length: int):
+        assert time_window >= 1
+        self._time_window = time_window
+        self._array_length = array_length
+
+        self._counts = np.zeros(time_window, dtype=int)
+        self._arrays = [np.zeros(array_length) for _ in range(time_window)]
+
+    def add_sample(self, time_lag: int, sample: np.ndarray):
+        assert len(sample) == self._array_length
+        self._counts[time_lag] += 1
+        self._arrays[time_lag] += sample
+
+    def get_average_at_timelag(self, time_lag: int):
+        if self._counts[time_lag] == 0:
+            array = np.full((self._array_length, ), np.nan)
+            return array
+        return self._arrays[time_lag] / self._counts[time_lag]
+
+    def get_average_all(self) -> NDArray[float]:
+        """
+        Returns an averaged array of shape ``(array_length, time_window)``.
+        """
+        return np.array([self.get_average_at_timelag(t) for t in range(self._time_window)]).T