# coloring.py¶

Routines to compute coloring for use with simultaneous derivatives.

class openmdao.utils.coloring.Coloring(sparsity, row_vars=None, row_var_sizes=None, col_vars=None, col_var_sizes=None)[source]

Bases: object

Container for all information relevant to a coloring.

__init__(sparsity, row_vars=None, row_var_sizes=None, col_vars=None, col_var_sizes=None)[source]

Initialize data structures.

Parameters
sparsityndarray

Full jacobian sparsity matrix (dense bool form).

row_varslist of str or None

Names of variables corresponding to rows.

row_var_sizesndarray or None

Sizes of row variables.

col_varslist of str or None

Names of variables corresponding to columns.

col_var_sizesndarray or None

Sizes of column variables.

color_iter(direction)[source]

Given a direction, yield an iterator over column (or row) groups.

Parameters
directionstr

Derivative direction (‘fwd’ or ‘rev’).

color_nonzero_iter(direction)[source]

Given a direction, yield an iterator over (columns, nz_rows) or (rows, nz_columns).

Parameters
directionstr

Indicates which coloring subdict (‘fwd’ or ‘rev’) to use.

display()[source]

Display a plot of the sparsity pattern, showing grouping by color.

display_txt()[source]

Print the structure of a boolean array with coloring info for each nonzero value.

Forward mode colored nonzeros are denoted by ‘f’, reverse mode nonzeros by ‘r’, overlapping nonzeros by ‘O’ and uncolored nonzeros by ‘x’. Zeros are denoted by ‘.’. Note that x’s and O’s should never appear unless there is a bug in the coloring algorithm.

If names and sizes of row and column vars are known, print the name of the row var alongside each row and print the names of the column vars, aligned with each column, at the bottom.

get_declare_partials_calls()[source]

Return a string containing declare_partials() calls based on the subjac sparsity.

Returns
str

A string containing a declare_partials() call for each nonzero subjac. This string may be cut and pasted into a component’s setup() method.

get_dense_sparsity()[source]

Return a dense bool array representing the full sparsity.

Returns
ndarray

Dense sparsity matrix.

get_row_col_map(direction)[source]

Return mapping of nonzero rows to each column (fwd) or nonzeros columns to each row (rev).

Parameters
directionstr

Indicator of forward mode (‘fwd’) or reverse mode (‘rev’).

Returns
list of lists of int

List where each entry contains list of nonzero rows/cols for the index corresponding to each column/row.

get_row_var_coloring(varname)[source]

Return the number of fwd and rev solves needed for a particular row variable.

Parameters
varnamestr

Name of the row variable.

Returns
int

Number of forward solves needed for the given variable.

int

Number of reverse solves needed for the given variable.

get_subjac_sparsity()[source]

Compute the sparsity structure of each subjacobian based on the full jac sparsity.

If row/col variables and sizes are not known, returns None.

Returns
dict or None

Mapping of (of, wrt) keys to their corresponding (nzrows, nzcols, shape).

static load(fname)[source]

Read the coloring object from the given pickle file.

Parameters
fnamestr

Name of file to read from.

Returns
Coloring

See docstring for Coloring class.

modes()[source]

Return a tuple containing the modes included in this coloring.

Returns
tuple

Tuple containing some subset of (‘fwd’, ‘rev’).

save(fname)[source]

Write the coloring object to the given stream, creating intermediate dirs if needed.

Parameters
fnamestr

File to save to.

summary()[source]

Print a summary of this coloring.

Parameters
streamfile-like

Where the output will go.

total_solves(do_fwd=True, do_rev=True)[source]

Return total number of solves required based on the given coloring info.

Parameters
do_fwdbool

If True, add fwd colors to total.

do_revbool

If True, add rev colors to total.

Returns
int

Total number of solves required to compute the jacobian.

openmdao.utils.coloring.MNCO_bidir(J)[source]

Compute bidirectional coloring using Minimum Nonzero Count Order (MNCO).

Based on the algorithm found in Coleman, T.F., Verma, A. (1998) The efficient Computation of Sparse Jacobian Matrices Using Automatic Differentiation. SIAM Journal on Scientific Computing, 19(4), 1210-1233.

Parameters
Jndarray

Dense Jacobian sparsity matrix (boolean)

Returns
Coloring

See docstring for Coloring class.

openmdao.utils.coloring.compute_total_coloring(problem, mode=None, of=None, wrt=None, num_full_jacs=3, tol=1e-25, orders=None, setup=False, run_model=False, fname=None, use_abs_names=False)[source]

Compute simultaneous derivative colorings for the total jacobian of the given problem.

Parameters
problemProblem

The Problem being analyzed.

modestr or None

The direction for computing derivatives. If None, use problem._mode.

ofiter of str or None

Names of the ‘response’ variables.

wrtiter of str or None

Names of the ‘design’ variables.

num_full_jacsint

Number of times to repeat total jacobian computation.

tolfloat

Tolerance used to determine if an array entry is nonzero.

ordersint

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

setupbool

If True, run setup before calling compute_totals.

run_modelbool

If True, run run_model before calling compute_totals.

fnamefilename or None

File where output coloring info will be written. If None, no info will be written.

use_abs_namesbool

If True, use absolute naming for of and wrt variables.

Returns
Coloring

See docstring for Coloring class.

openmdao.utils.coloring.dynamic_total_coloring(driver, run_model=True, fname=None)[source]

Compute simultaneous deriv coloring during runtime.

Parameters
driver<Driver>

The driver performing the optimization.

run_modelbool

If True, call run_model before computing coloring.

fnamestr or None

Name of file where coloring will be saved.

Returns
Coloring

The computed coloring.

openmdao.utils.coloring.get_tot_jac_sparsity(problem, mode='fwd', num_full_jacs=3, tol=1e-25, setup=False, run_model=False)[source]

Compute derivative sparsity for the given problem.

Parameters
problemProblem

The Problem being analyzed.

modestr

Derivative direction.

num_full_jacsint

Number of times to repeat total jacobian computation.

tolfloat

Tolerance used to determine if an array entry is nonzero.

setupbool

If True, run setup before calling compute_totals.

run_modelbool

If True, run run_model before calling compute_totals.

Returns
dict

A nested dict specifying subjac sparsity for each total deriv, e.g., sparsity[resp][dv].

ndarray

Boolean sparsity matrix.