3.7.7. Data Book Definitions

The data book defines quantities that Cape tracks as results. It also allows for the definition of “Target” data for comparison to any CFD results. Data book components can be integrated forces and moments, point sensors, line loads, or potentially other subjects. The following JSON example shows some of the capabilities.

"DataBook": {
    // List of components or data book items
    "Components": ["fuselage", "wing", "tail", "engines", "P1"],
    // Number of iterations to use for statistics
    "nStats": 50,
    "nMin": 200,
    // Place to put the data book
    "Folder": "data"
    // Sorting order
    "Sort": ["mach", "alpha", "beta"],
    // Information for each component
    "fuselage": {
        "Type": "FM",
        "Targets": {"CA": "WT/CAFC", "CY": "WT/CY", "CN": "WT/CN"}
    },
    "wing":     {"Type": "FM"},
    "tail":     {"Type": "FM"},
    "engines":  {"Type": "Force"},
    // Information for a point sensor
    "P1": {
        "Type": "PointSensor",
        "Points": ["P101", "P102"],
        "nStats": 20
    },
    // Target data from a wind tunnel
    "Targets": {
        "WT": {
            "File": "data/wt.csv",
            "RunMatrix": {"mach": "Mach"},
            "Tolerances": {
                "mach": 0.02, "alpha": 0.25, "beta": 0.1
            }
        }
    }
}

Links to default options for each specific solver are found below.

3.7.7.1. General Data Book Definitions

The following dictionary of options describes the general definitions of the data book. These are applicable to any data book for any of the solvers.

Components: list (str)

List of components to analyze and create data book entries for

nStats: [ {1} | int ]

Number of iterations to use for computing statistics (such as mean, iterative history min and max, and standard deviation)

nMin: [ {0} | int ]

Minimum iteration number allowed for inclusion in results and statistics; a case must have at least nMin+nStats iterations for inclusion in the data book

nMaxStats: [ {None} | int ]

Optional parameter for maximum number of iterations for inclusion in statistics; Cape will use nStats<=n<=nMaxStats iterations based on its estimate of resulting iterative uncertainty

Folder: str

Location in which to store data book (relative to JSON root)

Sort: str | list (str)

RunMatrix key(s) on which to sort data book (in reverse order if a list); ignored if not the name of a trajectory variable

Each component in Components can be either a force, moment, force & moment, point sensor, or alternative data type defined for specific solvers. For each force and/or moment component, a file such as aero_fuselage.csv, aero_wing.csv, etc. is created in the location specified by Folder. The Folder is created if necessary when reading/writing the data book.

Point sensor components create files such as pt_P101.csv and pt_P102.csv in the same directory.

The Sort option, if specified, is used by Cape to sort he lines of the data book files before writing to file. Without a Sort key, lines in the data book files are written in the order in which they were processed.

3.7.7.2. Data Book Component Definitions

Each data book component has at least the following possible options. Additional components may have more options that are not defined in this universal context.

The values for nStats, nMin, and nMaxStats are optional and will default to those from the general data book. This capability enables users to specify different values of these parameters for different components.

comp: dict

Definition for individual component comp

Type: {"FM"} | str

Type of component being tracked

Coefficients: list (str)

List of coefficients for this component

Transformations: {[]} | list (dict)

List of transformation dictionaries

Targets: {{}} | T | dict (str)

Dictionary of column names for target values

nStats: [ {1} | int ]

Number of iterations to use for computing statistics

nMin: [ {0} | int ]

Minimum iteration number allowed for inclusion in results

nMaxStats: [ {None} | int ]

Maximum number of iterations for inclusion in statistics

CA: {["mu","min","max","std","err"]} | list (str)

List of statistical properties for coefficient CA

Cp: {["mu","std","min","max"]} | list (str)

List of statistical properties for coefficient Cp

Each coefficient can have a list of statistical properties defined for it. The example above only lists CA and Cp, but this may be defined for any coefficient defined in the Coefficients section.

3.7.7.2.1. Data Book Transformations

Each data book may have a list of transformations. This may be useful, for example, if a component has been rotated with respect to the CFD axes, and the forces and moments, which have been recorded in the CFD axes, need to be transformed to reflect the correct values in the body frame of the rotated component. Another example is that moment coefficients are often recorded about the opposite-direction x and z axes, and so it is necessary to multiply the values of CLL and CLN by -1.

Transformations: [E] | [S] | list (dict)

List of data transformations

E: dict

Definition for an Euler 3-2-1 transformation

Type: "Euler321"

Specify the transformation type

phi: {"phi"} | "-phi" | str

Name of the trajectory variable to use for the roll angle transformation value

theta: {"theta"} | "-theta" | str

Name of the trajectory variable to use for the pitch angle transformation value

psi: {"psi"} | "-psi" | str

Name of the trajectory variable to use for the yaw angle transformation value

S: dict

Definition for coefficient scaling

Type: "ScaleCoeffs"

Specify the transformation type

CA: {1.0} | float

Scale factor by which to multiply CA values

CY: {1.0} | -1.0 | float

Scale factor by which to multiply CY values

CLL: 1.0 | {-1.0} | float

Scale factor by which to multiply CLL values

CLN: 1.0 | {-1.0} | float

Scale factor by which to multiply CLN values

3.7.7.2.2. Data Book Component Target Definitions

Defining target values for a data book component is relatively straightforward. The target data book, defined below, may use column names differing from CA, CY, etc., and this section is used to specify what columns to use. By default, Cape will try to compare to a target value from the first target defined; to be more explicit, one can use a forward slash to specify both which target to use and which column within that target. For example, to use a column named CAFC in target WT use "WT/CAFC" in the JSON file.

Targets: {{}} | T | dict (str)

Dictionary of column names for target values

T: dict

Dictionary of target values

CA: {"CA"} | targ/col | str

Name of column for target CA value; column col from target targ where targ defaults to first column if this field does not contain a forward slash

Cp: {"Cp"} | targ/col | str

Name of column for target Cp value; column col from target targ where targ defaults to first column if this field does not contain a forward slash

3.7.7.2.3. Force and Moment Data Book Components

The following dictionary fills in some of the values applicable to force and moment objects. It is a more specific version of the more general dictionary.

comp: dict

Definition for individual component comp

Type: {"FM"} | "Force" | "Moment"

Type of component being tracked

Coefficients: list (str)

List of coefficients for this component

Transformations: {[S]} | list (dict)

List of transformation dictionaries

S: dict

Transformation dictionary

Type: {"ScaleCoeffs"} | "Euler321"

Transformation type

Targets: {{}} | T | dict (str)

Dictionary of column names for target values

CA: {["mu","min","max","std","err"]} | list (str)

List of statistical properties for axial force coefficient

CY: {["mu","min","max","std","err"]} | list (str)

List of statistical properties for lateral force coefficient

CN: {["mu","min","max","std","err"]} | list (str)

List of statistical properties for normal force coefficient

CLL: {["mu","min","max","std","err"]} | list (str)

List of statistical properties for rolling moment coefficient

CLM: {["mu","min","max","std","err"]} | list (str)

List of statistical properties for pitching moment coefficient

CLN: {["mu","min","max","std","err"]} | list (str)

List of statistical properties for yawing moment coefficient

CL: {["mu","min","max","std","err"]} | list (str)

List of statistical properties for lift coefficient

CD: {["mu","min","max","std","err"]} | list (str)

List of statistical properties for drag coefficient

3.7.7.2.4. Point Sensor Data Book Components

The following dictionary fills in some of the values applicable to point sensor objects. It is a more specific version of the more general dictionary. Furthermore, the list of available coefficients and their particular interpretation varies from solver to solver.

comp: dict

Definition for individual component comp

Type: {"TriqPoint"} | "Point"

Type of component being tracked

Coefficients: list (str)

List of coefficients for this component

Targets: {{}} | T | dict (str)

Dictionary of column names for target values

Cp: {["mu","std","min","max"]} | list (str)

List of statistical properties for pressure coefficient

M: {["mu","std","min","max"]} | list (str)

List of statistical properties for Mach number

rho: {["mu","std","min","max"]} | list (str)

Statistical properties for density or nondimensional density

p: {["mu","std","min","max"]} | list (str)

Statistical properties for pressure or nondimensional pressure

T: {["mu","std","min","max"]} | list (str)

Statistical properties for temperature or nondimensional temperature

3.7.7.3. Target or Comparison Data Sources

The Targets key is an optional parameter that points to another data source (or multiple other data sources) for use as a reference value both in the data book files and plots. Each “Target” is read from a single file that contains columns used to map points in that file to run matrix conditions and one or more force/moment coefficients for one or more components in the data book. The list of Targets parameters is given below.

Targets: {{}} | {targ: T} | dict (dict)

List of target dict descriptions

targ: str

Name of target

T: dict

Individual target description

Label: str

Label to be used for this data source, e.g. in plot legends; defaults to value of Name option

File: str

File name of the data source

Delimiter: {", "} | "," | " " | str

Delimiter to be used when reading/writing data book files

Comment: {"#"} | str

Character used to denote comment line in source file

Components: list (str)

List of components to which this target file applies; default is all components in the data book

RunMatrix: dict (str)

Dictionary of column names for trajectory variables to be used for comparing trajectory cases to target data points. Any case that has matching values for all keys listed in this dict will be considered to be at matching conditions

Tolerances: dict (float)

Dictionary of tolerances for matching rows of the target to data book points. For example, including "mach": 0.02" means the target data point can differ in Mach number from the Cape data book point by up to 0.02 (inclusive)

All targets are generally available to any report subfigure, but the user can specify certain targets to correspond to certain databook components by adding target information to the databook component definition. The full set of options is described above, but an example is helpful. The following is a sample definition for two "FM" components called "STACK_No_Aft" and "STACK_No_Base".

"STACK_No_Aft": {
    "Type": "FM",
    "Targets": {
        "CA": ["CAF", "rev6/CA", "Forebody/CA", "Mimic/CA"]
    }
},
"STACK_No_Base": {
    "Type": "FM",
    "Targets": {
        "CY":  ["CYF",  "rev6/CY",  "Forebody/CY",  "Mimic/CY"],
        "CN":  ["CNF",  "rev6/CN",  "Forebody/CN",  "Mimic/CN"],
        "CLL": ["CLLF", "rev6/CLL", "Forebody/CLL", "Mimic/CLL"],
        "CLM": ["CLMF", "rev6/CLM", "Forebody/CLM", "Mimic/CLM"],
        "CLN": ["CLNF", "rev6/CLN", "Forebody/CLN", "Mimic/CLN"]
    }
}

This means that the CA from STACK_No_Aft can only be compared to CA results, namely any column called CAF (a common wind tunnel data name for axial force coefficient) or any column called CA from targets rev6, Forebody, or Mimic. This prevents STACK_No_Aft data from matching CA results from any other targets.

Similarly, the other five force & moment coefficients are set up to show up on plots of STACK_No_Base instead.