Merge pull request #17 from dgasmith/obligations

Code compliance and FAQ

ComplianceLevels.md

@@ -0,0 +1,20 @@
+# Compliance Levels
+
+The specificiation has various levels of compliance so that partner codes can
+implement various levels of specification based on their requirements and
+desired support.  
+
+## Tier 1
+- A) Verifies the JSON input
+- B) Can perform energy, optimization, and frequency computations and record output 
+
+## Tier 2 
+- C) Can obtain energy/gradient/Hessian quantities
+- D) Records all miscellaneous quantities into the Variables field without
+    requiring specific nomenclature for intra-program consistency (one-electron
+    energy, two-electron energy, KS energy, ...) 
+- E) Exports Wavefunction quantities (orbitals, eigenvalues, densities, ...)
+
+## Tier 3
+- F) Converts AO quantities to a common ordered and normalized representation
+- G) Uses a standard dictionary of Variables as output

FAQ.md

@@ -0,0 +1,30 @@
+# Frequently Asked Questions
+
+### Will the json be validated before it reaches my software?
+Since we are electing to use JSON the schema will not automatically be
+validated; however, MolSSI will sponsor software to validate the schema in a
+variety of languages.  Likely through [these
+implementations](http://json-schema.org/implementations.html).
+
+### Does the schema accept arbitrary extra fields if my software piece needs internal extensions?
+Yes, we are currently discussing which fields are reserved and where the best
+place for arbitrary fields would be.
+
+### Are there libraries for writing the schema in [programming-language]?
+JSON is agnostic to the underlying programming language and is well supported
+in a variety of languages (C++/Python/JS/etc). We will provide examples on how
+to write JSON in other languages where JSON is not as well supported (Fortran).
+
+### Why not use XML?
+The ability to hand write and tweak a given input has been a sought after
+property. In addition, the overall structure of JSON is viewed as simpler and
+more intuitive than XML. As the schema is fully specified it should be possible
+for the validator to take in a JSON input and return an XML output.
+
+### What style will be used for indexing and case?
+We will support zero-indexing and camelCase in the JavaScript notation.
+Discussion is underway if we will follow the full [Google JSON Style
+Guide](https://google.github.io/styleguide/jsoncstyleguide.xml).
+
+### Will the schema be versioned?
+Yes, the schema will have version flags so that it can evolve over time.

topology/bagel_json.json

@@ -1,3 +1,4 @@
+{
 "geometry" : [
   {"atom" :"C", "xyz" : [ -1.20433891360,  0.54285096106, -0.04748199659] },
   {"atom" :"C", "xyz" : [ -1.20543291352, -0.83826393986,  0.12432899108] },
@@ -12,3 +13,4 @@
   {"atom" :"H", "xyz" : [  2.13410684690,  1.07591292282, -0.12500599103] },
   {"atom" :"H", "xyz" : [ -0.00000000000,  2.29608983528, -0.28688797942] }
 ]
+}

topology/bagel_json2.json

@@ -1,7 +1,9 @@
+{
 "geometry" : [
   { "atom" : "Cu",  "xyz" : [  0.000000,      0.000000,      0.000000]},
   { "atom" :  "H",  "xyz" : [  0.000000,      0.000000,     -1.560000],
                    "basis" : "cc-pvtz"},
   { "atom" :  "H",  "xyz" : [  0.000000,      0.000000,      1.560000],
                    "basis" : "cc-pvtz"}
 ]
+}

topology/nwchem_json.json

@@ -1,3 +1,4 @@
+{
 "molecule": {
   "atoms": [
     {
@@ -48,3 +49,4 @@
     "groupname": "C1"
   }
 }
+}