Package openmdao.main

This package contains the openmdao framework infrastructure code.

api.py

Pseudo package containing all of the main classes/objects in the openmdao.main API.

convert_units

create

create_io_traits

dump_iteration_tree

enable_console

get_available_types

get_default_name

set_as_top

Assembly

Case

Component

ComponentWithDerivatives

ConstraintError

Container

Dataflow

Driver

ExprEvaluator

Factory

FileMetadata

FileRef

SequentialWorkflow

SimulationRoot

Variable

Workflow

assembly.py

Class definition for Assembly.

class openmdao.main.assembly.Assembly(doc=None, directory='')

Bases: openmdao.main.component.Component

This is a container of Components. It understands how to connect inputs and outputs between its children. When executed, it runs the top level Driver called ‘driver’.

Instance (Driver) driver

The top level Driver that manages execution of this Assembly.

• default: ‘None’
• copy: ‘deep’

add(name, obj)

Add obj to the component graph and call base class add.

Returns the added object.

calc_derivatives(first=False, second=False)

Overides the component’s version of this function. An assembly must initiate the call of calc_derivatives on all components in its driver’s workflow.

check_derivatives(order, driver_inputs, driver_outputs)

An assembly just tells its driver to run check_derivatives on each element in its workflow. Note that an assembly signifies a change of scope, so the driver input and output lists are pared down.

child_invalidated(childname, outs=None, force=False)

Invalidate all variables that depend on the outputs provided by the child that has been invalidated.

config_changed(update_parent=True)

Call this whenever the configuration of this Component changes, for example, children are added or removed, connections are made or removed, etc.

connect(srcpath, destpath)

Connect one src Variable to one destination Variable. This could be a normal connection between variables from two internal Components, or it could be a passthrough connection, which connects across the scope boundary of this object. When a pathname begins with ‘parent.’, that indicates that it is referring to a Variable outside of this object’s scope.

srcpath: str

Pathname of source variable.

destpath: str

Pathname of destination variable.

create_passthrough(pathname, alias=None)

Creates a PassthroughTrait that uses the trait indicated by pathname for validation, adds it to self, and creates a connection between the two. If alias is None, the name of the alias trait will be the last entry in its pathname. The trait specified by pathname must exist.

disconnect(varpath, varpath2=None)

If varpath2 is supplied, remove the connection between varpath and varpath2. Otherwise, if varpath is the name of a trait, remove all connections to/from varpath in the current scope. If varpath is the name of a Component, remove all connections from all of its inputs and outputs.

exec_counts(compnames)

execute()

Runs driver and updates our boundary variables.

get_valid(names)

Returns a list of boolean values indicating whether the named variables are valid (True) or invalid (False). Entries in names may specify either direct traits of self or those of children.

invalidate_deps(varnames=None, force=False)

Mark all Variables invalid that depend on varnames. Returns a list of our newly invalidated boundary outputs.

varnames: iter of str (optional)

An iterator of names of destination variables.

force: bool (optional)

If True, force the invalidation to proceed beyond the boundary even if all outputs were already invalid.

list_connections(show_passthrough=True)

Return a list of tuples of the form (outvarname, invarname).

remove(name)

Remove the named container object from this assembly and remove it from its workflow (if any).

step()

Execute a single child component and return.

stop()

Stop the calculation.

update_inputs(compname, varnames)

Transfer input data to input variables on the specified component. The varnames iterator is assumed to contain local names (no component name), for example: [‘a’, ‘b’].

update_outputs(outnames)

Execute any necessary internal or predecessor components in order to make the specified output variables valid.

case.py

class openmdao.main.case.Case(inputs=None, outputs=None, max_retries=None, retries=None, label='', case_uuid=None, parent_uuid='', msg=None)

Bases: object

Contains all information necessary to specify an input case, i.e., a list of names for all inputs to the case and their values. The case names may contain indexing into containers, attribute access, and/or function calls, as long as the full expression is valid as the left hand side of an assignment. Outputs to be collected may also be added to the Case, and they can be more general expressions, i.e., they do not have to refer to a single variable. After the Case is executed, it will contain an indicator of the exit status of the case, a string containing error messages associated with the running of the case (if any), and a unique case identifier.

add_input(name, value)

Adds an input and its value to this case.

name: str

Name of the input to be added. May contain an expression as long as it is valid when placed on the left hand side of an assignment.

value:

Value that the input will be assigned to.

add_inputs(inp_iter)

Adds multiple inputs to this case.

inp_iter: iterator returning (name,value)

iterator of input names and values

add_output(name, value=<class 'openmdao.main.case._Missing'>)

Adds an output to this case.

name: str

name of output to be added

add_outputs(outputs)

Adds outputs to this case.

outputs: iterator returning names or tuples of the form (name,value)

outputs to be added

apply_inputs(scope)

Take the values of all of the inputs in this case and apply them to the specified scope.

items(iotype=None)

Return a list of (name,value) tuples for variables/expressions in this Case.

iotype: str or None

If ‘in’, only inputs are returned. If ‘out’, only outputs are returned If None (the default), inputs and outputs are returned

keys(iotype=None)

Return a list of name/expression strings for this Case.

iotype: str or None

If ‘in’, only inputs are returned. If ‘out’, only outputs are returned If None (the default), inputs and outputs are returned

reset()

Remove any saved output values, set retries to None, get a new uuid and reset the parent_uuid. Essentially this Case becomes like a new Case with the same set of inputs and outputs that hasn’t been executed yet.

subcase(names)

Return a new Case having a specified subset of this Case’s inputs and outputs.

update_outputs(scope, msg=None)

Update the value of all outputs in this Case, using the given scope.

values(iotype=None)

Return a list of values for this Case.

iotype: str or None

If ‘in’, only inputs are returned. If ‘out’, only outputs are returned If None (the default), inputs and outputs are returned

caseiter.py

openmdao.main.caseiter.caseiter_to_dict(caseiter, varnames, include_errors=False)

Retrieve the values of specified variables from cases in a CaseIterator.

Returns a dict containing a list of values for each entry, keyed on variable name.

Only data from cases containing ALL of the specified variables will be returned so that all data values with the same index will correspond to the same case.

caseiter: CaseIterator

A CaseIterator containing the cases of interest.

varnames: list[str]

Iterator of names of variables to be retrieved.

include_errors: bool (optional) [False]

If True, include data from cases that reported an error.

component.py

Class definition for Component.

class openmdao.main.component.Component(doc=None, directory='')

Bases: openmdao.main.container.Container

This is the base class for all objects containing Traits that are accessible to the OpenMDAO framework and are “runnable.”

Str directory

If non-blank, the directory to execute in.

• default: ‘’
• iotype: ‘in’

Bool force_execute

If True, always execute even if all IO traits are valid.

• default: ‘False’
• iotype: ‘in’

Bool create_instance_dir

• default: ‘False’

Int exec_count

Number of times this Component has been executed.

• default: ‘0’

List external_files

FileMetadata objects for external files used by this component.

• default: ‘[]’
• copy: ‘deep’

add(name, obj)

Override of base class version to force call to check_config after any child containers are added. Returns the added Container object.

add_trait(name, trait)

Overrides base definition of add_trait in order to force call to check_config prior to execution when new traits are added.

calc_derivatives(first=False, second=False)

Prepare for Fake Finite Difference runs by calculating all needed derivatives, and saving the current state as the baseline. The user must supply calculate_first_derivatives() and/or calculate_second_derivatives() in the component.

This function is overridden by ComponentWithDerivatives

first: Bool

Set to True to calculate first derivatives.

second: Bool

Set to True to calculate second derivatives.

check_config()

Verify that this component is fully configured to execute. This function is called once prior to the first execution of this component and may be called explicitly at other times if desired. Classes that override this function must still call the base class version.

check_derivatives(order, driver_inputs, driver_outputs)

ComponentsWithDerivatives overloads this function to check for missing derivatives.

This function is overridden by ComponentWithDerivatives

check_path(path, check_dir=False)

Verify that the given path is a directory and is located within the allowed area (somewhere within the simulation root path).

checkpoint(outstream, fmt=4)

Save sufficient information for a restart. By default, this just calls save().

config_changed(update_parent=True)

Call this whenever the configuration of this Component changes, for example, children are added or removed.

connect(srcpath, destpath)

Connects one source variable to one destination variable. When a pathname begins with ‘parent.’, that indicates that it is referring to a variable outside of this object’s scope.

srcpath: str

Pathname of source variable.

destpath: str

Pathname of destination variable.

disconnect(srcpath, destpath)

Removes the connection between one source variable and one destination variable.

execute()

Perform calculations or other actions, assuming that inputs have already been set. This must be overridden in derived classes.

get_abs_directory()

Return absolute path of execution directory.

get_expr_depends()

Returns a list of tuples of the form (src_comp_name, dest_comp_name) for each dependency resulting from ExprEvaluators in this Component.

get_expr_sources()

Return a list of tuples containing the names of all upstream components that are referenced in any of our ExprEvaluators, along with an initial exec_count of 0.

get_file_vars()

Return list of (filevarname,filevarvalue,file trait) owned by this component.

get_valid(names)

Get the value of the validity flag for the specified variables. Returns a list of bools.

names: iterator of str

Names of variables whose validity is requested.

invalidate_deps(varnames=None, force=False)

Invalidate all of our outputs if they’re not invalid already. For a typical Component, this will always be all or nothing, meaning there will never be partial validation of outputs.

NOTE: Components supporting partial output validation must override this function.

Returns None, indicating that all outputs are newly invalidated, or [], indicating that no outputs are newly invalidated.

is_valid()

Return False if any of our variables is invalid.

list_containers()

Return a list of names of child Containers.

list_inputs(valid=None, connected=None)

Return a list of names of input values.

valid: bool (optional)

If valid is not None, the list will contain names of inputs with matching validity.

connected: bool (optional)

If connected is not None, the list will contain names of inputs with matching external connectivity status.

list_outputs(valid=None, connected=None)

Return a list of names of output values.

valid: bool (optional)

If valid is not None, the list will contain names of outputs with matching validity.

connected: bool (optional)

If connected is not None, the list will contain names of outputs with matching external connectivity status.

static load(instream, fmt=4, package=None, call_post_load=True, top_obj=True, name='', observer=None)

Load object(s) from instream. If instream is an installed package name, then any external files referenced in the object(s) are copied from the package installation to appropriate directories. If an external file has metadata attribute ‘constant’ == True and the machine supports it, a symlink is used rather than a file copy. The package and top_obj arguments are normally used by a loader script (generated by save_to_egg()) to load a sub-component from the egg. name is set when creating an instance via a factory. In this case, external files are copied to a name directory and the component’s directory attribute set accordingly. Existing files are not overwritten. Returns the root object.

instream: file or string

Stream to load from.

fmt: int

Format of state data.

package: string

Name of package to look for instream if instream is a string that is not an existing file.

call_post_load: bool

If True, call post_load().

top_obj: bool

Set True if loading the default entry, False if loading a child entry point object.

name: string

Name for the root object.

observer: callable

Will be called via an EggObserver.

pop_dir()

Return to previous directory saved by push_dir().

push_dir(directory=None)

Change directory to dir, remembering the current directory for a later pop_dir(). Returns the new absolute directory path.

remove(name)

Override of base class version to force call to check_config after any child containers are removed.

remove_trait(name)

Overrides base definition of add_trait in order to force call to check_config prior to execution when a trait is removed.

restart(instream)

Restore state using a checkpoint file. The checkpoint file is typically a delta from a full saved state file. If checkpoint is overridden, this should also be overridden.

run(force=False, ffd_order=0, case_id='')

Run this object. This should include fetching input variables if necessary, executing, and updating output variables. Do not override this function.

force: bool

If True, force component to execute even if inputs have not changed. (Default is False)

ffd_order: int

Order of the derivatives to be used during Fake Finite Difference (typically 1 or 2). During regular execution, ffd_order should be 0. (Default is 0)

case_id: str

Identifier for the Case that is associated with this run. (Default is ‘’)

save_to_egg(name, version, py_dir=None, require_relpaths=True, child_objs=None, dst_dir=None, observer=None, need_requirements=True)

Save state and other files to an egg. Typically used to copy all or part of a simulation to another user or machine. By specifying child components in child_objs, it will be possible to create instances of just those components from the installed egg. Child component names should be specified relative to this component.

name: string

Name for egg, must be an alphanumeric string.

version: string

Version for egg, must be an alphanumeric string.

py_dir: string

The (root) directory for local Python files. It defaults to the current directory.

require_relpaths: bool

If True, any path (directory attribute, external file, or file trait) which cannot be made relative to this component’s directory will raise ValueError. Otherwise such paths generate a warning and the file is skipped.

child_objs: list

List of child objects for additional entry points.

dst_dir: string

The directory to write the egg in.

observer: callable

Will be called via an EggObserver.

need_requirements: bool

Passed to eggsaver.save_to_egg().

After collecting files and possibly modifying their paths, this calls container.save_to_egg(). Returns (egg_filename, required_distributions, orphan_modules).

set_valid(names, valid)

Mark the io traits with the given names as valid or invalid.

step()

For Components that run other components (e.g., Assembly or Drivers), this will run one Component and return. For simple components, it is the same as run().

stop()

Stop this component.

tree_rooted()

Calls the base class version of tree_rooted(), checks our directory for validity, and creates the directory if it doesn’t exist.

update_outputs(outnames)

Do what is necessary to make the specified output Variables valid. For a simple Component, this will result in a run().

dir_context

The DirectoryContext for this component.

class openmdao.main.component.SimulationRoot

Bases: object

Singleton object used to hold root directory.

static chroot(path)

Change to directory path and set the singleton’s root. Normally not called but useful in special situations.

path: string

Path to move to.

static get_root()

Return this simulation’s root directory path.

static legal_path(path)

Return True if path is legal (descendant of our root).

path: string

Path to check.

component_with_derivatives.py

A component with derivatives. Derived from Component

class openmdao.main.component_with_derivatives.ComponentWithDerivatives(*args, **kwargs)

Bases: openmdao.main.component.Component

This is the base class for all objects containing Traits that are accessible to the OpenMDAO framework and are “runnable.”

calc_derivatives(first=False, second=False)

Prepare for Fake Finite Difference runs by calculating all needed derivatives, and saving the current state as the baseline. The user must supply calculate_first_derivatives() and/or calculate_second_derivatives() in the component.

This function should not be overriden.

first: Bool

Set to True to calculate first derivatives.

second: Bool

Set to True to calculate second derivatives.

check_derivatives(order, driver_inputs, driver_outputs)

Calls the validate method of the derivatives object, in order to warn the user about all missing derivatives.

constants.py

Package containing various constants/enumerations.

Currently it only includes: SAVE_YAML, SAVE_LIBYAML, SAVE_PICKLE, SAVE_CPICKLE.

container.py

The Container class.

class openmdao.main.container.Container(doc=None, iotype=None)

Bases: enthought.traits.has_traits.HasTraits

Base class for all objects having Traits that are visible to the framework

add(name, obj, **kw_args)

Add a Container object to this Container. Returns the added Container object.

add_trait(name, trait)

Overrides HasTraits definition of add_trait in order to keep track of dynamically added traits for serialization and to add callbacks for input Variables.

connect(srcpath, destpath)

Connects one source variable to one destination variable. When a pathname begins with ‘parent.’, that indicates that it is referring to a variable outside of this object’s scope.

srcpath: str

Pathname of source variable.

destpath: str

Pathname of destination variable.

contains(path)

Return True if the child specified by the given dotted path name is contained in this Container.

disconnect(srcpath, destpath)

Removes the connection between one source variable and one destination variable.

get(path, index=None)

Return the object specified by the given path, which may contain ‘.’ characters.

get_dyn_trait(pathname, iotype=None, trait=None)

Returns a trait if a trait with the given pathname exists, possibly creating it “on-the-fly” and adding its Container. If an attribute exists with the given pathname but no trait is found or can be created, or if pathname references a trait in a parent scope, None will be returned. If no attribute exists with the given pathname within this scope, an AttributeError will be raised.

pathname: str

Pathname of the desired trait. May contain dots.

iotype: str (optional)

Expected iotype of the trait.

trait: TraitType (optional)

Trait to be used for validation.

get_metadata(traitpath, metaname=None)

Retrieve the metadata associated with the trait found using traitpath. If metaname is None, return the entire metadata dictionary for the specified trait. Otherwise, just return the specified piece of metadata. If the specified piece of metadata is not part of the trait, None is returned.

get_pathname(rel_to_scope=None)

Return full path name to this container, relative to scope rel_to_scope. If rel_to_scope is None, return the full pathname.

get_trait(name, copy=False)

Returns the trait indicated by name, or None if not found. No recursive search is performed if name contains dots. This is a replacement for the trait() method on HasTraits objects, because that method can return traits that shouldn’t exist. DO NOT use the trait() function as a way to determine the existence of a trait.

get_wrapped_attr(name)

If the named trait can return a TraitValWrapper, then this function will return that, with the value set to the current value of the named variable. Otherwise, it functions like getattr, just returning the value of the named variable. Raises an exception if the named trait cannot be found. The value will be copied if the trait has a ‘copy’ metadata attribute that is not None. Possible values for ‘copy’ are ‘shallow’ and ‘deep’.

is_valid()

items(recurse=False, **metadata)

Return a list of tuples of the form (rel_pathname, obj) for each trait of this Container that matches the given metadata. If recurse is True, also iterate through all child Containers of each Container found.

list_containers()

Return a list of names of child Containers.

static load(instream, fmt=4, package=None, call_post_load=True, name=None)

Load object(s) from the input stream. Pure Python classes generally won’t need to override this, but extensions will. The format can be supplied in case something other than cPickle is needed.

instream: file or string

Stream to load from.

fmt: int

Format of state data.

package: string

Name of package to look for instream, if instream is a string that is not an existing file.

call_post_load: bool

If True, call post_load().

name: string

Name for root object.

Returns the root object.

static load_from_eggfile(filename, observer=None)

Extract files in egg to a subdirectory matching the saved object name and then load object graph state.

filename: string

Name of egg file to be loaded.

observer: callable

Will be called via an EggObserver.

Returns the root object.

static load_from_eggpkg(package, entry_name=None, instance_name=None, observer=None)

Load object graph state by invoking the given package entry point. If specified, the root object is renamed to instance_name.

package: string

Package name.

entry_name: string

Name of entry point.

instance_name: string

Name for root object.

observer: callable

Will be called via an EggObserver.

Returns the root object.

post_load()

Perform any required operations after model has been loaded.

pre_delete()

Perform any required operations before the model is deleted.

raise_exception(msg, exception_class=<type 'exceptions.Exception'>)

Raise an exception.

remove(name)

Remove the specified child from this container and remove any public trait objects that reference that child. Notify any observers.

remove_trait(name)

Overrides HasTraits definition of remove_trait in order to keep track of dynamically added traits for serialization.

revert_to_defaults(recurse=True)

Sets the values of all of the inputs to their default values.

save(outstream, fmt=4, proto=-1)

Save the state of this object and its children to the given output stream. Pure Python classes generally won’t need to override this because the base class version will suffice, but Python extension classes will have to override. The format can be supplied in case something other than cPickle is needed.

outstream: file or string

Stream to save to.

fmt: int

Format for saved data.

proto: int

Protocol used.

save_to_egg(name, version, py_dir=None, src_dir=None, src_files=None, child_objs=None, dst_dir=None, observer=None, need_requirements=True)

Save state and other files to an egg. Typically used to copy all or part of a simulation to another user or machine. By specifying child containers in child_objs, it will be possible to create instances of just those containers from the installed egg. Child container names should be specified relative to this container.

name: string

Name for egg, must be an alphanumeric string.

version: string

Version for egg, must be an alphanumeric string.

py_dir: string

The (root) directory for local Python files. It defaults to the current directory.

src_dir: string

The root of all (relative) src_files.

src_files: list

List of paths to files to be included in the egg.

child_objs: list

List of child objects for additional entry points.

dst_dir: string

The directory to write the egg in.

observer: callable

Will be called via an EggObserver.

need_requirements: bool

Passed to eggsaver.save_to_egg().

After collecting entry point information, calls eggsaver.save_to_egg(). Returns (egg_filename, required_distributions, orphan_modules).

set(path, value, index=None, src=None, force=False)

Set the value of the Variable specified by the given path, which may contain ‘.’ characters. The Variable will be set to the given value, subject to validation and constraints. index, if not None, should be a list of ints, at most one for each array dimension of the target value.

tree_rooted()

Called after the hierarchy containing this Container has been defined back to the root. This does not guarantee that all sibling Containers have been defined. It also does not guarantee that this component is fully configured to execute. Classes that override this function must call their base class version.

This version calls tree_rooted() on all of its child Containers.

name

The name of this Container.

parent

The parent Container of this Container.

openmdao.main.container.build_container_hierarchy(dct)

Create a hierarchy of Containers based on the contents of a nested dict. There will always be a single top level scoping Container regardless of the contents of dct.

openmdao.main.container.create_io_traits(cont, obj_info, iotype='in')

Create io trait(s) specified by the contents of obj_info. Calls build_trait() on the scoping object, which can be overridden by subclasses, to create each trait.

obj_info is assumed to be either a string, a tuple, or a list that contains strings and/or tuples. Tuples must contain a name and an ‘internal’ name, and may optionally contain an iotype and a validation trait. The first name is the one that will be used to access the trait’s attribute in the Container, while the second name represents some alternate naming scheme within the Container.

For example, the following are valid calls:

create_io_traits(obj, ‘foo’) create_io_traits(obj, [‘foo’,’bar’,’baz’]) create_io_traits(obj, (‘foo’, ‘foo_alias’, ‘in’, some_trait), ‘bar’) create_io_traits(obj, [(‘foo’, ‘fooa’, ‘in’),(‘bar’, ‘barb’, ‘out’),(‘baz’, ‘bazz’)])

The newly created traits are added to the specified Container.

openmdao.main.container.deep_hasattr(obj, pathname)

Returns True if the attrbute indicated by the give pathname exists, False otherwise.

openmdao.main.container.dump(cont, recurse=False, stream=None, **metadata)

Print all items having specified metadata and their corresponding values to the given stream. If the stream is not supplied, it defaults to sys.stdout.

openmdao.main.container.find_name(parent, obj)

Find the given object in the specified parent and return its name in the parent’s __dict__. There could be multiple names bound to a given object. Only the first name found is returned.

Return ‘’ if not found.

openmdao.main.container.find_trait_and_value(obj, pathname)

Return a tuple of the form (trait, value) for the given dotted pathname. Raises an exception if the value indicated by the pathname is not found in obj. If the value is found but has no trait, then (None, value) is returned.

openmdao.main.container.get_closest_proxy(start_scope, pathname)

Resolve down to the closest in-process parent object of the object indicated by pathname. Returns a tuple containing (proxy_or_parent, rest_of_pathname)

openmdao.main.container.get_default_name(obj, scope)

Return a unique name for the given object in the given scope.

openmdao.main.container.set_as_top(cont)

Specifies that the given Container is the top of a Container hierarchy.

dataflow.py

class openmdao.main.dataflow.Dataflow(parent=None, scope=None, members=None)

Bases: openmdao.main.seqentialflow.SequentialWorkflow

A Dataflow consists of a collection of Components which are executed in data flow order.

add(compname)

Add a new component to the workflow by name.

config_changed()

Notifies the Workflow that its configuration (dependencies, etc.) has changed.

remove(compname)

Remove a component from this Workflow by name.

depgraph.py

Class definition for Assembly

exception openmdao.main.depgraph.AlreadyConnectedError

Bases: exceptions.RuntimeError

class openmdao.main.depgraph.DependencyGraph

Bases: object

A dependency graph for Components. Each edge contains a _Link object, which maps all connected inputs and outputs between the two Components. Graph nodes starting with ‘@’ are abstract nodes that represent boundary connections.

@xin is external to our input boundary

@bin is our input boundary

@bout is our output boundary

@xout is external to our output boundary

add(name)

Add the name of a Component to the graph.

connect(srcpath, destpath)

Add an edge to our Component graph from srccompname to destcompname.

connections_to(path)

Returns a list of tuples of the form (srcpath, destpath) for all connections between the variable or component specified by path.

copy_graph()

disconnect(srcpath, destpath=None)

Disconnect the given variables.

dump(stream=<open file '<stdout>', mode 'w' at 0x01A70070>)

Prints out a simple text representation of the graph.

get_connected_inputs()

get_connected_outputs()

get_link(srcname, destname)

Return the link between the two specified nodes. If there is no connection then None is returned.

get_source(destpath)

in_links(cname)

Return a list of the form [(compname, link), (compname2, link2)...] containing each incoming link to the given component and the name of the connected component.

in_map(cname, varset)

Yield a tuple of lists of the form (srccompname, srclist, destlist) for each link, where all dests in destlist are found in varset. If no dests are found in varset, a tuple will not be returned at all for that link.

invalidate_deps(scope, cnames, varsets, force=False)

Walk through all dependent nodes in the graph, invalidating all variables that depend on output sets for the given component names.

scope: Component

Scoping object containing this dependency graph.

cnames: list of str

Names of starting nodes.

varsets: list of sets of str

Sets of names of outputs from each starting node.

force: bool (optional)

If True, force invalidation to continue even if a component in the dependency chain was already invalid.

list_connections(show_passthrough=True)

Return a list of tuples of the form (outvarname, invarname).

out_links(cname)

Return a list of the form [(compname, link), (compname2, link2)...] containing each outgoing link from the given component and the name of the connected component.

remove(name)

Remove the name of a Component from the graph. It is not an error if the component is not found in the graph.

var_edges(name=None)

Return a list of outgoing edges connecting variables.

var_in_edges(name=None)

Return a list of incoming edges connecting variables.

derivatives.py

Class definition for Derivatives. This object is used by Component to store derivative information and to perform calculations during a Fake Finite Difference.

class openmdao.main.derivatives.Derivatives

Bases: object

Class for storing derivatives between the inputs and outputs of a component at specified orders.

calculate_output(comp, out_name, order)

Returns the Fake Finite Difference output for the given output name using the stored baseline and derivatives along with the new inputs in comp.

declare_first_derivative(comp, out_name, in_name)

Declares that a component can calculate a first derivative between the given input and output.

comp: Component

Component that contains the variables out_name and in_name.

out_name: str

Name of component’s output variable.

in_name: str

Name of component’s first input variable for derivative.

declare_second_derivative(comp, out_name, in_name1, in_name2)

Declares that a component can calculate a second derivative between the given input and output.

comp: Component

Component that contains the variables out_name and in_name(1,2)

out_name: str

Name of component’s output variable.

in_name1: str

Name of component’s first input variable for derivative.

in_name2: str

Name of component’s second input variable for derivative.

save_baseline(comp)

Saves the baseline of all inputs and outputs for which derivatives have been specified.

set_first_derivative(out_name, in_name, value)

Stores a single first derivative value.

out_name: str

Name of component’s output variable.

in_name: str

Name of component’s input variable.

value: float

Value of derivative.

set_second_derivative(out_name, in_name1, in_name2, value)

Stores a single second derivative value.

Note cross terms (i.e., df_dxdy) are assumed symmetric so you only have to specify them once.

out_name: str

Name of component’s output variable.

in_name1: str

Name of component’s first input variable for derivative.

in_name2: str

Name of component’s second input variable for derivative.

value: float

Value of derivative.

validate(comp, order, driver_inputs, driver_outputs)

Check the component’s inputs and output and warn about any input- output combinations that are missing a derivative.

driver.py

Driver class definition

class openmdao.main.driver.Driver(doc=None)

Bases: openmdao.main.component.Component

A Driver iterates over a workflow of Components until some condition is met.

Instance (ICaseRecorder) recorder

Case recorder for iteration data.

• default: ‘None’
• required: False
• copy: ‘deep’

Instance (Workflow) workflow

• default: ‘None’
• copy: ‘deep’

add_event(name)

Adds an event variable to be set by the driver.

name: string

Name of the event variable the driver should set during execution.

calc_derivatives(first=False, second=False)

Calculate derivatives and save baseline states for all components in this workflow.

check_config()

Verify that our workflow is able to resolve all of its components.

check_derivatives(order, driver_inputs, driver_outputs)

Check derivatives for all components in this workflow.

clear_events()

Remove all event variables from the driver’s list.

config_changed(update_parent=True)

Call this whenever the configuration of this Component changes, for example, children are added or removed or dependencies may have changed.

continue_iteration()

Return False to stop iterating.

execute()

Iterate over a workflow of Components until some condition is met. If you don’t want to structure your driver to use pre_iteration, post_iteration, etc., just override this function. As a result, none of the <start/pre/post/continue>_iteration() functions will be called.

get_events()

Return the list of event variables to be set by this driver.

get_expr_depends()

Returns a list of tuples of the form (src_comp_name, dest_comp_name) for each dependency introduced by any ExprEvaluators in this Driver, ignoring any dependencies on components that are inside of this Driver’s iteration set.

is_valid()

Return False if any Component in our workflow(s) is invalid, or if any of our variables is invalid.

iteration_set()

Return a set of all Components in our workflow(s), and recursively in any workflow in any Driver in our workflow(s).

post_iteration()

Called after each iteration.

pre_iteration()

Called prior to each iteration. This is where iteration events are set.

remove_event(name)

Remove the name of the specified event variable from the driver’s list of event variables to be set during execution.

run_iteration()

Runs workflow.

set_events()

Set all events in the event list.

start_iteration()

Called just prior to the beginning of an iteration loop. This can be overridden by inherited classes. It can be used to perform any necessary pre-iteration initialization.

step()

Similar to the ‘execute’ function, but this one only executes a single Component from the workflow each time it’s called.

stop()

eggchecker.py

openmdao.main.eggchecker.check_save_load(comp, py_dir=None, test_dir='test_dir', cleanup=True, logfile=None)

Convenience routine to check that saving & reloading comp works.

comp: Component

The component to check.

py_dir: string or None

The directory in which to find local Python modules.

test_dir: string

Name of a scratch directory to unpack in.

cleanup: bool

If True, the scratch directory will be removed after the test.

logfile: string or None

Name of file for logging progress.

Creates an egg in the current directory, unpacks it in test_dir via a separate process, and then loads and runs the component in another subprocess. Returns the first non-zero subprocess exit code, or zero if everything succeeded.

exceptions.py

Exception classes for OpenMDAO.

exception openmdao.main.exceptions.ConstraintError(msg)

Bases: exceptions.ValueError

Raised when a constraint is violated.

exception openmdao.main.exceptions.CircularDependencyError(msg)

Bases: exceptions.RuntimeError

Raised when a circular dependency occurs.

exception openmdao.main.exceptions.RunInterrupted(msg)

Bases: exceptions.RuntimeError

Raised when run() was interrupted, implying an inconsistent state.

exception openmdao.main.exceptions.RunStopped(msg)

Bases: exceptions.RuntimeError

Raised when run() was stopped, implying a consistent state but not necessarily reflecting input values.

expreval.py

class openmdao.main.expreval.ExprEvaluator(text, scope=None)

Bases: object

A class that translates an expression string into a new string containing any necessary framework access functions, e.g., set, get. The compiled bytecode is stored within the object so that it doesn’t have to be reparsed during later evaluations. A scoping object is required at construction time or evaluation time, and that object determines the form of the translated expression. Variables that are local to the scoping object are translated to a simple attribute access on the object, whereas variables from other objects must be accessed using the appropriate set() or get() call. Array entry access, ‘late’ attribute access, and function invocation are also translated in a similar way.”. For a description of the format of the ‘index’ arg of set/get that is generated by ExprEvaluator, see the doc string for the Container._process_index_entry function.

check_resolve()

Return True if all variables referenced by our expression can be resolved.

evaluate(scope=None)

Return the value of the scoped string, evaluated using the eval() function.

get_referenced_compnames()

Return a set of source or dest Component names based on the pathnames of Variables referenced in our expression string.

get_referenced_varpaths()

Return a set of source or dest Variable pathnames relative to scope.parent and based on the names of Variables referenced in our expression string.

is_valid_assignee()

Returns True if the syntax of our expression is valid to be on the left hand side of an assignment. No check is performed to see if the variable(s) in the expression actually exist.

refs_valid()

Return True if all variables referenced by our expression are valid.

set(val, scope=None)

Set the value of the referenced object to the specified value.

scope

The scoping object used to evaluate the expression

text

The expression string

factory.py

class openmdao.main.factory.Factory

Bases: object

Base class for objects that know how to create other objects based on a type argument and several optional arguments (version, server id, and resource description).

create(typname, version=None, server=None, res_desc=None, **ctor_args)

Return an object of type typename, using the specified package version, server location, and resource description.

get_available_types(groups=None)

Return a set of tuples of the form (typename, dist_version), one for each available plugin type in the given entry point groups. If groups is None, return the set for all openmdao entry point groups.

factorymanager.py

Manages the creation of framework objects, either locally or remotely.

openmdao.main.factorymanager.create(typname, version=None, server=None, res_desc=None, **ctor_args)

Create and return an object specified by the given type, version, etc.

openmdao.main.factorymanager.register_class_factory(fct)

Add a Factory to the factory list.

openmdao.main.factorymanager.get_available_types(groups=None)

Return a set of tuples of the form (typename, dist_version), one for each available plugin type in the given entry point groups. If groups is None, return the set for all openmdao entry point groups.

filevar.py

Support for files, either as File or external files.

class openmdao.main.filevar.FileMetadata(path, **metadata)

Bases: object

Metadata related to a file, specified by keyword arguments (except for ‘path’). By default, the metadata includes:

• ‘path’, a string, no default value. It may be a glob-style pattern in the case of an external file description. Non-absolute paths are relative to their owning component’s directory.
• ‘desc’, a string, default null.
• ‘content_type’, a string, default null.
• ‘binary’, boolean, default False.
• ‘big_endian’, boolean, default False. Only meaningful if binary.
• ‘single_precision’, boolean, default False. Only meaningful if binary.
• ‘integer_8’, boolean, default False. Only meaningful if binary.
• ‘unformatted’, boolean, default False. Only meaningful if binary.
• ‘recordmark_8’, boolean, default False. Only meaningful if unformatted.

In addition, external files have defined behavior for:

• ‘input’, boolean, default False. If True, the file(s) should exist before execution.
• ‘output’, boolean, default False. If True, the file(s) should exist after execution.
• ‘constant’, boolean, default False. If True, the file(s) may be safely symlinked.

Arbitrary additional metadata may be assigned.

get(attr, default)

Return attr value, or default if attr has not been defined.

class openmdao.main.filevar.FileRef(path, owner=None, **metadata)

Bases: openmdao.main.filevar.FileMetadata

A reference to a file on disk. As well as containing metadata information, it supports open() to read the file’s contents. Before open() is called, ‘owner’ must be set to an object supporting check_path() and get_abs_directory() (typically a Component or one of its child Container objects).

copy(owner)

Return a copy of ourselves, owned by owner.

owner: Component

The component used to determine the root for relative paths and checking the legality of absolute paths.

open()

Open file for reading.

hasconstraints.py

Functions in the HasConstraints, HasEqConstraints, and HasIneqConstraints interfaces.

class openmdao.main.hasconstraints.Constraint(lhs, comparator, rhs, scaler, adder, scope=None)

Bases: object

Object that stores info for a single constraint.

evaluate()

Returns a tuple of the form (lhs, rhs, comparator, is_violated).

class openmdao.main.hasconstraints.HasConstraints(parent)

Bases: object

Add this class as a delegate if your Driver supports both equality and inequality constraints.

add_constraint(expr_string, scaler=1.0, adder=0.0)

Adds a constraint in the form of a boolean expression string to the driver.

expr_string: str

Expression string containing the constraint.

scaler: float (optional)

Multiplicative scale factor applied to both sides of the constraint’s boolean expression. It should be a positive nonzero value. Default is unity (1.0).

adder: float (optional)

Additive scale factor applied to both sides of the constraint’s boolean expression. Default is no additive shift (0.0).

add_eq_constraint(lhs, rhs, scaler, adder)

Adds an equality constraint as two strings, a left-hand side and a right-hand side.

add_ineq_constraint(lhs, comparator, rhs, scaler, adder)

Adds an inequality constraint as three strings; a left-hand side, a comparator (‘<’,’>’,’<=’, or ‘>=’), and a right hand side.

clear_constraints()

Removes all constraints.

eval_eq_constraints()

Returns a list of tuples of the form (lhs, rhs, comparator, is_violated) from evalution of equality constraints.

eval_ineq_constraints()

Returns a list of tuples of the form (lhs, rhs, comparator, is_violated) from evalution of inequality constraints.

get_eq_constraints()

Returns an ordered dict of equality constraint objects.

get_expr_depends()

Returns a list of tuples of the form (src_comp_name, dest_comp_name) for each dependency introduced by a constraint.

get_ineq_constraints()

Returns an ordered dict of inequality constraint objects.

list_constraints()

Return a list of strings containing constraint expressions.

remove_constraint(expr_string)

Removes the constraint with the given string.

class openmdao.main.hasconstraints.HasEqConstraints(parent)

Bases: openmdao.main.hasconstraints._HasConstraintsBase

Add this class as a delegate if your Driver supports equality constraints but does not support inequality constraints.

add_constraint(expr_string, scaler=1.0, adder=0.0)

Adds a constraint in the form of a boolean expression string to the driver.

Parameters:

expr_string: str

Expression string containing the constraint.

scaler: float (optional)

Multiplicative scale factor applied to both sides of the constraint’s boolean expression. It should be a positive nonzero value. Default is unity (1.0).

adder: float (optional)

Additive scale factor applied to both sides of the constraint’s boolean expression. Default is no additive shift (0.0).

add_eq_constraint(lhs, rhs, scaler, adder)

Adds an equality constraint as two strings, a left-hand side and a right-hand side.

eval_eq_constraints()

Returns a list of tuples of the form (lhs, rhs, comparator, is_violated).

get_eq_constraints()

Returns an ordered dict of constraint objects.

class openmdao.main.hasconstraints.HasIneqConstraints(parent)

Bases: openmdao.main.hasconstraints._HasConstraintsBase

Add this class as a delegate if your Driver supports inequality constraints but does not support equality constraints.

add_constraint(expr_string, scaler=1.0, adder=0.0)

Adds a constraint in the form of a boolean expression string to the driver.

expr_string: str

Expression string containing the constraint.

scaler: float (optional)

Multiplicative scale factor applied to both sides of the constraint’s boolean expression. It should be a positive nonzero value. Default is unity (1.0).

adder: float (optional)

Additive scale factor applied to both sides of the constraint’s boolean expression. Default is no additive shift (0.0).

add_ineq_constraint(lhs, rel, rhs, scaler, adder)

Adds an inequality constraint as three strings; a left-hand side, a comparator (‘<’,’>’,’<=’, or ‘>=’), and a right-hand side.

eval_ineq_constraints()

Returns a list of constraint values

get_ineq_constraints()

Returns an ordered dict of inequality constraint objects.

hasevents.py

class openmdao.main.hasevents.HasEvents(parent)

Bases: object

This class provides an implementation of the IHasEvents interface.

add_event(name)

Adds an event variable to be set by the driver.

name: string

Name of the event variable the driver should set during execution.

clear_events()

Remove all event variables from the driver’s list.

get_events()

Return the list of event variables to be set by this driver.

remove_event(name)

Remove the name of the specified event variable from the driver’s list of event variables to be set during execution.

set_events()

Set all events in the event list.

hasobjective.py

class openmdao.main.hasobjective.HasObjective(parent)

Bases: object

This class provides an implementation of the IHasObjective interface.

add_objective(expr)

Sets the objective of this driver to be the specified expression. If there is a preexisting objective in this driver, it is replaced.

expr: string

String containing the objective expression.

eval_objective()

Returns the value of the evaluated objective.

get_expr_depends()

Returns a list of tuples of the form (src_comp_name, dest_comp_name) for each dependency introduced by our objective.

list_objective()

Returns the expression string for the objective.

class openmdao.main.hasobjective.HasObjectives(parent)

Bases: object

This class provides an implementation of the IHasObjectives interface.

add_objective(expr)

Adds an objective to the driver.

expr: string

String containing the objective expression.

add_objectives(obj_iter)

Takes an iterator of objective strings and creates objectives for them in the driver.

clear_objectives()

Removes all objectives.

eval_objectives()

Returns a list of values of the evaluated objectives.

get_expr_depends()

Returns a list of tuples of the form (src_comp_name, dest_comp_name) for each dependency introduced by our objectives.

list_objectives()

Returns a list of objective expressions.

remove_objective(expr)

Removes the specified objective expression. Spaces within the expression are ignored.

hasparameters.py

class openmdao.main.hasparameters.HasParameters(parent)

Bases: object

This class provides an implementation of the IHasParameters interface.

add_parameter(name, low=None, high=None, fd_step=None)

Adds a parameter to the driver.

name: string

Name of the variable the driver should vary during execution.

low: float (optional)

Minimum allowed value of the parameter.

high: float (optional)

Maximum allowed value of the parameter.

fd_step: float (optional)

Step-size to use for finite difference calculation. If no value is given, the differentitator will use its own default

If neither “low” nor “high” is specified, the min and max will default to the values in the metadata of the variable being referenced. If they are not specified in the metadata and not provided as arguments, a ValueError is raised.

add_parameters(param_iter)

Takes an iterator of tuples of the form (param_name, low, high) and adds the parameters to the driver.

clear_parameters()

Removes all parameters.

get_expr_depends()

Returns a list of tuples of the form (src_comp_name, dest_comp_name) for each dependency introduced by a parameter.

get_parameters()

Returns an ordered dict of parameter objects.

list_parameters()

Returns an alphabetized list of parameter names.

remove_parameter(name)

Removes the parameter with the given name.

set_parameters(values)

Pushes the values in the iterator ‘values’ into the corresponding variables in the model.

values: iterator

Iterator of input values with an order defined to match the order of parameters returned by the list_parameter method. ‘values’ must support the len() function.

class openmdao.main.hasparameters.Parameter(low=None, high=None, expr=None, fd_step=None)

Bases: object

hasstopcond.py

class openmdao.main.hasstopcond.HasStopConditions(parent)

Bases: object

A delegate that adds handling of stop conditions that are supplied as expression strings.

add_stop_condition(exprstr)

clear_stop_conditions()

Removes all stop conditions.

eval_stop_conditions()

Returns a list of evaluated stop conditions.

get_stop_conditions()

Returns a list of stop condition strings.

remove_stop_condition(expr_string)

Removes the stop condition matching the given string.

should_stop()

Return True if any of the stopping conditions evaluate to True.

importfactory.py

class openmdao.main.importfactory.ImportFactory

Bases: openmdao.main.factory.Factory

Creates objects using the standard Python __import__ mechanism. The object must have a ctor with the same name as the module, minus the file extension. For example, to create a MyComp object, the module must be named MyComp.py (or .pyc or .pyo). This factory does not support specific version creation or creation on a remote server.

create(typ, version=None, server=None, res_desc=None, **ctor_args)

Tries to import the given named module and return a factory function from it. The factory function or constructor must have the same name as the module. The module must be importable in the current Python environment.

get_available_types(groups=None)

Does nothing but is included to adhere to the Factory interface.

interfaces.py

Interfaces for the OpenMDAO project.

class openmdao.main.interfaces.ICaseIterator

Bases: enthought.traits.has_traits.Interface

An iterator that returns Case objects.

get_iter()

Return an iterator of Case objects.

class openmdao.main.interfaces.ICaseRecorder

Bases: enthought.traits.has_traits.Interface

A recorder of Cases.

get_iterator()

Return an iterator that matches the format that this recorder uses.

record(case)

Record the given Case.

class openmdao.main.interfaces.IComponent

Bases: openmdao.main.interfaces.IContainer

Interface for an IContainer object that can be executed to update the values of its output variables based on the values of its input variables.

check_config()

Verify that this component is fully configured to execute. This function is called once prior to the first execution of this component and may be called explicitly at other times if desired. Classes that override this function must still call the base class version.

checkpoint(outstream, fmt=4)

Save sufficient information for a restart. By default, this just calls save().

connect(srcpath, destpath)

Connects one source variable to one destination variable. When a pathname begins with ‘parent.’, that indicates that it is referring to a variable outside of this object’s scope.

srcpath: str

Pathname of source variable.

destpath: str

Pathname of destination variable.

disconnect(srcpath, destpath)

Removes the connection between one source variable and one destination variable.

get_abs_directory()

Return absolute path of execution directory.

get_expr_depends()

Returns a list of tuples of the form (src_comp_name, dest_comp_name) for each dependency resulting from ExprEvaluators in this Component.

get_expr_sources()

Return a list of tuples containing the names of all upstream components that are referenced in any of our objectives, along with an initial exec_count of 0.

get_file_vars()

Return list of (filevarname, filevarvalue, file trait) owned by this component.

get_valid(names)

Get the value of the validity flag for each of the named io traits.

invalidate_deps(varnames=None, force=False)

Invalidate all of our outputs if they’re not invalid already. For a typical Component, this will always be all or nothing, meaning there will never be partial validation of outputs. Components supporting partial output validation must override this function.

Returns None, indicating that all outputs are invalidated.

is_valid()

Return False if any of our variables is invalid.

list_inputs(valid=None)

Return a list of names of input values. If valid is not None, the the list will contain names of inputs with matching validity.

list_outputs(valid=None)

Return a list of names of output values. If valid is not None, the the list will contain names of outputs with matching validity.

restart(instream)

Restore state using a checkpoint file. The checkpoint file is typically a delta from a full saved state file. If checkpoint is overridden, this should also be overridden.

run(force=False)

Run this object. This should include fetching input variables, executing, and updating output variables. Do not override this function.

set_valid(names, valid)

Mark the io traits with the given names as valid or invalid.

step()

For Components that run other components (e.g., Assembly or Drivers), this will run one Component and return. For simple components, it is the same as run().

stop()

Stop this component.

update_outputs(outnames)

Do what is necessary to make the specified output Variables valid. For a simple Component, this will result in a run().

class openmdao.main.interfaces.IContainer

Bases: enthought.traits.has_traits.Interface

Interface for an object containing variables and other IContainers.

Str name

• default: ‘’

add(name, obj, **kw_args)

Add a Container object to this Container. Returns the added Container object.

add_trait(name, trait)

Overrides HasTraits definition of add_trait in order to keep track of dynamically added traits for serialization.

connect(srcpath, destpath)

Connects one source variable to one destination variable. When a pathname begins with ‘parent.’, that indicates that it is referring to a variable outside of this object’s scope.

srcpath: str

Pathname of source variable.

destpath: str

Pathname of destination variable.

contains(path)

Return True if the child specified by the given dotted path name is contained in this Container.

create_alias(path, alias, iotype=None, trait=None)

Create a trait that maps to some internal variable designated by a dotted path. If a trait is supplied as an argument, use that trait as a validator for the aliased value. The resulting trait will have the alias as its name and will be added to self. An exception will be raised if the trait already exists.

disconnect(srcpath, destpath)

Removes the connection between one source variable and one destination variable.

get(path, index=None)

Return the object specified by the given path, which may contain ‘.’ characters. index, if not None, should be a list of container indices and/or single entry lists of attribute names. For example, to get something like comp.x[2][‘mykey’].child.value, index would look like: [2,’mykey’,[‘child’],[‘value’]]. Attribute names are placed in sublists because strings are valid container indices.

get_dyn_trait(pathname, iotype=None, trait=None)

Returns a trait if a trait with the given pathname exists, possibly creating the trait “on-the-fly.” If an attribute exists with the given pathname but no trait is found or can be created, or if pathname references a trait in a parent scope, None will be returned. If no attribute exists with the given pathname within this scope, an AttributeError will be raised.

pathname: str

Pathname of the desired trait. May contain dots.

iotype: str (optional)

Expected iotype of the trait.

trait: TraitType (optional)

Trait to be used for validation.

get_metadata(traitpath, metaname=None)

Retrieve the metadata associated with the trait found using traitpath. If metaname is None, return the entire metadata dictionary for the specified trait. Otherwise, just return the specified piece of metadata. If the specified piece of metadata is not part of the trait, None is returned.

get_pathname(rel_to_scope=None)

Return full path name to this container, relative to scope rel_to_scope. If rel_to_scope is None, return the full pathname.

get_trait(name, copy=False)

Returns the trait indicated by name, or None if not found. No recursive search is performed if name contains dots. This is a replacement for the trait() method on HasTraits objects, because that method can return traits that shouldn’t exist. Do not use the trait() function unless you are certain that the named trait exists.

get_wrapped_attr(name)

If the named trait can return a TraitValWrapper, then this function will return that, with the value set to the current value of the named variable. Otherwise, it functions like getattr, just returning the value of the named variable. Raises an exception if the named trait cannot be found. The value will be copied if the trait has a ‘copy’ metadata attribute that is not None. Possible values for ‘copy’ are ‘shallow’ and ‘deep’.

items(recurse=False, **metadata)

Return a list of tuples of the form (rel_pathname, obj) for each trait of this Container that matches the given metadata. If recurse is True, also iterate through all child Containers of each Container found.

list_containers()

Return a list of names of child Containers.

post_load()

Perform any required operations after model has been loaded.

pre_delete()

Perform any required operations before being deleted.

remove(name)

Remove the specified child from this container and remove any public trait objects that reference that child. Notify any observers.

remove_trait(name)

Overrides HasTraits definition of remove_trait in order to keep track of dynamically added traits for serialization.

revert_to_defaults(recurse=True)

Sets the values of all of the inputs to their default values.

save(outstream, fmt=4, proto=-1)

Save the state of this object and its children to the given output stream. Pure Python classes generally won’t need to override this because the base class version will suffice, but Python extension classes will have to override. The format can be supplied in case something other than cPickle is needed.

outstream: file or string

Stream to save to.

fmt: int

Format for saved data.

proto: int

Protocol used.

set(path, value, index=None, src=None, force=False)

Set the value of the Variable specified by the given path, which may contain ‘.’ characters. The Variable will be set to the given value, subject to validation and constraints. index, if not None, should be a list of container indices and/or single entry lists of attribute names. For example, to get something like comp.x[2][‘mykey’].child.value, index would look like: [2,’mykey’,[‘child’],[‘value’]]. Attribute names are placed in sublists to avoid ambiguity with string container indices.

tree_rooted()

Called after the hierarchy containing this Container has been defined back to the root. This does not guarantee that all sibling Containers have been defined. It also does not guarantee that this component is fully configured to execute.

class openmdao.main.interfaces.IDOEgenerator

Bases: enthought.traits.has_traits.Interface

An iterator that returns arrays of normalized values that are mapped to design variables by a Driver.

Int num_parameters

number of parameters in the DOE

• default: ‘0’

class openmdao.main.interfaces.IDifferentiator

Bases: enthought.traits.has_traits.Interface

A plugin to driver that can determine derivatives between a driver’s parameters and its objectives and constraints.

calc_gradient()

Returns the gradient vectors for this Driver’s workflow

calc_hessian()

Returns the Hessian matrix for this Driver’s workflow

class openmdao.main.interfaces.IDriver

Bases: enthought.traits.has_traits.Interface

A marker interface for Drivers. To make a usable IDriver plug-in, you must still inherit from Driver.

Instance (Workflow) workflow

• default: ‘None’
• copy: ‘deep’

iteration_set()

Return a set of names (not pathnames) containing all Components in all of the workflows managed by this Driver.

class openmdao.main.interfaces.IFactory

Bases: enthought.traits.has_traits.Interface

An object that creates and returns objects based on a type string.

create(typ)

Create an object of the specified type and return it, or a proxy to it if it resides in another process.

class openmdao.main.interfaces.IHasConstraints

Bases: openmdao.main.interfaces.IHasEqConstraints, openmdao.main.interfaces.IHasIneqConstraints

An Interface for objects containing both equality and inequality constraints.

add_constraint(expr_string)

Adds a constraint as a string containing an assignment or an inequality, e.g., ‘a=b’ or ‘a<=b’.

class openmdao.main.interfaces.IHasEqConstraints

Bases: enthought.traits.has_traits.Interface

An Interface for objects containing equality constraints.

add_constraint(expr_string)

Adds an equality constraint.

expr_string: str

A string containing an assignment, e.g., ‘a = 2*b+5’

add_eq_constraint(lhs, rhs)

Adds an equality constraint.

lhs: str

Left-hand side of the equality.

rhs: str

Right-hand side of the equality.

clear_constraints()

Removes all constraints.

eval_eq_constraints()

Evaluates the constraint expressions and returns a list of tuples of the form (lhs, rhs, operator, is_violated), where rhs is the right-hand side of the equality, lhs is the left-hand side of the equality, operator is the string ‘=’, and is_violated is a boolean which is True if the constraint is currently violated. The operator entry in the tuple is always the same for an equality constraint, but is included for consistency with the eval_ineq_constraints function used for inequality constraints.

get_eq_constraints()

Returns an ordered dictionary of equality constraint objects.

remove_constraint(expr_string)

Removes the given constraint.

expr_string: str

A string matching the constraint to be removed. Whitespace is ignored when matching.

class openmdao.main.interfaces.IHasEvents

Bases: enthought.traits.has_traits.Interface

add_event(name)

Adds an event variable to be set when set_events is called.

name: str

Name of the event variable that should be set during execution.

clear_events()

Remove all event variables from the list.

get_events()

Return the list of event variables to be set.

remove_event(name)

Removes the specified event variable.

name: str

Name of the event to be removed.

set_events()

Set all events in the event list.

class openmdao.main.interfaces.IHasIneqConstraints

Bases: enthought.traits.has_traits.Interface

An Interface for objects containing inequality constraints.

add_constraint(expr_string)

Adds an inequality constraint as a string containing an inequality, for example, ‘a > b’.

add_ineq_constraint(lhs, rel, rhs)

Adds an inequality constraint as three strings; a left-hand side, a right-hand side, and a relation. The relation must be one of the following: ‘<’, ‘>’, ‘<=’, or ‘>=’.

clear_constraints()

Removes all constraints.

eval_ineq_constraints()

Evaluates the constraint expressions and returns a list of tuples of the form (lhs, rhs, relation, is_violated).

get_ineq_constraints()

Returns an ordered dict of inequality constraint objects.

remove_constraint(expr_string)

Removes the constraint matching the given string. Whitespace is ignored.

class openmdao.main.interfaces.IHasObjective

Bases: enthought.traits.has_traits.Interface

An Interface for objects having a single objective.

add_objective(expr)

Sets the objective of this driver to be the specified expression. If there is a preexisting objective in this driver, it is replaced.

expr: string

String containing the objective expression.

eval_objective()

Returns the value of the evaluated objective.

get_expr_depends()

Returns a list of tuples of the form (src_comp_name, dest_comp_name) for each dependency introduced by our objective.

list_objective()

Returns the expression string for the objective.

class openmdao.main.interfaces.IHasObjectives

Bases: enthought.traits.has_traits.Interface

An Interface for objects having a multiple objectives.

add_objective(expr)

Adds an objective to the driver.

expr: string

String containing the objective expression.

add_objectives(obj_iter)

Takes an iterator of objective strings and creates objectives for them in the driver.

clear_objectives()

Removes all objectives.

eval_objectives()

Returns a list of values of the evaluated objectives.

get_expr_depends()

Returns a list of tuples of the form (src_comp_name, dest_comp_name) for each dependency introduced by our objectives.

list_objectives()

Returns a list of objective expression strings.

remove_objective(expr)

Removes the specified objective expression. Spaces within the expression are ignored.

class openmdao.main.interfaces.IHasParameters

Bases: enthought.traits.has_traits.Interface

add_parameter(param_name, low=None, high=None)

Adds a parameter to the driver.

param_name: str

Name of the parameter to add.

low: number (optional)

Minimum allowed value the optimzier can use for this parameter. If not specified, then the low value from the variable is used.

high: number (optional)

Maximum allowed value the optimizer can use for this parameter. If not specified, then the high value from the variable is used.

add_parameters(param_iter)

Adds the given iterator of parameters to the driver.

param_iter: Iterator returning entries of the form (param_name, low, high)

Adds each parameter in the iterator to the driver, setting lower and upper bounds based on the values of low and high.

clear_parameters()

Removes all parameters.

get_parameters()

Returns an ordered dict of parameter objects.

list_parameters()

Lists all the parameters.

remove_parameter(param_name)

Removes the specified parameter. Raises a KeyError if param_name is not found.

param_name: str

Name of the parameter to remove.

set_parameters(X)

Pushes the values in the X input array into the corresponding variables in the model.

X: iterator

iterator of input values with an order defined to match the order of parameters returned by the list_parameter method. X must support the len() function.

class openmdao.main.interfaces.IResourceAllocator

Bases: enthought.traits.has_traits.Interface

An object responsible for allocating CPU/disk resources for a particular host, cluster, load balancer, etc.

deploy(name, resource_desc, criteria)

Deploy a server suitable for resource_desc. criteria is the dictionary returned by time_estimate(). Returns a proxy to the deployed server.

list_allocated_components()

Return a list of tuples (hostname, pid, component_name) for each Component currently allocated by this allocator.

max_servers(resource_desc)

Return the maximum number of servers which could be deployed for resource_desc. The value needn’t be exact, but performance may suffer if it overestimates. The value is used to limit the number of concurrent evaluations.

time_estimate(resource_desc)

Return (estimate, criteria) indicating how well this resource allocator can satisfy the resource_desc request. The estimate will be:

• >0 for an estimate of walltime (seconds).
• 0 for no estimate.
• -1 for no resource at this time.
• -2 for no support for resource_desc.

The returned criteria is a dictionary containing information related to the estimate, such as load averages, unsupported resources, etc.

class openmdao.main.interfaces.ISurrogate

Bases: enthought.traits.has_traits.Interface

get_uncertain_value(value)

Converts a deterministic value into an uncertain quantity which matches the uncertain variable type the surrogate predicts.

predict(X)

Predicts a value of from the surrogate model for the given independent values in X.

X: list

The input values for which the predicted output is requested.

Returns the predicted output value.

train(X, Y)

Trains the surrogate model, based on the given training data set.

X: iterator of lists

Values representing the training case input history.

y: iterator

Training case output history for this surrogate’s output, which corresponds to the training case input history given by X.

class openmdao.main.interfaces.IUncertainVariable

Bases: enthought.traits.has_traits.Interface

A variable which supports uncertainty

expected()

Calculates the expected value of the uncertainty distribution.

getvalue()

Returns either value from expected() or from sample() depending on the global or local uncertainty setting.

sample()

Generates a random number from an uncertain distribution.

openmdao.main.interfaces.obj_has_interface(obj, *ifaces)

Returns True if the specified object inherits from HasTraits and claims it implements one or more of the specified interfaces. If it is not a HasTraits object, then validate_implements() will be called on the object, which is slower because it actually checks for the presence of all methods and attributes specified in the interfaces.

mp_distributing.py

This module is based on the distributing.py file example which was (temporarily) posted with the multiprocessing module documentation.

This code assumes ssh has been set-up on all hosts such that no user intervention for passwords or passphrases is required.

class openmdao.main.mp_distributing.Cluster(hostlist, modules=None, authkey=None, allow_shell=False)

Bases: openmdao.main.mp_support.OpenMDAO_Manager

Represents a collection of hosts.

hostlist: list(Host)

Hosts which are to be members of the cluster.

modules: list(string)

Names of modules to be sent to each host.

authkey: string

Authorization key, passed to OpenMDAO_Manager.

allow_shell: bool

If True, execute_command() and load_model() are allowed in created servers. Use with caution!

openmdao_main_resource_LocalAllocator(*args, **kwds)

shutdown()

Shut down all remote managers and then this one.

start()

Start this manager and all remote managers.

class openmdao.main.mp_distributing.Host(hostname, python=None)

Bases: object

Represents a host to use as a node in a cluster.

hostname: string

Name of the host. ssh is used to log into the host. To log in as a different user use a host name of the form: “username@somewhere.org”.

python: string

Path the the Python command to be used on hostname.

poll()

Poll for process status.

register(cls)

Register proxy info to be sent to remote server.

cls: class

Class to be registered.

start_manager(index, authkey, address, files, allow_shell=False)

Launch remote manager process via ssh. The environment variable OPENMDAO_KEEPDIRS can be used to avoid removal of the temporary directory used on the host.

index: int

Index in parent cluster.

authkey: string

Authorization key used to connect to host server.

address: (ip_addr, port) or string referring to pipe.

Address to use to connect back to parent.

files: list(string)

Files to be sent to support server startup.

allow_shell: bool

If True, execute_command() and load_model() are allowed in created servers. Use with caution!

class openmdao.main.mp_distributing.HostManager(address, authkey)

Bases: openmdao.main.mp_support.OpenMDAO_Manager

Manager used for spawning processes on a remote host.

address: (ip_addr, port) or string referring to pipe.

Address to use to connect back to parent.

authkey: string

Authorization key, passed to OpenMDAO_Manager.

classmethod from_address(address, authkey)

Return manager given an address.

address: (ip_addr, port) or string referring to pipe.

Address to connect to.

authkey: string

Authorization key.

openmdao_main_resource_LocalAllocator(*args, **kwds)

openmdao.main.mp_distributing.main()

Code which runs a host manager. Expects configuration data from parent on stdin. Replies with address and optionally public key. The environment variable OPENMDAO_KEEPDIRS can be used to avoid removal of the temporary directory used here.

mp_support.py

This module defines modified versions of some classes and functions defined in multiprocessing.managers to support OpenMDAO distributed simulations.

Channel communication can be secured by setting authkey to ‘PublicKey’. When authkey is ‘PublicKey’, an additional session establishment protocol is used between the Proxy and Server:

1. Proxy sends session request containing the proxy’s public key, encrypted with the server’s public key (obtained when told what server to connect to).
2. Server responds with random session key, encrypted with proxy’s public key.
3. Subsequent communication is encrypted with the session key (which presumably is quicker than public/private key encryption).

If authkey is not ‘PublicKey’, then the above session protocol is not used, and channel data is in the clear.

Public methods of an object are determined by a role-based access control attribute associated with the method. The server will verify that the current role is allowed access. The current role is determined by an AccessController based on a Credentials object received from the proxy.

Assuming the credentials check passes, the server will set it’s credentials to those specified by the AccessController during the execution of the method.

class openmdao.main.mp_support.ObjectManager(obj, address=None, serializer='pickle', authkey=None, name=None, allowed_hosts=None, allowed_users=None)

Bases: object

Provides a multiprocessing interface for an existing object.

obj: object

Object to provide remote access to.

address: tuple or string

A multiprocessing address specifying an Internet address or a pipe.

serializer: string

Which serialization method to use.

authkey: string

Authorization key. Inherited from the current Process object if not specified.

name: string

Name for server, used in log files, etc.

allowed_hosts: list(string)

Host address patterns to check against.

allowed_users: dict

Dictionary of users and corresponding public keys allowed access. If None, any user may access. If empty, no user may access.

proxy

Proxy for our object server.

class openmdao.main.mp_support.OpenMDAO_Manager(address=None, authkey=None, serializer='pickle', pubkey=None, name=None, allowed_hosts=None, allowed_users=None)

Bases: multiprocessing.managers.BaseManager

Uses OpenMDAO_Server, retains the public key, and puts some slack in shutdown timing.

address: tuple or string

A multiprocessing address specifying an Internet address or a pipe.

authkey: string

Authorization key. Inherited from the current Process object if not specified.

serializer: string

Which serialization method to use.

pubkey: public key

Public portion of server’s public/private key pair. Needed for client/proxy side.

name: string

Name for server, used in log files, etc.

allowed_hosts: list(string)

Host address patterns to check against.

allowed_users: dict

Dictionary of users and corresponding public keys allowed access. If None, any user may access. If empty, no user may access.

get_server()

Return a server object with serve_forever() and address attribute.

start(cwd=None)

Spawn a server process for this manager object.

cwd: string

Directory to start in.

This version retrieves the server’s public key.

class openmdao.main.mp_support.OpenMDAO_Proxy(*args, **kwds)

Bases: multiprocessing.managers.BaseProxy

Proxy for a remote object.

args: tuple

Passed to BaseProxy.

kwds: dict

If it contains pubkey, then that value is used for the remote public key, and the entry is removed before being passed to BaseProxy.

This version sends credentials and provides dynamic result proxy generation.

static manager_is_alive(address)

Check whether manager is still alive.

address: tuple or string

A multiprocessing address specifying an Internet address or a pipe.

class openmdao.main.mp_support.OpenMDAO_Server(registry, address, authkey, serializer, name=None, allowed_hosts=None, allowed_users=None)

Bases: multiprocessing.managers.Server

A Server that supports dynamic proxy generation and credential checking.

registry: dict

Manager’s proxy registry.

address: tuple or string

A multiprocessing address specifying an Internet address or a pipe.

authkey: string

Authorization key. Inherited from the current Process object if not specified.

serializer: string

Which serialization method to use.

name: string

Name for server, used in log files, etc.

allowed_hosts: list(string)

Host address patterns to check against. Ignored if allowed_users is specified.

allowed_users: dict

Dictionary of users and corresponding public keys allowed access. If None, any user may access. If empty, no user may access. The host portions of user strings are used for address patterns.

create(conn, typeid, *args, **kwds)

Create a new shared object and return its id.

conn: socket or pipe

Connection to process.

typeid: string

Identifier string for type of object to be created.

This version uses public_methods().

debug_info(conn)

Return string representing state of id_to_obj mapping.

conn: socket or pipe

Unused.

This version handles proxies in a special manner.

handle_request(conn)

Handle a new connection.

conn: socket or pipe

Connection to process.

This version filters host connections and avoids getting upset if it can’t deliver a challenge. This is to deal with immediately closed connections caused by manager_is_alive() which are used to avoid getting hung trying to connect to a manager which is no longer there.

serve_client(conn)

Handle requests from the proxies in a particular process/thread.

conn: socket or pipe

Connection to process.

This version supports dynamic proxy generation and credential checking.

serve_forever()

Run the server forever. This version supports host connection filtering. Connection filtering allows for PublicKey servers which aren’t accessible by just any host.

shutdown(conn)

Shutdown this process.

public_key

Public key for session establishment.

public_key_text

Text representation of public key.

openmdao.main.mp_support.has_interface(obj, *ifaces)

obj_has_interface() replacement for when obj might be a proxy.

obj: object

Object to be tested.

ifaces: list[Interface]

Interfaces to be tested against.

Returns True if obj or the object obj refers to supports at least one Interface in ifaces.

openmdao.main.mp_support.is_instance(obj, typ)

isinstance() replacement for when obj might be a proxy.

obj: object

Object to be tested.

typ: class

Class to be tested against.

Returns True if obj is an instance of typ, or the object obj refers to is an instance of typ.

openmdao.main.mp_support.register(cls, manager, module=None)

Register class cls proxy info with manager. The class will be registered under it’s full path, with ‘.’ replaced by ‘_’. Not typically called by user code.

cls: class

Class to be registered.

manager: OpenMDAO_Manager

Manager to register with.

module: string

Module name for registration. Necessary if cls might be defined by module ‘__main__’.

mp_util.py

Multiprocessing support utilities.

openmdao.main.mp_util.decrypt(msg, session_key)

If session_key is specified, returns object from encrypted pickled data contained in msg. Otherwise msg is returned.

msg: string

Encrypted text of pickled object.

session_key: string

Key used for encryption. Should be at least 16 bytes long.

openmdao.main.mp_util.encrypt(obj, session_key)

If session_key is specified, returns (length, data) of encrypted, pickled, obj. Otherwise obj is returned.

obj: object

Object to be pickled and encrypted.

session_key: string

Key used for encryption. Should be at least 16 bytes long.

openmdao.main.mp_util.is_legal_connection(address, allowed_hosts, logger)

Return True if address is from an allowed host.

address: string

Connection address to be checked.

allowed_hosts: list(string)

IPv4 address patterns to check against. If a pattern ends with ‘.’ (a domain) then the host address must begin with the pattern. Otherwise the host address must completely match the pattern.

logger: logging.Logger

Used to output warnings about rejected connections.

openmdao.main.mp_util.keytype(authkey)

Just returns a string showing the type of authkey.

authkey: string

Key to report type of.

openmdao.main.mp_util.make_typeid(obj)

Returns a type ID string from obj‘s module and class names by replacing ‘.’ with ‘_’.

openmdao.main.mp_util.public_methods(obj)

Returns a list of names of the methods of obj to be exposed. Supports attribute access in addition to RBAC decorated methods.

obj: object

Object to be scanned.

openmdao.main.mp_util.read_allowed_hosts(path)

Return allowed hosts data read from path.

path: string

Path to allowed hosts file (typically ‘hosts.allow’).

The file should contain IPv4 host addresses, IPv4 domain addresses, or hostnames, one per line. Blank lines are ignored, and ‘#’ marks the start of a comment which continues to the end of the line.

openmdao.main.mp_util.read_server_config(filename)

Read a server’s connection information.

filename: string

Path to file to be read.

Returns (address, port, key).

openmdao.main.mp_util.write_server_config(server, filename)

Write server connection information.

server: OpenMDAO_Server

Server to be recorded.

filename: string

Path to file to be written.

Connection information including IP address, port, and public key is written using ConfigParser.

objserverfactory.py

Support for an OpenMDAO ‘object service’, a factory that can create servers which support various operations such as creating objects, loading models via egg files, remote execution, and remote file access.

class openmdao.main.objserverfactory.ObjServer(name='', allow_shell=False, allowed_types=None)

Bases: object

An object which knows how to create other objects, load a model, etc. All remote file accesses must be within the tree rooted in the current directory at startup.

name: string

Name of server, used in log messages, etc.

allow_shell: bool

If True, execute_command() and load_model() are allowed. Use with caution!

allowed_types: list(string)

Names of types which may be created. If None, then allow types listed by factorymanager.get_available_types(). If empty, no types are allowed.

chmod(path, mode)

Returns os.chmod(path, mode) if path is legal.

path: string

Path to file to modify.

mode: int

New mode bits (permissions).

create(typname, version=None, server=None, res_desc=None, **ctor_args)

If typname is an allowed type, returns an object of type typname, using the specified package version, server location, and resource description. All arguments are passed to factorymanager.create().

echo(*args)

Simply return the arguments. This can be useful for latency/thruput masurements, connectivity testing, firewall keepalives, etc.

execute_command(command, stdin, stdout, stderr, env_vars, poll_delay, timeout)

Run command in a subprocess if this server’s allow_shell attribute is True.

command: string

Command line to be executed.

stdin, stdout, stderr: string

Filenames for the corresponding stream.

env_vars: dict

Environment variables for the command.

poll_delay: float (seconds)

Delay between polling subprocess for completion.

timeout: float (seconds)

Maximum time to wait for command completion. A value of zero implies no timeout.

load_model(egg_filename)

Load model from egg and return top-level object if this server’s allow_shell attribute is True.

egg_filename: string

Filename of egg to be loaded.

open(filename, mode='r', bufsize=-1)

Returns open(filename, mode, bufsize) if filename is legal.

filename: string

Name of file to open.

mode: string

Accees mode.

bufsize: int

Size of buffer to use.

pack_zipfile(patterns, filename)

Create ZipFile of files matching patterns if filename is legal.

patterns: list

List of glob-style patterns.

filename: string

Name of ZipFile to create.

remove(path)

Remove path if path is legal.

path: string

Path to file to remove.

stat(path)

Returns os.stat(path) if path is legal.

path: string

Path to file to interrogate.

unpack_zipfile(filename)

Unpack ZipFile filename if filename is legal.

filename: string

Name of ZipFile to unpack.

class openmdao.main.objserverfactory.ObjServerFactory(name='ObjServerFactory', authkey=None, allow_shell=False, allowed_types=None, address=None)

Bases: openmdao.main.factory.Factory

An ObjServerFactory creates ObjServers and objects within those servers.

name: string

Name of factory, used in log messages, etc.

authkey: string

Passed to created ObjServer servers.

allow_shell: bool

Passed to created ObjServer servers.

allowed_types: list(string)

Passed to created ObjServer servers.

address: tuple or string

A multiprocessing address specifying an Internet address or a pipe (default). Created ObjServer servers will use the same form of address.

The environment variable OPENMDAO_KEEPDIRS can be used to avoid having server directory trees removed when servers are shut-down.

cleanup()

Shut-down all remaining ObjServers.

create(typname, version=None, server=None, res_desc=None, **ctor_args)

Create a new typname object in server or a new ObjectServer. Returns a proxy for for the new object. Starts servers in a subdirectory of the current directory.

typname: string

Type of object to create. If null then a proxy for the new ObjServer is returned.

version: string or None

Version of typname to create.

server: proxy

ObjServer on which to create typname. If none, then a new server is created.

res_desc: dict or None

Required resources. Currently not used.

ctor_args: dict

Other constructor arguments. If name or allowed_users are specified, they are used when creating the ObjServer. If no allowed_users are specified, the server is private to the current user.

echo(*args)

Simply return the arguments. This can be useful for latency/thruput masurements, connectivity testing, firewall keepalives, etc.

get_available_types(groups=None)

Returns a set of tuples of the form (typename, dist_version), one for each available plugin type in the given entry point groups. If groups is None, return the set for all openmdao entry point groups.

release(server)

Shut-down ObjServer server.

server: ObjServer

Server to be shut down.

class openmdao.main.objserverfactory.RemoteFile(fileobj)

Bases: object

Wraps a file with remote-access annotations such that only role ‘owner’ may access the file.

close()

Close the file.

flush()

Flush any buffered output.

read(size=-1)

Read up to size bytes.

readline(size=-1)

Read one line.

readlines(sizehint=-1)

Read until EOF.

write(data)

Write data to the file.

closed

True if file is not open.

openmdao.main.objserverfactory.connect(address, port, authkey='PublicKey', pubkey=None)

Connects to the ObjServerFactory at address and port using key and returns a (shared) proxy for it.

address: string

IP address for server, or pipe filename.

port: int

Server port. If < 0, address is a pipe filename.

authkey:

Server authorization key.

pubkey:

Server public key, required if authkey is ‘PublicKey’.

openmdao.main.objserverfactory.main()

OpenMDAO factory service process.

Usage: python objserverfactory.py [–allow-public][–allow-shell][–hosts=filename][–types=filename][–users=filename][–address=address][–port=number][–prefix=name]

–allow-public:

Allows access by anyone from any allowed host. Use with care!

–allow-shell:

Allows access to execute_command() and load_model(). Use with care!

–hosts: string

Filename for allowed hosts specification. Default hosts.allow. Ignored if ‘–users’ is specified. The file should contain IPv4 host addresses, IPv4 domain addresses, or hostnames, one per line. Blank lines are ignored, and ‘#’ marks the start of a comment which continues to the end of the line.

–types: string

Filename for allowed types specification. If not specified then allow types listed by factorymanager.get_available_types(). The file should contain one type name per line.

–users: string

Filename for allowed users specification. Ignored if ‘–allow-public’ is specified. Default is ~/.ssh/authorized_keys, other files should be of the same format. The host portions of user strings are used for allowed hosts.

–address: string

IPv4 address, hostname, or pipe name. Default is the host’s default IPv4 address.

–port: int

Server port (default of 0 implies next available port). Note that ports below 1024 typically require special privileges. If port is negative, then a local pipe is used for communication.

–prefix: string

Prefix for configuration and stdout/stderr files (default server).

If prefix.key exists, it is read for an authorization key string. Otherwise public key authorization and encryption is used.

Allowed hosts must be specified if port is >= 0. Only allowed hosts may connect to the server.

Once initialized prefix.cfg is written with address, port, and public key information.

openmdao.main.objserverfactory.start_server(authkey='PublicKey', address=None, port=0, prefix='server', allowed_hosts=None, allowed_users=None, allow_shell=False, allowed_types=None, timeout=None)

Start an ObjServerFactory service in a separate process in the current directory.

authkey: string

Authorization key, must be matched by clients.

address: string

IPv4 address, hostname, or pipe name. Default is the host’s default IPv4 address.

port: int

Server port (default of 0 implies next available port). Note that ports below 1024 typically require special privileges. If port is negative, then a local pipe is used for communication.

prefix: string

Prefix for server config file and stdout/stderr file.

allowed_hosts: list(string)

Host address patterns to check against. Required if port >= 0. Ignored if allowed_users is specified.

allowed_users: dict

Dictionary of users and corresponding public keys allowed access. If None, any user may access. If empty, no user may access. The host portions of user strings are used for address patterns.

allow_shell: bool

If True, execute_command() and load_model() are allowed. Use with caution!

allowed_types: list(string)

Names of types which may be created. If None, then allow types listed by get_available_types(). If empty, no types are allowed.

timeout: int

Seconds to wait for server to start. Note that public key generation can take a while. The default value of None will use an internally computed value based on host type (and for Windows, the availability of pyWin32).

Returns ShellProc.

pkg_res_factory.py

class openmdao.main.pkg_res_factory.EntryPtLoader(name, group, dist, entry_pt)

Bases: object

Holder of entry points. Will perform lazy importing of distributions as needed.

create(env, **ctor_args)

Return the object created by calling the entry point. If necessary, first activate the distribution and load the entry point, and check for conflicting version dependencies before loading.

class openmdao.main.pkg_res_factory.PkgResourcesFactory(groups, search_path=None)

Bases: openmdao.main.factory.Factory

A Factory that loads plugins using the pkg_resources API, which means it searches through egg info of distributions in order to find any entry point groups corresponding to openmdao plugin types, e.g., openmdao.component, openmdao.variable, etc.

create(typ, version=None, server=None, res_desc=None, **ctor_args)

Create and return an object of the given type, with optional name, version, server id, and resource description.

get_available_types(groups=None)

Return a set of tuples of the form (typename, dist_version), one for each available plugin type in the given entry point groups. If groups is None, return the set for all openmdao entry point groups.

get_loaders(group, active=True)

Return a list of EntryPointLoaders with group ids that match the given group.

update_search_path(search_path)

Updates the plugin search path.

openmdao.main.pkg_res_factory.import_version(modname, req, env=None)

Import the specified module from the package specified in the Requirement req, if it can be found in the current WorkingSet or in the specified Environment. If a conflicting version already exists in the WorkingSet, a VersionConflict will be raised. If a distrib cannot be found matching the requirement, raise a DistributionNotFound.

plugin.py

openmdao.main.plugin.plugin_build_docs(argv=None)

A command line script (plugin_build_docs) points to this. It builds the Sphinx documentation for the specified distribution directory. If no directory is specified, the current directory is assumed.

usage: plugin_build_docs [dist_dir_path]

openmdao.main.plugin.plugin_docs(argv=None)

A command line script (plugin_docs) points to this. It brings up the Sphinx documentation for the named plugin in a browser.

openmdao.main.plugin.plugin_install(argv=None)

A command line script (plugin_install) points to this. It installs the specified plugin distribution into the current environment.

openmdao.main.plugin.plugin_makedist(argv=None)

A command line script (plugin_makedist) points to this. It creates a source distribution containing Sphinx documentation for the specified distribution directory. If no directory is specified, the current directory is assumed.

usage: plugin_makedist [dist_dir_path]

openmdao.main.plugin.plugin_quickstart(argv=None)

A command line script (plugin_quickstart) points to this. It generates a directory structure for an openmdao plugin package along with Sphinx docs.

usage: plugin_quickstart <dist_name> [-v <version>] [-d <dest_dir>] [-g <plugin_group>] [-c class_name]

openmdao.main.plugin.update_libpath()

Find all of the shared libraries in the current virtual environment and modify the activate script to put their directories in LD_LIBRARY_PATH

rbac.py

Support for Role-Based Access Control (RBAC).

Remote access to methods is determined by a role-based access control attribute attached to the method. This attribute contains a sequence of role patterns, an optional proxy role to be used while executing the method, and a list of return types which are to be proxied. The rbac decorator is available for assigning this access control attribute to methods.

Remote access to attributes is checked based on role, accessing method, object, and attribute.

These access checks are mediated by an AccessController. There is a default controller assigned to each OpenMDAO_Server. The server will check for an object-specific controller by trying to invoke get_access_controller() on the object before using the default.

The current role is determined from a Credentials object which is attached to the current thread. Mapping from credentials to roles can become fairly involved in a real system, typically with site-specific configuration. The default role mapping here just returns the roles ‘owner’ or ‘user’ based on whether the credentials match those in effect when the controller object was created.

Warning

Credentials as currently defined are quite weak unless the receiver has a list of known client keys. This access control scheme should not be relied upon unless the receiving server verifies that the Credentials public key matches what is expected.

exception openmdao.main.rbac.CredentialsError

Bases: exceptions.Exception

Raised when decoding/verifying received credentials.

exception openmdao.main.rbac.RoleError

Bases: exceptions.Exception

Raised when the current role is not allowed to invoke the requested method. Also raised when encountering some internal problems.

class openmdao.main.rbac.AccessController

Bases: object

Responsible for mapping Credentials to roles and optionally getting different credentials for executing a method.

Also reponsible for determining which attributes and classes require a proxy to be returned rather than the value.

attr_proxy_required(obj, attr, required=True)

Record that a proxy is/is not required for obj.attr.

obj: object

Object whose attribute is to be recorded.

attr: string

Name of attribute to be recorded.

required: bool

If True, a proxy must be created.

check_access(role, methodname, obj, attr)

Verify that role is allowed to invoke methodname of obj for attr.

role: string

Current role.

methodname: string

Name of method to be invoked.

obj: object

Object whose attribute is to be accessed.

attr: string

Name of attribute to be accessed.

Used for access control on getattr(), setattr(), and delattr() operations. This default version requires a non-null role, and only ‘owner’ may delete attributes.

class_proxy_required(cls)

Record that a proxy is required for cls or any subclasses.

cls: class

Class to be recorded.

get_proxy_credentials(meth, credentials)

If special credentials are needed while executing meth, return them, else return credentials.

meth: method

Method to be invoked.

credentials: Credentials

Current credentials in effect.

get_role(credentials)

Trivial Credentials-to-role mapping.

credentials: Credentials

Credentials to obtain role for.

Returns the role associated with credentials.

This version returns a null string for no credentials, ‘owner’ if credentials matches the credentials in effect when we were created, and ‘user’ otherwise.

need_proxy(obj, attr, res)

Returns True if attr of obj whose value is res requires a proxy.

obj: object

Object whose attribute is to be returned.

attr: string

Name of attribute accessed.

res: object

Result to be returned.

Checks res against registered classes to be proxied as well as the proxy registry for obj.attr.

set_proxy_credentials(proxy_role, credentials)

Set credentials to be used for proxy_role to credentials.

proxy_role: string

Role to assign credentials to.

credentials: Credentials

Credentials to be assigned.

class openmdao.main.rbac.Credentials(encoded=None)

Bases: object

Credentials are used to certify that a message is from a particular user on a particular host. The scheme here is quite weak unless the receiver has a list of known client keys.

Essentially all we can prove here is that someone somewhere created a correctly formed credential. Without known client keys at the receiving end the best we can do is detect when more than one client claims the same identity.

If the receiver does keep a list of known client keys, then the information here will support strict authorization.

The client_creds attribute is simply used to trace back to the original user, it is not part of the credentials signature. It is carried along for auditing purposes when proxy credentials are used to allow a publicly accessible proprietary method to invoke other restricted methods on behalf of an ordinary user.

encoded: tuple

If specified, data used to recreate a remote Credentials object.

encode()

Return object to be sent: (data, signature, client_creds).

static verify(encoded, allowed_users)

Verify that encoded is a valid encoded credentials object and that its public key matches the public key we’ve already seen, if any.

encoded: tuple

Encoded credentials.

allowed_users: dict

Dictionary of users and corresponding public keys allowed access. If None, any user may access. If empty, no user may access.

Returns Credentials object from encoded.

class openmdao.main.rbac.rbac(roles, proxy_role='', proxy_types=None)

Bases: object

Decorator for specifying RBAC roles for a method.

roles: string or sequence[string]

Role name patterns which are allowed access.

proxy_role: string

Role to use during execution of method. A null string implies that the current role is used.

proxy_types: list[class]

Types of return values that must be proxied.

openmdao.main.rbac.check_role(role, meth)

Verifies that role is matched by at least one fnmatch-style pattern in meth‘s RBAC. Raises RoleError if no match is found.

role: string

Role to be checked.

meth: method.

Method to be checked.

openmdao.main.rbac.get_credentials()

Get the current thread’s credentials.

openmdao.main.rbac.need_proxy(meth, result)

Returns True if result from meth requires a proxy.

meth: method.

Method to be checked.

result: object

Result value to be checked.

openmdao.main.rbac.rbac_decorate(method, roles, proxy_role='', proxy_types=None)

Post-definition decorator for specifying RBAC roles for a method. Not typically used, but needed if proxy_types must include the class currently being defined, since the normal decorator won’t see the class yet.

method: instancemethod

Method to be decorated.

roles: string or sequence[string]

Role name patterns which are allowed access.

proxy_role: string

Role to use during execution of method. A null string implies that the current role is used.

proxy_types: list[class]

Types of return values that must be proxied.

openmdao.main.rbac.rbac_methods(obj)

Returns a list of names of the methods of obj to be exposed.

obj: object

Object to be scanned.

openmdao.main.rbac.remote_access()

Return True if the current thread is providing remote access.

openmdao.main.rbac.set_credentials(credentials)

Set the current thread’s credentials.

resource.py

Support for allocation of servers from one or more resources (i.e., the local host, a cluster of remote hosts, etc.)

class openmdao.main.resource.ClusterAllocator(name, machines, authkey=None, allow_shell=False)

Bases: object

Cluster-based resource allocator. This allocator manages a collection of LocalAllocator, one for each machine in the cluster.

name: string

Name of allocator, used in log messages, etc.

machines: list(dict)

Dictionaries providing configuration data for each machine in the cluster. At a minimum, each dictionary must specify a host address in ‘hostname’ and the path to the OpenMDAO Python command in ‘python’.

authkey: string

Authorization key to be passed-on to remote servers.

allow_shell: bool

If True, execute_command() and load_model() are allowed in created servers. Use with caution!

We assume that machines in the cluster are similar enough that ranking by load average is reasonable.

deploy(name, resource_desc, criteria)

Deploy a server suitable for resource_desc. Uses the allocator saved in criteria. Returns a proxy to the deployed server.

name: string

Name for server.

resource_desc: dict

Description of required resources.

criteria: dict

The dictionary returned by time_estimate().

max_servers(resource_desc)

Returns the total of max_servers() across all LocalAllocator in the cluster.

resource_desc: dict

Description of required resources.

release(server)

Release a server (proxy).

server: OpenMDAO_Proxy

Server to be released.

shutdown()

Shutdown, releasing resources.

time_estimate(resource_desc)

Returns (estimate, criteria) indicating how well this allocator can satisfy the resource_desc request. The estimate will be:

• >0 for an estimate of walltime (seconds).
• 0 for no estimate.
• -1 for no resource at this time.
• -2 for no support for resource_desc.

The returned criteria is a dictionary containing information related to the estimate, such as hostnames, load averages, unsupported resources, etc.

This allocator polls each LocalAllocator in the cluster to find the best match and returns that. The best allocator is saved in the returned criteria for a subsequent deploy().

resource_desc: dict

Description of required resources.

class openmdao.main.resource.LocalAllocator(name='LocalAllocator', total_cpus=0, max_load=1.0, authkey=None, allow_shell=False)

Bases: openmdao.main.resource.ResourceAllocator

Purely local resource allocator.

name: string

Name of allocator, used in log messages, etc.

total_cpus: int

If >0, then that is taken as the number of cpus/cores available. Otherwise the number is taken from multiprocessing.cpu_count().

max_load: float

Specifies the maximum cpu-adjusted load (obtained from os.getloadavg()) allowed when reporting max_servers() and when determining if another server may be started in time_estimate().

authkey: string

Authorization key for this allocator and any deployed servers.

allow_shell: bool

If True, execute_command() and load_model() are allowed in created servers. Use with caution!

deploy(name, resource_desc, criteria)

Deploy a server suitable for resource_desc. Returns a proxy to the deployed server.

name: string

Name for server.

resource_desc: dict

Description of required resources.

criteria: dict

The dictionary returned by time_estimate().

max_servers(resource_desc)

Returns total_cpus * max_load if resource_desc is supported, otherwise zero.

resource_desc: dict

Description of required resources.

time_estimate(resource_desc)

Returns (estimate, criteria) indicating how well this allocator can satisfy the resource_desc request. The estimate will be:

• >0 for an estimate of walltime (seconds).
• 0 for no estimate.
• -1 for no resource at this time.
• -2 for no support for resource_desc.

The returned criteria is a dictionary containing information related to the estimate, such as hostnames, load averages, unsupported resources, etc.

resource_desc: dict

Description of required resources.

class openmdao.main.resource.ResourceAllocationManager

Bases: object

The allocation manager maintains a list of ResourceAllocator which are used to select the “best fit” for a particular resource request. The manager is initialized with a LocalAllocator for the local host, using authkey of ‘PublicKey’, and allowing ‘shell’ access. Additional allocators can be added and the manager will look for the best fit across all the allocators.

static add_allocator(allocator)

Add an allocator to the list of resource allocators.

allocator: ResourceAllocator

The allocator to be added.

static allocate(resource_desc)

Determine best resource for resource_desc and deploy. In the case of a tie, the first allocator in the allocators list wins. Returns (proxy-object, server-dict).

resource_desc: dict

Description of required resources.

static get_allocator(index)

Return allocator at index.

index: int

List index for allocator to be returned.

static get_hostnames(resource_desc)

Determine best resource for resource_desc and return hostnames. In the case of a tie, the first allocator in the allocators list wins. Typically used by parallel code wrappers which have MPI or something similar for process deployment.

resource_desc: dict

Description of required resources.

static get_instance()

Return singleton instance.

static insert_allocator(index, allocator)

Insert an allocator into the list of resource allocators.

index: int

List index for the insertion point.

allocator: ResourceAllocator

The allocator to be inserted.

static list_allocators()

Return list of allocators.

static max_servers(resource_desc)

Returns the maximum number of servers compatible with ‘resource_desc`. This should be considered an upper limit on the number of concurrent allocations attempted.

resource_desc: dict

Description of required resources.

static release(server)

Release a server (proxy).

server: OpenMDAO_Proxy

Server to be released.

class openmdao.main.resource.ResourceAllocator(name, authkey=None, allow_shell=False)

Bases: openmdao.main.objserverfactory.ObjServerFactory

Base class for allocators. Allocators estimate the suitability of a resource and can deploy on that resource.

name: string

Name of allocator, used in log messages, etc.

authkey: string

Authorization key for this allocator and any deployed servers.

allow_shell: bool

If True, execute_command() and load_model() are allowed in created servers. Use with caution!

check_orphan_modules(resource_value)

Returns True if this allocator can support the specified ‘orphan’ modules.

resource_value: list

List of ‘orphan’ module names.

check_required_distributions(resource_value)

Returns True if this allocator can support the specified required distributions.

resource_value: list

List of Distributions.

deploy(name, resource_desc, criteria)

Deploy a server suitable for resource_desc. Returns a proxy to the deployed server.

name: string

Name for server.

resource_desc: dict

Description of required resources.

criteria: dict

The dictionary returned by time_estimate().

max_servers(resource_desc)

Return the maximum number of servers which could be deployed for resource_desc. The value needn’t be exact, but performance may suffer if it overestimates. The value is used to limit the number of concurrent evaluations.

resource_desc: dict

Description of required resources.

time_estimate(resource_desc)

Return (estimate, criteria) indicating how well this resource allocator can satisfy the resource_desc request. The estimate will be:

• >0 for an estimate of walltime (seconds).
• 0 for no estimate.
• -1 for no resource at this time.
• -2 for no support for resource_desc.

The returned criteria is a dictionary containing information related to the estimate, such as hostnames, load averages, unsupported resources, etc.

resource_desc: dict

Description of required resources.

seqentialflow.py

class openmdao.main.seqentialflow.SequentialWorkflow(parent=None, scope=None, members=None)

Bases: openmdao.main.workflow.Workflow

A Workflow that is a simple sequence of components.

add(compnames)

Add new component(s) to the end of the workflow by name.

clear()

Remove all components from this workflow.

get_names()

Return a list of component names in this workflow.

remove(compname)

Remove a component from the workflow by name. Do not report an error if the specified component is not found.

treeproxy.py

class openmdao.main.treeproxy.TreeProxy(root, path)

Bases: object

Acts as a proxy object for objects within an opaque, hierarchically structured local object so that normal python attribute access will work to access objects inside of the opaque object’s tree.

The opaque object must implement the following interface which is checked only via duck typing:

def get(pathname, index=None)
def set(pathname, value, index=None)
def call(pathname, *args, **kwargs)
def __contains__(pathname)

where pathname is a dot separated name, and index is a list of element indices or attribute names, e.g., [2,1], [‘mykey’] or [2,1,[‘attrname’]]. Attribute names are buried inside of a nested list to avoid confusion with strings used to index into a container. Also, nested tuples are not used to avoid confusion for the same reason, i.e. they are hashable and therefore could be used to index into a container.

openmdao.main.treeproxy.all_tree_names(pathnames)

Returns the set of all names, including intermediate names, given a list of pathnames. For example, given the pathname ‘a.b.c’, it would return set([‘a’, ‘a.b’, ‘a.b.c’])

tvalwrapper.py

class openmdao.main.tvalwrapper.TraitValWrapper(value=None, **metadata)

Bases: object

A class that encapsulates a trait value and any metadata necessary for validation of that trait. For example, a TraitValWrapper for a Float object would include ‘units’ metadata to allow for unit compatability checking and conversion.

uncertain_distributions.py

class openmdao.main.uncertain_distributions.NormalDistribution(mu=0.0, sigma=1.0)

Bases: openmdao.main.uncertain_distributions.UncertainDistribution

An UncertainDistribution which represents a quantity with a normal distribution of uncertainty.

mu: float

mean value

sigma: float

standard deviation

expected()

sample()

class openmdao.main.uncertain_distributions.TriangularDistribution(max=0.0, min=1.0, mode=0.5, *args, **kwargs)

Bases: openmdao.main.uncertain_distributions.UncertainDistribution

An UncertainDistribution which represents a quantity with a triangular distribution of uncertainty.

min: float

minimum value

max: float

maximum value

mode: float

mode

expected()

sample()

class openmdao.main.uncertain_distributions.UncertainDistribution(valmethod=None)

Bases: object

Base class for uncertain variables.

expected()

getvalue()

sample()

class openmdao.main.uncertain_distributions.UniformDistribution(max=0.0, min=1.0, *args, **kwargs)

Bases: openmdao.main.uncertain_distributions.UncertainDistribution

An UncertainDistribution which represents a quantity with a uniform distribution of uncertainty.

min: float

minimum value

max: float

maximum value

expected()

sample()

class openmdao.main.uncertain_distributions.WeibullDistribution(alpha=1.0, beta=2.0, *args, **kwargs)

Bases: openmdao.main.uncertain_distributions.UncertainDistribution

An UncertainDistribution which represents a quantity with a weibull distribution of uncertainty.

alpha: float

scale parameter

beta: float

shape parameter

expected()

sample()

uses_derivatives.py

Decorator for drivers that need to take derivatives (either gradients or Hessians) of their workflow. The following delegates are available:

UsesGradients - if you need first derivatives

UsesHessians - if you need second derivatives

From a driver’s perspective, derivatives are needed from its parameters to its objective(s) and constraints.

class openmdao.main.uses_derivatives.UsesDerivatives_Base(parent)

Bases: object

This class provides an implementation of the derivatives delegates.

class openmdao.main.uses_derivatives.UsesGradients(parent)

Bases: openmdao.main.uses_derivatives.UsesDerivatives_Base

This class provides an implementation of the UsesGradients interface.

check_gradients()

Run check_derivatives on our workflow.

class openmdao.main.uses_derivatives.UsesHessians(parent)

Bases: openmdao.main.uses_derivatives.UsesDerivatives_Base

This class provides an implementation of the UsesHessians interface.

check_hessians()

Run check_derivatives on our workflow.

variable.py

class openmdao.main.variable.Variable(default_value=<enthought.traits.trait_handlers.NoDefaultSpecified object at 0x032E5F90>, **metadata)

Bases: enthought.traits.trait_handlers.TraitType

An OpenMDAO specific trait type that serves as a common base class for framework visible inputs and outputs.

workflow.py

Workflow class definition

class openmdao.main.workflow.Workflow(parent=None, scope=None, members=None)

Bases: object

A Workflow consists of a collection of Components which are to be executed in some order.

add(comp)

Add a new component to the workflow by name.

calc_derivatives(first=False, second=False)

Calculate derivatives and save baseline states for all components in this workflow.

check_derivatives(order, driver_inputs, driver_outputs)

Run check_derivatives on all components in workflow.

config_changed()

Notifies the Workflow that workflow configuration (dependencies, etc) has changed.

get_components()

Returns a list of all component objects in the workflow. No ordering is assumed.

get_names()

Return a list of component names in this workflow.

remove(comp)

Remove a component from this Workflow by name.

run(ffd_order=0, case_id='')

Run the Components in this Workflow.

step(ffd_order=0, case_id='')

Run a single component in this Workflow.

stop()

Stop all Components in this Workflow. We assume it’s OK to to call stop() on something that isn’t running.

scope

The scoping Component that is used to resolve the Component names in this Workflow.