Design Runs (🧪Beta)
albert.resources.design_runs
DesignRunState
DesignRunStage
Bases: StrEnum
Detail on what a running run is doing.
Attributes:
| Name | Type | Description |
|---|---|---|
BUILDING_MODELS |
|
|
GENERATING_CANDIDATES |
|
|
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(int | None) -
num_candidates_selected(int | None)
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:
-
status(Status | None) -
id(DesignRunId | None) -
schema_version(int | None) -
name(str | None) -
description(str | None) -
parent_id(ProjectId | None) -
method(DesignMethod | None) -
state(DesignRunState | str | None) -
stage(DesignRunStage | str | None) -
violations(list[DesignRunViolation] | None) -
started_at(datetime | None) -
ended_at(datetime | None) -
smart_dataset_id(SmartDatasetId | None) -
design_space_id(DesignSpaceId | None) -
design_model_config_id(DesignModelConfigId | None) -
objectives(dict[TargetId, DesignObjective] | None) -
anchor_targets(list[TargetId] | None) -
settings(DesignRunSettings | None) -
result_set_id(DesignCandidateSetId | None) -
version(int | None) -
created(AuditFields | None) -
updated(AuditFields | None)
parent_id
parent_id: ProjectId | None = None
The project (format PRO...) that owns the run and controls access to it.
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.
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
Target IDs that narrowed which experiments anchor a space-filling run.
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.