cape.cfdx.case: Generic case control

This module contains templates for interacting with individual cases. Since this is one of the most highly customized modules of the Cape system, there are few functions here, and the functions that are present are mostly templates.

In general, the case module is used for actually running the CFD solver (and any additional binaries that may be required as part of the run process), and it contains other capabilities for renaming files and determining the settings for a particular case. Cape saves many settings for the CFD solver and archiving in a file called case.json within each case folder, which prevents changes to the master JSON file from unpredictably affecting cases that have already been initialized or are already running.

Actual functionality is left to individual modules listed below.

Several of the key methods for this API module are described below.

cape.cfdx.case.CaseAFLR3(rc, proj='Components', fmt='lb8.ugrid', n=0)

Create volume mesh using aflr3

This function looks for several files to determine the most appropriate actions to take, replacing Components with the value from proj for each file name and lb8.ugrid with the value from fmt:

  • Components.i.tri: Triangulation file

  • Components.surf: AFLR3 surface file

  • Components.aflr3bc: AFLR3 boundary conditions

  • Components.xml: Surface component ID mapping file

  • Components.lb8.ugrid: Output volume mesh

  • Components.FAIL.surf: AFLR3 surface indicating failure

If the volume grid file already exists, this function takes no action. If the surf file does not exist, the function attempts to create it by reading the tri, xml, and aflr3bc files using cape.tri.Tri. The function then calls cape.bin.aflr3() and finally checks for the FAIL file.

Call:
>>> CaseAFLR3(rc, proj="Components", fmt='lb8.ugrid', n=0)
Inputs:
rc: cape.options.runControl.RunControl

Case options interface from case.json

proj: {"Components"} | str

Project root name

fmt: {"b8.ugrid"} | str

AFLR3 volume mesh format

n: int

Iteration number

Versions:

  • 2016-04-05 @ddalle: Version 1.0

cape.cfdx.case.CaseIntersect(rc, proj='Components', n=0, fpre='run')

Run intersect to combine geometries if appropriate

This is a multistep process in order to preserve all the component IDs of the input triangulations. Normally intersect requires each intersecting component to have a single component ID, and each component must be a water-tight surface.

Cape utilizes two input files, Components.c.tri, which is the original triangulation file with intersections and the original component IDs, and Components.tri, which maps each individual original tri file to a single component. The files involved are tabulated below.

  • Components.tri: Intersecting components, each with own compID

  • Components.c.tri: Intersecting triangulation, original compIDs

  • Components.o.tri: Output of intersect, only a few compIDs

  • Components.i.tri: Original compIDs mapped to intersected tris

More specifically, these files are "%s.i.tri" % proj, etc.; the default project name is "Components". This function also calls the Chimera Grid Tools program triged to remove unused nodes from the intersected triangulation and optionally remove small triangles.

Call:
>>> CaseIntersect(rc, proj='Components', n=0, fpre='run')
Inputs:
rc: cape.options.runControl.RunControl

Case options interface from case.json

proj: {'Components'} | str

Project root name

n: int

Iteration number

fpre: {'run'} | str

Standard output file name prefix

See also:
Versions:

  • 2015-09-07 @ddalle: Split from run_flowCart()

  • 2016-04-05 @ddalle: Generalized to cape

cape.cfdx.case.CaseVerify(rc, proj='Components', n=0, fpre='run')

Run verify to check triangulation if appropriate

This function checks the validity of triangulation in file "%s.i.tri" % proj. It calls cape.bin.verify().

Call:
>>> CaseVerify(rc, proj='Components', n=0, fpre='run')
Inputs:
rc: cape.options.runControl.RunControl

Case options interface from case.json

proj: {'Components'} | str

Project root name

n: int

Iteration number

fpre: {'run'} | str

Standard output file name prefix

Versions:

  • 2015-09-07 @ddalle: Version 1.0; from run_flowCart()

  • 2016-04-05 @ddalle: Version 1.1; generalize to cape

cape.cfdx.case.GetCurrentIter()

Template function to report the most recent iteration

Call:
>>> n = cape.case.GetCurrentIter()
Outputs:
n: 0

Most recent index, customized for each solver

Versions:

  • 2015-09-27 @ddalle: Version 1.0

cape.cfdx.case.GetPhaseNumber(rc, n=None, fpre='run')

Determine the phase number based on results available

Call:
>>> j = GetPhaseNumber(rc, n=None, fpre='run')
Inputs:
rc: cape.options.runControl.RunControl

Options interface for run control

n: int

Iteration number

fpre: {"run"} | str

Prefix for output files

Outputs:
j: int

Most appropriate phase number for a restart

Versions:

  • 2014-10-02 @ddalle: Version 1.0

  • 2015-10-19 @ddalle: Version 1.1; FUN3D version

  • 2016-04-14 @ddalle: Version 1.2; CAPE version

cape.cfdx.case.GetRestartIter()

Get the restart iteration

This is a placeholder function and is only called in error.

Call:
>>> cape.case.GetRestartIter()
Raises:
RuntimeError: Exception

Error regarding where this was called

Versions:

  • 2016-04-14 @ddalle: Version 1.0

cape.cfdx.case.GetTriqFile(proj='Components')

Get most recent triq file and its associated iterations

This is a template version with specific implementations for each solver. The cape version simply returns the most recent triq file in the current folder with no iteration information.

Call:
>>> ftriq, n, i0, i1 = GetTriqFile(proj='Components')
Inputs:
proj: {"Components"} | str

File root name

Outputs:
ftriq: str

Name of most recently modified triq file

n: {None}

Number of iterations included

i0: {None}

First iteration in the averaging

i1: {None}

Last iteration in the averaging

Versions:

  • 2016-12-19 @ddalle: Version 1.0

cape.cfdx.case.PrepareEnvironment(rc, i=0)

Set environment variables, alter resource limits (ulimit)

This function relies on the system module resource.

Call:
>>> case.PrepareEnvironment(rc, i=0)
Inputs:
rc: cape.options.runControl.RunControl

Options interface for run control and command-line inputs

i: int

Phase number

See also:
Versions:

  • 2015-11-10 @ddalle: Version 1.0

cape.cfdx.case.ReadCaseJSON(fjson='case.json')

Read Cape settings for local case

Call:
>>> rc = cape.case.ReadCaseJSON()
Inputs:
fjson: {"case.json"} | str

Name of JSON settings file

Outputs:
rc: cape.options.runControl.RunControl

Options interface for run control and command-line inputs

Versions:

  • 2014-10-02 @ddalle: Version 1.0

cape.cfdx.case.ReadConditions(k=None)

Read run matrix variable value in the current folder

Call:
>>> conds = cape.case.ReadConditions()
>>> v = cape.case.ReadConditions(k)
Inputs:
k: str

Name of run matrix variable/trajectory key

Outputs:
conds: dict (any)

Dictionary of run matrix conditions

v: any

Run matrix conditions of key k

Versions:

  • 2017-03-28 @ddalle: Version 1.0

cape.cfdx.case.ReadStartTimeProg(fname)

Read the most recent start time to file

Call:
>>> nProc, tic = ReadStartTimeProg(fname)
Inputs:
fname: str

Name of file containing CPU usage history

Outputs:
nProc: int

Number of cores

tic: datetime.datetime

Time at which most recent run was started

Versions:

  • 2016-08-30 @ddalle: Version 1.0

cape.cfdx.case.SetResourceLimit(r, ulim, u, i=0, unit=1024)

Set resource limit for one variable

Call:
>>> SetResourceLimit(r, ulim, u, i=0, unit=1024)
Inputs:
r: int

Integer code of particular limit, from resource

ulim: cape.options.ulimit.ulimit

System resource options interface

u: str

Name of limit to set

i: int

Phase number

unit: int

Multiplier, usually for a kbyte

See also:

  • cape.options.ulimit

Versions:

  • 2016-03-13 @ddalle: Version 1.0

  • 2021-10-21 @ddalle: Version 1.1; check if Windows

cape.cfdx.case.StartCase()

Empty template for starting a case

The function is empty but does not raise an error

Call:
>>> cape.case.StartCase()
See also:
Versions:

  • 2015-09-27 @ddalle: Skeleton

cape.cfdx.case.StopCase()

Stop a case by deleting PBS job and removing RUNNING file

Call:
>>> case.StopCase()
Versions:

  • 2014-12-27 @ddalle: Version 1.0

cape.cfdx.case.WriteStartTimeProg(tic, rc, i, fname, prog)

Write the time to file at which a program or job started

Call:
>>> WriteStartTimeProg(tic, rc, i, fname, prog)
Inputs:
tic: datetime.datetime

Time from which timer will be measured

rc: pyCart.options.runControl.RunControl

Options interface

i: int

Phase number

fname: str

Name of file containing CPU usage history

prog: str

Name of program to write in history

Versions:

  • 2016-08-30 @ddalle: Version 1.0

cape.cfdx.case.WriteUserTimeProg(tic, rc, i, fname, prog)

Write time usage since time tic to file

Call:
>>> toc = WriteUserTime(tic, rc, i, fname, prog)
Inputs:
tic: datetime.datetime

Time from which timer will be measured

rc: pyCart.options.runControl.RunControl

Options interface

i: int

Phase number

fname: str

Name of file containing CPU usage history

prog: str

Name of program to write in history

Outputs:
toc: datetime.datetime

Time at which time delta was measured

Versions:

  • 2015-12-09 @ddalle: Version 1.0

  • 2015-12-22 @ddalle: Copied from cape.pycart.case

cape.cfdx.case.init_timer()

Mark a case as RUNNING and initialize a timer

Call:
>>> tic = init_timer()
Outputs:
tic: datetime.datetime

Time at which case was started

Versions:

  • 2021-10-21 @ddalle: Version 1.0; from run_fun3d()

cape.cfdx.case.read_case_json(cls=<class 'cape.cfdx.options.runControl.RunControl'>)

Read RunControl settings from case.json

Call:
>>> rc = read_case_json()
>>> rc = read_case_json(cls)
Inputs:
cls: {RunControl} | type

Class to use for output file

Outputs:
rc: cls

Case run control settings

Versions:

  • 2021-10-21 @ddalle: Version 1.0