Skip to content

Design Runs (🧪Beta)

albert.resources.design_runs

DesignRunState

Bases: StrEnum

Lifecycle of a design run. Orthogonal to its soft-delete status.

Attributes:

Name Type Description
QUEUED
RUNNING
COMPLETE
ERROR

QUEUED

QUEUED = 'queued'

RUNNING

RUNNING = 'running'

COMPLETE

COMPLETE = 'complete'

ERROR

ERROR = 'error'

DesignRunStage

Bases: StrEnum

Detail on what a running run is doing.

Attributes:

Name Type Description
BUILDING_MODELS
GENERATING_CANDIDATES
SAMPLING

BUILDING_MODELS

BUILDING_MODELS = 'building_models'

GENERATING_CANDIDATES

GENERATING_CANDIDATES = 'generating_candidates'

SAMPLING

SAMPLING = 'sampling'

DesignRunSettings

Bases: BaseAlbertModel

The sizing a design run was triggered with.

Show JSON schema:
{
  "description": "The sizing a design run was triggered with.",
  "properties": {
    "numCandidatesGenerated": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Candidates generated before selection (optimization) or the most sampled before\ndownsampling (space-filling).",
      "title": "Numcandidatesgenerated"
    },
    "numCandidatesSelected": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Candidates kept (at most ``100``).",
      "title": "Numcandidatesselected"
    }
  },
  "title": "DesignRunSettings",
  "type": "object"
}

Fields:

num_candidates_generated

num_candidates_generated: int | None = None

Candidates generated before selection (optimization) or the most sampled before downsampling (space-filling).

num_candidates_selected

num_candidates_selected: int | None = None

Candidates kept (at most 100).

DesignRun

Bases: BaseResource

A stored design run and its status.

Once state is complete, result_set_id names the candidate set holding its candidates; read it with DesignCandidateSetCollection.

Show JSON schema:
{
  "$defs": {
    "AuditFields": {
      "description": "The audit fields for a resource",
      "properties": {
        "by": {
          "default": null,
          "title": "By",
          "type": "string"
        },
        "byName": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Byname"
        },
        "at": {
          "anyOf": [
            {
              "format": "date-time",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "At"
        }
      },
      "title": "AuditFields",
      "type": "object"
    },
    "ComparisonOperator": {
      "description": "How a measured value is compared against a target value.\n\nAttributes\n----------\nEQ : str\n    Equal to the target value.\nGT : str\n    Strictly greater than the target value.\nGTE : str\n    Greater than or equal to the target value.\nLT : str\n    Strictly less than the target value.\nLTE : str\n    Less than or equal to the target value.\nBETWEEN : str\n    Within an inclusive range; pairs with a [`NumericRange`][albert.resources.targets.NumericRange] value.\nIN_SET : str\n    Among a set of allowed values; pairs with a list value.",
      "enum": [
        "eq",
        "gt",
        "gte",
        "lt",
        "lte",
        "between",
        "in-set"
      ],
      "title": "ComparisonOperator",
      "type": "string"
    },
    "DesignMethod": {
      "description": "Wire ``method`` value for a design-run request.",
      "enum": [
        "generate",
        "space_filling"
      ],
      "title": "DesignMethod",
      "type": "string"
    },
    "DesignObjective": {
      "description": "A per-run optimization goal: a success criterion plus how much it matters.\n\nA [`Criterion`][albert.resources.targets.Criterion] states what good looks like.\n``weight`` states how much that goal counts relative to the other objectives on the\nsame run, and belongs to the run rather than to the Target. A Target carries no\npriority of its own, so the same targets can be reweighted from one run to the next\nto see how the trade-off moves the candidates.\n\nA plain ``Criterion`` is accepted anywhere a ``DesignObjective`` is expected and\ntakes the default weight.\n\n!!! example\n    ```python\n    from albert.resources.design import DesignObjective\n\n    # a hard specification that should not be traded away\n    DesignObjective(operator=\"gte\", value=95, weight=3.0)\n\n    # the same goal at the default weight\n    DesignObjective(operator=\"gte\", value=95)\n    ```",
      "properties": {
        "operator": {
          "$ref": "#/$defs/ComparisonOperator",
          "description": "How the measured value is compared against ``value``."
        },
        "value": {
          "anyOf": [
            {
              "$ref": "#/$defs/NumericRange"
            },
            {
              "type": "string"
            },
            {
              "type": "number"
            },
            {
              "items": {},
              "type": "array"
            }
          ],
          "description": "The value being compared against. Use a [`NumericRange`][albert.resources.targets.NumericRange] with the ``between`` operator, a list with the ``in-set`` operator, or a single number/string for the scalar operators.",
          "title": "Value"
        },
        "weight": {
          "default": 1.0,
          "description": "How much this objective counts relative to the others on the same run.\n\nCandidate scores are combined as a product of each objective's score raised to its\nweight, so a weight above ``1.0`` makes the objective harder to trade away and a\nweight below ``1.0`` makes it easier. Must be positive; to ignore an objective,\nleave it out.\n\nAlways a float, never ``None``: an unweighted objective is ``1.0``, which weighs it\nequally against the others. Omitting the field, or passing an explicit ``None``,\nboth give ``1.0``.",
          "exclusiveMinimum": 0,
          "title": "Weight",
          "type": "number"
        }
      },
      "required": [
        "operator",
        "value"
      ],
      "title": "DesignObjective",
      "type": "object"
    },
    "DesignRunSettings": {
      "description": "The sizing a design run was triggered with.",
      "properties": {
        "numCandidatesGenerated": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Candidates generated before selection (optimization) or the most sampled before\ndownsampling (space-filling).",
          "title": "Numcandidatesgenerated"
        },
        "numCandidatesSelected": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Candidates kept (at most ``100``).",
          "title": "Numcandidatesselected"
        }
      },
      "title": "DesignRunSettings",
      "type": "object"
    },
    "DesignRunStage": {
      "description": "Detail on what a ``running`` run is doing.",
      "enum": [
        "building_models",
        "generating_candidates",
        "sampling"
      ],
      "title": "DesignRunStage",
      "type": "string"
    },
    "DesignRunState": {
      "description": "Lifecycle of a design run. Orthogonal to its soft-delete ``status``.",
      "enum": [
        "queued",
        "running",
        "complete",
        "error"
      ],
      "title": "DesignRunState",
      "type": "string"
    },
    "DesignRunViolation": {
      "description": "A single validation failure for a design-run configuration.",
      "properties": {
        "code": {
          "anyOf": [
            {
              "$ref": "#/$defs/DesignRunViolationCode"
            },
            {
              "type": "string"
            }
          ],
          "description": "Machine-readable violation category. A code this version does not know yet is kept\nas a plain string.",
          "title": "Code"
        },
        "message": {
          "description": "Human-readable explanation of the failure.",
          "title": "Message",
          "type": "string"
        },
        "targetId": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Target id when the violation is scoped to one performance target.",
          "title": "Targetid"
        },
        "components": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "The entities (element ids, parameter keys or target ids) the violation points at.",
          "title": "Components"
        }
      },
      "required": [
        "code",
        "message"
      ],
      "title": "DesignRunViolation",
      "type": "object"
    },
    "DesignRunViolationCode": {
      "description": "Structured preflight failure codes returned by design-run validation.",
      "enum": [
        "invalid_settings",
        "dataset_not_ready",
        "objective_out_of_scope",
        "no_performance_targets",
        "invalid_objective",
        "insufficient_training_data",
        "infeasible_design_space",
        "model_training_error",
        "optimization_system_mismatch",
        "internal",
        "job_timeout",
        "result_persistence_failed",
        "estimator_downgraded",
        "unknown_reference",
        "reference_not_published",
        "unsupported_operand",
        "invalid_constraint",
        "feasibility_indeterminate",
        "dimension_not_in_dataset",
        "dimension_not_modelled",
        "duplicate_constraint_subject",
        "variable_not_derived",
        "target_not_in_dataset",
        "transform_requires_positive_target",
        "inert_mask_entry",
        "feature_dropped_by_overlap",
        "duplicate_extra",
        "conflicting_label_definition"
      ],
      "title": "DesignRunViolationCode",
      "type": "string"
    },
    "NumericRange": {
      "description": "An inclusive numeric range, used with the ``between`` operator.",
      "properties": {
        "min": {
          "description": "The lower bound of the range.",
          "title": "Min",
          "type": "number"
        },
        "max": {
          "description": "The upper bound of the range.",
          "title": "Max",
          "type": "number"
        }
      },
      "required": [
        "min",
        "max"
      ],
      "title": "NumericRange",
      "type": "object"
    },
    "Status": {
      "description": "The status of a resource.\n\nAttributes\n----------\nACTIVE : str\n    The resource is fully operational and visible in normal operations.\nINACTIVE : str\n    The resource is hidden from normal operations and disabled from use.",
      "enum": [
        "active",
        "inactive"
      ],
      "title": "Status",
      "type": "string"
    }
  },
  "description": "A stored design run and its status.\n\nOnce ``state`` is ``complete``, ``result_set_id`` names the candidate set holding\nits candidates; read it with\n[`DesignCandidateSetCollection`][albert.collections.design_candidate_sets.DesignCandidateSetCollection].",
  "properties": {
    "status": {
      "anyOf": [
        {
          "$ref": "#/$defs/Status"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The status of the resource, optional."
    },
    "created": {
      "anyOf": [
        {
          "$ref": "#/$defs/AuditFields"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Audit fields for the creation of the run."
    },
    "updated": {
      "anyOf": [
        {
          "$ref": "#/$defs/AuditFields"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Audit fields for the last update of the run."
    },
    "id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The unique identifier of the run (format ``DSR...``).",
      "title": "Id"
    },
    "schemaVersion": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The version of the run record layout.",
      "title": "Schemaversion"
    },
    "name": {
      "anyOf": [
        {
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Display name of the run.",
      "title": "Name"
    },
    "description": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Free-text description of the run.",
      "title": "Description"
    },
    "parentId": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The project (format ``PRO...``) that owns the run and controls access to it.",
      "title": "Parentid"
    },
    "method": {
      "anyOf": [
        {
          "$ref": "#/$defs/DesignMethod"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "How candidates are produced: ``generate`` or ``space_filling``."
    },
    "state": {
      "anyOf": [
        {
          "$ref": "#/$defs/DesignRunState"
        },
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Lifecycle state: ``queued``, ``running``, ``complete`` or ``error``. A state this\nversion does not know yet is kept as a plain string.",
      "title": "State"
    },
    "stage": {
      "anyOf": [
        {
          "$ref": "#/$defs/DesignRunStage"
        },
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "What the run is doing while ``running``. A stage this version does not know yet is\nkept as a plain string.",
      "title": "Stage"
    },
    "violations": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/DesignRunViolation"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Why the run failed. Populated when ``state`` is ``error``.",
      "title": "Violations"
    },
    "startedAt": {
      "anyOf": [
        {
          "format": "date-time",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "When the run started.",
      "title": "Startedat"
    },
    "endedAt": {
      "anyOf": [
        {
          "format": "date-time",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "When the run reached a terminal state.",
      "title": "Endedat"
    },
    "smartDatasetId": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The smart dataset (format ``SDT...``) the run was triggered against.",
      "title": "Smartdatasetid"
    },
    "designSpaceId": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The design space (format ``DSP...``) used. ``None`` for the dataset-derived default.",
      "title": "Designspaceid"
    },
    "designModelConfigId": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The design model config (format ``DMC...``) used. ``None`` for the dataset-derived default.",
      "title": "Designmodelconfigid"
    },
    "objectives": {
      "anyOf": [
        {
          "additionalProperties": {
            "$ref": "#/$defs/DesignObjective"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Per-target objectives, keyed by target ID. Optimization runs only.",
      "title": "Objectives"
    },
    "anchorTargets": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Target IDs that narrowed which experiments anchor a space-filling run.",
      "title": "Anchortargets"
    },
    "settings": {
      "anyOf": [
        {
          "$ref": "#/$defs/DesignRunSettings"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The sizing the run was triggered with."
    },
    "resultSetId": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The candidate set (format ``DCS...``) of the run's candidates. ``None`` until the run\nis ``complete``.",
      "title": "Resultsetid"
    },
    "version": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Version counter of the record.",
      "title": "Version"
    }
  },
  "title": "DesignRun",
  "type": "object"
}

Fields:

id

id: DesignRunId | None = None

The unique identifier of the run (format DSR...).

schema_version

schema_version: int | None = None

The version of the run record layout.

name

name: str | None = None

Display name of the run.

description

description: str | None = None

Free-text description of the run.

parent_id

parent_id: ProjectId | None = None

The project (format PRO...) that owns the run and controls access to it.

method

method: DesignMethod | None = None

How candidates are produced: generate or space_filling.

state

state: DesignRunState | str | None = None

Lifecycle state: queued, running, complete or error. A state this version does not know yet is kept as a plain string.

stage

stage: DesignRunStage | str | None = None

What the run is doing while running. A stage this version does not know yet is kept as a plain string.

violations

violations: list[DesignRunViolation] | None = None

Why the run failed. Populated when state is error.

started_at

started_at: datetime | None = None

When the run started.

ended_at

ended_at: datetime | None = None

When the run reached a terminal state.

smart_dataset_id

smart_dataset_id: SmartDatasetId | None = None

The smart dataset (format SDT...) the run was triggered against.

design_space_id

design_space_id: DesignSpaceId | None = None

The design space (format DSP...) used. None for the dataset-derived default.

design_model_config_id

design_model_config_id: DesignModelConfigId | None = None

The design model config (format DMC...) used. None for the dataset-derived default.

objectives

objectives: dict[TargetId, DesignObjective] | None = None

Per-target objectives, keyed by target ID. Optimization runs only.

anchor_targets

anchor_targets: list[TargetId] | None = None

Target IDs that narrowed which experiments anchor a space-filling run.

settings

settings: DesignRunSettings | None = None

The sizing the run was triggered with.

result_set_id

result_set_id: DesignCandidateSetId | None = None

The candidate set (format DCS...) of the run's candidates. None until the run is complete.

version

version: int | None = None

Version counter of the record.

created

created: AuditFields | None = None

Audit fields for the creation of the run.

updated

updated: AuditFields | None = None

Audit fields for the last update of the run.