The semantics of Chemical Markup Language (CML) for computational chemistry : CompChem.

: This paper introduces a subdomain chemistry format for storing computational chemistry data called CompChem. It has been developed based on the design, concepts and methodologies of Chemical Markup Language (CML) by adding computational chemistry semantics on top of the CML Schema. The format allows a wide range of ab initio quantum chemistry calculations of individual molecules to be stored. These calculations include, for example, single point energy calculation, molecular geometry optimization, and vibrational frequency analysis. The paper also describes the supporting infrastructure, such as processing software, dictionaries, validation tools and database repositories. In addition, some of the challenges and difficulties in developing common computational chemistry dictionaries are discussed. The uses of CompChem are illustrated by two practical applications.

Background

Introduction

Computational Quantum Chemistry is a very popular area of research today and will be even more popular in the future. This is due to several emerging key technologies. Developments in computational quantum theory, better numerical methods, as well as parallel and distributed computing, have significantly reduced the computational time (from months to days or hours). With software packages such as Gaussian [1], GAMESS (US) [2], and GAMESS-UK [3] properties of large or short-lived molecules can be calculated which may be difficult or impossible to obtain experimentally. Increasingly, this is done with little human intervention, as automated chemical model generators are becoming more and more popular [4]. As a consequence the amount of data available will very soon become too vast to be analyzed manually. Regardless of how advanced the technology is, these calculations will always require resources which may be wasted if somebody else has completed the same calculation already. For this reason efficient storage and retrieval of computational chemistry data is an important issue. To address this issue the development of an easily accessible and usable infrastructure is necessary.

At present, most computational results are output as “log files” which are designed to record information as human-readable plain text. The log files contain not only information about the calculated properties, but also metadata, such as computing environments, errors, warnings, etc. Many crucial pieces of information, such as units, computational methods or algorithms, are usually omitted from the outputs because they are often considered to be “obvious” [5] or are provided in separate documentation. Moreover, the structure of the log files depends on the software used, which creates difficulties in retrieving textual information among the different formats. This impedes the automation of the data analysis which is essential in the study of a large chemical system.

A typical solution to the problem is to extract the information from the log files (known as “parsing”) and cast them into a format that is more efficient for retrieval and processing. The eXtensible Markup Language [6] (XML) is usually selected for storing data due to its universality and extensibility for both simple and complex data. Furthermore, XML provides the means for checking conformance of the structure and data ensuring that the XML instances meet the requirements of the application in question. The fact that XML has become an industrial standard for data storage, in addition to the fact that most modern software is built to support it, are the strongest testaments to its usefulness.

For chemistry applications, the Chemical Markup Language (CML) [7-10] has been developed based on the XML standard in order to provide the semantics for chemical data. CML allows the representation of complex chemical objects by using the hierarchical tree structure of XML. In addition, CML is accompanied by a number of methodologies [11-13] and infrastructures, such as CMLXOM [14], Jumbo6 [15], Jumbo-Converter [16] and CMLValidator [17], which support the development of a more general computational chemistry format. The following features make CML specifically suited for our purpose:

1. CML contains a set of hundreds of chemical name tags covering all aspects of chemistry and so allows one to compose a suitable representation for any chemical data;

2. CML is widely supported by chemistry software, such as, OpenBabel [18], PyBel [19], Jmol [20], Avogadro [21], making it easy to integrate a subdomain format of CML into most of the existing systems which use these libraries with little modification;

3. CML has been developed over 15 years so the terminology, concepts and semantics have become highly stable, complete and well understood with relatively small changes in its schema and, as a result, it has been accepted by the chemistry community.

The purpose of this paper is to use CML to develop a standard called CompChem, which is suitable to represent computational chemistry information, including a set of supporting open-source tools. Furthermore, we illustrate the use of CompChem for managing computational chemistry data and for calculating thermodynamic properties.

The paper is structured as follows. We briefly review the important CML concepts used throughout this paper in section “CML overview”. In section “Methodology in CompChem”, we describe the requirements for the design of CompChem and the semantics and the detailed specification of CompChem. Finally, in section “Utility : example use cases”, we report a recent application with examples.

CML overview

In this section, we briefly outline the key CML concepts and terminologies, which are adopted by CompChem, for readers who are not familiar with CML. Detailed discussions have already been published in Murray-Rust et al.[13] and Townsend et al.[11]. The latest information of the ongoing developments are also publicly available online at http://www.xml-cml.org. The development of CompChem is based on the following components and concepts:

· XML Schema [22] is an XML-based schema language which specifies the constraints on the structure of an XML document. It is also written in XML and referred to as XML Schema Definition (XSD). The term “XML Schema” (with a capital “S”) should not be confused with XML schema. The latter is a term describing schema languages in general. XML Schema is one of the most commonly used schema languages today. It was published as a W3C recommendation in 2001 [23] to replace Document Type Definition (DTD) and provide additional features for defining the constraints and validating the contents of XML document.

· CML Schema [10, 24] is an XML Schema containing hundreds of chemical definitions (XML tags and attributes). It covers most aspects of chemistry, e.g., CMLReact [25] for chemical reactions, CMLSpec [26] for spectral data, CML for crystallography [27] and CML for polymers (PML) [28]. With the CML Schema, one can determine if a CML document conforms to the specification or not. For example, the schema will tell whether a CML document contains a misspelled element name or an undefined attribute. This ensures that the applications will not generate any errors due to using a “bad” CML document as their input. In the latest version of CML Schema (version 3), the content model restrictions have been lifted in order to make it more flexible for creating any type of chemical documents.

· CML Convention is a set of rules and constraints on the content model of a CML document. It is a subset of the CML Schema with some additional rules for a specific chemistry domain, some of which cannot be defined using XSD. When a convention is specified on a CML element (using the @convention attribute), the structure of the element must conform to the rules defined by the convention. The convention is represented by a short-hand notation, known as a qualify name (QName [29]), which represents a globally unique Uniform Resource Locator (URL).

· CML Dictionary is a collection of “controlled vocabularies” which are used to add semantics to generic CML elements, especially for and . There are several types of CML dictionaries, for example, property and parameter dictionaries (specified using @dictRef), unit dictionaries (specified using @unit) and unit type dictionaries (specified using @unitType). The existing dictionaries can be found at http://www.xml-cml.org/dictionary/.

· Validation is the most important step to verify whether a CML document conforms to the structure required by your application. The CML approach to validation [11] consists of several steps, e.g., CML Schema, CML convention, CML dictionary validations, and so on. These are usually performed sequentially (as shown in Figure 1), however, they are completely independent. A sophisticated online validator is available at http://validator.xml-cml.org/.

A linear schematic diagram of validation process for CompChem.

Methodology in CompChem

CompChem design

The development of CompChem started back in the summer of 2009 with the initial goal of archiving our published computational quantum chemistry results [30-34], which were calculated using the convenient software Gaussian 03, in a machine readable format and stored in a queriable database for automating the studies of chemical reactions in a combustion system. It was a collaborative effort between chemical engineers and cheminformatic scientists to explore the power of Semantic Web technologies for storing scientific data. The format was developed purely using the existing CML without making any modification to its schema. The number of elements we use in CompChem, see sections “CompChem convention” and 2, is currently relatively small compared to the whole set of CML elements available, but it is sufficient for most of the data that needs to be stored in the current work. It is very likely that other CML elements will be included to support other functionalities in later years as CompChem evolves.

Like other XML standards, the CompChem convention can only work well if it is widely accepted and, until now, there has not been one for computational chemistry, due to the varied nature of studies. This is a fact that we have to accept and, therefore, we only focus on formalizing the data calculated from the quantum chemistry software in this work.

The design of the CompChem convention shares and inherits the common goals of CML, Polymer Markup Language (PML) and other XML standards, which are quoted from XML 1.0 W3C Recommendation [6]. (Readers are advised to read this documentation for further details) These are as follows:

1. CompChem shall be straightforwardly usable over the Internet;

2. CompChem shall support a wide variety of applications;

3. CompChem shall be compatible with Standard Generalized Markup Language (SGML);

4. It shall be easy to write programs which process CompChem documents;

5. The number of optional features in CompChem is to be kept to the absolute minimum, ideally zero;

6. CompChem documents should be human-legible and reasonably clear;

7. The CompChem design should be prepared quickly;

8. The design of CompChem shall be formal and concise;

9. CompChem documents shall be easy to create;

10. Terseness in CompChem markup is of minimal importance.

Apart from these general goals, there are more specific goals which distinguish CompChem from CML and other XML standards:

1. CompChem should be based on CML and reuse its components where appropriate. This is a typical goal of all subdomain formats of CML. Reusing CML and its components is the fundamental key to improve the quality and consistency of the format and reduce development cost and effort. In addition, any future improvement made into CML and its technologies will also be immediately applied to CompChem. In the development of CompChem, we introduced no new components into the CML Schema. Instead, the new concepts are defined using CML dictionaries and are applied to generic CML containers, see Section “Using dictionary in CompChem”.

2. CompChem should capture the semantics of most computational chemistry calculations. This is the main goal of our work. It is to reduce the flexibility in CML Schema and introduce a stricter structure into the documents so that software and applications know exactly how to process the information. The semantics of CompChem is modelled based on the typical nature of computational simulations or calculations, i.e., contains model input and output steps, see Section “CompChem convention”.

3. CompChem shall support any chemical data. CML provides a rich set of chemical data types in addition to standard XML data types. It is also possible to build more complex chemical objects from the abstract CML data types and components, thus, CompChem has gained this advantages from reusing CML.

4. CompChem should be able to be validated using standard processing tools. This is an important consideration to make the CompChem platform independent. The development of CompChem involves using both CML components and CML technologies. The CML components, i.e., CML elements and attributes, are validated using CML Schema and any standard XML Schema processor. The XML stylesheet, XPath [35] and XSLT [36] are chosen for implementing and validating the CML conventions. Therefore, one should be able to validate the CompChem convention by using any web browser capable of rendering XSLT.

5. CompChem should represent both computational input and output. CompChem is designed to be used as both input and output for the calculations. The computation input contains critical information, such as calculation model, basis set, level of theory, job type, etc., that defines the calculation itself. This information is required for the search functionality of the digital repository and the calculation output is usually what is returned from the search. Being able to store input and output are required features of CompChem.

6. CompChem should interoperate with other XML or CML models (conventions). This is one of the common goals that is shared by all CML works. Interoperability is a requirement for CompChem to be used in conjunction with other existing XML-based formats such as Dublin CoreⒸMetadata (DCMI) and Object Reuse and Exchange (OAI-ORE) standards. This makes CompChem not only reuse the CML components but also other well established formats.

7. CompChem shall allow users to define and insert new concepts. As discussed earlier, new concepts are added into CompChem through the use of a dictionary mechanism. This is not only applied to the basic values, such as , , @unit and @unitType, but also the complex model objects. It is feasible to insert an entire new convention into CompChem, although, it may not be understood by all standard chemistry tools.

8. CompChem Convention rules must be clear and well documented. Although the convention rules are implemented into the CompChem convention validator using stylesheets, it is important that there must also be human readable documentation. Clear documentation benefits both users and developers in the long term. We will adhere to this in all of our development. In practice, we make the decisions on what are the rules that should be in CompChem and then write documentation from these rules. After that, we implement the rules into the convention validator. This discipline ensures that there is always documentation for every convention we develop.

Using dictionary in CompChem

Because dictionaries play a central role in defining the semantics within a CompChem document, it is essential to fully understand the concepts and how the dictionary referencing mechanism works. Both are explained in detail in this section.

Concepts are the building blocks of scientific knowledge. In natural language, similar concepts can be expressed using several words or synonyms which are the common causes of ambiguity, confusion and error when the information is being processed. In software development, several similar concepts or synonyms can be grouped and represented by a carefully pre-determined term or vocabulary, commonly known as controlled vocabulary. Using controlled vocabulary, one can impose an order and reduce ambiguity by allowing the same concepts to be labelled using a single unique term.

In XML, the tags and attributes are predetermined terms, in other words, an XML schema is a set of controlled vocabularies. CML is no exception. The CML elements and attributes are predefined to cover almost all general aspects of chemistry and computational chemistry. However, it is impossible and futile to predefine every possible chemistry concept into CML. For example, concepts like boiling point, melting point, basis set, entropy, enthalpy, methodology, algorithm, etc., are not included in the CML Schema. Instead, CML uses a dictionary and a referencing mechanism to specify a new concept on the generic CML containers, such as , , , , etc., which can be used to hold the values of any types.

A new concept can be added as an entry into a CML dictionary without requiring the CML Schema to be modified. The dictionary referencing mechanism consists of 3 steps; defining the new concept, creating a reference to the defined concept and applying the reference to the CML generic container.

· Defining a new concept. In Figure 2 (1), we show a snippet of a CML dictionary which is created according to the CML dictionary convention. A dictionary can contain multiple child elements of entries allowing the vocabulary in the same category to be grouped as one set. The figure only briefly illustrates how a dictionary and its vocabulary should be defined so readers are strongly advised to read the latest detailed specifications of the dictionary convention on www.xml-cml.orgfor more information.

· Creating a reference to the defined concept. In CML, a qualify name (QName) [29] is used to identify an entry in the dictionary. A QName contains a namespace URI [29], a local part and a prefix. The prefix is only used as a placeholder for the associated namespace URI and is declared in a namespace declaration. Therefore, in order to be able to identify the dictionary, each dictionary must have a unique identifier and it is specified using @namespace on . This is not to be confused with the XML namespace which is denoted by @xmlns. Specifying @namespace on does not change the actual XML namespace of ; it remains in the CML namespace (http://www.xml-cml.org/schema).Each entry must have a unique @id (unique within the dictionary) and this is used as the local part of the QName. The combination of the dictionary @namespace and entry @id generates a globally unique reference for the defined concept. In Figure 2 (2), the prefix “cc” is associated to the same URI (http://www.xml-cml.org/dictionary/compchem/) that is declared for the CompChem-core dictionary’s @namespace. Using the entry id “job”, a QName “cc:job” is constructed as a reference in this step.

· Applying the reference. The reference or QName can be applied to a container using @dictRef, shown in Figure 2 (3).

Diagram illustrating the dictionary referencing mechanism using @dictRef in 3 steps. A snippet of the dictionary and its entry are shown in the top (orange) box and a snippet of CompChem job module is show in the bottom (blue) box.

This referencing mechanism is not only applied to @dictRef but also @units, @unitType and other attributes. Although the mechanisms are similar, the unit and unit type dictionaries are not defined using but rather and respectively. This is because the unit and unit type are common concepts for scientific data so it has been defined in the CML Schema.

CompChem convention

According to our design criteria that CompChem convention should capture the typical underlying processes of quantum calculations and their relationships, the proposed architecture described here is broad and may be applied to any computational modeling in general. The core concepts of CompChem contain the following components:

1. Job list(jobList) In computational quantum chemistry, calculations are often comprised of a series of subtasks, e.g., coarse optimization → fine optimization → NMR Spectrum Analysis. Each job performs a different type of calculation and passes the results to the next calculation job; this is because most quantum chemistry software packages are designed to be modularized and only to perform a single task at a time. The jobList concept is introduced to capture this series of successive subtasks and links the information from one subtask to the next subtask. It behaves like a wrapper for job modules.

2. Job(job) The job concept represents a computational job or a computer simulation task, e.g., geometry optimization and frequency analysis jobs, performed by quantum chemistry software. The job concept is the smallest module that fully describes an overall picture of a computational modeling unit. It consists of model parameters (initialization) and model optimizations or calculations (calculation), model results (finalization) and computing environments (environment). These four components are fundamental to every simulation. However, it is not required that all four components be present in every job. Only model parameters are mandatory. A module that contains only model parameters may be used as an abstract quantum chemistry input.

3. Model initialization(initialization) The model initialization concept represents the model parameters and inputs for a computational job. The model parameters are one of the most important elements that exist in every modeling study. Therefore, it is required in the CompChem convention.

4. Model calculation(calculation) A model calculation concept represents the computation, the optimization or the iteration processes for the computational job specified by the initialization. The calculation process may or may not be of interest to some scientists; therefore, it is an optional information in CompChem.

5. Model finalization(finalization) A model finalization concept represents the model output or result of a computational job. In some cases, a CompChem module may only represent the model inputs and does not contain any calculations, therefore, it is optional in CompChem.

6. Computing environment(environment) The computing environment concept refers to the configuration settings with respect to the hardware platform, software application and operating system. The environment also includes metadata such as machine id, username, starting and finishing date time, tools, compilers, and Internet Protocol address (IP address).

7. User defined concept CompChem allows users to define their own concepts if the recommended concepts above do not fit into their requirements. A user defined concept in CompChem is represented by a module element with a @dictRef attribute whose value points to an entry in a dictionary that defines the concept. Users are free to design any structure for a user defined module. However, it is recommended to use existing structures or a structure that has a schema for validation. Information in a user defined module cannot be guaranteed to be understandable by all processing software tools.

Each concept, defined above, is associated with the core CompChem dictionary (available at http://www.xml-cml.org/dictionary/compchem/), whose @dictRefs and rules are given in Table 1. The rules in this table are coded into a stylesheet which can be used to validate a CompChem document. It is anticipated that the rules need to be modified or extended when more complex calculations, such as transition state searches or molecular dynamic simulations are included in CompChem.

Table 1

Rules of CompChem

dictRef.	Rules
cc:jobList	- A jobList module element MUST have an id attribute the value of which MUST be unique within the module specifying the compchem convention.
	- A jobList module element MUST contain at least one job module child element.
	- A jobList module element SHOULD have a title attribute the value of which MUST be a non-empty string specifying a human-readable title for the module.
	- A jobList module element MAY contain more than one child element in any namespace.
cc:job	- A job module element MUST contain exactly one initialization module child element.
	- A job module element MAY contain zero or more calculation module child elements.
	- A job module element MAY contain no more than one finalization module child element.
	- A job module element MAY contain no more than one environment module element.
	- The order of the calculation module elements in a job module MUST represent the order of the calculation steps but there is no restriction on the order of other child element types.
	- If a calculation module element is present, a finalization module element MUST also be present as a child of a job module element.
	- A job module element SHOULD have a title attribute, the value of which MUST be a non-empty string specifying a human-readable title for the module.
	- A job module element MAY also contain other child elements in any namespace.
cc:initialization	- An initialization module element MUST NOT contain more than one <molecule> child element. The <molecule> MUST specify a convention using the convention attribute and the convention SHOULD be one of the RECOMMENDED molecular conventions.
	- An initialization module element MUST NOT contain more than one <parameterList> element.
	- An initialization module element MAY contain any number of user defined module element.
	- An initialization module element MUST contain at least one child of molecule, <parameterList> or user defined module elements.
	- An initialization module element MAY contain more than one child element in any namespace but MUST NOT contain a property child element or a <propertyList> child element.
	- A job module element MAY also contain other child elements in any namespace.
cc:initialization	- An initialization module element MUST NOT contain more than one <molecule> child element. The <molecule> MUST specify a convention using the convention attribute and the convention SHOULD be one of the RECOMMENDED molecular conventions.
	- An initialization module element MUST NOT contain more than one <parameterList> element.
	- An initialization module element MAY contain any number of user defined module element.
	- An initialization module element MUST contain at least one child of molecule, <parameterList> or user defined module elements.
	- An initialization module element MAY contain more than one child element in any namespace but MUST NOT contain a property child element or a <propertyList> child element.
cc:calculation	- A calculation module element MUST NOT contain more than one molecule child element. The molecule MUST specify a convention using the convention attribute and the convention SHOULD be one of the RECOMMENDED molecular conventions.
	- A calculation module element MUST NOT contain more than one <parameterList> element.
	- A calculation module element MUST NOT contain more than one <propertyList> element.
	- A calculation module element MAY contain any number of user defined module elements.
	- A calculation module element MUST contain at least one child of molecule, <parameterList>, <propertyList> or user defined module elements.
	- A calculation module element MAY contain more than one child element in any namespace.
cc:finalization	- A finalization module element MUST NOT contain more than one molecule child element. The molecule MUST specify a convention using the convention attribute and the convention SHOULD be one of the RECOMMENDED molecular conventions.
	- A finalization module element MUST NOT contain more than one <propertyList> element.
	- A finalization module element MAY contain any number of user defined module elements.
	- A finalization module element MUST contain at least one molecule child, <propertyList> child or user defined module element.
	- A finalization module element MAY contain more than one child element in any namespace but MUST NOT contain a parameter child element or a <parameterList> child element.
cc:environment	- An environment module element MUST NOT contain more than one <propertyList> element.
	- Any environment property element MUST be a child of a <propertyList> element.
	- An environment module element MAY contain more than one child element in any namespace including any number of user defined module elements. However, CompChem can only understand a particular set of concepts.
	- An environment module MUST contain at least one child of <parameterList> or userDefinedModule elements.
	- An environment module element MAY contain more than one child element in any namespace but MUST NOT contain a parameter child element or a <parameterList> child element.

The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 [37].

Figure 3 shows a snippet of a CompChem document with the key features labeled accordingly.

Figure 3

The structure of CML for storing computational chemistry output: (1) CompChem convention declaration, (2) CML convention namespace, (3) a jobList module, (4) a job module, (5) an initialization module, (6) Molecular convention declaration, (7) a basis set parameter specified by cc:basis dictionary reference, (8) a Gaussian specific parameter declared in Gaussian dictionary, (9) a finalization module, (10) si:none for dimensionless units, (11) CML identifier.

Semantics of properties and parameters

There is a core set of CML which is required for storing the actual contents and data. Since CML Schema are content model free, it is necessary to precisely define how the elements should be used. In this section, we list and describe the CML elements which are often found to be useful in CompChem documents. The rules given here for these components are meant to serve only as a guideline for using the common CML components, such as , , , , and . If the given rules are not applicable, users are allowed to define their own structures and annotate it with their own dictionary reference using the @dictRef attribute. However, the new structures should be clearly specified and documented in the user dictionary so that anyone is able to write a code that can process the dictionary.

Parameter and property containers

A container is a general notion for an XML element that contains data. The CompChem element parameter is also a container. The exact definition of parameter depends on the context where it is used. In the context of CompChem, parameters are a set of model conditions which can be numerical quantities, options, constraints, text or any chemical objects, for example, a basis set (e.g., 6-311+G(d,p)), level of theory, convergence criteria, calculation type (e.g., geometry optimization, frequency analysis, NMR). Some values can be enumerated. For example, Gaussian 03/09 [1] may need to know whether it should use symmetry in the wave function or not. This option can be set to only either “NoSymm” or “Symm” according to the online manual for Gaussian software [1] and this can be pre-enumerated for use in a CompChem document with values “On” or “Off”.

In CompChem, a value cannot be added directly as a text child of a parameter. It must be wrapped by a CML primitive data container, see Section “Data containers”, which is usually one of , or . For plain text, a scalar should be used. This allows the computer software to understand exactly which variable type (i.e., variable type in programming language) is suitable for the value of a given parameter. In many cases, a primitive container is not sufficient and it requires a complex object representation to hold the data. Figure 4 shows examples of both primitive and complex chemistry objects. In Figure 4(b), we illustrate a complex object using .