chemicalml 0.1.0

data/reference-docs/dictionaries/compchem.md

@@ -0,0 +1,335 @@
+<!-- Source: http://www.xml-cml.org/dictionary/compchem/ -->
+<!-- Authors: Peter Murray-Rust, Weerapong Phadungsukanan, Jens Thomas -->
+<!-- License: CC-BY-3.0 (http://creativecommons.org/licenses/by/3.0/) -->
+
+# CompChem Dictionary
+
+Toplevel dictionary for computational chemistry.
+
+Concepts in this dictionary are general throughout computational
+chemistry and are used extensively in the CompChem convention to
+describe the structure of computational chemistry.
+
+Author: Weerapong Phadungsukanan.
+
+## Entries
+
+### calculation
+
+A calculation module for a computational job.
+
+A calculation module represents the concept of the model calculation,
+optimisation or iteration processes for a computational job. Almost any
+computational procedure is a calculation, and calculations can be nested
+to any level. As an example, an SCF calculation consists of an initial
+guess calculation, and a number of iterative calculations, the output of
+the final iteration constituting the results. An SCF geometry optimisation
+process consists of multiple calculation steps, each of which consists of
+an SCF calculation, followed by a gradient calculation.
+
+A calculation must contain an initialization module, which defines the
+inputs to the calculation (and therefore the calculation), and a
+finalization module, which holds all outputs. The calculation module may
+contain many other modules describing the process of the calculation, but
+that may not necessarily be desirable as results.
+
+### environment
+
+Module holding concepts relating to the environment that the job used or
+required.
+
+The computing environment concept refers to a hardware platform, software
+application, the operating system and any hardware and software
+configurations used in order to run the job or computational task. The
+environment includes metadata such as machine id, username, starting and
+finishing date time, tools, compilers, IP, etc.
+
+This information is not related to input and output of the model but is
+supplementary to the software application to run properly and may vary
+from machine to machine. Therefore, the computing environment is OPTIONAL
+in the CompChem convention.
+
+### finalization
+
+A finalization module for a computational job or calculation.
+
+Represents the concept of the model results for a computational job or
+calculation. This will usually be the output properties of the final
+calculation carried out by the job. The finalization module should contain
+a propertyList with scalar, array and matrix quantities, but may also
+contain more complex objects such as molecules or orbitals as cml:lists.
+
+### initialization
+
+An initialization module for a computational job or calculation.
+
+Represents the concept of the model parameters and inputs. The module
+defines the calculation, so that it should be possible to reproduce the
+calculation based solely on the data in this module. The initialization
+module should contain a parameterList with scalar, array and matrix
+quantities, and the starting molecule, but may also contain more complex
+objects as cml:lists, such as the basis set.
+
+### job
+
+A job or computational task.
+
+The job concept represents a computational job performed by quantum
+chemistry software, e.g. geometry optimisation job, frequency analysis
+job. The job can be considered as the unit of work that would be
+submitted to a computational resource. In almost all respects a job is
+identical to a calculation, in that it has an initialization module,
+which holds the inputs for the calculation(s) to be run, and a
+finalization module, which holds all outputs. In addition, a job may
+contain an environment module.
+
+### jobList
+
+A list of computational jobs.
+
+A quantum chemistry calculation is often comprised of a series of
+subtasks, e.g. coarse optimisation -> fine optimisation -> NMR Spectrum
+Analysis. The joblist concept captures these series of successive
+subtasks and links the information from one subtask to the next.
+
+### compileDate
+
+The date that the executable was compiled.
+
+### runDate
+
+The date that the job commenced.
+
+### executable
+
+The path to the executable program.
+
+### hostName
+
+The name of the host that the program was run on.
+
+### inputFile
+
+A cml module for a single literal representation of an input file.
+
+### inputFileList
+
+A cml module containing a list of input files.
+
+### inputFileName
+
+A representation of the name of a single input file.
+
+### numProc
+
+The number of processors used to run the job.
+
+### program
+
+The program being run. Known values:
+
+- `nwchem` — The Northwest Computational Chemistry Package (NWChem)
+- `gaussian` — The Gaussian electronic structure code
+
+### programVersion
+
+Specifies the version of the code that was used to run the calculation.
+
+### method
+
+The type of computational method. Example values: `SCF`, `DFT`, `MP2`.
+
+### task
+
+The task being carried out. Example values: `energy`, `frequency`,
+`geometry_optimization`, `gradient`, `initial_guess`, `iteration`, `step`.
+
+### id
+
+A CML id. Usable throughout cml documents. Need not be unique.
+
+### index
+
+An index. An integer used as an index.
+
+### iterationIndex
+
+The serial number of an iteration.
+
+### parameter
+
+(TODO)
+
+### property
+
+(TODO)
+
+### title
+
+An arbitrary title.
+
+### UUID
+
+A Universally Unique IDentifier as per RFC 4122.
+
+### cpuTime
+
+Elapsed CPU time.
+
+### wallTime
+
+Elapsed wallclock time.
+
+### charge
+
+The total charge on the system in elementary charge units.
+
+### atomType
+
+the type of the element (the atomic symbol).
+
+### numAtoms
+
+The number of atoms. Normally the count of atoms in a molecule.
+
+### numElectrons
+
+The total number of electrons in a system.
+
+### numAlphaElectrons
+
+The total number of alpha spin electrons.
+
+### numBetaElectrons
+
+The total number of beta spin electrons.
+
+### numClosedShells
+
+The number of closed shells.
+
+### numOpenShells
+
+The number of open shells.
+
+### pointGroup
+
+The molecular point group in Schoenflies notation.
+
+### spinMultiplicity
+
+The spin multiplicity = (alpha electrons) - (beta electrons) + 1.
+
+### wavefunctionType
+
+The type of wavefunction. Acceptable values: `closed`, `open`,
+`restricted open`.
+
+### basisSet
+
+A cml list container for all information related to the basis set.
+
+The basis set is the set of functions from which the electron orbitals
+are constructed.
+
+### basisSetLabel
+
+The name of the basis set. Should be one of the names used within the
+EMSL Basis Set Exchange.
+
+### basisSetType
+
+The type of the basis set. Valid values: `orbital`, `dftorb`, `dftxfit`,
+`dftcfit`, `periodic`, `ecporb`, `spinorb`, `polarization`, `diffuse`,
+`tight`, `rydberg`.
+
+### basisSetHarmonicType
+
+The type of the angular functions. Valid values: `cartesian`, `spherical`.
+
+### basisSetContractionType
+
+How the gaussian functions are contracted. Valid values: `segmented`,
+`general`, `uncontracted`.
+
+### basisSetDescription
+
+A description of the basis set.
+
+### basisSetContractions
+
+The cml:list container for the contractions relating to a particular
+atom type.
+
+### basisSetShell
+
+The label for the contraction shell. Valid values: `S`, `P`, `SP`, `D`,
+`F`, `G`, `H`, `I`, `K`, `L`, `M`.
+
+### basisSetContraction
+
+The cml:list container for an individual contraction.
+
+### basisSetExponent
+
+A cml:array holding the list of exponents for an individual contraction.
+
+### basisSetRExponent
+
+A cml:array holding the list of R exponents for an individual ECP
+contraction.
+
+### basisSetCoefficient
+
+A cml:array holding the list of coefficients for an individual contraction.
+
+### numElectronsReplaced
+
+The number of electrons replaced by an Effective Core Potential (ECP).
+
+### orbital
+
+A cml list container for all information related to an Orbital.
+
+### dftFunctional
+
+A cml list container for all information related to a DFT Functional.
+
+### dftFunctionalLabel
+
+The name of the DFT functional used, if a standard functional was used.
+
+### coulombEnergy
+
+The Coulomb component of the electronic energy in a Density Functional
+Calculation.
+
+### correlationEnergy
+
+The Correlation Energy.
+
+### e1Energy
+
+The one-electron energy. The one-electron kinetic energy component of
+the Hamiltonian operator.
+
+### e2Energy
+
+The two-electron energy.
+
+### nuclearRepulsionEnergy
+
+The potential energy arising from Coulombic nuclei-nuclei repulsions.
+
+### scfEnergy
+
+The Hartree-Fock Self-Consistent Field component of the energy.
+
+### totalEnergy
+
+The total energy for a system of electrons and nuclei. Formed from the
+sum of the nuclear, one- and two-electron energies.
+
+### xcEnergy
+
+The Exchange correlation energy.

data/reference-docs/dictionaries/index.md

@@ -0,0 +1,52 @@
+<!-- Source: http://www.xml-cml.org/dictionary/ -->
+<!-- License: CC-BY-3.0 (http://creativecommons.org/licenses/by/3.0/) -->
+
+# CML Dictionaries
+
+Dictionaries allow CML to be *understood* by machines. Much of physical
+science is managed through the dictionary mechanism. We find terms and
+units relating to an aspect of science (such as heat of formation,
+melting point, point group) and create entries for these items in a
+dictionary.
+
+The entries can consist of just a unique id (within the dictionary's
+namespace) and some human-understandable definition, but we strongly
+encourage more information: units, upper/lower bounds, data type.
+
+Different programs sometimes produce data with the same label but a
+different interpretation; does `density` mean electron density or
+physical density? Each computational chemistry code has its own
+dictionary; the community can then group concepts into a higher-level
+common dictionary (the compchem dictionary).
+
+## Implemented Dictionaries
+
+### Common Concepts
+
+- **Fundamental Chemistry Concepts** — namespace:
+  `http://www.xml-cml.org/dictionary/cml/`
+- **Chemical Naming Conventions** — namespace:
+  `http://www.xml-cml.org/dictionary/cml/name/`
+- **Chemical Formula Conventions** — namespace:
+  `http://www.xml-cml.org/dictionary/cml/formula/`
+
+### Crystallography
+
+- **CIF Core Definitions** — namespace:
+  `http://www.xml-cml.org/dictionary/cif/`
+
+### Computational Chemistry
+
+- **Computational Chemistry — Core Concepts** — namespace:
+  `http://www.xml-cml.org/dictionary/compchem/`
+
+## Unit Dictionaries
+
+### Units
+
+- **SI Units** — namespace: `http://www.xml-cml.org/unit/si/`
+- **Non-SI Units** — namespace: `http://www.xml-cml.org/unit/nonSi/`
+
+### Unit Types
+
+- **Unit Types** — namespace: `http://www.xml-cml.org/unit/unitType/`

data/reference-docs/examples/schema24-index.md

@@ -0,0 +1,50 @@
+<!-- Source: http://www.xml-cml.org/examples/schema24/ -->
+<!-- License: CC-BY-3.0 (http://creativecommons.org/licenses/by/3.0/) -->
+
+# Schema 2.4 Examples
+
+We have attempted to provide at least one example for each element.
+(There are also some examples for many of the attributes and types.)
+The examples show minimal examples of how each element can be used and
+so are a guide to its semantics. By convention an element `foo` will
+have an example `foo1.cml`. There may be further examples (`foo2.cml`
+etc.) which are often more complex.
+
+## Example index
+
+action1, action2, actionList1, alternative1, alternativeType1, amount1,
+angle1, annotation1, appinfo1, arg1, arg2, array1, array2, array3,
+atom1, atom2, atomArray1, atomArray2, atomicBasisFunction1,
+atomIDType1, atomParity1, atomRefArrayType1, atomRefs21, atomRefs31,
+atomRefs41, atomRefType1, atomSet1, atomTest, atomType1, atomTypeList1,
+band1, basisSet1, basisSet2, basisSet3, bond1, bond2, bond3, bond4,
+bondArray1, bondRefArrayType1, bondSet1, bondStereo1, bondType1,
+bondTypeList1, box31, cml2, cmlone, complexObject1, conditionList1,
+coordinateComponentArrayType1, coordinateComponentArrayType2, countType1,
+crystal1, crystal2, dataTypeType1, definition1, delimiterType1,
+description1, dictionary1, dictionary2, dictRefGroup1, dictRefGroup2,
+dimension1, dimension2, documentation1, eigen1, eigen2, electron1,
+electron2, elementTypeArrayType1, elementTypeType1, entry1, enumeration1,
+expression1, formalChargeType1, formula1, formula2, formula3,
+formulaType1, gradient1, ichi, idArrayType1, identifier1, identifier2,
+isotope1, isotope2, isotope3, isotope4, isotopeList1, join1, kpoint1,
+label1, lattice3, latticeVector1, latticeVector2, length1, line31,
+list1, matrix1, maxType1, mechanism1, mechanismComponent1, metadata1,
+module1, molecule1, moleculeTable1, name1, namespaceRefType1,
+nonNegativeAngleType, object1, observation1, parameter1, parameterList1,
+particleRefType1, peak1, peak2, peakGroup1, peakList1, peakStructure1,
+peakStructure1Schema, peakStructure2, peakStructure2Schema, plane31,
+point31, positiveAngleType, potential1, potentialForm1, potentialList1,
+productList1, property1, propertyList1, reactant1, reactantList1,
+reaction1, reaction10a, reaction10b, reaction11, reaction5, reaction6,
+reaction7, reaction9a, reaction9b, reactionList1, reactionList2,
+reactionScheme1, reactionScheme3, reactionScheme4a, reactionScheme4b,
+reactionStepList1, reactionStepList2, reactionStepList3,
+reactionStepList4, reactionStepList5a, reactiveCentre1, refGroup1,
+region1, region2, sample1, scalar1, space1, spectator1, spectatorList1,
+spectrum1, spectrum2-local, spectrum2, spectrum3, spectrum4, spectrum5,
+spectrumData1, spectrumList1, sphere31, spin1, stateType1, stmml1,
+substance1, substanceList1, substanceList2, symmetry1, symmetry2,
+system1, table1, table4, table5, table6, table7, title1, torsion1,
+transitionState1, unitList1, unitType1, unitType2, vector31, xaxis,
+xaxis1, yaxis, yaxis1, zMatrix1.

data/reference-docs/examples/schema3-compchem-index.md

@@ -0,0 +1,14 @@
+<!-- Source: http://www.xml-cml.org/examples/schema3/compchem/ -->
+<!-- License: CC-BY-3.0 (http://creativecommons.org/licenses/by/3.0/) -->
+
+# Schema 3 CompChem Examples
+
+The CML files here were generated by the Jumbo Converters from the
+NWChem log files linked below. The Jumbo NWChem converters are currently
+the reference for generating Convention-Compliant CML.
+
+| Title | CML | NWChem Logfile |
+| --- | --- | --- |
+| DFT B3LYP calculation on CH2 with 3-21g basis | `ch2_321g_b3lyp.cml` | `ch2_321g_b3lyp.nwo` |
+| HF SCF optimisation on water with STO-3G basis | `h2o_sto3g_opt.cml` | `h2o_sto3g_opt.nwo` |
+| Two jobs: DFT and MP2 calculations on water with different basis sets | `two_jobs.cml` | `two_jobs.nwo` |

data/reference-docs/examples/schema3-molecular-index.md

@@ -0,0 +1,28 @@
+<!-- Source: http://www.xml-cml.org/examples/schema3/molecular/ -->
+<!-- License: CC-BY-3.0 (http://creativecommons.org/licenses/by/3.0/) -->
+
+# Schema 3 Molecular Examples
+
+The following examples are all valid under the molecular convention. The
+files have been used to unit-test the validation service and should
+therefore give a fairly full example of each element.
+
+## Example index
+
+- atom with non cml content
+- atoms in formula do not need id
+- bond order other should have dictRef
+- bondStereo atomRefs2 must match parent bonds 1, 2
+- bondStereo atomRefs4 must contain parent bonds 1–8
+- bondStereo other should have dictRef
+- formula must have atomArray or concise or inline 1–7
+- minimal molecule 1–4
+- minimal molecule with foreign sibling
+- minimal molecule with non cml content 1–3
+- molecular convention molecule with non molecular sibling 1, 2
+- molecular convention not as root element
+- molecular molecule within non molecular
+- must be at least one molecule in molecular convention 1, 2
+- property must have dictRef and title
+- repeated atom ids in different molecules
+- scalar must have units and datatype and be child of property