stereo[el.stereo]

A container supporting "cis/trans", "wedge hatch" and other stereochemistry.

An explict list of atomRefs must be given, or it must be a child of bond. There are no implicit conventions such as E/Z. This will be extended to other types of stereochemistry.

At present the following are supported:

No atomRefs attribute. Deprecated, but probably unavoidable. This must be a child of bond where it picks up the two atomRefs in the atomRefs2 attribute. Possible values are C/T (which only makes sense if there is exactly one ligand at each end of the bond) and W/H. The latter should be raplaced by atomParity wherever possible. Note that W/H makes no sense without 2D atom coordinates.
atomRefs4 attribute. The 4 atoms represent a cis or trans configuration. This may or may not be a child of bond; if so the second and third atomRefs should be identical with the two atomRefs in the bond. This structure can be used to guide processors in processing stereochemistry and is recommended, since there is general agreement on the semantics. The semantics of stereo not related to bonds is less clear (e.g. cumulenes, substituted ring nuclei) etc.It is currently an error to have more than one stereo referring to the same ordered 4-atom list
atomRefs attribute. There are other stereochemical conventions such as cis/trans for metal complexes which require a variable number of reference atoms. This allows users to create their own - at present we do not see CML creating exhaustive tables. For example cis/trans square-planar complexes might require 4 (or 5) atoms for their definition, octahedral 6 or 7, etc. In principle this is very powerful and could supplement or replace the use of cis-, mer-, etc.

the atomRefs and atomRefs4 attributes cannot be used simultaneously.

example

<bondArray>
  <bond id="b1" atomRefs2="a3 a8" order="D">
    <electron bondRef="b1"/>
    <stereo>C</stereo>
  </bond>
  <bond id="b2" atomRefs2="a3 a8" order="S">
    <stereo convention="MDL" conventionValue="6"/>
  </bond>
</bondArray>

Content Model

stereoType[st.stereoType]

(Bond) stereochemistry (as a string)

. This is purely conventional; . There is no default value. The emptyString attribute can be used to indicate a bond of unknown or unspecified type. The interpretation of this is outside the scope of CML-based algorithms. It may be accompanied by a convention attribute which links to a dictionary

example

<bondArray>
  <bond id="b1" atomRefs2="a3 a8" order="D">
    <electron bondRef="b1"/>
    <stereo>C</stereo>
  </bond>
  <bond id="b2" atomRefs2="a3 a8" order="S">
    <stereo convention="MDL" conventionValue="6"/>
  </bond>
</bondArray>

Allowed values

C

A cis bond
T

A trans bond
W

A wedge bond
H

A hatch bond
empty or missing

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*

atomRefs[]

An array of atomRefs

The atomRefs cannot be schema- or schematron-validated. Instances of this type will be used in array-style representation of bonds and atomParitys. It can also be used for arrays of atomIDTypes such as in complex setereochemistry, geometrical definitions, atom groupings, etc.

example

<molecule id="m1">
  <atomArray atomID="a2 a4 a6"  
      elementType="O N S"/>
</molecule>

XSD:LIST of atomRefType

A reference to an existing atom

example

<molecule id="m1">
  <atomArray>
    <atom id="a1"/>
  </atomArray>
  <electron id="e1" atomRef="a1"/>
</molecule>

[xsd:string]

Pattern: *[A-Za-z_][A-Za-z0-9\-:_]*\s*

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>

conventionValue[]

The stereo value when the convention attribute is used

When convention is used this attribute must be present and element content must be empty.