cape.pyfun.databook: Post-processing for FUN3D data

This module contains functions for reading and processing forces, moments, and other statistics from cases in a trajectory. Data books are usually created by using the cape.pyfun.cntl.Cntl.ReadDataBook() function.

# Read FUN3D control instance
cntl = pyFun.Cntl("pyFun.json")
# Read the data book
cntl.ReadDataBook()
# Get a handle
DB = cntl.DataBook

# Read a line load component
DB.ReadLineLoad("CORE_LL")
DBL = DB.LineLoads["CORE_LL"]
# Read a target
DB.ReadTarget("t97")
DBT = DB.Targets["t97"]

Data books can be created without an overall control structure, but it requires creating a run matrix object using cape.pyfun.runmatrix.RunMatrix, so it is a more involved process.

Data book modules are also invoked during update and reporting command-line calls.

$ pyfun --aero
$ pyfun --ll
$ pyfun --pt
$ pyfun --triqfm
$ pyfun --report

The available components mirror those described on the template data book modules, cape.cfdx.dataBook, cape.cfdx.lineload, and cape.cfdx.pointsensor. However, some data book types may not be implemented for all CFD solvers.

See Also:
class cape.pyfun.databook.CaseFM(proj: str, comp: str, **kw)

Iterative force & moment histories for one case, one component

This class contains methods for reading data about an the history of an individual component for a single casecntl. It reads the Tecplot file $proj_fm_$comp.dat where proj is the lower-case root project name and comp is the name of the component. From this file it determines which coefficients are recorded automatically.

Call:
>>> fm = CaseFM(proj, comp)
Inputs:
proj: str

Root name of the project

comp: str

Name of component to process

Outputs:
fm: CaseFM

Instance of the force and moment class

Versions:

  • 2014-11-12 @ddalle: v0.1; starter version

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

  • 2016-05-05 @ddalle: v1.1; handle adaptive cases

  • 2016-10-28 @ddalle: v1.2; catch iteration resets

get_filelist() → list

Get list of files to read

Call:
>>> filelist = fm.get_filelist()
Inputs:
fm: CaseFM

Component iterative history instance

Outputs:
filelist: list[str]

List of files to read to construct iterative history

Versions:

  • 2024-01-23 @ddalle: v1.0; from old __init__()

get_flow_folder() → str

Get the working folder for primal solutions

This will be either "" (base dir) or "Flow"

Call:
>>> workdir = fm.get_flow_folder()
Inputs:
fm: CaseFM

Force & moment iterative history

Outputs:
workdir: "" | "Flow"

Current working folder for primal (flow) solutions

Versions:

  • 2024-01-23 @ddalle: v1.0

readfile(fname: str) → dict

Read a Tecplot iterative history file

Call:
>>> db = fm.readfile(fname)
Inputs:
fm: CaseFM

Single-component iterative history instance

fname: str

Name of file to read

Outputs:
db: tsvfile.TSVTecDatFile

Data read from fname

Versions:

  • 2024-01-23 @ddalle: v1.0

class cape.pyfun.databook.CaseResid(proj: str, **kw)

FUN3D iterative history class

This class provides an interface to residuals, CPU time, and similar data for a given case

Call:
>>> hist = CaseResid(proj)
Inputs:
proj: str

Project root name

Outputs:
hist: cape.pyfun.databook.CaseResid

Instance of the run history class

PlotR1(**kw)

Plot the density

Call:
>>> h = hist.PlotR1(n=None, nFirst=None, nLast=None, **kw)
Inputs:
hist: cape.pyfun.databook.CaseResid

Instance of the DataBook residual history

n: int

Only show the last n iterations

nFirst: int

Plot starting at iteration nStart

nLast: int

Plot up to iteration nLast

FigWidth: float

Figure width

FigHeight: float

Figure height

Outputs:
h: dict

Dictionary of figure/plot handles

Versions:

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

PlotTurbResid(**kw)

Plot the turbulence residual

Call:
>>> h = hist.PlotTurbResid(n=None, nFirst=None, nLast=None,
        **kw)
Inputs:
hist: cape.pyfun.databook.CaseResid

Instance of the DataBook residual history

n: int

Only show the last n iterations

nFirst: int

Plot starting at iteration nStart

nLast: int

Plot up to iteration nLast

FigWidth: float

Figure width

FigHeight: float

Figure height

Outputs:
h: dict

Dictionary of figure/plot handles

Versions:

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

get_filelist() → list

Get list of files to read

Call:
>>> filelist = h.get_filelist()
Inputs:
fm: CaseResid

Component iterative history instance

Outputs:
filelist: list[str]

List of files to read to construct iterative history

Versions:

  • 2024-01-23 @ddalle: v1.0; from old __init__()

get_flow_folder() → str

Get the working folder for primal solutions

This will be either "" (base dir) or "Flow"

Call:
>>> workdir = fm.get_flow_folder()
Inputs:
fm: CaseFM

Force & moment iterative history

Outputs:
workdir: "" | "Flow"

Current working folder for primal (flow) solutions

Versions:

  • 2024-01-23 @ddalle: v1.0

get_subiter_filelist() → list

Get list of files to read

Call:
>>> filelist = h.get_filelist()
Inputs:
fm: CaseResid

Component iterative history instance

Outputs:
filelist: list[str]

List of files to read to construct iterative history

Versions:

  • 2024-01-23 @ddalle: v1.0; from old __init__()

readfile(fname: str) → dict

Read a Tecplot iterative history file

Call:
>>> db = h.readfile(fname)
Inputs:
h: CaseResid

Case residual history instance

fname: str

Name of file to read

Outputs:
db: tsvfile.TSVTecDatFile

Data read from fname

Versions:

  • 2024-01-23 @ddalle: v1.0

readfile_subiter(fname: str) → dict

Read a Tecplot sub-iterative history file

These files, e.g. {PROJECT}_subhist.dat, are written when the solver is in time-accurate mode.

Call:
>>> db = fm.readfile_subhist(fname, di)
Inputs:
fm: CaseFM

Single-component iterative history instance

fname: str

Name of file to read

di: float | int

Iteration shift to correct for FUN3D counter restarts

Outputs:
db: tsvfile.TSVTecDatFile

Data read from fname

Versions:

  • 2024-01-23 @ddalle: v1.0 (readfile_subhist)

  • 2024-02-21 @ddalle: v2.0

class cape.pyfun.databook.DBComp(comp, cntl, targ=None, check=False, lock=False, **kw)
class cape.pyfun.databook.DBTarget(targ, x, opts, RootDir=None)
class cape.pyfun.databook.DBTriqFM(x, opts, comp, **kw)

Force and moment component extracted from surface triangulation

Call:
>>> DBF = DBTriqFM(x, opts, comp, RootDir=None)
Inputs:
x: cape.runmatrix.RunMatrix

RunMatrix/run matrix interface

opts: cape.options.Options

Options interface

comp: str

Name of TriqFM component

RootDir: {None} | st

Root directory for the configuration

Outputs:
DBF: cape.pyfun.databook.DBTriqFM

Instance of TriqFM data book

Versions:

  • 2017-03-28 @ddalle: v1.0

GetTriqFile()

Get most recent triq file and its associated iterations

Call:
>>> qtriq, ftriq, n, i0, i1 = DBF.GetTriqFile()
Inputs:
DBF: cape.pyfun.databook.DBTriqFM

Instance of TriqFM data book

Outputs:
qtriq: {False}

Whether or not to convert file from other format

ftriq: str

Name of triq file

n: int

Number of iterations included

i0: int

First iteration in the averaging

i1: int

Last iteration in the averaging

Versions:

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

  • 2024-12-03 @ddalle: v2.0; use CaseRunner method

PreprocessTriq(ftriq, **kw)

Perform any necessary preprocessing to create triq file

Call:
>>> DBL.PreprocessTriq(ftriq, i=None)
Inputs:
DBF: cape.pyfun.databook.DBTriqFM

Instance of TriqFM data book

ftriq: str

Name of triq file

i: {None} | int

Case index (else read from conditions.json)

Versions:

  • 2017-03-28 @ddalle: v1.0

class cape.pyfun.databook.DataBook(cntl, RootDir: str | None = None, targ: str | None = None, **kw)

This class provides an interface to the data book for a given CFD run matrix.

Call:
>>> DB = pyFun.databook.DataBook(x, opts)
Inputs:
x: cape.pyfun.runmatrix.RunMatrix

The current pyFun trajectory (i.e. run matrix)

opts: cape.pyfun.options.Options

Global pyFun options instance

Outputs:
DB: cape.pyfun.databook.DataBook

Instance of the pyFun data book class

ReadCaseFM(comp)

Read a CaseFM object

Call:
>>> FM = DB.ReadCaseFM(comp)
Inputs:
DB: cape.cfdx.databook.DataBook

Instance of data book class

comp: str

Name of component

Outputs:
FM: cape.pyfun.databook.CaseFM

Residual history class

Versions:

  • 2017-04-13 @ddalle: First separate version

ReadCaseResid()

Read a CaseResid object

Call:
>>> H = DB.ReadCaseResid()
Inputs:
DB: cape.cfdx.databook.DataBook

Instance of data book class

Outputs:
H: cape.pyfun.databook.CaseResid

Residual history class

Versions:

  • 2017-04-13 @ddalle: First separate version

ReadDBComp(comp, check=False, lock=False)

Initialize data book for one component

Call:
>>> DB.ReadDBComp(comp, check=False, lock=False)
Inputs:
DB: cape.pyfun.databook.DataBook

Instance of the pyCart data book class

comp: str

Name of component

check: True | {False}

Whether or not to check LOCK status

lock: True | {False}

If True, wait if the LOCK file exists

Versions:

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

  • 2016-06-27 @ddalle: v1.1; add targ keyword

  • 2017-04-13 @ddalle: v1.2; self-contained

ReadTriqFM(comp, check=False, lock=False)

Read a TriqFM data book if not already present

Call:
>>> DB.ReadTriqFM(comp)
Inputs:
DB: cape.pyfun.databook.DataBook

Instance of pyFun data book class

comp: str

Name of TriqFM component

check: True | {False}

Whether or not to check LOCK status

lock: True | {False}

If True, wait if the LOCK file exists

Versions:

  • 2017-03-28 @ddalle: v1.0

ReadTriqPoint(comp, check=False, lock=False, **kw)

Read a TriqPoint data book if not already present

Call:
>>> DB.ReadTriqPoint(comp, check=False, lock=False, **kw)
Inputs:
DB: cape.pyfun.databook.DataBook

Instance of pyFun data book class

comp: str

Name of TriqFM component

check: True | {False}

Whether or not to check LOCK status

lock: True | {False}

If True, wait if the LOCK file exists

pts: {None} | list[str]

List of points to read (default is read from DB.opts)

pt: {None} | str

Individual point to read

Versions:

  • 2017-03-28 @ddalle: v1.0

  • 2017-10-11 @ddalle: From ReadTriqFM()