cape.cfdx.cmd: Creating system commands

This module creates system commands as lists of strings for binaries or scripts that require multiple command-line options. It is closely tied to cape.cfdx.bin.

Commands are created in the form of a list of strings. This is the format used in subprocess commands (with shell=``False``) and also cape.bin.calli(), etc. As a very simple example, the system command "ls -lh" becomes the list ["ls", "-lh"].

Inputs to the functions in this module take one of two forms:

• A cape.options.Options object or subset thereof

• Keyword arguments

The first method allows any appropriate Options interface and then extracts the appropriate portion. For instance verify() can be given either a top-level options object, a "RunControl" options interface (e.g. from cape.options.runControl), or a dict of options specific to verify. It does this using the following Python commands:

opts = opts.get("RunControl", opts)
opts = opts.get("verify", opts)

Other functions, such as aflr3(), rely on the built-in methods of the cape.cfdx.options.Options class. For example, opts.get_aflr3_i(j) returns the aflr3 input file name for phase j if opts is in any of the following classes:

Class	Description
cape.cfdx.options.Options	All Cape settings
cape.cfdx.options.RunControlOpts	All run settings
cape.cfdx.options.aflr3opts	AFLR3 settings

cape.cfdx.cmdgen.aflr3(opts=None, j=0, **kw)

Create AFLR3 system command as a list of strings

Call:

>>> cmdi = aflr3(opts=None, j=0, **kw)

Inputs:

opts: cape.options.Options

Options interface, either global, “RunControl”, or “aflr3”

j: int | None

Phase number

blc: bool

Whether or not to generate prism layers

blr: float

Boundary layer stretching option

blds: float

Initial surface stretching

cdfr: float

Maximum geometric stretching

cdfs: {None} | 0 <= float <=10

Distribution function exclusion zone

angblisimx: float

Max BL intersection angle

Outputs:

cmdi: list[str]

System command created as list of strings

Versions:

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

• 2023-08-18 @ddalle: v1.1; use isolate_subsection()

cape.cfdx.cmdgen.append_cmd_if(cmdi: list, opt, app: list, exc=None)

Append to command list if value is not False-like

Call:

>>> append_cmd_if(cmdi, opt, app, exc=None)

Inputs:

cmdi: list[str]

List of strings of existing command, appended

opt: object

Value to to test whether to append

app: list[str]

Commands to append to cmdi if opt

exc: {None} | BaseException

Exception to raise if opt is False-like

Versions:

• 2023-08-19 @ddalle: v1.0

cape.cfdx.cmdgen.append_cmd_if_not_none(cmdi: list, opt, app: list, exc=None)

Append to command list if value is not None

Call:

>>> append_cmd_if_not_none(cmdi, opt, app, exc=None)

Inputs:

cmdi: list[str]

List of strings of existing command, appended

opt: object

Value to to test whether to append

app: list[str]

Commands to append to cmdi if opt is not None

exc: {None} | BaseException

Exception to raise if opt is None

Versions:

• 2023-08-19 @ddalle: v1.0

cape.cfdx.cmdgen.get_mpi_procs() → int

Estimate number of MPI processes available

This works by reading PBS or Slurm environment variables

Call:

>>> nproc = get_mpi_procs()

Outputs:

nproc: int

Number of CPUs indicated by environment variables

Versions:

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

cape.cfdx.cmdgen.get_nproc(rc: Options, j: int = 0) → int

Get the number of processes available or specified

Call:

>>> nproc = get_nproc(rc, j=0)

Inputs:

rc: Options

Options interface, or RunControl section

j: {0} | int

Phase number

Outputs:

nproc: int

Number of CPUs or GPUs

Versions:

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

cape.cfdx.cmdgen.infix_phase(fname: str, j: int = 0) → str

Add a two-digit phase number to file name before final extension

Call:

>>> fnamej = infix_phase(fname, j)

Inputs:

fname: str

Oritinal name of file

j: {0} | int

Phase number

Outputs:

fnamej: str

Infixed file name

Examples:

>>> infix_phase("fun3d.nml", 2)
'fun3d.02.nml'

Versions:

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

cape.cfdx.cmdgen.intersect(opts=None, j=0, **kw)

Interface to Cart3D binary intersect

Call:

>>> cmd = cape.cmd.intesect(opts=None, **kw)

Inputs:

opts: cape.options.Options

Options interface

i: str

Name of input tri file

o: str

Name of output tri file

Outputs:

cmd: list (str)

Command split into a list of strings

Versions:

• 2015-02-13 @ddalle: v1.0

• 2023-08-18 @ddalle: v1.1; use isolate_subsection()

cape.cfdx.cmdgen.isolate_subsection(opts, cls: type, subsecs: tuple)

Get an options class instance for a section or subsection

For example this class can be used to get the "RunControl" section whether opts is a dict, overall Options instance, or already is an instance of RunControlOpts. It allows the user to get the correct section automatically by either using an instance of that section’s class directly or by giving any parent thereof.

Call:

>>> myopts = isolate_subsection(opts, cls, subsecs)

Inputs:

opts: None | dict | OptionsDict

Options interface of either target section or parent thereof

cls: type

Subclass of OptionsDict for top-level options

subsecs: tuple[str]

Tuple of subsections of cls to isolate

Versions:

• 2023-08-18 @ddalle: v1.0

cape.cfdx.cmdgen.mpiexec(opts: OptionsDict | None = None, j: int = 0, **kw) → list

Create command [prefix] to run MPI, e.g. mpiexec -np 10

Call:

>>> cmdi = aflr3(opts=None, j=0, **kw)

Inputs:

opts: {None} | OptionsDict

Options interface, either global or “RunControl” section

j: {0} | int

Phase number

Outputs:

cmdi: list[str]

System command created as list of strings

Versions:

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

• 2024-10-10 @ddalle: v1.1; add args and threads

cape.cfdx.cmdgen.tecmcr(mcr='export-lay.mcr', **kw)

Run a Tecplot macro

Call:

>>> cmd = tecmcr(mcr="export-lay.mcr")

Inputs:

mcr: str

File name of Tecplot macro

Outputs:

cmd: list (str)

Command split into a list of strings

Versions:

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

cape.cfdx.cmdgen.verify(opts=None, **kw)

Generate command for Cart3D executable verify

Call:

>>> cmdi = cape.cmd.verify(opts=None, **kw)

Inputs:

opts: cape.options.Options

Options interface

i: {"Components.i.tri" | str

Name of tri file to test

ascii: {True} | False

Flag to consider input file ASCII

binary: True | {False}

Flag to consider input file binary

Outputs:

cmdi: list (str)

Command split into a list of strings

Versions:

• 2015-02-13 @ddalle: v1.0

• 2023-08-18 @ddalle: v1.1; use isolate_subsection()