array_utils.py

Utils for dealing with arrays.

openmdao.utils.array_utils.abs_complex(x)

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)

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_hash(arr, alg=<built-in function openssl_sha1>)

Return a hash of the given numpy array.

arr must be C-contiguous.

Parameters:

arrndarray

The array to be hashed.

alghashing algorithm

Algorithm defaults to hashlib.sha1.

Returns:

str

The computed hash.

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

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)

Convert negative indices based on full array size.

Parameters:

arrndarray

The index array.

sizeint

The full size of the array.

Returns:

ndarray

The array with negative indices converted to positive.

openmdao.utils.array_utils.dv_abs_complex(x, x_deriv)

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)

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_evenly_distributed_size(comm, full_size)

Return the size of the current rank’s part of an array of the given size.

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

Parameters:

commMPI communicator

The communicator we’re distributing the array across.

full_sizeint

Number of entries in the array.

Returns:

int

The size of this rank’s part of the full distributed array.

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

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.get_random_arr(shape, comm=None, generator=None)

Request a random array, ensuring that its value will be consistent across MPI processes.

Parameters:

shapeint

Shape of the random array.

commMPI communicator or None

All members of this communicator will receive the random array.

generatorrandom number generator or None

If not None, use this as the random number generator if on rank 0.

Returns:

ndarray

The random array.

openmdao.utils.array_utils.identity_column_iter(column)

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

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.scatter_dist_to_local(dist_val, comm, sizes)

Scatter a full distributed value to local values in each MPI process.

Parameters:

dist_valndarray

The full distributed value.

commMPI communicator

The MPI communicator.

sizesndarray

The array of sizes for each process.

Returns:

ndarray

The local value on this process.

openmdao.utils.array_utils.shape_to_len(shape)

Compute length given a shape tuple.

Parameters:

shapetuple of int or None

Numpy shape tuple.

Returns:

int

Length of array.

openmdao.utils.array_utils.sizes2offsets(size_array)

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)

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)

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)

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.