qctrl-commons 25.2.1__tar.gz → 25.4.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {qctrl_commons-25.2.1 → qctrl_commons-25.4.0}/PKG-INFO +1 -1
- {qctrl_commons-25.2.1 → qctrl_commons-25.4.0}/pyproject.toml +1 -1
- {qctrl_commons-25.2.1 → qctrl_commons-25.4.0}/qctrlcommons/__init__.py +1 -1
- {qctrl_commons-25.2.1 → qctrl_commons-25.4.0}/qctrlcommons/data_types.py +8 -0
- {qctrl_commons-25.2.1 → qctrl_commons-25.4.0}/qctrlcommons/serializers.py +2 -0
- {qctrl_commons-25.2.1 → qctrl_commons-25.4.0}/qctrlcommons/simulation_types.py +12 -9
- qctrl_commons-25.4.0/qctrlcommons/sparse_occ_op.py +195 -0
- {qctrl_commons-25.2.1 → qctrl_commons-25.4.0}/LICENSE +0 -0
- {qctrl_commons-25.2.1 → qctrl_commons-25.4.0}/README.md +0 -0
- {qctrl_commons-25.2.1 → qctrl_commons-25.4.0}/qctrlcommons/constants.py +0 -0
- {qctrl_commons-25.2.1 → qctrl_commons-25.4.0}/qctrlcommons/core_exceptions.py +0 -0
- {qctrl_commons-25.2.1 → qctrl_commons-25.4.0}/qctrlcommons/exceptions.py +0 -0
- {qctrl_commons-25.2.1 → qctrl_commons-25.4.0}/qctrlcommons/graph.py +0 -0
- {qctrl_commons-25.2.1 → qctrl_commons-25.4.0}/qctrlcommons/node/__init__.py +0 -0
- {qctrl_commons-25.2.1 → qctrl_commons-25.4.0}/qctrlcommons/node/base.py +0 -0
- {qctrl_commons-25.2.1 → qctrl_commons-25.4.0}/qctrlcommons/node/wrapper.py +0 -0
- {qctrl_commons-25.2.1 → qctrl_commons-25.4.0}/qctrlcommons/pauli_operations.py +0 -0
- {qctrl_commons-25.2.1 → qctrl_commons-25.4.0}/qctrlcommons/preconditions.py +0 -0
- {qctrl_commons-25.2.1 → qctrl_commons-25.4.0}/qctrlcommons/pytest_plugin.py +0 -0
- {qctrl_commons-25.2.1 → qctrl_commons-25.4.0}/qctrlcommons/run_options.py +0 -0
- {qctrl_commons-25.2.1 → qctrl_commons-25.4.0}/qctrlcommons/utils.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: qctrl-commons
|
|
3
|
-
Version: 25.
|
|
3
|
+
Version: 25.4.0
|
|
4
4
|
Summary: Q-CTRL Commons
|
|
5
5
|
License-File: LICENSE
|
|
6
6
|
Keywords: black opal,boulder opal,fire opal,nisq,open controls,q control,q ctrl,q-control,q-ctrl,qcontrol,qctrl,quantum,quantum algorithms,quantum circuits,quantum coding,quantum coding software,quantum computing,quantum control,quantum control software,quantum control theory,quantum engineering,quantum error correction,quantum firmware,quantum fundamentals,quantum sensing,qubit,qudit
|
|
@@ -48,6 +48,7 @@ from qctrlcommons.simulation_types import (
|
|
|
48
48
|
ModelType,
|
|
49
49
|
SimulationType,
|
|
50
50
|
)
|
|
51
|
+
from qctrlcommons.sparse_occ_op import SparseOccupationOperators
|
|
51
52
|
|
|
52
53
|
|
|
53
54
|
def handle_built_in_iterator(obj):
|
|
@@ -639,3 +640,10 @@ class SimulationTypeDataType(DataclassType):
|
|
|
639
640
|
|
|
640
641
|
_type = SimulationType
|
|
641
642
|
object_key = "fire_opal_simulation_type"
|
|
643
|
+
|
|
644
|
+
|
|
645
|
+
class SparseOccupationOperatorsDataType(DataclassType):
|
|
646
|
+
"""Handle SparseOccupationOperators serialization."""
|
|
647
|
+
|
|
648
|
+
_type = SparseOccupationOperators
|
|
649
|
+
object_key = "fire_opal_sparse_occ_op"
|
|
@@ -41,6 +41,7 @@ from .data_types import (
|
|
|
41
41
|
SimulationTypeDataType,
|
|
42
42
|
SliceDataType,
|
|
43
43
|
SparseMatrix,
|
|
44
|
+
SparseOccupationOperatorsDataType,
|
|
44
45
|
SympyExprDataType,
|
|
45
46
|
SympyPolyDataType,
|
|
46
47
|
)
|
|
@@ -71,6 +72,7 @@ class DataTypeMixin:
|
|
|
71
72
|
PauliOperatorDataType(),
|
|
72
73
|
ModelTypeDataType(),
|
|
73
74
|
SimulationTypeDataType(),
|
|
75
|
+
SparseOccupationOperatorsDataType(),
|
|
74
76
|
]
|
|
75
77
|
|
|
76
78
|
|
|
@@ -30,11 +30,11 @@ class ModelType:
|
|
|
30
30
|
|
|
31
31
|
Parameters
|
|
32
32
|
----------
|
|
33
|
-
hopping_amplitude : list[float]
|
|
33
|
+
hopping_amplitude : float or list[float]
|
|
34
34
|
Hopping amplitude between sites.
|
|
35
|
-
on_site_interaction : list[float]
|
|
35
|
+
on_site_interaction : float or list[float]
|
|
36
36
|
On-site interaction strength.
|
|
37
|
-
chemical_potential : list[float]
|
|
37
|
+
chemical_potential : float or list[float]
|
|
38
38
|
Chemical potential at each site.
|
|
39
39
|
name : str, optional
|
|
40
40
|
Name of the model (for example, `"Fermi-Hubbard"`). Defaults to "Fermi-Hubbard".
|
|
@@ -47,9 +47,9 @@ class ModelType:
|
|
|
47
47
|
If any field has an invalid type or value.
|
|
48
48
|
"""
|
|
49
49
|
|
|
50
|
-
hopping_amplitude: list[float]
|
|
51
|
-
on_site_interaction: list[float]
|
|
52
|
-
chemical_potential: list[float]
|
|
50
|
+
hopping_amplitude: list[float] | float
|
|
51
|
+
on_site_interaction: list[float] | float
|
|
52
|
+
chemical_potential: list[float] | float
|
|
53
53
|
name: Literal["Fermi-Hubbard"] = "Fermi-Hubbard"
|
|
54
54
|
lattice_type: Literal["1D"] = "1D"
|
|
55
55
|
|
|
@@ -75,11 +75,14 @@ class ModelType:
|
|
|
75
75
|
("chemical_potential", self.chemical_potential),
|
|
76
76
|
):
|
|
77
77
|
if not (
|
|
78
|
-
isinstance(term_value,
|
|
79
|
-
|
|
78
|
+
isinstance(term_value, int | float)
|
|
79
|
+
or (
|
|
80
|
+
isinstance(term_value, list)
|
|
81
|
+
and all(isinstance(item, int | float) for item in term_value)
|
|
82
|
+
)
|
|
80
83
|
):
|
|
81
84
|
raise QctrlArgumentsValueError(
|
|
82
|
-
f"The model {term_name} must be a list of real numbers.",
|
|
85
|
+
f"The model {term_name} must be a real number or a list of real numbers.",
|
|
83
86
|
{term_name: term_value},
|
|
84
87
|
)
|
|
85
88
|
|
|
@@ -0,0 +1,195 @@
|
|
|
1
|
+
# Copyright 2026 Q-CTRL. All rights reserved.
|
|
2
|
+
#
|
|
3
|
+
# Licensed under the Q-CTRL Terms of service (the "License"). Unauthorized
|
|
4
|
+
# copying or use of this file, via any medium, is strictly prohibited.
|
|
5
|
+
# Proprietary and confidential. You may not use this file except in compliance
|
|
6
|
+
# with the License. You may obtain a copy of the License at
|
|
7
|
+
#
|
|
8
|
+
# https://q-ctrl.com/terms
|
|
9
|
+
#
|
|
10
|
+
# Unless required by applicable law or agreed to in writing, software
|
|
11
|
+
# distributed under the License is distributed on an "AS IS" BASIS. See the
|
|
12
|
+
# License for the specific language.
|
|
13
|
+
"""
|
|
14
|
+
Dataclass defining sparse occupation operators for Fire Opal dynamics simulation.
|
|
15
|
+
"""
|
|
16
|
+
|
|
17
|
+
from dataclasses import asdict, dataclass
|
|
18
|
+
from typing import Any
|
|
19
|
+
|
|
20
|
+
OperatorComponent = tuple[str, int]
|
|
21
|
+
Operator = list[OperatorComponent]
|
|
22
|
+
_COMPONENT_LENGTH = 2
|
|
23
|
+
_VALID_SPINS = {"Nup", "Ndn"}
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
@dataclass
|
|
27
|
+
class SparseOccupationOperators:
|
|
28
|
+
"""
|
|
29
|
+
A dataclass representing sparse occupation operators.
|
|
30
|
+
|
|
31
|
+
This class handles observables by accepting a list of terms, where each
|
|
32
|
+
term is itself a list of (spin, site) tuples. A 1-point observable is
|
|
33
|
+
represented as a list of length 1, while multi-point observables are
|
|
34
|
+
lists of length > 1.
|
|
35
|
+
|
|
36
|
+
Parameters
|
|
37
|
+
----------
|
|
38
|
+
operators : list[list[tuple[str, int]]]
|
|
39
|
+
A list of terms making up the operator. Each term is a list of tuples.
|
|
40
|
+
1-point observable example: `[[("Nup", 3)]]`
|
|
41
|
+
Multi-point observable example: `[[("Ndn", 7), ("Nup", 9), ("Nup", 4)]]`
|
|
42
|
+
coefficients : list[float]
|
|
43
|
+
A list of coefficients corresponding to each operator term in `operators`.
|
|
44
|
+
Must be the exact same length as `operators`.
|
|
45
|
+
|
|
46
|
+
Raises
|
|
47
|
+
------
|
|
48
|
+
ValueError
|
|
49
|
+
If the lengths of `operators` and `coefficients` do not match, if an operator
|
|
50
|
+
tuple does not have exactly 2 elements, or if the spin is not "Nup" or "Ndn".
|
|
51
|
+
TypeError
|
|
52
|
+
If the types within the lists are incorrect (e.g., coefficient is
|
|
53
|
+
not a number, spin is not a string, or site is not an integer).
|
|
54
|
+
|
|
55
|
+
Examples
|
|
56
|
+
--------
|
|
57
|
+
>>> # Case 1: 1-point observables (lists of length 1)
|
|
58
|
+
>>> operator_1 = SparseOccupationOperators(
|
|
59
|
+
... operators=[[("Nup", 3)], [("Ndn", 7)]],
|
|
60
|
+
... coefficients=[+1/4, -4/5]
|
|
61
|
+
... )
|
|
62
|
+
|
|
63
|
+
>>> # Case 2: Mixed multi-point and 1-point observables
|
|
64
|
+
>>> operator_2 = SparseOccupationOperators(
|
|
65
|
+
... operators=[[("Nup", 3)], [("Ndn", 7), ("Nup", 9), ("Nup", 4)]],
|
|
66
|
+
... coefficients=[+1.0, -1.0]
|
|
67
|
+
... )
|
|
68
|
+
"""
|
|
69
|
+
|
|
70
|
+
operators: list[Operator]
|
|
71
|
+
coefficients: list[float]
|
|
72
|
+
|
|
73
|
+
def __post_init__(self):
|
|
74
|
+
if len(self.operators) != len(self.coefficients):
|
|
75
|
+
raise ValueError(
|
|
76
|
+
f"Length mismatch: 'operators' has {len(self.operators)} elements, "
|
|
77
|
+
f"but 'coefficients' has {len(self.coefficients)} elements.",
|
|
78
|
+
)
|
|
79
|
+
|
|
80
|
+
for i, coefficient in enumerate(self.coefficients):
|
|
81
|
+
if not isinstance(coefficient, int | float):
|
|
82
|
+
raise TypeError(
|
|
83
|
+
f"Coefficient at index {i} must be a float or int. "
|
|
84
|
+
f"Got: {type(coefficient).__name__}",
|
|
85
|
+
)
|
|
86
|
+
|
|
87
|
+
for i, operator in enumerate(self.operators):
|
|
88
|
+
# Enforce that every term is a list
|
|
89
|
+
if not isinstance(operator, list):
|
|
90
|
+
raise TypeError(
|
|
91
|
+
f"Operator at index {i} must be a list of tuples. "
|
|
92
|
+
f"Got: {type(operator).__name__}",
|
|
93
|
+
)
|
|
94
|
+
|
|
95
|
+
if len(operator) == 0:
|
|
96
|
+
raise ValueError(f"Operator list at index {i} cannot be empty.")
|
|
97
|
+
|
|
98
|
+
for component in operator:
|
|
99
|
+
if not isinstance(component, tuple):
|
|
100
|
+
raise TypeError(
|
|
101
|
+
f"Expected tuple for component in operator list at index {i}, "
|
|
102
|
+
f"got: {type(component).__name__}",
|
|
103
|
+
)
|
|
104
|
+
self._validate_term_component(component, index=i)
|
|
105
|
+
|
|
106
|
+
def _validate_term_component(self, component: tuple, index: int):
|
|
107
|
+
"""
|
|
108
|
+
Helper method to validate a single (spin, site) tuple.
|
|
109
|
+
|
|
110
|
+
Parameters
|
|
111
|
+
----------
|
|
112
|
+
component : tuple
|
|
113
|
+
A tuple representing a single operator component (spin, site).
|
|
114
|
+
index : int
|
|
115
|
+
The index of the operator in the operators list for error reporting.
|
|
116
|
+
|
|
117
|
+
Raises
|
|
118
|
+
------
|
|
119
|
+
ValueError
|
|
120
|
+
If the component does not have exactly 2 elements or if the spin is invalid.
|
|
121
|
+
TypeError
|
|
122
|
+
If the spin is not a string or the site is not an integer.
|
|
123
|
+
"""
|
|
124
|
+
if len(component) != _COMPONENT_LENGTH:
|
|
125
|
+
raise ValueError(
|
|
126
|
+
f"Operator component at index {index} must be a 2-tuple (spin, site). "
|
|
127
|
+
f"Got: {component}",
|
|
128
|
+
)
|
|
129
|
+
|
|
130
|
+
spin, site = component
|
|
131
|
+
if spin not in _VALID_SPINS:
|
|
132
|
+
raise ValueError(
|
|
133
|
+
f"Spin in operator at index {index} must be one of {_VALID_SPINS}. "
|
|
134
|
+
f"Got: '{spin}'",
|
|
135
|
+
)
|
|
136
|
+
|
|
137
|
+
if not isinstance(site, int):
|
|
138
|
+
raise TypeError(
|
|
139
|
+
f"Site in operator at index {index} must be an integer. Got: {type(site).__name__}",
|
|
140
|
+
)
|
|
141
|
+
if site < 0:
|
|
142
|
+
raise ValueError(
|
|
143
|
+
f"Site in operator at index {index} must be a non-negative integer. Got: {site}",
|
|
144
|
+
)
|
|
145
|
+
|
|
146
|
+
def to_dict(self) -> dict[str, Any]:
|
|
147
|
+
"""
|
|
148
|
+
Convert the SparseOccupationOperators instance to a dictionary representation.
|
|
149
|
+
|
|
150
|
+
Returns
|
|
151
|
+
-------
|
|
152
|
+
dict[str, Any]
|
|
153
|
+
A dictionary containing 'operators' and 'coefficients'.
|
|
154
|
+
"""
|
|
155
|
+
return asdict(self)
|
|
156
|
+
|
|
157
|
+
@classmethod
|
|
158
|
+
def from_dict(cls, data: dict[str, Any]) -> "SparseOccupationOperators":
|
|
159
|
+
"""
|
|
160
|
+
Create a SparseOccupationOperators instance from a dictionary.
|
|
161
|
+
|
|
162
|
+
Safely handles cases where tuple inner-components may have been
|
|
163
|
+
converted to lists (e.g., from JSON deserialization).
|
|
164
|
+
|
|
165
|
+
Parameters
|
|
166
|
+
----------
|
|
167
|
+
data : dict[str, Any]
|
|
168
|
+
A dictionary containing 'operators' and 'coefficients' keys.
|
|
169
|
+
|
|
170
|
+
Returns
|
|
171
|
+
-------
|
|
172
|
+
SparseOccupationOperators
|
|
173
|
+
A newly initialized instance of the class.
|
|
174
|
+
"""
|
|
175
|
+
parsed_operators = []
|
|
176
|
+
|
|
177
|
+
for operator in data.get("operators", []):
|
|
178
|
+
if isinstance(operator, list):
|
|
179
|
+
reconstructed_term = []
|
|
180
|
+
for component in operator:
|
|
181
|
+
if isinstance(component, list):
|
|
182
|
+
reconstructed_term.append(tuple(component))
|
|
183
|
+
else:
|
|
184
|
+
reconstructed_term.append(
|
|
185
|
+
component,
|
|
186
|
+
)
|
|
187
|
+
parsed_operators.append(reconstructed_term)
|
|
188
|
+
else:
|
|
189
|
+
# Leave invalid outer formats as-is
|
|
190
|
+
parsed_operators.append(operator)
|
|
191
|
+
|
|
192
|
+
return cls(
|
|
193
|
+
operators=parsed_operators,
|
|
194
|
+
coefficients=data.get("coefficients", []),
|
|
195
|
+
)
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|