# 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:

xndarrayInput 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 intShape of the first array.

shape2tuple of intShape 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>)[source]Return a hash of the given numpy array.

arr must be C-contiguous.

- Parameters:

arrndarrayThe array to be hashed.

alghashing algorithmAlgorithm 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'>)[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:

arrndarrayArray being visualized.

probProblem or NoneProblem object.

oflist of str or NoneNames of response variables used in derivative calculation.

wrtlist of str or NoneNames of design variables used in derivative calculation.

streamfile-likeStream where output will be written.

- openmdao.utils.array_utils.convert_neg(
arr,size)[source]Convert negative indices based on full array size.

- Parameters:

arrndarrayThe index array.

sizeintThe 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)[source]Compute the complex-step derivative of the absolute value function and its derivative.

- Parameters:

xndarrayInput array, used for determining which elements to negate.

x_derivndarrayIncominng 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_divisionsintNumber of parts to divide the array into.

arr_sizeintNumber 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)[source]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 communicatorThe communicator we’re distributing the array across.

full_sizeintNumber 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)[source]Split an array of indices into vec outs + ins into two arrays of indices into outs and ins.

- Parameters:

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

inputsVectorInputs vector.

outputsVectorOutputs vector.

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

is_totalboolIf 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)[source]Request a random array, ensuring that its value will be consistent across MPI processes.

- Parameters:

shapeintShape of the random array.

commMPI communicator or NoneAll members of this communicator will receive the random array.

generatorrandom number generator or NoneIf 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)[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:

columnndarrayThe 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:

shapetupleDesired shape of the matrix.

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

dtypetypeSpecifies 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)[source]Scatter a full distributed value to local values in each MPI process.

- Parameters:

dist_valndarrayThe full distributed value.

commMPI communicatorThe MPI communicator.

sizesndarrayThe array of sizes for each process.

- Returns:

- ndarray
The local value on this process.

- openmdao.utils.array_utils.shape_to_len(
shape)[source]Compute length given a shape tuple.

- Parameters:

shapetuple of int or NoneNumpy shape tuple.

- Returns:

- int
Length of 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_arrayndarrayArray 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:

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

indsndarray or listSub-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:

rankintMPI rank of this process.

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

seqiterIterator 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:

datandarrayArray of values.

rowsindex arrayArray of row indices.

colsindex arrayArray of column indices.

nrowintNumber of rows in sub jacobian.

ncolintNumber of columns in sub jacobian.

num_nodesintNumber 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.