torsion[el.torsion]
A torsion angle ("dihedral") between 4 distinct atoms

The atoms need not be formally bonded. It can be used for:

  • Recording experimentally determined torsion angles (e.g. in a crystallographic paper).
  • Providing the torsion component for internal coordinates (e.g. z-matrix).

Note that the order of atoms is important.

example

<molecule id="m1">
  <atomArray atomID="a1 a2 a3 a4"/>
  <torsion atomRefs4="a4 a2 a3 a1" units="degrees">123</torsion>
</molecule>
Content Model
torsionAngleType[st.torsionAngleType]
The type of a torsion angle
[xsd:decimal]
minInclusive: -360.0
maxInclusive: 360.0
id[att.id]
A unique ID for an element

This is not formally of type ID (an XML NAME which must start with a letter and contain only letters, digits and .-_:). It is recommended that IDs start with a letter, and contain no punctuation or whitespace. The function generate-id() in XSLT will generate semantically void unique IDs.

It is difficult to ensure uniqueness when documents are merged. We suggest namespacing IDs, perhaps using the containing elements as the base. Thus mol3:a1 could be a useful unique ID. However this is still experimental.

[xsd:string]
Pattern: [A-Za-z0-9_-]+(:[A-Za-z0-9_-]+)?
An attribute providing a unique ID for an element
title[att.title]
A title on an element.
No controlled value.

example

<action title="turn on heat" start="T09:00:00" convention="xsd"/>
convention[att.convention]
A string referencing a dictionary, units, convention or other metadata.

The namespace is optional but recommended where possible

Note: this convention is only used within STMML and related languages; it is NOT a generic URI.

example

<list>
<!-- dictRef is of namespaceRefType -->
  <scalar dictRef="chem:mpt">123</scalar>  
<!-- error -->
  <scalar dictRef="mpt23">123</scalar>  
</list>
[xsd:string]
Pattern: [A-Za-z][A-Za-z0-9_]*(:[A-Za-z][A-Za-z0-9_]*)?
A reference to a convention

There is no controlled vocabulary for conventions, but the author must ensure that the semantics are openly available and that there are mechanisms for implementation. The convention is inherited by all the subelements, so that a convention for molecule would by default extend to its bond and atom children. This can be overwritten if necessary by an explicit convention.

It may be useful to create conventions with namespaces (e.g. iupac:name). Use of convention will normally require non-STMML semantics, and should be used with caution. We would expect that conventions prefixed with "ISO" would be useful, such as ISO8601 for dateTimes.

There is no default, but the conventions of STMML or the related language (e.g. CML) will be assumed.

example

<bond convention="fooChem" order="-5"
   xmlns:fooChem="http://www.fooChem/conventions"/>
dictRef[att.dictRef]
A string referencing a dictionary, units, convention or other metadata.

The namespace is optional but recommended where possible

Note: this convention is only used within STMML and related languages; it is NOT a generic URI.

example

<list>
<!-- dictRef is of namespaceRefType -->
  <scalar dictRef="chem:mpt">123</scalar>  
<!-- error -->
  <scalar dictRef="mpt23">123</scalar>  
</list>
[xsd:string]
Pattern: [A-Za-z][A-Za-z0-9_]*(:[A-Za-z][A-Za-z0-9_]*)?

A reference to a dictionary entry.

Elements in data instances such as scalar may have a dictRef attribute to point to an entry in a dictionary. To avoid excessive use of (mutable) filenames and URIs we recommend a namespace prefix, mapped to a namespace URI in the normal manner. In this case, of course, the namespace URI must point to a real XML document containing entry elements and validated against STMML Schema.

Where there is concern about the dictionary becoming separated from the document the dictionary entries can be physically included as part of the data instance and the normal XPointer addressing mechanism can be used.

This attribute can also be used on dictionary elements to define the namespace prefix

example

<scalar dataType="xsd:float" title="surfaceArea" 
  dictRef="cmlPhys:surfArea" 
  xmlns:cmlPhys="http://www.xml-cml.org/dict/physical"
  units="units:cm2">50</scalar>

example

<stm:list xmlns:stm="http://www.xml-cml.org/schema/stmml">
  <stm:observation>
    <p>We observed <object count="3" dictRef="#p1"/> 
      constructing dwellings of different material</p>
  </stm:observation>
  <stm:entry id="p1" term="pig">
    <stm:definition>A domesticated animal.</stm:definition>
    <stm:description>Predators include wolves</stm:description>
    <stm:description class="scientificName">Sus scrofa</stm:description>
  </stm:entry>
</stm:list>
atomRefs4[att.atomRefs4]
A reference to four distinct existing atoms in order

example

<molecule id="m1">
  <atomArray>
    <atom id="a1"/>  
    <atom id="a2"/>
    <atom id="a3"/>
    <atom id="a4"/>
  </atomArray>
  <torsion atomRefs4="a1 a2 a3 a4" units="degrees">123.4</torsion>
</molecule>
[xsd:string]
Pattern: \s*(\S+\s+){3}\S+\s*
A list of 4 references to atoms.
Typically used for defining torsions and atomParities, but could also be used to define a four-centre bond.
units[att.units]
Scientific units

These will be linked to dictionaries of units with conversion information, using namespaced references (e.g. si:m)

Distinguish carefully from unitType which is an element describing a type of a unit in a unitList

example

<stm:unitList xmlns:stm="http://www.xml-cml.org/schema/stmml">

<!-- ======================================================================= -->
<!-- ========================= fundamental types =========================== -->
<!-- ======================================================================= -->

<stm:unitType id="length" name="length">
  <stm:dimension name="length"/>
</stm:unitType>

<stm:unitType id="time" name="time">
  <stm:dimension name="time"/>
</stm:unitType>

<!-- ... -->

<stm:unitType id="dimensionless" name="dimensionless">
  <stm:dimension name="dimensionless"/>
</stm:unitType>

<!-- ======================================================================= -->
<!-- ========================== derived types ============================== -->
<!-- ======================================================================= -->

<stm:unitType id="acceleration" name="acceleration">
  <stm:dimension name="length"/>
  <stm:dimension name="time" power="-2"/>
</stm:unitType>

<!-- ... -->

<!-- ======================================================================= -->
<!-- ====================== fundamental SI units =========================== -->
<!-- ======================================================================= -->

<stm:unit id="second" name="second" unitType="time">
  <stm:description>The SI unit of time</stm:description>
</stm:unit>

<stm:unit id="meter" name="meter" unitType="length"
  abbreviation="m">
  <stm:description>The SI unit of length</stm:description>
</stm:unit>

<!-- ... -->

<stm:unit id="kg" name="nameless" unitType="dimensionless"
  abbreviation="nodim">
  <stm:description>A fictitious parent for dimensionless units</stm:description>
</stm:unit>

<!-- ======================================================================= -->
<!-- ===================== derived SI units ================================ -->
<!-- ======================================================================= -->

<stm:unit id="newton" name="newton" unitType="force">
  <stm:description>The SI unit of force</stm:description>
</stm:unit>

<!-- ... -->

<!-- multiples of fundamental SI units -->

<stm:unit id="g" name="gram" unitType="mass"
  parentSI="kg"
  multiplierToSI="0.001"
  abbreviation="g">
  <stm:description>0.001 kg. </stm:description>
</stm:unit>

<stm:unit id="celsius" name="Celsius" parentSI="k"
  multiplierToSI="1" 
  constantToSI="273.18">
  <stm:description><p>A common unit of temperature</p></stm:description>
</stm:unit>

<!-- fundamental non-SI units -->

<stm:unit id="inch" name="inch" parentSI="meter"
   abbreviation="in"
  multiplierToSI="0.0254" >
  <stm:description>An imperial measure of length</stm:description>
</stm:unit>

<!-- derived non-SI units -->

<stm:unit id="l" name="litre" unitType="volume"
   parentSI="meterCubed"
   abbreviation="l"
   multiplierToSI="0.001">
  <stm:description>Nearly 1 dm**3 This is not quite exact</stm:description>
</stm:unit>

<!-- ... -->

<stm:unit id="fahr" name="fahrenheit" parentSI="k"
   abbreviation="F"
  multiplierToSI="0.55555555555555555" 
  constantToSI="-17.777777777777777777">
  <stm:description>An obsolescent unit of temperature still used in popular
  meteorology</stm:description>
</stm:unit>

</stm:unitList>
[xsd:string]
Scientific units on an element.
These must be taken from a dictionary of units. There should be some mechanism for validating the type of the units against the possible values of the element.
errorValue[att.errorValue]
An observed or calculated estimate of the error in the value of a numeric quantity

An observed or calculated estimate of the error in the value of a numeric quantity. . It should be ignored for dataTypes such as URL, date or string. The statistical basis of the errorValueType is not defined - it could be a range, an estimated standard deviation, an observed standard error, etc. This information can be added through errorBasisType.

example

<scalar 
    dataType="xsd:decimal" 
    errorValue="1.0" 
    errorBasis="observedStandardDeviation" 
    title="body weight"
    dictRef="zoo:bodywt"
    units="units:g">34.3</scalar>
[xsd:decimal]
errorBasis[att.errorBasis]
The basis of an error value

Errors in values can be of several types and this simpleType provides a small controlled vocabulary

example

<scalar 
    dataType="xsd:decimal" 
    errorValue="1.0" 
    errorBasis="observedStandardDeviation" 
    title="body weight"
    dictRef="zoo:bodywt"
    units="units:g">34.3</scalar>

Allowed values

  • observedRange
  • observedStandardDeviation
  • observedStandardError
  • estimatedStandardDeviation
  • estimatedStandardError
min[att.min]
The minimum INCLUSIVE value of a quantity

The minimum INCLUSIVE value of a sortable quantity such as numeric, date or string. It should be ignored for dataTypes such as URL. The use of min and min attributes can be used to give a range for the quantity. The statistical basis of this range is not defined. The value of min is usually an observed quantity (or calculated from observations). To restrict a value, the minExclusive type in a dictionary should be used.

The type of the minimum is the same as the quantity to which it refers - numeric, date and string are currently allowed

example

<scalar dataType="xsd:float" maxValue="20" minValue="12">15</scalar>
[xsd:string]
max[att.max]
The maximum INCLUSIVE value of a quantity

The maximum INCLUSIVE value of a sortable quantity such as numeric, date or string. It should be ignored for dataTypes such as URL. The use of min and max attributes can be used to give a range for the quantity. The statistical basis of this range is not defined. The value of max is usually an observed quantity (or calculated from observations). To restrict a value, the maxExclusive type in a dictionary should be used.

The type of the maximum is the same as the quantity to which it refers - numeric, date and string are currently allowed

example

<scalar dataType="xsd:float" maxValue="20" minValue="12">15</scalar>
[xsd:string]
ref[att.ref]
A reference to an existing element

A reference to an existing element in the document. The target of the ref attribute must exist. The test for validity will normally occur in the element's appinfo

Any DOM Node created from this element will normally be a reference to another Node, so that if the target node is modified a the dereferenced content is modified. At present there are no deep copy semantics hardcoded into the schema.

BASE: idType
A unique ID for an element

This is not formally of type ID (an XML NAME which must start with a letter and contain only letters, digits and .-_:). It is recommended that IDs start with a letter, and contain no punctuation or whitespace. The function generate-id() in XSLT will generate semantically void unique IDs.

It is difficult to ensure uniqueness when documents are merged. We suggest namespacing IDs, perhaps using the containing elements as the base. Thus mol3:a1 could be a useful unique ID. However this is still experimental.

[xsd:string]
Pattern: [A-Za-z0-9_-]+(:[A-Za-z0-9_-]+)?
A reference to an element of given type

ref modifies an element into a reference to an existing element of that type within the document. This is similar to a pointer and it can be thought of a strongly typed hyperlink. It may also be used for "subclassing" or "overriding" elements.

example

<cml>
  <molecule id="m1">
    <atomArray>
      <atom elementType="N"/>
      <atom elementType="O"/>
    </atomArray>
  </molecule>
  <html:p>The action of <molecule ref="#m1"/> on cardiac muscle ...</html:p>
</cml>