Design Spaces (🧪Beta)
albert.collections.design_spaces.DesignSpaceCollection
Bases: BaseCollection
Manage Design Spaces in the Albert platform (🧪 Beta).
A design space is the bounded envelope (also called the search space) that a design run samples formulations from: which ingredients may or must appear, the fraction bounds on each, the allowed values of parameters, and how many ingredients one formulation may carry.
A space is created as a draft, edited with builder operations, checked for feasibility, and published. A published space is frozen; editing one means forking it into a new draft.
This collection is accessed as client.design_spaces.
Beta Feature!
Please do not use in production or without explicit guidance from Albert. You might otherwise have a bad experience. This feature currently falls outside of the Albert support contract, but we'd love your feedback!
Example
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
session
|
AlbertSession
|
The authenticated Albert session used for API calls. |
required |
Attributes:
| Name | Type | Description |
|---|---|---|
base_path |
str
|
The base API route for design-space requests. |
Methods:
| Name | Description |
|---|---|
create |
Create a draft design space, empty or seeded from a smart dataset. |
get_by_id |
Get a single design space by its ID. |
get_all |
Get all design spaces in a project. |
update |
Update the name or description of a draft design space. |
apply |
Apply builder operations to a draft design space. |
check_feasibility |
Check whether a design space can produce valid formulations. |
get_sample |
Get a sample of the formulations a design space would produce. |
publish |
Publish a draft design space, freezing it for use by design runs. |
fork |
Fork a published design space into a new editable draft. |
get_references |
Get what references a component of a design space. |
delete |
Delete a design space by its ID. |
Source code in src/albert/collections/design_spaces.py
create
create(
*,
name: str,
parent_id: ProjectId,
description: str | None = None,
smart_dataset_id: SmartDatasetId | None = None,
) -> DesignSpaceCreated
Create a draft design space.
A design space (also called an envelope or search space) bounds what a design run may propose: the ingredients and their fraction bounds, the allowed parameter values, and the ingredient-count bounds.
Pass smart_dataset_id to pre-populate the draft from a smart dataset's
observed dimensions; omit it to start empty and add dimensions with
apply.
Example
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Display name of the design space. |
required |
parent_id
|
ProjectId
|
The project (format |
required |
description
|
str
|
Free-text description of the space's intent. |
None
|
smart_dataset_id
|
SmartDatasetId
|
Smart dataset (format |
None
|
Returns:
| Type | Description |
|---|---|
DesignSpaceCreated
|
The created draft design space. Its |
Source code in src/albert/collections/design_spaces.py
get_by_id
get_by_id(*, id: DesignSpaceId) -> DesignSpace
Get a single design space by its ID.
Example
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
DesignSpaceId
|
The design space ID (format |
required |
Returns:
| Type | Description |
|---|---|
DesignSpace
|
The fully populated design space. |
Source code in src/albert/collections/design_spaces.py
get_all
get_all(
*,
parent_id: ProjectId,
state: DesignSpaceState | None = None,
max_items: int | None = None,
) -> Iterator[DesignSpace]
Get all design spaces in a project.
Results are returned as a lazily paginated iterator.
Example
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
parent_id
|
ProjectId
|
The project (format |
required |
state
|
DesignSpaceState
|
Limit to drafts or to published spaces. |
None
|
max_items
|
int
|
Stop after this many spaces. |
None
|
Returns:
| Type | Description |
|---|---|
Iterator[DesignSpace]
|
A lazily paginated iterator over the project's design spaces. |
Source code in src/albert/collections/design_spaces.py
update
update(*, design_space: DesignSpace) -> DesignSpace
Update the name or description of a draft design space.
Retrieve the space with
get_by_id,
modify name and/or description, then pass it here. Only changed fields
are applied.
A published space is frozen and cannot be updated;
fork it into a
new draft instead.
Example
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
design_space
|
DesignSpace
|
The design space carrying the desired changes. Its |
required |
Returns:
| Type | Description |
|---|---|
DesignSpace
|
The updated design space. |
Notes
The following fields can be updated: name, description.
Source code in src/albert/collections/design_spaces.py
apply
apply(
*,
id: DesignSpaceId,
operations: list[DesignSpaceOperation],
validate: bool = False,
preview: int | None = None,
dry_run: bool = False,
) -> DesignSpaceApplyResponse
Apply builder operations to a draft design space.
Operations apply atomically and in the order given; if one cannot apply (for example an unknown reference or an invalid constraint) nothing is applied. The five operations:
SetIngredientOperation: upsert an ingredient. Its value carries the three-way action (must include, may include, or exclude) and the ingredient's fraction bounds.SetParameterOperation: upsert a parameter with its allowed values.SetCountBoundsOperation: set or clear the ingredient-count bounds.RemoveComponentOperation: remove an ingredient or parameter by its path.UpdateComponentOperation: change one field of a component in place.
Ingredient bounds are checked as they are applied: min greater than max
is rejected for any action, and mustInclude with a max of 0 is rejected.
Changing min or max of an excluded ingredient with an
UpdateComponentOperation is also rejected; change its action first. Both
changes can be applied together, since operations apply in order.
Example
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
DesignSpaceId
|
The design space ID (format |
required |
operations
|
list[DesignSpaceOperation]
|
The operations to apply, in order. |
required |
validate
|
bool
|
Fold a feasibility check into the result. An infeasible outcome is a normal
result with |
False
|
preview
|
int
|
Fold a sample preview of this many formulations (1 to 25) into the result. |
None
|
dry_run
|
bool
|
Compute the would-be result without saving it. |
False
|
Returns:
| Type | Description |
|---|---|
DesignSpaceApplyResponse
|
The resulting design space, any non-blocking findings, and the feasibility check and sample preview when asked for. |
Raises:
| Type | Description |
|---|---|
AlbertClientError
|
An operation could not apply (unknown reference, invalid constraint, invalid ingredient bounds, or a conflicting edit), or the space is published. |
AlbertHTTPError
|
Other failures. |
Source code in src/albert/collections/design_spaces.py
270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 | |
check_feasibility
check_feasibility(
*,
id: DesignSpaceId,
smart_dataset_id: SmartDatasetId | None = None,
design_model_config_id: str | None = None,
) -> DesignSpaceValidationResponse
Check whether a design space can produce valid formulations.
Feasibility needs no dataset. smart_dataset_id and design_model_config_id
are accepted for checking the space against that context, but that check is not
applied yet: today the result reflects the space's own feasibility only.
valid=False with populated violations is a normal result, not an
exception. A solver timeout is reported as the feasibility_indeterminate
violation, meaning the answer is unknown rather than infeasible.
Example
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
DesignSpaceId
|
The design space ID (format |
required |
smart_dataset_id
|
SmartDatasetId
|
Smart dataset (format |
None
|
design_model_config_id
|
str
|
Design model config to check the space against. Accepted, but not applied yet. |
None
|
Returns:
| Type | Description |
|---|---|
DesignSpaceValidationResponse
|
The feasibility result with |
Source code in src/albert/collections/design_spaces.py
get_sample
get_sample(
*, id: DesignSpaceId, num_samples: int = 10
) -> DesignSpaceSample
Get a sample of the formulations a design space would produce.
A quick look at the envelope (search space), for inspecting what the bounds allow before committing a design run to them. The space is checked for feasibility before any formulation is drawn, so the call can take up to about a minute for a hard space.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
DesignSpaceId
|
The design space ID (format |
required |
num_samples
|
int
|
Number of formulations to draw (1 to 25, default 10). |
10
|
Returns:
| Type | Description |
|---|---|
DesignSpaceSample
|
The drawn sample. |
Raises:
| Type | Description |
|---|---|
AlbertClientError
|
The space is not valid (infeasible, or its feasibility could not be determined in time); the violations are listed. |
AlbertHTTPError
|
Other failures. |
Source code in src/albert/collections/design_spaces.py
publish
publish(*, id: DesignSpaceId) -> DesignSpace
Publish a draft design space, freezing it for use by design runs.
The space is validated first: an infeasible space cannot be published, and an
already-published space conflicts. Published spaces are immutable; to change
one, fork it
into a new draft.
Example
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
DesignSpaceId
|
The design space ID (format |
required |
Returns:
| Type | Description |
|---|---|
DesignSpace
|
The published design space. |
Raises:
| Type | Description |
|---|---|
AlbertClientError
|
The space is infeasible (the blocking violations are listed) or already published. |
AlbertHTTPError
|
Other failures. |
Source code in src/albert/collections/design_spaces.py
fork
fork(
*, id: DesignSpaceId, parent_id: ProjectId | None = None
) -> DesignSpace
Fork a published design space into a new editable draft.
The new draft remembers which published space it came from
(forked_from_id). Forking a draft conflicts; only published spaces can be
forked.
Example
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
DesignSpaceId
|
The published design space ID (format |
required |
parent_id
|
ProjectId
|
Target project (format |
None
|
Returns:
| Type | Description |
|---|---|
DesignSpace
|
The new draft design space. |
Source code in src/albert/collections/design_spaces.py
get_references
get_references(
*, id: DesignSpaceId, component: str
) -> DesignSpaceReferences
Get what references a component of a design space.
Powers safe removal: check whether anything still points at the component
before removing it with
apply.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
DesignSpaceId
|
The design space ID (format |
required |
component
|
str
|
Component path, |
required |
Returns:
| Type | Description |
|---|---|
DesignSpaceReferences
|
The references to the component. |
Source code in src/albert/collections/design_spaces.py
delete
delete(*, id: DesignSpaceId) -> None
Delete a design space by its ID.
A published space that a design run still references cannot be deleted.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
DesignSpaceId
|
The design space ID (format |
required |
Returns:
| Type | Description |
|---|---|
None
|
|