cape.pyover.case: OVERFLOW base 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.

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: Version 1.0

cape.pyover.case.ExtendCase(m=1, run=True)

Extend the maximum number of iterations and restart/resubmit

Call:
>>> ExtendCase(m=1, run=True)
Inputs:
m: {1} | int

Number of additional sets to add

run: {True} | False

Whether or not to actually run the case

Versions:

  • 2016-09-19 @ddalle: Version 1.0

cape.pyover.case.GetCurrentIter()

Get the most recent iteration number

Call:
>>> n = GetHistoryIter()
Outputs:
n: int | None

Last iteration number

Versions:

  • 2015-10-19 @ddalle: Version 1.0

cape.pyover.case.GetHistoryIter()

Get the most recent iteration number for a history file

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

Call:
>>> n = GetHistoryIter()
Outputs:
n: int | None

Most recent iteration number

Versions:

  • 2016-02-01 @ddalle: Version 1.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: Version 1.0

cape.pyover.case.GetNamelist(rc=None, i=None)

Read case namelist file

Call:
>>> nml = GetNamelist(rc=None, i=None)
Inputs:
rc: pyFun.options.runControl.RunControl

Run control options

i: {None} | nonnegative int

Phase number (0-based)

Outputs:
nml: pyOver.overNamelist.OverNamelist

Namelist interface

Versions:

  • 2015-12-29 @ddalle: Version 1.0

  • 2015-02-02 @ddalle: Copied from cape.pyfun.case

  • 2016-12-12 @ddalle: Added phase as optional input

cape.pyover.case.GetOutIter()

Get the most recent iteration number for a running file

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

Call:
>>> n = GetOutIter()
Outputs:
n: int | None

Most recent iteration number

Versions:

  • 2016-02-02 @ddalle: Version 1.0

cape.pyover.case.GetPBSScript(i=None)

Determine the file name of the PBS script to call

This is a compatibility function for cases that do or do not have multiple PBS scripts in a single run directory

Call:
>>> fpbs = GetPBSScript(i=None)
Inputs:
i: int

Run index

Outputs:
fpbs: str

Name of PBS script to call

Versions:

  • 2014-12-01 @ddalle: Version 1.0

  • 2015-10-19 @ddalle: FUN3D version

cape.pyover.case.GetPhaseNumber(rc)

Determine the appropriate input number based on results available

Call:
>>> i = GetPhaseNumber(rc)
Inputs:
rc: pyOver.options.runControl.RunControl

Options interface for run control

Outputs:
i: int

Most appropriate phase number for a restart

Versions:

  • 2014-10-02 @ddalle: Version 1.0

  • 2015-12-29 @ddalle: FUN3D version

  • 2016-02-03 @ddalle: OVERFLOW version

  • 2017-01-13 @ddalle: Removed req’t to have full run.%02.* seq

cape.pyover.case.GetPrefix(rc=None, i=None)

Read OVERFLOW file prefix

Call:
>>> rname = GetPrefix()
>>> rname = GetPrefix(rc=None, i=None)
Inputs:
rc: pyFun.options.runControl.RunControl

Run control options

i: int

Phase number

Outputs:
rname: str

Project prefix

Versions:

  • 2016-02-01 @ddalle: Version 1.0

cape.pyover.case.GetQ()

Get the most recent q.* file, with q.avg taking precedence

Call:
>>> fq = GetQ()
Outputs:
fq: None | str

Name of most recent averaged q file or most recent q file

Versions:

  • 2016-12-29 @ddalle: Version 1.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: Version 1.0

  • 2017-03-28 @ddalle: Moved from lineLoad to case

cape.pyover.case.GetRestartIter(rc=None)

Get total iteration number of most recent flow file

Call:
>>> n = GetRestartIter()
Outputs:
n: int

Index of most recent check file

Versions:

  • 2015-10-19 @ddalle: Version 1.0

cape.pyover.case.GetRunningIter()

Get the most recent iteration number for a running file

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

Call:
>>> n = GetRunningIter()
Outputs:
n: int | None

Most recent iteration number

Versions:

  • 2016-02-01 @ddalle: Version 1.0

cape.pyover.case.GetStopIter()

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 number from the file.

Call:
>>> n = GetStopIter()
Outputs:
n: None | int

Iteration at which to stop OVERFLOW

Versions:

  • 2017-03-07 @ddalle: Version 1.0

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: Version 1.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: Version 1.0

cape.pyover.case.LinkQ()

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

Call:
>>> LinkQ()
Versions:

  • 2016-09-06 @ddalle: Version 1.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: Version 1.0

cape.pyover.case.ReadCaseJSON()

Read RunControl settings for local case

Call:
>>> rc = ReadCaseJSON()
Outputs:
rc: pyFun.options.runControl.RunControl

Options interface for run control settings

Versions:

  • 2014-10-02 @ddalle: Version 1.0

  • 2015-12-29 @ddalle: OVERFLOW version

cape.pyover.case.RestartCase(i0=None)

Restart a case by either submitting it or calling with a system command

This version of the command is called with run_overflow() after running a phase or attempting to run a phase.

Call:
>>> RestartCase(i0=None)
Inputs:
i0: int | None

Phase index of the previous run

Versions:

  • 2016-02-01 @ddalle: Version 1.0

cape.pyover.case.SetRestartIter(rc, n=None)

Set a given check file as the restart point

Call:
>>> SetRestartIter(rc, n=None)
Inputs:
rc: pyFun.options.runControl.RunControl

Run control options

n: int

Restart iteration number, defaults to most recent available

Versions:

  • 2014-10-02 @ddalle: Version 1.0

  • 2014-11-28 @ddalle: Added td_flowCart compatibility

cape.pyover.case.StartCase()

Start a case by submitting it or calling a system command

Call:
>>> StartCase()
Versions:

  • 2015-10-19 @ddalle: Version 1.0

cape.pyover.case.WriteCaseJSON(rc)

Write or rewrite RunControl settings to case.json

Call:
>>> WriteCaseJSON(rc)
Inputs:
rc: pyFun.options.runControl.RunControl

Options interface for run control settings

Versions:

  • 2016-09-19 @ddalle: Version 1.0

cape.pyover.case.WriteStartTime(tic, rc, i, fname='pyover_start.dat')

Write the start time in tic

Call:
>>> WriteStartTime(tic, rc, i, fname="pyover_start.dat")
Inputs:
tic: datetime.datetime

Time to write into data file

rc: pyOver.options.runControl.RunControl

Options interface

i: int

Phase number

fname: {"pyover_start.dat"} | str

Name of file containing run start times

Versions:

  • 2016-08-31 @ddalle: Version 1.0

cape.pyover.case.WriteStopIter(n=0)

Create a STOP file and optionally set the iteration at which to stop

Call:
>>> WriteStopIter(n)
Inputs:
n: None | {0} | positive int

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

Versions:

  • 2017-03-07 @ddalle: Version 1.0

cape.pyover.case.WriteUserTime(tic, rc, i, fname='pyover_time.dat')

Write time usage since time tic to file

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

Time from which timer will be measured

rc: pyOver.options.runControl.RunControl

Options interface

i: int

Phase number

fname: str

Name of file containing CPU usage history

Outputs:
toc: datetime.datetime

Time at which time delta was measured

Versions:

  • 2015-12-29 @ddalle: Version 1.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: Version 1.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: Version 1.0

cape.pyover.case.run_overflow()

Setup and run the appropriate OVERFLOW command

Call:
>>> run_overflow()
Versions:

  • 2016-02-02 @ddalle: Version 1.0

  • 2021-10-08 @ddalle: Version 1.1