general_utils.py

Some miscellaneous utility functions.

class openmdao.utils.general_utils.ContainsAll

Bases: object

A fake dictionary that always reports __contains__(name) to be True.

__contains__(name)

Return if the named object is contained.

Parameters:

namestr

Name of the object being looked up.

Returns:

bool

Always returns True.

class openmdao.utils.general_utils.LocalRangeIterable(system, vname, use_vec_offset=True)

Bases: object

Iterable object yielding local indices while iterating over local, distributed, or remote vars.

The number of iterations for a distributed variable will be the full distributed size of the variable.

None will be returned for any indices that are not local to the given rank.

Parameters:

systemSystem

Containing System.

vnamestr

Name of the variable.

use_vec_offsetbool

If True, return indices for the given variable within its parent vector, else just return indices within the variable itself, i.e. range(var_size).

Attributes:

_vnamestr

Name of the variable.

_indsndarray

Variable indices (unused for distributed variables).

_var_sizeint

Full size of distributed or remote variable.

_startint

Starting index of distributed variable on this rank.

_endint

Last index + 1 of distributed variable on this rank.

_offsetint

Offset of this variable into the local vector,.

_itermethod

The iteration method used.

__init__(system, vname, use_vec_offset=True)

Initialize the iterator.

__iter__()

Return an iterator.

Returns:

iterator

An iterator over our indices.

openmdao.utils.general_utils.add_border(msg, borderstr='=', vpad=0)

Add border lines before and after a message.

The message is assumed not to span multiple lines.

Parameters:

msgstr

The message to be enclosed in a border.

borderstrstr

The repeating string to be used in the border.

vpadint

The number of blank lines between the border and the message (before and after).

Returns:

str

A string containing the original message enclosed in a border.

openmdao.utils.general_utils.all_ancestors(pathname, delim='.')

Return a generator of pathnames of the starting object and all of its parents.

Pathnames are ordered from longest to shortest.

Parameters:

pathnamestr

Pathname of starting object.

delimstr

Delimiter used to split the name.

Yields:

str

openmdao.utils.general_utils.call_depth2indent(tabsize=2, offset=- 1)

Return a string of spaces corresponding to the current call depth.

Parameters:

tabsizeint

Number of spaces per tab.

offsetint

Offset to add to the call depth.

Returns:

str

A string of spaces.

openmdao.utils.general_utils.common_subpath(pathnames)

Return the common dotted subpath found in all of the given dotted pathnames.

Parameters:

pathnameslist or tuple of str

Dotted pathnames of systems.

Returns:

str

Common dotted subpath. Returns ‘’ if no common subpath is found.

openmdao.utils.general_utils.convert_src_inds(parent_src_inds, parent_src_shape, my_src_inds, my_src_shape)

Compute lower level src_indices based on parent src_indices.

Parameters:

parent_src_indsndarray

Parent src_indices.

parent_src_shapetuple

Shape of source expected by parent.

my_src_indsndarray or fancy index

Src_indices at the current system level, before conversion.

my_src_shapetuple

Expected source shape at the current system level.

Returns:

ndarray

Final src_indices based on those of the parent.

openmdao.utils.general_utils.dbg(funct)

Do nothing.

Parameters:

functfunction

The function being decorated.

Returns:

function

The function.

openmdao.utils.general_utils.default_noraise(o)

Try to convert some extra types during JSON serialization.

This is intended to be passed to json.dump or json.dumps as the ‘default’ arg. It will attempt to convert values if possible, but if no conversion works, will return ‘unserializable object (<type>)’ instead of raising a TypeError.

Parameters:

oobject

The object to be converted.

Returns:

object

The converted object.

openmdao.utils.general_utils.determine_adder_scaler(ref0, ref, adder, scaler)

Determine proper values of adder and scaler based on user arguments.

Adder and Scaler are used internally because the transformation is slightly more efficient.

Parameters:

ref0float or ndarray, optional

Value of response variable that scales to 0.0 in the driver.

reffloat or ndarray, optional

Value of response variable that scales to 1.0 in the driver.

adderfloat or ndarray, optional

Value to add to the model value to get the scaled value. Adder is first in precedence.

scalerfloat or ndarray, optional

Value to multiply the model value to get the scaled value. Scaler is second in precedence.

Returns:

tuple

Adder and scaler, properly formatted and based on ref/ref0 if provided.

Raises:

ValueError

If both ref/ref0 and adder/scaler were provided.

Notes

The response can be scaled using ref and ref0. The argument ref0 represents the physical value when the scaled value is 0. The argument ref represents the physical value when the scaled value is 1.

openmdao.utils.general_utils.do_nothing_context()

Do nothing.

Useful when you have a block of code that only requires a context manager sometimes, and you don’t want to repeat the context managed block.

Returns:

contextmanager

A do nothing context manager.

openmdao.utils.general_utils.dprint(*args, **kwargs)

Print only if OM_DBG is truthy in the environment.

Parameters:

argslist

Positional args.

kwargsdict

Named args.

openmdao.utils.general_utils.ensure_compatible(name, value, shape=None, indices=None)

Make value compatible with the specified shape or the shape of indices.

Parameters:

namestr

The name of the value.

valuefloat or list or tuple or ndarray or Iterable

The value of a variable.

shapeint or tuple or list or None

The expected or desired shape of the value.

indicesIndexer or None

The indices into a source variable.

Returns:

ndarray

The value in a shape compatible with the specified shape and/or indices.

tuple

The resulting shape of the value.

Raises:

ValueError

If value cannot be made to conform to shape or if shape and indices are incompatible.

openmdao.utils.general_utils.env_none(env_var)

Return True if the given environment variable is None.

Parameters:

env_varstr

The name of the environment variable.

Returns:

bool

True if the specified environment variable is None.

openmdao.utils.general_utils.env_truthy(env_var)

Return True if the given environment variable is ‘truthy’.

Parameters:

env_varstr

The name of the environment variable.

Returns:

bool

True if the specified environment variable is ‘truthy’.

openmdao.utils.general_utils.find_matches(pattern, var_list)

Return list of variable names that match given pattern.

Parameters:

patternstr

Glob pattern or variable name.

var_listlist of str

List of variable names to search for pattern.

Returns:

list

Variable names that match pattern.

openmdao.utils.general_utils.format_as_float_or_array(name, values, val_if_none=0.0, flatten=False)

Format array option values.

Checks that the given array values are either None, float, or an iterable of numeric values. On output all iterables of numeric values are converted to a flat np.ndarray. If values is scalar, it is converted to float.

Parameters:

namestr

The path of the variable relative to the current system.

valuesfloat or numpy ndarray or Iterable

Values of the array option to be formatted to the expected form.

val_if_nonefloat or numpy ndarray

The default value for the option if values is None.

flattenbool

Set to True to flatten any ndarray return.

Returns:

float or np.ndarray

Values transformed to the expected form.

Raises:

ValueError

If values is Iterable but cannot be converted to a numpy ndarray

TypeError

If values is scalar, not None, and not a Number.

openmdao.utils.general_utils.get_connection_owner(system, tgt)

Return (owner, promoted_src, promoted_tgt) for the given connected target.

Note : this is not speedy. It’s intended for use only in error messages.

Parameters:

systemSystem

Any System. The search always goes from the model level down.

tgtstr

Absolute pathname of the target variable.

Returns:

tuple

(owning group, promoted source name, promoted target name).

openmdao.utils.general_utils.get_rev_conns(conns)

Return a dict mapping each connected output to a list of its connected inputs.

Parameters:

connsdict

Dict mapping each input to its connected output.

Returns:

dict

Dict mapping each connected output to a list of its connected inputs.

openmdao.utils.general_utils.inconsistent_across_procs(comm, arr, tol=1e-15, return_array=True)

Check serial deriv values across ranks.

This should only be run after _apply_linear.

Parameters:

commMPI communicator

Communicator belonging to the component that owns the derivs array.

arrndarray

The array being checked for consistency across processes.

tolfloat

Tolerance to determine if diff is 0.

return_arraybool

If True, return a boolean array on rank 0 indicating which indices are inconsistent.

Returns:

ndarray on rank 0, boolean elsewhere, or bool everywhere if return_array is False

On rank 0, boolean array with True in entries that are not consistent across all processes in the communicator. On other ranks, True if there are inconsistent entries.

openmdao.utils.general_utils.is_truthy(s)

Return True if the given string is ‘truthy’.

Parameters:

sstr

The name string being tested.

Returns:

bool

True if the specified string is ‘truthy’.

openmdao.utils.general_utils.make_serializable(o)

Recursively convert numpy types to native types for JSON serialization.

This function should NOT be passed into json.dump or json.dumps as the ‘default’ arg.

Parameters:

oobject

The object to be converted.

Returns:

object

The converted object.

openmdao.utils.general_utils.make_serializable_key(o)

Recursively convert numpy types to native types for JSON serialization.

This function is for making serizializable dictionary keys, so no containers. This function should NOT be passed into json.dump or json.dumps as the ‘default’ arg.

Parameters:

oobject

The object to be converted.

Returns:

object

The converted object.

openmdao.utils.general_utils.make_set(str_data, name=None)

Construct a set containing the specified character strings.

Parameters:

str_dataNone, str, or list of strs

Character string(s) to be included in the set.

namestr, optional

A name to be used in error messages.

Returns:

set

A set of character strings.

openmdao.utils.general_utils.make_traceback()

Create a traceback for use later with an exception.

The traceback will begin at the stack frame above the caller of make_traceback.

Returns:

traceback

The newly constructed traceback.

openmdao.utils.general_utils.match_includes_excludes(name, includes=None, excludes=None)

Check to see if the variable name passes through the includes and excludes filter.

Parameters:

namestr

Name to be checked for match.

includesiter of str or None

Glob patterns for name to include in the filtering. None, the default, means include all.

excludesiter of str or None

Glob patterns for name to exclude in the filtering.

Returns:

bool

Return True if the name passes through the filtering of includes and excludes.

openmdao.utils.general_utils.match_prom_or_abs(name, prom_name, includes=None, excludes=None)

Check to see if the variable names pass through the includes and excludes filter.

Parameters:

namestr

Unpromoted variable name to be checked for match.

prom_namestr

Promoted variable name to be checked for match.

includesiter of str or None

Glob patterns for name to include in the filtering. None, the default, means to include all.

excludesiter of str or None

Glob patterns for name to exclude in the filtering.

Returns:

bool

Return True if the name passes through the filtering of includes and excludes.

openmdao.utils.general_utils.meta2src_iter(meta_iter)

Yield the source name for each metadata dict in the given iterator.

Parameters:

meta_iteriter of dict

Iterator over metadata dicts.

Yields:

str

The source name for each metadata dict.

openmdao.utils.general_utils.om_dump(*args, **kwargs)

Do nothing.

Parameters:

*argslist

Positional args.

**kwargsdict

Named args.

openmdao.utils.general_utils.pad_name(name, width=10, quotes=False)

Pad a string so that they all line up when stacked.

Parameters:

namestr

The string to pad.

widthint

The number of total spaces the string should take up.

quotesbool

If name should be quoted.

Returns:

str

Padded string.

openmdao.utils.general_utils.pattern_filter(patterns, var_iter, name_index=None)

Yield variable names that match a given pattern.

Parameters:

patternsiter of str

Glob patterns or variable names.

var_iteriter of str or iter of tuple/list

Iterator of variable names (or tuples containing variable names) to search for patterns.

name_indexint or None

If not None, the var_iter is assumed to yield tuples, and the name_index is the index of the variable name in the tuple.

Yields:

str

Variable name that matches a pattern.

openmdao.utils.general_utils.printoptions(*args, **kwds)

Context manager for setting numpy print options.

Set print options for the scope of the with block, and restore the old options at the end. See numpy.set_printoptions for the full description of available options. If any invalid options are specified, they will be ignored.

>>> with printoptions(precision=2):
...     print(np.array([2.0])) / 3
[0.67]
The `as`-clause of the `with`-statement gives the current print options:
>>> with printoptions(precision=2) as opts:
...      assert_equal(opts, np.get_printoptions())

Parameters:

*argslist

Variable-length argument list.

**kwdsdict

Arbitrary keyword arguments.

Yields:

str or int

See also

set_printoptions

Set printing options.

get_printoptions

Get printing options.

openmdao.utils.general_utils.remove_whitespace(s, right=False, left=False)

Remove white-space characters from the given string.

If neither right nor left is specified (the default), then all white-space is removed.

Parameters:

sstr

The string to be modified.

rightbool

If True, remove white-space from the end of the string.

leftbool

If True, remove white-space from the beginning of the string.

Returns:

str

The string with white-space removed.

openmdao.utils.general_utils.run_driver(prob)

Call run_driver on problem and capture output.

Parameters:

probProblem

An instance of Problem.

Returns:

bool

Failure flag; True if failed to converge, False is successful.

string

Output from calling run_driver on the Problem, captured from stdout.

openmdao.utils.general_utils.run_model(prob, ignore_exception=False)

Call run_model on problem and capture output.

Parameters:

probProblem

An instance of Problem.

ignore_exceptionbool

Set to True to ignore an exception of any kind.

Returns:

string

Output from calling run_model on the Problem, captured from stdout.

openmdao.utils.general_utils.set_pyoptsparse_opt(optname, fallback=True)

For testing, sets the pyoptsparse optimizer using the given optimizer name.

This may be modified based on the value of OPENMDAO_FORCE_PYOPTSPARSE_OPT. This can be used on systems that have SNOPT installed to force them to use SLSQP in order to mimic our test machines on travis and appveyor.

Parameters:

optnamestr

Name of pyoptsparse optimizer that is requested by the test.

fallbackbool

If True, fall back to SLSQP if optname can’t be found.

Returns:

object

Pyoptsparse optimizer instance.

str

Pyoptsparse optimizer string.

openmdao.utils.general_utils.set_trace_predicate(funct)

Set the function that determines which methods will be traced.

Parameters:

functfunction

Set of functions to be traced.

openmdao.utils.general_utils.shape2tuple(shape)

Return shape as a tuple.

Parameters:

shapeint or tuple

The given shape.

Returns:

tuple or None

The shape as a tuple or None if shape is None.

openmdao.utils.general_utils.vprint(it, end='\n', getter=None, file=None)

Iterate over the given iterator and print each item separated by end.

Parameters:

ititer

Iterator to be printed.

endstr

String written after each item.

getterfunction or None

If not None, only print the part of each item returned by getter(item).

filefile-like or None

File to write to. If None, use sys.stdout.

openmdao.utils.general_utils.wing_dbg()

Make import of wingdbstub contingent on value of WING_DBG environment variable.

Also will import wingdbstub from the WINGHOME directory.