XTCE12 — Missed optional descriptive elements on calibrators from proposed schema

It has been requested that the 3 core calibrator implementations: Spline, Polynomial, and MathOperation, provide some space for description and naming (optionally). In addition, annotation updates still need some refinement.

Propose to correct the misses in the calibration elements (re-presented)

The team members who originally opposed this resolution have decided that now this is okay. Re-presenting this resolution fix for ballot.

The cleanest method to do this correction is to first add a new type, in this case named "BaseCalibratorType" that includes these extended descriptive elements and use that as the base for each of the specific calibrator elements.

First step is to create the new "BaseCalibratorType" complexType just prior to the "CalibratorType" in the schema document:

<complexType name="BaseCalibratorType" abstract="true">
<annotation>
<documentation xml:lang="en">Supplies an optional non-reference-able name and short description for calibrators. Also includes an optional ancillary data for any special local flags, note that these may not necessarily transfer to another recipient of an instance document.</documentation>
</annotation>
<sequence>
<element name="AncillaryDataSet" type="xtce:AncillaryDataSetType" minOccurs="0">
<annotation>
<documentation xml:lang="en">Optional additional ancillary information for this calibrator/algorithm</documentation>
</annotation>
</element>
</sequence>
<attribute name="name" type="string">
<annotation>
<documentation xml:lang="en">Optional name for this calibrator/algorithm</documentation>
</annotation>
</attribute>
<attribute name="shortDescription" type="xtce:ShortDescriptionType">
<annotation>
<documentation xml:lang="en">Optional description for this calibrator/algorithm</documentation>
</annotation>
</attribute>
</complexType>

Then update the CalibratorType to use this base type instead of inheriting from "OptionalNameDescriptionType" to cleanup some of the extra fluff in that element that would no longer be needed. Replace the existing "CalibratorType":

<complexType name="CalibratorType">
<annotation>
<documentation xml:lang="en">Calibrators are normally used to convert to and from bit compacted numerical data</documentation>
</annotation>
<complexContent>
<extension base="xtce:OptionalNameDescriptionType">
<choice>
<element name="SplineCalibrator" type="xtce:SplineCalibratorType"/>
<element name="PolynomialCalibrator" type="xtce:PolynomialCalibratorType"/>
<element name="MathOperationCalibrator" type="xtce:MathOperationCalibratorType"/>
</choice>
</extension>
</complexContent>
</complexType>

With the following new definition for "CalibratorType":

<complexType name="CalibratorType">
<annotation>
<documentation xml:lang="en">Describe a calibrator to transform a source data type raw/uncalibrated value (e.g. an integer count from a spacecraft) to an engineering unit/calibrated value for users (e.g. a float).</documentation>
</annotation>
<complexContent>
<extension base="xtce:BaseCalibratorType">
<choice>
<element name="SplineCalibrator" type="xtce:SplineCalibratorType">
<annotation>
<documentation xml:lang="en">Describes a calibrator in the form of a piecewise defined function</documentation>
</annotation>
</element>
<element name="PolynomialCalibrator" type="xtce:PolynomialCalibratorType">
<annotation>
<documentation xml:lang="en">Describes a calibrator in the form of a polynomial function</documentation>
</annotation>
</element>
<element name="MathOperationCalibrator" type="xtce:MathOperationCalibratorType">
<annotation>
<documentation xml:lang="en">Describes a calibrator in the form of a user/program/implementation defined function</documentation>
</annotation>
</element>
</choice>
</extension>
</complexContent>
</complexType>

Next, update the complexType "SplineCalibratorType". This is the simplest of the three changes for the concrete calibrators.

Replace the old one:

<complexType name="SplineCalibratorType">
<annotation>
<documentation xml:lang="en">A calibration type where a segmented line in a raw vs calibrated plane is described using a set of points. Raw values are converted to calibrated values by finding a position on the line corresponding to the raw value. The algorithm triggers on the input parameter.</documentation>
</annotation>
<sequence>
<element name="SplinePoint" type="xtce:SplinePointType" minOccurs="2" maxOccurs="unbounded"/>
</sequence>
<attribute name="order" type="xtce:NonNegativeLongType" default="1"/>
<attribute name="extrapolate" type="boolean" default="false"/>
</complexType>

With this new implementation:

<complexType name="SplineCalibratorType">
<annotation>
<documentation xml:lang="en">Describe a spline function for calibration using a set of at least 2 points. Raw values are converted to calibrated values by finding a position on the line corresponding to the raw value. The line may be interpolated and/or extrapolated as needed. The interpolation order may be specified for all the points and overridden on individual points. The algorithm triggers on the input parameter. See CalibratorType.</documentation>
</annotation>
<complexContent>
<extension base="xtce:BaseCalibratorType">
<sequence>
<element name="SplinePoint" type="xtce:SplinePointType" minOccurs="2" maxOccurs="unbounded">
<annotation>
<documentation xml:lang="en">Describes a single point of the spline or piecewise function.</documentation>
</annotation>
</element>
</sequence>
<attribute name="order" type="xtce:NonNegativeLongType" default="1">
<annotation>
<documentation xml:lang="en">The interpolation order to apply to the overall spline function. Order 0 is no slope between the points (flat). Order 1 is linear interpolation. Order 2 would be quadratic and in this special case, 3 points would be required, etc.</documentation>
</annotation>
</attribute>
<attribute name="extrapolate" type="boolean" default="false">
<annotation>
<documentation xml:lang="en">Extrapolation allows the closest outside point and the associated interpolation to extend outside of the range of the points in the spline function.</documentation>
</annotation>
</attribute>
</extension>
</complexContent>
</complexType>

Next update the PolynomialCalibratorType. Here we replace the implementation with a new one and also delete a now unused subtype:

Existing implementation to replace:

<complexType name="PolynomialCalibratorType">
<annotation>
<documentation xml:lang="en">A calibration type where a curve in a raw vs calibrated plane is described using a set of polynomial coefficients. Raw values are converted to calibrated values by finding a position on the curve corresponding to the raw value. The first coefficient belongs with the X^0 term, the next coefficient belongs to the X^1 term and so on. </documentation>
</annotation>
<complexContent>
<extension base="xtce:PolynomialType"/>
</complexContent>
</complexType>

New implementation:

<complexType name="PolynomialCalibratorType">
<annotation>
<documentation xml:lang="en">Describe a polynomial equation for calibration. This is a calibration type where a curve in a raw vs calibrated plane is described using a set of polynomial coefficients. Raw values are converted to calibrated values by finding a position on the curve corresponding to the raw value. The first coefficient belongs with the X^0 term, the next coefficient belongs to the X^1 term and so on. See CalibratorType.</documentation>
</annotation>
<complexContent>
<extension base="xtce:BaseCalibratorType">
<sequence>
<element name="Term" type="xtce:TermType" maxOccurs="unbounded">
<annotation>
<documentation xml:lang="en">A single term in the polynomial function.</documentation>
<appinfo>Generally only up to second order powers are reflexive. Implementations may limit the maximum number of terms supported.</appinfo>
</annotation>
</element>
</sequence>
</extension>
</complexContent>
</complexType>

Delete the now unused PolynomialType:

<complexType name="PolynomialType">
<annotation>
<documentation xml:lang="en">A polynomial expression. For example: 3 + 2x</documentation>
</annotation>
<sequence>
<element name="Term" type="xtce:TermType" maxOccurs="unbounded"/>
</sequence>
</complexType>

Updates to the MathOperationCalibratorType are last. Replace this existing implementation:

<complexType name="MathOperationCalibratorType">
<complexContent>
<extension base="xtce:MathOperationType"/>
</complexContent>
</complexType>

With this new implementation:

<complexType name="MathOperationCalibratorType">
<annotation>
<documentation xml:lang="en">Describe a mathematical function for calibration where the mathematical function is defined using the MathOperationType.</documentation>
</annotation>
<complexContent>
<extension base="xtce:BaseCalibratorType">
<choice maxOccurs="unbounded">
<annotation>
<documentation xml:lang="en">Describe a postfix (aka Reverse Polish Notation (RPN)) expression for mathematical equations. It uses a stack where operands (either fixed values or ParameterInstances) are pushed onto the stack from first to last in the XML. As the operators are specified, each pops off operands as it evaluates them, and pushes the result back onto the stack. For example, the stack, 4 8 /, would result as 0.5. In this case postfix is used to avoid having to specify parenthesis. To convert from infix to postfix, use Dijkstra's "shunting yard" algorithm.</documentation>
</annotation>
<element name="ValueOperand" type="string">
<annotation>
<documentation xml:lang="en">Use a constant in the calculation.</documentation>
</annotation>
</element>
<element name="ThisParameterOperand" type="string" fixed="">
<annotation>
<documentation xml:lang="en">Use the value of this parameter in the calculation. It is the calibrator's value only. If the raw value is needed, specify it explicitly using ParameterInstanceRefOperand. Note this element has no content.</documentation>
</annotation>
</element>
<element name="Operator" type="xtce:MathOperatorsType">
<annotation>
<documentation xml:lang="en">All operators utilize operands on the top values in the stack and leaving the result on the top of the stack. Ternary operators utilize the top three operands on the stack, binary operators utilize the top two operands on the stack, and unary operators use the top operand on the stack.</documentation>
</annotation>
</element>
<element name="ParameterInstanceRefOperand" type="xtce:ParameterInstanceRefType">
<annotation>
<documentation xml:lang="en">This element is used to reference the last received/assigned value of any Parameter in this math operation.</documentation>
</annotation>
</element>
</choice>
</extension>
</complexContent>
</complexType>

Now, the MathOperationType no longer needs the content it contains. We retain it empty for inheritance by other more complex types.

Replace the existing implementation:

<complexType name="MathOperationType" abstract="true">
<annotation>
<documentation xml:lang="en">Postfix (aka Reverse Polish Notation (RPN)) notation is used to describe mathmatical equations. It uses a stack where operands (either fixed values or ParameterInstances) are pushed onto the stack from first to last in the XML. As the operators are specified, each pops off operands as it evaluates them, and pushes the result back onto the stack. In this case postfix is used to avoid having to specify parenthesis. To convert from infix to postfix, use Dijkstra's "shunting yard" algorithm.</documentation>
</annotation>
<choice maxOccurs="unbounded">
<element name="ValueOperand" type="double">
<annotation>
<documentation xml:lang="en">The element is used to represent a constant numeric value in the math operation.</documentation>
</annotation>
</element>
<element name="ThisParameterOperand" type="string">
<annotation>
<documentation xml:lang="en">This element is a shortcut to represent the current parameter for which this math operation applies. It is shorter than using the ParameterInstanceRefOperand, which can also specify this current parameter, but in a longer form syntax.</documentation>
</annotation>
</element>
<element name="ParameterInstanceRefOperand" type="xtce:ParameterInstanceRefType">
<annotation>
<documentation xml:lang="en">This element is used to reference the last received/assigned value of any Parameter in this math operation.</documentation>
</annotation>
</element>
<element name="Operator" type="xtce:MathOperatorsType">
<annotation>
<documentation xml:lang="en">Binary operators: +, -, *, /, %, ^ operate on the top two values in the stack, leaving the result on the top of the stack. Unary operators: 1/x, x!, e^x, ln, log, and trigonometric operators operate on the top member of the stack also leaving the result on the top of the stack. 'ln' is a natural log where 'log' is a base 10 logarithm. Trigonometric operators use degrees. 'swap' swaps the top two members of the stack.</documentation>
</annotation>
</element>
</choice>
</complexType>

With this new implementation:

<complexType name="MathOperationType" abstract="true">
<annotation>
<documentation xml:lang="en">Postfix (aka Reverse Polish Notation (RPN)) notation is used to describe mathmatical equations. It uses a stack where operands (either fixed values or ParameterInstances) are pushed onto the stack from first to last in the XML. As the operators are specified, each pops off operands as it evaluates them, and pushes the result back onto the stack. In this case postfix is used to avoid having to specify parenthesis. To convert from infix to postfix, use Dijkstra's "shunting yard" algorithm.</documentation>
</annotation>
<complexContent>
<extension base="xtce:MathOperationCalibratorType"/>
</complexContent>
</complexType>