sportran.md.mdsample.MDSample

class sportran.md.mdsample.MDSample(traj=None, spectr=None, psd=None, freqs=None, DT_FS=1.0)

Bases: object

An MDSample object contains all the information that represent a single and unique Molecular Dynamics sample. For example it may contain:

  • a trajectory (any N-dim time series in real space)

  • its spectrum (the Fourier transform)

  • its Power Spectral Density (aka periodogram)

  • …

All the information contained in this object is always consistent, i.e. it represents a single MD sample. Any operation that alters any of the sample’s properties should create a new MDSample object, in order to preserve the 1:1 correspondence among the sample’s attributes.

An MDSample object can be initialized from any of its main properties (trajectory, spectrum, periodogram), although e.g. it is not be possible to uniquely define a trajectory from its periodogram, as this contains less information.

ATTRIBUTES:

  • traj the trajectory, a (N, N_EQUIV_COMPONENTS) array

  • spectr the spectrum, i.e. trajectory’s FFT.

    For now it is assumed to be one sided, i.e. it contains NFREQS = N/2+1 normalized frequencies contained in the interval [0, 1/(2N*DT)]

  • psd the Power Spectral Density (periodogram), defined as

    DT N-1

    I(f) = —- * SUM | x[n] * exp(-2.0J*pi*f/N) |^2

    N n=0

    with f = [0, 1/(2N*DT)]

  • N size of traj

  • NFREQS number of trajectories, should be N/2+1

  • freqs an array of frequencies, should be [0, 1/(2N*DT)]

  • freqs_THz an array of frequencies, expressed in THz

  • DT_FS timestep in femtoseconds

  • fpsd filtered periodogram

  • flogpsd filtered log-periodogram

  • acf autocorrelation function

  • N_EQUIV_COMPONENTS number of EQUIVALENT (e.g. Cartesian) components (an average over them will be computed)

  • MANY_EQUIV_COMPONENTS True if N_EQUIV_COMPONENTS > 1

  • PSD_FILTER_W width of the moving average filter (reduced frequency units)

  • PSD_FILTER_W_THZ width of the moving average filter (THz)

  • PSD_FILTER_WF width of the moving average filter (number of frequencies)

__init__(traj=None, spectr=None, psd=None, freqs=None, DT_FS=1.0)

Methods

__init__([traj, spectr, psd, freqs, DT_FS])

compute_acf([NLAGS])

Computes the autocovariance function of the trajectory.

compute_gkintegral()

Compute the integral of the autocovariance function.

compute_psd([PSD_FILTER_W, freq_units, ...])

Compute the periodogram from the trajectory or the spectrum.

compute_spectrum()

Compute spectrum from trajectory by FFT.

compute_trajectory()

Compute trajectory from spectrum by IFFT.

filter_psd([PSD_FILTER_W, freq_units, ...])

Filter the periodogram with the given PSD_FILTER_W [freq_units].

initialize_psd([freq_psd, psd, freqs, DT_FS])

Initialize the PSD. This can be done in 3 ways:

initialize_spectrum(array)

initialize_traj(array)

Initialize a trajectory from an array. The dimensions of the array should be: (number of time points, number of equivalent components) or, in the case of one component: (number of time points).

plot_periodogram([PSD_FILTER_W, freq_units, ...])

Plots the current's periodogram (psd) :param current: current object to plot periodogram :param PSD_FILTER_W: width of the filtering window :param freq_units: 'thz' [THz] 'red' [omega*DT/(2*pi)] :param freq_scale: rescale red frequencies by this factor (e.g. 2 --> freq = [0, 0.25]) :param axes: plot periodograms in units of kappa (default: True) - NB: log-psd not converted :param FIGSIZE: size of the plot.

plot_resample(xf[, PSD_FILTER_W, ...])

Plots the periodogram of a time series and of a filtered/resampled one for comparison. :param x: a time series object to plot :param xf: a filtered & resampled time series object :param freq_units: 'thz' [THz] 'red' [omega*DT/(2*pi)] :param PSD_FILTER_W: PSD filtering window width [chosen frequency units] :param FIGSIZE: plot figure size.

plot_trajectory(*[, axis, FIGSIZE])

Plot the time series.

resample([TSKIP, fstar_THz, FILTER_W, plot, ...])

Simulate the resampling of the time series.

set_plotter([plotter])

Set the plotter class.

timeseries()

Return a time series (fs units).
compute_acf(NLAGS=None)

Computes the autocovariance function of the trajectory.

compute_gkintegral()

Compute the integral of the autocovariance function.

compute_psd(PSD_FILTER_W=None, freq_units='THz', method='trajectory', DT_FS=None, normalize=False)

Compute the periodogram from the trajectory or the spectrum. If a PSD_FILTER_W (expressed in freq_units) is known or given, the psd is also filtered. The PSD is multiplied by DT_FS at the end.

compute_spectrum()

Compute spectrum from trajectory by FFT.

compute_trajectory()

Compute trajectory from spectrum by IFFT.

filter_psd(PSD_FILTER_W=None, freq_units='THz', window_type='rectangular', logpsd_filter_type=1)
Filter the periodogram with the given PSD_FILTER_W [freq_units].

  • PSD_FILTER_W PSD filter window [freq_units]

  • freq_units frequency units [‘THz’ (default), ‘red’]

  • window_type filtering window type [‘rectangular’]

initialize_psd(freq_psd=None, psd=None, freqs=None, DT_FS=None)
Initialize the PSD. This can be done in 3 ways:
  • passing a tuple (freqs, psd)

    e.g. initialize_psd((freqs,psd))

  • passing frequencies and PSD separately

    e.g. initialize_psd(freqs, psd) e.g. initialize_psd(freqs=freqs, psd=psd)

  • passing PSD only (frequencies will be computed automatically)

    e.g. initialize_psd(psd)

initialize_traj(array)

Initialize a trajectory from an array. The dimensions of the array should be:

(number of time points, number of equivalent components)

or, in the case of one component:

(number of time points)

plot_periodogram(PSD_FILTER_W=None, *, freq_units='THz', freq_scale=1.0, axes=None, FIGSIZE=None, mode='log', **plot_kwargs)

Plots the current’s periodogram (psd) :param current: current object to plot periodogram :param PSD_FILTER_W: width of the filtering window :param freq_units: ‘thz’ [THz]

‘red’ [omega*DT/(2*pi)]

Parameters

  • freq_scale – rescale red frequencies by this factor (e.g. 2 –> freq = [0, 0.25])

  • axes – plot periodograms in units of kappa (default: True) - NB: log-psd not converted

  • FIGSIZE – size of the plot

Returns

a matplotlib.axes.Axes object

plot_resample(xf, PSD_FILTER_W=None, *, freq_units='THz', axes=None, FIGSIZE=None, mode='log')

Plots the periodogram of a time series and of a filtered/resampled one for comparison. :param x: a time series object to plot :param xf: a filtered & resampled time series object :param freq_units: ‘thz’ [THz]

‘red’ [omega*DT/(2*pi)]

Parameters

  • PSD_FILTER_W – PSD filtering window width [chosen frequency units]

  • FIGSIZE – plot figure size

Returns

xf: a filtered & resampled time series object axes: a matplotlib.axes.Axes object

plot_trajectory(*, axis=None, FIGSIZE=None, **plot_kwargs)

Plot the time series.

resample(TSKIP=None, fstar_THz=None, FILTER_W=None, plot=False, PSD_FILTER_W=None, freq_units='THz', FIGSIZE=None, verbose=True)

Simulate the resampling of the time series.

Parameters

  • TSKIP = sampling time [steps]

  • fstar_THz = target cutoff frequency [THz]

  • TSKIP and fstar_THZ are mutually exclusive.

  • FILTER_W = pre-sampling filter window width [steps]

  • plot = plot the PSD [False]

  • PSD_FILTER_W = PSD filtering window width [chosen frequency units]

  • freq_units = ‘thz’ [THz] – ‘red’ [omega*DT/(2*pi)]

  • FIGSIZE = plot figure size

  • verbose = print log [True]

Returns

  • xf (a filtered & resampled time series object)

  • ax (an array of plot axes, optional (if plot=True))

classmethod set_plotter(plotter=None)

Set the plotter class. The _plotter attribute will contain the selected plotter class. All the plot functions of plotter (named ‘plot_*’) will be transformed into methods of Current.

timeseries()

Return a time series (fs units).