Changelog

Release 2.0.0

New Features

  • Added a command cape --1to2 to help update Python files written against the CAPE 1.2 API to the newer module names mentioned below.

  • New command-line interface. The CLI supports the commands that would have worked for CAPE 1 but also support a new method that allows the user to be more explicit about the primary purpose of the command. For example

    $ pyfun --re "m1.2" --report

    is the same as

    $ pyfun report --re "m1.2"

    The new CLI also implements checks so that misspelled or unrecognized options will result in an error instead of just ignoring those options.

  • Created a new executable cape-tec that takes a Tecplot(R) layout file as input and exports a PNG from that layout.

  • Rewritten interface to RunControl > Archive. Users may now prescribe “only keep the most recent file of this set” of multiple patterns in a single line. For example …

    "Archive": {
    "SearchMethod": "regex",
    "clean": {
        "PreDeleteFiles": {
            "pyfun[0-9]+_([a-z][a-z0-9_-]+)_timestep[0-9]+\\.plt": 1
        }
    }
}

    This will delete most Tecplot .plt files but keep the most recent 1 matches. The new feature is that it will collect all the files that match this regular expression but divide them into separate lists for all the unique values of the regular expression group (the part inside parentheses). So if you have the following files:

    • pyfun00_plane-y0_timestep1000.plt

    • pyfun00_tec_boundary_timestep1000.plt

    • pyfun01_plane-y0_timestep2000.plt

    • pyfun01_tec_boundary_timestep2000.plt

    • pyfun02_plane-y0_timestep3000.plt

    • pyfun02_plane-y0_timestep4000.plt

    • pyfun02_tec_boundary_timestep3000.plt

    • pyfun02_tec_boundary_timestep4000.plt

    Then it would delete most of these files but only keep

    • pyfun02_plane-y0_timestep4000.plt

    • pyfun02_tec_boundary_timestep4000.plt

    This would not have been possible in CAPE 1; users would need to provide two separate instructions.

  • A RunMatrix key with the type "translation" can now use two named points as the "Vector". This means that the direction that a component is translated can be affected by prior RunMatrix keys

Behavior Changes

  • Many modules have been renamed, including renaming the case modules to the less-confusing name casecntl. In addition, the main cntl module has been moved into the cape.cfdx folder.

Bugs Fixed

  • Determination of number of available MPI ranks on Slurm jobs

Release 1.2.1

New Features

  • Each case now generates logs, which are helpful for debugging or just understanding the sequence of actions CAPE takes. The two log files within each case are cape/cape-main.log and cape/cape-verbose.log).

  • PBS/Slurm job names are now longer (32 chars instead of 15), and the length is configurable (RunMatrix > MaxJobNameLength).

Behavior Changes

  • PBS/Slurm job IDs are now saved as the full string instead of just the job number (often something like 123456.pbspl1)

  • The extensions are now build against NumPy version 2.0+ for Python 3.10 and later. The Python 3.9 extension is still build against NumPy 1.x.

Bugs Fixed

  • Better support of newer aero.csh script for Cart3D

  • Various compatibility issues with NumPy 2.0 release

Release 1.2.0

CAPE 1.2 is a smaller change than CAPE 1.1 and focuses on improving the quality of CAPE’s underlying code. Many modules have been de-linted, and some of the older modules have been rewritten. Test coverage is also significantly improved.

New Features

Behavior Changes

  • The iterative history modules, CaseFM and CaseResid, are now subclasses of DataKit. Among other things, this means that what used to be fm.CN is now fm["CN"]. This is a major improvement to making those classes extensible for histories of things other than forces & moments.

  • The cape.filecntl.filecntl module, which is critical to how CAPE reads and modifies CFD input files, was rewritten and tested to 100% coverage.

  • Rename some RunControl options to more understandable

    • Resubmit → ResubmitNextPhase

    • Continue → opposite of ResubmitSamePhase

    (See https://nasa.github.io/cape-doc/1.2/common/json/RunControl.html)

Bugs Fixed

  • The documentation now builds without warnings.

Release 1.1.1.post2

Bugs Fixed

  • Add (back) default "MuFormat" for coefficient table subfigures, which was causing tables full of the text “None” in some cases

  • Fix nmlfile when saving a long string in an existing array

  • Fix default formatting of user and tag run matrix keys in conditions table subfigures

Release 1.1.1.post1

That’s a weird-looking version number…

This post-release fixes some issues that the testing suite did not catch regarding the previous CAPE 1.1 releases.

Bugs Fixed

  • The TriRotate and TriTranslate run matrix keys now work properly again; they were not getting noticed as the correct key type in previous 1.1 releases.

  • Using a list inside a @map dict now works with phase numbers in cape.optdict

  • Fixes to flow initializations for FUN3D for new nmlfile Fortran namelist manipulation module

  • The cape.nmlfile namelist module now supports N-dimensional arrays, whereas the set_opt() method didn’t support this before.

Release 1.1.1

CAPE 1.1.1 introduces the optional "NJob" option, which can be placed in the "RunControl" section. If you set this parameter to a positive integer, CAPE will automatically keep that many jobs running. When one case finishes, it will submit the appropriate number of new jobs until the total number of jobs (not counting the one that is finishing) equals NJob. Using this option, users can start a run matrix and keep a roughly fixed number of cases running for long periods of time without having to manually check and/or submit new jobs.

Features added

  • "RunControl" > "NJob" option

Bugs Fixed

(Same as Release 1.0.4)

  • Allow spaces in strings when reading tab-delimited files using DataKit or TextDataFile.

  • Fix some matplotlib imports to work with more matplotlib versions.

  • Switch order of CaseFunction() hook and WriteCaseJSON() in cape.pycart so that case.json reflects options changes from all hooks.

Release 1.1.0

CAPE 1.1 incorporates an entirely new interface to how it reads the JSON files that define most of the CAPE inputs. See cape.optdict for details about the new options package and cape.cfdx.options for an gateway to the CAPE-specific options for each section.

CAPE 1.1 removes support for Python 2.7. It supports Python 3.6+ (because that’s the version available on standard Red Hat Enterprise Linux versions 7 and 8), but testing is performed in Python 3.9.

This change is meant to be backwards-compatible with CAPE 1.0 with respect to the JSON files, so the same JSON file that worked with CAPE 1.0 should work with CAPE 1.1. However, the API is not fully backward-compatible, so some user scripts and any hooks may need to be modified for CAPE 1.1. Also, although CAPE 1.0 JSON files should be compatible with CAPE 1.1, there may be many warnings when using CAPE 1.1.

CAPE 1.1 adds support for a fourth CFD solver, namely Kestrel from the Department of Defense’s CREATE-AV program.

There are three key features for CAPE 1.1 that all come from the incorporation of cape.optdict:

  • Option names, types, and values are checked and validated throughout the JSON file. This contrasts with the CAPE 1.0 behavior where unrecognized options (e.g. a spelling error) were silently ignored, and invalid values (e.g. a str instead of an int) may or may not result in an Exception later.

  • JSON syntax errors generate much more helpful messages, especially if the error is in a nested file using the JSONFile() directive.

  • All or nearly all settings in the JSON file (except in the "RunMatrix" section) can vary with run matrix conditions using one of three methods.

Related to the third bullet, you can use @cons (constraints), @map, and @expr. For example to set a CFL number equal to 2 times the Mach number, assuming the "RunMatrix" > "Keys" includes a key called "mach", set

"CFL": {
    "@epxr": "2*$mach"
}

The next example demonstrates how to use a separate grid for supersonic and subsonic conditions.

"Mesh": {
    "File": {
        "@cons": {
            "$mach < 1": "subsonic.ugrid",
            "$mach >= 1": "supersonic.ugrid"
        }
    }
}

The third method is @map, which might be used to use specific values based on the value of some run matrix key. This example creates a map of how many PBS nodes to use based on a run matrix key called "arch".

"PBS": {
    "select": {
        "@map": {
            "model1": 10,
            "model2": 20
        },
        "key": "arch"
    }
}

You can also nest these features, with the most common example having an @expr inside a cons set.

Features added

  • Better error messages for JSON syntax errors

  • Explicit checks for option names and option values in most of JSON file

  • Ability to easily vary almost any JSON parameter as a function of run matrix conditions

  • Add support for Kestrel as fourth CFD solver (cape.pykes)

Bugs fixed

  • Raise an exception if component list not found during py{x} --ll (previously wrote invalid triload input files and encountered an error later)

Behavior changes

  • Drop support for Python 2.7.

  • FUN3D namelists no longer preserve text of template file; instead cape.nmlfile.NmlFile reads a namelist into a dict.

  • Options modules and classes renamed to more reasonable convention, e.g. cape.cfdx.options.runctlopts.RunControlOpts.

  • More readable cape.pyfun.case.run_fun3d() and other main loop runner functions.

Release 1.0.4

The test suite now runs with three Python versions: Python 2.7, 3.6, and 3.11. We also found a way to create wheels with the _cape2 or _cape3 extension module in more Python versions.

Bugs Fixed

  • Allow spaces in strings when reading tab-delimited files using DataKit or TextDataFile.

  • Fix some matplotlib imports to work with more matplotlib versions.

  • Switch order of CaseFunction() hook and WriteCaseJSON() in cape.pycart so that case.json reflects options changes from all hooks.

Release 1.0.3

Features added

  • Add "Config" > "KeepTemplateComponents" for pyfun, which tells pyfun to add components to the 'component_parameters' section rather than replacing it.

  • Support FUN3D 14.0 (a change to the STDOUT used to measure progress in pyfun)

Bugs fixed

  • Properly tests if grid.i.tri is already present using usurp for pyover --ll

  • Raise an exception if component list not found during py{x} --ll (previously wrote invalid triload input files and ecnountered an error later)

Release 1.0.2.post1

Bugs fixed

  • Restore previous support for dictionaries like

    {
    "sampling_parameters": {
        "plane_center(1:3, 2)": [0.0, 1.0, 0.0],
        "label(2)": "plane-y1",
    }
}

    as inputs to cape.filecntl.namelist.Namelist.ApplyDict. This is related to GitHub issues #4 and #19.

Release 1.0.2

Features added

  • Add "PostShellCmds" to "RunControl" for cape.pyover; allows users to add a list of commands that run after every call to OVERFLOW

  • Support more recent versions of aero.csh in cape.pycart

  • Add command-line options to py{x} --report:

    --report RP

    Update report named RP (default: first report in JSON file)

    –report RP –force

    Update report and ignore cache for all subfigures

    –report RP –no-compile

    Create images for a report but don’t compile into PDF

    –report RP –rm

    Delete existing caches of report subfigure images instead of creating them

  • Add support for commas within strings in DataBooks and run matrices

  • Add "A" option in "PBS" section

  • Allow nodet_mpi to set "nProc" automatically with Slurm

  • Add options "YLim", "YMin", "YMax", "YLimMin" and likewise for "PlotCoeff" subfigures.

    • "YLim": list of explicit min and explicit max to use for y-axis

    • "YMin": explicit min to use for y-axis

    • "YMax": explicit max to use for y-axis

    • "YLimMax": outer bounds for ymin and ymax; CAPE will not plot a y-value below YLimMax[0] but may have a min y-axis value greater than that, and CAPE will not plot a y-value above YLimMax[1]. Also supports using None (in Python) or null (in JSON) to use one of the bounds. E.g. "YLimMax": [0.0, null] will guarantee only positive y-values are shown but not set an upper bound.

    • The same options, replacing Y with X

Release 1.0.1

Features added

  • Warm-start capability for cape.pyfun, adds options WarmStart and WarmStartDir to "RunControl" section

Behavior changes

  • Use os.mkdir() instead of cape.cfdx.options.Options.mkdir() during archiving (affects resulting file permissions of new folders)

  • Write binary (lr4) instead of ASCII .triq files when using it_avg in cape.pycart; speeds up pycart --ll significantly

  • Allow users to write PNG or JPG files during --report commands w/o also creating PDFs; also ability to include PNG or JPG into compiled report

Bug fixes

  • Better control of force & moment requests in cape.pycart

  • Fix bug in reading some OVERFLOW iterative residual histories

  • Support columns with all np.nan in cape.attdb.rdb.DataKit.write_csv()

  • Allow adding two cape.pycart.dataBook.CaseFM instances with different iteration counts