Common Types

For the sake of code reuse and reduction of complexity, most of the elements and element attributes of schema are defined as separate types.

Simple Types

Simple types are used mostly within attributes. For example, all reference types, defining ID/IDREF pairs value restriction, are defined as simple types. Here, only types that are used in multiple places of schema are indicated. Types, specific to branches: species(atoms, molecules),processes (radiative,collisions) are described in respective sections of this manual.

AngularMomentumProjectionType

Restriction of double type. Allowed values: integer or half-integer. Examples: -11.5, 2, +2.0, -0.5.

AngularMomentumType

Restriction of double type. Allowed values: non-negative integer or half-integer. Examples: 11.5, 2, 2.0, 0.5.

DataDescriptionType

Descriptor for the type of a collisonal parameter, can take one of the following values:

• crossSection
• collisionStrength
• rateCoefficient
• probability
• effectiveCollisionStrength
• sputteringYield
• sputteredEnergyCoefficient
• particleReflectionCoefficient
• energyReflectionCoefficient
• meanPenetrationDepth

DoubleListType

A list of values of type double

ElementSymbolType

Symbol for a chemical element. Allowed values: an upper-case letter that may be followed by a lower-case letter. Examples: D, Hf, P.

EnvironmentIDType

Identifier for environments. May contain any symbols except spaces, first symbol must be E.

EnvironmentRefType

Reference for EnvironmentIDType

FunctionIDType

Identifier for functions. May contain any symbols except spaces, first symbol must be F.

FunctionRefType

Reference for FunctionIDType

MethodIDType

Identifier for methods of data production. May contain any symbols except spaces, first symbol must be M.

MethodRefType

Reference for MethodIDType

MixingClassType

Indicates the nature of the mixing coefficients in the expansion of a wave function in a specific basis. Allowed values:

• squared
• signed

NormalModeIDType

Identifier for vibrational normal modes for complex molecules.. May contain any symbols except spaces, first symbol must be V.

NormalModeRefType

Reference for NormalModeIDType

OrbitalAngularMomentumSymbolType

symbol for OrbitalAngularMomentumType, any lowercase letter is a valid value.

ParityType

Allowed values:

• even
• odd
• undefined

PrincipalQuantumNumberType

Allowed values: positive integer.

ReferenceFrameType

Descriptor for the frame of reference:

• CenterOfMass
• LaboratoryFrame
• TargetFrame

SourceIDType

Identifier for Sources of data. May contain any symbols except spaces, first symbol must be B.

SpeciesIDType

Identifier for species. Used in Atoms and Molecules. May contain any symbols except spaces, first symbol must be X.

SpeciesRefType

Reference for SpeciesIDType

StateIDType

Identifier for a specific state. Used in all species. May contain any symbols except spaces, first symbol must be S.

StateRefType

Reference for StateIDType

StringListType

Space-separated list of arbitrary strings.

UnitsType

Defines a list of allowed units within XSAMS document. This list is updated and extended as necessary on data producers request. [UnitsML] approach may be adopted in later versions of schema.

The positive powers are indicated by digits, the negative powers follow the backslash symbol /. For unitless (dimensionless) parameters, use unitless.

So far, this list contains the following values. If any additional values are required, contact responsibles for schema.

• undef
• eV/amu
• keV/amu
• MeV/amu
• eV
• keV
• MeV
• au
• 1/cm
• J
• Ry
• unitless
• kJ/mol
• kcal/mol
• K
• Hz
• kHz
• MHz
• m
• cm
• A
• nm
• deg
• rad
• srad
• s
• m3/s
• cm3/s
• cm6/s
• m2
• cm2
• b
• Mb
• 1/s
• C.m
• J/T
• C.m2
• m/s
• cm/s
• C
• electron
• g
• amu
• kg
• 1/m2/s
• 1/cm2/s
• J/m2/s
• J/cm2/s
• 1/m2
• 1/cm2
• 1/m3
• 1/cm3
• J/m2
• J/cm2
• W/m2
• W/cm2
• W
• atm
• km/mol
• 1/cm2/atm
• 1/cm/atm

Complex Types

PrimaryType

This is the fundamental elementary type used to built other types as extensions. It contains:

• optional methodRef attribute of type MethodRefType,
• one or more SourceRef elements, containing source identifiers,
• optional Comments element for arbitrary comments.

ChemicalElementType

The mandatory element NuclearCharge must be a positive integer. The optional element ElementSymbol must begin with an upper-case letter which may be followed by a lower-case letter. Examples: P, T, Au.

DataType

Extension of the PrimaryType which is used for description of numerical data, including units and accuracy. Contains a mandatory Value element of type ValueType and an optional Accuracy element, defined by AccuracyType.

DataFuncType

Defined in the similar way as DataType, DataFuncType has additionally

• mandatory name attribute,
• choice between a pair of value / Accuracy elements and a list of FitParameters elements, defined by FitParametersType, each containing sufficient set of parameters needed to calculate the value using some Function.

It is used in Broadening and Shifting sections of [XSAMS] to define lineshape parameters.

AccuracyType

Extension of the PrimaryType, describing measurement/calculation accuracy of some physical quantity. Used in the Accuracy element of DataType and DataFuncType. The definition is inspired by [IVOA] Spectral Data Model and is still a draft and a subject to change or refine in future versions of [XSAMS].

Following attributes and child elements are defined:

• optional calibration attribute, describing the kind of the reference frame for data. It may take values:
  • absolute indicates that the values in the data are expected to be correct within the given uncertainty
  • relative indicates that although an unknown systematic error is present, the ratio and difference of any two values originating from the same source will be correct.
  • normalized indicates that the values, originating from this source, have been divided by a certain reference quantity. In this case units field of ValueType should be ‘unitless’
  • uncalibrated indicates that not only an unknown systematic error is present in data, originating from that source, but also some unspecified value-dependant error. Thus, for example, for transitions frequencies only the order of transitions is guaranteed, neither frequencies, nor their difference/ratio are accurate.
• Optional quality attribute of integer type that may be used for distinguishing quality-assessed data. Zero value means data, accurate within their errors, other values means that there were some problems with data.
• Optional Systematic element of type AccuracyErrorType for systematic errors
• Optional Statistical element of type AccuracyErrorType for total statistical error, i.e. upper/lower range are equal.
• Optional StatHigh and StatLow elements group, also of AccuracyErrorType, may be specified instead of single Statistical element to indicate statistical errors in case of unequal upper and lower error ranges.

AccuracyErrorType

AccuracyErrorType is an extension of xs:double type, adding two optional attributes:

• confidence of type xs:double, with valid ranges from 0 to 1, indicating confidence level for which this accuracy is calculated. Ususal values would be like 0.95 or 0.99.
• relative of type xs:boolean, indicating whether this accuracy value is absolute(false) or relative(true). By default, accuracy should be treated as absolute.

FitParametersType

FitParametersType defines a full set of data required to calculate some quantity using the predefined function. For a function definition, see Functions branch of XSAMS. Following attributes and elements are defined:

• functionRef attribute, of type FunctionRefType, defining the reference to a function used,
• list of FitArgument elements, of type ArgumentType, defining validity limits of arguments in particular fit,
• list of FitParameter elements, of type NamedDataType, giving the function parameters values, possibly with source references. The NamedDataType is an extension of DataType with a mandatory name string attribute.

LifeTimeType

Extension of the DataType that defines the additional attribute decay with possible values:

• total,
• totalRadiative,
• totalNonRadiative.

The type is used both in atomic and molecular states to define state lifetime.

SpeciesStateRefType

This type allows to define the SpeciesRef (SpeciesRefType) or StateRef (StateRefType) child elements (or both). At least one should be specified, but it is always kind to explicitly provide SpeciesRef.

ValueType

The data must be of type xs:double with the mandatory units attribute of type UnitsType

Data structures

In this section generic data structures that are used in multiple places in schema are described.

DataSeriesType

DataSeriesType allows description of data as a list of values or a linear sequence, including errors.

Extends PrimaryType to allow source references, adds following attributes and elements:

• optional string attribute parameter that may contain the function parameter name or just a description of meaning of sequence.
• optional attribute units of UnitsType to define the data units
• optional attribute id of type xs:ID that is reserved for future use.
• mandatory choice of
  • DataList element of DataListType: to represent a space-separated list of double values.
  • LinearSequence element of LinearSequenceType. Should be used if data is a linear sequence. Example would be to represent frequency/wavelength points for spectrum data.
  • DataFile string element that should contain a file name, containing space-separated or newline-separated set of data. This element is also reserved for future use, currently no software is able to pass data files along with XSAMS instance documents.
• optional choise of Error or ErrorList to define errors for data points. List may be used if error values are different for different points, otherwise single Error element should be used.

DataTableType

DataTableType is the type used in Collision’s DataXY element.

DataTableType has following attributes and elements defined:

• mandatory units attribute of type UnitsType,
• optional parameter attribute to describe the type of unit (e.g., energy, time, or surface...)
• mandatory DataList element, of type DataListType:, providing the numerical values as a list.
• optional Error, providing centered error bar, or
• NegativeError and
• PositiveError elements, providing asymmetric error bar;
• optional DataDescription string element.

All error-related elements have the same type DataListType: (list of values of type xs:double). All missing error values should be reported as -1.

LinearSequenceType

Allows to describe a linear sequence of data, in form of:

An extension of PrimaryType, defines following attributes:

• Mandatory a0 and a1 attributes of type xs:double
• Optional integer n attribute to indicate the count of sequence elements
• Optional units attribute of UnitsType to define units of data

VectorsType

Defines a collection of vectors in 3D space, specifying source reference, dimensions units and vector reference frame.

Both VectorsType and Vector are extending PrimaryType.

VectorsType defines units attribute of type UnitsType and a collection of Vector elements.

Vector has following attributes:

• string ref that is context-specific and defines the reference element to which the vector applies,
• three xs:double coordinate attributes: x3, y3, z3, with units defined in the Vectors container.

DataListType:

Defines a space-separated list of double precision floating-point numbers, with the following optional attributes:

• units of type UnitsType to define units of the list
• integer n to indicate the number of elements in a list

MatrixType:

A nrows x ncols matrix. Being an extension of the PrimaryType, MatrixType defines following elements and attributes:

• mandatory RowRefs element that contains whitespace separated list of row names,
• mandatory ColRefs element that contains the same list for columns.
• mandatory Matrix element that contains a whitespace separated list of values, either real or complex
• mandatory integer attribute nrows defining the number of rows,
• mandatory integer attribute ncols defining the number of columns,
• mandatory attribute form that identifies the type of matrix. It can be - arbitrary - symmetric - asymmetric - diagonal - antidiagonal
• mandatory attribute ‘values’ that may take values - binary - integer - real - imaginary - complex

For an arbitrary matrix, Matrix element has nrows*ncols entries. First you output elements of the first row, starting from the leftmost column.

	c1	c2	c3
r1	0	1	2
r2	3	4	5
r3	6	7	8

<MatrixData units="arbitrary" nrows="3" ncols="3" form="arbitrary" values="integer">
        <RowRefs>r1 r2 r3</RowRefs>
        <ColRefs>c1 c2 c3</ColRefs>
        <Matrix>
                0 1 2 3 4 5 6 7 8
        </Matrix>
</MatrixData>

For diagonal and antidiagonal matrix there are nrows=ncols entries, counting from left to right

	c1	c2	c3
r1	1	0	0
r2	0	2	0
r3	0	0	3

<MatrixData units="arbitrary" nrows="3" ncols="3" form="diagonal" values="integer">
        <RowRefs>r1 r2 r3</RowRefs>
        <ColRefs>c1 c2 c3</ColRefs>
        <Matrix>
                1 2 3
        </Matrix>
</MatrixData>

	c1	c2	c3
r1	0	0	3
r2	0	2	0
r3	1	0	0

<MatrixData units="arbitrary" nrows="3" ncols="3" form="antidiagonal" values="integer">
        <RowRefs>r1 r2 r3</RowRefs>
        <ColRefs>c1 c2 c3</ColRefs>
        <Matrix>
                1 2 3
        </Matrix>
</MatrixData>

For a symmetric matrix there are nrows(nrows+1)/2 entries.

	c1	c2	c3
r1	1	2	3
r2	2	4	5
r3	3	5	6

<MatrixData units="arbitrary" nrows="3" ncols="3" form="symmetric" values="integer">
        <RowRefs>r1 r2 r3</RowRefs>
        <ColRefs>c1 c2 c3</ColRefs>
        <Matrix>
                1 2 3 4 5 6
        </Matrix>
</MatrixData>