StationControlInterface

class StationControlInterface

Bases: ABC

Station control interface.

Station control interface implementation should implement 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", "gates.measure.constant.QB2.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.interface.station_control

Methods

abort_job	Either remove a job from the queue, or abort it gracefully if it's already executing.
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_calibration_set_quality_metrics	Get the latest quality metrics for the given calibration set ID.
get_channel_properties	Get channel properties from the station.
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_default_calibration_set	Get default calibration set from the database.
get_default_calibration_set_observations	Get default calibration set observations from the database.
get_default_calibration_set_quality_metrics	Get the latest quality metrics for the current default calibration set.
get_default_dynamic_quantum_architecture	Get dynamic quantum architecture for the default calibration set.
get_dut_fields	Get DUT fields for the specified DUT label from the database.
get_duts	Get DUTs of the station control.
get_dynamic_quantum_architecture	Get dynamic quantum architecture for the given calibration set ID.
get_exa_configuration	Return the recommended EXA configuration from the server.
get_health	Return the status of the station control service.
get_job	Get job data.
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 one if it doesn't exist.
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_static_quantum_architecture	Get static quantum architecture of the station for the given DUT label.
get_sweep	Get N-dimensional sweep data from the database.
get_sweep_results	Get N-dimensional sweep results from the database.
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.
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.

abstract get_about()

Return information about the station control.

Return type:

dict

abstract get_health()

Return the status of the station control service.

Return type:

dict

abstract get_configuration()

Return the configuration of the station control.

Return type:

dict

abstract get_exa_configuration()

Return the recommended EXA configuration from the server.

Return type:

str

abstract get_or_create_software_version_set(software_version_set)

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

Parameters:

software_version_set (dict[str, str]) –

Return type:

int

abstract get_settings()

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

Return type:

SettingNode

abstract get_chip_design_record(dut_label)

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

Parameters:

dut_label (str) –

Return type:

dict

abstract get_channel_properties()

Get channel properties from the station.

Channel properties contain information regarding hardware limitations e.g. sampling rate, granularity and supported instructions.

Returns:

Mapping from channel name to AWGProperties or ReadoutProperties.

Return type:

dict[str, ChannelProperties]

abstract 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:

ExaError if submitting a sweep failed. –

Return type:

dict

abstract get_sweep(sweep_id)

Get N-dimensional sweep data from the database.

Parameters:

sweep_id (UUID) –

Return type:

SweepData

abstract delete_sweep(sweep_id)

Delete sweep in the database.

Parameters:

sweep_id (UUID) –

Return type:

None

abstract get_sweep_results(sweep_id)

Get N-dimensional sweep results from the database.

Parameters:

sweep_id (UUID) –

Return type:

dict[str, list[ndarray]]

abstract run(run_definition, update_progress_callback=None, wait_job_completion=True)

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

Parameters:

• run_definition (RunDefinition) –

• update_progress_callback (Callable[[list[tuple[str, int, int]]], None] | None) –

• wait_job_completion (bool) –

Return type:

bool

abstract get_run(run_id)

Get run data from the database.

Parameters:

run_id (UUID) –

Return type:

RunData

abstract 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]

abstract 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]

abstract 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]

abstract 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]

abstract 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]

abstract 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]

abstract 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

abstract 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

abstract 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

abstract 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

abstract 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]

abstract get_default_calibration_set()

Get default calibration set from the database.

Return type:

ObservationSetData

abstract get_default_calibration_set_observations()

Get default calibration set observations from the database.

Return type:

list[ObservationLite]

abstract get_default_dynamic_quantum_architecture()

Get dynamic quantum architecture for the default calibration set.

Return type:

DynamicQuantumArchitecture

abstract get_dynamic_quantum_architecture(calibration_set_id)

Get dynamic quantum architecture for the given calibration set ID.

Returns:

Dynamic quantum architecture of the station for the given calibration set ID.

Parameters:

calibration_set_id (UUID) –

Return type:

DynamicQuantumArchitecture

abstract get_default_calibration_set_quality_metrics()

Get the latest quality metrics for the current default calibration set.

Return type:

QualityMetrics

abstract get_calibration_set_quality_metrics(calibration_set_id)

Get the latest quality metrics for the given calibration set ID.

Parameters:

calibration_set_id (UUID) –

Return type:

QualityMetrics

abstract get_duts()

Get DUTs of the station control.

Return type:

list[DutData]

abstract get_dut_fields(dut_label)

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

Parameters:

dut_label (str) –

Return type:

list[DutFieldData]

abstract 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]

abstract create_sequence_metadata(sequence_metadata_definition)

Create sequence metadata in the database.

Parameters:

sequence_metadata_definition (SequenceMetadataDefinition) –

Return type:

SequenceMetadataData

abstract 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

abstract get_sequence_result(sequence_id)

Get sequence result from the database.

Parameters:

sequence_id (UUID) –

Return type:

SequenceResultData

abstract get_static_quantum_architecture(dut_label)

Get static quantum architecture of the station for the given DUT label.

Returns:

Static quantum architecture of the station for the given DUT label.

Parameters:

dut_label (str) –

Return type:

StaticQuantumArchitecture

abstract get_job(job_id)

Get job data.

Parameters:

job_id (UUID) –

Return type:

JobData

abstract abort_job(job_id)

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

The status of the job will be set to JobStatus.ABORTED. If the job is not found or is already finished nothing happens.

Parameters:

job_id (UUID) –

Return type:

None