cape.cfdx.cntlbase: Abstract base module for run matrix control

This module provides an abstract base class CntlBase, which contains much of the functionality for controlling a full CFD run matrix in CAPE.

See also:
class cape.cfdx.cntlbase.CntlBase(fname: str | None = None)

Bases: ABC

Base class for cape.cfdx.cntl.Cntl

abstractmethod ApplyCase(i: int, **kw)

Rewrite CAPE inputs for case i

Call:
>>> cntl.ApplyCase(i, n=1, j=None, imax=None)
Inputs:
cntl: cape.pyfun.cntl.Cntl

CAPE main control instance

i: int

Run index

qsub: True | {False}

Option to submit case after applying settings

nPhase: int

Phase to apply settings to

abstractmethod ApplyCases(**kw)

Reapply settings to one or more cases

Call:
>>> cntl.ApplyCases(cons=[], j=None, extend=1, **kw)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Instance of overall control interface

extend: {True} | positive int

Extend phase j by extend nominal runs

j: {None} | nonnegative int

Phase number

cons: list[str]

List of constraints

I: list[int]

List of indices

Versions:

  • 2016-12-12 @ddalle: v1.0

abstractmethod ArchiveCase(i: int, test: bool = False)

Perform --archive archiving on one case

There are no restrictions on the status of the case for this action.

Call:
>>> cntl.CleanCase(i, test=False)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Instance of control interface

i: int

Case index

test: True | {False}

Log file/folder actions but don’t actually delete/copy

Versions:

  • 2024-09-18 @ddalle: v1.0

abstractmethod ArchiveCases(**kw)

Archive completed cases and clean them up if specified

Call:
>>> cntl.ArchiveCases()
>>> cntl.ArchiveCases(cons=[], **kw)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Instance of overall control interface

cons: list[str]

List of constraints

I: list[int]

List of indices

Versions:

  • 2016-12-09 @ddalle: v1.0

  • 2024-09-19 @ddalle: v2.0

abstractmethod CaseFunction(i: int)

Run one or more functions at “prepare-case” hook

This function is executed at the beginning of PrepareCase(i)().

This is meant to serve as a filter if a user wants to change the settings for some subset of the cases. Using this function can change any setting, which can be dependent on the case i.

This calls the function(s) in the global "CaseFunction" option from the JSON file. These functions must take cntl as an input and the case number i. The function(s) are usually from a module imported via the "Modules" option. See the following example:

"Modules": ["testmod"],
"CaseFunction": ["testmod.testfunc"]

This leads CAPE to call testmod.testfunc(cntl, i) at the beginning of PrepareCase() for each case i in the run matrix. The function is also called at the beginning of ApplyCase() if pyfun --apply or similar is issued.

Call:
>>> cntl.CaseFunction(i)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall control interface

i: int

Case number

Versions:

  • 2017-04-05 @ddalle: v1.0

See also:
abstractmethod CaseGetCurrentPhase()

Get the current phase number from the appropriate module

This function utilizes the cape.cfdx.case module, and so it must be copied to the definition for each solver’s control class.

Call:
>>> j = cntl.CaseGetCurrentPhase()
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

Outputs:
j: int | None

Phase number

Versions:

  • 2017-06-29 @ddalle: v1.0

  • 2023-07-06 @ddalle: v1.1; use CaseRunner

abstractmethod CheckBatch() → int

Check to see if we are running inside a batch job

This looks for environment variables to see if this is running inside a batch job. Currently supports slurm and PBS.

Call:
>>> q = cntl.CheckBatch()
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

Outputs:
jobid: int

0 if no batch environment was detected

Versions:

  • 2023-12-13 @dvicker: v1.0

  • 2023-12-18 @ddalle: v1.1; debug

abstractmethod CheckCase(i: int, force: bool = False, v: bool = False) → int | None

Check current status of case i

Because the file structure is different for each solver, some of this method may need customization. This customization, however, can be kept to the functions cape.cfdx.casecntl.GetCurrentIter() and cape.cfdx.cntl.Cntl.CheckNone().

Call:
>>> n = cntl.CheckCase(i, v=False)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

i: int

Index of the case to check (0-based)

v: True | {False}

Verbose flag; prints messages if n is None

Outputs:
n: int | None

Number of completed iterations or None if not set up

Versions:

  • 2014-09-27 @ddalle: v1.0

  • 2015-09-27 @ddalle: v2.0; generic

  • 2015-10-14 @ddalle: v2.1; no case req

  • 2017-02-22 @ddalle: v2.2; add verbose flag

  • 2023-11-06 @ddalle: v2.3; call setx_i(i)

abstractmethod CheckError(i: int) → bool

Check if a case has a failure

Call:
>>> q = cntl.CheckError(i)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

i: int

Run index

Outputs:
q: bool

If True, case has FAIL file in it

abstractmethod CheckNone(v: bool = False) → bool

Check if the current directory has the needed files to run

This function needs to be customized for each CFD solver so that it checks for the appropriate files.

Call:
>>> q = cntl.CheckNone(v=False)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Cape control interface

v: True | {False}

Verbose flag; prints message if q is True

Outputs:
q: `True | False`

Whether or not case is missing files

Versions:

  • 2015-09-27 @ddalle: v1.0

  • 2017-02-22 @ddalle: v1.1, verbosity option

abstractmethod CheckPhase(i: int, v: bool = False) → int | None

Check current phase number of run i

Call:
>>> n = cntl.CheckPhase(i, v=False)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

i: int

Index of the case to check (0-based)

v: True | {False}

Verbose flag; prints messages if n is None

Outputs:
j: int | None

Phase number

Versions:

  • 2017-06-29 @ddalle: v1.0

abstractmethod CheckRunning(i: int) → bool

Check if a case is currently running

Call:
>>> q = cntl.CheckRunning(i)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

i: int

Run index

Outputs:
q: bool

If True, case has RUNNING file in it

abstractmethod CheckUsedPhase(i: int, v: bool = False)

Check maximum phase number run at least once

Call:
>>> j, n = cntl.CheckUsedPhase(i, v=False)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

i: int

Index of the case to check (0-based)

v: True | {False}

Verbose flag; prints messages if n is None

Outputs:
j: int | None

Phase number

n: int | None

Maximum phase number

Versions:

  • 2017-06-29 @ddalle: v1.0

  • 2017-07-11 @ddalle: v1.1; verbosity option

  • 2025-03-02 @ddalle: v2.0; use CaseRunner

abstractmethod CheckZombie(i)

Check a case for ZOMBIE status

A running case is declared a zombie if none of the listed files (by default *.out) have been modified in the last 30 minutes. However, a case cannot be a zombie unless it contains a RUNNING file and returns True from CheckRunning().

Call:
>>> q = cntl.CheckZombie(i)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

i: int

Run index

Outputs:
q: bool

True if no listed files have been modified recently

Versions:

  • 2017-04-04 @ddalle: v1.0

  • 2021-01-25 @ddalle: v1.1; use cls._zombie_files

abstractmethod CleanCase(i: int, test: bool = False)

Perform --clean archiving on one case

There are no restrictions on the status of the case for this action.

Call:
>>> cntl.CleanCase(i, test=False)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Instance of control interface

i: int

Case index

test: True | {False}

Log file/folder actions but don’t actually delete/copy

abstractmethod CleanCases(**kw)

Clean a list of cases using Progress archive options only

Call:
>>> cntl.CleanCases(**kw)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Instance of control interface

Versions:

  • 2017-03-13 @ddalle: v1.0

  • 2024-09-18 @ddalle: v2.0

abstractmethod CountQueuedCases(I: list | None = None, u: str | None = None, **kw) → int

Count cases that have currently active PBS/Slurm jobs

Call:
>>> n = cntl.CountQueuedCases(I=None, u=None, **kw)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

I: {None} | list[int]

List of indices

u: str

User name (defaults to process username)

kw: dict

Other kwargs used to subset the run matrix

Outputs:
n: int

Number of running or queued jobs (not counting the job from which function is called, if applicable)

Versions:

  • 2024-01-12 @ddalle: v1.0

  • 2024-01-17 @ddalle: v1.1; check for this_job

  • 2025-05-01 @ddalle: v1.2; remove jobs kwarg

abstractmethod CountRunningCases(I: list, jobs: dict | None = None, u: str | None = None) → int

Count number of running cases via the batch system

Also print a status of the running jobs.

Call:
>>> n = cntl.CountRunningCases(I, jobs=None, u=None)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

I: list[int]

List of indices

jobs: dict

Information on each job by ID number

u: str

User name (defaults to process username)

Outputs:
n: int

Number of running or queued jobs

Versions:

  • 2023-12-08 @dvicker: v1.0

abstractmethod Defail(**kw)

Clean up any FAIL cases

Call:
>>> cntl.Defail(**kw)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Instance of overall control interface

extend: {True} | positive int

Extend phase j by extend nominal runs

j: {None} | int >= 0

Phase number

imax: {None} | int

Do not increase iteration number beyond imax

cons: list[str]

List of constraints

I: list[int]

List of indices

Versions:

  • 2026-07-23 @ddalle: v1.0

abstractmethod DeleteCase(i: int, **kw)

Delete a case

This function deletes a case’s PBS job and removes the entire directory. By default, the method prompts for user’s confirmation before deleting; set prompt to False to delete without prompt.

Call:
>>> n = cntl.DeleteCase(i)
Inputs:
cntl: cape.cfdx.cntl.Cntl

CAPE run matrix control instance

i: int

Index of the case to check (0-based)

prompt: {True} | False

Whether or not to prompt user before deleting case

Outputs:
n: 0 | 1

Number of folders deleted

Versions:

  • 2018-11-20 @ddalle: v1.0

abstractmethod Dezombie(**kw)

Clean up any ZOMBIE cases

Call:
>>> cntl.Dezombie(**kw)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Instance of overall control interface

extend: {True} | positive int

Extend phase j by extend nominal runs

j: {None} | int >= 0

Phase number

imax: {None} | int

Do not increase iteration number beyond imax

cons: list[str]

List of constraints

I: list[int]

List of indices

early: True | {False}

Reduce iteration count to current iter

Versions:

  • 2021-10-14 @ddalle: v1.0

  • 2026-02-25 @ddalle: v1.1; add early option

abstractmethod DisplayStatus(**kw)

Display current status for all cases

This prints case names, current iteration numbers, and so on. This is the function that is called when the user issues a system command like cape -c.

Call:
>>> cntl.DisplayStatus(j=False)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

j: bool

Whether or not to display job ID numbers

cons: list[str]

List of constraints like 'Mach<=0.5'

Versions:

  • 2014-10-04 @ddalle: v1.0

  • 2014-12-09 @ddalle: v2.0; --cons

  • 2025-06-20 @ddalle: v3.0; use caseloop_verbose()

abstractmethod ExecScript(**kw) → int

Execute a script in a given case folder

This function is the interface to command-line calls using the -e flag, such as pycart -e 'ls -lh'.

Call:
>>> ierr = cntl.ExecScript(i, cmd)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

i: int

Case index (0-based)

Outputs:
ierr: None | int

Exit status from the command

Versions:

  • 2016-08-26 @ddalle: v1.0

  • 2024-12-09 @jfdiaz3:v1.1

abstractmethod ExtendCase(i: int, n: int = 1, j: int | None = None, imax: int | None = None)

Add iterations to case i by repeating the last phase

Call:
>>> cntl.ExtendCase(i, n=1, j=None, imax=None)
Inputs:
cntl: cape.pyfun.cntl.Cntl

CAPE main control instance

i: int

Case index

n: {1} | positive int

Add n times steps to the total iteration count

j: {None} | int

Optional phase to extend

imax: {None} | nonnegative int

Use imax as the maximum iteration count

abstractmethod ExtendCases(**kw)

Extend one or more case by a number of iterations

By default, this applies to the final phase, but the phase number j can also be specified as input. The number of additional iterations is generally the nominal number of iterations that phase j would normally run.

Call:
>>> cntl.ExtendCases(cons=[], extend=1, **kw)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Instance of overall control interface

extend: {True} | positive int

Extend phase j by extend nominal runs

imax: {None} | int

Do not increase iteration number beyond imax

j, phase: {None} | int

Optional index of phase to extend

cons: list[str]

List of constraints

I: list[int]

List of indices

Versions:

  • 2016-12-12 @ddalle: v1.0

abstractmethod FilterUser(i: int, **kw) → bool

Determine if case i is assigned to current user

Call:
>>> q = cntl.FilterUser(i, **kw)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

i: int

Index of the case to check (0-based)

u, user: str

User name (default: executing process’s username) for comparing to run matrix

Outputs:
q: bool

Whether user is owner of case i

Versions:

2017-07-10 @ddalle: v1.0

abstractmethod GetCPUTime(i: int)

Read a CAPE-style core-hour file from a case

This function needs to be customized for each solver because it needs to know the name of the file in which timing data is saved. It defaults to cape_time.dat. Modifying this command is a one-line fix with a call to cape.cfdx.cntl.Cntl.GetCPUTimeFromFile() with the correct file name.

Call:
>>> CPUt = cntl.GetCPUTime(i)
Inputs:
cntl: cape.cfdx.cntl.Cntl

CAPE control interface

i: int

Case index

Outputs:
CPUt: float | None

Total core hours used in this job

Versions:

  • 2015-12-22 @ddalle: v1.0

  • 2016-08-30 @ddalle: v1.1; check for RUNNING

  • 2016-08-31 @ddalle: v1.2; use GetCPUTimeBoth

  • 2023-07-09 @ddalle: v2.0; use CaseRunner

abstractmethod GetCaseIndex(frun: str) → int | None

Get index of a case in the current run matrix

Call:
>>> i = cntl.GetCaseIndex(frun)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Cape control interface

frun: str

Name of case, must match exactly

Outputs:
i: int | None

Index of case with name frun in run matrix, if present

Versions:

  • 2024-08-15 @ddalle: v1.0

  • 2024-10-16 @ddalle: v1.1; move to RunMatrix

abstractmethod GetCaseMeshFolder(i: int) → str

Get relative path to folder where mesh should be copied

Call:
>>> fdir = cntl.GetCaseMeshFolder(i)
Inputs:
cntl: Cntl

CAPE run matrix control instance

i: {0} | int

Case index

Outputs:
fdir: str

Folder to copy file, relative to cntl.RootDir

Versions:

  • 2024-11-06 @ddalle: v1.0

abstractmethod GetCurrentIter(i: int, force: bool = False) → int

Get the current iteration number (using case)

This function utilizes the cape.cfdx.case module, and so it must be copied to the definition for each solver’s control class.

Call:
>>> n = cntl.GetCurrentIter(i, force=False)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

i: int

Index of the case to check (0-based)

force: True | {False}

Option to ignore cache

Outputs:
n: int

Number of completed iterations

Versions:

  • 2015-10-14 @ddalle: v1.0

  • 2023-07-07 @ddalle: v2.0; use CaseRunner

  • 2025-03-01 @ddalle: v3.0; add caching

abstractmethod GetIndices(**kw) → ndarray

Find cases using multiple conditions

Call:
>>> inds = cntl.GetIndices(**kw)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

status: {None} | "DONE" | str

Status filter

Outputs:
inds: :np.ndarray`[int]

List of case indices that meet all conditions

Versions:

  • 2026-08-13 @ddalle: v1.0 (was part of cntl.x

abstractmethod GetInputMeshFileNames() → list

Return the list of mesh files from file

Call:
>>> fnames = cntl.GetInputMeshFileNames()
Inputs:
cntl: Cntl

Run matrix control instance for unstructured-mesh solver

Outputs:
fnames: list[str]

List of file names read from root directory

Versions:

  • 2015-10-19 @ddalle: v1.0 (pyfun)

  • 2024-10-22 @ddalle: v1.0

abstractmethod GetLastIter(i: int) → int

Get minimum required iteration for a given case

Call:
>>> nIter = cntl.GetLastIter(i)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Cape control interface

i: int

Run index

Outputs:
nIter: int

Number of iterations required for case i

Versions:

  • 2014-10-03 @ddalle: v1.0

abstractmethod GetPBSJobID(i: int) → str | None

Get PBS job number if one exists

Call:
>>> jobID = cntl.GetPBSJobID(i)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

i: int

Run index

Outputs:
jobID: None | str

Most recent PBS/Slurm job name, if able

Versions:

  • 2014-10-06 @ddalle: v1.0

  • 2024-01-12 @ddalle: v1.1; remove CheckCase() for speed

abstractmethod GetPBSName(i: int) → str

Get PBS name for a given case

Call:
>>> lbl = cntl.GetPBSName(i, pre=None)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

i: int

Run index

pre: {None} | str

Prefix for PBS job name

Outputs:
lbl: str

Short name for the PBS job, visile via qstat

Versions:

  • 2014-09-30 @ddalle: v1.0

  • 2016-12-20 @ddalle: v1.1, moved to x

abstractmethod GetPhaseBreaks() → list

Get expected iteration numbers at phase breaks

This fills in 0 entries in RunControl ‣ PhaseIters and returns the filled-out list.

Call:
>>> PI = cntl.GetPhaseBreaks()
Inputs:
cntl: cape.cfdx.cntl.Cntl

Cape control interface

Outputs:
PI: list[int]

Min iteration counts for each phase

Versions:

  • 2017-04-12 @ddalle: v1.0

abstractmethod GetProcessedMeshFileNames() → list

Return the list of mesh files that are written

Call:
>>> fname = cntl.GetProcessedMeshFileNames()
Inputs:
cntl: Cntl

Run matrix control instance for unstructured-mesh solver

Outputs:
fname: list[str]

List of file names written to case folders

Versions:

  • 2015-10-19 @ddalle: v1.0

abstractmethod GetProjectRootName(j: int = 0) → str

Get the project root name

The JSON file overrides the value from the namelist file if appropriate

Call:
>>> name = cntl.GetProjectName(j=0)
Inputs:
cntl: Cntl

CAPE run matrix control instance

j: {0} | int

Phase number

Outputs:
name: str

Project root name

Versions:

  • 2015-10-18 @ddalle: v1.0 (pyfun)

  • 2023-06-15 @ddalle: v1.1; cleaner logic

  • 2024-10-22 @ddalle: v2.0; moved to cfdx

  • 2025-07-15 @ddalle: v2.1; move into CntlBase

abstractmethod GetSurfCT_ExitArea(key: str, i: int, comp: str | None = None) → float

Get exit area for a CT trajectory key

This can use either the area ratio (if available) or calculate from the exit Mach number. The input area is determined from the component ID. If using the exit Mach number M2, the input Mach number M1 is also needed. The relationship between area ratio and exit Mach is given below.

\[\begin{split}\\frac{A_2}{A_1} = \\frac{M_1}{M_2}\\left( \\frac{1+\\frac{\\gamma-1}{2}M_2^2}{ 1+\\frac{\\gamma-1}{2}M_1^2} \\right) ^ {\\frac{1}{2}\\frac{\\gamma+1}{\\gamma-1}}\end{split}\]
Call:
>>> A2 = cntl.GetSurfCT_ExitArea(key, i)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

key: str

Name of trajectory key to check

i: int

Case number

comp: {None} | str

Name of component for which to get BCs

Outputs:
A2: list (float)

Exit area for each component referenced by this key

Versions:

  • 2016-04-13 @ddalle: v1.0

abstractmethod GetSurfCT_ExitMach(key: str, i: int, comp: str | None = None) → float

Get exit Mach number for a CT trajectory key

This can use either the "ExitMach" parameter (if available) or calculate from the area ratio. If using the area ratio, the input Mach number is also needed. The relationship between area ratio and exit Mach is given below.

\[\frac{A_2}{A_1} = \frac{M_1}{M_2}\left( \frac{1+\frac{\gamma-1}{2}M_2^2}{ 1+\frac{\gamma-1}{2}M_1^2} \right) ^ {\frac{1}{2}\frac{\gamma+1}{\gamma-1}}\]
Call:
>>> M2 = cntl.GetSurfCT_ExitMach(key, i)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

key: str

Name of trajectory key to check

i: int

Case number

comp: {None} | str

Name of component for which to get BCs

Outputs:
M2: float

Exit Mach number

Versions:

  • 2016-04-13 @ddalle: v1.0

abstractmethod GetSurfCT_RefArea(key: str, i: int) → float

Get reference area for surface CT trajectory key

This references the "RefArea" parameter of the definition for the run matrix variable key. The user should set this parameter to 1.0 if thrust inputs are given as dimensional values.

If this is None, it returns the global reference area; if it is a string the reference area comes from the reference area for that component using cntl.opts.get_RefArea(comp).

Call:
>>> Aref = cntl.GetSurfCT_RefArea(key, i)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

key: str

Name of trajectory key to check

i: int

Case number

Outputs:
Aref: float

Reference area for normalizing thrust coefficients

Versions:

  • 2016-04-13 @ddalle: v1.0

abstractmethod ImportModules()

Import user-defined modules if specified in the options

All modules from the "Modules" global option of the JSON file (cntl.opts["Modules"]) will be imported and saved as attributes of cntl. For example, if the user wants to use a module called dac3, it will be imported as cntl.dac3. A noncomprehensive list of disallowed module names is below.

DataBook, RootDir, jobs, opts, tri, x

The name of any method of this class is also disallowed. However, if the user wishes to import a module whose name is disallowed, he/she can use a dictionary to specify a different name to import the module as. For example, the user may import a module called tri as mytri using the following JSON syntax.

"Modules": [{"tri": "mytri"}]
Call:
>>> cntl.ImportModules()
Inputs:
cntl: cape.cfdx.cntl.Cntl

Instance of Cape control interface

Versions:

  • 2014-10-08 @ddalle: v1.0 (pycart)

  • 2015-09-20 @ddalle: v1.0

  • 2022-04-12 @ddalle: v2.0; use self.modules

abstractmethod InitFunction()

Run one or more functions a “initialization” hook

This calls the function(s) in the global "InitFunction" option from the JSON file. These functions must take cntl as an input, and they are usually from a module imported via the "Modules" option. See the following example:

"Modules": ["testmod"],
"InitFunction": ["testmod.testfunc"]

This leads CAPE to call testmod.testfunc(cntl).

Call:
>>> cntl.InitFunction()
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall control interface

Versions:

  • 2017-04-04 @ddalle: v1.0

  • 2022-04-12 @ddalle: v2.0; use _exec_funclist()

abstractmethod MarkERROR(**kw)

Mark one or more cases as ERROR and rewrite matrix

Call:
>>> cntl.MarkERROR(**kw)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

I: list[int]

List of indices

cons: list[str]

List of constraints like 'Mach<=0.5'

flag: {"E"} | "e" | "ERROR" | "$E"

Marker to use to denote status

Versions:

  • 2019-06-14 @ddalle: v1.0

abstractmethod MarkPASS(**kw)

Mark one or more cases as PASS and rewrite matrix

Call:
>>> cntl.MarkPASS(**kw)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

I: list[int]

List of indices

cons: list[str]

List of constraints like 'Mach<=0.5'

flag: {"p"} | "P" | "PASS" | "$p"

Marker to use to denote status

Versions:

  • 2019-06-14 @ddalle: v1.0

abstractmethod PrepareCase(i: int)

Prepare case for running if necessary

This function creates the folder, copies mesh files, and saves settings and input files. All of these tasks are completed only if they have not already been completed, and it needs to be customized for each CFD solver.

Call:
>>> cntl.PrepareCase(i)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

i: int

Index of case to analyze

Versions:

  • 2014-09-30 @ddalle: v1.0

  • 2015-09-27 @ddalle: v2.0, convert to template

abstractmethod PrepareConfig(i: int)

Apply rotations, translations, etc. to Config.xml

Call:
>>> cntl.PrepareConfig(i)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

i: int

Case index

Versions:

  • 2016-08-23 @ddalle: v1.0

abstractmethod PrepareConfigFunction(key: str, i: int)

Apply special configuration modification function for a case

Call:
>>> cntl.PrepareConfigFunction(key, i)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

key: str

Name of key

i: int

Index of the case to check (0-based)

Versions:

  • 2016-08-23 @ddalle: v1.0

  • 2022-04-13 @ddalle: v2.0; exec_modfunction()

abstractmethod PrepareConfigRotation(key: str, i: int)

Apply a rotation to a component or components

Call:
>>> cntl.PrepareConfigRotation(key, i)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

key: str

Name of the trajectory key

i: int

Index of the case to check (0-based)

Versions:

  • 2016-08-23 @ddalle: v1.0

abstractmethod PrepareConfigTranslation(key: str, i: int)

Apply a translation to a component or components

Call:
>>> cntl.PrepareConfigTranslation(key, i)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

key: str

Name of variable from which to get value

i: int

Index of the case to check (0-based)

Versions:

  • 2016-08-23 @ddalle: v1.0

abstractmethod PrepareMesh(i: int)

Prepare the mesh for case i if necessary

Call:
>>> cntl.PrepareMesh(i)
Inputs:
cntl: cape.pyfun.cntl.Cntl

Instance of control class

i: int

Case index

Versions:

  • 2015-10-19 @ddalle: v1.0 (pyfun)

  • 2024-11-04 @ddalle: v1.3 (pyfun)

  • 2024-11-07 @ddalle: v1.0

abstractmethod PrepareMeshFiles(i: int) → int

Copy main unstructured mesh files to case folder

Call:
>>> n = cntl.PrepareMeshFiles(i)
Inputs:
cntl: Cntl

CAPE run matrix control instance

i: int

Case index

Outputs:
n: int

Number of files copied

Versions:

  • 2024-11-05 @ddalle: v1.0

  • 2025-04-02 @ddalle: v1.1; add LinkMesh option

abstractmethod PrepareMeshTri(i: int)

Prepare surface triangulation for AFLR3, if appropriate

Call:
>>> cntl.PrepareMeshTri(i)
Inputs:
cntl: Cntl

CAPE run matrix control instance

i: int

Case index

Versions:

  • 2024-11-01 @ddalle: v1.0 (from pyfun’s PrepareMesh())

abstractmethod PrepareMeshUnstructured(i: int)

Prepare the mesh for case i if necessary

Call:
>>> cntl.PrepareMeshUnstructured(i)
Inputs:
cntl: cape.pyfun.cntl.Cntl

Instance of control class

i: int

Case index

Versions:

  • 2015-10-19 @ddalle: v1.0 (pyfun)

  • 2024-11-04 @ddalle: v1.3 (pyfun)

  • 2024-11-07 @ddalle: v1.0

  • 2025-07-15 @ddalle: v1.1; name change

abstractmethod PrepareMeshWarmStart(i: int) → bool

Prepare WarmStart files for case, if appropriate

Call:
>>> warmstart = cntl.PrepareMeshWarmStart(i)
Inputs:
cntl: Cntl

Name of main CAPE input (JSON) file

i: int

Case index

Outputs:
warmstart: bool

Whether or not case was warm-started

Versions:

  • 2024-11-04 @ddalle: v1.0

abstractmethod PreparePoints(i: int)

Calculate the value of each named "Point" for case i

Call:
>>> x = cntl.PreparePoints(i)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

i: int

Case index

Versions:

  • 2022-03-07 @ddalle: v1.0

abstractmethod PreparePointsRotation(key: str, i: int)

Apply a rotation to named config points for one col

Call:
>>> cntl.PreparePointsRotation(key, i)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

key: str

Name of the trajectory key

i: int

Index of the case to check (0-based)

Versions:

  • 2022-03-07 @ddalle: v1.0

abstractmethod PreparePointsTranslation(key: str, i: int)

Apply a translation to named config points for one col

Call:
>>> cntl.PreparePointsTranslation(key, i)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

key: str

Name of the trajectory key

i: int

Case index

Versions:

  • 2022-03-07 @ddalle: v1.0

abstractmethod PrepareTri(i: int)

Rotate/translate/etc. triangulation for given case

Call:
>>> cntl.PrepareTri(i)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

i: int

Index of the case to check (0-based)

Versions:

  • 2014-12-01 @ddalle: v1.0

  • 2016-04-05 @ddalle: v1.1, pycart -> cape

abstractmethod PrepareTriFunction(key: str, i: int)

Apply special surf modification function for a case

Call:
>>> cntl.PrepareTriFunction(key, i)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

key: str

Name of key

i: int

Index of the case to check (0-based)

Versions:

  • 2015-09-11 @ddalle: v1.0

  • 2016-04-05 @ddalle: v1.1, pycart -> cape

  • 2022-04-13 @ddalle: v2.0; exec_modfunction()

abstractmethod PrepareTriRotation(key: str, i: int)

Apply a rotation to a component or components

Call:
>>> cntl.PrepareTriRotation(key, i)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

key: str

Run matrix for rotation defn’

i: int

Index of the case to check (0-based)

Versions:

  • 2015-09-11 @ddalle: v1.0

  • 2016-04-05 @ddalle: v1.1, pycart -> cape

abstractmethod PrepareTriTranslation(key: str, i: int)

Apply a translation to a component or components

Call:
>>> cntl.PrepareTriTranslation(key, i)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

key: str

Run matrix key for translation def’n

i: int

Index of the case to check (0-based)

Versions:

  • 2015-09-11 @ddalle: v1.0

  • 2016-04-05 @ddalle: v1.1, pycart -> cape

abstractmethod ReadCaseRunner(i: int) → CaseRunnerBase

Read CaseRunner into slot

Call:
>>> runner = cntl.ReadCaseRunner(i)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

i: int

Index of the case to check (0-based)

Outputs:
runner: CaseRunner

Controller to run one case of solver

abstractmethod ReadConfig(f=False) → ConfigXML | ConfigJSON

Read Config.xml or other surf configuration format

Call:
>>> cntl.ReadConfig(f=False)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

f: True | {False}

Option to reread existing cntl.config

Versions:

  • 2016-06-10 @ddalle: v1.0

  • 2016-10-21 @ddalle: v2.0, added Config.json

  • 2020-09-01 @ddalle: v2.1, add f kwarg

abstractmethod ReadFolderCaseRunner(fdir: str) → CaseRunnerBase

Read a CaseRunner from a folder by name

Call:
>>> runner = cntl.ReadFolderCaseRunner(fdir)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

fdir: str

Folder of case to read from

Outputs:
runner: CaseRunner

Controller to run one case of solver

abstractmethod ReadMapBC(j: int = 0, q: bool = True) → MapBCFile | None

Read the FUN3D boundary condition map

Call:
>>> cntl.ReadMapBC(q=True)
Inputs:
cntl: cape.pyfun.cntl.Cntl

Instance of the pyFun control class

q: {True} | False

Whether or not to read to MapBC, else MapBC0

Versions:

  • 2016-03-30 @ddalle: v1.0

abstractmethod ReadReport(rep: str)

Read a report interface

Call:
>>> rep = cntl.ReadReport(rep)
Inputs:
cntl: cape.cfdx.cntl.Cntl

CAPE main control instance

rep: str

Name of report

Outputs:
rep: cape.cfdx.report.Report

Report interface

Versions:

  • 2018-10-19 @ddalle: Version 1.0

abstractmethod ReadTri()

Read initial triangulation file(s)

Call:
>>> cntl.ReadTri()
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

Versions:

  • 2014-08-30 @ddalle: v1.0

  • 2026-05-22 @ddalle: v1.1; check which files were read

abstractmethod RevertOptions()

Revert to cntl.opts0 as working options

Call:
>>> cntl.ResetOptions()
Inputs:
cntl: Cntl

CAPE solver control interface

Versions:

  • 2021-07-31 @ddalle: v1.0

abstractmethod SaveOptions()

Copy cntl.opts and store it as cntl.opts0

Call:
>>> cntl.SaveOptions()
Inputs:
cntl: Cntl

CAPE solver control interface

Versions:

  • 2021-07-31 @ddalle: v1.0

abstractmethod SkeletonCase(i: int, test: bool = False)

Perform --skeleton archiving on one case

There are no restrictions on the status of the case for this action.

Call:
>>> cntl.SkeletonCase(i, test=False)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Instance of control interface

i: int

Case index

test: True | {False}

Log file/folder actions but don’t actually delete/copy

Versions:

  • 2024-09-18 @ddalle: v1.0

abstractmethod SkeletonCases(**kw)

Archive completed cases and delete all but a few files

Call:
>>> cntl.SkeletonCases()
>>> cntl.SkeletonCases(cons=[], **kw)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Instance of overall control interface

cons: list[str]

List of constraints

I: list[int]

List of indices

Versions:

  • 2016-12-14 @ddalle: v1.0

  • 2024-09-19 @ddalle: v2.0

abstractmethod StartCase(i: int)

Start a case by either submitting it or running it

This function checks whether or not a case is submittable. If so, the case is submitted via cape.cfdx.queue.pqsub(), and otherwise the case is started using a system call.

Before starting case, this function checks the folder using cape.cfdx.cntl.CheckCase(); if this function returns None, the case is not started. Actual starting of the case is done using CaseStartCase(), which has a specific version for each CFD solver.

Call:
>>> pbs = cntl.StartCase(i)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

i: int

Index of the case to check (0-based)

Outputs:
pbs: int | None

PBS job ID if submitted successfully

abstractmethod StopCase(i: int)

Stop a case if running

This function deletes a case’s PBS job and removes the RUNNING file if it exists.

Call:
>>> cntl.StopCase(i)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Cape control interface

i: int

Index of the case to check (0-based)

SubmitJobs(**kw)

Check jobs and prepare or submit jobs if necessary

Call:
>>> cntl.SubmitJobs(**kw)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

c: :True | {False}

If True, only display status; do not submit new jobs

j: bool

Whether or not to display job ID numbers

n: int

Maximum number of jobs to submit

I: list[int]

List of indices

cons: list[str]

List of constraints like 'Mach<=0.5'

Versions:

  • 2014-10-05 @ddalle: v1.0

  • 2014-12-09 @ddalle: v2.0, --cons

  • 2021-08-01 @ddalle: v2.1, save/revert options

  • 2023-05-17 @ddalle: v2.2, opts.setx_i()

abstractmethod UnarchiveCases(**kw)

Unarchive a list of cases

Call:
>>> cntl.UnarchiveCases(**kw)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Instance of control interface

Versions:

  • 2017-03-13 @ddalle: v1.0

  • 2023-10-20 @ddalle: v1.1; arbitrary-depth frun

  • 2024-09-20 @ddalle: v2.0; use CaseArchivist

abstractmethod UnmarkCase(**kw)

Remove PASS or ERROR marking from one or more cases

Call:
>>> cntl.UnmarkCase(**kw)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

I: list[int]

List of indices

cons: list[str]

List of constraints like 'Mach<=0.5'

Versions:

  • 2019-06-14 @ddalle: v1.0

abstractmethod UpdateReport(**kw)

Update a report

Call:
>>> cntl.UpdateReport(**kw)
Inputs:
cntl: cape.cfdx.cntl.Cntl

CAPE main control instance

report: {True} | str

Name of report (or first report)

I: {None} | np.ndarray[int]

Indices to report

Versions:

  • 2025-08-25 @ddalle: v1.0

abstractmethod WriteCaseJSON(i: int, rc: dict | None = None)

Write JSON file with run control settings for case i

Call:
>>> cntl.WriteCaseJSON(i, rc=None)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Generic control class

i: int

Run index

rc: {None} | dict

If specified, write specified “RunControl” options

Versions:

  • 2015-10-19 @ddalle: v1.0

  • 2023-03-31 @ddalle: v2.0; manual options input

  • 2023-08-29 @ddalle: v2.1; call sample_dict()

  • 2024-08-24 @ddalle: v2.2; use CaseRunner

  • 2025-01-23 @ddalle: v2.3; eliminate Arvhive settings

abstractmethod WriteConditionsJSON(i: int)

Write JSON file with run matrix settings for case i

Call:
>>> cntl.WriteConditionsJSON(i, rc=None)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Generic control class

i: int

Run index

rc: {None} | dict

If specified, write specified “RunControl” options

Versions:

  • 2021-09-08 @ddalle: v1.0

abstractmethod WritePBS(i: int)

Write the PBS script(s) for a given case

Call:
>>> cntl.WritePBS(i)
Inputs:
cntl: cape.pyfun.cntl.Cntl

CAPE main control instance

i: int

Run index

Versions:

  • 2014-10-19 @ddalle: v1.0

  • 2023-10-20 @ddalle: v1.1; arbitrary frun depth

  • 2024-08-01 @ddalle: v2.0; solver-agnostic

abstractmethod WritePBSHeader(fp: IOBase, i: int | None = None, j: int = 0, typ: str | None = None, wd: str | None = None)

Write common part of PBS or Slurm script

Call:
>>> cntl.WritePBSHeader(fp, i=None, j=0, typ=None, wd=None)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

fp: IOBase

Open file handle

i: {None} | int

Case index (ignore if None); used for PBS job name

j: int

Phase number

typ: {None} | "batch" | "post"

Group of PBS options to use

wd: {None} | str

Folder to enter when starting the job

Versions:

  • 2015-09-30 @ddalle: v1.0, fork WritePBS()

  • 2016-09-25 @ddalle: v1.1, “BatchPBS”

  • 2016-12-20 @ddalle: v1.2

    • Consolidated to opts

    • Added prefix

  • 2024-08-15 @ddalle: v1.3

    • Use cntl.opts.name as prefix

    • User-controlled job name length, longer default

abstractmethod abspath(fname: str) → str

Absolutize a file name

Call:
>>> fabs = cntl.abspath(fname)
Inputs:
cntl: Cntl

CAPE main control instance

fname: str

A file name

Outputs:
fabs: str

Absolute file path

Versions:

  • 2021-10-25 @ddalle: v1.0

  • 2025-03-26 @ddalle: v1.1; Windows compatibility fix

abstractmethod apply_setter(opt: str, v: Any)

Change an option by name of setter method

Call:
>>> cntl.apply_setter(opt, v)
Inputs:
cntl: Cntl

CAPE solver control interface

opt: str

Name of option, e.g. "PBS_q" will cause the function to look for cntl.opts.set_PBS_q()

v: any

Value to set the option to

Versions:

  • 2026-05-23 @ddalle: v1.0

abstractmethod caseloop(casefunc: Callable, **kw) → list

Loop through cases and execute function for each case

Call:
>>> cases = cntl.caseloop(casefun, **kw)
Inputs:
cntl: cape.cfdx.cntl.Cntl

CAPE run matrix control instance

indent: {0} | int

Number of spaces to indent each case name

Outputs:
cases: list[tuple]

List of (case index, case name) for each case

Versions:

  • 2025-02-12 @ddalle: v1.0

  • 2026-08-07 @ddalle: v1.1; add output

abstractmethod caseloop_verbose(casefunc: Callable | None = None, **kw) → int

Loop through cases and produce verbose table

Call:
>>> n = cntl.caseloop_verbose(casefunc, **kw)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

casefunc: {None} | Callable

Optional function to run in each case folder

I: {None} | np.ndarray[int]

Case indices

Outputs:
n: int

Number of cases started/submitted

Versions:

  • 2025-06-19 @ddalle: v1.0

abstractmethod check_case_job(i: int, active: bool = True) → str

Get queue status of the PBS/Slurm job from case i

Call:
>>> s = cntl.check_case_job(i, active=True)
Inputs:
cntl: Cntl

Controller for one CAPE run matrix

i: int

Case index

active: {True} | False

Whether or not to allow new calls to qstat

Outputs:
s: str

Job queue status

  • -: not in queue

  • Q: job queued (not running)

  • R: job running

  • H: job held

  • E: job error status

Versions:

  • 2025-05-04 @ddalle: v1.0

abstractmethod check_case_status(i: int, active: bool = True, force: bool = False) → str

Get queue status of the PBS/Slurm job from case i

Call:
>>> sts = cntl.check_case_job(i, active=True)
Inputs:
cntl: Cntl

Controller for one CAPE run matrix

i: int

Case index

active: {True} | False

Whether or not to allow new calls to qstat

force: True | {False}

Option to override cache and reevaluate

Outputs:
sts: str

Case status

  • ---: folder does not exist

  • INCOMP: case incomplete but [partially] set up

  • QUEUE: case waiting in PBS/Slurm queue

  • RUNNING: case currently running

  • DONE: all phases and iterations complete

  • PASS: DONE and marked by user as passed

  • ZOMBIE: seems running; but no recent file updates

  • PASS*: case marked by user but not DONE

  • ERROR: case marked as error

  • FAIL: case failed but not marked by user

Versions:

  • 2025-05-04 @ddalle: v1.0

  • 2026-08-13 @ddalle: v1.1; use cache

abstractmethod copy_files(i: int)

Copy files from Mesh section

This applies to both CopyFiles and CopyAsFiles in the Mesh section. The former will copy a given file into the run folder for case i using the base name of the original (source) file. Using

"Mesh": {
    "CopyAsFiles": {
        "inputs/mesh-config02.ugrid": "mesh.ugrid"
    }
}

will copy the file inputs/mesh-config02.ugrid into the run folder but name it mesh.ugrid there.

Call:
>>> cntl.copy_files(i)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

i: int

Case index

Versions:

  • 2025-03-26 @ddalle: v1.0

  • 2025-09-19 @ddalle: v1.1; CopyAsFiles

abstractmethod declare_early_exit_case(i: int)

Change PhaseIters to current iteration for one case

Call:
>>> cntl.declare_early_exit_case(i)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Instance of overall control interface

i: int

Case index

Versions:

  • 2026-02-25 @ddalle: v1.0

abstractmethod edit_json(txt: str | None = None, opts: dict | None = None, fjson: str | None = None)

Edit JSON settings based on CLI

Call:
>>> cntl.edit_json(txt=None, opts=None, fjson=None)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

txt: {None} | str

JSON-encoded text to apply

opts: {None} | dict

Python object to apply to cntl.opts

fjson: {None} | str

Name of JSON file to apply to cntl.opts

Versions:

  • 2026-06-08 @ddalle: v1.0

abstractmethod exec_cntl_function_dict(funcspec: dict)

Execute a Cntl function, accessing user-specified modules

Call:
>>> v = cntl.exec_cntl_function_dict(funcspec)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall control interface

funcspec: dict

Function opts parsed by UserFuncOpts

Outputs:
v: any

Output from execution of function

Versions:

  • 2025-03-28 @ddalle: v1.0

abstractmethod exec_cntlfunction(funcspec: str | dict) → Any

Execute a Cntl function, accessing user-specified modules

Call:
>>> v = cntl.exec_cntlfunction(funcname)
>>> v = cntl.exec_cntlfunction(funcspec)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall control interface

funcname: str

Name of function to execute, e.g. "mymod.myfunc"

funcspec: dict

Function opts parsed by UserFuncOpts

Outputs:
v: any

Output from execution of function

Versions:

  • 2025-03-28 @ddalle: v1.0

abstractmethod exec_cntlfunction_str(funcname: str) → Any

Execute a function from cntl.modules

Call:
>>> v = cntl.exec_modfunction(funcname, a, kw, name=None)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall control interface

funcname: str

Name of function to execute, e.g. "mymod.myfunc"

Outputs:
v: any

Output from execution of function

Versions:

  • 2025-03-28 @ddalle: v1.0

abstractmethod exec_modfunction(funcname: str, a: tuple | list | None = None, kw: dict | None = None, name: str | None = None) → Any

Execute a function from cntl.modules

Call:
>>> v = cntl.exec_modfunction(funcname, a, kw, name=None)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall control interface

funcname: str

Name of function to execute, e.g. "mymod.myfunc"

a: {None} | tuple

Positional arguments to called function

kw: {None} | dict

Keyworkd arguments to called function

name: {None} | str

Hook name to use in status update

Outputs:
v: any

Output from execution of function

Versions:

  • 2022-04-12 @ddalle: v1.0

  • 2025-03-28 @ddalle: v1.1; improve error messages

abstractmethod find_large_cases(cutoff: float = '100MB', **kw) → list

Find large case folders

Call:
>>> fruns = cntl.find_large_cases(cutoff='100MB', **kw)
Inputs:
cutoff: {"100MB"} | str | float

Cutoff for “large”, string or raw number of bytes

kw: dict

Options used to subset the run matrix

Outputs:
fruns: list[str]

List of “large” cases by total folder size

Versions:

  • 2025-09-25 @ddalle: v1.0

abstractmethod genr8_opts_hash() → str

Generate hash from current options dictionary

Call:
>>> h = cntl.genr8_opts_hash()
Outputs:
h: str

Hash generated from options dictionary

Versions:

  • 2026-06-10 @ddalle: v1.0

abstractmethod genr8_opts_jsonl() → str

Generate single-line JSON string from current options

Call:
>>> jsonl = cntl.genr8_opts_jsonl()
Outputs:
jsonl: str

Canonical single-line JSON representation of options

Versions:

  • 2026-06-10 @ddalle: v1.0

abstractmethod get_databook_comp_nmin(comp: str) → int

Calculate the min iterations required for a DataBook comp

Call:
>>> n = cntl.get_databook_comp_nmin(comp)
Inputs:
cntl: cape.cfdx.cntl.Cntl

CAPE run matrix control instance

comp: str

Name of DataBook component

Outputs:
n: int

Iteration number

Versions:

  • 2025-07-29 @ddalle: v1.0

abstractmethod get_dir_files(i: int) → int

Get total number of files in case folder

Call:
>>> nfiles = cntl.get_dir_files(i)
Inputs:
cutoff: {"100MB"} | str | float

Cutoff for “large”, string or raw number of bytes

i: int

Case index

Outputs:
nfiles: int

Total number of files

Verions:

  • 2025-09-25 @ddalle: v1.0

abstractmethod get_dir_size(i: int) → int

Get total size of case folder

Call:
>>> frun = cntl.get_dir_size(i)
Inputs:
cutoff: {"100MB"} | str | float

Cutoff for “large”, string or raw number of bytes

i: int

Case index

Outputs:
fsize: int

Number of bytes in folder

Verions:

  • 2025-09-25 @ddalle: v1.0

abstractmethod get_edit_allowlist() → list

Get list of files, rel. to root dir, the agent may edit

Call:
>>> flist = cntl.get_edit_allowlist()
Inputs:
cntl: Cntl

Overall CAPE run matrix control instance

Outputs:
flist: list[str]

Names of files, relative to root dir, that agentic tools are allowed to edit

abstractmethod get_funcname(frame: int = 1) → str

Get name of calling function, mostly for log messages

Call:
>>> funcname = runner.get_funcname(frame=1)
Inputs:
cntl: Cntl

CAPE run matrix control instance

frame: {1} | int

Depth of function to seek title of

Outputs:
funcname: str

Name of calling function

Versions:

  • 2025-04-30 @ddalle

abstractmethod get_log_level() → int

Get the current logging level

Call:
>>> loglvl = cntl.get_log_level()
Outputs:
loglvl: int

Logging level (e.g., 10 for DEBUG, 20 for INFO)

Versions:

  • 2026-06-10 @ddalle: v1.0

abstractmethod get_logger() → CntlLogger

Get current logger and/or initialize one

Call:
>>> logger = cntl.get_logger()
Inputs:
cntl: Cntl

CAPE run matrix control instance

Outputs:
logger: CntlLogger

Run matrix logger instance

Versions:

  • 2025-04-30 @ddalle: v1.0

abstractmethod get_opts_hash(f: bool = False) → str

Get hash of current options, with optional recalculation

Call:
>>> h = cntl.get_opts_hash(f=False)
Inputs:
f: True | {False}

Option to force recalculation

Outputs:
h: str

Hash of current options

Versions:

  • 2026-06-10 @ddalle: v1.0

abstractmethod get_opts_jsonl(f: bool = False) → str

Get current options as a single-line JSON string

Call:
>>> jsonl = cntl.get_opts_jsonl(f=False)
Inputs:
f: True | {False}

Option to force recalculation

Outputs:
jsonl: str

Single-line JSON representation of options

Versions:

  • 2026-06-10 @ddalle: v1.0

abstractmethod get_pbs_jobs(force: bool = False, u: str | None = None, server: str | None = None, qstat: bool = True) → dict

Get dictionary of current jobs active by one user

Call:
>>> jobs = cntl.get_pbs_jobs(force=False, **kw)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

force: True | {False}

Query current queue even if cntl.jobs exists

u: {None} | str

User name (defaults to process username)

server: {None} | str

Name of non-default PBS/Slurm server

Outputs:
jobs: dict

Information on each job by ID number

Versions:

  • 2024-01-12 @ddalle: v1.0

  • 2024-08-22 @ddalle: v1.1; add qstat option

  • 2025-05-01 @ddalle: v1.2; simplify flow

abstractmethod get_phase_niter(i: int, j: int) → int

Get number of steps for one call of phase j in case i

Call:
>>> niter = cntl.get_Phase_inter(i, j)
Inputs:
cntl: cape.pyfun.cntl.Cntl

CAPE main control instance

i: int

Case index

j: int

Phase number

Outputs:
niter: int

Number of iterations for phase j; may be specific to case i

Versions:

  • 2025-08-11 @ddalle: v1.0

abstractmethod get_report_comps(rep: str | None = None) → list

Get list of components and coefficients in given report

Call:
>>> comps = cntl.get_report_comps(rep=None)
Inputs:
cntl: cape.cfdx.cntl.Cntl

CAPE main control instance

rep: {None} | str

Name of report

Outputs:
comps: list[str, str]

List of (comp, coeff) from each "PlotCoeff" subfigure included in the report rep

abstractmethod get_runmatrix_keys(keyname: str | None = None) → dict

Get main properties of some run matrix keys

Call:
>>> props = cntl.get_runmatrix_keys(keyname=None)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Cape control interface

keyname: {None} | str

Wild-card pattern that keys must match

Outputs:
props: dict

Type and DType for matching run matrix keys

abstractmethod get_transformation_matrix(topts: dict, i: int) → ndarray | None

Calculate rotation matrix for a databook transformation

Call:
>>> mat = cntl.get_transformation_matrix(topts, i)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

topts: dict

Definitions for transformation

i: int

Case number

Outputs:
mat: None | np.ndarray[float]

Rotation matrix if topts is a rotation

Versions:

  • 2025-01-30 @ddalle: v1.0

abstractmethod getval(opt: str, i: int) → Any

Get run matrix or case status value for one case

Call:
>>> v = cntl.getval(opt, i)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

opt: str

Name of option or run matrix key

i: int

Case index

Outputs:
v: Any

Value of option opt for case i

Versions:

  • 2025-06-16 @ddalle: v1.0

abstractmethod getvalstr(opt: str, i: int) → str

Get value of run matrix variable as string

Call:
>>> txt = cntl.getvalstr(opt, i)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

opt: str

Name of option or run matrix key

i: int

Case index

Outputs:
txt: str

Text of value of option opt for case i

Versions:

  • 2025-06-16 @ddalle: v1.0

abstractmethod import_module(modname: str)

Import a module by name, if possible

Call:
>>> mod = cntl.import_module(modname)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall control interface

modname: str

Name of module to import

Outputs:
mod: module

Python module

Versions:

  • 2025-03-28 @ddalle: v1.0

abstractmethod init_post()

Do py{x} specific initialization actions

Call:
>>> cntl.init_post()
Inputs:
cntl: cape.cfdx.cntl.Cntl

CAPE run matrix control instance

Versions:

  • 2023-05-31 @ddalle: v1.0

abstractmethod inspect_json(jq: str = '.', maxdepth: int | None = None) → Any

Inspect an item or subset of the expanded options

This uses a simple subset of the path syntax used by the common system utility jq -r; supported syntax is:

  • .: the entire options

  • .KEY: one key from a dict

  • ."KEY": dict key containing spaces or other specials

  • .["KEY"]: dict key using string syntax

  • .[I] or .KEY[I]: index into a list

  • .KEY[I1:I2]: slice of a list

If maxdepth is given, any dicts deeper than maxdepth levels (relative to the selected item) are replaced by {} in the output.

Call:
>>> v = cntl.inspect_json(jq=".", maxdepth=None)
Inputs:
cntl: Cntl

Instance of CAPE control interface

jq: {"."} | str

Path to item to retrieve, using jq path syntax

maxdepth: {None} | int

Maximum depth of dicts to include in output

Outputs:
v: any

Selected item or subset of cntl.opts

Examples:
>>> cntl.inspect_json(".PBS.select")
10
>>> cntl.inspect_json(".PBS", maxdepth=0)
{}
Versions:

  • 2026-08-30: v1.0

Link files from Mesh section

This applies to both LinkFiles and LinkAsFiles in the Mesh section. The former will copy a given file into the run folder for case i using the base name of the original (source) file. Using

"Mesh": {
    "LinkAsFiles": {
        "inputs/mesh-config02.ugrid": "mesh.ugrid"
    }
}

will create a link (using the absolute path) from inputs/mesh-config02.ugrid to mesh.ugrid in the case run folder.

Call:
>>> cntl.link_files(i)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

i: int

Case index

Versions:

  • 2025-03-26 @ddalle: v1.0

  • 2025-09-19 @ddalle: v1.1; LinkAsFiles

abstractmethod log_cmd(msg: str, title: str | None = None, parent: int = 0)

Write a message to CLI log

Call:
>>> runner.log_cmd(msg, title, parent=0)
Inputs:
runner: CaseRunner

Controller to run one case of solver

msg: str

Primary content of message

title: {None} | str

Manual title (default is name of calling function)

parent: {0} | int

Extra levels to use for calling function name

Versions:

  • 2025-04-30 @ddalle: v1.0

abstractmethod log_cntl(f: bool = False)

Record the current JSON settings and document any changes

Call:
>>> cntl.log_cntl(f=True)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

f: :True | {False}

Force recalculation of hash of current options

abstractmethod log_main(msg: str, title: str | None = None, parent: int = 0)

Write a message to primary log

Call:
>>> runner.log_main(msg, title, parent=0)
Inputs:
runner: CaseRunner

Controller to run one case of solver

msg: str

Primary content of message

title: {None} | str

Manual title (default is name of calling function)

parent: {0} | int

Extra levels to use for calling function name

Versions:

  • 2025-04-30 @ddalle: v1.0

log_parser(parser: ArgReader)

Log a CLI command based on parser

Call:
>>> cntl.log_parser(parser)
Inputs:
cntl: cape.cfdx.cntl.Cntl

CAPE run matrix control instance

parser: cape.argread.ArgReader

CLI parser based on cape.cfdx.cli

Versions:

  • 2026-01-05 @ddalle: v1.0

abstractmethod make_case_folder(i: int)

Create folder(s) if needed for case i

Call:
>>> cntl.make_case_folder(i)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

i: int

Index of case to analyze

Versions:

  • 2023-08-25 @ddalle: v1.0 (CreateFolder)

  • 2023-10-20 @ddalle: v2.0; support arbitrary depth

abstractmethod prep_aflr3(i: int)

Prepare the AFLR3 surface file (.surf) for a case

Writes <proj>.surf to the case folder when the aflr3 option is enabled. Does nothing otherwise.

Call:
>>> cntl.prep_aflr3(i)
Inputs:
cntl: Cntl

CAPE run matrix control instance

i: int

Case index

Versions:

  • 2026-05-02 @ddalle: v1.0

abstractmethod prep_intersect(i: int)

Prepare triangulation input files for intersect

Writes the volume, component-ID, and farfield triangulation files needed by the Cart3D intersect tool, or writes a plain .i.tri when only verify is requested. Does nothing if neither option is set.

Call:
>>> cntl.prep_intersect(i)
Inputs:
cntl: Cntl

CAPE run matrix control instance

i: int

Case index

Versions:

  • 2026-05-02 @ddalle: v1.0

abstractmethod prep_tri_write(i: int)

Write the surface triangulation file to a case folder

Writes <proj>.<ext> (typically .tri or .fro) when WriteTri is set and neither aflr3 nor intersect is active (those options handle their own triangulation output).

Call:
>>> cntl.prep_tri_write(i)
Inputs:
cntl: Cntl

CAPE run matrix control instance

i: int

Case index

Versions:

  • 2026-05-02 @ddalle: v1.0

abstractmethod prepare_mesh_overset(i: int)

Copy/link mesh files from config folder into case folder

Call:
>>> cntl.prepare_mesh_overset(i)
Inputs:
cntl: Cntl

CAPE run matrix controller instance

i: int

Case index

Versions:

  • 2024-10-10 @ddalle: v1.0

abstractmethod preprocess_kwargs(kw: dict)

Preprocess command-line arguments and flags/keywords

This will effect the following CLI options:

--cons CONS

Comma-separated constraints split into a list

-x FPY

Each -x argument is executed (can be repeated)

-I INDS

Convert INDS like 3-6,8 to [3, 4, 5, 8]

Call:
>>> opts = cntl.cli_preprocess(*a, **kw)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

kw: dict[True | False | str]

CLI keyword arguments and flags, modified in-place

Versions:

  • 2024-12-19 @ddalle: v1.0

abstractmethod process_mesh_filename(fname: str, fproj: str | None = None) → str

Return a mesh file name using the project root name

Call:
>>> fout = cntl.process_mesh_filename(fname, fproj=None)
Inputs:
cntl: Cntl

Run matrix control instance for unstructured-mesh solver

fname: str

Raw file name to be converted to case-folder file name

fproj: {None} | :class;`str`

Project root name

Outputs:
fout: str

Name of file name using project name as prefix

Versions:

  • 2016-04-05 @ddalle: v1.0 (pyfun)

  • 2023-03-15 @ddalle: v1.1; add fproj

  • 2024-10-22 @ddalle: v2.0; move to cfdx

abstractmethod qdel_cases(**kw)

Kill/stop PBS job of cases

This function deletes a case’s PBS/Slurm jobbut not delete the foder for a case.

Call:
>>> cntl.qdel_cases(**kw)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Cape control interface

I: {None} | list[int]

List of cases to delete

kw: dict

Other subset parameters, e.g. re, cons

Versions:

  • 2025-06-22 @ddalle: v1.0

abstractmethod read_case_json(i: int) → RunControlOpts

Read case.json file from case i if possible

Call:
>>> rc = cntl.read_case_json(i)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Instance of control class

i: int

Case index

Outputs:
rc: None | dict

Run control interface read from case.json file

Versions:

  • 2016-12-12 @ddalle: v1.0

  • 2017-04-12 @ddalle: v1.1; add to cape.cfdx

  • 2023-06-29 @ddalle: v2.0; use _case_mod

  • 2023-07-07 @ddalle: v2.1; use CaseRunner

abstractmethod read_dex(comp: str, force: bool = False)

Read a DataBook component using DataExchanger

Call:
>>> db = cntl.read_dex(comp, force=False)
Inputs:
cntl: Cntl

CAPE run matrix controller instance

comp: str

Name of component to read

force: True | {False}

Option to re-read even if present in database

Outputs:
db: cape.cfdx.dex.DataExchanger

Data extracted from run matrix for comp comp

Versions:

  • 2025-07-25 @ddalle: v1.0

abstractmethod read_options(fjson: str)

Read options using appropriate class

This allows users to set warning mode via an environment variable.

Call:
>>> cntl.read_options(fjson)
Inputs:
cntl: cape.cfdx.cntl.Cntl

CAPE run matrix control instance

fjson: str

Name of JSON file to read

Versions:

  • 2023-05-26 @ddalle: v1.0; forked from __init__()

  • 2023-12-13 @ddalle: v1.1; add RootDir and JSONFile

abstractmethod rm_cases(prompt: bool = True, **kw) → int

Delete one or more cases

This function deletes a case’s PBS job and removes the entire directory. By default, the method prompts for confirmation before deleting; set prompt to False to delete without prompt, but only cases with 0 iterations can be deleted this way.

Call:
>>> n = cntl.rm_cases(prompt=True, **kw)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Cape control interface

prompt: {True} | False

Whether or not to prompt user before deleting case

I: {None} | list[int]

List of cases to delete

kw: dict

Other subset parameters, e.g. re, cons

Outputs:
n: int

Number of folders deleted

Versions:

  • 2025-06-20 @ddalle: v1.0

abstractmethod run_batch(argv: list) → str

Write and submit PBS/Slurm script for a CLI

Call:
>>> jobid = cntl.run_batch(argv)
Inputs:
cntl: cape.cfdx.cntl.Cntl

CAPE run matrix control instance

argv: list[str]

List of command-line inputs

Outputs:
jobid: str

PBS/Slurm job number/ID

Versions:

  • 2024-12-20 @ddalle: v1.0

  • 2026-04-28 @ddalle: v1.1; update file name

abstractmethod update_dex(**kw)

Extract one or more DataBook components

Call:
>>> cntl.update_dex(cons=[], **kw)
Inputs:
cntl: cape.cfdx.cntl.Cntl

Overall CAPE control instance

dex, comp: {None} | str

Wildcard to subset list of FM components

I: list[int]

List of indices

cons: list[str]

List of constraints like 'Mach<=0.5'

Versions:

  • 2026-03-12 @ddalle: v1.0

abstractmethod update_dex_case(comp: str, i: int) → int

Update one case of a DataBook component

Call:
>>> n = cntl.update_dex_case(comp, i)
Inputs:
cntl: Cntl

CAPE run matrix controller instance

comp: str

Name of component to read

i: int

Case to index

Outputs:
n: 0 | 1

Number of updates made

Versions:

  • 2025-07-25 @ddalle: v1.0

abstractmethod update_dex_comp(comp: str, **kw)

Update a DataBook component

Call:
>>> n = cntl.update_dex_comp(comp, **kw)
Inputs:
cntl: Cntl

CAPE run matrix controller instance

comp: str

Name of component to read

I: {None} | np.ndarray[int]

Indices of cases to process

Versions:

  • 2025-07-29 @ddalle: v1.0