sportran.current.electric.ElectricCurrent

class sportran.current.electric.ElectricCurrent(traj, **params)

Bases: sportran.current.current.Current

ElectricCurrent API for thermo-cepstral analysis. Defines an ElectricCurrent object with useful tools to perform analysis.

INPUT parameters:

  • traj the current time series (N, N_EQUIV_COMPONENTS) array For a multi-component fluid use a (N_CURRENTS, N, N_EQUIV_COMPONENTS) array

  • DT_FS MD time step [fs]

  • UNITS the units of current (‘metal’, ‘real’, …) - use the method get_units_list() to get a list of supported units

  • TEMPERATURE average temperature [K]

  • VOLUME simulation cell volume [A^3]

OPTIONAL parameters:

  • PSD_FILTER_W PSD filter window [freq_units] (optional)

  • FREQ_UNITS frequency units [THz or red] (optional)

  • MAIN_CURRENT_INDEX for a multi-current time series, the index of the “main” current (e.g. energy) [0]

  • MAIN_CURRENT_FACTOR factor to be multiplied by the main current [1.0]

__init__(traj, **params)

Methods

__init__(traj, **params)

cepstral_analysis([aic_type, ...])

Performs Cepstral Analysis on the Current's trajectory.

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 heat current time series.

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].

fstar_analysis(TSKIP_LIST[, aic_type, ...])

get_units_list()

Get the list of supported units.

initialize_cepstral_parameters()

Defines the parameters of the theoretical distribution of the cepstrum.

initialize_currents(j, DT_FS[, ...])

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).

initialize_units(**parameters)

Initializes the units and defines the KAPPA_SCALE.

plot_L0_Pstar(*[, axis, label, FIGSIZE])

Plots L0 as a function of P*.

plot_cepstral_spectrum(*[, freq_units, ...])

Plots the cepstral spectrum.

plot_ck(*[, axis, label, FIGSIZE])

Plots the cepstral coefficients c_K.

plot_cospectrum_component(idx1, idx2, *[, ...])

Plot the (idx1, idx2) component of the cospectrum.

plot_fstar_analysis(FSTAR_THZ_LIST[, ...])

Plots kappa(P*) as a function of the f*.

plot_kappa_Pstar(*[, axis, label, FIGSIZE, ...])

Plots the value of kappa as a function of P*.

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: matplotlib.axes.Axes object (if None, create one) :param kappa_units: plot periodograms in units of kappa (default: True) - NB: log-psd not converted :param FIGSIZE: size of the plot.

plot_psd([j2, j2pl, f_THz_max, k_SI_max, ...])

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).
cepstral_analysis(aic_type='aic', aic_Kmin_corrfactor=1.0, manual_cutoffK=None)

Performs Cepstral Analysis on the Current’s trajectory.

cutoffK = (P*-1) is the number of cepstral coefficients retained by the filter. By default, this is chosen as the number of cepstral coefficients that minimizes the Akaike Information Criterion, multiplied by a correction factor (aic_Kmin_corrfactor):

self.cfilt.cutoffK = argmin(self.cfilt.aic) * aic_Kmin_corrfactor

This choice can be manually overridden by setting manual_cutoffK to the desired value.

Input parameters:

aic_type = the Akaike Information Criterion function used to choose the cutoff (‘aic’, ‘aicc’) aic_Kmin_corrfactor = correction factor multiplied by the AIC cutoff (cutoffK = aic_Kmin * Kmin_corrfactor) (default: 1.0) manual_cutoffK = (P*-1) = manual cutoff. If set, the AIC cutoff will be ignored.

The resulting conductivity is returned in the chosen units, generally:

kappa +/- kappa_std [SI units]

The log of the analysis can be retried from the variable self.cepstral_log.

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')

Compute the periodogram from the heat current time series. 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’, ‘red’ (default)]

  • window_type filtering window type [‘rectangular’]

classmethod get_units_list()

Get the list of supported units. Units are defined in the module current/units/{current_type}.py, where {current_type} is the _current_type attribute of this class (‘heat’, ‘electric’, …).

initialize_cepstral_parameters()

Defines the parameters of the theoretical distribution of the cepstrum.

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)

initialize_units(**parameters)

Initializes the units and defines the KAPPA_SCALE.

plot_L0_Pstar(*, axis=None, label=None, FIGSIZE=None)

Plots L0 as a function of P*. :param current: current object to plot :param axis: matplotlib.axes.Axes object (if None, create one) :param label: :param FIGSIZE: size of the plot

Returns

a matplotlib.axis.Axes object

plot_cepstral_spectrum(*, freq_units='THz', freq_scale=1.0, axes=None, kappa_units=True, FIGSIZE=None, mode='log', **plot_kwargs)

Plots the cepstral spectrum.

Parameters

  • current – current object to plot

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

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

  • axes – matplotlib.axes.Axes object (if None, create one)

  • kappa_units – 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_ck(*, axis=None, label=None, FIGSIZE=None)

Plots the cepstral coefficients c_K. :param current: current object to plot :param axis: matplotlib.axes.Axes object (if None, create one) :param label: :param FIGSIZE: size of the plot

Returns

a matplotlib.axis.Axes object

plot_cospectrum_component(idx1, idx2, *, axis=None, FIGSIZE=None, f_THz_max=None, k_SI_max=None, k_SI_min=None, k_tick=None, f_tick=None)

Plot the (idx1, idx2) component of the cospectrum.

plot_fstar_analysis(FSTAR_THZ_LIST, original_current=None, *, axes=None, FIGSIZE=None, **plot_kwargs)

Plots kappa(P*) as a function of the f*.

plot_kappa_Pstar(*, axis=None, label=None, FIGSIZE=None, pstar_max=None, kappa_SI_min=None, kappa_SI_max=None, pstar_tick=None, kappa_tick=None)

Plots the value of kappa as a function of P*. :param current: current object to plot :param axis: matplotlib.axes.Axes object (if None, create one) :param label: :param FIGSIZE: size of the plot

Returns

a matplotlib.axes.Axes object

plot_periodogram(PSD_FILTER_W=None, *, freq_units='THz', freq_scale=1.0, axes=None, kappa_units=True, 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 – matplotlib.axes.Axes object (if None, create one)

  • kappa_units – 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 [True]

  • 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.

NOTE If called by a subclass, it will change the plotter of the base class (Current) and all its subclasses. If this is not a good behavior, we should change it in the future.

timeseries()

Return a time series (fs units).