StationControlClient

StationControlClient#

class StationControlClient(root_url, get_token_callback=None)#

Bases: object

Station control client implementation.

Current implementation uses HTTP calls to the remote station control service, that is controlling the station control instance.

Parameters:

  • root_url (str) – Remote station control service URL.

  • get_token_callback (Callable[[], str] | None) – A callback function that returns a token (str) which will be passed in Authorization header in all requests.

Station control client implements generic query methods for certain objects, like query_observations(), query_observation_sets(), and query_sequence_metadatas(). These methods accept only keyword arguments as parameters, which are based on the syntax field__lookup=value. Note double-underscore in the name, to separate field names like dut_field from lookup types like in. The syntax is based on Django implementation, documented here and here.

As a convenience, when no lookup type is provided (like in dut_label="foo"), the lookup type is assumed to be exact (dut_label__exact="foo"). Other supported lookup types are:

  • range: Range test (inclusive).

    For example, created_timestamp__range=(datetime(2023, 10, 12), datetime(2024, 10, 14))

  • in: In a given iterable; often a list, tuple, or queryset.

    For example, dut_field__in=["QB1.frequency", "QB2.readout.frequency"]

  • icontains: Case-insensitive containment test.

    For example, origin_uri__icontains="local"

  • overlap: Returns objects where the data shares any results with the values passed.

    For example, tags__overlap=["calibration=good", "2023-12-04"]

  • contains: The returned objects will be those where the values passed are a subset of the data.

    For example, tags__contains=["calibration=good", "2023-12-04"]

  • isnull: Takes either True or False, which correspond to SQL queries of IS NULL and IS NOT NULL, respectively.

    For example, end_timestamp__isnull=False

In addition to model fields (like “dut_label”, “dut_field”, “created_timestamp”, “invalid”, etc.), all of our generic query methods accept also following shared query parameters:

  • latest: str. Return only the latest item for this field, based on “created_timestamp”.

    For example, latest="invalid" would return only one result (latest “created_timestamp”) for each different “invalid” value in the database. Thus, maximum three results would be returned, one for each invalid value of True, False, and None.

  • order_by: str. Prefix with “-” for descending order, for example “-created_timestamp”.

  • limit: int: Default 20. If 0 (or negative number) is given, then pagination is not used, i.e. limit=infinity.

  • offset: int. Default 0.

Our generic query methods are not fully generalized yet, thus not all fields and lookup types are supported. Check query methods own documentation for details about currently supported query parameters.

Generic query methods will return a list of objects, but with additional (optional) “meta” attribute, which contains metadata, like pagination details. The client can ignore this data, or use it to implement pagination logic for example to fetch all results available.

Module: iqm.station_control.client.station_control

Methods

create_observation_set

Create an observation set in the database.

create_observations

Create observations in the database.

create_sequence_metadata

Create sequence metadata in the database.

delete_sweep

Delete sweep in the database.

finalize_observation_set

Finalize an observation set in the database.

get_about

Return information about the station control.

get_chad

DEPRECATED.

get_chip_design_record

Get a raw chip design record matching the given chip label.

get_configuration

Return the configuration of the station control.

get_dut_fields

Get DUT fields for the specified DUT label from the database.

get_duts

Get DUTs of the station control.

get_observation_set

Get an observation set from the database.

get_observation_set_observations

Get the constituent observations of an observation set from the database.

get_observations

Get observations from the database.

get_or_create_software_version_set

Get software version set ID from the database, or create if it doesn't exist.

get_qubit_design_properties

DEPRECATED.

get_run

Get run data from the database.

get_sequence_result

Get sequence result from the database.

get_settings

Return a tree representation of the default settings as defined in the configuration file.

get_sweep

Get N-dimensional sweep data from the database.

get_sweep_results

Get N-dimensional sweep results from the database.

get_task

Get task data.

query_observation_sets

Query observation sets from the database.

query_observations

Query observations from the database.

query_runs

Query runs from the database.

query_sequence_metadatas

Query sequence metadatas from the database.

revoke_sweep

Either remove a sweep task from the queue, or abort it gracefully if it's already executing.

run

Execute an N-dimensional sweep of selected variables and save run, sweep and results.

save_sequence_result

Save sequence result in the database.

sweep

Execute an N-dimensional sweep of selected variables and save sweep and results.

update_observation_set

Update an observation set in the database.

update_observations

Update observations in the database.
get_about()#

Return information about the station control.

Return type:

dict

get_configuration()#

Return the configuration of the station control.

Return type:

dict

get_or_create_software_version_set(software_version_set)#

Get software version set ID from the database, or create if it doesn’t exist.

Parameters:

software_version_set (dict[str, str]) –

Return type:

int

get_settings()#

Return a tree representation of the default settings as defined in the configuration file.

Return type:

SettingNode

get_chip_design_record(dut_label)#

Get a raw chip design record matching the given chip label.

Parameters:

dut_label (str) –

Return type:

dict

get_chad(dut_label)#

DEPRECATED.

Parameters:

dut_label (str) –

Return type:

CHAD

get_qubit_design_properties(dut_label)#

DEPRECATED.

Parameters:

dut_label (str) –

Return type:

dict

sweep(sweep_definition)#

Execute an N-dimensional sweep of selected variables and save sweep and results.

The raw data for each spot in the sweep is saved as numpy arrays, and the complete data for the whole sweep is saved as an x-array dataset which has the sweep_definition.sweeps as coordinates and data of sweep_definition.return_parameters data as DataArrays.

The values of sweep_definition.playlist will be uploaded to the controllers given by the keys of sweep_definition.playlist.

Parameters:

sweep_definition (SweepDefinition) – The content of the sweep to be created.

Returns:

Dict containing the task ID and sweep ID, and corresponding hrefs, of a successful sweep execution in monolithic mode or successful submission to the task queue in remote mode.

Raises:

RequestError if submitting a sweep failed. –

Return type:

dict

get_sweep(sweep_id)#

Get N-dimensional sweep data from the database.

Parameters:

sweep_id (UUID) –

Return type:

SweepData

revoke_sweep(sweep_id)#

Either remove a sweep task from the queue, or abort it gracefully if it’s already executing.

If the task was already executing when revoked, the status of the task will be set to "INTERRUPTED". If the task had not started yet, the status will be set to "REVOKED". If the task is not found or is already finished nothing happens.

Parameters:

sweep_id (UUID) –

Return type:

None

delete_sweep(sweep_id)#

Delete sweep in the database.

Parameters:

sweep_id (UUID) –

Return type:

None

get_sweep_results(sweep_id)#

Get N-dimensional sweep results from the database.

Parameters:

sweep_id (UUID) –

Return type:

dict[str, list[ndarray]]

run(run_definition, update_progress_callback=None, wait_task_completion=True)#

Execute an N-dimensional sweep of selected variables and save run, sweep and results.

Parameters:
Return type:

bool

get_run(run_id)#

Get run data from the database.

Parameters:

run_id (UUID) –

Return type:

RunData

query_runs(**kwargs)#

Query runs from the database.

Runs are queried by the given query parameters. Currently supported query parameters:

  • run_id: uuid.UUID

  • run_id__in: list[uuid.UUID]

  • sweep_id: uuid.UUID

  • sweep_id__in: list[uuid.UUID]

  • username: str

  • username__in: list[str]

  • username__contains: str

  • username__icontains: str

  • experiment_label: str

  • experiment_label__in: list[str]

  • experiment_label__contains: str

  • experiment_label__icontains: str

  • experiment_name: str

  • experiment_name__in: list[str]

  • experiment_name__contains: str

  • experiment_name__icontains: str

  • software_version_set_id: int

  • software_version_set_id__in: list[int]

  • begin_timestamp__range: tuple[datetime, datetime]

  • end_timestamp__range: tuple[datetime, datetime]

  • end_timestamp__isnull: bool

Returns:

Queried runs with some query related metadata.

Return type:

ListWithMeta[RunLite]

create_observations(observation_definitions)#

Create observations in the database.

Parameters:

observation_definitions (Sequence[ObservationDefinition]) – A sequence of observation definitions, each containing the content of the observation which will be created.

Returns:

Created observations, each including also the database created fields like ID and timestamps.

Return type:

ListWithMeta[ObservationData]

get_observations(*, mode, dut_label=None, dut_field=None, tags=None, invalid=False, run_ids=None, sequence_ids=None, limit=None)#

Get observations from the database.

Observations are queried by the given query parameters.

Parameters:

  • mode (Literal['all_latest', 'tags_and', 'tags_or', 'sequence']) –

    The “mode” used to query the observations. Possible values “all_latest”, “tags_and”, or “tags_or”.

    • ”all_latest”:Query all the latest observations for the given dut_label. No other query parameters are accepted.

    • ”tags_and”: Query observations. Query all the observations that have all the given tags. By default, only valid observations are included. All other query parameters can be used to narrow down the query, expect “run_ids” and “sequence_ids”.

    • ”tags_or”: Query all the latest observations that have at least one of the given tags. Additionally, dut_label must be given. No other query parameters are used.

    • ”sequence”: Query observations originating from a list of run and/or sequence IDs. No other query parameters are accepted.

  • dut_label (str | None) – DUT label of the device the observations pertain to.

  • dut_field (str | None) – Name of the property the observation is about.

  • tags (list[str] | None) – Human-readable tags of the observation.

  • invalid (bool | None) – Flag indicating if the object is invalid. Automated systems must not use invalid objects. If None, both valid and invalid objects are included.

  • run_ids (list[UUID] | None) – The run IDs for which to query the observations.

  • sequence_ids (list[UUID] | None) – The sequence IDs for which to query the observations.

  • limit (int | None) – Indicates the maximum number of items to return.

Returns:

Observations, each including also the database created fields like ID and timestamps.

Return type:

list[ObservationData]

query_observations(**kwargs)#

Query observations from the database.

Observations are queried by the given query parameters. Currently supported query parameters:

  • observation_id: int

  • observation_id__in: list[int]

  • dut_label: str

  • dut_field: str

  • dut_field__in: list[str]

  • tags__overlap: list[str]

  • tags__contains: list[str]

  • invalid: bool

  • source__run_id__in: list[uuid.UUID]

  • source__sequence_id__in: list[uuid.UUID]

  • source__type: str

  • uncertainty__isnull: bool

  • created_timestamp__range: tuple[datetime, datetime]

  • observation_set_ids__overlap: list[uuid.UUID]

  • observation_set_ids__contains: list[uuid.UUID]

Returns:

Queried observations with some query related metadata.

Return type:

ListWithMeta[ObservationData]

update_observations(observation_updates)#

Update observations in the database.

Parameters:

observation_updates (Sequence[ObservationUpdate]) – A sequence of observation updates, each containing the content of the observation which will be updated.

Returns:

Updated observations, each including also the database created fields like ID and timestamps.

Return type:

list[ObservationData]

query_observation_sets(**kwargs)#

Query observation sets from the database.

Observation sets are queried by the given query parameters. Currently supported query parameters:

  • observation_set_id: UUID

  • observation_set_id__in: list[UUID]

  • observation_set_type: Literal[“calibration-set”, “generic-set”, “quality-metric-set”]

  • observation_ids__overlap: list[int]

  • observation_ids__contains: list[int]

  • describes_id: UUID

  • describes_id__in: list[UUID]

  • invalid: bool

  • created_timestamp__range: tuple[datetime, datetime]

  • end_timestamp__isnull: bool

  • dut_label: str

  • dut_label__in: list[str]

Returns:

Queried observation sets with some query related metadata

Return type:

ListWithMeta[ObservationSetData]

create_observation_set(observation_set_definition)#

Create an observation set in the database.

Parameters:

observation_set_definition (ObservationSetDefinition) – The content of the observation set to be created.

Returns:

The content of the observation set.

Raises:

ExaError – If creation failed.

Return type:

ObservationSetData

get_observation_set(observation_set_id)#

Get an observation set from the database.

Parameters:

observation_set_id (UUID) – Observation set to retrieve.

Returns:

The content of the observation set.

Raises:

ExaError – If retrieval failed.

Return type:

ObservationSetData

update_observation_set(observation_set_update)#

Update an observation set in the database.

Parameters:

observation_set_update (ObservationSetUpdate) – The content of the observation set to be updated.

Returns:

The content of the observation set.

Raises:

ExaError – If updating failed.

Return type:

ObservationSetData

finalize_observation_set(observation_set_id)#

Finalize an observation set in the database.

A finalized set is nearly immutable, allowing to change only invalid flag after finalization.

Parameters:

observation_set_id (UUID) – Observation set to finalize.

Raises:

ExaError – If finalization failed.

Return type:

None

get_observation_set_observations(observation_set_id)#

Get the constituent observations of an observation set from the database.

Parameters:

observation_set_id (UUID) – UUID of the observation set to retrieve.

Returns:

Observations belonging to the given observation set.

Return type:

list[ObservationLite]

get_duts()#

Get DUTs of the station control.

Return type:

list[DutData]

get_dut_fields(dut_label)#

Get DUT fields for the specified DUT label from the database.

Parameters:

dut_label (str) –

Return type:

list[DutFieldData]

query_sequence_metadatas(**kwargs)#

Query sequence metadatas from the database.

Sequence metadatas are queried by the given query parameters. Currently supported query parameters:

  • origin_id: str

  • origin_id__in: list[str]

  • origin_uri: str

  • origin_uri__icontains: str

  • created_timestamp__range: tuple[datetime, datetime]

Returns:

Sequence metadatas with some query related metadata.

Return type:

ListWithMeta[SequenceMetadataData]

create_sequence_metadata(sequence_metadata_definition)#

Create sequence metadata in the database.

Parameters:

sequence_metadata_definition (SequenceMetadataDefinition) –

Return type:

SequenceMetadataData

save_sequence_result(sequence_result_definition)#

Save sequence result in the database.

This method creates the object if it doesn’t exist and completely replaces the “data” and “final” if it does. Timestamps are assigned by the database. “modified_timestamp” is not set on initial creation, but it’s updated on each subsequent call.

Parameters:

sequence_result_definition (SequenceResultDefinition) –

Return type:

SequenceResultData

get_sequence_result(sequence_id)#

Get sequence result from the database.

Parameters:

sequence_id (UUID) –

Return type:

SequenceResultData

get_task(task_id)#

Get task data.

Parameters:

task_id (UUID) –

Return type:

dict