Utility Functions

A group of useful functions

modred.util.Hankel(first_col, last_row=None)

Construct a Hankel array, whose skew diagonals are constant.

Args:

first_col: 1D array corresponding to first column of Hankel array.

Kwargs:

last_row: 1D array corresponding to the last row of Hankel array. First element will be ignored. Default is an array of zeros of the same size as first_col.

Returns:

Hankel: 2D array with dimensions [len(first_col), len(last_row)].

modred.util.Hankel_chunks(first_col_chunks, last_row_chunks=None)

Construct a Hankel array using chunks, whose elements have Hankel structure at the chunk level (constant along skew diagonals), rather than at the element level.

Args:

first_col_chunks: List of 2D arrays corresponding to the first column of Hankel array chunks.

Kwargs:

last_row_chunks: List of 2D arrays corresponding to the last row of Hankel array chunks. Default is a list of arrays of zeros.

Returns:

Hankel: 2D array with dimension [len(first_col) * first_col[0].shape[0], len(last_row) * last_row[0].shape[1]].

class modred.util.InnerProductBlock(inner_product)

Only used in tests. Takes inner product of all vectors.

exception modred.util.UndefinedError

modred.util.atleast_2d_col(array)

Converts 1d arrays to 2d arrays, but always as column vectors

modred.util.atleast_2d_row(array)

Converts 1d arrays to 2d arrays, but always as row vectors

modred.util.balanced_truncation(A, B, C, order=None, return_sing_vals=False)

Balance and truncate discrete-time linear time-invariant (LTI) system defined by A, B, C arrays. It’s not very accurate due to numerical issues.

Args:

A, B, C: LTI discrete-time arrays.

Kwargs:

order: Order (number of states) of truncated system. Default is to use the maximal possible value (can truncate system afterwards).

Returns:

A_balanced, B_balanced, C_balanced: LTI discrete-time arrays of balanced system.

If return_sing_vals is True, also returns:

sing_vals: Hankel singular values.

Notes:

• D is unchanged by balanced truncation.
• This function is not computationally efficient or accurate relative to Matlab’s balancmr.

modred.util.drss(num_states, num_inputs, num_outputs)

Generates a discrete-time random state-space system.

Args:

num_states: Number of states.

num_inputs: Number of inputs.

num_outputs: Number of outputs.

Returns:

A, B, C: State-space arrays of discrete-time system.

By construction, all eigenvalues are real and stable.

modred.util.eig_biorthog(array, scale_choice='left')

Wrapper for numpy.linalg.eig that returns both left and right eigenvectors. Eigenvalues and eigenvectors are sorted and scaled so that the left and right eigenvector arrays are orthonormal.

Args:

array: Array to take eigendecomposition of.

Kwargs:

scale_choice: Determines whether ‘left’ (default) or ‘right’ eigenvectors will be scaled to yield a biorthonormal set. The other eigenvectors will be left unscaled, leaving them with unit norms.

Returns:

evals: 1D array of eigenvalues.

R_evecs: Array whose columns are right eigenvectors.

L_evecs: Array whose columns are left eigenvectors.

modred.util.eigh(array, atol=1e-13, rtol=None, is_positive_definite=False)

Wrapper for numpy.linalg.eigh. Computes eigendecomposition of a Hermitian array.

Args:

array: Array to take eigendecomposition of.

atol: Value below which eigenvalues (and corresponding eigenvectors) are truncated.

rtol: Maximum relative difference between largest and smallest eigenvalues. Smaller ones are truncated.

is_positive_definite: If true, array being decomposed will be assumed to be positive definite. Tolerance will be automatically adjusted (if necessary) so that only positive eigenvalues are returned.

Returns:

eigvals: 1D array of eigenvalues, sorted in descending order (of magnitude).

eigvecs: Array whose columns are eigenvectors.

modred.util.flatten_list(my_list)

Flatten a list of lists into a single list.

modred.util.get_data_members(obj)

Returns a dictionary containing data members of obj.

modred.util.get_file_list(directory, file_extension=None)

Returns list of files in directory with file_extension.

modred.util.impulse(A, B, C, num_time_steps=None)

Generates impulse response outputs for a discrete-time system.

Args:

A, B, C: State-space system arrays.

Kwargs:

num_time_steps: Number of time steps to simulate.

Returns:

outputs: Impulse response outputs, with indices corresponding to [time step, output, input].

No D array is included, but one can simply be prepended to the output if it is non-zero.

modred.util.load_array_text(file_name, delimiter=None, is_complex=False)

Reads data saved in a text file, returns an array.

Args:

file_name: Name of file from which to load data.

Kwargs:

delimiter: Delimiter in file. Default is same as numpy.loadtxt.

is_complex: Boolean describing whether the data to be loaded is complex valued.

Returns:

array: 2D array containing loaded data.

See save_array_text() for the format used by this function.

modred.util.load_multiple_signals(signal_paths, delimiter=None)

Loads multiple signal files from text files with columns [t channel1 channel2 …].

Args:

signal_paths: List of filepaths to files containing signals.

Returns:

time_values: 1D array of time values.

all_signals: Array of signals with indices [path, time, signal].

See load_signals().

modred.util.load_signals(signal_path, delimiter=None)

Loads signals from text files with columns [t signal1 signal2 …].

Args:

signal_paths: List of filepaths to files containing signals.

Returns:

time_values: 1D array of time values.

signals: Array of signals with dimensions [time, signal].

Convenience function. Example file has format:

0 0.1 0.2
1 0.2 0.46
2 0.2 1.6
3 0.6 0.1

modred.util.lsim(A, B, C, inputs, initial_condition=None)

Simulates a discrete-time system with arbitrary inputs.

Args:

A, B, and C: State-space system arrays.

inputs: Array of inputs , with dimensions [num_time_steps, num_inputs].

Kwargs:

initial_condition: Initial condition .

Returns:

outputs: Array of outputs , with dimensions [num_time_steps, num_outputs].

D array is assumed to be zero.

modred.util.make_iterable(arg)

Checks if arg is iterable. If not, makes it a one-element list. Otherwise returns arg.

modred.util.rss(num_states, num_inputs, num_outputs)

Generates a continuous-time random state-space system.

Args:

num_states: Number of states.

num_inputs: Number of inputs.

num_outputs: Number of outputs.

Returns:

A, B, C: State-space arrays of continuous-time system.

By construction, all eigenvalues are real and stable.

modred.util.save_array_text(array, file_name, delimiter=None)

Saves a 1D or 2D array to a text file.

Args:

array: 1D or 2D or array to save to file.

file_name: Filepath to location where data is to be saved.

Kwargs:

delimiter: Delimiter in file. Default is same as numpy.savetxt.

Format of saved files is:

2.3 3.1 2.1 ...
5.1 2.2 9.8 ...
7.6 3.1 5.5 ...
0.1 1.9 9.1 ...
...

Complex data is saved in the following format (as floats):

real[0,0] imag[0,0] real[0,1] imag[0,1] ...
real[1,0] imag[1,0] real[1,1] imag[1,1] ...
...

Files can be read in Matlab with the provided functions or often with Matlab’s load.

modred.util.smart_eq(arg1, arg2)

Checks for equality, accounting for the fact that numpy’s == doesn’t return a bool. In that case, returns True only if all elements are equal.

modred.util.sum_arrays(arr1, arr2)

Used for allreduce command.

modred.util.sum_lists(list1, list2)

Sums the elements of each list, returns a new list.

This function is used in MPI reduce commands, but could be used elsewhere too.

modred.util.svd(array, atol=1e-13, rtol=None)

Wrapper for numpy.linalg.svd, computes the singular value decomposition of an array.

Args:

array: Array to take singular value decomposition of.

Kwargs:

atol: Level below which singular values are truncated.

rtol: Maximum relative difference between largest and smallest singular values. Smaller ones are truncated.

Returns:

U: Array whose columns are left singular vectors.

S: 1D array of singular values.

V: Array whose columns are right singular vectors.

Truncates U, S, and V such that the singular values obey both atol and rtol.