Models

Model

class qrobot.models.Model(n: int, tau: int, backend: QuantumBackend | None = None)

Base class for quantum-like perception models.

A model encodes an n-dimensional sequence over tau samples in a quantum circuit. Subclasses define the input-to-rotation mapping, query transformation, and decoding rule.

Parameters:

• n (int) – Number of input dimensions. Each dimension is represented by one qubit.

• tau (int) – Number of samples encoded in one temporal window.

n

Model’s dimension.

Type:

int

tau

Number of samples of the temporal window.

Type:

int

circ

Backend-specific circuit containing the encoded window.

Type:

object

clear() → None

Re-initialize the model with an empty circuit.

abstractmethod decode() → str

Measure and decode the model state as a basis-state label.

abstractmethod encode(scalar_input: float | int, dim: int) → float

Encode one normalized scalar in a single model dimension.

Subclasses implement the mapping from a normalized input to their backend operation. Implementations apply that operation to dim and return the numeric encoding parameter they used.

encode_vector(input_vector: Sequence[float | int]) → list[float]

Encode one input value for every model dimension.

This is the multidimensional counterpart of encode(). The value at each vector index is passed to the model’s encode() implementation for the matching dimension.

Parameters:

input_vector (sequence of float or int) – Exactly one model-specific scalar input per dimension.

Returns:

Numeric encoding parameters per dimension.

Return type:

list of float

Raises:

• TypeError – input_vector is not iterable, or encode() rejects one of its elements.

• ValueError – The vector length differs from n, or encode() rejects one of its elements.

get_density_matrix() → ndarray

Return the simulated density matrix of the model.

Returns:

Model’s density matrix.

Return type:

numpy.ndarray

get_statevector() → ndarray

Return the simulated state vector of the model.

Returns:

Model’s state vector.

Return type:

numpy.ndarray

measure(shots: int = 1) → dict[str, int]

Measure the qubits using the configured backend.

Parameters:

shots (int) – Number of times to repeat the measurement shot

Returns:

State occurrences counts in the form {“state”: count}

Return type:

dict

plot_state_mat() → None

Plot the real parts of the state vector and density matrix.

Example

To plot a perfectly balanced superposition of states:

model = Model(n, tau) # change Model with the desired child class

for t in range(0,model.tau): # loop through time
    model.encode_vector([.5] * model.n)

model.plot_state_mat()

Raises:

OverflowError – If the dimension of the model is 6 or greater, plotting fails due to the high number of basis states.

print_circuit() → None

Print the quantum circuit on which the model is implemented.

abstractmethod query(target_vector: Sequence[float | int] | float | int) → None

Change basis so target_vector maps to state |00…0>.

AngularModel

class qrobot.models.AngularModel(n: int, tau: int, backend: QuantumBackend | None = None)

Encode normalized inputs as Bloch-sphere rotation angles.

Each sample contributes scalar_input * pi / tau to the qubit assigned to its input dimension.

decode() → str

Decode the model with one computational-basis measurement.

Returns:

Measured basis-state bit string.

Return type:

str

encode(scalar_input: float | int, dim: int) → float

Encode one scalar input as a fractional y-axis rotation.

Use this method for one value in one dimension. Use encode_vector() to encode a complete multidimensional sample at once.

Parameters:

• scalar_input (float) – Normalized input in the interval [0, 1].

• dim (int) – Zero-based input dimension.

Returns:

The rotation angle applied to the qubit.

Return type:

float

Examples

Encode one value in dimension zero:

model = AngularModel(n=2, tau=1)
angle = model.encode(0.25, dim=0)

Encode both dimensions together:

angles = model.encode_vector([0.25, 0.75])

query(target_vector: Sequence[float | int] | float | int) → None

Change basis so target_vector maps to state |00…0>.

Parameters:

target_vector (list) – Normalized target value for every model dimension.

LinearModel

class qrobot.models.LinearModel(n: int, tau: int, backend: QuantumBackend | None = None)

Map a single normalized input linearly to measurement probability.

Warning

For tau == 1, measuring 1 has probability scalar_input. A constant input repeated over a longer window has the same relationship. Time-varying windows accumulate inverse-sine rotation angles, so their measurement probability is generally not the arithmetic mean of the inputs.

encode(scalar_input: float | int, dim: int) → float

Encode one scalar input using the linear-probability angle map.

Use this method for one value in one dimension. Use encode_vector() to encode a complete multidimensional sample at once.

Parameters:

• scalar_input (float) – Normalized input in the interval [0, 1].

• dim (int) – Zero-based input dimension.

Returns:

The rotation angle applied to the qubit.

Return type:

float

Examples

Encode one value in dimension zero:

model = LinearModel(n=2, tau=1)
angle = model.encode(0.25, dim=0)

Encode both dimensions together:

angles = model.encode_vector([0.25, 0.75])