Utilities

Calculus on time series

GWFrames.ScalarDerivative(f: ndarray, t: ndarray) → ndarray

Differentiate a real function of time by finite differences.

The times need not be uniformly spaced. When there are at least five points, the fourth-order five-point formula of Eq. (A 5b) of Bowen and Smith, “Derivative formulas and errors for non-uniformly spaced points”, is used. With three or four points a three-point formula is used, and with two points the derivative is the slope of the line through them. Fewer than two points raise an error.

Parameters:

  • f (array_like of float) – Values of the function.

  • t (array_like of float) – Times corresponding to the elements of f; the two must have the same length.

Returns:

ndarray of float – The derivative at each time.

GWFrames.ComplexDerivative(f: ndarray, t: ndarray) → ndarray

Differentiate a complex function of time by finite differences.

This is the complex counterpart of ScalarDerivative, and uses the same formulas.

Parameters:

  • f (array_like of complex) – Values of the function.

  • t (array_like of float) – Times corresponding to the elements of f; the two must have the same length.

Returns:

ndarray of complex – The derivative at each time.

GWFrames.ScalarIntegral(fdot: ndarray, t: ndarray) → ndarray

Integrate a scalar function of time by the trapezoidal rule.

The integral is cumulative: element i of the result is the integral from t[0] to t[i], so that the first element is zero.

Parameters:

  • fdot (array_like of float) – Values of the integrand.

  • t (array_like of float) – Times corresponding to the elements of fdot; the two must have the same length.

Returns:

ndarray of float – The integral at each time.

See also

CumulativeScalarIntegral

The integral over the whole time span.

GWFrames.CumulativeScalarIntegral(fdot: ndarray, t: ndarray) → float

Integrate a scalar function over its whole time span by the trapezoidal rule.

Despite the name, only the total is returned: the result is the integral from t[0] to t[-1], which is the last element of the result of ScalarIntegral.

Parameters:

  • fdot (array_like of float) – Values of the integrand.

  • t (array_like of float) – Times corresponding to the elements of fdot; the two must have the same length.

Returns:

float – The integral over the whole time span.

GWFrames.VectorIntegral(fdot: ndarray, t: ndarray) → ndarray

Integrate a vector function of time by the trapezoidal rule.

Each component is integrated separately, as in ScalarIntegral. The integral is cumulative: row i of the result is the integral from t[0] to t[i], so that the first row is zero.

Parameters:

  • fdot (array_like of float, shape (N, M)) – Values of the integrand, with time along the first axis.

  • t (array_like of float, shape (N,)) – Times corresponding to the rows of fdot.

Returns:

ndarray of float, shape (N, M) – The integral at each time.

GWFrames.CumulativeVectorIntegral(fdot: ndarray, t: ndarray) → ndarray

Integrate a vector function over its whole time span by the trapezoidal rule.

Despite the name, only the total is returned: the result is the integral from t[0] to t[-1], which is the last row of the result of VectorIntegral.

Parameters:

  • fdot (array_like of float, shape (N, M)) – Values of the integrand, with time along the first axis.

  • t (array_like of float, shape (N,)) – Times corresponding to the rows of fdot.

Returns:

ndarray of float, shape (M,) – The integral over the whole time span.

GWFrames.Unwrap(In: ndarray) → ndarray

Unwrap a phase so that it is (roughly) continuous.

Multiples of \(2\pi\) are added to the elements of In so that the difference between successive elements of the result lies between \(-\pi\) and \(\pi\). This is the algorithm of MATLAB’s unwrap.

Parameters:

In (array_like of float) – The phase, in radians.

Returns:

ndarray of float – The unwrapped phase, with the same length as In.

Time series

GWFrames.Intersection(
t1: ndarray,
t2: ndarray,
MinStep: float = 0.005,
MinTime: float = -1e+300,
MaxTime: float = 1e+300,
) → ndarray

Return a time series covering the intersection of two time series.

The result starts at the latest of t1[0], t2[0], and MinTime, and ends no later than the earliest of t1[-1], t2[-1], and MaxTime. The step from each time to the next is the smaller of the local steps of t1 and t2 at that time, or MinStep if that is larger. Both inputs are assumed to be strictly increasing. An error is raised if either input is empty or the intersection is empty.

Parameters:

  • t1 (array_like of float) – The first time series.

  • t2 (array_like of float) – The second time series.

  • MinStep (float, default 0.005) – Smallest time step in the result.

  • MinTime (float, default -1e300) – Earliest time allowed in the result.

  • MaxTime (float, default 1e300) – Latest time allowed in the result.

Returns:

ndarray of float – The new time series.

See also

Union

GWFrames.Union(t1: ndarray, t2: ndarray, MinStep: float = 0.005) → ndarray

Return a time series covering the union of two time series.

The result runs from the earlier of t1[0] and t2[0] to the later of t1[-1] and t2[-1]. Where only one input covers a time, the step from that time to the next is the local step of that input; where both do, it is the smaller of the two local steps. In either case the step is never smaller than MinStep. Both inputs are assumed to be strictly increasing. If one input is empty, the other is returned; if the two do not overlap, an error is raised.

Parameters:

  • t1 (array_like of float) – The first time series.

  • t2 (array_like of float) – The second time series.

  • MinStep (float, default 0.005) – Smallest time step in the result.

Returns:

ndarray of float – The new time series.

See also

Intersection

Matrices

class GWFrames.Matrix

Real matrix stored in a GSL matrix.

This class is a thin wrapper around a GSL matrix of floats. It is used as the input to the eigen-system helpers, such as DominantPrincipalAxis and Eigensystem, most of which require a symmetric \(3\times3\) matrix. It is rarely needed directly. The element in row row and column col is returned by M(row, col), and the method Matrix.numpy returns a copy of all the elements as a numpy array. The difference M1 - M2 of two matrices of the same shape is taken element by element, and the product M * b with a sequence b of M.ncols() floats is the matrix-vector product, returned as a numpy array.

A matrix with zero rows or zero columns is empty: it has no storage, and it reports zero rows and zero columns. An empty matrix may be copied, printed, converted to a numpy array of shape (0, 0), resized, and cleared.

A Matrix may be constructed in any of these ways:

Matrix()

An empty matrix, which may be given a size with Matrix.resize.

Matrix(rows, cols)

A matrix of zeros with rows rows and cols columns.

Matrix(rows, cols, a)

A matrix with rows rows and cols columns, each of whose elements is the float a.

Matrix(M)

A copy of the matrix M.

Matrix(DataIn)

A matrix with the elements of DataIn, a sequence of rows, each of which is a sequence of floats. All rows must have the same length, or ValueError is raised. The matrix is empty if DataIn or its rows are empty.

classmethod __new__(*args, **kwargs)
Matrix.nrows() → int

Return the number of rows of this matrix.

Returns:

int – The number of rows.

Matrix.ncols() → int

Return the number of columns of this matrix.

Returns:

int – The number of columns.

Matrix.set(row: int, col: int, value: float) → Matrix

Set one element of this matrix.

Parameters:

  • row (int) – Index of the row.

  • col (int) – Index of the column.

  • value (float) – New value of the element.

Returns:

Matrix – This object, modified in place.

Matrix.resize(newNRows: int, newNCols: int, value: float = 0.0) → None

Change the shape of this matrix, discarding its contents.

The previous elements are not preserved; every element of the resized matrix is set to value. If either new dimension is zero, the matrix becomes empty.

Parameters:

  • newNRows (int) – New number of rows.

  • newNCols (int) – New number of columns.

  • value (float, default 0.0) – Value given to every element.

Matrix.clear() → None

Release the storage of this matrix, leaving it empty.

Afterward the matrix has zero rows and zero columns, and it may be given a new size with Matrix.resize. Clearing an empty matrix does nothing.

Matrix.numpy() → numpy.typing.NDArray[numpy.float64]

Return a copy of this Matrix as a two-dimensional numpy array.

GWFrames.Determinant(M: Matrix) → float

Return the determinant of a \(3\times3\) matrix.

Parameters:

M (Matrix) – A \(3\times3\) matrix; any other shape raises an error.

Returns:

float – The determinant.

GWFrames.Eigenvalues(M: Matrix) → ndarray

Return the eigenvalues of a symmetric matrix in decreasing order.

Parameters:

M (Matrix) – A symmetric \(3\times3\) matrix. It is modified; see the notes.

Returns:

ndarray of float, shape (3,) – The eigenvalues, from largest to smallest.

Notes

The eigen-system is computed by GSL’s gsl_eigen_symmv, which uses only the diagonal and lower triangle of M and overwrites them. Pass a copy if the matrix will be needed afterward.

GWFrames.Eigenvectors(M: Matrix) → ndarray

Return the eigenvectors of a symmetric matrix.

The eigenvectors are normalized and ordered by decreasing eigenvalue, and are returned one after another in a flat array: elements 3*j through 3*j+2 are the eigenvector with the j-th largest eigenvalue.

Parameters:

M (Matrix) – A symmetric \(3\times3\) matrix. It is modified; see the notes.

Returns:

ndarray of float, shape (9,) – The three eigenvectors, concatenated.

Notes

The eigen-system is computed by GSL’s gsl_eigen_symmv, which uses only the diagonal and lower triangle of M and overwrites them. Pass a copy if the matrix will be needed afterward.

GWFrames.Eigensystem(M: Matrix) → ndarray

Return the eigenvectors and eigenvalues of a symmetric matrix.

The eigenpairs are ordered by decreasing eigenvalue, and are returned one after another in a flat array: elements 4*j through 4*j+2 are the normalized eigenvector with the j-th largest eigenvalue, and element 4*j+3 is that eigenvalue.

Parameters:

M (Matrix) – A symmetric \(3\times3\) matrix. It is modified; see the notes.

Returns:

ndarray of float, shape (12,) – The three eigenpairs, concatenated.

Notes

The eigen-system is computed by GSL’s gsl_eigen_symmv, which uses only the diagonal and lower triangle of M and overwrites them. Pass a copy if the matrix will be needed afterward.

GWFrames.DominantPrincipalAxis(M: Matrix) → ndarray

Return the eigenvector of a symmetric matrix with the largest eigenvalue.

Parameters:

M (Matrix) – A symmetric \(3\times3\) matrix. It is modified; see the notes.

Returns:

ndarray of float, shape (3,) – The normalized eigenvector belonging to the largest eigenvalue.

Notes

The eigen-system is computed by GSL’s gsl_eigen_symmv, which uses only the diagonal and lower triangle of M and overwrites them. Pass a copy if the matrix will be needed afterward.

GWFrames.SubordinatePrincipalAxis(M: Matrix) → ndarray

Return the eigenvector of a symmetric matrix with the smallest eigenvalue.

Parameters:

M (Matrix) – A symmetric \(3\times3\) matrix. It is modified; see the notes.

Returns:

ndarray of float, shape (3,) – The normalized eigenvector belonging to the smallest eigenvalue.

Notes

The eigen-system is computed by GSL’s gsl_eigen_symmv, which uses only the diagonal and lower triangle of M and overwrites them. Pass a copy if the matrix will be needed afterward.

GWFrames.DominantPrincipalValue(M: Sequence[Matrix]) → ndarray

Return the largest eigenvalue of each of a sequence of symmetric matrices.

Each matrix must be a symmetric \(3\times3\) Matrix; only the shape of the first is checked. The eigenvalues are computed with GSL from the diagonal and lower triangle of each matrix.

Parameters:

M (list of Matrix) – The matrices.

Returns:

ndarray of float – The largest eigenvalue of each matrix.

GWFrames.SubordinatePrincipalValue(M: Sequence[Matrix]) → ndarray

Return the smallest eigenvalue of each of a sequence of symmetric matrices.

Each matrix must be a symmetric \(3\times3\) Matrix; only the shape of the first is checked. The eigenvalues are computed with GSL from the diagonal and lower triangle of each matrix.

Parameters:

M (list of Matrix) – The matrices.

Returns:

ndarray of float – The smallest eigenvalue of each matrix.