clarify frag ordering, req'd prov fields, user guidance (#57)

* require all three provenance fields * Update molecule.py * Update molecule.py
MolSSI · Dec 14, 2018 · e435f43 · e435f43
1 parent c68f112
commit e435f43
Show file tree

Hide file tree

Showing 2 changed files with 28 additions and 10 deletions.
diff --git a/qcschema/dev/definitions.py b/qcschema/dev/definitions.py
@@ -27,15 +27,15 @@
             "type": "string"
         },
         "version": {
-            "description": "The version of the program which created this object, blank otherwise.",
+            "description": "The version of the program which created this object, blank otherwise. Suggest that versions be interpretable by PEP 440 (https://www.python.org/dev/peps/pep-0440/).",
             "type": "string"
         },
         "routine": {
             "description": "The routine of the program which created this object, blank otherwise.",
             "type": "string"
         }
     },
-    "required": ["creator"],
+    "required": ["creator", "version", "routine"],
     "description": "A short provenance of the object.",
     "additionalProperties": True
 }

diff --git a/qcschema/dev/molecule.py b/qcschema/dev/molecule.py
@@ -16,7 +16,8 @@
             }
         },
         "geometry": {
-            "description": "(3 * nat, ) vector of XYZ coordinates of the atoms.",
+            "description": "(3 * nat, ) vector of XYZ coordinates [a0] of the atoms.",
+            "guidance": "Atom ordering is fixed; that is, a consumer who shuffles atoms must not reattach the input (pre-shuffling) molecule schema instance to any output (post-shuffling) per-atom results (e.g., gradient).",
             "type": "array",
             "items": {
                 "type": "number"
@@ -30,7 +31,7 @@
             }
         },
         "atomic_numbers": {
-            "description": "(nat, ) atomic numbers, nuclear charge for atoms.",
+            "description": "(nat, ) atomic numbers, nuclear charge for atoms. Ghostedness should be indicated through 'real' field, not zeros here.",
             "type": "array",
             "items": {
                 "type": "number",
@@ -80,21 +81,36 @@
         },
         "connectivity": {
             "description": "A list describing bonds within a molecule. Each element is a (atom1, atom2, order) tuple.",
+            "guidance": "Bonds may be freely reordered and inverted.",
             "type": "array",
             "items": {
                 "type": "array",
                 "minItems": 3,
                 "maxItems": 3,
-                "items": {
-                    "type": "number",
-                    "minimum": 0,
-                    "maximum": 5,
-                }
+                "items": [
+                    {
+                        "description": "Atom number (0-indexed) at one end of bond.",
+                        "type": "number",
+                        "multipleOf": 1.0
+                    },
+                    {
+                        "description": "Atom number (0-indexed) at other end of bond.",
+                        "type": "number",
+                        "multipleOf": 1.0
+                    },
+                    {
+                        "description": "Bond order.",
+                        "type": "number",
+                        "minimum": 0,
+                        "maximum": 5,
+                    }
+                ]
             }
         },
         "fragments": {
             "description":
-            "(nfr, -1) list of indices (0-indexed) grouping atoms into molecular fragments within the topology.",
+            "(nfr, <varies>) list of indices (0-indexed) grouping atoms into molecular fragments within the topology.",
+            "guidance": "Fragment ordering is fixed; that is, a consumer who shuffles fragments must not reattach the input (pre-shuffling) molecule schema instance to any output (post-shuffling) per-fragment results (e.g., n-body energy arrays).",
             "type": "array",
             "items": {
                 "type": "array",
@@ -121,11 +137,13 @@
         },
         "fix_com": {
             "description": "Whether translation of geometry is allowed (fix F) or disallowed (fix T).",
+            "guidance": "A consumer who translates the geometry must not reattach the input (pre-translation) molecule schema instance to any output (post-translation) origin-sensitive results (e.g., an ordinary energy when EFP present).",
             "type": "boolean",
             "default": False
         },
         "fix_orientation": {
             "description": "Whether rotation of geometry is allowed (fix F) or disallowed (fix T).",
+            "guidance": "A consumer who rotates the geometry must not reattach the input (pre-rotation) molecule schema instance to any output (post-rotation) frame-sensitive results (e.g., molecular vibrations).",
             "type": "boolean",
             "default": False
         },