options_dictionary.py

Define the OptionsDictionary class.

class openmdao.utils.options_dictionary.OptionsDictionary(parent_name=None, read_only=False)

Bases: object

Dictionary with pre-declaration of keys for value-checking and default values.

This class is instantiated for:

1. the options attribute in solvers, drivers, and processor allocators

2. the supports attribute in drivers

3. the options attribute in systems

Parameters:

parent_namestr

Name or class name of System that owns this OptionsDictionary.

read_onlybool

If True, setting (via __setitem__ or update) is not permitted.

Attributes:

_dictdict of dict

Dictionary of entries. Each entry is a dictionary consisting of value, values, types, desc, lower, and upper.

_parent_namestr or None

If defined, prepend this name to beginning of all exceptions.

_read_onlybool

If True, no options can be set after declaration.

_all_recordablebool

Flag to determine if all options in UserOptions are recordable.

_context_cachedict

A dictionary to store cached option/value pairs when using the OptionsDictionary as a context manager.

__contains__(key)

Check if the key is in the local dictionary.

Parameters:

keystr

name of the option.

Returns:

bool

whether key is in the local dict.

__getitem__(name)

Get an option from the dict or declared default.

Parameters:

namestr

name of the option.

Returns:

value-

value of the option.

__init__(parent_name=None, read_only=False)

Initialize all attributes.

__iter__()

Provide an iterator.

Returns:

iterable

iterator over the keys in the dictionary.

__setitem__(name, value)

Set an option in the local dictionary.

Parameters:

namestr

name of the option.

value-

value of the option to be value- and type-checked if declared.

declare(name, default=UNDEFINED, values=None, types=None, desc='', upper=None, lower=None, check_valid=None, allow_none=False, recordable=True, set_function=None, deprecation=None)

Declare an option.

The value of the option must satisfy the following: 1. If values only was given when declaring, value must be in values. 2. If types only was given when declaring, value must satisfy isinstance(value, types). 3. It is an error if both values and types are given.

Parameters:

namestr

Name of the option.

defaultobject or Null

Optional default value that must be valid under the above 3 conditions.

valuesset or list or tuple or None

Optional list of acceptable option values.

typestype or tuple of types or None

Optional type or list of acceptable option types.

descstr

Optional description of the option.

upperfloat or None

Maximum allowable value.

lowerfloat or None

Minimum allowable value.

check_validfunction or None

User-supplied function with arguments (name, value) that raises an exception if the value is not valid.

allow_nonebool

If True, allow None as a value regardless of values or types.

recordablebool

If True, add to recorder.

set_functionNone or function

User-supplied function with arguments (Options metadata, value) that pre-processes value and returns a new value.

deprecationstr or tuple or None

If None, it is not deprecated. If a str, use as a DeprecationWarning during __setitem__ and __getitem__. If a tuple of the form (msg, new_name), display msg as with str, and forward any __setitem__/__getitem__ to new_name.

items(recordable_only=False)

Yield name and value of options.

Parameters:

recordable_onlybool

If True, return only recordable options.

Yields:

keystr

Name of option.

valueint or bool or float or string

Value of the option.

set(**kwargs)

Set one or more options in the options dictionary simultaneously.

Parameters:

**kwargs

Keyword arguments where the option names in the OptionsDictionary are the keywords and the associated values are the values for those options.

temporary(**kwargs)

Provide a context manager for temporary option values within the context.

Parameters:

**kwargs

Keyword arguments where the option names in the OptionsDictionary are the keywords and the associated values are the temporary values for those options.

to_table(fmt='github', missingval='N/A', max_width=None, display=True)

Get a table representation of this OptionsDictionary as a table in the requested format.

Parameters:

fmtstr

The formatting of the requested table. Options are [‘github’, ‘rst’, ‘text’, ‘html’, ‘tabulator’] and several ‘grid’ and ‘outline’ formats that mimic those found in the python ‘tabulate’ library. Default value of ‘github’ produces a table in GitHub-flavored markdown. ‘html’ and ‘tabulator’ produce output viewable in a browser.

missingvalstr

The value to be displayed in place of None.

max_widthint or None

If not None, try to limit the total width of the table to this value.

displaybool

If True, display the table, typically by writing it to stdout or opening a browser.

Returns:

str

A string representation of the table in the requested format.

undeclare(name)

Remove entry from the OptionsDictionary, for classes that don’t use that option.

Parameters:

namestr

The name of a key, the entry of which will be removed from the internal dictionary.

update(in_dict)

Update the internal dictionary with the given one.

Parameters:

in_dictdict

The incoming dictionary to add to the internal one.

openmdao.utils.options_dictionary.check_valid(name, value)

Check the validity of value for the option with name.

Parameters:

namestr

Name of the option.

valueany

Value for the option.

Raises:

ValueError

If value is not valid for option.