CAPE Documentation

Welcome to CAPE, a computational aerosciences processing environment for efficient interaction with several high-fidelity aerodynamics codes. This includes tools for pre-processing, executing the codes, performing post-processing tasks, and creating finished databases. The approach of Cape is to provide tools that make users more efficient at some or all of the modeling and analysis process. It may be useful to use CAPE for just one step of a particular user’s project, or it may be useful to use it for the entire process.

LICENSE

What’s new in version 2.3.0

  • More flexible command-line interface

    CAPE calls, while still preserving backward compatibility, can now be simplified. Instead of calling pyfun, pycart, pyover, etc. most calls can now be done by just using cape. CAPE will automatically determine which solver module to use by quickly looking at the contents of the JSON file. In combination with the implicit or explicit sub-command, this means that most CAPE calls have four different ways to be invoked:

    $ cape c
$ cape -c
$ pyfun check
$ pyfun -c

    If the cape executable determines the wrong solver (e.g. it thinks your JSON file is a Cart3D JSON file when it’s actually for LAVA), you can use the explicit call (pylava in the previous example).

  • pylava: CAPE has added support for a fifth solver, NASA’s new LAVA package. For this release only the LAVA Cartesian solver is fully supported.

  • Additional CAPE sub-commands and options

    • Use cape open-pdf report/report-$REPORT.pdf --pull to automatically transfer a report file from an HPC node and open it locally

    • Use cape find to just return the indices of cases that match a set of constraints.

    • The cape edit-json command is an option to edit the contents of the main JSON file through a command-line interface

    • Case subsets can now be constrained by status, e.g

      $ cape c --status DONE

      However, using this constraint interferes with the speed-up from parallelization (see below).

    • For shared run matrices, you can use the new option --me instead of the much longer --cons "user=='$USER'". The --me option will do nothing unless you have a run matrix key named "user" or another user-type key defined.

  • Much faster run matrix checking

    Checking on a large run matrix, especially with pyfun, can be time-consuming. This is mostly because determining how many iterations have been run can be surprisingly complicated for some of the CFD solvers. cape -c is now automatically parallelized, so that it can analyze several cases in parallel, controlled by the new --nproc option.

  • Smarter error handling

    Many errors caused by incorrect input (and also KeyboardInterrupt or Ctrl-C) will now produce a small error message rather than a full Python traceback. Progress will continue to be made on this front in future versions of CAPE.

  • Logging: most command-line CAPE calls are now recorded in a log file.

    Whenever you run a CAPE command that involves a cape.cfdx.cntl.Cntl instance, it will now log that command the folder

    log/{BASENAME_OF_JSON_FILE}/

    where $BASENAME_OF_JSON_FILE is the name of the JSON/YAML control file with the .json stripped. This can include sub-folders. In this folder for logging a single CAPE file, you will see

    • cmd.log

    • hash.log

    • last.json

    For example if you run pyfun -c and pyFun.json is linked to run/dac3-asc01.json, you’ll get a folder (or append to it if it already exists) called log/cmd/run/dac3-asc01/ with those three files in it. The cmd.log file will contain a line such as

    CMD,2026-01-07 14:55:33,pyfun check -f run/dac3-asc01.json

    The commands are “canonical-ized” so that the actual name of the JSON file is always included, and it will use the new two-word format for the logged commands. The line preceding this CMD line will be a SHA-256 hash of the current expanded (and comment-stripped) JSON file for tracing.

    You can turn this off by setting

    "LogLevel": 0

    in the JSON file or by the environment variable $CAPE_LOG_LEVEL.

    export CAPE_LOG_LEVEL=0

  • Advanced case naming

    New settings in the "RunMatrix" section named "Replace" and "RegexSubs". These allow you to replace one string with another (Replace) or apply general regular expression replacements using re.sub(). For example, if you don’t want decimal points in your case names, you could use:

    "RunMatrix": {
    "Replace": {
        ".": "p"
    }
}

    to get conversions like m2.50a2.0 → m2p50a2p0 or use

    "RunMatrix": {
    "Replace": {
        ".": ""
    }
}

    to get conversions like m2.50a2.0 → m250a20. One more example:

    "RunMatrix": {
    "Replace": {
        ".0": "",
        ".": ""
    }
}

    to get m2.50a2.0 → m250a2.

See the full Changelog for more details on recent features.

Installation: Installation is done using the standard Python packaging tool pip.

Most users really would rather evaluate new tools by seeing some examples, so here are the links to the example pages for the main solvers:

Currently, CAPE has interfaces for Cart3D, FUN3D, CREATE-AV Kestrel, and OVERFLOW. The Cart3D interface, cape.pycart has been used for several NASA projects. One example was the creation of an aerodynamic database for booster separation for the Space Launch System, which included over 10,000 different adaptive Cart3D runs in a 12-dimensional run matrix.

The FUN3D interface, cape.pyfun, reuses most of the code used to build cape.pycart; and the OVERFLOW interface, cape.pyover was constructed in a similar manner. All modules are built off of common tools in the cape and cape.cfdx modulew, and so much of the usage is common between the two interfaces. These interfaces can be used to run OVERFLOW/FUN3D, interact with databases, and archive or clean up solutions. There is a Python interface to solution files including easy dimensionalization of state variables.

In addition to running CFD codes, CAPE contains a package called cape.dkit for cleaning and processing numerical databases whether the original data comes from CFD or not. The key tool from this package is the class

which can read CSV files, other ASCII text data files, MATLAB .mat files, Excel spreadsheets, and more.

Each CFD interface is a portmanteau of “Python” and the name of the solver. The command-line interface is invoked with the commands pycart, pyfun, and pyover. In addition, there are several scripts matching the glob p?_*.py and for isolated tasks such as converting grid formats, and there is a run_*.py script for running the appropriate tasks for a single case of each CFD interface.

Cape Inputs and JSON Files Inputs to Cape can be given as either command-line arguments, input files associated with the CFD solver, or JSON files. JSON is a simple but flexible format similar to XML. There are interpreters for many languages.

Common CAPE Capabilities The following bullet list of capabilities is common to all interfaces including any that will be added in the future.

  • Automatically create parametrically-named folders for cases in a matrix

  • Copy input files to run folders and edit them according to run matrix variables and multiple phases of global input settings

  • Create PBS scripts and submit them automatically

  • Built-in variables such as Mach number, angle of attack, sideslip, Reynolds number, and temperature

  • Automated averaging of iterative histories and statistics for databases

  • Automated reports using LaTeX (usually supports Tecplot and ParaView images)

pyCart Capabilities The Cart3D interface, pyCart, has quite a few capabilities. Some highlights and critical aspects are listed below.

  • Copy Cart3D input files to run files and edit them according to run matrix variables and global input settings

  • Simplified interface for refining initial volume mesh using component names

  • Rotate components (such as fins or separating bodies) using Euler angles or a hinge axis

  • Automated reports of iterative histories and Tecplot layouts

  • Interface for custom functions for more advanced run matrix variables such as thrust settings

The basic usage for this module is to create a file called pyCart.json and use the script pycart. In addition to this control file for pyCart, several other Cart3D input files (or, more accurately, input template files) can be provided or interfaced. The names below are canonical names; it is possible to use other file names when setting up configurations.

  • Cart3D input control file, input.cntl

  • Surface triangulation file, Components.i.tri

  • Surface triangulation component names, Config.xml

  • If an adaptive run, an adaptive run script, aero.csh

  • Run matrix, either specified within pyCart.json or a file

pyFun Capabilities The FUN3D interface, pyFun, is newer and has somewhat fewer capabilities, although most of the database and reporting capabilities are inherited from pyCart. Some capabilities are highlighted below.

  • Copy FUN3D input files to run files and edit them according to run matrix variables and global input settings

  • Interface with AFLR3 for volume mesh generation, which can be used to have multiple bodies in different relative positions for each case in a run matrix

  • Interface to Chimera Grid Tools triload to calculate sectional loads

The basic usage for this module is to create a file called pyFun.json and use the script pyfun. The required FUN3D input files are described below.

  • FUN3D run settings template, fun3d.nml

  • Mesh file; a recommended format is AFLR3, *.ugrid

  • Boundary condition file, *.mapbc

  • Run matrix, either specified within pyFun.json or a file

pyOver Capabilities The OVERFLOW interface, pyOver, is also new but will have a rapidly expanding set of capabilities. Much of the database and report capabilities are inherited from pyCart. Some highlights are below.

  • Copy OVERFLOW input namelists and edit them according to run matrix variables and multiple phases of input settings

  • Highly generalized interface to OVERFLOW namelists that doesn’t need great amounts of user preparation

  • Built-in interface to OVERFLOW q files with simple access to coefficients and dimensional states

The basic usage for this module involves a file pyOver.json, and the primary script is pyover. Required input files depend on whether the case is being run in DCF or Pegasus5 mode. In this module, the user is responsible for informing pyOver which mesh files are required, although a default list is defined. In general the required files are the following.

  • OVERFLOW namelist template, overflow.inp

  • Mesh files, usually in the common/ folder

  • Run Matrix, either within pyOver.json or in a CSV-like file

Reference

API Documenattion

Testing

Authors

Contributing

Notices

Copyright © 2022 United States Government as represented by the Administrator of the National Aeronautics and Space Administration. All Rights Reserved.

Disclaimers

No Warranty: THE SUBJECT SOFTWARE IS PROVIDED “AS IS” WITHOUT ANY WARRANTY OF ANY KIND, EITHER EXPRESSED, IMPLIED, OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, ANY WARRANTY THAT THE SUBJECT SOFTWARE WILL CONFORM TO SPECIFICATIONS, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR FREEDOM FROM INFRINGEMENT, ANY WARRANTY THAT THE SUBJECT SOFTWARE WILL BE ERROR FREE, OR ANY WARRANTY THAT DOCUMENTATION, IF PROVIDED, WILL CONFORM TO THE SUBJECT SOFTWARE. THIS AGREEMENT DOES NOT, IN ANY MANNER, CONSTITUTE AN ENDORSEMENT BY GOVERNMENT AGENCY OR ANY PRIOR RECIPIENT OF ANY RESULTS, RESULTING DESIGNS, HARDWARE, SOFTWARE PRODUCTS OR ANY OTHER APPLICATIONS RESULTING FROM USE OF THE SUBJECT SOFTWARE. FURTHER, GOVERNMENT AGENCY DISCLAIMS ALL WARRANTIES AND LIABILITIES REGARDING THIRD-PARTY SOFTWARE, IF PRESENT IN THE ORIGINAL SOFTWARE, AND DISTRIBUTES IT “AS IS.”

Waiver and Indemnity: RECIPIENT AGREES TO WAIVE ANY AND ALL CLAIMS AGAINST THE UNITED STATES GOVERNMENT, ITS CONTRACTORS AND SUBCONTRACTORS, AS WELL AS ANY PRIOR RECIPIENT. IF RECIPIENT’S USE OF THE SUBJECT SOFTWARE RESULTS IN ANY LIABILITIES, DEMANDS, DAMAGES, EXPENSES OR LOSSES ARISING FROM SUCH USE, INCLUDING ANY DAMAGES FROM PRODUCTS BASED ON, OR RESULTING FROM, RECIPIENT’S USE OF THE SUBJECT SOFTWARE, RECIPIENT SHALL INDEMNIFY AND HOLD HARMLESS THE UNITED STATES GOVERNMENT, ITS CONTRACTORS AND SUBCONTRACTORS, AS WELL AS ANY PRIOR RECIPIENT, TO THE EXTENT PERMITTED BY LAW. RECIPIENT’S SOLE REMEDY FOR ANY SUCH MATTER SHALL BE THE IMMEDIATE, UNILATERAL TERMINATION OF THIS AGREEMENT.