chemicalml 0.1.0

data/reference-docs/conventions/compchem.md

@@ -0,0 +1,141 @@
+<!-- Source: http://www.xml-cml.org/convention/compchem -->
+<!-- Editors: Weerapong Phadungsukanan, Sam Adams, Joe Townsend, Jens Thomas -->
+<!-- License: CC-BY-3.0 (http://creativecommons.org/licenses/by/3.0/) -->
+
+# CML CompChem Convention
+
+**This version:** http://www.xml-cml.org/convention/compchem-20110524
+**Latest version:** http://www.xml-cml.org/convention/compchem
+**Editors:** Weerapong Phadungsukanan, Sam Adams, Joe Townsend (University
+of Cambridge); Jens Thomas (STFC Daresbury Laboratory).
+
+## Abstract
+
+This specification defines the requirements of the Chemical Markup Language
+CompChem convention.
+
+## Namespaces
+
+| Prefix | Namespace URI | Description |
+| --- | --- | --- |
+| `cml` | `http://www.xml-cml.org/schema` | Chemical Markup Language elements |
+| `convention` | `http://www.xml-cml.org/convention/` | Standard CML convention namespace |
+| `compchem` | `http://www.xml-cml.org/dictionary/compchem/` | CompChem Dictionary namespace |
+| `xhtml` | `http://www.w3.org/1999/xhtml` | XHTML |
+| `dc` | `http://purl.org/dc/elements/1.1/` | Dublin Core Metadata Element Set, v1.1 |
+
+## Applying the CompChem convention
+
+The CompChem convention MUST be specified using the `convention`
+attribute on a `module` element, with value `convention:compchem`. A
+CompChem module MUST contain at least one `jobList` module child (e.g.
+`<module dictRef="compchem:jobList" id="jobList-0000">`).
+
+## Core concepts
+
+- **JobList** — series of successive subtasks
+- **Job** — a computational job (input + calculations + output + environment)
+- **Initialization** — model parameters/inputs (REQUIRED)
+- **Calculation** — computation/optimisation/iteration (OPTIONAL, nestable)
+- **Finalization** — model outputs/results (OPTIONAL)
+- **Environment** — host, software, runtime metadata (OPTIONAL)
+- **User defined concept** — extension modules with a `dictRef`
+
+## Structural rules
+
+### jobList module
+
+- MUST have `dictRef="compchem:jobList"` on a `module` element
+- MUST have an `id` unique within the compchem module
+- MUST contain at least one `job` module child
+- SHOULD have a `title`
+
+### job module
+
+- MUST have `dictRef="compchem:job"` on a `module` element
+- MUST have an `id` unique within the compchem module
+- MUST contain exactly one `initialization` module child
+- MAY contain zero or more `calculation` module children
+- MAY contain no more than one `finalization` module child
+- MAY contain no more than one `environment` module child
+- If a `calculation` is present, a `finalization` MUST also be present
+
+### initialization module
+
+- MUST have `dictRef="compchem:initialization"`
+- MUST NOT contain more than one `molecule` child (the molecule MUST
+  specify its convention, SHOULD be molecular)
+- MUST NOT contain more than one `parameterList`
+- MAY contain any number of `list` elements (for complex objects like
+  basis sets, DFT functionals)
+- MUST contain at least one of: `molecule`, `parameterList`, or a
+  user-defined module
+- MUST NOT contain `property` or `propertyList` children
+
+### calculation module
+
+- MUST have `dictRef="compchem:calculation"`
+- MUST NOT contain more than one `molecule` child
+- MUST contain exactly one `initialization` module child
+- MAY contain zero or more `calculation` module children
+- MAY contain no more than one `finalization` module child
+
+### finalization module
+
+- MUST have `dictRef="compchem:finalization"`
+- MUST NOT contain more than one `molecule` child
+- MUST NOT contain more than one `propertyList`
+- MUST contain at least one of: `molecule`, `propertyList`, or a
+  user-defined module
+- MUST NOT contain `parameter` or `parameterList` children
+
+### environment module
+
+- MUST have `dictRef="compchem:environment"`
+- MUST NOT contain more than one `propertyList`
+- MUST contain at least one of: `parameterList`, user-defined module
+- MUST NOT contain `parameter` or `parameterList` directly (only via
+  `propertyList`)
+
+## Value containers
+
+CompChem currently only allows `scalar`, `array`, and `matrix` value
+containers.
+
+### scalar
+
+- MUST have `dataType` attribute: `xsd:string`, `xsd:integer`, or `xsd:double`
+- MUST have `units` if dataType is `xsd:integer` or `xsd:double`
+  (even if "unknown" or "dimensionless")
+- MUST NOT have `units` if dataType is `xsd:string`
+
+### array
+
+- MUST have `size` attribute (minimum 1)
+- `dataType` MUST be `xsd:integer` or `xsd:double`
+- MUST have `units` (even if dimensionless)
+
+### matrix
+
+- MUST have `rows` and `columns` attributes (minimum 1)
+- `dataType` MUST be `xsd:integer` or `xsd:double`
+- MUST have `units` (even if dimensionless)
+
+## Recommended properties/parameters
+
+### environment module
+
+- `hostName`, `runDate`, `program`, `programVersion`
+
+### initialization module
+
+- `basisSet`, `charge`, `dftFunctional`, `method`, `pointGroup`,
+  `spinMultiplicity`, `task`, `title`, `wavefunctionType`
+
+### finalization module
+
+- `nuclearRepulsionEnergy`, `totalEnergy`, `wallTime`
+
+## Acknowledgements
+
+Peter Murray-Rust, Joe Townsend, Sam Adams.

data/reference-docs/conventions/dictionary.md

@@ -0,0 +1,119 @@
+<!-- Source: http://www.xml-cml.org/convention/dictionary -->
+<!-- Editors: Sam Adams, Joe Townsend (University of Cambridge) -->
+<!-- License: CC-BY-3.0 (http://creativecommons.org/licenses/by/3.0/) -->
+
+# CML Dictionary Convention
+
+**This version:** http://www.xml-cml.org/convention/dictionary-20110525
+**Latest version:** http://www.xml-cml.org/convention/dictionary
+**Editors:** Sam Adams, Joe Townsend (University of Cambridge)
+
+## Abstract
+
+This specification defines the requirements of the Chemical Markup Language
+dictionary convention.
+
+## Namespaces
+
+| Prefix | Namespace URI | Description |
+| --- | --- | --- |
+| `cml` | `http://www.xml-cml.org/schema` | Chemical Markup Language elements |
+| `convention` | `http://www.xml-cml.org/convention/` | Standard CML convention namespace |
+| `xhtml` | `http://www.w3.org/1999/xhtml` | XHTML |
+
+## Applying the dictionary convention
+
+The dictionary convention MUST be specified using the `convention`
+attribute on either a `cml` or a `dictionary` element. If specified on a
+`cml` element, that element MUST contain a single child `dictionary`
+element in the CML namespace.
+
+## Dictionary Element
+
+### Namespace
+
+The `dictionary` element MUST have a `namespace` attribute, the value of
+which MUST be a valid URI defining the scope within which the entry terms
+are unique. The namespace URI SHOULD end with `/` or `#` so terms can be
+referenced by appending them to the URI.
+
+### Prefix
+
+The `dictionary` element SHOULD have a `dictionaryPrefix` attribute
+specifying the default prefix. MUST be a valid XML QName prefix, SHOULD
+be unique within the CML domain.
+
+### Title
+
+The `dictionary` element SHOULD have a `title` attribute for
+human-readability.
+
+### Description
+
+The `dictionary` element SHOULD have a single `description` child
+element. MUST contain one or more child elements in the XHTML namespace.
+MUST NOT contain any non-XHTML child elements.
+
+### Entries
+
+The `dictionary` element MUST contain one or more child `entry` elements,
+and MUST NOT contain any other child elements from the CML namespace.
+
+## Entry Elements
+
+### Id
+
+An `entry` element MUST have an `id` attribute, the value of which MUST
+be unique within the scope of the dictionary. MUST start with a letter,
+MUST only contain letters, numbers, dot, hyphen or underscore.
+
+| | | |
+| --- | --- | --- |
+| `IdStartChar` | ::= | `[A-Z] \| [a-z]` |
+| `IdChar` | ::= | `IdStartChar \| [0-9] \| "." \| "-" \| "_"` |
+| `Id` | ::= | `IdStartChar (IdChar)*` |
+
+### Term
+
+An `entry` element MUST have a `term` attribute, the value of which
+provides a unique nounal phrase linguistically identifying the subject
+of the entry.
+
+### Definition
+
+An `entry` element MUST contain a single `definition` child element. MUST
+contain one or more child elements in the XHTML namespace. MUST NOT
+contain any non-XHTML child elements.
+
+### Description
+
+An `entry` element MAY have a single `description` child element providing
+further information: examples, human-readable semantics, hyperlinks. MUST
+contain XHTML child elements only.
+
+### Data type
+
+When applicable, an `entry` SHOULD have `dataType` attribute, value is a
+QName referencing the data type of the value. Common types:
+`xsd:string`, `xsd:double`, `xsd:integer`, `xsd:boolean`.
+
+### Unit type
+
+An `entry` MUST have a `unitType` attribute, value is a QName referencing
+the unit type (e.g. temperature). An entry describing a concept that
+should not have units (e.g. name of a program) should have unitType
+`none` in the standard CML unitType dictionary.
+
+### Default units
+
+When applicable, an `entry` SHOULD have a `units` attribute, value is a
+QName referencing the default units (e.g. Kelvin).
+
+If `unitType` is `unknown`, the `units` attribute MUST NOT be present.
+If `unitType` is `none`, the `units` attribute MUST be present and must
+point to `http://www.xml-cml.org/unit/si#none`.
+
+## Acknowledgements
+
+Peter Murray-Rust, Joe Townsend, Nick England, Weerapong Phadungsukanan,
+Daniel Lowe, Sam Adams, Hannah Barjat.

data/reference-docs/conventions/index.md

@@ -0,0 +1,56 @@
+<!-- Source: http://www.xml-cml.org/convention/ -->
+<!-- License: CC-BY-3.0 (http://creativecommons.org/licenses/by/3.0/) -->
+
+# CML Conventions
+
+Different domains of chemistry think about chemistry differently; often this
+means a very tight specification of rules in *your* area of expertise and
+very little if any applied to the rest. The loosening of the CML content
+model in Schema 3 allows users to combine the elements and attributes as
+they need to represent data. However, users still need to be able to
+specify a set of rules (constraints) which model their particular domain.
+This can be likened to thinking of the elements and attributes of CML as
+representing the allowed vocabulary and the set of rules as a grammar
+specifying how these words are allowed to be put together. The entire set
+of constraints which the CML should conform to is called a `convention`.
+
+## Implemented Conventions
+
+The list of currently supported conventions is given below:
+
+Molecular Convention
+:   namespace: `http://www.xml-cml.org/convention/molecular`
+
+CompChem Convention
+:   namespace: `http://www.xml-cml.org/convention/compchem`
+
+Dictionary Convention
+:   namespace: `http://www.xml-cml.org/convention/dictionary`
+
+Unit Dictionary Convention
+:   namespace: `http://www.xml-cml.org/convention/unit-dictionary`
+
+Unit-Type Dictionary Convention
+:   namespace: `http://www.xml-cml.org/convention/unitType-dictionary`
+
+There is also a *toy* convention `simpleUnit` which is used as a very
+simple example in the CMLLite paper. The namespace of the convention is
+`http://www.xml-cml.org/convention/simpleUnit`.
+
+The `dictionary` convention is currently in the most finished state and
+acts as a template for how conventions will be described in future.
+
+Constraints are defined by using XSL Transformations (XSLT). These allow
+users to put more specific constraints and co-constraints on the allowed
+structure of the CML documents than using only schemas. The output is
+based on the ISO Schematron standard XML report language SVRL
+(Schematron Validation Report Language) to indicate errors and warnings
+in the document.
+
+Examples of constraints implemented in the `molecular` convention are:
+
+- an `atomArray` must have at least one `atom` child
+- the value of an `atom`'s `id` must be unique within the eldest
+  containing molecule
+- a `bond` element must have an `atomRefs2` attribute
+- a `bond` must be between `atom`s within the same molecule

data/reference-docs/conventions/molecular.md

@@ -0,0 +1,115 @@
+<!-- Source: http://www.xml-cml.org/convention/molecular -->
+<!-- Editors: Sam Adams, Joe Townsend (University of Cambridge) -->
+<!-- License: CC-BY-3.0 (http://creativecommons.org/licenses/by/3.0/) -->
+
+# CML Molecular Convention
+
+**This version:** http://www.xml-cml.org/convention/molecular-20110828
+**Latest version:** http://www.xml-cml.org/convention/molecular
+**Authors:** See acknowledgments.
+**Editors:** Sam Adams, Joe Townsend (University of Cambridge)
+
+## Abstract
+
+This specification defines the requirements of the Chemical Markup Language
+Molecular convention. This document describes the concepts which are
+introduced in the molecular convention, explains how to compose a document
+that conforms to the molecular convention and illustrates these with
+examples.
+
+## Namespaces
+
+| Prefix | Namespace URI | Description |
+| --- | --- | --- |
+| `cml` | `http://www.xml-cml.org/schema` | Chemical Markup Language elements |
+| `convention` | `http://www.xml-cml.org/convention/` | Standard CML convention namespace |
+
+## Applying the molecular convention
+
+The molecular convention MUST be specified using the `convention`
+attribute on a `molecule` element or a `cml` element. The value of the
+attribute MUST be a QName that represents the molecular convention,
+i.e. `convention:molecular`. If the molecular convention is specified
+on a `cml` element then that element MUST have at least one child
+`molecule` element that either has no convention specified or specifies
+the molecular convention.
+
+## Molecule Element
+
+Within the molecular convention, a `molecule` is REQUIRED to be a child
+of either `cml` or `molecule` elements.
+
+A `molecule` MAY hold any combination of:
+
+1. a string representation of a molecule (`name`, `label`, or `inline`
+   attribute on `formula`)
+2. the chemical composition of a substance (`concise` attribute on
+   `formula`, or `atomArray`)
+3. a connection table of `atom`s connected by `bond`s
+
+### Molecule sub-rules
+
+- `id` — REQUIRED, unique within document scope. Pattern:
+  `[A-Za-z][A-Za-z0-9._-]*`
+- `count` — REQUIRED on child molecules, MUST NOT appear on top-level
+  molecules. Non-negative number.
+- `atomArray` — at most one. Mutually exclusive with child `molecule`s.
+- `bondArray` — at most one. Mutually exclusive with child `molecule`s.
+- `formula` — any number
+- `property` — any number
+- `label` — any number
+- `name` — any number
+- `formalCharge` — RECOMMENDED
+- `spinMultiplicity` — RECOMMENDED
+- `chirality` — OPTIONAL
+- `spectrum` — any number, each MUST specify its own convention
+
+## AtomArray
+
+MUST be a child of `molecule` or `formula`. Container for `atom`s.
+MUST contain at least one child `atom`.
+
+## BondArray
+
+MUST be a child of `molecule`. Container for `bond`s.
+MUST contain at least one child `bond`.
+
+## Atom Element
+
+MUST be a child of `atomArray`. MUST have `elementType` attribute.
+MUST have `id` if inside an `atomArray` in a `molecule` (optional in
+`formula`).
+
+Supported attributes: `x2`/`y2` (2D display, must appear together),
+`x3`/`y3`/`z3` (3D coords in Angstrom, right-handed, must appear
+together), `formalCharge`, `isotopeNumber`, `spinMultiplicity`,
+`count` (only inside `formula`), `atomParity` child, any number of
+`label` and `property` children.
+
+## Bond Element
+
+MUST be a child of `bondArray`. Bonds are between exactly two `atom`s
+in the same parent `molecule`.
+
+- `atomRefs2` — REQUIRED, two distinct atom ids in same molecule
+- `order` — REQUIRED. Recommended values: `S`, `D`, `T`, `Q`, `A`.
+  Numeric values NOT recommended. If `other`, MUST have `dictRef`.
+- `id` — RECOMMENDED, unique within eldest containing molecule
+- `bondStereo` child — OPTIONAL
+- `label` children — any number
+
+## BondStereo Element
+
+MUST be a child of `bond`. Supports cis (`C`) / trans (`T`) and
+wedge (`W`) / hatch (`H`).
+
+- If value is `W` or `H` — MUST have `atomRefs2` (the two atoms in the
+  parent bond; first = sharp end, second = blunt end). MUST NOT have
+  `atomRefs4`.
+- If value is `C` or `T` — MUST have `atomRefs4` (four distinct atom
+  ids; two MUST be the parent bond's atoms). MUST NOT have `atomRefs2`.
+- If value is `other` — MUST have `dictRef`.
+
+## Acknowledgements
+
+Joe Townsend, Peter Murray-Rust, Alex Wade, Sam Adams.

data/reference-docs/conventions/unit-dictionary.md

@@ -0,0 +1,92 @@
+<!-- Source: http://www.xml-cml.org/convention/unit-dictionary -->
+<!-- Editors: Sam Adams, Joe Townsend (University of Cambridge) -->
+<!-- License: CC-BY-3.0 (http://creativecommons.org/licenses/by/3.0/) -->
+
+# CML Unit Dictionary Convention
+
+**This version:** http://www.xml-cml.org/convention/unit-dictionary-20110303
+**Latest version:** http://www.xml-cml.org/convention/unit-dictionary
+**Editors:** Sam Adams, Joe Townsend (University of Cambridge)
+
+## Abstract
+
+This specification defines the requirements of the Chemical Markup
+Language unit-dictionary convention.
+
+## Applying the unit-dictionary convention
+
+The unit-dictionary convention MUST be specified using the `convention`
+attribute on a `unitList` element.
+
+## UnitList Element
+
+### Namespace
+
+The `unitList` element MUST have a `namespace` attribute, value MUST be
+a valid URI defining the scope within which the unit ids are unique.
+SHOULD end with `/` or `#`.
+
+### Title
+
+The `unitList` element SHOULD have a `title` attribute (non-empty).
+
+### Description
+
+The `unitList` element SHOULD have a single `description` child element.
+MUST contain XHTML child elements only.
+
+### Units
+
+The `unitList` element MUST contain one or more child `unit` elements,
+and MUST NOT contain any other child elements from the CML namespace.
+
+## Unit Elements
+
+### Id
+
+A `unit` element MUST have an `id` attribute, unique within the
+unitList. Pattern: same as dictionary entry ids.
+
+### Title
+
+A `unit` element MUST have a `title` attribute — typically the full
+name (id is the abbreviation, e.g. id=`kg`, title=`kilogram`).
+
+### Symbol
+
+A `unit` element MUST have a `symbol` attribute — the full symbol used
+to represent this unit (e.g. `K`, `Hz`, `J`, `Bq`).
+
+### Parent SI
+
+A `unit` element MUST have a `parentSI` attribute — QName referencing
+the parent SI unit (e.g. calorie's parentSI is joule).
+
+### Multiplier and/or Constant to SI
+
+A `unit` element MUST have at least one of `multiplierToSI` or
+`constantToSI` (both doubles).
+
+- `multiplierToSI` — factor to multiply by to convert to SI (applied
+  before constantToSI). Unity for SI units.
+- `constantToSI` — amount to add to convert to SI (applied after
+  multiplierToSI). Zero for SI units.
+
+### Unit Type
+
+Every `unit` element MUST have a `unitType` attribute — QName
+referencing the unit type (time, temperature, length, force, ...).
+
+### Definition
+
+A `unit` element MUST contain a single `definition` child element with
+XHTML content.
+
+### Description
+
+A `unit` element MAY have a single `description` child element with
+XHTML content.
+
+## Acknowledgements
+
+Peter Murray-Rust, Joe Townsend, Sam Adams, Egon Willighagen.

data/reference-docs/conventions/unitType-dictionary.md

@@ -0,0 +1,51 @@
+<!-- Source: http://www.xml-cml.org/convention/unitType-dictionary -->
+<!-- Editors: Sam Adams, Joe Townsend (University of Cambridge) -->
+<!-- License: CC-BY-3.0 (http://creativecommons.org/licenses/by/3.0/) -->
+
+# CML Unit-Type Dictionary Convention
+
+**Latest version:** http://www.xml-cml.org/convention/unitType-dictionary
+**Editors:** Sam Adams, Joe Townsend (University of Cambridge)
+
+## Abstract
+
+This specification defines the requirements of the Chemical Markup
+Language unitType-dictionary convention. Unit types abstract over
+units: e.g. the units metre, angstrom and picometre are all of type
+*length*; Kelvin is of type *temperature*.
+
+## Applying the unitType-dictionary convention
+
+The unitType-dictionary convention MUST be specified using the
+`convention` attribute on a `unitTypeList` element.
+
+## UnitTypeList Element
+
+The `unitTypeList` element MUST have a `namespace` attribute (valid URI,
+SHOULD end with `/` or `#`).
+
+The `unitTypeList` element SHOULD have a `title` attribute (non-empty).
+
+The `unitTypeList` element SHOULD have a single `description` child
+element with XHTML content.
+
+The `unitTypeList` element MUST contain one or more child `unitType`
+elements, and MUST NOT contain any other CML-namespace child elements.
+
+## UnitType Elements
+
+A `unitType` element MUST have an `id` attribute unique within the
+unitTypeList. Pattern: `[A-Za-z][A-Za-z0-9._-]*`.
+
+A `unitType` element MUST have a `name` attribute — the full name of
+the unit type (e.g. `length`, `temperature`, `time`).
+
+A `unitType` element MUST contain a single `definition` child element
+with XHTML content.
+
+A `unitType` element MAY have a single `description` child element with
+XHTML content.
+
+## Acknowledgements
+
+Peter Murray-Rust, Joe Townsend, Sam Adams, Egon Willighagen.