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, things 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

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 problem
    dump_idxs       Show distributed index information.
    iprof           Profiling of calls to particular object instances.
    iprof_totals    Total timings of calls to particular object instances.
    mem             Memory profiler.
    mempost         Post-processor for 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.
    total_sparsity  Compute the sparsity pattern of the total jacobian.
    trace           Dump trace output.
    tree            Print the system tree.
    view_coloring   Colored jacobian viewer.
    view_connections
                    Connection viewer showing values and source/target units.
    view_model      Display an interactive N2 diagram of the problem.
                    (Deprecated, please use n2 instead.)
    xdsm            XDSM viewer.

Use -h after any sub-command for sub-command help.

All sub-commands are shown under ‘positional arguments’. To get further info on any sub-command, for example, for tree, follow the command with a -h. For example:

openmdao tree -h

usage: openmdao tree [-h] [-o OUTFILE] [-c] [-d DEPTH] [-a ATTRS] [-v VECVARS]
                     [-r RANK]
                     file

positional arguments:
  file                  Python file containing the model.

optional arguments:
  -h, --help            show this help message and exit
  -o OUTFILE            Output file name. By default, output goes to stdout.
  -c, --colors          Display colors if the terminal supports it. Requires
                        'colorama' python package. Use 'pip install colorama'
                        to install it.
  -d DEPTH, --depth DEPTH
                        Max depth of tree to display.
  -a ATTRS, --attr ATTRS
                        Add an attribute to search for in tree systems.
  -v VECVARS, --var VECVARS
                        Add a variable to search for in vectors of tree
                        systems.
  -r RANK, --rank RANK  Display the tree on this rank (if MPI is active).

Note

Several of the example commands below make use of a file circuit.py. This file is located in the openmdao/test_suite/scripts directory.

Post-setup Commands

The following commands all register a function that will run at the end of a Problem’s final_setup function. After the registered function completes, the program will exit, 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

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

× Instructions

Left clicking on a node in the partition tree will navigate to that node. Right clicking on a node in the model hierarchy will collapse/uncollapse it. A click on any element in the N^2 diagram will allow those arrows to persist.

OpenMDAO Model Hierarchy and N^2 diagram

Collapse Depth

Font Size 8px 9px 10px 11px 12px 13px 14px

Model Height 600px 650px 700px 750px 800px 850px 900px 950px 1000px 2000px 3000px 4000px

openmdao view_connections

The openmdao view_connections command generates a table of connection information for all input and output variables in the model. Units can be compared for each connection, and unconnected inputs and outputs can be easily identified. The displayed variables can be filtered by source system and/or target system. They can also be filtered by NO CONNECTION, which will show all of the unconnected inputs or outputs, depending on whether the NO CONNECTION filter is active for the source or target side. When units differ between a source and a target, they are highlighted in red, and when inputs are connected to outputs outside of the currently-selected, top-level system, they are highlighted in purple. This highlighting can be used to easily identify variables that are connected across group boundaries. Below is an example of a connection viewer for a pycycle propulsor model obtained using the command:

openmdao view_connections propulsor.py

An example of a connection viewer.

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 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. The tree Command also allows specific attributes and/or vector variables to be printed out along with their corresponding system in the tree.

Here’s an example of the tree output for a simple circuit model:

openmdao tree circuit.py

Driver: Driver
    Group 
        IndepVarComp ground
        IndepVarComp source
        Circuit circuit  LN: DirectSolver  NL: NewtonSolver LN_jac: CSCJacobian NL_jac: CSCJacobian
            Node n1  APPROX: ['fd'] (3 of 3)
            Node n2  APPROX: ['fd'] (2 of 2)
            Resistor R1  APPROX: ['fd'] (2 of 3)
            Resistor R2  APPROX: ['fd'] (2 of 3)
            Diode D1  APPROX: ['fd'] (2 of 3)

openmdao summary

The openmdao summary command prints a high level summary of the model. For example:

openmdao summary circuit.py

============== Problem Summary ============
Groups:               2
Components:           7
Max tree depth:       2

Design variables:            2   Total size:        2
Constraints (nonlinear):     0   Total size:        0
Constraints (linear):        0   Total size:        0
Objectives:                  1   Total size:        1

Input variables:            11   Total size:       11
Output variables:            7   Total size:        7

Total connections: 11   Total transfer data size: 11

Driver type: Driver
Linear Solvers: ['DirectSolver', 'LinearRunOnce']
Nonlinear Solvers: ['NewtonSolver', '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
Constraints (nonlinear):     1   Total size:        1
Constraints (linear):        0   Total size:        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']
Nonlinear Solvers: ['NonlinearRunOnce']