cape.cntl: Base module for CFD operations and processing

This module provides tools and templates for tools to interact with various CFD codes and their input files. The base class is cape.cntl.Cntl, and the derivative classes include cape.pycart.cntl.Cntl. This module creates folders for cases, copies files, and can be used as an interface to perform most of the tasks that Cape can accomplish except for running individual cases.

The control module is set up as a Python interface for the master JSON file, which contains the settings to be used for a given CFD project.

The derivative classes are used to read input files, set up cases, submit and/or run cases, and be an interface for the various Cape options as they are customized for the various CFD solvers. The individualized modules are below.

See also:
class cape.cntl.Cntl(fname='cape.json')

Class to handle options, setup, and execution of CFD codes

Call:
>>> cntl = cape.Cntl(fname="cape.json")
Inputs:
fname: str

Name of JSON settings file from which to read options

Outputs:
cntl: cape.cntl.Cntl

Instance of Cape control interface

cntl.opts: cape.cfdx.options.Options

Options interface

cntl.x: cape.runmatrix.RunMatrix

Run matrix interface

cntl.RootDir: str

Working directory from which the class was generated

Versions:

  • 2015-09-20 @ddalle: Started

  • 2016-04-01 @ddalle: Version 1.0

ApplyCases(**kw)

Reapply settings to one or more cases

Call:
>>> cntl.ApplyCases(cons=[], j=None, extend=1, **kw)
Inputs:
cntl: cape.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: Version 1.0

ArchiveCases(**kw)

Archive completed cases and clean them up if specified

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

Instance of overall control interface

cons: list[str]

List of constraints

I: list[int]

List of indices

Versions:

  • 2016-12-09 @ddalle: Version 1.0

ArchivePWD(phantom=False)

Archive a single case in the current folder ($PWD)

Call:
>>> cntl.ArchivePWD(phantom=False)
Inputs:
cntl: cape.cntl.Cntl

Instance of overall control interface

phantom: True | {False}

Option to write actions to archive.log but not actually delete files

Versions:

  • 2016-12-09 @ddalle: Version 1.0

CaseFunction(i)

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.cntl.Cntl

Overall control interface

i: int

Case number

Versions:

  • 2017-04-05 @ddalle: Version 1.0

See also:
CaseGetCurrentIter()

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.CaseGetCurrentIter()
Inputs:
cntl: cape.cntl.Cntl

Overall CAPE control instance

i: int

Index of the case to check (0-based)

Outputs:
n: int | None

Number of completed iterations or None if not set up

Versions:

  • 2015-10-14 @ddalle: Version 1.0

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.cntl.Cntl

Overall CAPE control instance

i: int

Index of the case to check (0-based)

Outputs:
j: int | None

Phase number

Versions:

  • 2017-06-29 @ddalle: Version 1.0

CaseStartCase()

Start a case by either submitting it or running it

This function relies on cape.cfdx.case, and so it is customized for the correct solver only in that it calls the correct case module.

Call:
>>> pbs = cntl.CaseStartCase()
Inputs:
cntl: cape.cntl.Cntl

Cape control interface

Outputs:
pbs: None | int

PBS job ID if submitted successfully

Versions:

  • 2015-10-14 @ddalle: Version 1.0

  • 2021-10-26 @ddalle: Version 2.0; use cls._case_mod

CheckCase(i, v=False)

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.case.GetCurrentIter() and cape.cntl.Cntl.CheckNone().

Call:
>>> n = cntl.CheckCase(i, v=False)
Inputs:
cntl: cape.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: Version 1.0

  • 2015-09-27 @ddalle: Version 2.0; generic

  • 2015-10-14 @ddalle: Version 2.1; no case req

  • 2017-02-22 @ddalle: Version 2.2; add verbose flag

CheckCaseStatus(i, jobs=None, auto=False, u=None)

Determine the current status of a case

Call:
>>> sts = cntl.CheckCaseStatus(i, jobs=None, **kw)
Inputs:
cntl: cape.cntl.Cntl

Overall CAPE control instance

i: int

Index of the case to check (0-based)

jobs: dict

Information on each job by ID number

u: str

User name (defaults to process username)

Versions:

  • 2014-10-04 @ddalle: Version 1.0

  • 2014-10-06 @ddalle: Version 1.1, check queue status

CheckError(i)

Check if a case has a failure

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

Overall CAPE control instance

i: int

Run index

Outputs:
q: bool

If True, case has FAIL file in it

Versions:

  • 2015-01-02 @ddalle: Version 1.0

CheckFM(**kw)

Display missing force & moment components

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

Overall CAPE control instance

fm, aero: {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:

  • 2018-10-19 @ddalle: Version 1.0

CheckLL(**kw)

Display missing line load components

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

Overall CAPE control instance

fm, aero: {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:

  • 2018-10-19 @ddalle: Version 1.0

CheckNone(v=False)

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.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: Version 1.0

  • 2017-02-22 @ddalle: Version 1.1, verbosity option

CheckPhase(i, v=False)

Check current phase number of run i

Call:
>>> n = cntl.CheckPhase(i, v=False)
Inputs:
cntl: cape.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: Version 1.0

CheckRunning(i)

Check if a case is currently running

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

Overall CAPE control instance

i: int

Run index

Outputs:
q: bool

If True, case has RUNNING file in it

Versions:

  • 2014-10-03 @ddalle: Version 1.0

CheckTriqFM(**kw)

Display missing TriqFM components

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

Overall CAPE control instance

fm, aero: {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:

  • 2018-10-19 @ddalle: Version 1.0

CheckTriqPoint(**kw)

Display missing TriqPoint components

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

Overall CAPE control instance

fm, aero: {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:

  • 2018-10-19 @ddalle: Version 1.0

CheckUsedPhase(i, v=False)

Check maximum phase number run at least once

Call:
>>> j, n = cntl.CheckUsedPhase(i, v=False)
Inputs:
cntl: cape.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: Version 1.0

  • 2017-07-11 @ddalle: Version 1.1, verbosity option

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.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: Version 1.0

  • 2021-01-25 @ddalle: Version 1.1; use cls._zombie_files

CleanCases(**kw)

Clean a list of cases using Progress archive options only

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

Instance of control interface

Versions:

  • 2017-03-13 @ddalle: Version 1.0

CleanPWD(phantom=False)

Clean ProgressFiles from current folder

Call:
>>> cntl.CleanPWD(phantom=False)
Inputs:
cntl: cape.cntl.Cntl

Instance of control interface

phantom: True | {False}

Option to write actions to archive.log but not delete any files

Versions:

  • 2017-03-10 @ddalle: Version 1.0

  • 2017-12-15 @ddalle: Version 1.1, added phantom

DeleteCase(i, **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.cntl.Cntl

Cape control interface

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: Version 1.0

Dezombie(**kw)

Clean up any ZOMBIE cases

Call:
>>> cntl.Dezombie(**kw)
Inputs:
cntl: cape.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:

  • 2021-10-14 @ddalle: Version 1.0

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.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: Version 1.0

  • 2014-12-09 @ddalle: Version 2.0, --cons

ExecScript(i, cmd)

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.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: Version 1.0

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=[], j=None, extend=1, **kw)
Inputs:
cntl: cape.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:

  • 2016-12-12 @ddalle: Version 1.0

FilterUser(i, **kw)

Determine if case i is assigned to current user

Call:
>>> q = cntl.FilterUser(i, **kw)
Inputs:
cntl: cape.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

Versions:

2017-07-10 @ddalle: Version 1.0

GetCPUTime(i, running=False)

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.cntl.Cntl.GetCPUTimeFromFile() with the correct file name.

Call:
>>> CPUt = cntl.GetCPUTime(i)
Inputs:
cntl: cape.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: Version 1.0

  • 2016-08-30 @ddalle: Version 1.1, check for RUNNING

  • 2016-08-31 @ddalle: Version 1.2
GetCPUTimeBoth(i, fname, fstart, running=False)

Read CAPE-style core-hour files 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.cntl.Cntl.GetCPUTimeFromFile() with the correct file name.

Call:
>>> t = cntl.GetCPUTimeBoth(i, fname, fstart, running=False)
Inputs:
cntl: cape.cntl.Cntl

Cape control interface

i: int

Case index

Outputs:
t: float | None

Total core hours used in this job

Versions:

  • 2015-12-22 @ddalle: Version 1.0

  • 2016-08-30 @ddalle: Version 1.1, check for RUNNING

GetCPUTimeFromFile(i, fname='cape_time.dat')

Read a Cape-style core-hour file

Call:
>>> CPUt = cntl.GetCPUTimeFromFile(i, fname)
Inputs:
cntl: cape.cntl.Cntl

Cape control interface

i: int

Case index

fname: str

Name of file containing timing history

Outputs:
CPUt: float | None

Total core hours used in this job

Versions:

  • 2015-12-22 @ddalle: Version 1.0

GetCPUTimeFromStartFile(i, fname='cape_start.dat')

Read CAPE-style start time file and compare to current time

Call:
>>> CPUt = cntl.GetCPUTimeFromStartFile(i, fname)
Inputs:
cntl: cape.cntl.Cntl

Cape control interface

i: int

Case index

fname: str

Name of file containing timing history

Outputs:
CPUt: float | None

Total core hours used in this job

Versions:

  • 2015-08-30 @ddalle: Version 1.0

GetLastIter(i)

Get minimum required iteration for a given case

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

Cape control interface

i: int

Run index

Outputs:
nIter: int

Number of iterations required for case i

Versions:

  • 2014-10-03 @ddalle: Version 1.0

GetPBSJobID(i)

Get PBS job number if one exists

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

Overall CAPE control instance

i: int

Run index

Outputs:
pbs: None | int

Most recently reported job number for case i

Versions:

  • 2014-10-06 @ddalle: Version 1.0

GetPBSName(i, pre=None)

Get PBS name for a given case

Call:
>>> lbl = cntl.GetPBSName(i, pre=None)
Inputs:
cntl: cape.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, visible via qstat

Versions:

  • 2014-09-30 @ddalle: Version 1.0

  • 2016-12-20 @ddalle: Version 1.1, moved to x

GetPhaseBreaks()

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.cntl.Cntl

Cape control interface

Outputs:
PI: list[int]

Min iteration counts for each phase

Versions:

  • 2017-04-12 @ddalle: Version 1.0

GetSurfCT_ExitArea(key, i, comp=None)

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.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: Version 1.0

GetSurfCT_ExitMach(key, i, comp=None)

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.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: Version 1.0

GetSurfCT_RefArea(key, i)

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.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: Version 1.0

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.cntl.Cntl

Instance of Cape control interface

Versions:

  • 2014-10-08 @ddalle: Version 1.0 (pycart)

  • 2015-09-20 @ddalle: Version 1.0

  • 2022-04-12 @ddalle: Version 2.0; use self.modules

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.cntl.Cntl

Overall control interface

Versions:

  • 2017-04-04 @ddalle: Version 1.0

  • 2022-04-12 @ddalle: Version 2.0; use _exec_funclist()

MarkERROR(**kw)

Mark one or more cases as ERROR and rewrite matrix

Call:
>>> cntl.MarkERROR(**kw)
Inputs:
cntl: cape.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: Version 1.0

MarkPASS(**kw)

Mark one or more cases as PASS and rewrite matrix

Call:
>>> cntl.MarkPASS(**kw)
Inputs:
cntl: cape.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: Version 1.0

PrepareCase(i)

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.cntl.Cntl

Overall CAPE control instance

i: int

Index of case to analyze

Versions:

  • 2014-09-30 @ddalle: Version 1.0

  • 2015-09-27 @ddalle: Version 2.0, convert to template

PrepareConfig(i)

Apply rotations, translations, etc. to Config.xml

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

Overall CAPE control instance

i: int

Case index

Versions:

  • 2016-08-23 @ddalle: Version 1.0

PrepareConfigFunction(key, i)

Apply special configuration modification function for a case

Call:
>>> cntl.PrepareConfigFunction(key, i)
Inputs:
cntl: cape.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: Version 1.0

  • 2022-04-13 @ddalle: Version 2.0; exec_modfunction()

PrepareConfigRotation(key, i)

Apply a rotation to a component or components

Call:
>>> cntl.PrepareConfigRotation(key, i)
Inputs:
cntl: cape.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: Version 1.0

PrepareConfigTranslation(key, i)

Apply a translation to a component or components

Call:
>>> cntl.PrepareConfigTranslation(key, i)
Inputs:
cntl: cape.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: Version 1.0

PreparePoints(i)

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

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

Overall CAPE control instance Index of the case to check (0-based)

Versions:

  • 2022-03-07 @ddalle: Version 1.0

PreparePointsRotation(key, i)

Apply a rotation to named config points for one col

Call:
>>> cntl.PreparePointsRotation(key, i)
Inputs:
cntl: cape.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: Version 1.0

PreparePointsTranslation(key, i)

Apply a translation to named config points for one col

Call:
>>> cntl.PreparePointsTranslation(key, i)
Inputs:
cntl: cape.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: Version 1.0

PrepareTri(i)

Rotate/translate/etc. triangulation for given case

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

Overall CAPE control instance

i: int

Index of the case to check (0-based)

Versions:

  • 2014-12-01 @ddalle: Version 1.0

  • 2016-04-05 @ddalle: Version 1.1, pycart -> cape

PrepareTriFunction(key, i)

Apply special surf modification function for a case

Call:
>>> cntl.PrepareTriFunction(key, i)
Inputs:
cntl: cape.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: Version 1.0

  • 2016-04-05 @ddalle: Version 1.1, pycart -> cape

  • 2022-04-13 @ddalle: Version 2.0; exec_modfunction()

PrepareTriRotation(key, i)

Apply a rotation to a component or components

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

Overall CAPE control instance

i: int

Index of the case to check (0-based)

Versions:

  • 2015-09-11 @ddalle: Version 1.0

  • 2016-04-05 @ddalle: Version 1.1, pycart -> cape

PrepareTriTranslation(key, i)

Apply a translation to a component or components

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

Overall CAPE control instance

i: int

Index of the case to check (0-based)

Versions:

  • 2015-09-11 @ddalle: Version 1.0

  • 2016-04-05 @ddalle: Version 1.1, pycart -> cape

ReadCaseJSON(i)

Read case.json file from case i if possible

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

Instance of control class

i: int

Run index

Outputs:
rc: None | dict

Run control interface read from case.json file

Versions:

  • 2016-12-12 @ddalle: Version 1.0

  • 2017-04-12 @ddalle: Version 1.1, adde to cape

ReadConfig(f=False)

Read Config.xml or other surf configuration format

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

Overall CAPE control instance

f: True | {False}

Option to reread existing cntl.config

Versions:

  • 2016-06-10 @ddalle: Version 1.0

  • 2016-10-21 @ddalle: Version 2.0, added Config.json

  • 2020-09-01 @ddalle: Version 2.1, add f kwarg

ReadTri()

Read initial triangulation file(s)

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

Overall CAPE control instance

Versions:

  • 2014-08-30 @ddalle: Version 1.0

RevertOptions()

Revert to cntl.opts0 as working options

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

CAPE solver control interface

Versions:

  • 2021-07-31 @ddalle: Version 1.0

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: Version 1.0

SkeletonCases(**kw)

Archive completed cases and delete all but a few files

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

Instance of overall control interface

cons: list[str]

List of constraints

I: list[int]

List of indices

Versions:

  • 2016-12-14 @ddalle: Version 1.0

SkeletonPWD(phantom=False)

Delete most files in current folder, leaving only a skeleton

Call:
>>> cntl.SkeletonPWD(phantom=False)
Inputs:
cntl: cape.cntl.Cntl

Instance of control interface

phantom: True | {False}

Option to write actions to archive.log but not delete any files

Versions:

  • 2017-12-14 @ddalle: Version 1.0

StartCase(i)

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.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.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

Versions:

  • 2014-10-06 @ddalle: Version 1.0

StopCase(i)

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.cntl.Cntl

Cape control interface

i: int

Index of the case to check (0-based)

Versions:

  • 2014-12-27 @ddalle: Version 1.0

SubmitBatchPBS(argv)

Write a PBS script for a batch run

Call:
>>> cntl.SubmitBatchPBS(argv)
Inputs:
argv: list[str]

List of command-line inputs

Versions:

  • 2016-09-25 @ddalle: Version 1.0

SubmitJobs(**kw)

Check jobs and prepare or submit jobs if necessary

Call:
>>> cntl.SubmitJobs(**kw)
Inputs:
cntl: cape.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: Version 1.0

  • 2014-12-09 @ddalle: Version 2.0, --cons

  • 2021-08-01 @ddalle: Version 2.1, save/revert options

UnarchiveCases(**kw)

Unarchive a list of cases

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

Instance of control interface

Versions:

  • 2017-03-13 @ddalle: Version 1.0

UnmarkCase(**kw)

Remove PASS or ERROR marking from one or more cases

Call:
>>> cntl.UnmarkCase(**kw)
Inputs:
cntl: cape.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: Version 1.0

UpdateCaseProp(**kw)

Update generic-property databook for one or more comp

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

Overall CAPE control instance

prop: {None} | str

Wildcard to subset list of "Prop" components

I: list[int]

List of indices

cons: list[str]

List of constraints like 'Mach<=0.5'

Versions:

  • 2022-04-08 @ddalle: Version 1.0

UpdateDBPyFunc(**kw)

Update Python function databook for one or more comp

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

Overall CAPE control instance

prop: {None} | str

Wildcard to subset list of "Prop" components

I: list[int]

List of indices

cons: list[str]

List of constraints like 'Mach<=0.5'

Versions:

  • 2022-04-10 @ddalle: Version 1.0

UpdateFM(**kw)

Collect force and moment data

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

Overall CAPE control instance

fm, aero: {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:

  • 2014-12-12 @ddalle: Version 1.0

  • 2014-12-22 @ddalle: Version 2.0

    • Complete rewrite of DataBook class

    • Eliminate “Aero” class

  • 2017-04-25 @ddalle: Version 2.1, add wildcards

  • 2018-10-19 @ddalle: Version 3.0, rename from Aero()

UpdateLL(**kw)

Update one or more line load data books

Call:
>>> cntl.UpdateLL(ll=None, **kw)
Inputs:
cntl: cape.cntl.Cntl

Overall CAPE control instance

ll: {None} | str

Optional name of line load component to update

I: list[int]

List of indices

cons: list[str]

List of constraints like 'Mach<=0.5'

pbs: True | {False}

Whether or not to calculate line loads with PBS scripts

Versions:

  • 2016-06-07 @ddalle: Version 1.0

  • 2016-12-21 @ddalle: Version 1.1, Add pbs flag

  • 2017-04-25 @ddalle: Version 1.2

    • Removed pbs

    • Added --delete

UpdateTriqFM(**kw)

Update one or more TriqFM data books

Call:
>>> cntl.UpdateTriqFM(comp=None, **kw)
Inputs:
cntl: cape.cntl.Cntl

Control class

comp: {None} | str

Name of TriqFM component

I: list[int]

List of indices

cons: list[str]

List of constraints like 'Mach<=0.5'

Versions:

  • 2017-03-29 @ddalle: Version 1.0

UpdateTriqPoint(**kw)

Update one or more TriqPoint point sensor data books

Call:
>>> cntl.UpdateTriqPoint(comp=None, **kw)
Inputs:
cntl: cape.cntl.Cntl

Control class

comp: {None} | str

Name of TriqFM component

I: list[int]

List of indices

cons: list[str]

List of constraints like 'Mach<=0.5'

Versions:

  • 2017-03-29 @ddalle: Version 1.0

WriteCaseJSON(i, rc=None)

Write JSON file with run control settings for case i

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

Generic control class

i: int

Run index

rc: {None} | dict

If specified, write specified “RunControl” options

Versions:

  • 2015-10-19 @ddalle: Version 1.0

  • 2013-03-31 @ddalle: Version 2.0, manual options input

WriteConditionsJSON(i, rc=None)

Write JSON file with run matrix settings for case i

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

Generic control class

i: int

Run index

rc: {None} | dict

If specified, write specified “RunControl” options

Versions:

  • 2021-09-08 @ddalle: Version 1.0

WritePBSHeader(f, i=None, j=0, typ=None, wd=None, pre=None)

Write common part of PBS or Slurm script

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

Overall CAPE control instance

f: file

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

pre: {None} | str

PBS job name prefix, used for postprocessing

Versions:

  • 2015-09-30 @ddalle: Version 1.0, fork WritePBS()

  • 2016-09-25 @ddalle: Version 1.1, “BatchPBS”

  • 2016-12-20 @ddalle: Version 1.2

    • Consolidated to opts

    • Added prefix

abspath(fname)

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: Version 1.0

cli(*a, **kw)

Command-line interface to cape

Call:
>>> cntl.cli(*a, **kw)
Inputs:
cntl: cape.cntl.Cntl

Overall CAPE control instance

kw: dict[True | False | str]

Unprocessed keyword arguments

Outputs:
cmd: None | str

Name of command that was processed, if any

Versions:

  • 2018-10-19 @ddalle: Version 1.0

cli_cape(*a, **kw)

Common command-line interface

This function is applied after the command-line arguments are parsed using cape.argread.readflagstar() and the control interface has already been read according to the -f flag.

Call:
>>> cmd = cntl.cli_cape(*a, **kw)
Inputs:
cntl: cape.cntl.Cntl

Overall CAPE control instance

kw: dict

Preprocessed command-line keyword arguments

Outputs:
cmd: None | str

Name of command that was processed, if any

Versions:

  • 2018-10-19 @ddalle: Version 1.0

cli_preprocess(*a, **kw)

Preprocess command-line arguments and flags/keywords

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

Overall CAPE control instance

kw: dict[True | False | str]

Command-line keyword arguments and flags

Outputs:
a: tuple

List of sequential command-line parameters

kw: dict

Flags with any additional preprocessing performed

Versions:

  • 2018-10-19 @ddalle: Version 1.0

exec_modfunction(funcname, a=None, kw=None, name=None)

Execute a function from cntl.modules

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

Overall control interface

func: 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: Version 1.0

mkdir(fdir)

Make a directory with the correct permissions

Call:
>>> cntl.mkdir(fdir)
Inputs:
cntl: cape.cntl.Cntl

Overall CAPE control instance

fdir: str

Directory to create

Versions:

  • 2015-09-27 @ddalle: Version 1.0