cape.cfdx.casedata: Single-case data interfaces¶
This module provides the classes CaseFM and
CaseResid that resid iterative histories of various types.
- class cape.cfdx.casedata.CaseData(meta: bool = False, **kw)¶
Base class for case iterative histories
- Call:
>>> fm = CaseData()
- Outputs:
- fm:
cape.cfdx.databook.CaseData Base iterative history class
- fm:
- Versions:
2015-12-07
@ddalle: v1.02024-01-10
@ddalle: v2.0
- ExtractValue(c: str, col=None, **kw)¶
Extract the iterative history for one coefficient/state
This function may be customized for some modules
- Call:
>>> C = fm.Extractvalue(c) >>> C = fm.ExtractValue(c, col=None)
- Inputs:
- Outputs:
- C:
np.ndarray Values for c at each iteration or sample interval
- C:
- Versions:
2015-12-07
@ddalle: v1.02024-01-10
@ddalle: v2.0, CaseFM -> DataKit
- GetIterationIndex(i: int)¶
Return index of a particular iteration in fm.i
If the iteration i is not present in the history, the index of the last available iteration less than or equal to i is returned.
- Call:
>>> j = fm.GetIterationIndex(i)
- Inputs:
- fm:
cape.cfdx.databook.CaseData Case component history class
- i:
int Iteration number
- fm:
- Outputs:
- j:
int Index of last iteration less than or equal to i
- j:
- Versions:
2015-03-06
@ddalle: v1.0 (CaseFM)2015-12-07
@ddalle: v1.02024-01-11
@ddalle: v1.1; use keys instead of attrs
- PlotValue(c: str, col=None, n=None, **kw)¶
Plot an iterative history of some value named c
- Call:
>>> h = fm.PlotValue(c, n=None, **kw)
- Inputs:
- fm:
cape.cfdx.databook.CaseData Case component history class
- c:
str Name of coefficient to plot, e.g.
'CA'- col:
str|int|None Select a column by name or index
- n:
int Only show the last n iterations
- nMin: {
0} |int First iteration allowed for use in averaging
- nAvg, nStats: {
100} |int Use at least the last nAvg iterations to compute an average
- dnAvg, dnStats: {nStats} |
int Use intervals of dnStats iterations for candidate windows
- nMax, nMaxStats: {nStats} |
int Use at most nMax iterations
- d:
float Delta in the coefficient to show expected range
- k:
float Multiple of iterative standard deviation to plot
- u:
float Multiple of sampling error standard deviation to plot
- err:
float Fixed sampling error, def uses
util.SearchSinusoidFit()- nLast:
int Last iteration to use (defaults to last iteration available)
- nFirst:
int First iteration to plot
- FigureWidth:
float Figure width
- FigureHeight:
float Figure height
- PlotOptions:
dict Dictionary of additional options for line plot
- StDevOptions:
dict Options passed to
plt.fill_between()for stdev plot- ErrPltOptions:
dict Options passed to
plt.fill_between()for uncertainty plot- DeltaOptions:
dict Options passed to
plt.plot()for reference range plot- MeanOptions:
dict Options passed to
plt.plot()for mean line- ShowMu:
bool Option to print value of mean
- ShowSigma:
bool Option to print value of standard deviation
- ShowError:
bool Option to print value of sampling error
- ShowDelta:
bool Option to print reference value
- MuFormat: {
"%.4f"} |str Format for text label of the mean value
- DeltaFormat: {
"%.4f"} |str Format for text label of the reference value d
- SigmaFormat: {
"%.4f"} |str Format for text label of the iterative standard deviation
- ErrorFormat: {
"%.4f"} |str Format for text label of the sampling error
- XLabel:
str Specified label for x-axis, default is
I"teration Number"- YLabel:
str Specified label for y-axis, default is c
- Grid: {
None} |True|False Turn on/off major grid lines, or leave as is if
None- GridStyle: {
{}} |dict Dictionary of major grid line line style options
- MinorGrid: {
None} |True|False Turn on/off minor grid lines, or leave as is if
None- MinorGridStyle: {
{}} |dict Dictionary of minor grid line line style options
- Ticks: {
None} |False Turn off ticks if
False- XTicks: {Ticks} |
None|False|list x-axis tick levels, turn off if
Falseor[]- YTicks: {Ticks} |
None|False|list y-axis tick levels, turn off if
Falseor[]- TickLabels: {
None} |False Turn off tick labels if
False- XTickLabels:{
None} |False|list x-axis tick labels, turn off if
Falseor[]- YTickLabels: {
None} |False|list y-axis tick labels, turn off if
Falseor[]
- fm:
- Outputs:
- h:
dict Dictionary of figure/plot handles
- h:
- Versions:
2014-11-12
@ddalle: v1.02014-12-09
@ddalle: v1.1; move toAeroPlotclass2015-02-15
@ddalle: v1.2; move toAeroclass2015-03-04
@ddalle: v1.3; add nStart and nLast2015-12-07
@ddalle: v1.4; move toCaseData2017-10-12
@ddalle: v1.5; add grid and tick options2024-01-10
@ddalle: v1.6; DataKit updates
- PlotValueHist(coeff: str, nAvg=100, nLast=None, **kw)¶
Plot a histogram of the iterative history of some value c
- Call:
>>> h = fm.PlotValueHist(comp, c, n=1000, nAvg=100, **kw)
- Inputs:
- fm:
cape.cfdx.databook.CaseData Instance of the component force history class
- comp:
str Name of component to plot
- c:
str Name of coefficient to plot, e.g.
'CA'- nAvg:
int Use the last nAvg iterations to compute an average
- nBins: {
20} |int Number of bins in histogram, also can be set in HistOptions
- nLast:
int Last iteration to use (defaults to last iteration available)
- fm:
- Keyword Arguments:
- FigureWidth:
float Figure width
- FigureHeight:
float Figure height
- Label: [ {comp} |
str] Manually specified label
- TargetValue:
float|list[float] Target or list of target values
- TargetLabel:
str|list(str) Legend label(s) for target(s)
- StDev: [ {None} |
float] Multiple of iterative history standard deviation to plot
- HistOptions:
dict Plot options for the primary histogram
- StDevOptions:
dict Dictionary of plot options for the standard deviation plot
- DeltaOptions:
dict Options passed to
plt.plot()for reference range plot- MeanOptions:
dict Options passed to
plt.plot()for mean line- TargetOptions:
dict Options passed to
plt.plot()for target value lines- OutlierSigma: {
7.0} |float Standard deviation multiplier for determining outliers
- ShowMu:
bool Option to print value of mean
- ShowSigma:
bool Option to print value of standard deviation
- ShowError:
bool Option to print value of sampling error
- ShowDelta:
bool Option to print reference value
- ShowTarget:
bool Option to show target value
- MuFormat: {
"%.4f"} |str Format for text label of the mean value
- DeltaFormat: {
"%.4f"} |str Format for text label of the reference value d
- SigmaFormat: {
"%.4f"} |str Format for text label of the iterative standard deviation
- TargetFormat: {
"%.4f"} |str Format for text label of the target value
- XLabel:
str Specified label for x-axis, default is
Iteration Number- YLabel:
str Specified label for y-axis, default is c
- FigureWidth:
- Outputs:
- h:
dict Dictionary of figure/plot handles
- h:
- Versions:
2015-02-15
@ddalle: v1.02015-03-06
@ddalle: v1.1; add nLast2015-03-06
@ddalle: v1.2; change class2024-01-10
@ddalle: v1.3; DataKit updates
- append_casedata(data: dict, jsrc=None, typ='raw')¶
Append data read from a single file
- Call:
>>> h.append_casedata(data, jsrc=None, typ="raw")
- Inputs:
- Versions:
2024-01-22
@ddalle: v1.02024-02-21
@ddalle: v1.1; add typ2024-06-24
@ddalle: v1.2; call trim_repeat_iters()
- apply_mask(mask=None, parent: str = 'i')¶
Remove subset of iterative history
- Call:
>>> h.apply_mask(mask, parent="i")
- Inputs:
- h:
CaseData Single-case iterative history instance
- mask:
np.ndarray[bool|int] Optional mask of which cases to keep
- parent: {
"i"} |str Name of iterations column
- h:
- Versions:
2024-01-22
@ddalle: v1.02024-02-20
@ddalle: v1.1; add parent
- apply_mask_iters(mask: ndarray)¶
Apply a mask to simple iteration history
- Call:
>>> db.apply_mask_iters(mask)
- Inputs:
- db:
cape.cfdx.casedata.CaseData Single-case iterative history interface
- mask:
np.ndarray[int|bool] Mask of indices or booleans of which to keep
- db:
- Versions:
2025-07-31
@ddalle: v1.0
- init_empty()¶
Create empty CaseFM instance
- Call:
>>> h.init_empty()
- Inputs:
- h:
CaseData Single-case iterative history index
- h:
- Versions:
2015-10-16
@ddalle: v1.02023-01-11
@ddalle: v2.0; DataKit updates2024-01-22
@ddalle: v2.1; use class attributes
- init_sourcefiles(meta: bool = False)¶
Initialize file name list and metadata
- Call:
>>> h.init_sourcefiles(meta=False)
- Inputs:
- h:
CaseData Single-case iterative history instance
- meta:
True| {False} Option to only read metadata (skip subiterations)
- h:
- Versions:
2024-01-22
@ddalle: v1.02024-02-21
@ddalle: v1.1; add subiteration hooks2025-08-05
@ddalle: v1.2; add meta
- process_sourcefile(fname: str)¶
Read data from a file (if necessary)
In most cases, developers will NOT nead to customize this function for each application or for each solver.
- process_subiter_sourcefile(fname: str)¶
Read data from a subiteration history file (if necessary)
In most cases, developers will NOT nead to customize this function for each application or for each solver.
- read()¶
Read iterative histroy from all sources
This will first attempt to read the cached histroy from a
.cdbfile and then ready any raw solver output files as necessary.- Call:
>>> h.read()
- Inputs:
- h:
CaseData Single-case iterative history instance
- h:
- Versions:
2024-01-22
@ddalle: v1.02024-02-21
@ddalle: v1.1; add subiteration hooks
- read_cdb()¶
Read contents of history from
.cdbfileSee
capefilemodule. The name of the file will bef"cape/fm_{fm.comp}.cdb".- Call:
>>> fm.read_cdb()
- Inputs:
- fm:
CaseData Iterative history instance
- fm:
- Versions:
2024-01-20
@ddalle: v1.02024-01-22
@ddalle: v1.1; _special_cols check
- readfile(fname: str) dict¶
Read raw data solver file and return a dict
This method needs to be customized for each individual solver.
- readfile_lastiter(fname: str) float¶
Estimate the last iteration of a data file
The purpose of this function is to determine if the file fname needs to be read. If negative, the file is always read.
This function should be customized for each subclass. However, if it isn’t, that just means the latest raw data file written by the solver is always read.
- readfile_subiter(fname: str) dict¶
Read raw data subiteration solver file and return a dict
This method needs to be customized for each individual solver.
- trim_iters()¶
Trim iters that are followed by later restart at lower iter
If a previous case continues past its last restart, the history may contain some iterations that get overwritten during the next run.
- Call:
>>> fm.trim_iters()
- Inputs:
- fm:
CaseData Single-case iterative history instance
- fm:
- Versions:
2024-08-09
@ddalle: v1.0
- class cape.cfdx.casedata.CaseFM(comp: str, **kw)¶
Force and moment iterative histories
This class contains methods for reading data about an the histroy of an individual component for a single case.
- Call:
>>> fm = cape.cfdx.databook.CaseFM(C, MRP=None, A=None)
- Inputs:
- Outputs:
- Versions:
2014-11-12
@ddalle: Starter version2014-12-21
@ddalle: Copied from previous aero.FM
- AddData(A: dict)¶
Add iterative force and/or moment history for a component
- Call:
>>> fm.AddData(A)
- Inputs:
- fm:
cape.cfdx.databook.CaseFM Instance of the force and moment class
- A:
numpy.ndarrayshape=(N,4) or shape=(N,7) Matrix of forces and/or moments at N iterations
- fm:
- Versions:
2014-11-12
@ddalle: v1.02015-10-16
@ddalle: v2.0; complete rewrite2024-01-10
@ddalle: v2.1; simplify using DataKit
- Copy()¶
Copy an iterative force & moment history
- Call:
>>> fm2 = FM1.Copy()
- Inputs:
- FM1:
cape.cfdx.databook.CaseFM Force and moment history
- FM1:
- Outputs:
- FM2:
cape.cfdx.databook.CaseFM Copy of FM1
- FM2:
- Versions:
2017-03-20
@ddalle: v1.02024-01-10
@ddalle: v2.0; simplify using DataKit
- GetStats(nStats=100, nMax=None, **kw)¶
Get mean, min, max, and stdev for all coefficients
- Call:
>>> s = fm.GetStats(nStats, nMax=None, nLast=None)
- Inputs:
- fm:
cape.cfdx.databook.CaseFM Instance of the force and moment class
- coeff:
str Name of coefficient to process
- nStats: {
100} |int Min number of iterations in window to use for statistics
- dnStats: {nStats} |
int Interval size for candidate windows
- nMax: (nStats} |
int Maximum number of iterations to use for statistics
- nMin: {
0} |int First usable iteration number
- nLast: {fm.i[-1]} |
int Last iteration to use for statistics
- fm:
- Outputs:
- Versions:
2017-09-29
@ddalle: v1.02024-01-10
@ddalle: v1.1; DataKit updates
- GetStatsCoeff(coeff, nStats=100, nMax=None, **kw)¶
Get mean, min, max, and other statistics for one coefficient
- Call:
>>> s = fm.GetStatsCoeff(coeff, nStats=100, nMax=None, **kw)
- Inputs:
- fm:
cape.cfdx.databook.CaseFM Instance of the force and moment class
- coeff:
str Name of coefficient to process
- nStats: {
100} |int Min number of iterations in window to use for statistics
- dnStats: {nStats} |
int Interval size for candidate windows
- nMax: (nStats} |
int Maximum number of iterations to use for statistics
- nMin: {
0} |int First usable iteration number
- nLast: {fm.i[-1]} |
int Last iteration to use for statistics
- fm:
- Outputs:
- Versions:
2017-09-29
@ddalle: v1.02024-01-10
@ddalle: v1.1; DataKit updates
- GetStatsN(nStats=100, nLast=None)¶
Get mean, min, max, and standard deviation for all coefficients
- Call:
>>> s = fm.GetStatsN(nStats, nLast=None)
- Inputs:
- Outputs:
- Versions:
2014-12-09
@ddalle: v1.02015-02-28
@ddalle: v1.1; wasGetStats()2015-03-04
@ddalle: v1.2; add nLast2024-01-10
@ddalle: v1.3; DataKit updates
- GetStatsOld(nStats=100, nMax=None, nLast=None)¶
Get mean, min, max, and standard deviation for all coefficients
- Call:
>>> s = fm.GetStatsOld(nStats, nMax=None, nLast=None)
- Inputs:
- Outputs:
- Versions:
2015-02-28
@ddalle: v1.02015-03-04
@ddalle: v1.1; add nLast2024-01-10
@ddalle: v1.2; DataKit updates
- PlotCoeff(c: str, n=None, **kw)¶
Plot a single coefficient history
- Call:
>>> h = fm.PlotCoeff(c, n=1000, nAvg=100, **kw)
- Inputs:
- fm:
cape.cfdx.databook.CaseFM Instance of the component force history class
- c:
str Name of coefficient to plot, e.g.
'CA'- n:
int Only show the last n iterations
- nAvg:
int Use the last nAvg iterations to compute an average
- d:
float Delta in the coefficient to show expected range
- nLast:
int Last iteration to use (defaults to last iteration available)
- nFirst:
int First iteration to plot
- FigureWidth:
float Figure width
- FigureHeight:
float Figure height
- fm:
- Outputs:
- h:
dict Dictionary of figure/plot handles
- h:
- Versions:
2014-11-12
@ddalle: v1.02014-12-09
@ddalle: Transferred toAeroPlot2015-02-15
@ddalle: Transferred todatabook.Aero2015-03-04
@ddalle: Added nStart and nLast2015-12-07
@ddalle: Moved content to base class
- PlotCoeffHist(c: str, nAvg=100, nBin=20, nLast=None, **kw)¶
Plot a single coefficient histogram
- Call:
>>> h = fm.PlotCoeffHist(comp, c, n=1000, nAvg=100, **kw)
- Inputs:
- fm:
cape.cfdx.databook.CaseFM Instance of the component force history class
- comp:
str Name of component to plot
- c:
str Name of coefficient to plot, e.g.
'CA'- nAvg:
int Use the last nAvg iterations to compute an average
- nBin:
int Number of bins to plot
- nLast:
int Last iteration to use (defaults to last iteration available)
- FigureWidth:
float Figure width
- FigureHeight:
float Figure height
- fm:
- Keyword arguments:
See
cape.cfdx.databook.CaseData.PlotValueHist()
- Outputs:
- h:
dict Dictionary of figure/plot handles
- h:
- Versions:
2015-02-15
@ddalle: v1.02015-03-06
@ddalle: Added nLast and fixed documentation2015-03-06
@ddalle: Copied toCaseFM
- ShiftMRP(Lref, x, xi=None)¶
Shift the moment reference point
- TransformFM(topts: dict, x: dict, i: int)¶
Transform a force and moment history
Available transformations and their parameters are listed below.
“Euler321”: “psi”, “theta”, “phi”
“Euler123”: “phi”, “theta”, “psi”
“ScaleCoeffs”: “CA”, “CY”, “CN”, “CLL”, “CLM”, “CLN”
RunMatrix variables are used to specify values to use for the transformation variables. For example,
topts = {"Type": "Euler321", "psi": "Psi", "theta": "Theta", "phi": "Phi"}
will cause this function to perform a reverse Euler 3-2-1 transformation using x.Psi[i], x.Theta[i], and x.Phi[i] as the angles.
Coefficient scaling can be used to fix incorrect reference areas or flip axes. The default is actually to flip CLL and CLN due to the transformation from CFD axes to standard flight dynamics axes.
tops = {"Type": "ScaleCoeffs", "CLL": -1.0, "CLN": -1.0}
- TrimIters()¶
Trim non-ascending iterations and other problems
- Call:
>>> fm.TrimIters()
- Versions:
2017-10-02
@ddalle: v1.02024-01-10
@ddalle: v2.0; DataKit updates
- trim_iters()¶
Trim any repeated iterations from history
- Call:
>>> db.trim_iters()
- Inputs:
- db;
cape.cfdx.casedata.CaseData Single-case iterative history
- db;
- Versions:
2025-07-31
@ddalle: v1.0
- class cape.cfdx.casedata.CaseResid(meta: bool = False, **kw)¶
Iterative residual history class
This class provides an interface to residuals, CPU time, and similar data for a given run directory
- Call:
>>> hist = cape.cfdx.databook.CaseResid()
- Outputs:
- hist:
cape.cfdx.databook.CaseResid Instance of the run history class
- hist:
- GetIterationIndex(i)¶
Return index of a particular iteration in hist.i
If the iteration i is not present in the history, the index of the last available iteration less than or equal to i is returned.
- GetNOrders(nStats: int = 1, col: str | None = None, nLast: int | None = None) float¶
Get the number of orders of magnitude of residual drop
- Call:
>>> nOrders = hist.GetNOrders(nStats=None, col=None)
- Inputs:
- Outputs:
- nOrders: {
1} |float Number of orders of magnitude of residual drop
- nOrders: {
- Versions:
2015-01-01
@ddalle: v1.02024-01-24
@ddalle: v2.0; generalize w/ DataKit apprch2025-08-05
@ddalle: v2.1; add nLast
- GetNOrdersUnsteady(n=1)¶
Get residual drop magnitude
- Call:
>>> nOrders = hist.GetNOrders(n=1)
- Inputs:
- hist:
cape.cfdx.databook.CaseResid Instance of the DataBook residual history
- n:
int Number of iterations to analyze
- hist:
- Outputs:
- nOrders:
numpy.ndarray[float] Number of orders of magnitude of unsteady residual drop
- nOrders:
- Versions:
2015-01-01
@ddalle: First version
- PlotL1(n=None, nFirst=None, nLast=None, **kw)¶
Plot the L1 residual
- Call:
>>> h = hist.PlotL1(n=None, nFirst=None, nLast=None, **kw)
- Inputs:
- Outputs:
- h:
dict Dictionary of figure/plot handles
- h:
- Versions:
2014-11-12
@ddalle: v1.02014-12-09
@ddalle: v1.1; move toAeroPlot2015-02-15
@ddalle: v1.2; move todatabook.Aero2015-03-04
@ddalle: v1.3; add nStart and nLast2015-10-21
@ddalle: v1.4; refer toPlotResid()
- PlotL2(n=None, nFirst=None, nLast=None, **kw)¶
Plot the L2 residual
- Call:
>>> h = hist.PlotL2(n=None, nFirst=None, nLast=None, **kw)
- Inputs:
- Outputs:
- h:
dict Dictionary of figure/plot handles
- h:
- Versions:
2014-11-12
@ddalle: v1.02014-12-09
@ddalle: v1.1; move toAeroPlot2015-02-15
@ddalle: v1.2; move todatabook.Aero2015-03-04
@ddalle: v1.3; add nStart and nLast2015-10-21
@ddalle: v1.4; refer toPlotResid()
- PlotLInf(n=None, nFirst=None, nLast=None, **kw)¶
Plot the L-infinity residual
- Call:
>>> h = hist.PlotLInf(n=None, nFirst=None, nLast=None, **kw)
- Inputs:
- Outputs:
- h:
dict Dictionary of figure/plot handles
- h:
- Versions:
2016-02-04
@ddalle: v1.0
- PlotResid(c='L1Resid', n=None, nFirst=None, nLast=None, **kw)¶
Plot a residual by name
- Call:
>>> h = hist.PlotResid(c='L1Resid', n=None, **kw)
- Inputs:
- hist:
cape.cfdx.databook.CaseResid Instance of the DataBook residual history
- c:
str Name of coefficient to plot
- n:
int Only show the last n iterations
- PlotOptions:
dict Plot options for the primary line(s)
- nFirst:
int Plot starting at iteration nStart
- nLast:
int Plot up to iteration nLast
- FigureWidth:
float Figure width
- FigureHeight:
float Figure height
- YLabel:
str Label for y-axis
- hist:
- Outputs:
- h:
dict Dictionary of figure/plot handles
- h:
- Versions:
2014-11-12
@ddalle: v1.02014-12-09
@ddalle: v1.1; move toAeroPlot2015-02-15
@ddalle: v1.2; move todatabook.Aero2015-03-04
@ddalle: v1.3; add nStart and nLast2015-10-21
@ddalle: v1.4; fromPlotL1()2022-01-28
@ddalle: v1.5; add xcol
- find_subiters(col: str = 'i_sub')¶
Find indices of first and last subiter for each whole iter
- Call:
>>> maska, maskb = hist.find_subiters(col=None)
- Inputs:
- Outputs:
- maska:
np.ndarray[int] Index of first subiter for each whole iter
- maskb:
np.ndarray[int] Index of last subiter for each whole iter
- maska:
- Versions:
2024-07-18
@ddalle: v1.0
- class cape.cfdx.casedata.CaseTS(comp: str, **kw)¶
Force and moment time series iterative histories
This class contains methods for reading data about an the histroy of an individual component for a single case.
- Call:
>>> fm = cape.cfdx.databook.CaseFM(C, MRP=None, A=None)
- Inputs:
- Outputs:
- Versions:
2024-10-09
@aburkhea: Started
- class cape.cfdx.casedata.DBPlotOpts(*args, **kw)¶
- cape.cfdx.casedata.ImportPyPlot()¶
Import
matplotlib.pyplotif not already loaded- Call:
>>> ImportPyPlot()
- Versions:
2014-12-27
@ddalle: v1.0
