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.casecntl.CaseRunner(fdir: str | None = 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)

find_surf_source() → MeshFileMeta

Find latest available files with surface data

Call:

>>> typ, x, q = runner.find_surf_source()

Inputs:

runner: CaseRunner

Controller to run one case of solver

Outputs:

typ: "vol" | "srf"

Data source type

x: str

Name of surface/volume grid file

q: str

Name of surface/volume solution file

Versions:

• 2025-08-16 @ddalle: v1.0

genr8_resid_args() → tuple

Get list of args to CaseResid

Call:

>>> args = runner.genr8_resid_args()

Inputs:

runner: CaseRunner

Controller to run one case of solver

Outputs:

args: tuple[str]

Tuple of one string, project base root name

Versions:

• 2025-09-16 @ddalle: v1.0

get_dex_args_pre_fm() → tuple

Get list of args prior to component name in CaseFM

Call:

>>> args = runner.get_dex_args_pre_fm()

Inputs:

runner: CaseRunner

Controller to run one case of solver

Outputs:

args: tuple[str]

Tuple of one string, project base root name

Versions:

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

get_dex_iter_lineload(comp: str) → int

Get number of iterations for "LineLoad" comp

Call:

>>> n = runner.get_dex_iter_lineload()

Inputs:

runner: CaseRunner

Controller to run one case of solver

comp: str

Name of DataBook component

Outputs:

n: int

Iteration count

Versions:

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

get_dex_iter_triqfm(comp: str) → int

Get number of iterations for "TriqFM" comp

Call:

>>> n = runner.get_dex_iter_triqfm()

Inputs:

runner: CaseRunner

Controller to run one case of solver

comp: str

Name of DataBook component

Outputs:

n: int

Iteration count

Versions:

• 2025-08-13 @ddalle: v1.0

get_dex_nstats_lineload(comp: str) → int

Get window size for a "LineLoad" DataBook component

Call:

>>> n = db.get_dex_nstats_lineload(comp)

Inputs:

runner: CaseRunner

Controller to run one case of solver

comp: str

Name of DataBook component

Outputs:

n: int

Iterations/timesteps included in averaging window

Versions:

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

get_grid_regex() → str

Return regular expression for volume grid files

Call:

>>> pat = runner.get_grid_regex()

Inputs:

runner: CaseRunner

Controller to run one case of solver

Outputs:

pat: str

Regular expression search pattern

Versions:

• 2025-08-16 @ddalle: v1.0

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

get_surf_regex()

Get regular expression that all surface output files match

Call:

>>> regex = runner.get_surf_regex()

Inputs:

runner: CaseRunner

Controller to run one case of solver

Outputs:

regex: str

Regular expression that all surface sol’n files match

Versions:

• 2025-01-24 @ddalle: v1.0

get_surfgrid_regex()

Return regular expression for surface grid files

Call:

>>> pat = runner.get_surfgrid_regex()

Inputs:

runner: CaseRunner

Controller to run one case of solver

Outputs:

pat: str

Regular expression search pattern

Versions:

• 2025-08-16 @ddalle: v1.0

get_vol_regex() → str

Get regular expression that all volume output files match

Call:

>>> regex = runner.get_vol_regex()

Inputs:

runner: CaseRunner

Controller to run one case of solver

Outputs:

regex: str

Regular expression that all surface sol’n files match

Versions:

• 2025-08-13 @ddalle: v1.0

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

infer_tavg_nstats(n: int | None = None, fname: int | None = None) → int

Infer num of iters averaged for output at iteration n

Call:

>>> nstats = runner.infer_tavg_nstats(n)

Inputs:

runner: CaseRunner

Controller to run one case of solver

n: int

Iteration number

Outputs:

nstats: int

Number of iterations averaged in viz file

Versions:

• 2025-08-10 @ddalle: v1.0

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

prep_qvol(subdir: str = 'lineload')

Prepare q.vol in subdir as link to best q vol file

Call:

>>> runner.prep_qvol(subdir="lineload")

Inputs:

runner: CaseRunner

Controller to run one case of solver

Versions:

• 2025-08-15 @ddalle: v1.0

prepare_triq(subdir: str = 'lineload')

Prep q and x files to create grid.i.triq

This will first identify the most recent source files in the working directory and also run splitmq and splitmx if so prescribed.

Call:

>>> triqstats = runner.prepare_triq(subdir="lineload")

Inputs:

runner: CaseRunner

Controller to run one case of solver

subdir: {"lineload"} | str

Name folder to create grid.i.triq within

Outputs:

triqstats: collections.namedtuple

FileStatus of .triq file

triqstats.fname: "grid.i.triq"

Name of .triq file (created or found)

triqstats.n: int

Iteration number for fname

Versions:

• 2025-08-19 @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

splitmq(fsplitmq: str = 'splitmq.i')

Run splitmq to extract surface and second-layer sol data

Call:

>>> runner.splitmq(fsplitmq="splitmq.i")

Inputs:

runner: CaseRunner

Controller to run one case of solver

fsplitmq: {"splitmq.i"} | str

Name of input file

Versions:

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

splitmx(fsplitmx: str)

Run splitmx to extract surface and second-layer grid

Call:

>>> runner.splitmx(fsplitmx="splitmx.i")

Inputs:

runner: CaseRunner

Controller to run one case of solver

fsplitmx: {"splitmx.i"} | str

Name of input file

Versions:

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

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.casecntl.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.casecntl.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.casecntl.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.casecntl.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.casecntl.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.casecntl.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.casecntl.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.casecntl.LinkX()

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

Call:

>>> LinkX()

Versions:

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

class cape.pyover.casecntl.MeshFileMeta(typ, x, q)

Class for solution mesh + data file names

q

Alias for field number 2

typ

Alias for field number 0

x

Alias for field number 1

cape.pyover.casecntl.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.casecntl.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.casecntl.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