# coloring.py#

Routines to compute coloring for use with simultaneous derivatives.

classopenmdao.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.

- Parameters:

sparsityndarrayFull jacobian sparsity matrix (dense bool form).

row_varslist of str or NoneNames of variables corresponding to rows.

row_var_sizesndarray or NoneSizes of row variables.

col_varslist of str or NoneNames of variables corresponding to columns.

col_var_sizesndarray or NoneSizes of column variables.

- Attributes:

_shapetuple of int (nrows, ncols)Tuple describing the shape of the sparsity matrix.

_nzrowsndarray of intRow indices of nonzero entries in the full jac sparsity matrix.

_nzcolsndarray of intColumn indices of nonzero entries in the full jac sparsity matrix.

_pct_nonzerofloatIf known, percentage of nonzero vs total array entries.

_fwdtuple (col_lists, row_maps) or NoneContains lists of grouped columns and nonzero rows for each column for forward coloring.

_revtuple (col_lists, row_maps) or NoneContains lists of grouped columns and nonzero rows for each column for reverse coloring.

_col_varslist of str or NoneNames of variables corresponding to columns.

_col_var_sizesndarray or NoneSizes of column variables.

_row_varslist of str or NoneNames of variables corresponding to rows.

_row_var_sizesndarray or NoneSizes of row variables.

_metadictDictionary of metadata used to create the coloring.

_names_arrayndarray or None:Names of total jacobian rows or columns.

_local_arrayndarray or None:Indices of total jacobian rows or columns.

_abs2prom{‘input’: dict, ‘output’: dict}Dictionary mapping absolute names to promoted names.

- __init__(
sparsity,row_vars=None,row_var_sizes=None,col_vars=None,col_var_sizes=None)[source]Initialize data structures.

- color_iter(
direction)[source]Given a direction, yield an iterator over column (or row) groups.

- Parameters:

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

- Yields:

- list of int
Lists of column indices (in fwd mode) or row indices (in rev mode).

- color_nonzero_iter(
direction)[source]Given a direction, yield an iterator over (columns, nz_rows) or (rows, nz_columns).

- Parameters:

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

- Yields:

- (column or row groups, nonzero row or column lists)
Yields a list of columns/rows and their associated nonzero rows/columns for each color.

- colored_jac_iter(
compressed_j,direction,trans=None)[source]Yield nonzero parts of columns (fwd) or rows (rev) of a colored jacobian.

- Parameters:

compressed_jndarrayThe compressed jacobian.

directionstrDerivative computation direction (‘fwd’ or ‘rev’).

transndarrayIndex array to translate from compressed jac in function context to openmdao jac.

- Yields:

- ndarray
Nonzero part of current jacobian column or row.

- ndarray
Indices into full jacobian column or row where nonzero values should be placed.

- int
Index into the full jacobian of the current column or row.

- display(
show=True,fname='coloring.png')[source]Display a plot of the sparsity pattern, showing grouping by color.

- Parameters:

showboolIf True, show the plot. Otherwise, just save the plot in a file. Default is True.

fnamestrPath to the location where the plot file should be saved.

- display_bokeh(
output_file='total_coloring.html',show=False,max_colors=200,use_prom_names=True)[source]Display a plot of the sparsity pattern, showing grouping by color.

- Parameters:

sourcestr or Coloring DriverThe source for the coloring information, which can either be a string of the filepath to the coloring data file, an instance of Coloring, or the Driver containing the coloring information.

output_filestr or NoneThe name of the output html file in which the display is written. If None, the resulting plots will not be saved.

showboolIf True, a browswer will be opened to display the generated file.

max_colorsintBokeh supports at most 256 colors in a colormap. This function reduces that number to some default length, otherwise both forward and reverse displays may share shades very near white and be difficult to distinguish. Once the number of forward or reverse solves exceeds this threshold, the color pattern restarts.

use_prom_namesboolIf True, display promoted names rather than absolute path names for variables.

- display_txt(
out_stream=DEFAULT_OUT_STREAM,html=False,summary=True,use_prom_names=True)[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.

- Parameters:

out_streamfile-like or _DEFAULT_OUT_STREAMThe destination stream to which the text representation of coloring is to be written.

htmlboolIf True, the output will be formatted as HTML. If False, the resulting output will be plain text.

summaryboolIf True, include the coloring summary.

use_prom_namesboolIf True, display promoted names rather than absolute path names for variables.

- expand_jac(
compressed_j,direction)[source]Expand the given compressed jacobian into a full jacobian.

- Parameters:

compressed_jndarrayThe compressed jacobian.

directionstrDerivative computation direction (‘fwd’ or ‘rev’).

- Returns:

- ndarray
The full jacobian.

- 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(
dtype=<class 'bool'>)[source]Return a dense array representing the full sparsity.

- Parameters:

dtypeobjectData type of returned numpy array.

- 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:

directionstrIndicator 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:

varnamestrName 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).

staticload(fname)[source]Read the coloring object from the given pickle file.

- Parameters:

fnamestrName 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:

fnamestrFile to save to.

- summary(
out_stream=DEFAULT_OUT_STREAM)[source]Print a summary of this coloring.

- Parameters:

out_streamfile-like or _DEFAULT_OUT_STREAMThe destination stream to which the text representation of coloring is to be written.

- tangent_iter(
direction,arr=None,trans=None)[source]Given a direction, return input (fwd) or output (rev) tangent arrays.

Each array will contain multiple columns/rows of the identity matrix that share the same color.

- Parameters:

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

arrndarray or NoneStorage for the current array value.

transndarray or NoneIndex translation array.

- Yields:

- ndarray
tangent array for inputs (fwd) or outputs (rev)

- tangent_matrix(
direction,trans=None)[source]Return a tangent or cotangent matrix for use with jax.

- Parameters:

directionstrDerivative computation direction (‘fwd’ or ‘rev’).

transndarray or NoneIndex translation array.

- Returns:

- ndarray
The tangent or cotangent matrix.

- total_solves(
fwd=True,rev=True)[source]Return total number of solves required based on the given coloring info.

- Parameters:

fwdboolIf True, add fwd colors to total.

revboolIf 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:

Jcoo_matrixJacobian 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)[source]Compute simultaneous derivative colorings for the total jacobian of the given problem.

- Parameters:

problemProblemThe Problem being analyzed.

modestr or NoneThe direction for computing derivatives. If None, use problem._mode.

ofiter of str or NoneNames of the ‘response’ variables.

wrtiter of str or NoneNames of the ‘design’ variables.

num_full_jacsintNumber of times to repeat total jacobian computation.

tolfloatTolerance used to determine if an array entry is nonzero.

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

setupboolIf True, run setup before calling compute_totals.

run_modelboolIf True, run run_model before calling compute_totals.

fnamefilename or NoneFile where output coloring info will be written. If None, no info will be written.

- Returns:

- Coloring
See docstring for Coloring class.

- openmdao.utils.coloring.display_coloring(
source,output_file='total_coloring.html',as_text=False,show=True,max_colors=200)[source]Display the coloring information from source to html format.

- Parameters:

sourcestr or Coloring or DriverThe source of the coloring information. If given as a string, source should be a valid coloring file path. If given as a Driver, display_colroing will attempt to obtain coloring information from the Driver.

output_filestr or Path or NoneThe output file to which the coloring display should be sent. If as_text is True and output_file ends with .html, then the coloring will be sent to that file as html, otherwise it will the html file will be saved in a temporary file.

as_textboolIf True, render the coloring information using plain text.

showboolIf True, open the resulting html file in the system browser.

max_colorsintBokeh colormaps support at most 256 colors. Near the upper end of this interval, the colors are nearly white and may be difficult to distinguish. This setting sets the upper limit for the color index before the pattern repeats.

- 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_modelboolIf True, call run_model before computing coloring.

fnamestr or NoneName of file where coloring will be saved.

- Returns:

- Coloring
The computed coloring.