bond[el.bond]
A bond between atoms, or between atoms and bonds

bond is a child of bondArray and contains bond information. Bond must refer to at least two atoms (using atomRefs2) but may also refer to more for multicentre bonds. Bond is often EMPTY but may contain electron, length or stereo elements.

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>

example

<!-- Zeise's salt: Cl2Pt(CH2=CH2)-->
<atomArray>
  <atom id="pt1" elementType="Pt"/>
  <atom id="cl1" elementType="Cl"/>
  <atom id="cl2" elementType="Cl"/>
  <atom id="c1" elementType="C" hydrogenCount="2"/>
  <atom id="c2" elementType="C" hydrogenCount="2"/>
</atomArray>
<bondArray>
  <bond id="b1" atomRefs2="c1 c2" order="D"/>
  <bond id="b2" atomRefs2="pt1 cl1" order="S"/>
  <bond id="b3" atomRefs2="pt1 cl2" order="S"/>
  <bond id="b4" atomRefs="pt1" bondRefs="b1"/>
</bondArray>
Validate Bonds
<val:template match="bond" >
Atom Refs for 2-atom bond
<val:variable name="at1" select="substring-before(normalize-space(@atomRefs2),' ')" > </val:variable>
<val:variable name="at2" select="substring-after(normalize-space(@atomRefs2),' ')" > </val:variable>
Do both atoms exist in current molecule context?
<val:if test="not(key('atoms', $at1))" >
<val:call-template name="error" >
<val:with-param name="error" > BOND (
<val:value-of select="@id" > </val:value-of>
): ATOMREF not found:
<val:value-of select="$at1" > </val:value-of>
</val:with-param>
</val:call-template>
</val:if>
</val:template>
Content Model
(electron|stereo|length)*
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>
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>
atomRefs2[]
A reference to two distinct existing atoms in order

example

<molecule id="m1">
  <atomArray>
    <atom id="a1"/>  
    <atom id="a2"/>
  </atomArray>
  <bondArray>
    <bond atomRefs2="a1 a2"/>
  </bondArray>
</molecule>
[xsd:string]
Pattern: \s*\S+\s+\S+\s*
The two atoms in the bond

. This will be the normal reference attribute on the bond element. The order of atoms is preserved and may matter for some conventions (e.g. wedge/hatch or donor bonds)

atomRefs[]
The atoms in the bond

. This is designed for multicentre bonds (as in delocalised systems or electron-deficient centres. The semantics are experimental at this stage. As an example, a B-H-B bond might be described as <bond atomRefs="b1 h2 b2"/>

bondRefs[]
Bonds involved in the bond

. This is designed for pi-bonds and other systems where formal valence bonds are not drawn to atoms. The semantics are experimental at this stage. As an example, a Pt-|| bond (as the Pt-ethene bond in Zeise's salt) might be described as <bond atomRefs="pt1" bondRefs="b32"/>

order[]
Bond order (as a string)

This is purely conventional and used for bond/electron counting. 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 on the bond which links to a dictionary. Example: <bond convention="ccdc:9" atomRefs2="a1 a2"/> could represent a delocalised bond in the CCDC convention.

Allowed values

  • S
    Single bond

  • 1
    Single bond

  • D
    Double bond

  • 2
    Double bond

  • T
    Triple bond

  • 3
    Triple bond

  • A
    Aromatic bond

The order of the bond

There is NO default. This order is for bookkeeping only and is not related to length, QM calculations or other experimental or theoretical calculations. see orderType