qcsk: description string and formatting changes to models

qcelemental/models/basis.py

@@ -12,18 +12,14 @@ class NonnegativeInt(ConstrainedInt):
 
 
 class HarmonicType(str, Enum):
-    """
-    The angular momentum representation of a shell.
-    """
+    """The angular momentum representation of a shell."""
 
     spherical = "spherical"
     cartesian = "cartesian"
 
 
 class ElectronShell(ProtoModel):
-    """
-    Information for a single electronic shell
-    """
+    """Information for a single electronic shell."""
 
     angular_momentum: List[NonnegativeInt] = Field(
         ..., description="Angular momentum for the shell as an array of integers.", min_items=1
@@ -89,18 +85,14 @@ def is_contracted(self) -> bool:
 
 
 class ECPType(str, Enum):
-    """
-    The type of the ECP potential.
-    """
+    """The type of the ECP potential."""
 
     scalar = "scalar"
     spinorbit = "spinorbit"
 
 
 class ECPPotential(ProtoModel):
-    """
-    Information for a single ECP potential.
-    """
+    """Information for a single ECP potential."""
 
     ecp_type: ECPType = Field(..., description=str(ECPType.__doc__))
     angular_momentum: List[NonnegativeInt] = Field(
@@ -140,9 +132,7 @@ def _check_coefficient_length(cls, v, values):
 
 
 class BasisCenter(ProtoModel):
-    """
-    Data for a single atom/center in a basis set.
-    """
+    """Data for a single atom/center in a basis set."""
 
     electron_shells: List[ElectronShell] = Field(..., description="Electronic shells for this center.", min_items=1)
     ecp_electrons: int = Field(0, description="Number of electrons replaced by ECP, MCP, or other field potentials.")
@@ -169,14 +159,16 @@ class BasisSet(ProtoModel):
         1, description="The version number of ``schema_name`` to which this model conforms."
     )
 
-    name: str = Field(..., description="A standard basis name if available (e.g., 'cc-pVDZ').")
-    description: Optional[str] = Field(None, description="A brief description of the basis set.")
-    center_data: Dict[str, BasisCenter] = Field(..., description="A mapping of all types of centers available.")
+    name: str = Field(..., description="The standard basis name if available (e.g., 'cc-pVDZ').")
+    description: Optional[str] = Field(None, description="Brief description of the basis set.")
+    center_data: Dict[str, BasisCenter] = Field(
+        ..., description="Shared basis data for all atoms/centers in the parent molecule"
+    )
     atom_map: List[str] = Field(
-        ..., description="Mapping of all centers in the parent molecule to centers in `center_data`."
+        ..., description="Mapping of all atoms/centers in the parent molecule to centers in ``center_data``."
     )
 
-    nbf: Optional[int] = Field(None, description="The number of basis functions.")
+    nbf: Optional[int] = Field(None, description="The number of basis functions. Use for convenience or as checksum")
 
     class Config(ProtoModel.Config):
         def schema_extra(schema, model):

qcelemental/models/common_models.py

@@ -16,12 +16,10 @@
 
 
 class Provenance(ProtoModel):
-    """
-    Provenance information.
-    """
+    """Provenance information."""
 
-    creator: str = Field(..., description="The creator of the object.")
 
+    creator: str = Field(..., description="The name of the program, library, or person who created the object.")
     version: str = Field(
         "",
         description="The version of the creator, blank otherwise. This should be sortable by the very broad [PEP 440](https://www.python.org/dev/peps/pep-0440/).",
@@ -37,17 +35,17 @@ def schema_extra(schema, model):
 
 
 class Model(ProtoModel):
-    """
-    The quantum chemistry model specification for a given operation to compute against
-    """
+    """The computational molecular sciences model to run."""
 
     method: str = Field(  # type: ignore
-        ..., description="The quantum chemistry method to evaluate (e.g., B3LYP, PBE, ...)."
+        ...,
+        description="The quantum chemistry method to evaluate (e.g., B3LYP, PBE, ...). "
+        "For MM, name of the force field.",
     )
     basis: Optional[Union[str, BasisSet]] = Field(  # type: ignore
         None,
         description="The quantum chemistry basis set to evaluate (e.g., 6-31g, cc-pVDZ, ...). Can be ``None`` for "
-        "methods without basis sets.",
+        "methods without basis sets. For molecular mechanics, name of the atom-typer.",
     )
 
     # basis_spec: BasisSpec = None  # This should be exclusive with basis, but for now will be omitted
@@ -58,7 +56,7 @@ class Config(ProtoModel.Config):
 
 
 class DriverEnum(str, Enum):
-    """Allowed quantum chemistry driver values."""
+    """Allowed computation driver values."""
 
     energy = "energy"
     gradient = "gradient"
@@ -74,19 +72,20 @@ def derivative_int(self):
 
 
 class ComputeError(ProtoModel):
-    """A complete description of the error."""
+    """Complete description of the error from an unsuccessful program execution."""
 
     error_type: str = Field(  # type: ignore
         ...,  # Error enumeration not yet strict
-        description="The type of error which was thrown. Restrict this field short classifiers e.g. 'input_error'.",
+        description="The type of error which was thrown. Restrict this field to short classifiers e.g. 'input_error'. Suggested classifiers: https://github.com/MolSSI/QCEngine/blob/master/qcengine/exceptions.py",
     )
     error_message: str = Field(  # type: ignore
         ...,
-        description="Text associated with the thrown error, often the backtrace, but can contain additional "
+        description="Text associated with the thrown error. This is often the backtrace, but it can contain additional "
         "information as well.",
     )
     extras: Optional[Dict[str, Any]] = Field(  # type: ignore
-        None, description="Additional data to ship with the ComputeError object."
+        None,
+        description="Additional information to bundle with the error.",
     )
 
     class Config:
@@ -97,11 +96,7 @@ def __repr_args__(self) -> "ReprArgs":
 
 
 class FailedOperation(ProtoModel):
-    """
-    A record indicating that a given operation (compute, procedure, etc.) has failed and contains the reason and
-    input data which generated the failure.
-
-    """
+    """Record indicating that a given operation (program, procedure, etc.) has failed and containing the reason and input data which generated the failure."""
 
     id: str = Field(  # type: ignore
         None,
@@ -127,7 +122,7 @@ class FailedOperation(ProtoModel):
     )
     extras: Optional[Dict[str, Any]] = Field(  # type: ignore
         None,
-        description="Additional information to bundle with this Failed Operation. Details which pertain specifically "
+        description="Additional information to bundle with the failed operation. Details which pertain specifically "
         "to a thrown error should be contained in the `error` field. See :class:`ComputeError` for details.",
     )