driver.py

Define a base class for all Drivers in OpenMDAO.

class openmdao.core.driver.Driver(**kwargs)

Bases: object

Top-level container for the systems and drivers.

Parameters:

**kwargsdict of keyword arguments

Keyword arguments that will be mapped into the Driver options.

Attributes:

iter_countint

Keep track of iterations for case recording.

options<OptionsDictionary>

Dictionary with general pyoptsparse options.

recording_options<OptionsDictionary>

Dictionary with driver recording options.

citestr

Listing of relevant citations that should be referenced when publishing work that uses this class.

_problemweakref to <Problem>

Pointer to the containing problem.

supports<OptionsDictionary>

Provides a consistent way for drivers to declare what features they support.

_designvarsdict

Contains all design variable info.

_designvars_discretelist

List of design variables that are discrete.

_dist_driver_varsdict

Dict of constraints that are distributed outputs. Key is a ‘user’ variable name, typically promoted name or an alias. Values are (local indices, local sizes).

_consdict

Contains all constraint info.

_objsdict

Contains all objective info.

_responsesdict

Contains all response info.

_lin_dvsdict

Contains design variables relevant to linear constraints.

_nl_dvsdict

Contains design variables relevant to nonlinear constraints.

_remote_dvsdict

Dict of design variables that are remote on at least one proc. Values are (owning rank, size).

_remote_consdict

Dict of constraints that are remote on at least one proc. Values are (owning rank, size).

_remote_objsdict

Dict of objectives that are remote on at least one proc. Values are (owning rank, size).

_rec_mgr<RecordingManager>

Object that manages all recorders added to this driver.

_coloring_infodict

Metadata pertaining to total coloring.

_total_jac_formatstr

Specifies the format of the total jacobian. Allowed values are ‘flat_dict’, ‘dict’, and ‘array’.

_con_subjacsdict

Dict of sparse subjacobians for use with certain optimizers, e.g. pyOptSparseDriver. Keyed by sources and aliases.

_total_jac_TotalJacInfo or None

Cached total jacobian handling object.

_total_jac_linear_TotalJacInfo or None

Cached linear total jacobian handling object.

resultDriverResult

DriverResult object containing information for use in the optimization report.

_has_scalingbool

If True, scaling has been set for this driver.

__init__(**kwargs)

Initialize the driver.

add_recorder(recorder)

Add a recorder to the driver.

Parameters:

recorderCaseRecorder

A recorder instance.

check_relevance()

Check if there are constraints that don’t depend on any design vars.

This usually indicates something is wrong with the problem formulation.

cleanup()

Clean up resources prior to exit.

declare_coloring(num_full_jacs=3, tol=1e-25, orders=None, perturb_size=1e-09, min_improve_pct=5.0, show_summary=True, show_sparsity=False, use_scaling=False)

Set options for total deriv coloring.

Parameters:

num_full_jacsint

Number of times to repeat partial jacobian computation when computing sparsity.

tolfloat

Tolerance used to determine if an array entry is nonzero during sparsity determination.

ordersint

Number of orders above and below the tolerance to check during the tolerance sweep.

perturb_sizefloat

Size of input/output perturbation during generation of sparsity.

min_improve_pctfloat

If coloring does not improve (decrease) the number of solves more than the given percentage, coloring will not be used.

show_summarybool

If True, display summary information after generating coloring.

show_sparsitybool

If True, display sparsity with coloring info after generating coloring.

use_scalingbool

If True, use driver scaling when generating the sparsity.

get_constraint_values(ctype='all', lintype='all', driver_scaling=True)

Return constraint values.

Parameters:

ctypestr

Default is ‘all’. Optionally return just the inequality constraints with ‘ineq’ or the equality constraints with ‘eq’.

lintypestr

Default is ‘all’. Optionally return just the linear constraints with ‘linear’ or the nonlinear constraints with ‘nonlinear’.

driver_scalingbool

When True, return values that are scaled according to either the adder and scaler or the ref and ref0 values that were specified when add_design_var, add_objective, and add_constraint were called on the model. Default is True.

Returns:

dict

Dictionary containing values of each constraint.

get_design_var_values(get_remote=True, driver_scaling=True)

Return the design variable values.

Parameters:

get_remotebool or None

If True, retrieve the value even if it is on a remote process. Note that if the variable is remote on ANY process, this function must be called on EVERY process in the Problem’s MPI communicator. If False, only retrieve the value if it is on the current process, or only the part of the value that’s on the current process for a distributed variable.

driver_scalingbool

When True, return values that are scaled according to either the adder and scaler or the ref and ref0 values that were specified when add_design_var, add_objective, and add_constraint were called on the model. Default is True.

Returns:

dict

Dictionary containing values of each design variable.

get_driver_derivative_calls()

Return number of derivative evaluations made during a driver run.

Returns:

int

Number of derivative evaluations made during a driver run.

get_driver_objective_calls()

Return number of objective evaluations made during a driver run.

Returns:

int

Number of objective evaluations made during a driver run.

get_exit_status()

Return exit status of driver run.

Returns:

str

String indicating result of driver run.

get_objective_values(driver_scaling=True)

Return objective values.

Parameters:

driver_scalingbool

When True, return values that are scaled according to either the adder and scaler or the ref and ref0 values that were specified when add_design_var, add_objective, and add_constraint were called on the model. Default is True.

Returns:

dict

Dictionary containing values of each objective.

get_reports_dir()

Get the path to the directory where the report files should go.

If it doesn’t exist, it will be created.

Returns:

str

The path to the directory where reports should be written.

property msginfo

Return info to prepend to messages.

Returns:

str

Info to prepend to messages.

record_derivatives()

Record the current total jacobian.

record_iteration()

Record an iteration of the current Driver.

run()

Execute this driver.

The base Driver just runs the model. All other drivers overload this method.

Returns:

bool

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

scaling_report(outfile='driver_scaling_report.html', title=None, show_browser=True, jac=True)

Generate a self-contained html file containing a detailed connection viewer.

Optionally pops up a web browser to view the file.

Parameters:

outfilestr, optional

The name of the output html file. Defaults to ‘driver_scaling_report.html’.

titlestr, optional

Sets the title of the web page.

show_browserbool, optional

If True, pop up a browser to view the generated html file. Defaults to True.

jacbool

If True, show jacobian information.

Returns:

dict

Data used to create html file.

set_design_var(name, value, set_remote=True)

Set the value of a design variable.

‘name’ can be a promoted output name or an alias.

Parameters:

namestr

Global pathname of the design variable.

valuefloat or ndarray

Value for the design variable.

set_remotebool

If True, set the global value of the variable (value must be of the global size). If False, set the local value of the variable (value must be of the local size).

use_fixed_coloring(coloring=<object object>)

Tell the driver to use a precomputed coloring.

Parameters:

coloringstr or Coloring

A coloring filename or a Coloring object. If no arg is passed, filename will be determined automatically.

class openmdao.core.driver.DriverResult(driver)

Bases: object

A container that stores information pertaining to the result of a driver execution.

Parameters:

driverDriver

The Driver associated with this DriverResult.

Attributes:

_driverweakref to Driver

A weakref to the Driver associated with this DriverResult.

runtimefloat

The time required to execute the driver, in seconds.

iter_countint

The number of iterations used by the optimizer.

model_evalsint

The number of times the objective function was evaluated (model solve_nonlinear calls).

model_timefloat

The time spent in model solve_nonlinear evaluations.

deriv_evalsint

The number of times the total jacobian was computed.

deriv_timefloat

The time spent computing the total jacobian.

exit_statusstr

A string that may provide more detail about the results of the driver run.

successbool

A boolean that dictates whether or not the driver was successful.

__getitem__(s)

Provide key access to the attributes of DriverResult.

This is included for backward compatibility with some tests which require dictionary-like access.

Parameters:

sstr

The name of the attribute.

Returns:

object

The value of the attribute

__init__(driver)

Initialize the DriverResult object.

reset()

Set the driver result attributes back to their default value.

static track_stats(kind)

Decorate methods to track the model solve_nonlinear or deriv time and count.

This decorator should be applied to the _objfunc or _gradfunc (or equivalent) methods of drivers. It will either accumulate the elapsed time in driver.result.model_time or driver.result.deriv_time, based on the value of kind.

Parameters:

kindstr

One of ‘model’ or ‘deriv’, specifying which statistics should be accumulated.

Returns:

Callable

A wrapped version of the decorated function such that it accumulates the time and call count for either the objective or derivatives.

class openmdao.core.driver.RecordingDebugging(name, iter_count, recording_requester)

Bases: Recording

A class that acts as a context manager.

Handles doing the case recording and also the Driver debugging printing.

Parameters:

namestr

Name of object getting recorded.

iter_countint

Current counter of iterations completed.

recording_requesterobject

Object to which this recorder is attached.

__init__(name, iter_count, recording_requester)

Initialize Recording.

class openmdao.core.driver.SaveOptResult(driver)

Bases: object

A context manager that saves details about a driver run.

Parameters:

driverDriver

The driver.

Attributes:

_driverDriver

The driver for which we are saving results.

_start_timefloat

The start time used to compute the run time.

__init__(driver)

Initialize attributes.

openmdao.core.driver.filter_by_meta(metadict_items, key, chk_none=False, exclude=False)

Filter metadata items based on their value.

Parameters:

metadict_itemsiter of (name, meta)

Iterable of (name, meta) tuples.

keystr

Metadata key.

chk_nonebool

If True, compare items to None. If False, check if items are truthy.

excludebool

If True, exclude matching items rather than yielding them.

Yields:

tuple

Tuple of the form (name, meta) for each item in metadict_items that satisfies the condition.

openmdao.core.driver.record_iteration(requester, prob, case_name)

Record an iteration of the current Problem or Driver.

Parameters:

requesterProblem or Driver

The recording requester.

probProblem

The Problem.

case_namestr

The name of this case.