OSML Elements

Root Element

OSML

Integrity Element

Secure

Declaration Elements

  Semantics
  Symbol
  Argument

Construction Elements

  Math
  Definition
  Apply
  Function
  Constant
  Sequence
  Link
  Element
  Number
  Sep

Meta-Data Element

Annotation

Version 1.0

Optical Spectroscopy Markup Language

OSML Elements

This is preliminary version subject to change

The 16 elements of this language are all we need to write OSML documents containing complex mathematical expressions such as : function libraries, optical property files and spectroscopic model definitions. The documents constructed with these elements are secure, human readable and understandable by software to facilitate data exchange between applications.
In the following, each element description contains several sub-sections corresponding to the various parts of the definition as described below :

Description

A description of the element in human readable form.

Content

The list of possible child elements, their occurrence and requirements.

Attributes

A list of attributes of the OSML element. Some attributes have a direct impact on the mathematical semantics of the object. For example the type attribute of the number element is used to determine what type of value (integer, real, etc.) is being constructed.

Examples

Typical examples of the use of the element in OSML.

top

OSML Element

Description

The OSML element is the root element of the optical spectroscopy markup language. It contains a required attribute that indicates the version number of the language used to write the document. In secure documents, its first child must be the secure element.

Content

Possible childs of this element in their order of appearance.

Name	Minimum Occurrence	Maximum Occurrence	Required
secure	0	1	No
annotation	0	Unbounded	No
semantics	0	1	No
math	0	1	No

Attributes

Name	Value	Default	Required
version	...	No default value	Yes

Examples

Markup appearance :

 <OSML version="1.0">
    .
    .      
 </OSML>

Example of OSML fragment involving semantic and math content. This is the typical form for complex spectroscopic model definitions :

 <OSML version="1.0">
   <secure algorithm="SHA-256">
    84983E44 1C3BD26E BAAE4AA1 F95129E5 E54670F1 A23FD542 1AC53D5E 2ABE4DA9
   </secure>
   <annotation name="meta-data"> description string </annotation>
   <semantics> 
     .
     . 
   </semantics>
   <math>
     .
     .      
   </math>   
 </OSML>

A function library document or a optical property file must contain only semantic content:

 <OSML version="1.0">
   <secure algorithm="SHA-256">
    84983E44 1C3BD26E BAAE4AA1 F95129E5 E54670F1 A23FD542 1AC53D5E 2ABE4DA9
   </secure>
   <annotation name="author"> Author of the library </annotation>
   <annotation name="documentation"> Description of the library content </annotation>
   <semantics> 
     .
     . 
   </semantics>
 </OSML>

Classical form of a document using only external declarations :

 <OSML version="1.0">
   <secure algorithm="SHA-256">
    84983E44 1C3BD26E BAAE4AA1 F95129E5 E54670F1 A23FD542 1AC53D5E 2ABE4DA9
   </secure>
   <annotation name="meta-data"> description string </annotation>
   <math>
     .
     .      
   </math>   
 </OSML>

top

Secure Element

Description

The intention of the secure element is to allow applications that are using OSML files to detect critical changes of the content that were made outside the control of the system that generated it. The protection scheme consists in storing a small-encoded version of the original document within the secure element and to use it for integrity testing. The encoded version, which is also called a message digest, is calculated by using a secure hashing function whose name is specified by the attribute algorithm of the secure element. The knowledge of this information is sufficient for an application to test the integrity of an OSML document by computing its message digest with the specified algorithm and comparing it to the stored one.
Core function libraries are protected with this security mechanism and their message digest is registered in the core signature file. This precaution allows to strengthen the protection by avoiding naming claches between core function libraries and user ones.
The secure element can only appear once in a document and only at the beginning of the OSML element. It does not apply to content outside the scope of the OSML element.

Content

The content of this element is the encoded version of the document also called message digest.

Attributes

Name	Value	Default	Required
algorithm	SHA-256	No default value	Yes

Examples

 <secure algorithm="SHA-256">
  84983E44 1C3BD26E BAAE4AA1 F95129E5 E54670F1 A23FD542 1AC53D5E 2ABE4DA9
 </secure>

top

Semantics Element

Description

The semantics element is the container that stores the declarations of user defined constants and functions.

Content

Name	Minimum Occurrence	Maximum Occurrence	Required
symbol	0	Unbounded	No
annotation	0	Unbounded	No

Attributes

No attributes

Examples

Markup appearance :

 <semantics> 
     .
     . 
 </semantics>

Semantic block containing declarations of functions and constants :

 <semantics>
   <symbol name="Boltzmann" type="constant">
     <number type="real" encoding="e-notation"> 1.38e-23 </number>
   </symbol>

   <symbol name="myfunction" type="function">
     <argument name="x">
       <annotation name="info"> Function variable </annotation>
       <number> 0.0 </number>
     </argument>
 
     <argument name="A">
       <annotation name="info"> Function parameter </annotation>
       <number> 1.0 </number>
     </argument>

     <definition name="value">
       <apply>
         <function name="plus"/>
         <link> x </link>
         <link> A </link>
         <number> 1.0 </number>
       </apply>
     </definition >
   </symbol>

   <symbol name="formulaname" type="function" encoding="formula">
     <annotation content="mathExpression">
      formulaname(x,A) = x + A  
     </annotation> 
   </symbol>
 </semantics>

top

Symbol Element

Description

The symbol element is used to declare new constants and functions. The type of declaration function or constant and its name are directly given by the corresponding type and name attributes. Even if the preferred encoding type for the definition of a function is OSML, other formats such as MathML, OpenMath are also allowed to define special functions that cannot be directly constructed with the functions of the core library. Other formats than OSML and formula must be declared as external with the encoding attribute. The semantics of these functions must be included in a separate file whose location is given by an annotation element.
In the case of an OSML encoding, the content of the symbol element starts with a list of argument elements and is followed by one or more definition elements. The first definition element contains the definition of the function, the other definition elements are pieces of the first definition element and are connected to it via link elements.

Content

Name	Minimum Occurrence	Maximum Occurrence	Required
annotation	0	Unbounded	No
argument	0	Unbounded	No
definition	0	Unbounded	No
number	0	1	No

Attributes

Name	Value	Default	Required
name	...	No default value	Yes
type	constant\|function	function	No
encoding	OSML\|formula\|external	OSML	No

Examples

Constant declaration : myconstant = 2.5e10

 <symbol name="myconstant" type="constant">
   <number type="real" encoding="e-notation"> 2.5e10 </number>
 </symbol>

OSML version of a function declaration : myfunction(x, A) = x + A + 1.0

 <symbol name="myfunction" type="function">
   <argument name="x">
     <annotation> Function variable </annotation>
     <number> 0.0 </number>
   </argument>
 
   <argument name="A">
     <annotation> Function parameter </annotation>
     <number> 1.0 </number>
   </argument>

   <definition name="functiondefinition">
     <apply>
       <function name="plus"/>
       <link> x </link>
       <link> A </link>
       <number> 1.0 </number>
     </apply>
   </definition>
 </symbol>

Formula version of a function declaration :

 <symbol name="formulaname" type="function" encoding="formula">
  <annotation content="mathExpression">
   formulaname(x,A) = cos(x) + A   
  </annotation> 
 </symbol>

External version of a function declaration :

 <symbol name="specialfunction" type="function" encoding="external">
  <annotation content="definitionURL">
   http://www.specialfunctions.com/speciallibrary.fun 
  </annotation> 
 </symbol>

top

Argument Element

Description

The argument element is used declare an argument of a new function.

Content

Name	Minimum Occurrence	Maximum Occurrence	Required
annotation	0	Unbounded	No
number	1	1	yes

Attributes

Name	Value	Default	Required
name	...	No default value	Yes

Examples

 <argument name="width">
   <annotation> Full Width at Half Height </annotation>
   <number> 0.0 </number>
 </argument>

top

Math Element

Description

The math element is a container for storing a set of interconnected definition elements. It is the base element that appears in the OSML representation of complex spectroscopic models.

Content

Name	Minimum Occurrence	Maximum Occurrence	Required
annotation	0	Unbounded	No
definition	1	Unbounded	Yes

Attributes

No attributes

Examples

Markup appearance :

 <math> 
   .
   . 
 </math>

Math block containing several model definitions :

 <math>
   <definition name="x">
   </definition> 
 
   <definition name="Amplitude">
     <number> 1.0 </number> 
   </definition> 
 
   <definition name="includereferences">
     <apply>
       <function name="sum"/> 
       <apply>
         <function name="lorentzian" source="core"/> 
         <link> x </link>
         <link> Amplitude </link>
         <number> 100.0 </number>
         <constant name="pi"/>
       </apply>
       <apply>
         <function name="gaussian" source="core"/> 
         <link> x </link>
         <number> 1.0 </number>
         <number> 200.0 </number>
         <number> 20.0 </number>
       </apply>
     </apply>  
   </definition> 
 </math>

top

Definition Element

Description

The definition element is the OSML constructor of a mathematical expression that can be referenced via its name. References to definition objects can be used as arguments for functions or operators involved in the expression of other definition element.
The mathematical expression is built with the basic constructors apply, function, sequence, constant, element, number and references to other definitions.
This element contains zero or one constructor element and an unbounded number of annotation elements.

Content

Name	Minimum Occurrence	Maximum Occurrence	Required
annotation	0	Unbounded	No
apply	0	1	No
number	0	1	No
constant	0	1	No

Attributes

Name	Value	Default	Required
name	...	No default value	Yes

Examples

Variable definition:

 <definition name="x">
 </definition>

Variable definition with an annotation element :

 <definition name="lambda">
   <annotation name="units"> MICROMETERS </annotation> 
 </definition>

Parameter definition :

 <definition name="Amplitude">
   <number> 1.0 </number> 
 </definition>

More complex definition including references:

 <definition name="gauss-lorentz">
   <apply>
     <function name="sum"/> 
     <apply>
       <function name="lorentzian"/> 
       <link> x </link>
       <link> Amplitude </link>
       <link> Center </link>
       <number> 10.0 </number>
     </apply>
     <apply>
       <function name="gaussian"/> 
       <link> x </link>
       <link> Amplitude </link>
       <link> Center </link>
       <number> 10.0 </number>
     </apply>
   </apply>  
 </definition>

top

Apply Element

Description

The apply element is the OSML constructor for function application. Its purpose is to apply a function or operator to its arguments to produce an expression representing an element of the codomain of the function.
The first child represents the function or the operator which is applied to the remaining childs which are considered as arguments.
It is involved in everything from forming sums such as a + b as in :

 <apply>
   <function name="plus"/>
   <link> a </link>
   <link> b </link>
 </apply>

through to using the sine function to construct sin(5) as in :

 <apply>
   <function name="sin"/>
   <number> 5 </number>
 </apply>

Content

Name	Minimum Occurrence	Maximum Occurrence	Required
function	0	1	No
sequence	0	1	No
element	0	1	No
constant	0	Unbounded	No
number	0	Unbounded	No
link	0	Unbounded	No
apply	0	Unbounded	No

Attributes

No attributes.

Examples

OSML version of : gaussian(x, Amplitude, Center, Width)

 <apply>
   <function name="gaussian" source="core"/> 
   <link> x </link>
   <link> Amplitude </link>
   <link> Center </link>
   <link> Width </link>
 </apply>

OSML version of : userfunction(x, 100.0, 5.0)

 <apply>
   <function name="userfunction" source="userlibrary"/> 
   <link> x </link>
   <number> 100.0 </number>
   <number> 5.0 </number>
 </apply>

OSML version of : log(x + cos(y) - 1.0)

 <apply>
   <function name="log"/> 
   <apply>
     <function name="sum"/>
     <link> x </link>
     <apply> 
       <function name="cos"/>
       <link> y </link>
     </apply>
     <number> -1.0 </number>
   </apply>
 </apply>

top

Function Element

Description

The function element is used to construct function objects such as the elementary mathematical functions described in the core function library or more complicated ones defined in other function libraries.
The type of function to be constructed is indicated by the name attribute and the location of its semantics is given by the source attribute.
The source attribute must be document if the semantics of a function are defined inside the OSML element. For an external definition, the attribute takes the name of the function library containing it.

Content

Empty element.

Attributes

Name	Value	Default	Required
name	...	No default value	Yes
source	document\|core\|...	core	No

Examples

 <function name="cos"/>
 
 <function name="airy" source="document"/>

 <function name="gaussian" source="peak-functions"/>

top

Sequence Element

Description

The sequence element is used to construct sequences of element elements.
The name of sequence to be constructed is indicated by the name attribute and the location of its definition is given by the source attribute.
An example of sequence is the list of points used by a function that evaluates ordinates by using a cubic spline interpolation between the points.

Content

Empty element.

Attributes

Name	Value	Default	Required
name	point-list\|...	No default value	Yes
source	document\|core\|...	core	No

Examples

 <sequence name="point-list"/>

OSML version of a sequence of 3 points : {(0.0, 1.0),(10.0, 12.5), (100.0, 6.0)}

 <apply>
   <sequence name="point-list"/> 
   <apply>
     <element name="point"/>
     <number> 0.0 </number>
     <number> 1.0 </number>
   </apply> 
   <apply>
     <element name="point"/>
     <number> 10.0 </number>
     <number> 12.5 </number>
   </apply> 
   <apply>
     <element name="point"/>
     <number> 100.0 </number>
     <number> 6.0 </number>
   </apply> 
 </apply>

top

Element Element

Description

The element element is used to construct an element of a sequence.
The name of the element to be constructed is indicated by the name attribute and the location of its definition is given by the source attribute.

Content

Empty element.

Attributes

Name	Value	Default	Required
name	point\|...	No default value	Yes
source	document\|core\|...	core	No

Examples

 <element name="point"/>

OSML fragment defining a point (x,y) = (0.0, 1.0)

 <apply>
   <element name="point"/>
   <number> 0.0 </number>
   <number> 1.0 </number>
 </apply>

top

Constant Element

Description

The constant element is used to construct numerical constants whose values have been defined elsewhere.
The name of constant to be constructed is indicated by the name attribute and the location of its definition is given by the source attribute.
The source attribute must be document if the value of the constant is defined inside the OSML element or, for an external definition, the name of the library containing it.

Content

Empty element.

Attributes

Name	Value	Default	Required
name	pi\|e	No default value	Yes
source	document\|core\|...	core	No

Examples

 <constant name="pi"/>
 
 <constant name="k" source="document"/>

 <constant name="Planck" source="si-constants"/>

top

Link Element

Examples

 <link> x </link>

top

Number Element

Description

The number element is introduced to specify a numerical value. Its content must be a valid representation of a number :
- 0 or 1 for a boolean
- a string of decimal digits for integers
- two strings of decimal digits separated by the sep element for rationals
- e-notation, float32 or float64 representations for real numbers
- two real representations separated by the sep element for complex numbers.

The optional attribute type indicates what kind of number is stored : integer, rational, real or complex. The default value is real.

The encoding attribute, which is also optional, allows to specify the type of encoding of the number.

Content

A number representation.

Name	Minimum Occurrence	Maximum Occurrence	Required
sep	0	1	No

Attributes

Name	Value	Default	Required
type	boolean\|integer\|rational\|real\|complex	real	No
encoding	DECIMAL\|E-NOTATION\|FLOAT32\|FLOAT64	E-NOTATION	No

Examples

 <number> 1.25 </number>
 
 <number type="integer"> 250 </number>
 
 <number type="rational"> 1 <sep/> 3 </number>
 
 <number type="real" encoding="e-notation"> 7.6e-2 </number>

top

Sep Element

Description

The sep element is used to separate the content of the specialized forms rational and complex of the number element into two tokens. For example, sep is used when specifying the real and imaginary parts of the complex number : 1 + i (see below).

Content

Empty element.

Attributes

No attributes.

Examples

 <number type="complex"> 1.0 <sep/> 1.0 </number>

top

Annotation Element

Description

The annotation element is a versatile container that is used to specify meta-data such as : date of creation of the OSML document, authors, content description and references, units, etc...
The attributes content, group and name of this element allow to structure this extra information and to specify the type of content.

Content

The type of content is specified by the content attribute.

Attributes

Name	Value	Default	Required
content	documentation\|appInfo\|mathExpression\|definitionURL	documentation	No
group	...	No default value	No
name	...	No default value	Yes

Examples

 <annotation group="history" name="creation-date"> 2/03/2003 </annotation>

 <annotation group="history" name="last-modification"> 5/03/2003 </annotation>

 <annotation content="appInfo" name="units"> WAVENUMBER </annotation>