# array_utils.py¶

Utils for dealing with arrays.

openmdao.utils.array_utils.abs_complex(x)[source]

Compute the absolute value of a complex-stepped vector.

Rather than taking a Euclidian norm, simply negate the values that are less than zero.

Parameters
xndarray

Input array.

Returns
ndarray

Complex-step absolute value of the array.

openmdao.utils.array_utils.array_connection_compatible(shape1, shape2)[source]

Return True if the two arrays shapes are compatible.

Array shapes are compatible if the underlying data has the same size and is stored in the same contiguous order for the two shapes.

Parameters
shape1tuple of int

Shape of the first array.

shape2tuple of int

Shape of the second array.

Returns
bool

True if the two shapes are compatible for connection, else False.

openmdao.utils.array_utils.array_viz(arr, prob=None, of=None, wrt=None, stream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)[source]

Display the structure of a boolean array in a compact form.

If prob, of, and wrt are supplied, print the name of the response alongside each row and print the names of the design vars, aligned with each column, at the bottom.

Parameters
arrndarray

Array being visualized.

probProblem or None

Problem object.

oflist of str or None

Names of response variables used in derivative calculation.

wrtlist of str or None

Names of design variables used in derivative calculation.

streamfile-like

Stream where output will be written.

openmdao.utils.array_utils.convert_neg(arr, size)[source]

Convert any negative indices into their positive equivalent.

This only works for a 1D array.

Parameters
arrndarray

Array having negative indices converted.

sizeint

Dimension of the array.

Returns
ndarray

The converted array.

openmdao.utils.array_utils.dv_abs_complex(x, x_deriv)[source]

Compute the complex-step derivative of the absolute value function and its derivative.

Parameters
xndarray

Input array, used for determining which elements to negate.

x_derivndarray

Incominng partial derivative array, may have one additional dimension.

Returns
ndarray

Absolute value applied to x.

ndarray

Absolute value applied to x_deriv.

openmdao.utils.array_utils.evenly_distrib_idxs(num_divisions, arr_size)[source]

Return evenly distributed entries for the given array size.

Given a number of divisions and the size of an array, chop the array up into pieces according to number of divisions, keeping the distribution of entries as even as possible.

Parameters
num_divisionsint

Number of parts to divide the array into.

arr_sizeint

Number of entries in the array.

Returns
tuple

A tuple of (sizes, offsets), where sizes and offsets contain values for all divisions.

openmdao.utils.array_utils.get_input_idx_split(full_idxs, inputs, outputs, use_full_cols, is_total)[source]

Split an array of indices into vec outs + ins into two arrays of indices into outs and ins.

Parameters
full_idxsndarray

Indices into the full array (which could be outs + ins or just ins).

inputsVector

Inputs vector.

outputsVector

Outputs vector.

use_full_colsbool

If True, full idxs are into the full outs + ins vector.

is_totalbool

If True, total derivatives are being computed and wrt vector is the outputs vector.

Returns
list of tuples

Each tuple is of the form (array, idxs).

openmdao.utils.array_utils.identity_column_iter(column)[source]

Yield the given column with a 1 in each position.

This is useful if you don’t want to allocate memory for the full sized identity matrix. Note that this reuses the column array and assumes that the column array has not been modified outside of this function.

Parameters
columnndarray

The array that will contain a column of the ‘virtual’ identity matrix.

Yields
ndarray

A column of the identity matrix.

openmdao.utils.array_utils.rand_sparsity(shape, density_ratio, dtype=<class 'bool'>)[source]

Return a random boolean COO matrix of the given shape with given percent density.

Row and column indices are generated using random integers so some duplication is possible, resulting in a matrix with somewhat lower density than specified.

Parameters
shapetuple

Desired shape of the matrix.

density_ratiofloat

Approximate ratio of nonzero to zero entries in the desired matrix.

dtypetype

Specifies type of the values in the returned matrix.

Returns
coo_matrix

A COO matrix with approximately the nonzero density desired.

openmdao.utils.array_utils.shape_to_len(shape)[source]

Compute length given a shape tuple.

For realistic-dimension arrays, looping over the shape tuple is much faster than np.prod.

Parameters
shapetuple

Numpy shape tuple.

Returns
int

Length of multidimensional array.

openmdao.utils.array_utils.sizes2offsets(size_array)[source]

For a given array of sizes, return an array of offsets.

Offsets will be computed using a flattened version of size_array and then reshaped to match the shape of size_array.

Parameters
size_arrayndarray

Array of sizes.

Returns
ndarray

Array of offsets.

openmdao.utils.array_utils.sparse_subinds(orig, inds)[source]

Compute new rows or cols resulting from applying inds on top of an existing sparsity pattern.

This only comes into play when we have an approx total jacobian where some dv/resp have indices.

Parameters
origndarray

Either row or col indices (part of a subjac sparsity pattern).

indsndarray or list

Sub-indices introduced when adding a desvar or response.

Returns
ndarray

New compressed rows or cols.

ndarray

Mask array that can be used to update subjac value and corresponding index array to orig.

openmdao.utils.array_utils.take_nth(rank, size, seq)[source]

Iterate returning every nth value.

Return an iterator over the sequence that returns every nth element of seq based on the given rank within a group of the given size. For example, if size = 2, a rank of 0 returns even indexed elements and a rank of 1 returns odd indexed elements.

Parameters
rankint

MPI rank of this process.

sizeint

Size of the array we’re taking nth entries from.

seqiter

Iterator containing the values being returned.

Yields
generator
openmdao.utils.array_utils.tile_sparse_jac(data, rows, cols, nrow, ncol, num_nodes)[source]

Assemble arrays necessary to define a COO sparse jacobian for a vectorized component.

These arrays can also be passed to csc_matrix or csr_matrix to create CSC and CSR sparse matrices.

Parameters
datandarray

Array of values.

rowsindex array

Array of row indices.

colsindex array

Array of column indices.

nrowint

Number of rows in sub jacobian.

ncolint

Number of columns in sub jacobian.

num_nodesint

Number of vectorized copies to tile.

Returns
ndarray, ndarray, ndarray

Arrays to define a COO sparse jacobian of size num_nodes*nrow by num_nodes*ncol.