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.update_dex() function.

from cape.pyfun.cntl import Cntl

# Read FUN3D control instance
cntl = Cntl("pyFun.json")
# Read the data book
db = read_dex("name_of_component")

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, runner: CaseRunner | None = None, **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

apply_moving_body()

Read and apply any moving-body data

Call:
>>> fm.apply_moving_body()
Inputs:
fm: CaseFM

Force & moment iterative history

Versions:

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

  • 2025-09-26 @ddalle: v1.1; add alpha, beta

  • 2025-10-15 @ddalle: v1.2; add (aoa|phi)[pv]

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

get_rotation_origin() → Point

Get rotation origin [history]

Call:
>>> x, y, z = fm.get_rotation_origin()
>>> p = fm.genr8_mrget_rotation_origin_history()
Inputs:
fm: CaseFM

Force & moment iterative history

Outputs:
x: np.ndarray | float

Coordinate of origin of rotation

y: np.ndarray | float

Coordinate of origin of rotation

z: np.ndarray | float

Coordinate of origin of rotation

p: cape.cfdx.casedata.Point

Named tuple object of p.x, p.y, p.z

Versions:

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

get_rotation_origin_x() → float

Get rotation origin from moving body

Call:
>>> x0 = fm.get_rotation_origin_x()
Inputs:
fm: CaseFM

Force & moment iterative history

Outputs:
x0: float

Coordinate of rotation point

Versions:

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

get_rotation_origin_y() → float

Get rotation origin from moving body

Call:
>>> y0 = fm.get_rotation_origin_y()
Inputs:
fm: CaseFM

Force & moment iterative history

Outputs:
y0: float

Coordinate of rotation point

Versions:

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

get_rotation_origin_z() → float

Get rotation origin from moving body

Call:
>>> z0 = fm.get_rotation_origin_z()
Inputs:
fm: CaseFM

Force & moment iterative history

Outputs:
z0: float

Coordinate of rotation point

Versions:

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

read_bodydat() → TSVTecDatFile | None

Read and return any moving-body data

Call:
>>> dat = fm.read_bodydat()
Inputs:
fm: CaseFM

Force & moment iterative history

Outputs:
dat: cape.dkit.tsvfile.TSVTecDatFile | None

Moving-body position data, if relevant and found

Versions:

  • 2025-09-25 @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, runner: CaseRunner, **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.CaseSurfCp(proj: str, comp: str, compid: str, ftriq: str, cntl: CntlBase, i: int, **kw)
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

class cape.pyfun.databook.CaseTS(proj: str, comp: str, **kw)
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