Command Line Tools¶
OpenMDAO has a number of debugging/viewing command line tools that are available via the openmdao command. There are two types of commands available, those that perform some sort of viewing or configuration checking on the Problem after its setup is complete, and those that are used to collect information about the entire run of the Problem, like profilers and tracers.
Note
The openmdao sub-commands, as well as any other console scripts associated with OpenMDAO, will only be available if you have installed OpenMDAO using pip. See Getting Started
Note
When using a command line tool on a script that takes its own command line arguments, those
arguments must be placed after a -- on the command line. Anything to the right of the
-- will be ignored by the openmdao command line parser and passed on to the user script.
For example: openmdao n2 -o foo.html myscript.py -- -x --myarg=bar would pass
-x and --myarg=bar as args to myscript.py.
All available openmdao sub-commands can be shown using the following command:
openmdao -h
usage: openmdao [-h] ...
OpenMDAO Command Line Tools
optional arguments:
-h, --help show this help message and exit
Tools:
call_tree Display the call tree for the specified class method and
all 'self' class methods it calls.
check Perform a number of configuration checks on the problem.
cite Print citations referenced by the problem
iprof Profile calls to particular object instances.
iprof_totals Generate total timings of calls to particular object
instances.
mem Profile memory used by OpenMDAO related functions.
mempost Post-process memory profile output.
n2 Display an interactive N2 diagram of the problem.
partial_coloring
Compute coloring(s) for specified partial jacobians.
scaffold Generate a simple scaffold for a component.
summary Print a short top-level summary of the problem.
total_coloring Compute a coloring for the total jacobian.
trace Dump trace output.
tree Print the system tree.
view_coloring View a colored jacobian.
view_connections
View connections showing values and source/target units.
view_mm View a metamodel.
view_model Display an interactive N2 diagram of the problem.
(Deprecated, please use n2 instead.)
xdsm Generate an XDSM diagram of a model.
Use -h after any sub-command for sub-command help. If using a tool on a script
that takes its own command line arguments, place those arguments after a "--".
For example: openmdao n2 -o foo.html myscript.py -- -x --myarg=bar
To get further info on any sub-command, follow the command with a -h. For example:
openmdao n2 -h
usage: openmdao n2 [-h] [-o OUTFILE] [--no_browser] [--embed] [--title TITLE]
[--use_declare_partial_info]
file
positional arguments:
file Python script or recording containing the model.
optional arguments:
-h, --help show this help message and exit
-o OUTFILE html output file.
--no_browser don't display in a browser.
--embed create embeddable version.
--title TITLE diagram title.
--use_declare_partial_info
use declare partial info for internal connectivity.
Note
Several of the example commands below make use of the files circuit.py and
circle_opt.py. These files are located in the openmdao/test_suite/scripts directory.
Viewing and Checking Commands¶
Usually these commands will exit after executing, rather than continuing to the end of the user’s run script. This makes it convenient to view or check the configuration of a model in any run script without having to wait around for the entire script to run.
openmdao check¶
The openmdao check command will perform a number of checks on a model and display
errors, warnings, or informational messages describing what it finds. Some of the available
checks are unconnected_inputs, which lists any input variables that are not connected, and
out_of_order, which displays any systems that are being executed out-of-order.
You can supply individual checks on the command line using -c args. For example:
openmdao check -c cycles circuit.py
INFO: checking cycles INFO: The following groups contain cycles: Group 'circuit' has the following cycles: [['n1', 'n2', 'R1', 'R2', 'D1']]
Otherwise, a set of default checks will be done. To see lists of the available and default checks, run the following command:
openmdao check -h
usage: openmdao check [-h] [-o OUTFILE] [-p PROBLEM] [-c CHECKS] file
positional arguments:
file Python file containing the model
optional arguments:
-h, --help show this help message and exit
-o OUTFILE output file
-p PROBLEM, --problem PROBLEM
Problem name
-c CHECKS Only perform specific check(s). Default checks are:
['comp_has_no_outputs', 'dup_inputs',
'missing_recorders', 'out_of_order', 'solvers',
'system']. Other available checks are: ['cycles',
'promotions', 'unconnected_inputs']
openmdao n2¶
The openmdao n2 command will generate an \(N^2\) diagram of the model that is
viewable in a browser, for example:
openmdao n2 circuit.py
will generate an \(N^2\) diagram like the one below.
openmdao view_connections¶
The openmdao view_connections command generates a table of connection information for all input and
output variables in the model. Its primary purpose is to help debug a model by making the following
things easier:
Identifying unconnected inputs
Highlighting unit conversions or missing units
Identifying missing or unwanted implicit connections
The table can be sorted by any column by clicking on the column header, and a column can be filtered by typing text into the ‘filter column’ field found at the top of each column. Also, any column can be shown or hidden using the toggle buttons at the bottom of the table. When input and output units differ, they are highlighted in red. In the promoted input and output columns, variables that are promoted at some level in the model are shown in blue, while variables that are never promoted are shown in black.
Below is an example of a connection viewer for a pycycle propulsor model obtained using the command:
openmdao view_connections -v propulsor.py
An example of a connection viewer.¶
By default the promoted names columns of both inputs and outputs are shown, but in the example above, the absolute input names are shown and the promoted input names are hidden.
Unconnected inputs can easily be identified by typing ‘[NO CONNECTION]’ or ‘[‘, into the filter field of either the absolute or promoted output column. Unconnected outputs can be shown similarly by typing ‘[NO CONNECTION]’ or ‘[‘ into the filter field of either the absolute or promoted input column.
When showing promoted output and promoted input columns, if the promoted output name equals the promoted input name, that means the connection is an implicit connection. Otherwise the connection is explicit, meaning somewhere in the model there is an explicit call to connect that producted the connection.
In OpenMDAO, multiple inputs can be promoted to the same name, and by sorting the promoted inputs column, all such inputs will be grouped together. This can make it much easier to spot either missing or unwanted implicit connections.
openmdao tree¶
The openmdao tree command prints an indented list of all systems in the model tree. Each system’s
type and name are shown, along with their linear and nonlinear solvers if
they differ from the defaults, which are LinearRunOnce and NonlinearRunOnce respectively.
If the -c option is used, the tree will print in color if the terminal supports it and
the colorama package is installed. If colors are used, implicit and explicit components will be
displayed using different colors.
The input and output sizes can also be displayed using the –sizes arg, and the –approx arg will display the approximation method and the number of approximated partials for systems that use approximated derivatives.
The tree command also allows specific attributes and/or vector variables to be printed out along with their corresponding system in the tree using the –attr and –var args respectively.
Here’s an example of the tree output for a simple circuit model:
openmdao tree --sizes --approx circuit.py
Driver: Driver
Group (11 / 7)
IndepVarComp ground (0 / 1)
IndepVarComp source (0 / 1)
Circuit circuit (11 / 5) LN: DirectSolver NL: NewtonSolver Jac: CSCJacobian
Node n1 (3 / 1) APPROX: ['fd'] (3 of 3)
Node n2 (2 / 1) APPROX: ['fd'] (2 of 2)
Resistor R1 (2 / 1) APPROX: ['fd'] (2 of 3)
Resistor R2 (2 / 1) APPROX: ['fd'] (2 of 3)
Diode D1 (2 / 1) APPROX: ['fd'] (2 of 3)
openmdao summary¶
The openmdao summary command prints a high level summary of the model. For example:
openmdao summary circle_opt.py
============== Problem Summary ============
Groups: 1
Components: 7
Max tree depth: 1
Design variables: 3 Total size: 21
Nonlinear Constraints: 4 Total size: 21
equality: 2 11
inequality: 2 10
Linear Constraints: 1 Total size: 1
equality: 1 1
inequality: 0 0
Objectives: 1 Total size: 1
Input variables: 11 Total size: 82
Output variables: 9 Total size: 67
Total connections: 10 Total transfer data size: 72
Driver type: ScipyOptimizeDriver
Linear Solvers: [LinearRunOnce]
Nonlinear Solvers: [NonlinearRunOnce]
openmdao cite¶
The openmdao cite command prints citations for any classes in the model that have them.
It supports optional -c arguments to allow you to limit displayed citations to
only those belonging to a particular class or group of classes. By default, all citations for
any class used in the problem will be displayed. For example:
openmdao cite circuit.py
Class: <class 'openmdao.core.problem.Problem'>
@article{openmdao_2019,
Author={Justin S. Gray and John T. Hwang and Joaquim R. R. A.
Martins and Kenneth T. Moore and Bret A. Naylor},
Title="{OpenMDAO: An Open-Source Framework for Multidisciplinary
Design, Analysis, and Optimization}",
Journal="{Structural and Multidisciplinary Optimization}",
Year={2019},
Publisher={Springer},
pdf={http://openmdao.org/pubs/openmdao_overview_2019.pdf},
note= {In Press}
}
Profiling and Tracing Commands¶
The following commands perform profiling or tracing on a run script, filtering their target
functions based on pre-defined groups of functions that can be displayed using the -h command
line option. For example, here’s the usage output for the openmdao trace command, which includes
the function groups available at the time of this writing:
usage: openmdao trace [-h] [-g METHODS] [-v] file
positional arguments:
file Python file to be traced.
optional arguments:
-h, --help show this help message and exit
-g METHODS, --group METHODS
Determines which group of methods will be traced.
Default is "openmdao". Options are: ['dataflow',
'linear', 'mpi', 'openmdao', 'openmdao_all', 'setup']
-v, --verbose Show function locals and return values.
openmdao iprof¶
The openmdao iprof command will display an icicle plot showing the time elapsed in all of the target
methods corresponding to each object instance that they were called on. For more details, see
Instance-based Profiling.
openmdao iprof_totals¶
The openmdao iprof_totals command performs the same profiling as openmdao iprof, but it outputs a simple,
text-based summary of the total time spent in each method. The Instance-based Profiling
section contains more details.
openmdao trace¶
The openmdao trace command prints a call trace for a specified set of functions. Optionally it can
display values of function locals and return values. For more detail, see
Instance-based Call Tracing.
Memory Profiling¶
openmdao mem¶
The openmdao mem command profiles the memory usage of python functions. For more detail,
see Memory Profiling.
openmdao mempost¶
The openmdao mempost postprocesses the raw memory dump file generated by openmdao mem.
For more detail, see Memory Profiling.
Other Commands¶
openmdao call_tree¶
The openmdao call_tree command takes the full module path of a class method and displays the
call tree for that method. It’s purpose is to show which class ‘owns’ the specified method
call and any other ‘self.*’ methods that it calls. Note that it shows all of the methods called,
regardless of the result of conditionals within any function, so the displayed tree does not
necessarily represent a trace of the function as it executes. The functions are ordered top to
bottom as they are encountered in the source code, and a given subfunction is only displayed
once within a given function, even if it is actually called in multiple places within the function.
Here’s an example:
openmdao call_tree openmdao.api.LinearBlockGS.solve
BlockLinearSolver.solve
Solver._solve
Solver._mpi_print_header
BlockLinearSolver._iter_initialize
BlockLinearSolver._update_rhs_vecs
LinearSolver._run_apply
BlockLinearSolver._iter_get_norm
Solver._mpi_print
LinearBlockGS._single_iteration
LinearSolver._run_apply
BlockLinearSolver._iter_get_norm
openmdao scaffold¶
The openmdao scaffold command generates simple scaffolding, or ‘skeleton’ code for
an explicit or implicit component. In addition, it will generate the scaffolding for a simple
test file of that component. The available options are as follows:
openmdao scaffold -h
usage: openmdao scaffold [-h] -c CLASS_NAME [-e] [-i] [file]
positional arguments:
file output file.
optional arguments:
-h, --help show this help message and exit
-c CLASS_NAME, --class CLASS_NAME
Name of the component class. If an output file is not
provided, this name will be used to generate the
output file name.
-e, --explicit Generate an ExplicitComponent.
-i, --implicit Generate an ImplicitComponent.
This command is only an initial attempt to provide this sort of functionality and any user feedback describing how to improve it is welcome.
Using Commands under MPI¶
In general, usage of openmdao subcommands under MPI is the same as usual, except the command will be preceded by mpirun -n <num_procs>. For example:
mpirun -n 2 openmdao summary multipoint_beam_opt.py
============== Problem Summary ============
Groups: 4
Components: 10
Max tree depth: 3
Design variables: 1 Total size: 5
Nonlinear Constraints: 1 Total size: 1
equality: 1 1
inequality: 0 0
Linear Constraints: 0 Total size: 0
equality: 0 0
inequality: 0 0
Objectives: 1 Total size: 1
Input variables: 10 Total size: 1961
Output variables: 10 Total size: 1117
Total connections: 10 Total transfer data size: 1961
Driver type: ScipyOptimizeDriver
Linear Solvers: [LinearRunOnce x 4]
Nonlinear Solvers: [NonlinearRunOnce x 4]