array_utils.py

Utils for dealing with arrays.

class openmdao.utils.array_utils.ValueRepeater(val, size)

Bases: object

An iterable over a single value that repeats a given number of times.

Parameters:

valobject

The value to be repeated.

sizeint

The number of times to repeat the value.

Yields:

object

The value.

Attributes:

valobject

The value to be repeated.

sizeint

The number of times to repeat the value.

__contains__(item)

Return True if the given item is equal to the value.

Parameters:

itemobject

The item to be checked for containment.

__getitem__(idx)

Return the value.

Parameters:

idxint

The index of the value to be returned.

__init__(val, size)

Initialize all attributes.

__iter__()

Return an iterator over the value.

Yields:

object

The value.

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.allzero(a)

Return True if all elements of a are zero.

Parameters:

andarray

Array to be checked for zeros.

Returns:

bool

True if all elements of a are zero.

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_nans_in_nested_list(val_as_list)

Given a list, possibly nested, replace any numpy.nan values with the string “nan”.

This is done since JSON does not handle nan. This code is used to pass variable values to the N2 diagram.

The modifications to the list values are done in-place to avoid excessive copying of lists.

Parameters:

val_as_listlist

List, possibly nested, whose nan elements need to be converted.

openmdao.utils.array_utils.convert_ndarray_to_support_nans_in_json(val)

Given numpy array of arbitrary dimensions, return the equivalent nested list with nan replaced.

numpy.nan values are replaced with the string “nan”.

Parameters:

valndarray

Numpy array to be converted.

Returns:

list

The equivalent list (possibly nested) with any nan values replaced with the string “nan”.

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.csr_array_viz(arr, val_map=None, stream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

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

Parameters:

arrndarray

Array being visualized.

val_mapdict or None

Mapping of array values to characters.

streamfile-like

Stream where output will be written.

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.get_sparsity_diff_array(sparsity1, sparsity2)

Return an array showing the difference between two sparsity patterns.

Parameters:

sparsity1bool ndarray or sparse array or None

First sparsity pattern.

sparsity2bool ndarray or sparse array or None

Second sparsity pattern.

Returns:

csr_array

Sparse array of dtype int8 where: 0: zero val in both 1: non-zero val in sparsity1 3: non-zero val in sparsity2 4: non-zero val in both.

openmdao.utils.array_utils.get_tol_violation(x, ref, atol=0.0, rtol=1e-05)

Compute the max tolerance violation of the difference between x and ref.

tolerance violation is defined as:

abs(x - ref) - (atol + rtol * abs(ref))

If the result is positive, then the tolerance is violated.

Parameters:

xndarray

The test array.

refndarray

The reference array.

atolfloat

The absolute tolerance.

rtolfloat

The relative tolerance.

Returns:

tuple

Max_error, (max_x_location, max_ref_location), above_tolerance.

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.idxs2minmax_tuples(idxs)

Convert a flat array of indices into a list of contiguous (min, max) tuples.

Note that to convert these tuples to slices or ranges, you would use slice(min, max+1) or range(min, max+1).

Parameters:

idxsndarray

Array of indices.

Returns:

list

List of contiguous ranges.

openmdao.utils.array_utils.rand_sparsity(shape, density_ratio, dtype=<class 'bool'>, rng=None)

Return a random 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.

rngnp.random.Generator or None

Random number generator.

Returns:

coo_matrix

A COO matrix with approximately the nonzero density desired.

openmdao.utils.array_utils.safe_norm(arr)

Return the norm of the given array, or 0 if the array is None or empty.

Parameters:

arrndarray or None

Array to be normed.

Returns:

float

Norm of the array or 0 if the array is None or empty.

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.sparsity_diff_viz(arr1, arr2, val_map=None, stream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Display the difference between two sparsity patterns in a compact form.

Parameters:

arr1ndarray

First sparsity pattern.

arr2ndarray

Second sparsity pattern.

val_mapdict or None

Mapping of array values to characters.

streamfile-like

Stream where output will be written.

Returns:

bool

True if they agree, False otherwise.

openmdao.utils.array_utils.submat_sparsity_iter(row_var_size_iter, col_var_size_iter, nzrows, nzcols, shape)

Yield the sparsity of each submatrix, based on variable names and sizes.

Parameters:

row_var_size_iteriterator of (name, size)

Iterator of row variable names and sizes.

col_var_size_iteriterator of (name, size)

Iterator of column variable names and sizes.

nzrowsndarray

Row indices of nonzero entries in the full matrix.

nzcolsndarray

Column indices of nonzero entries in the full matrix.

shapetuple

Shape of the full matrix.

Yields:

tuple

(row_varname, col_varname, nonzero rows, nonzero cols, shape)

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.