cape.pyover.case: OVERFLOW case control module

This module contains the important function run_overflow(), which actually runs overrunmpi or whichever executable is specified by the user, along with the utilities that support it.

It also contains OVERFLOW-specific versions of some of the generic methods from cape.cfdx.case. For instance the function GetCurrentIter() determines how many OVERFLOW iterations have been run in the current folder, which is obviously a solver-specific task. It also contains the function LinkQ() and LinkX() which creates links to fixed file names from the most recent output created by OVERFLOW, which is useful for creating simpler Tecplot layouts, for example.

All of the functions from cape.case are imported here. Thus they are available unless specifically overwritten by specific cape.pyover versions.

class cape.pyover.case.CaseRunner(fdir=None)

finalize_files(j: int)

Clean up files after running one cycle of phase j

Call:

>>> runner.finalize_files(j)

Inputs:

runner: CaseRunner

Controller to run one case of solver

j: int

Phase number

Versions:

• 2016-04-14 @ddalle: v1.0 (FinalizeFiles)

get_prefix(j=None)

Read OVERFLOW file prefix

Call:

>>> rname = runner.get_prefix(j=None)

Inputs:

runner: CaseRunner

Controller to run one case of solver

j: {None} | int

Phase number

Outputs:

rname: str

Project prefix

Versions:

• 2016-02-01 @ddalle: v1.0 (GetPrefix)

• 2023-07-08 @ddalle: v1.1; instance method

get_stop_iter()

Get iteration at which to stop by reading STOP file

If the file exists but is empty, returns 0; if file does not exist, returns None; and otherwise reads the iteration

Call:

>>> qstop, nstop = runner.get_stop_iter()

Inputs:

runner: CaseRunner

Controller to run one case of solver

Outputs:

nstop: int | None

Iteration at which to stop, if any

Versions:

• 2017-03-07 @ddalle: v1.0 (GetStopIter)

• 2023-07-08 @ddalle: v1.1; instance method

getx_history_iter()

Get the most recent iteration number for a history file

This function uses the last line from the file run.resid

Call:

>>> n = runner.getx_history_iter()

Inputs:

runner: CaseRunner

Controller to run one case of solver

Outputs:

n: int | float | None

Most recent iteration number

Versions:

• 2016-02-01 @ddalle: v1.0 (GetHistoryIter)

• 2023-07-08 @ddalle: v1.1; instance method

getx_iter()

Get the most recent iteration number for OVERFLOW case

Call:

>>> n = runner.getx_iter()

Inputs:

runner: CaseRunner

Controller to run one case of solver

Outputs:

n: int | None

Last iteration number

Versions:

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

• 2023-07-08 @ddalle: v1.1; instance method

getx_out_iter()

Get the most recent iteration number for a running file

This function uses the last line from the file resid.out

Call:

>>> n = runner.getx_out_iter()

Inputs:

runner: CaseRunner

Controller to run one case of solver

Outputs:

n: int | None

Most recent iteration number

Versions:

• 2016-02-02 @ddalle: v1.0 (GetOutIter)

• 2023-07-08 @ddalle: v1.1; instance method

getx_phase(n: int)

Get the appropriate input number based on results available

Call:

>>> j = runner.getx_phase(n)

Inputs:

runner: CaseRunner

Controller to run one case of solver

n: int

Iteration number

Outputs:

j: int

Most appropriate phase number for a restart

Versions:

• 2014-10-02 @ddalle: v1.0 (cape.pycart.case)

• 2015-12-29 @ddalle: v1.0 (cape.pyfun.case)

• 2016-02-03 @ddalle: v1.0 (GetPhaseNumber)

• 2017-01-13 @ddalle: v1.1; no full run.%02.* seq

• 2023-07-09 @ddalle: v1.2; rename, instance method

getx_restart_iter()

Get total iteration number of most recent flow file

Call:

>>> n = runner.getx_restart_iter()

Inputs:

runner: CaseRunner

Controller to run one case of solver

Outputs:

n: int

Index of most recent check file

Versions:

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

getx_running_iter()

Get the most recent iteration number for a running file

This function uses the last line from the file resid.tmp

Call:

>>> n = runner.getx_running_iter()

Inputs:

runner: CaseRunner

Controller to run one case of solver

Outputs:

n: int | None

Most recent iteration number

Versions:

• 2016-02-01 @ddalle: v1.0 ( GetRunningIter)

• 2023-07-08 @ddalle: v1.2; instance method

init_post()

Custom initialization for pyover

Call:

>>> runner.init_post()

Inputs:

runner: CaseRunner

Controller to run one case of solver

Versions:

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

read_namelist(j=None)

Read case namelist file

Call:

>>> nml = runner.read_namelist(j=None)

Inputs:

runner: CaseRunner

Controller to run one case of solver

i: {None} | nonnegative int

Phase number (0-based)

Outputs:

nml: OverNamelist

Namelist interface

Versions:

• 2015-12-29 @ddalle: v1.0 (cape.pyfun.case)

• 2015-02-02 @ddalle: v1.0 (GetNamelist)

• 2016-12-12 @ddalle: v1.1; i kwarg

• 2023-07-09 @ddalle: v1l.1; rename, instance method

run_phase(j: int)

Run one phase using appropriate commands

Call:

>>> runner.run_phase(j)

Inputs:

runner: CaseRunner

Controller to run one case of solver

j: int

Phase number

Versions:

• 2023-06-05 @ddalle: v1.0; from run_overflow

• 2023-07-08 @ddalle; v1.1; instance method

write_stop_iter(n=0)

Create a STOP file and optionally set the stop iteration

Call:

>>> runner.write_stop_iter(n)

Inputs:

n: None | {0} | positive int

Iteration at which to stop; empty file if 0 or None

Versions:

• 2017-03-07 @ddalle: v1.0 (WriteStopIter)

• 2023-06-05 @ddalle: v2.0; use context manager

• 2023-07-08 @ddalle: v2.1; rename, instance method

cape.pyover.case.EditSplitmqI(fin, fout, qin, qout)

Edit the I/O file names in a splitmq/splitmx input file

Call:

>>> EditSplitmqI(fin, fout, qin, qout)

Inputs:

fin: str

Name of template splitmq input file

fout: str

Name of altered splitmq input file

qin: str

Name of input solution or grid file

qout: str

Name of output solution or grid file

Versions:

• 2017-01-07 @ddalle: v1.0

cape.pyover.case.GetLatest(glb)

Get the most recent file matching a glob or list of globs

Call:

>>> fq = GetLatest(glb)
>>> fq = GetLatest(lglb)

Inputs:

glb: str

File name glob

lblb: list[str]

List of file name globs

Outputs:

fq: None | str

Name of most recent file matching glob(s)

Versions:

• 2017-01-08 @ddalle: v1.0

cape.pyover.case.GetQ()

Find most recent q.* file, with q.avg taking precedence

Call:

>>> fq = GetQ()

Outputs:

fq: None | str

Name of most recent averaged q file or newest q file

Versions:

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

cape.pyover.case.GetQFile(fqi='q.pyover.p3d')

Get most recent OVERFLOW q file and its associated iterations

Averaged solution files, such as q.avg take precedence.

Call:

>>> fq, n, i0, i1 = GetQFile(fqi="q.pyover.p3d")

Inputs:

fqi: {q.pyover.p3d} | q.pyover.avg | q.pyover.vol | str

Target Overflow solution file after linking most recent files

Outputs:

fq: str

Name of q file

n: int

Number of iterations included

i0: int

First iteration in the averaging

i1: int

Last iteration in the averaging

Versions:

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

• 2017-03-28 @ddalle: v1.1; from `lineLoad` to ``case

cape.pyover.case.GetX()

Get the most recent x.* file

Call:

>>> fx = GetX()

Outputs:

fx: None | str

Name of most recent x.save or similar file

Versions:

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

cape.pyover.case.LinkLatest(fsrc, fname)

Create a symbolic link, but clean up existing links

This prevents odd behavior when using os.symlink() when the link already exists. It performs no action (rather than raising an error) when the source file does not exist or is None. Finally, if fname is already a full file, no action is taken.

Call:

>>> LinkLatest(fsrc, fname)

Inputs:

fsrc: None | str

Name of file to act as source for the link

fname: str

Name of the link to create

Versions:

• 2017-01-08 @ddalle: v1.0

cape.pyover.case.LinkQ()

Link the most recent q.* file to a fixed file name

Call:

>>> LinkQ()

Versions:

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

• 2016-12-29 @ddalle: Moved file search to GetQ()

cape.pyover.case.LinkX()

Link the most recent x.* file to a fixed file name

Call:

>>> LinkX()

Versions:

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

cape.pyover.case.checkqavg(fname)

Check the number of iterations in a q.avg file

This function works by attempting to read a Fortran record at the very end of the file with exactly one (single-precision) integer. The function tries both little- and big-endian interpretations. If both methods fail, it returns 1 to indicate that the q file is a single-iteration solution.

Call:

>>> nq = checkqavg(fname)

Inputs:

fname: str

Name of OVERFLOW q file

Outputs:

nq: int

Number of iterations included in average

Versions:

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

cape.pyover.case.checkqt(fname)

Check the iteration number or time in a q file

Call:

>>> t = checkqt(fname)

Inputs:

fname: str

Name of OVERFLOW q file

Outputs:

t: None | float

Iteration number or time value

Versions:

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

cape.pyover.case.run_overflow()

Setup and run the appropriate OVERFLOW command

Call:

>>> run_overflow()

Versions:

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

• 2021-10-08 @ddalle: v1.1

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