Model Decomposition¶

class
sails.modal.
MvarModalDecomposition
[source]¶ Object which calculates the modal decomposition of a fitted model derived from the AbstractLinearModel class. This is typically created using the
initialise()
classmethod which computes the decomposition and returns a populated object instance.
compute_modal_parameters
()[source]¶ Compute the order 1 or 2 autoregressive coefficients associated with each pole or conjugate pair.
Warning
This function is a work in progress and has not been fully validated.
Returns: Array containing the timedomain AR parameters for each mode Return type: ndarray

compute_residues
()[source]¶ Compute the residue matrix from the eigenvectors associated with each pole.
Returns: Array containing residue matrices for each pole. Return type: ndarray

excitation
(resid_cov)[source]¶ Compute the mode excitation as defined in [Neumaier2001]. This is a metric to quantify the dynamical importance of each mode in the decomposition.
Warning
This function is a work in progress and has not been fully validated.
Parameters: resid_cov (ndarray) – Residual covariance matrix for modelled system Returns: Vector containing modal excitation values Return type: ndarray

get_mode_inds
(fmin=0, fmax=None, mag_thresh=0, resid_thresh=0, index_mode='inclusive')[source]¶ Helper function to identify mode indices based on given criteria.
Parameters:  fmin (float) – Minimum frequency of modes to include (Default value = 0)
 fmax (float) – Maximum frequency of modes to include (Default value = None)
 mag_thresh (float ( 0 > mag_thresh > 1 )) – Minimum pole magnitude to include (Default value = 0)
 resid_thresh (float) – Minimum value of mode residue norm to include (Default value = 0)
 index_mode ({'inclusive','exclusive'}) – Flag indicating whether mode selection limits should be inclusive or exclusive (Default value = ‘inclusive’)
Returns: Array of integers indexing the included poles
Return type: ndarray

classmethod
initialise
(model, sample_rate=None, normalise=False)[source]¶ Compute the modal poleresidue decomposition of the A matrix from a fitted MVAR model.
Currently only implemented for a single realisation (A.ndim == 3)
Parameters:  model (LinearModel) – Fitted model object. Must be derived from AbstractLinearModel.
 sample_rate (float) – sample rate of system in Hz (Default value = None)
 normalise (bool) – Whether to adjust the phase of the eigenvectors (Default value = False)
Returns: Modal decomposition object
Return type: type

modal_timecourse
(data)[source]¶ Compute the modal timecourse from a dataset and a fitted model. This is the transformation of a set of [nsignals x time] data observations into modal coordinates of shape [nmodes x time].
Warning
This function is a work in progress and has not been fully validated.
Parameters: data (ndarray) – Input data to convert into modal coordinates Returns: Data transformed into modal timeseries Return type: ndarray

modal_transfer_function
(sample_rate, modes=None)[source]¶ Compute a transfer function matrix based on the excitation period for each mode
Parameters:  sample_rate (float) – sample rate of system in Hz
 modes (list of int) – List of mode indices to evaluate over (optional) (Default value = None)
Returns: Transfer function computed for each mode
Return type: ndarray

mode_indices
¶ Returns a list of tuples of mode indices where each tuple contains the indices of either a polepair or an unpaired pole
Returns: list of tuples containing indices into the modes Return type: List

per_mode_transfer_function
(sample_rate, freq_vect)[source]¶ Extracts the transfer function for each mode by summing the transfer function across polepairs where necessary
The transfer function is computed for each pole using
transfer_function()
before summing individual modes (real valued poles or complexconjugate pairs).Parameters:  sample_rate – sample rate of system in Hz
 freq_vect – Vector of frequencies at which to evaluate function
Returns: Array containing the transfer function for each individual mode
Return type: ndarray

period_hz
¶ This is an old and deprecated way of accessing peak_frequency

pole_plot
(ax=None, normscale=50, plottype='unitcircle')[source]¶ Plot the poles of the current system.
Parameters:  ax (matplotlib axes handle) – Optional axis on which to plot (Default value = None)
 normscale (float) – Scaling factor for points on plot (Default value = 50)
 plottype ({'unitcircle','eigenspectrum'}) – Flag indicating whether to plot results on a unitcircle or an eigenspectrum (Default value = ‘unitcircle’)
Returns: Reference to axes on which plot was drawn
Return type: matplotlib axes handle

residue_norm
¶ The matrixnorm of the residue matrix of each mode

transfer_function
(sample_rate, freq_vect, modes=None, sum_modes=True)[source]¶ Compute the transfer function in poleresidue form, splitting the system into modes with separate transfer functions. The full system transfer function is then a linear sum of each modal transfer function.
When sum_modes is False, this function returns the transfer function for each individual pole (ie will return a transfer function for each pole in a conjugate pair). Please use per_mode_transfer_function to compute the transfer function for individual modes (ie one transfer function for each real pole or complexconjugate pair)
Parameters:  sample_rate (float) – sample rate of system in Hz
 freq_vect (ndarray) – Vector of frequencies at which to evaluate function
 modes (list of ints) – List of mode indices to evaluate over (optional) (Default value = None)
 sum_modes (bool) – Boolean indicating whether to sum modes or return all (Default value = True)
Returns: Array containing the transfer function for each individual pole
Return type: ndarray
