Introduction to CAPE Application Program Interface

The various methods used by pyCart, pyFun, and pyOver are based on a set of Python modules with a few capabilities written in C (with a full Python/C interface). In order to reduce the number of lines, most of the base functionality is provided by a common module cape. Then each of the modules for individual solvers (cape.pycart, cape.pyfun, cape.pyover) are based off of this module. Furthermore, pyCart is a heavily object-oriented implementation in which the vast majority of capabilities come from customized classes.

The most critical class is cape.cntl.Cntl, which acts as a template for the three classes that interact with actually submitting jobs and checking status. An instance of one of these classes comes from reading all the settings from a master JSON file. When a user utilizes the primary command-line interface via a command such as

$ pycart -f run/poweroff.json -c

the program works by loading an instance of cape.pycart.cntl.Cntl by reading run/poweroff.json and using methods of that instance. In this case, the Python version of the above is shown below.

# Load the pyCart API module
import cape.pycart

# Read the settings from the JSON file
cntl = cape.pycart.Cntl('run/powroff.json')

# Do something (in this case, the "-c" command)
cntl.DisplayStatus()

The basic modules based on this model are listed below:

Reading the JSON files depends heavily on the cape.options module. The majority of JSON settings are defined in cape.json, with some of the additional settings particular to each individual solver defined in cape.pycart.options, etc.

There are also a collection of helper modules, such as cape.pycart.report. These typically provide one or more classes (such as pyCart.report.Report) which add a few methods to the cape version. This leads to a definition for the cape.pycart version of the module that starts something like the following.

# Import CAPE version
import cape.cfdx.report

# Definition for pyCart.report.Report based on cape.cfdx.report.Report
class Report(cape.cfdx.report.Report):

    ...

Then the code in cape/pycart/report.py contains either methods that are particular to Cart3D or methods that need to be modified from the definitions in cape/report.py.

There are a few modules that provide tools that are not primarily based on classes. There is a set of so-called “case” modules, which are the interface to running the individual programs for each solver. For example, cape.pycart.case contains the function cape.pycart.case.run_flowCart(), which runs from within a case folder. The “case” modules are also based on cape.case but in a different way. These modules begin with the following line, and then additional commands that are particular to each solver are created in subsequent lines.

# Import all methods from the CAPE version
from cape.case import *

# Load local modules
from . import cmd
from . import bin
...

Here is a list of modules that are not primarily based on classes. Modules that are particular to a solver are listed as children of the cape module.

Finally, in addition to the cape.cntl.Cntl class, there are several classes that form the basis for the key CAPE functionality.

Class

Description and discussion

cape.tri.Tri

Interface to Cart3D-style surface triangulations, can read several formats, and triq files also can be read

cape.cfdx.dataBook.DataBook

CFD raw data database class

cape.cfdx.dataBook.CaseData

Template class for reading and interacting with iterative data from a single case

cape.cfdx.report.Report

Interface to automated reports

cape.filecntl.filecntl.FileCntl

Template for interacting with many CFD solver settings file types

cape.filecntl.namelist.Namelist

Class for reading Fortran namelists

cape.filecntl.namelist2.Namelist2

Alternative interface to Fortran namelists