Command Line Tools

OpenMDAO has a number of command line tools that are available via the openmdao command.


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


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 -- -x --myarg=bar would pass -x and --myarg=bar as args to

All available openmdao sub-commands can be shown using the following command:

openmdao -h
usage: openmdao [-h] [--version]  ...

OpenMDAO Command Line Tools

optional arguments:
  -h, --help            show this help message and exit
  --version             show program's version number and exit

    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
    cite                Print citations referenced by the problem.
                        Compute entry point declarations to add to the
    find_plugins        Find openmdao plugins on github.
    iprof               Profile calls to particular object instances.
    iprof_totals        Generate total timings of calls to particular object
    list_installed      List installed types recognized by OpenMDAO.
    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.
    scaling             View driver scaling report.
    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
    view_dyn_shapes     View the dynamic shape dependency graph.
    view_mm             View a metamodel.

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

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.
                        ignored, now always true.


Several of the example commands below make use of the files and 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
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:
                        ['auto_ivc_warnings', '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

will generate an \(N^2\) diagram like the one below.

It’s also possible to generate an \(N^2\) diagram for a particular test function rather than for a standalone script. This is done by providing the test spec for the test function instead of the filename of the script. For example, if we had a test located in a file called, and the test named test_my_stuff was inside of a TestCase class called MyTestCase, we could generate the \(N^2\) diagram for it using the following command:

openmdao n2

If the test module happens to be part of a python package, then you can also use the dotted module pathname of the test module instead of the filename.

A number of other openmdao commands, includng view_connections and tree, also support this functionality.

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
An example of a connection viewer

An example of a connection viewer.

By default the promoted names columns of both inputs and outputs are shown and their absolute 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 produced 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 scaling

The openmdao scaling command generates tables of information for design variables, objectives, and constraints, as well as a viewer that shows magnitudes of subjacobians of the total jacobian.

Design variable/objective/constraint tables

Any of the columns in the design variable, objective, and constraint tables can be sorted by clicking on the header of the desired column. Each row in a table corresponds to an individual design variable, objective, or constraint, and if that variable happens to be an array then the row can be expanded vertically using the “+” button on the far left to show a row for each entry in that array. In the constraints table, if a constraint is linear it will have a green check mark in the “linear” column.

Jacobian viewer

The jacobian viewer displays magnitude information for each subjacobian of the total jacobian. It contains one column for each design variable and one row for each objective and constraint. If there are linear constraints, the part of the total jacobian that depends on them will be displayed in a separate tab. A detailed view of a given sub-jacobian can be see by left clicking on the corresponding cell in the total jacobian view. It will open a new tab containing the detailed sub-jacobian view. The detailed sub-jacobian view can be closed by right clicking on the tab.

Cells in both the top level and detailed sub-jacobian views will be colored based on the maximum absolute value found in that location. If the location is known to be zero because a total coloring has been computed, it will be dark gray in color. If the location happens to have a value of zero for some other reason, it will be colored light gray. All other values will be displayed using a color map that goes from red at large values down to blue for small values.

Below is an example of what the driver scaling tables and the jacobian view look like:

An example of driver scaling report tables

An example of driver scaling report tables.

An example of driver scaling report jacobian view

An example of driver scaling report jacobian view.

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
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
============== Problem Summary ============
Groups:               1
Components:           8
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:           10   Total size:       77

Total connections: 11   Total transfer data size: 82

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
Class: <class 'openmdao.core.problem.Problem'>
        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}",
        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

openmdao scaffold

The openmdao scaffold command generates simple scaffolding, or ‘skeleton’ code for a class that inherits from an allowed OpenMDAO base class. The allowed base classes are shown as part of the description of the –base arg below:

openmdao scaffold -h
usage: openmdao scaffold [-h] [-c CLASS_NAME] [-b BASE] [-p PACKAGE]
                         [--cmd COMMAND_NAME]

optional arguments:
  -h, --help            show this help message and exit
                        Name of the new class. If an output file is not
                        provided, this name will be used to generate the
                        output file name.
  -b BASE, --base BASE  Name of the base class for the new class. Allowed base
                        classes are: ['BaseCaseReader', 'CaseRecorder',
                        'Driver', 'ExplicitComponent', 'Group',
                        'ImplicitComponent', 'LinearSolver',
                        'NonlinearSolver', 'SurrogateModel']
  -p PACKAGE, --package PACKAGE
                        Specify name of python package. If this is specified,
                        the directory structure for a python package will be
  --cmd COMMAND_NAME    Create scaffolding for an OpenMDAO command line tool.

In addition, the command will generate the scaffolding for a simple test file for that class, and if the –package option is used, it will generate the directory structure for a simple installable python package and will declare an entry point in the file so that the given class can be discoverable as an OpenMDAO plugin when installed.

To build scaffolding for an OpenMDAO command line tool plugin, use the –cmd option.

openmdao list_installed

The openmdao list_installed command lists installed classes of the specified type(s). Its options are shown below:

openmdao list_installed -h
usage: openmdao list_installed [-h] [-d] [-x EXCLUDES] [-i INCLUDES]
                               [types [types ...]]

positional arguments:
  types                 List these types of installed classes. Allowed types
                        are ['case_reader', 'case_recorder', 'command',
                        'component', 'driver', 'group', 'lin_solver',
                        'nl_solver', 'surrogate_model'].

optional arguments:
  -h, --help            show this help message and exit
  -d, --docs            Display the class docstrings.
  -x EXCLUDES, --exclude EXCLUDES
                        Package to exclude.
  -i INCLUDES, --include INCLUDES
                        Package to include.

By default, installed types from all installed packages are shown, but the output can be filtered by the use of the -i option to include only specified packages, or the -x option to exclude specified packages.

For example, to show only those linear and nonlinear solver types that are part of the openmdao package, do the following:

openmdao list_installed lin_solver nl_solver -i openmdao
Installed lin_solvers:

  Package: openmdao  Version: 3.6.1-dev 

    Class or Function  Module  
    -----------------  ------  
    LinearBlockGS      openmdao.solvers.linear.linear_block_gs
    LinearBlockJac     openmdao.solvers.linear.linear_block_jac
    LinearRunOnce      openmdao.solvers.linear.linear_runonce
    PETScKrylov        openmdao.solvers.linear.petsc_ksp
    ScipyKrylov        openmdao.solvers.linear.scipy_iter_solver
    LinearUserDefined  openmdao.solvers.linear.user_defined

Installed nl_solvers:

  Package: openmdao  Version: 3.6.1-dev 

    Class or Function  Module  
    -----------------  ------  
    ArmijoGoldsteinLS  openmdao.solvers.linesearch.backtracking
    BoundsEnforceLS    openmdao.solvers.linesearch.backtracking
    BroydenSolver      openmdao.solvers.nonlinear.broyden
    NewtonSolver       openmdao.solvers.nonlinear.newton
    NonlinearBlockGS   openmdao.solvers.nonlinear.nonlinear_block_gs
    NonlinearBlockJac  openmdao.solvers.nonlinear.nonlinear_block_jac
    NonlinearRunOnce   openmdao.solvers.nonlinear.nonlinear_runonce

Similarly, to hide all of the built-in (openmdao) solver types and only see installed plugin solver types, do the following.

openmdao list_installed lin_solver nl_solver -x openmdao

openmdao find_plugins

The openmdao find_plugins command finds github repositories containing openmdao plugins. Its options are shown below:

openmdao find_plugins -h
usage: openmdao find_plugins [-h] [types [types ...]]

positional arguments:
  types       Find these types of plugins. Allowed types are ['case_reader',
              'case_recorder', 'command', 'component', 'driver', 'group',
              'lin_solver', 'nl_solver', 'openmdao', 'surrogate_model'].

optional arguments:
  -h, --help  show this help message and exit

One example of its use would be to display any github repositories containing openmdao command line tools. At the time this documentation was created, the following repositories were found:

openmdao find_plugins command
Pkg Name       URL                                      Topics
--------       ___                                      ______
OpenMDAO-XDSM  ['openmdao', 'openmdao-command']
om_devtools  ['openmdao', 'openmdao-command']

openmdao compute_entry_points

The openmdao compute_entry_points command lists entry point groups and entry points for any openmdao compatible classes, e.g., Component, Group, etc., that it finds within a given python package. Its options are shown below:

openmdao compute_entry_points -h
usage: openmdao compute_entry_points [-h] [-o OUTFILE] package

positional arguments:
  package     Compute entry points for this package.

optional arguments:
  -h, --help  show this help message and exit
  -o OUTFILE  output file.

For example, to show all of the potential openmdao entry point groups and entry points for an installed python package called mypackage, you would do the following:

openmdao compute_entry_points mypackage

The entry point information will be printed in a form that can easily be pasted into the file for the specified package.

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
============== 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]