Improve docstrings for design execution and candidate classes

src/citrine/informatics/design_candidate.py

@@ -21,6 +21,8 @@
 
 
 class DesignCandidateComment(Serializable["DesignCandidateComment"]):
+    """A user comment attached to a design candidate."""
+
     message = properties.String('message')
     """:str: the text of the comment"""
     created_by = properties.UUID('created.user')
@@ -30,10 +32,18 @@ class DesignCandidateComment(Serializable["DesignCandidateComment"]):
 
 
 class DesignVariable(PolymorphicSerializable["DesignVariable"]):
-    """Classes containing data corresponding to individual descriptors.
+    """A predicted or specified value for a single material descriptor.
+
+    Materials are represented as (descriptor, value) pairs. Each
+    DesignVariable holds one value. The concrete subtype depends
+    on the descriptor type:
+
+    * :class:`MeanAndStd` — continuous (real-valued) descriptors
+    * :class:`TopCategories` — categorical descriptors
+    * :class:`Mixture` — formulation descriptors
+    * :class:`ChemicalFormula` — chemical formula descriptors
+    * :class:`MolecularStructure` — SMILES-based descriptors
 
-    If you think of materials as being represented as a set of (descriptor, value) pairs,
-    these are simplified representations of the values.
     """
 
     def __init__(self, arg):
@@ -170,9 +180,14 @@ class HierarchicalDesignMaterial(Serializable["HierarchicalDesignMaterial"]):
 
 
 class DesignCandidate(Serializable["DesignCandidate"]):
-    """A candidate material generated by the Citrine Platform.
+    """A candidate material generated by a design execution.
+
+    Each candidate contains predicted property values and a
+    ``primary_score`` indicating how well it satisfies the
+    objectives and constraints (higher is better). Retrieve
+    candidates via
+    :meth:`~citrine.informatics.executions.design_execution.DesignExecution.candidates`.
 
-    This class represents the candidate computed by a design execution.
     """
 
     uid = properties.UUID('id')
@@ -199,9 +214,13 @@ class DesignCandidate(Serializable["DesignCandidate"]):
 
 
 class HierarchicalDesignCandidate(Serializable["HierarchicalDesignCandidate"]):
-    """A hierarchical candidate material generated by the Citrine Platform.
+    """A design candidate with full material history.
+
+    Like :class:`DesignCandidate`, but the material includes
+    the hierarchical structure (process history, ingredients,
+    sub-materials). Retrieve via
+    :meth:`~citrine.informatics.executions.design_execution.DesignExecution.hierarchical_candidates`.
 
-    This class represents the candidate computed by a design execution.
     """
 
     uid = properties.UUID('id')

src/citrine/informatics/executions/design_execution.py

@@ -13,10 +13,16 @@
 
 
 class DesignExecution(Resource["DesignExecution"], Execution):
-    """The execution of a DesignWorkflow.
+    """A single run of a design workflow that generates candidates.
 
-    Possible statuses are INPROGRESS, SUCCEEDED, and FAILED.
-    Design executions also have a ``status_description`` field with more information.
+    A DesignExecution is created by triggering a
+    :class:`~citrine.resources.design_workflow.DesignWorkflow`
+    with a :class:`~citrine.informatics.scores.Score`. Once
+    the execution status reaches ``SUCCEEDED``, use
+    :meth:`candidates` to retrieve the generated candidates
+    ranked by score.
+
+    Possible statuses: ``INPROGRESS``, ``SUCCEEDED``, ``FAILED``.
 
     """
 
@@ -47,7 +53,23 @@ def _build_candidates(cls, subset_collection: Iterable[dict]) -> Iterable[Design
             yield DesignCandidate.build(candidate)
 
     def candidates(self, *, per_page: int = 100) -> Iterable[DesignCandidate]:
-        """Fetch the Design Candidates for the particular execution, paginated."""
+        """Fetch the design candidates generated by this execution.
+
+        Returns an iterator of candidates ranked by score
+        (highest first). Each candidate contains predicted
+        material property values and a ``primary_score``.
+
+        Parameters
+        ----------
+        per_page : int, optional
+            Number of candidates per page. Default: 100.
+
+        Returns
+        -------
+        Iterable[DesignCandidate]
+            Paginated iterator over design candidates.
+
+        """
         path = self._path() + '/candidates'
 
         fetcher = partial(self._fetch_page, path=path, fetch_func=self._session.get_resource)
@@ -63,7 +85,24 @@ def _build_hierarchical_candidates(
             yield HierarchicalDesignCandidate.build(candidate)
 
     def hierarchical_candidates(self, *, per_page: int = 100) -> Iterable[DesignCandidate]:
-        """Fetch the Design Candidates for the particular execution, paginated."""
+        """Fetch candidates with full material history.
+
+        Like :meth:`candidates`, but each candidate includes
+        the hierarchical material structure (process history,
+        ingredients, sub-materials) rather than a flat
+        representation.
+
+        Parameters
+        ----------
+        per_page : int, optional
+            Number of candidates per page. Default: 100.
+
+        Returns
+        -------
+        Iterable[HierarchicalDesignCandidate]
+            Paginated iterator over hierarchical candidates.
+
+        """
         path = self._path() + '/candidate-histories'
 
         fetcher = partial(self._fetch_page, path=path, fetch_func=self._session.get_resource)
@@ -74,7 +113,23 @@ def hierarchical_candidates(self, *, per_page: int = 100) -> Iterable[DesignCand
 
     def predict(self,
                 predict_request: PredictRequest) -> DesignCandidate:
-        """Invoke a prediction on a design candidate."""
+        """Run a prediction for a specific material configuration.
+
+        Uses the predictor from this execution's workflow to
+        generate predicted property values for the material
+        described in the request.
+
+        Parameters
+        ----------
+        predict_request : PredictRequest
+            The material configuration to predict on.
+
+        Returns
+        -------
+        DesignCandidate
+            A candidate with predicted property values.
+
+        """
         path = self._path() + '/predict'
 
         res = self._session.post_resource(path, predict_request.dump(), version=self._api_version)

src/citrine/informatics/predict_request.py

@@ -7,9 +7,29 @@
 
 
 class PredictRequest(Serializable["PredictRequest"]):
-    """A Citrine Predict Request.
+    """A request to predict properties for a specific material.
+
+    Typically constructed from an existing design candidate to
+    re-predict with modified inputs, or to run a what-if
+    analysis on a specific material configuration.
+
+    Parameters
+    ----------
+    material_id : UUID
+        Unique identifier of the material to predict on.
+    identifiers : list[str]
+        List of identifier strings for this material (e.g.
+        sample IDs, lot numbers).
+    material : DesignMaterial
+        The material definition containing descriptor values
+        to use as predictor inputs.
+    created_from_id : UUID
+        The UID of the design candidate this request was
+        derived from.
+    random_seed : int, optional
+        Seed for reproducible stochastic predictions. If
+        omitted, the platform chooses a random seed.
 
-    This class represents the candidate computed by a design execution.
     """
 
     material_id = properties.UUID('material_id')