Ptable Reference

Table of contents

Introduction

A Ptable is a class whose instances represent an aircraft performance table or graph. The performance table or graph may have one or more dimensions. Each Ptable instance has input parameters for each dimension and a single output. The interpolate() method takes a series of values, one for each input, and does a multi-way interpolation of the input values against the values in the performance tables and produces a single output value.

A Ptable instance is created by passing an info object argument with properties that describe the title, the inputs, the output, and the performance table data. For example, the following is a Climb Rate table from a Cessna 172S:

Pressure Altitude -20°C 0°C 20°C 40°C
Sea Level 855 785 710 645
2,000 760 695 625 560
4,000 685 620 555 495
6,000 575 515 450 390
8,000 465 405 345 285
10,000 360 300 240 180
12,000 255 195 135 -

The Climb Rate table can be captured as:

new Ptable({
	title: `Max rate climb rate`,
	inputs: [
		{key:'oat', limit:'clampLo'},
		{key:'pressureAltitude', limit:'clampLo'},
	],
	output: {key:'climbRate', rndMult:'5d'},
	a: [
		{p:-20, a: [
			{p:0,		v:855},
			{p:2000,	v:760},
			{p:4000,	v:685},
			{p:6000,	v:575},
			{p:8000,	v:465},
			{p:10000,	v:360},
			{p:12000,	v:255}
		]},
		{p:0, a: [
			{p:0,		v:785},
			{p:2000,	v:695},
			{p:4000,	v:620},
			{p:6000,	v:515},
			{p:8000,	v:405},
			{p:10000,	v:300},
			{p:12000,	v:195}
		]},
		{p:20, a: [
			{p:0,		v:710},
			{p:2000,	v:625},
			{p:4000,	v:555},
			{p:6000,	v:450},
			{p:8000,	v:345},
			{p:10000,	v:240},
			{p:12000,	v:135}
		]},
		{p:40, a: [
			{p:0,		v:645},
			{p:2000,	v:560},
			{p:4000,	v:495},
			{p:6000,	v:390},
			{p:8000,	v:285},
			{p:10000,	v:180}
		]}
	],
});

The title property describes the table. It is mainly used for documenting the table contents, error messages, and debugging. The inputs property is an array that defines each input parameter. You can provide input parameters in any order, but the order used in the inputs property must be consistent with the order in which the data is encoded.

The interpolate() method also takes an optional options argument, which adjusts the interpolation request's characteristics.

Data encoding

The data is encoded as arrays of objects with subarrays for the next dimension in the chosen order. All arrays and sub-arrays are under an a key, and input parameter values are under a p key. An object with a p key may have a single output value under a v key or a subarray under an a key. Note that single-letter keys are used because keys get very repetitive in large tables with many dimensions.

The numeric values of the p property within a array elements must either be monotonically increasing or decreasing. No ordering of string p values is required.

If a Ptable has a v property instead of an a property, it returns a single value regardless of input. This is useful in cases where some aircraft models have a varying value, and some have a single fixed value. For example, this often happens for maneuvering airspeed (Va), where older models have a fixed value while newer models specify a value that varies with weight.

Parameters can also be strings. For example, a takeoff distance table:

new Ptable({
	title: `Landing distance`,
	inputs: [
		{key:'flaps'},
		...
	],
	output: {key:'distance', rndMult:'10u'},
	a: [
		{p:'landing', a: [
			...
		]},
		{p:'partial', a: [
			...
		]},
	],
});

Interpolation

The Ptable interpolate() method has the signature:

interpolate(input, options)

Both arguments are objects. The options argument is optional and modifies the behavior of the interpolation. The input object has properties for each key in the inputs array. The object may have other properties; they are ignored if they don't match the keys in the inputs array. This makes it possible to use a common aircraft conditions object to accommodate the different keys in different models. For example, the object can contain both oat and isa properties. The OutsideConditions class provides instances that have environmental conditions like temperature and altitude in a variety of forms while allowing other properties to be added.

The interpolate() method linearly interpolates the input values by default. If a Ptable has only one input parameter with key parm1, then the interpolation would return the v value of the data array object with a p value that matches the input object value associated with parm1. If no value match can be found, it will find the p values that bracket parm1 and return the linear interpolation of parm1 between those two values. If a p value is a string, it must match the input value exactly.

If the Ptable has two or more input parameters, the parameters are processed in inputs order. If a parameter matches the corresponding input value, then the a array is recursively processed using the input value associated with the next inputs key, or the v value is used if it's the final inputs entry. If a parameter does not match, the results of recursively interpolating the bracketing parameters are interpolated.

So, a one-parameter table can involve interpolating up to 2 table entries. A two-parameter table can recursively interpolate up to 6 (2+4) values based on up to 4 different table entries. A three-parameter table can involve recursively interpolating up to 14 (2+4+8) values based on up to 8 table entries, and so on. Of course, if all input values match table parameters, only the table entry's v value matching the last input parameter will be returned.

In the Climb Rate table example:

climbTable.interpolate({oat:0, pressureAltitude:2000}) === 695
climbTable.interpolate({oat:20, pressureAltitude:2000}) === 625
climbTable.interpolate({oat:10, pressureAltitude:2000}) === 660
interpolate(10, 0, 695, 20, 625) === 660

Interpolation types

A Ptable interpolates numeric input values that fall between two parameter values for that input key in the table. By default, it uses linear interpolation. However, this can be adjusted by the info.intertype property when the Ptable is created. It can take the following values:

Output

The interpolation output can be adjusted by the output object property in the info object when the Ptable is created. The output object can contain a rndMult property that contains a number or a string with the same meaning and format as the mult parameter in the roundMult() function. For example, a rndMult value of 10 will round the output value to the nearest multiple of 10. A rndMult value of '10u' will round the output value up to the next higher multiple of 10.

Range errors

By default, if a numeric input value is outside the range of the corresponding table parameters, the [interpolate() method] will return a StateVarError instance, which is also an instance of Error. This is also the case if a string parameter or a limit setting of 'match' (see below) doesn't match a corresponding input value. See the createError() method. The instance will contain a cause object with an inputKey property containing the input key string that caused the error. The key will be for the first input in the inputs array that is out of range; subsequent input keys will be ignored. The Error message will contain either 'too high', 'too low', or 'no match'. The latter is only generated when using the match interpolation type or when the parameter is a string.

The range error behavior can be adjusted for each input by setting the limit property in an inputs array element, which can have the following values:

In the Climb Rate table example, limit:'clampLo' means that if the corresponding input value is below the lowest corresponding data parameter value, that parameter value should be used instead. In that case, the result will be conservative as lower temperature and altitude mean better performance.

Valid input range limits

You can inquire about the lowest and highest valid values for a particular key using the min() method or max() method. However, it is sometimes the case that the range of values for a particular input key that will produce a valid result will depend on the previous input values in the order of the inputs array. For example, in the Climb Rate table there is no data for an oat of 40 and a pressureAltitude of 12,000. That means the pressureAltitude may vary between 0 and 12,000 ft. except where the oat input is greater than 20°C. where it can only range between 0 and 10,000 ft. This is because there is no upper value to interpolate between when the pressureAltitude is greater than 10,000 ft. and the oat is greater than 20°C. The min() method or max() method returns the overall minimum or maximum input values. However, the input values for other keys may still cause an error even if the subject input is within the returned bounds.

The inputLimits() method will return the minimum and maximum values for a particular input key and input object. Using an input value within those limits for that key will not result in a range error. If the key is for a string parameter or a parameter that requires a match, it will return the list of parameter values in the table data for that key and those input values.

Handling errors.

When an error instance is returned, the errorValue property is set to POH by default. The errorValue is returned by the instance's valueOf() method. So, setting a State Variable value to the returned error will cause the errorValue to be displayed in most cases. You can customize the returned value by setting info.errorValue when creating the Ptable instance.

Many aircraft computations involve interpolating several similar tables. For example, the climb time, fuel, and distance. In addition, some computations involve a series of tables such as takeoff distance, takeoff weight adjustment, and takeoff headwind adjustment. You can certainly test for errors after each one, but alternatively, you can have the [interpolate() method] throw the error and catch errors in a collection of interpolations. You can do this by adding a truthy throwError property to the options argument object or by using the interpolateT() method.

Interpolations can produce errors due to different input value range issues, and it's important for an app user to understand what's gone wrong. For example, when a pressureAltitude input property value is too high for the table, the user should know that the chosen cruise altitude is the problem. Ptable provides static methods to help build relevant errors. See Ptable.getErrorMessage(), Ptable.getSvErrorMessage(), and
Ptable.mapErrorMessage().

Interpolation chaining

In many cases a performance calculation requires interpolating a series of tables. For example, a takeoff roll calculation can involve a takeoff roll at a maximum weight table, a weight adjustment table for lesser weight, and a wind adjustment table. Setting the toInput property in the interpolate() method's options to a truthy value will cause the interpolation to set a property representing the output value (a number or Error) in the input object. The default property key is the info. (if a string) or info.output.key set up when the Ptable was constructed. If the input object already had the output key, its value is overridden. The default output key may be overridden by the options.outputKey value if present when calling the interpolate() method. The interpolateC() method is a shorthand for calling interpolate() with option.toInput forced to true.

Here's a takeoff roll example that chains the output of the interpolations:

const conditions = {
	oat: 20,
	pressureAltitude: pressureAltitude(1000, 30.12),
	weight: 2500,
	headwind: 8,
}
takeoffRollTable.interpolateC(conditions)
takeoffWeightAdjTable.interpolateC(conditions)
const takeoffRoll = takeoffWindAdjTable.interpolate(conditions)
if (isError(takeoffRoll)) {
	...
} else {
	...
}

The call to takeoffRollTable.interpolateC() will add a runwayDistance property to the conditions object which may contain a number or an Error. The second interpolation adjusts the runwayDistance property, and the last interpolation returns a result value. If any interpolation produces an error, it will be passed through to the takeoffRoll result.

Using OutsideConditions

The previous example assumed that takeoffRollTable requires pressure altitude and OAT for input parameters rather than density altitude or ISA temperature. The input requirements can change between aircraft types or models. The OutsideConditions class could be used to provide all of these alternatives without knowing eactly which form the interpolation requires. An OutsideConditions instance can also take other properties that may be required, such as headwind, weight, or flap setting. Here's the previous example using OutsideConditions:

const conditions = new OutsideConditions({
	oat: 20,
	altitude:1000,
	altimeter: 30.12
	weight: 2500,
	headwind: 8,
})
takeoffRollTable.interpolateC(conditions)
takeoffWeightAdjTable.interpolateC(conditions)
const takeoffRoll = takeoffWindAdjTable.interpolate(conditions)
if (isError(takeoffRoll)) {
	...
} else {
	...
}

Units

Each aviation app uses a set of units for computations appropriate for that aircraft type and pilots. Unfortunately, older models often provide data in different units. Ptable allows you to enter the data in units appropriate to the model that may differ from the main app units. Input values in app units are automatically converted to units applicable to the input parameter values, and the results are also automatically converted to app units if appropriate.

The app's internal computation units are set using Ptable.defaultUnits(). The function's argument is an object with keys representing the possible data keys used in the app (e.g., 'weight', 'runwayDistance') with values that are the default unit string for that key (e.g., 'lb', 'ft'). When a Ptable is created, each inputs array element object can have a units property with the units string for the data for that parameter. If units is absent, the default units for the input's key are assumed. If the units unit string for the key differs from the default, any input value with that key is converted from the default units to the specified units before interpolation.

Similarly, the units for output values in the table may differ from the default units. When a Ptable is created, the info.output object can contain key and units properties similar to the inputs array elements. If the units unit string for the key differs from the default, the output value is converted from the specified units to the default units for that key.

Importing Ptable

Ptable is available for import from common/aero/exports.js.

Constructor

Syntax

new Ptable(info)

Creates a new Ptable instance as described by the info object.

Parameters

Instance methods

clamp()

clamp(inputKey, value)

Returns value clamped to the minimum and maximum table parameter values for the inputKey. The minimum and maximum values are the overall minimum and maximum values anywhere in the table for that parameter. So if the table has more than one input parameter and the inputKey is not the first key in the inputs array, interpolation using the clamped value with some combinations of other input values may still return a range error.

Parameters

Return value

A Number.

createError()

createError(msg, inputKey)

Returns a new StateVarError instance instance. The instance's message property is set to msg. The instance's cause object will be set with the following properties:

Parameters

Return value

An instance of StateVarError.

inputKeys()

inputKeys()

Returns an array of the key property values in each element of the table's inputs array. The keys are in the same order as the inputs array.

Return value

An array of input key strings for table inputs in the same order as the table's inputs array.

inputLimits()

inputLimits(inputKey, input)
inputLimits(inputKey, input, clamp)

Returns an object that describes the requirements for a valid value for inputKey, assuming the values for the other keys in the input object. The input object must provide the values for all the input keys in the table's inputs array before inputKey. If those input values fall outside the parameter range, null is returned. If they are in range, then one of the following objects is returned:

If clamp is truthy, then any input values are clamped to their nearest in-range value when evaluating the limits for inputKey.

Parameters

Return value

If the value of the input properties required to evaluate inputKeys limits are out of range or otherwise invalid, null is returned. If the inputKey requires matching, an object containing a values property whose value is an array of valid inputs for inputKey. Otherwise, an object containing min and max properties with values that are the minimum and maximum valid values for inputKey.

interpolate()

Syntax

interpolate(input)
interpolate(input, options)

Returns a value that is the interpolation of the table given the value in the input object according to the interpolation type and input and output processing required when the Ptable instance was created. The input object must contain properties whose keys match the key for all entries in the table's inputs array. If the input object is an instance of Error, it is returned. If input values are invalid or out of range, a StateVarError instance is returned. See the createError() method.

If required, the input and output values are automatically converted from or to the default units. The output value is rounded as specified when the Ptable instance was created.

If present, options is an object that contains properties that modifies the interpolation.

Parameters

Return value

A numeric value or a StateVarError instance.

interpolateC()

Syntax

interpolateC(input)
interpolateC(input, options)

Returns the interpolated result value based on the input object and options object similar to the interpolate() method. However, it also sets the returned value in the input object. It is a shorthand for forcing options.toInput to true and calling the interpolate() method.

Parameters

See interpolate().

Return value

A numeric value or a StateVarError instance. Any errors generated by the interpolation will be thrown. An Error instance passed as input will be returned and not thrown.

interpolateT()

Syntax

interpolateT(input)
interpolateT(input, options)

Returns the interpolated result value based on the input object and options object similar to the interpolate() method. However, it will throw an error if an error occurs. It is a shorthand for forcing options.throwError to true and calling the interpolate() method.
object properties.

Parameters

See interpolate().

Return value

A numeric value or a StateVarError instance. Any errors generated by the interpolation will be thrown. An Error instance passed as input will be returned and not thrown.

isInputKeys()

isInputKeys(...keys)

Returns true if the key names in the table's inputs array match the number and values of the keys specified by the arguments.

Parameters

Return value

A Boolean.

isValid()

Syntax

isValid(inputKey, value)

Return true if the value is within the minimum and maximum valid values for the input with with key inputKey. It also returns true if the parameters associated with key inputKey are stings or if the inputs array element specifies 'match'. isValid() compares values against the minimums and maximum for the inputKey parameter in the entire table. Specific input values for other input keys may affect the valid range, and using the value in an interpolation will return a range error.

Parameters

Return value

A Boolean.

max()

Syntax

max(inputKey)

Returns the maximum table parameter values for the inputKey. The maximum value is the overall maximum value anywhere in the table for that parameter. So if the table has more than one input parameter and the inputKey is not the first key in the inputs array then interpolation using the returned value with some combinations of other input values may still return a range error.

Parameters

Return value

A Number.

min()

Syntax

min(inputKey)

Returns the minimum table parameter values for the inputKey. The minimum value is the overall minimum value anywhere in the table for that parameter. So if the table has more than one input parameter and the inputKey is not the first key in the inputs array, then interpolation using the returned value with some combinations of other input values may still return a range error.

Parameters

Return value

A Number.

Instance Properties

a

If a v property is not present in info then this is set to info.a.

Value

An array. Read-only.

info

The info object used to create the Ptabble.

Value

An object. Read-only.

title

The title of the table. Set to info.title.

Value

A string. Read-only.

v

If a v property is present in info then this is set to info.v.

Value

A number. Read-only.

Static methods

Ptable.defaultUnits()

Syntax

Ptable.defaultUnits(keysToUnitsMap)
Ptable.defaultUnits()

Returns the current default units map, optionally merging new entries into it first. Any Ptable input or output that is encoded in different units will be converted to or from these units. See Units.

If keysToUnitsMap is provided, its entries are merged into the existing default units using objectMergeOver(), so multiple calls accumulate entries rather than replacing them. The updated map is then returned. If keysToUnitsMap is omitted, the current map is returned unchanged.

Parameters

Return value

The current default units object (a map from key strings to unit strings).

Ptable.getErrorMessage()

Syntax

Ptable.getErrorMessage(keyErrorMap, ...args)

Find the first invalid value in args and map it to an error message by calling Ptable.mapErrorMessage(). If no argument is invalid, return ''. Only the error message for the first invalid value is returned.

Ptable.getErrorMessage() is useful to test a series of computed values for errors.

Parameters

Return value

An error message string or '' if there are nor invalid values.

Ptable.getSvErrorMessage()

Syntax

Ptable.getSvErrorMessage(keyErrorMap, ...args)

Find the first invalid value in the state variables in args and map it to an error message by calling Ptable.mapErrorMessage(). If no argument is invalid, return ''. Only the error message for the first invalid state variable is returned.

Ptable.getSvErrorMessage() is useful for testing a series of computed state variable values for errors.

Parameters

Return value

An error message string or '' if there are no invalid state variable values.

Ptable.isPtableError()

Syntax

Ptable.isPtableError(value)

Return true if value is an error generated by createError().

Parameters

Return value

A Boolean.

Ptable.mapErrorMessage()

Syntax

Ptable.mapErrorMessage(error, keyErrorMap)

Map Ptable errors to a message specific to the key for the input that caused the problem. The keyErrorMap is an object that maps Ptable input keys to a descriptive string specific to the computation: e.g. {pressureAltitude: 'Cruise altitude'}.

Error messages are composed starting with the mapped descriptive string and appending the words "above POH maximum" or "below POH minimum" depending on whether the error.message was 'too high' or 'too low'. For example, if the cruise altitude was too high for the conditions and caused an error, the message would be: "Cruise altitude above POH maximum".

Parameters

Return value

An error message string.