qat.utils.pydantic module

Utility file for Pydantic related classes and functions.

Contains base classes for Pydantic models with builtin constraints, as well as utility functions and classes for efficient (de)serialization of numpy arrays and validation of custom types.

class AllowExtraFieldsModel(**data)

Bases: BaseModel

A Pydantic BaseModel with the extra constraints:

1. Assignment of fields after initialisation is checked again.

2. Extra fields given to the model are ignored (default behaviour in BaseModel).

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'use_enum_values': False, 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class FrozenDict(root=PydanticUndefined, **data)

Bases: PydDictBase

A Pydantic dict that is immutable after instantiation.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

root: pyd_frozendict[K, V]

class FrozenSet(root=PydanticUndefined, **data)

Bases: PydSetBase

A Pydantic set that is immutable after instantiation.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

root: frozenset[V]

class NoExtraFieldsFrozenModel(**data)

Bases: NoExtraFieldsModel

A Pydantic BaseModel with the extra constraints:

1. Assignment of fields after initialisation is checked again.

2. Extra fields given to the model are not ignored (default behaviour in BaseModel),

but raise an error now.

# All fields are frozen upon instantiation.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True, 'ser_json_inf_nan': 'constants', 'use_enum_values': False, 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class NoExtraFieldsModel(**data)

Bases: BaseModel

A Pydantic BaseModel with the extra constraints:

1. Assignment of fields after initialisation is checked again.

2. Extra fields given to the model are not ignored (default behaviour in BaseModel),

but raise an error now.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'ser_json_inf_nan': 'constants', 'use_enum_values': False, 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class PydArray(*args, value: NDArray[Any, int | float | complex | bool])

Bases: NoExtraFieldsModel, NDArrayOperatorsMixin

A data class wrapper to handle the information needed to completely describe a numpy array:

• Value is the numpy array itself

• Shape is the shape of the numpy array

• dtype is the data (implied) type of the numpy array

Through annotations, this allows creation of metadata classes on top of PydArray that describes how to (de)serialise a (blob) PydArray object according to some (required) type. See _validator() and _serializer().

Enlisting the array data as (nested) list(s) is not optimal, and this class renders (de)serialisation fast.

This class also mixes in NDArrayOperatorsMixin, which defines Python arithmetic operators in terms of NumPy ufuncs. This does NOT guarantee full interoperability with NumPy but allows the option to extend this support in the future. For now, the sole purpose of this class is ONLY to be a data class wrapper and mediator for (de)serialisation purposes.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'ser_json_inf_nan': 'constants', 'use_enum_values': False, 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context, /)

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Return type:

None

Args:

self: The BaseModel instance. context: The context.

value: NDArray[Shape['*, ...'], int | float | complex | bool]

class PydDictBase(root=PydanticUndefined, **data)

Bases: RootModel[dict[~GeneralKey, ~GeneralValue]]

Base class for Pydantic dict containers.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

get(key, default=None)

items()

keys()

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pop(key, *args, **kwargs)

root: dict[K, V]

values()

class PydListBase(root=PydanticUndefined, **data)

Bases: RootModel[list[~GeneralValue]]

Base class for Pydantic list containers.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

root: list[V]

class PydSetBase(root=PydanticUndefined, **data)

Bases: RootModel[set[~GeneralValue]]

Base class for Pydantic set containers.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

root: set[V]

class PydValidatedBase(root=PydanticUndefined, **data)

Bases: RootModel

Base class for validated Pydantic containers.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

validate_value(value)

validation_setup()

Setup validation for the container.

class RehydratableModel(**data)

Bases: BaseModel

A base model with utility to serialize and deserialize objects with type information.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property object_type: str

Returns the type of the object, which is the class name.

class ValidatedDict(root=PydanticUndefined, **data)

Bases: PydDictBase, PydValidatedBase

A dict object that validates the input added after instantiation.

This way, we are sure that the elements in a dict are only of a certain type. Pydantic containers only validate upon instantiation, not when modifying the container.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

update(data)

validate_key(key)

validation_setup()

Validate the types of keys and values in the dictionary.

class ValidatedList(root=PydanticUndefined, **data)

Bases: PydListBase, PydValidatedBase

A list object that validates the input appended/extended after instantiation.

This way, we are sure that the elements in a list are only of a certain type. Pydantic containers only validate upon instantiation, not when modifying the container.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

append(value)

extend(values)

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

remove(value)

class ValidatedSet(root=PydanticUndefined, **data)

Bases: PydSetBase, PydValidatedBase

A set object that validates the input added after instantiation.

This way, we are sure that the elements in a set are only of a certain type. Pydantic containers only validate upon instantiation, not when modifying the container.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

add(value)

discard(value)

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pop()

remove(value)

update(*sets)

annotate_pyd_array(ty)

Creates an annotated type for numeric lists with Pydantic serializers and validators for efficient serialization.

Parameters:

ty (type) – The required type of the elements in the array (e.g. np.float64).

Return type:

TypeAlias

Returns:

An annotated type that can be used in Pydantic models.

find_all_subclasses(cls)

Recursively finds nested subclasses of a class.

Return type:

list[type]

class uint(n)

Bases: object

Helper class for defining annotated unsigned integer fields with a given bit width.

Used as uint[n] to represent an unsigned integer field with n bits, which is validated to be between 0 and 2^n - 1 inclusive. When used in a Pydantic model as type hint, this will provide validation on the value.

validate_calibratable_positive_float(value)

Validator function to check if a value is a non-negative float.

Parameters:

value (float) – The value to validate.

Return type:

float

Returns:

The validated value if it is a non-negative float.

Raises:

ValueError – If the value is not a non-negative float.

validate_calibratable_unit_interval(value)

Validator function to check if a value is a float in the unit interval [0, 1].

Parameters:

value (float) – The value to validate.

Return type:

float

Returns:

The validated value if it is a float in the unit interval [0, 1].

Raises:

ValueError – If the value is not a float in the unit interval [0, 1].

validate_calibratable_unit_interval_array(array)

Validator function to check if a 2x2 array has all elements in the unit interval [0, 1].

Parameters:

array (PydArray) – The array to validate.

Return type:

PydArray

Returns:

The validated array if all elements are in the unit interval [0, 1].

Raises:

ValueError – If any element in the array is not in the unit interval [0, 1].

validate_non_negative(value)

Validator function to check if a value is a non-negative integer.

Parameters:

value (int) – The value to validate.

Return type:

int

Returns:

The validated value if it is a non-negative integer.

Raises:

ValueError – If the value is not a non-negative integer.

validate_qubit_coupling(value)

Validator function to check if a value is a valid qubit coupling.

Parameters:

value (tuple[int, int]) – The value to validate.

Return type:

tuple[int, int]

Returns:

The validated value if it is a valid qubit coupling.

Raises:

TypeError – If the value is not a valid qubit coupling.

validate_waveform_type(value)