general_utils.py

Some miscellaneous utility functions.

class openmdao.utils.general_utils.ContainsAll[source]

Bases: object

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

__contains__(name)[source]

Return if the named object is contained.

Parameters
namestr

Name of the object being looked up.

Returns
bool

Always returns True.

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

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

openmdao.utils.general_utils.common_subpath(pathnames)[source]

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

Parameters
pathnamesiter of str

Dotted pathnames of systems.

Returns
str

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

openmdao.utils.general_utils.conditional_error(msg, exc=<class 'RuntimeError'>, category=<class 'UserWarning'>)[source]

Raise an exception or issue a warning, depending on the value of _ignore_errors.

Parameters
msgstr

The error/warning message.

excexception class

This exception class is used to create the exception to be raised.

categorywarning class

This category is the class of warning to be issued.

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

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.default_noraise(o)[source]

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)[source]

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
reffloat or ndarray, optional

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

ref0float or ndarray, optional

Value of response variable that scales to 0.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()[source]

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.ensure_compatible(name, value, shape=None, indices=None)[source]

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.

indicesint or list of ints or tuple of ints or int ndarray or None

The indices of a source variable, used to determine shape if shape is None. If shape is not None, the shape of the indices must match shape.

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_truthy(env_var)[source]

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)[source]

Return list of variable names that match given pattern.

Parameters
patternstr

String pattern

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)[source]

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)[source]

Return (owner, promoted_src, promoted_tgt) for the given connected source and 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.ignore_errors(flag=None)[source]

Disable certain errors that will prevent setup from completing.

Parameters
flagbool or None

If not None, set the value of _ignore_errors to this value.

Returns
bool

The current value of _ignore_errors

openmdao.utils.general_utils.ignore_errors_context(flag=True)[source]

Set ignore_errors to the given flag in this context.

Parameters
flagbool

If not None, set ignore_errors to this value.

openmdao.utils.general_utils.json_load_byteified(file_handle)[source]

Load data from a JSON file, converting unicode to bytes if Python version is 2.x.

Intended for use only with Python 2.x, behaves the same as json.load() under Python 3.x.

Parameters
file_handlefile

file containing the data to be converted

Returns
data item or structure

data item or structure with unicode converted to bytes

openmdao.utils.general_utils.json_loads_byteified(json_str)[source]

Load data from a JSON string, converting unicode to bytes if Python version is 2.x.

Intended for use only with Python 2.x, behaves the same as json.loads() under Python 3.x.

Parameters
json_strstr

text string containing json encoded data

Returns
data item or structure

data item or structure with unicode converted to bytes

openmdao.utils.general_utils.make_serializable(o)[source]

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)[source]

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)[source]

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.match_includes_excludes(name, includes=None, excludes=None)[source]

Check to see if the variable names pass 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)[source]

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.pad_name(name, pad_num=10, quotes=False)[source]

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

Parameters
namestr

The string to pad.

pad_numint

The number of total spaces the string should take up.

quotesbool

If name should be quoted.

Returns
str

Padded string

openmdao.utils.general_utils.printoptions(*args, **kwds)[source]

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.

Parameters
*argslist

Variable-length argument list.

**kwdsdict

Arbitrary keyword arguments.

See also

set_printoptions, get_printoptions

Examples

>>> 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())
openmdao.utils.general_utils.prom2ivc_src_dict(prom_dict)[source]

Convert a dictionary with promoted input names into one with ivc source names.

Parameters
prom_dictdict

Original dict with some promoted paths.

Returns
dict

New dict with ivc source pathnames.

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

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.

class openmdao.utils.general_utils.reset_warning_registry(pattern=None)[source]

Bases: object

Context manager which archives & clears warning registry for duration of context.

From https://bugs.python.org/file40031/reset_warning_registry.py

__init__(pattern=None)[source]

Initialize all attributes.

Parameters
patternregex pattern

Causes manager to only reset modules whose names match pattern. defaults to ".*".

openmdao.utils.general_utils.run_driver(prob)[source]

Call run_driver on problem and capture output.

Parameters
probProblem

an instance of Problem

Returns
boolean

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)[source]

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)[source]

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.shape2tuple(shape)[source]

Return shape as a tuple.

Parameters
shapeint or tuple

The given shape.

Returns
tuple

The shape as a tuple.

openmdao.utils.general_utils.shape_from_idx(src_shape, src_inds, flat_src_inds)[source]

Get the shape of the result if the given src_inds were applied to an array of the given shape.

Parameters
src_shapetuple

Expected shape of source variable.

src_indsndarray or fancy index

Indices into the source variable.

flat_src_indsbool

If True, src_inds index into a flat array.

Returns
tuple

Shape of the input.

openmdao.utils.general_utils.simple_warning(msg, category=<class 'UserWarning'>, stacklevel=2)[source]

Display a simple warning message without the annoying extra line showing the warning call.

Parameters
msgstr

The warning message.

categoryclass

The warning class.

stacklevelint

Number of levels up the stack to identify as the warning location.

openmdao.utils.general_utils.str2valid_python_name(s)[source]

Translate a given string into a valid python variable name.

Parameters
sstr

The string to be translated.

Returns
str

The valid python name string.

openmdao.utils.general_utils.warn_deprecation(msg)[source]

Raise a warning and prints a deprecation message to stdout.

Parameters
msgstr

Message that will be printed to stdout.