From 60dcfaaccd77252219f1df9330715f03d168ed24 Mon Sep 17 00:00:00 2001 From: Gregory Mulholland Date: Wed, 25 Mar 2026 13:08:58 -0700 Subject: [PATCH] Improve docstrings for design execution and candidate classes - DesignExecution: explain the execution lifecycle and link to Score, candidates(), and hierarchical_candidates() - candidates(): document return ordering (by score), per_page, and return type with full Parameters/Returns sections - hierarchical_candidates(): explain the difference from candidates() (includes process history and sub-materials) - predict(): document PredictRequest input and DesignCandidate return with full Parameters/Returns sections - PredictRequest: add full Parameters section documenting all 5 constructor arguments - DesignCandidate: explain primary_score semantics - DesignVariable: list all subtypes and when each is used - DesignCandidateComment: add missing class docstring Co-Authored-By: Claude Opus 4.6 (1M context) --- src/citrine/informatics/design_candidate.py | 33 +++++++-- .../executions/design_execution.py | 67 +++++++++++++++++-- src/citrine/informatics/predict_request.py | 24 ++++++- 3 files changed, 109 insertions(+), 15 deletions(-) diff --git a/src/citrine/informatics/design_candidate.py b/src/citrine/informatics/design_candidate.py index 94fbcd275..10169d93d 100644 --- a/src/citrine/informatics/design_candidate.py +++ b/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') diff --git a/src/citrine/informatics/executions/design_execution.py b/src/citrine/informatics/executions/design_execution.py index 0511cd06f..9875acf0e 100644 --- a/src/citrine/informatics/executions/design_execution.py +++ b/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) diff --git a/src/citrine/informatics/predict_request.py b/src/citrine/informatics/predict_request.py index b2c2adab0..0c5f93762 100644 --- a/src/citrine/informatics/predict_request.py +++ b/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')