Python interface

This section includes documentation of some of the internal methods and classes can be useful for further analysis.

Fourier transformations

This module provides an implementation of Filon’s integration formula. For information about Filon’s formula, see e.g. Abramowitz and Stegun, Handbook of Mathematical Functions, section 25 or Allen and Tildesley, Computer Simulation of Liquids, Appendix D.

Integration is performed along one dimension (default axis=0), e.g.,

[F0[0]  F1[0] ..  FN[0] ]     [f0[0]  f1[0] ..  fN[0] ]
[   .      .         .  ]     [   .      .         .  ]
[F0[.]  F1[.] ..  FN[.] ] = I([f0[.]  f1[.] ..  fN[.] ], dx, [k[0] .. k[Nk]])
[   .      .         .  ]     [   .      .         .  ]
[F0[Nk] F1[Nk] .. FN[Nk]]     [f0[Nx] f1[Nx] .. fN[Nx]]

where k and Fj have end index Nk, and fj has end index Nx. Nk is automatically set by the length of k. Due to the algorithm, fj[Nx] must be of odd length (Nx must be an even number), and should correspond to a linearly spaced set of data points (separated by dx along the integration axis).

sin_integral() and cos_integral() allow for shifted integration intervals by the optional argument x0.

dsf.filon.cos_integral(f, dx, k, x0=0.0, axis=0)

Calculates the integral \(\int_{x_0}^{2n\Delta x} f(x) \cos(k x) dx\).

Parameters:

  • f (array) – function values; must contain an odd number of elements

  • dx (float) – spacing of x-axis (\(\Delta x\))

  • k (array) – values of reciprocal axis, at which to evaluate transform; if k is not provided, linspace(0.0, 2*pi/dx, f.shape[axis]), will be used.

  • x0 (float) – offset for integration interval

  • axis (int) – axis along which to carry out integration

Returns:

tuple of k and F values

Return type:

float

dsf.filon.fourier_cos(f, dx, k=None, axis=0)

Calculates the direct Fourier cosine transform \(F(k)\) of a function \(f(x)\) using Filon’s integration method.

The array values f[0]..f[2n] are expected to correspond to \(f(0.0)\ldots f(2n\Delta x)\). Hence, f should contain an odd number of elements.

The transform is approximated by the integral \(F(k) = 2\int_{0}^{x_{max}} f(x) \cos(k x) dx\), where \(x_{max} = 2n \Delta x\).

Parameters:

  • f (array) – function values; must contain an odd number of elements

  • dx (float) – spacing of x-axis (\(\Delta x\))

  • k (array) – values of reciprocal axis, at which to evaluate transform; if k is not provided, linspace(0.0, 2*pi/dx, f.shape[axis]), will be used.

  • axis (int) – axis along which to carry out integration

Returns:

tuple of k and F values

Return type:

(array, array)

Example

A common use case is

k, F = fourier_cos(f, dx)
dsf.filon.sin_integral(f, dx, k, x0=0.0, axis=0)

Calculates the integral \(\int_{x_0}^{2n\Delta x} f(x) \sin(k x) dx\).

Parameters:

  • f (array) – function values; must contain an odd number of elements

  • dx (float) – spacing of x-axis (\(\Delta x\))

  • k (array) – values of reciprocal axis, at which to evaluate transform; if k is not provided, linspace(0.0, 2*pi/dx, f.shape[axis]), will be used.

  • x0 (float) – offset for integration interval

  • axis (int) – axis along which to carry out integration

Returns:

tuple of k and F values

Return type:

float

Trajectory handling

dsf.trajectory.get_itraj(filename: str, step: int = 1, max_frames: int = 0, readers=[<class 'dsf.trajectory_reader.lammpstrj_trajectory_reader.lammpstrj_trajectory_reader'>, <class 'dsf.trajectory_reader.extxyz_trajectory_reader.extxyz_trajectory_reader'>])

Return a dynasor-style trajectory iterator

Simple wrapper for the trajectory_reader-classes.

Parameters:

  • filename (str) – name of input file

  • step (int) – step to access (1 by default = every single frame); must be > 0.

  • max_frames (int) – maximum number of frames to read (0 by default = no limit); must be >= 0.

Return type:

Each iterator step consists of a dictionary.

{
 'index' : trajectory frame index (1, 2, 3, ...),
 'box'   : simulation box as 3 row vectors (nm),
 'N'     : number of atoms,
 'x'     : particle positions as 3xN array (nm),
 'v'     : (*) particle velocities as 3xN array (nm/ps),
 'time'  : (*) simulation time (ps),
}

(*) may not be available, depends on reader and trajectory file format.

class dsf.trajectory.iwindow(itraj, width=2, stride=1, element_processor=None)

Sliding window iterator.

Returns consecutive windows (a windows is represented as a list of objects), created from an input iterator.

Parameters:

  • width (int) – length of window

  • stride (int) – distance between the start of two consecutive window frames

  • element_processor (function) – enables processing each non-discarded object; useful if stride > width and map_item is expensive (as compared to directly passing map(fun, itraj) as itraj); if stride < width, you could as well directly pass map(fun, itraj).