cape.pykes.cntl: Kestrel control module

This module provides tools to quickly setup basic or complex Kestrel run matrices and serve as an executive for pre-processing, running, post-processing, and managing the solutions. A collection of cases combined into a run matrix can be loaded using the following commands.

>>> import cape.pykes.cntl
>>> cntl = cape.pykes.cntl.Cntl("pyKes.json")
>>> cntl
<cape.pyfun.Cntl(nCase=892)>
>>> cntl.x.GetFullFolderNames(0)
'poweroff/m1.5a0.0b0.0'

An instance of this cape.pykes.cntl.Cntl class has many attributes, which include the run matrix (cntl.x), the options interface (cntl.opts), and optionally the data book (cntl.DataBook), the appropriate input files (such as cntl.), and possibly others.

cape.cntl.Cntl class, so any methods available to the CAPE class are also available here.

class cape.pykes.cntl.Cntl(fname=None)

Class for handling global options and setup for Kestrel

This class is intended to handle all settings used to describe a group of Kestrel cases.

The settings are read from a JSON file.

Defaults are read from the file options/pyKes.default.json.

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

Name of pyKes input file

Outputs:
cntl: cape.pykes.cntl.Cntl

Instance of the pyKes control class

Data members:
cntl.opts: dict

Dictionary of options for this case (directly from fname)

cntl.x: pyFun.runmatrix.RunMatrix

Values and definitions for variables in the run matrix

cntl.RootDir: str

Absolute path to the root directory

Versions:

  • 2015-10-16 @ddalle: Started

ApplyCase(i, nPhase=None, **kw)

Apply settings from cntl.opts to an individual case

This rewrites each run namelist file and the case.json file in the specified directories.

Call:
>>> cntl.ApplyCase(i, nPhase=None)
Inputs:
cntl: cape.pyfun.cntl.Cntl

FUN3D control interface

i: int

Case number

nPhase: {None} | positive int

Last phase number (default determined by PhaseSequence)

Versions:

  • 2016-03-31 @ddalle: Version 1.0

ArchivePWD(phantom=False)

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

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

CAPE main control instance

phantom: True | {False}

Write actions to archive.log; only delete if False

Versions:

  • 2017-03-10 @ddalle: First cape.pyfun version

  • 2017-12-15 @ddalle: Added phantom option

CheckMesh(i)

Check if the mesh for case i is prepared

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

Main CAPE control instance

i: int

Case index

Outputs:
q: True | False

Whether or not mesh for case i is prepared

Versions:

  • 2021-10-26 @ddalle: Version 1.0

CleanPWD(phantom=False)

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

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

Instance of control interface

phantom: True | {False}

Write actions to archive.log; only delete if False

Versions:

  • 2017-03-10 @ddalle: Version 1.0

  • 2017-12-15 @ddalle: Added phantom option

ExtendCase(i, n=1, j=None, imax=None)

Add iterations to case i by repeating the last phase

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

CAPE main control instance

i: int

Run index

n: {1} | positive int

Add n times steps to the total iteration count

j: {None} | nonnegative int

Apply to phase j, by default use the last phase

imax: {None} | nonnegative int

Use imax as the maximum iteration count

Versions:

  • 2022-07-26 @ddalle: Version 1.0

FindXMLPaths(j=0)

Find all Path and File elements

Call:
>>> elems = cntl.FindXMLPaths(j=0)
Inputs:
cntl: cape.pykes.cntl.Cntl

Run matrix control interface

j: {0} | int

Phase number

Outputs:
elems: list[Element]

List of XML elements

Versions:

  • 2021-10-25 @ddalle: Version 1.0

GetMeshFileNames(j=0)

Get list of copy/link files from both JSON and XML

Call:
>>> meshfiles = cntl.GetMeshFiles(j=0)
Inputs:
cntl: Cntl

CAPE main control instance

j: {0} | int

Phase number

Outputs:
meshfiles: list[str]

List of files to copy/link

Versions:

  • 2021-10-25 @ddalle: Version 1.0

PrepareCase(i)

Prepare a case for running if necessary

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

CAPE main control instance

i: int

Case index

Versions:

  • 2021-10-26 @ddalle: Version 1.0

PrepareJobXML(i)

Write pykes.xml file(s) for case i

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

CAPE main control instance

i: int

Case index

Versions:

  • 2021-10-26 @ddalle: Version 1.0

PrepareMesh(i)

Prepare the mesh for case i if necessary

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

CAPE main control instance

i: int

Case index

Versions:

  • 2021-10-26 @ddalle: Version 1.0

ReadJobXML(j=0, q=True)

Read the fun3d.nml file

Call:
>>> cntl.ReadNamelist(j=0, q=True)
Inputs:
cntl: cape.pykes.cntl.Cntl

Run matrix control interface

j: {0} | int

Phase number

q: {True} | False

Option read to JobXML, else JobXML0

Versions:

  • 2021-10-18 @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.pyfun.cntl.Cntl

CAPE main control instance

phantom: True | {False}

Write actions to archive.log; only delete if False

Versions:

  • 2017-12-14 @ddalle: Version 1.0

WritePBS(i)

Write the PBS script(s) for a given case

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

Main CAPE control instance

i: int

Case index

Versions:

  • 2021-10-26 @ddalle: Version 1.0

cli(*a, **kw)

Command-line interface

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

CAPE main 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: Content from bin/ executables

get_job_name(j=0)

Get “job name” for phase j

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

Instance of main CAPE control class

j: {0} | int

Phase number

Outputs:
name: str

Job name for phase j

Versions:

  • 2021-1-05 @ddalle: Version 1.0

init_post()

Do __init__() actions specific to pyfun

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

CAPE run matrix control instance

Versions:

  • 2023-07-10 @ddalle: v1.0