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 3.0.0

New Features

  • AI integration

    The new command

    $ cape agentic

    now starts a persistent user interface that allows users to interact with CAPE using a human-language chatbot. Users supply their own Open AI-compatible endpoint. This could be a commercial website e.g. from Open AI or Anthropic, an internal service to your agency/institute/company, or a locally run model. The CAPE agentic harness is designed to be functional with any level of model from a simple 1B model to a frontier model. Declare the ToolSet in the new cape-agentic.json file to be "low" for smaller models to avoid exposing it to complex tool calls.

    The CAPE-Agentic UI will be an interactive, clickable interface if your terminal emulator app supports it; there’s a fall-back to a standard persistent command-line interface tool otherwise.

  • Persistent TUI

    The new command

    $ cape tui

    will open a persistent user interface if your terminal emulator supports it. This is separate from the LLM-enabled capability of cape agentic. The Terminal User Interface (TUI) is interesting because it provides smart tab completion and uses cached cape.cfdx.cntl.Cntl instances so you can save on overhead of rereading your JSON file for each new CAPE command.

    There is also

    $ cape ui

    that uses a readline-based user interface with many of those same benefits without the clickable interface, log folding, etc.

  • Interactive “dispatch” command

    The new command

    $ cape dispatch [CASES]

    starts an interactive session where users can decide on what to do with each case in a (potentially large) list. The typical use case for this command is to have a report (generated by cape report) open in one window while issuing a matching cape dispatch command in a terminal. E.g. you might run

    $ cape report -I 50:100

    and then open the PDF that it generates. While scrolling through that PDF to decide on each case, also run

    $ cape dispatch -I 50:100

    This will ask the user what to do with each case 50 to 100. By default cape-dispatch offers the options of approve, extend, extend2, and skip, which are relatively self-explanatory. Users can also add their own custom actions. This is convenient because it builds up the lists in a single window and immediately takes the appropriate follow-up actions.

  • Cusotmized CLI actions

    The new command cape perform, which also ties in with cape dispatch allows users to create compound and, optionally, parallel actions. There are three built-in actions, matching the three approve, extend, and extend2 actions built into cape-dispatch.

    For example the default

    $ cape perform approve [CASES]
$ cape perform extend [CASES]
$ cape perform extend2 [CASES]

    $ cape approve [CASES]
$ cape extend [CASES]
$ cape extend [CASES] --extend 2

    but you can customize what any “action” does in the new Actions section of the main CAPE JSON file. An example from the initial Artemis V ascent CFD runs

    "Actions": {
    "approve": [
        {
            "type": "cntl",
            "function": "MarkPASS"
        },
        {
            "type": "cntl",
            "function": "update_dex",
            "kwargs": {
                "dex": "CMA*"
            }
        },
        {
            "type": "cntl",
            "function": "update_dex",
            "index": 2,
            "kwargs": {
                "dex": "CS_[A-G]*"
            }
        },
        {
            "type": "cntl",
            "function": "update_dex",
            "index": 2,
            "kwargs": {
                "dex": "CS_[H-O]*"
            }
        },
        {
            "type": "cntl",
            "function": "update_dex",
            "index": 2,
            "kwargs": {
                "dex": "CS_[P-Z]*"
            }
        }
    ]
}

    This truncated example first approves the case (MarkPASS()) and then extracts a single databook component ("CMA*" only matches a single component from the "DataBook" section in this case) and then runs three data-extraction processes in parallel. The parallel specification is controlled by the "index": 2 lines. The reason for running "CMA*" first is to avoid conflicts on converting the raw FUN3D file to the .triq format that many of the other components use. The point is you can combine and parallelize actions as you see fit using cape-perform. To add non-default actions, just add their names to "Actions" > "UsetTools" and then define their actions.

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.