loom.executor.circuit_error_model

Copyright (c) Entropica Labs Pte Ltd 2025.

Use, distribution and reproduction of this program in its source or compiled form is prohibited without the express written consent of Entropica Labs Pte Ltd.

class loom.executor.circuit_error_model.ApplicationMode(*values)

Bases: str, Enum

Enum-like class to define the application mode of the error model.

AFTER_GATE = 'after_gate'

BEFORE_GATE = 'before_gate'

END_OF_TICK = 'end_of_tick'

IDLE_END_OF_TICK = 'idle_end_of_tick'

class loom.executor.circuit_error_model.AsymmetricDepolarizeCEM(**data)

Bases: CircuitErrorModel

Error model that applies asymmetric depolarizing noise to the circuit.

Enforce the following properties: - The error model is time-dependent. - The error type is PAULI_CHANNEL. - The application mode is END_OF_TICK.

Parameters:

• t1 (float) – The time constant for the X and Y errors. Must be positive.

• t2 (float) – The time constant for the Z error. Must be positive.

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.

application_mode: ApplicationMode

classmethod check_positive(v, info)

Ensure that t1 and t2 are positive.

error_type: ErrorType

gate_error_probabilities: dict[str, Callable[[Optional[float]], list[float]]] | None

global_time_error_probability: ErrorProbProtocol

is_time_dependent: bool

model_computed_fields: ClassVar[Dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'frozen': True}

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

model_fields: ClassVar[Dict[str, FieldInfo]] = {'application_mode': FieldInfo(annotation=ApplicationMode, required=False, default=<ApplicationMode.END_OF_TICK: 'end_of_tick'>, init=False), 'circuit': FieldInfo(annotation=Circuit, required=True), 'error_type': FieldInfo(annotation=ErrorType, required=False, default=<ErrorType.PAULI_CHANNEL: ('pauli_channel', 3)>, init=False), 'gate_durations': FieldInfo(annotation=Union[dict[str, float], NoneType], required=False, default=defaultdict(<function CircuitErrorModel.<lambda>>, {})), 'gate_error_probabilities': FieldInfo(annotation=Union[dict[str, Callable[list, list[float]]], NoneType], required=False, default_factory=<lambda>, init=False), 'global_time_error_probability': FieldInfo(annotation=ErrorProbProtocol, required=False, default=<function AsymmetricDepolarizeCEM.<lambda>>, init=False), 'is_time_dependent': FieldInfo(annotation=bool, required=False, default=True, init=False), 't1': FieldInfo(annotation=float, required=True), 't2': FieldInfo(annotation=float, required=True)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo] objects.

This replaces Model.__fields__ from Pydantic V1.

t1: float

t2: float

classmethod validate_time_constants(model)

t2 must be smaller or equal 2*t1.

Return type:

float

class loom.executor.circuit_error_model.CircuitErrorModel(**data)

Bases: BaseModel

Define a circuit error model that can be used to simulate errors in quantum circuits. This model can be time-dependent or not, having error applied in different modes, and can define error probabilities for each gate in the circuit or for each tick in the circuit. It is designed to be used with the Circuit class and its operations.

This class is very general and allows for very flexible error modeling, however, it is a bit tedious to work with, so we recommend to define subclasses that define specific error models for your use case.

Parameters:

• circuit (Circuit) – The quantum circuit to which the error model will be applied. This is frozen after initialization, so it cannot be changed.

• error_type (ErrorType) – The type of error that the model will apply to the circuit. This is frozen after initialization, so it cannot be changed.

• is_time_dependent (bool) – Whether the error model is time-dependent or not. If True, the model will use gate_durations to compute error probabilities. If False, the model will not use gate_durations. This is frozen after initialization, so it cannot be changed.

• application_mode (ApplicationMode) – The mode in which the error is applied to the circuit. It can be BEFORE_GATE, AFTER_GATE, or END_OF_TICK. This is frozen after initialization, so it cannot be changed.

• gate_durations (Optional[dict[str, float]]) – A dictionary mapping gate names to their execution times. This is only used if the model is time-dependent. If the model is not time-dependent, this can be None. If provided, it must assign a duration to each gate type present in the circuit.

• gate_error_probabilities (Optional[dict[str, GateErrorProbProtocol]]) – A dictionary mapping gate names to a callable that returns the error probability for that gate. If the model is time-dependent, the callable can take an optional time parameter. If the model is not time-dependent, the callable should not take any parameters. If one gate isn’t in the dictionary, it will default to a callable that returns 0.

• global_time_error_probability (Callable[[Optional[float]], list[float]]) –

  A callable that returns the error probability at a specific time in the circuit. It can take an optional time parameter, which represents some information in the current tick: - If the application mode is END_OF_TICK, it represents the duration of the tick. - If the application mode is IDLE_END_OF_TICK, it represents the idle times of the channel in the tick.

  The function must be well-defined at t = 0 (for both inputs).

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.

application_mode: ApplicationMode

classmethod check__op_time_defined_if_time_dependent(model)

Ensure that _op_time is defined if the model is time-dependent.

classmethod check_duration_defined_if_time_dependent(model)

Ensure that gate_durations is defined if the model is time-dependent.

classmethod check_idle_application_is_time_dependent(model)

Ensure that idle application mode is only used for time-dependent models.

circuit: Circuit

error_type: ErrorType

gate_durations: Optional[dict[str, float]]

gate_error_probabilities: Optional[dict[str, Callable[[Optional[float]], list[float]]]]

get_gate_error_probability(gate)

Get the error type (instruction) and probability for a given gate.

Parameters:

Circuit – The quantum gate for which to get the error type and probability.

Returns:

List of floats representing the error probabilities parameters given the gate name if the error probability is 0, return None so that it gets ignored if the application mode is END_OF_TICK, return None

Return type:

list[float] | None

get_idle_tick_error_probability(tick_index, channel_id)

Get the error probability based on the time a specific channel was idle during a tick.

Parameters:

• tick_index (int) – The index of the tick for which to get the error probability.

• channel_id (str) – The ID of the channel for which to get the idle time error probability.

Returns:

List of floats representing the error probabilities for the idle tick. If the application mode is not IDLE_END_OF_TICK, returns None.

Return type:

list[float] | None

get_tick_error_probability(tick_index=None)

Get the error probability for a specific tick in the circuit.

Parameters:

int – The index of the tick for which to get the error probability.

Returns:

List of floats representing the error probabilities for the tick. If the application mode is not END_OF_TICK, returns None.

Return type:

list[float] | None

global_time_error_probability: ErrorProbProtocol

is_time_dependent: bool

model_computed_fields: ClassVar[Dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'frozen': True}

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

model_fields: ClassVar[Dict[str, FieldInfo]] = {'application_mode': FieldInfo(annotation=ApplicationMode, required=True), 'circuit': FieldInfo(annotation=Circuit, required=True), 'error_type': FieldInfo(annotation=ErrorType, required=True), 'gate_durations': FieldInfo(annotation=Union[dict[str, float], NoneType], required=False, default=defaultdict(<function CircuitErrorModel.<lambda>>, {})), 'gate_error_probabilities': FieldInfo(annotation=Union[dict[str, Callable[list, list[float]]], NoneType], required=False, default=defaultdict(<function CircuitErrorModel.<lambda>>, {})), 'global_time_error_probability': FieldInfo(annotation=ErrorProbProtocol, required=False, default=<function CircuitErrorModel.<lambda>>), 'is_time_dependent': FieldInfo(annotation=bool, required=True)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo] objects.

This replaces Model.__fields__ from Pydantic V1.

property total_time: float

Total time of the circuit, computed as the sum of all tick durations.

Returns:

The total time of the circuit.

Return type:

float

Raises:

ValueError – If the circuit is not time-dependent or tick durations are not set.

update_gate_durations(gate_durations)

Update the gate durations for the error model. This will recompute the operation times and tick durations if the model is time-dependent.

classmethod validate_gate_duration(model)

Ensure the gates duration are defined for all gate used in the circuit and that each gate has a valid duration.

classmethod validate_gate_error_probabilities(v)

Validate the gate error probabilities dictionary. Ensure it contains only gates in the gate_set Also ensure that each value is a callable.

Parameters:

v (dict[str, GateErrorProbProtocol] | None) – The dictionary of gate error probabilities, where keys are gate names and values are callables that return a list of floats representing the error probabilities for that gate. If None, it defaults to a callable that returns 0.0 for all gates.

Returns:

A validated dictionary of gate error probabilities, where each key is a gate name and each value is a callable that returns the error probabilities for that gate.

Return type:

dict[str, GateErrorProbProtocol]

Raises:

• TypeError – If v is not a dictionary or callable.:

• ValueError – If v contains invalid gate names or if a value is not callable.:

classmethod validate_gate_error_probabilities_output(model)

Validate that each lambda in gate_error_probabilities returns the correct number of parameters. The previous validators will typically assign default value of [0.0] to the gate error probabilities for each undefined gate, but some error types may require multiple parameters (e.g., PAULI_CHANNEL). This validator will reformat the default value to return a list of zeros with the correct length.

classmethod validate_global_time_error_probability(v)

Validate the tick error probabilities callable. Ensure it returns a float or a list of floats for t=0.

Return type:

ErrorProbProtocol

classmethod validate_global_time_error_probability_output(model)

Validate that global_time_error_probability returns the correct number of parameters. The previous validators will typically assign default value of [0.0] to the global time error probability, but some error types may require multiple parameters (e.g., PAULI_CHANNEL). This validator will reformat the default value to return a list of zeros with the correct length.

class loom.executor.circuit_error_model.ErrorProbProtocol(*args, **kwargs)

Bases: Protocol

Protocol for error probability functions.

class loom.executor.circuit_error_model.ErrorType(label, param_count)

Bases: Enum

Provides a set of error types that can be used to define the error model for a quantum circuit. Each error type has a label and a number of parameters that it expects. Also provides a method to validate the parameters for the error type by checking they are a proper probability distribution (sum doesn’t exceed 1 if multiple parameters) and that they are in the range [0, 1].

BIT_FLIP = ('bit-flip', 1)

DEPOLARIZING1 = ('depolarizing1', 1)

DEPOLARIZING2 = ('depolarizing2', 1)

PAULI_CHANNEL = ('pauli_channel', 3)

PAULI_X = ('pauli_x', 1)

PAULI_Y = ('pauli_y', 1)

PAULI_Z = ('pauli_z', 1)

PHASE_FLIP = ('phase-flip', 1)

validate_params(params)

Raise ValueError if params are not valid for this error type.

Return type:

None

class loom.executor.circuit_error_model.HomogeneousTimeDependentCEM(**data)

Bases: CircuitErrorModel

A constant probability error model that applies a fixed error probability function to all gates in the circuit.

Enforces the following properties:

• The error model is time-dependent.

Parameters:

• error_type (ErrorType) – The type of error that the model will apply to the circuit.

• application_mode (ApplicationMode) – The mode in which the error is applied to the circuit.

• error_probability (ErrorProbProtocol) – The error probability parameter(s) for the error model. This will be assigned to all target gates.

• target_gates (list[str]) – A list of gate names to which the error probability applies. Other gates will have an error probability of 0.0 by default.

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.

application_mode: ApplicationMode

error_probability: ErrorProbProtocol

error_type: ErrorType

is_time_dependent: bool

model_computed_fields: ClassVar[Dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'frozen': True}

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

model_fields: ClassVar[Dict[str, FieldInfo]] = {'application_mode': FieldInfo(annotation=ApplicationMode, required=True), 'circuit': FieldInfo(annotation=Circuit, required=True), 'error_probability': FieldInfo(annotation=ErrorProbProtocol, required=True), 'error_type': FieldInfo(annotation=ErrorType, required=True), 'gate_durations': FieldInfo(annotation=Union[dict[str, float], NoneType], required=False, default=defaultdict(<function CircuitErrorModel.<lambda>>, {})), 'gate_error_probabilities': FieldInfo(annotation=Union[dict[str, Callable[list, list[float]]], NoneType], required=False, default=defaultdict(<function CircuitErrorModel.<lambda>>, {})), 'global_time_error_probability': FieldInfo(annotation=ErrorProbProtocol, required=False, default=<function CircuitErrorModel.<lambda>>), 'is_time_dependent': FieldInfo(annotation=bool, required=False, default=True, init=False), 'target_gates': FieldInfo(annotation=list[str], required=False, default=[])}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo] objects.

This replaces Model.__fields__ from Pydantic V1.

target_gates: list[str]

class loom.executor.circuit_error_model.HomogeneousTimeIndependentCEM(**data)

Bases: CircuitErrorModel

A constant probability error model that applies a fixed error probability to all gates in the circuit. This model is not time-dependent, meaning the error probability does not change over time.

Enforces the following properties:

• The error model is not time-dependent.

Parameters:

• error_type (ErrorType) – The type of error that the model will apply to the circuit.

• application_mode (ApplicationMode) – The mode in which the error is applied to the circuit.

• error_probability (list[float]) – The error probability parameter(s) for the error model. This will be assigned to all target gates.

• target_gates (list[str]) – A list of gate names to which the error probability applies. Other gates will have an error probability of 0.0 by default.

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.

application_mode: ApplicationMode

error_probability: float | list[float]

error_type: ErrorType

gate_error_probabilities: dict[str, Callable[[Optional[float]], list[float]]] | None

global_time_error_probability: ErrorProbProtocol

is_time_dependent: bool

model_computed_fields: ClassVar[Dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'frozen': True}

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

model_fields: ClassVar[Dict[str, FieldInfo]] = {'application_mode': FieldInfo(annotation=ApplicationMode, required=True), 'circuit': FieldInfo(annotation=Circuit, required=True), 'error_probability': FieldInfo(annotation=Union[float, list[float]], required=True), 'error_type': FieldInfo(annotation=ErrorType, required=True), 'gate_durations': FieldInfo(annotation=Union[dict[str, float], NoneType], required=False, default=defaultdict(<function CircuitErrorModel.<lambda>>, {})), 'gate_error_probabilities': FieldInfo(annotation=Union[dict[str, Callable[list, list[float]]], NoneType], required=False, default_factory=<lambda>, init=False), 'global_time_error_probability': FieldInfo(annotation=ErrorProbProtocol, required=False, default=<function HomogeneousTimeIndependentCEM.<lambda>>, init=False), 'is_time_dependent': FieldInfo(annotation=bool, required=False, default=False, init=False), 'target_gates': FieldInfo(annotation=list[str], required=False, default=[])}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo] objects.

This replaces Model.__fields__ from Pydantic V1.

target_gates: list[str]

classmethod validate_error_probability(v)

Validate the error probability to ensure it is a list of floats.

Return type:

list[float]