# 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 'numpy.uint8'>)[source]Return a dense array representing the full sparsity.

- Parameters:

dtypeobjectData type of returned numpy array.

- Returns:

- ndarray
Dense sparsity matrix.

- get_renamed_copy(
row_translate,col_translate)[source]Return a new Coloring object with the variables renamed.

- Parameters:

row_translatedictDictionary mapping old row names to new row names.

col_translatedictDictionary mapping old column names to new column names.

- Returns:

- Coloring
New Coloring object with the variables renamed.

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

fnamestr or pathlib.PathFile to save to.

propertysparsityReturn the sparsity matrix as a COO sparse matrix.

- Returns:

- coo_matrix
The sparsity matrix.

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

classopenmdao.utils.coloring.ColoringMeta(num_full_jacs=3,tol=1e-25,orders=None,min_improve_pct=5.0,show_summary=True,show_sparsity=False,dynamic=False,static=None,perturb_size=1e-09,use_scaling=False,msginfo='')[source]Bases:

`object`

Container for all metadata relevant to a coloring.

- Parameters:

num_full_jacsintNumber of full jacobians to generate while computing sparsity.

tolfloatUse this tolerance to determine what’s a zero when determining sparsity.

ordersint or NoneNumber of orders += around ‘tol’ for the tolerance sweep when determining sparsity. If None, no tolerance sweep will be performed and whatever ‘tol’ is specified will be used.

min_improve_pctfloatDon’t use coloring unless at least min_improve_pct percentage decrease in number of solves.

show_summaryboolIf True, print a short summary of the coloring. Defaults to True.

show_sparsityboolIf True, show a plot of the sparsity. Defaults to False.

dynamicboolTrue if dynamic coloring is being used.

staticColoring, str, or NoneIf a Coloring object, just use that. If a filename, load the coloring from that file. If None, do not attempt to use a static coloring.

perturb_sizefloatSize of input/output perturbation during generation of sparsity.

use_scalingboolIf True, use driver scaling when computing sparsity.

msginfostrPrefix for warning/error messages.

- Attributes:

num_full_jacsintNumber of full jacobians to generate while computing sparsity.

tolfloatUse this tolerance to determine what’s a zero when determining sparsity.

ordersint or NoneNumber of orders += around ‘tol’ for the tolerance sweep when determining sparsity. If None, no tolerance sweep will be performed and whatever ‘tol’ is specified will be used.

min_improve_pctfloatDon’t use coloring unless at least min_improve_pct percentage decrease in number of solves.

show_summaryboolIf True, print a short summary of the coloring. Defaults to True.

show_sparsityboolIf True, show a plot of the sparsity. Defaults to False.

dynamicboolTrue if dynamic coloring is being used.

staticColoring, str, or NoneIf a Coloring object, just use that. If a filename, load the coloring from that file. If None, do not attempt to use a static coloring.

perturb_sizefloatSize of input/output perturbation during generation of sparsity.

use_scalingboolIf True, use driver scaling when computing sparsity.

msginfostrPrefix for warning/error messages.

_coloringColoring or NoneThe coloring object.

_failedboolIf True, coloring was already generated but failed.

_approxboolIf True, this is an approx coloring.

- __getitem__(
name)[source]Get the value of the named metadata.

- Parameters:

namestrName of the metadata.

- Returns:

- object
Value of the named metadata.

- __init__(
num_full_jacs=3,tol=1e-25,orders=None,min_improve_pct=5.0,show_summary=True,show_sparsity=False,dynamic=False,static=None,perturb_size=1e-09,use_scaling=False,msginfo='')[source]Initialize data structures.

- __iter__()[source]
Iterate over the metadata.

- Yields:

- (str, object)
Tuple containing the name and value of each metadata item.

- __setitem__(
name,value)[source]Set the value of the named metadata.

- Parameters:

namestrName of the metadata.

valueobjectValue of the metadata.

propertycoloringReturn the coloring.

- Returns:

- Coloring or None
The coloring.

- copy()[source]
Return a new object with metadata copied from this object.

- Returns:

- ColoringMeta
Copy of the metadata.

- display()[source]
Display information about the coloring.

- do_compute_coloring()[source]
Return True if coloring should be computed.

- Returns:

- bool
True if coloring should be computed.

- get(
name,default=None)[source]Get the value of the named metadata.

- Parameters:

namestrName of the metadata.

defaultobject or NoneThe value to return if the named metadata is not found.

- Returns:

- object
Value of the named metadata.

- reset_coloring()[source]
Reset the coloring to None.

- set_coloring(
coloring,msginfo='')[source]Set the coloring.

- Parameters:

coloringColoring or NoneThe coloring.

msginfostrPrefix for warning/error messages.

- update(
dct)[source]Update the metadata.

- Parameters:

dctdictDictionary of metadata.

exceptionopenmdao.utils.coloring.InvalidColoringError[source]Bases:

`Exception`

A custom error class that is raised in the event of an invalid coloring.

- __init__(
*args,**kwargs)

- add_note()
Exception.add_note(note) – add a note to the exception

- args

- with_traceback()
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

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

classopenmdao.utils.coloring.Partial_ColoringMeta(wrt_patterns=('*',),method='fd',form=None,step=None,per_instance=True,perturb_size=1e-09,num_full_jacs=3,tol=1e-25,orders=None,min_improve_pct=5.0,show_summary=True,show_sparsity=False,dynamic=False,static=None,msginfo='')[source]Bases:

`ColoringMeta`

Container for all metadata relevant to a partial coloring.

- Parameters:

wrt_patternslist/tuple of str or strPatterns used to match wrt variables.

methodstrFinite differencing method (‘fd’ or ‘cs’).

formstrForm of the derivatives (‘forward’, ‘backward’, or ‘central’). Only used if method is ‘fd’.

stepfloatStep size for ‘fd’, or ‘cs’.

per_instanceboolAssume each instance can have a different coloring, so coloring will not be saved as a class coloring.

perturb_sizefloatSize of input/output perturbation during generation of sparsity.

num_full_jacsintNumber of full jacobians to generate while computing sparsity.

tolfloatUse this tolerance to determine what’s a zero when determining sparsity.

ordersint or NoneNumber of orders += around ‘tol’ for the tolerance sweep when determining sparsity. If None, no tolerance sweep will be performed and whatever ‘tol’ is specified will be used.

min_improve_pctfloatDon’t use coloring unless at least min_improve_pct percentage decrease in number of solves.

show_summaryboolIf True, print a short summary of the coloring. Defaults to True.

show_sparsityboolIf True, show a plot of the sparsity. Defaults to False.

dynamicboolTrue if dynamic coloring is being used.

staticColoring, str, or NoneIf a Coloring object, just use that. If a filename, load the coloring from that file. If None, do not attempt to use a static coloring.

msginfostrPrefix for warning/error messages.

- Attributes:

`wrt_patterns`

list/tuple of str or strReturn the wrt patterns.

methodstrFinite differencing method (‘fd’ or ‘cs’).

formstrForm of the derivatives (‘forward’, ‘backward’, or ‘central’). Only used if method is ‘fd’.

stepfloatStep size for ‘fd’, or ‘cs’.

per_instanceboolAssume each instance can have a different coloring, so coloring will not be saved as a class coloring.

fnamestr or NoneFilename where coloring is stored.

wrt_matchesset of str or NoneWhere matched wrt names are stored.

- __getitem__(
name)Get the value of the named metadata.

- Parameters:

namestrName of the metadata.

- Returns:

- object
Value of the named metadata.

- __init__(
wrt_patterns=('*',),method='fd',form=None,step=None,per_instance=True,perturb_size=1e-09,num_full_jacs=3,tol=1e-25,orders=None,min_improve_pct=5.0,show_summary=True,show_sparsity=False,dynamic=False,static=None,msginfo='')[source]Initialize data structures.

- __iter__()
Iterate over the metadata.

- Yields:

- (str, object)
Tuple containing the name and value of each metadata item.

- __setitem__(
name,value)Set the value of the named metadata.

- Parameters:

namestrName of the metadata.

valueobjectValue of the metadata.

propertycoloringReturn the coloring.

- Returns:

- Coloring or None
The coloring.

- copy()
Return a new object with metadata copied from this object.

- Returns:

- ColoringMeta
Copy of the metadata.

- display()
Display information about the coloring.

- do_compute_coloring()
Return True if coloring should be computed.

- Returns:

- bool
True if coloring should be computed.

- get(
name,default=None)Get the value of the named metadata.

- Parameters:

namestrName of the metadata.

defaultobject or NoneThe value to return if the named metadata is not found.

- Returns:

- object
Value of the named metadata.

- reset_coloring()[source]
Reset coloring and fname metadata.

- set_coloring(
coloring,msginfo='')Set the coloring.

- Parameters:

coloringColoring or NoneThe coloring.

msginfostrPrefix for warning/error messages.

- update(
dct)[source]Update the metadata.

- Parameters:

dctdictDictionary of metadata.

propertywrt_patternsReturn the wrt patterns.

- Returns:

- list of tuple or None
Patterns used to match wrt variables.

- 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,driver=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.

driver<Driver>, None, or FalseThe driver associated with the coloring. If None, use problem.driver. If False, no driver will be used.

- 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,of=None,wrt=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.

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

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

- Returns:

- Coloring or None
The computed coloring.