qctrl-commons 25.2.0__tar.gz → 25.3.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.
Files changed (21) hide show
  1. {qctrl_commons-25.2.0 → qctrl_commons-25.3.0}/PKG-INFO +4 -3
  2. {qctrl_commons-25.2.0 → qctrl_commons-25.3.0}/pyproject.toml +4 -3
  3. {qctrl_commons-25.2.0 → qctrl_commons-25.3.0}/qctrlcommons/__init__.py +1 -1
  4. {qctrl_commons-25.2.0 → qctrl_commons-25.3.0}/qctrlcommons/data_types.py +8 -0
  5. {qctrl_commons-25.2.0 → qctrl_commons-25.3.0}/qctrlcommons/serializers.py +2 -0
  6. qctrl_commons-25.3.0/qctrlcommons/sparse_occ_op.py +195 -0
  7. {qctrl_commons-25.2.0 → qctrl_commons-25.3.0}/LICENSE +0 -0
  8. {qctrl_commons-25.2.0 → qctrl_commons-25.3.0}/README.md +0 -0
  9. {qctrl_commons-25.2.0 → qctrl_commons-25.3.0}/qctrlcommons/constants.py +0 -0
  10. {qctrl_commons-25.2.0 → qctrl_commons-25.3.0}/qctrlcommons/core_exceptions.py +0 -0
  11. {qctrl_commons-25.2.0 → qctrl_commons-25.3.0}/qctrlcommons/exceptions.py +0 -0
  12. {qctrl_commons-25.2.0 → qctrl_commons-25.3.0}/qctrlcommons/graph.py +0 -0
  13. {qctrl_commons-25.2.0 → qctrl_commons-25.3.0}/qctrlcommons/node/__init__.py +0 -0
  14. {qctrl_commons-25.2.0 → qctrl_commons-25.3.0}/qctrlcommons/node/base.py +0 -0
  15. {qctrl_commons-25.2.0 → qctrl_commons-25.3.0}/qctrlcommons/node/wrapper.py +0 -0
  16. {qctrl_commons-25.2.0 → qctrl_commons-25.3.0}/qctrlcommons/pauli_operations.py +0 -0
  17. {qctrl_commons-25.2.0 → qctrl_commons-25.3.0}/qctrlcommons/preconditions.py +0 -0
  18. {qctrl_commons-25.2.0 → qctrl_commons-25.3.0}/qctrlcommons/pytest_plugin.py +0 -0
  19. {qctrl_commons-25.2.0 → qctrl_commons-25.3.0}/qctrlcommons/run_options.py +0 -0
  20. {qctrl_commons-25.2.0 → qctrl_commons-25.3.0}/qctrlcommons/simulation_types.py +0 -0
  21. {qctrl_commons-25.2.0 → qctrl_commons-25.3.0}/qctrlcommons/utils.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: qctrl-commons
3
- Version: 25.2.0
3
+ Version: 25.3.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
@@ -27,8 +27,9 @@ Classifier: Topic :: Software Development :: Embedded Systems
27
27
  Classifier: Topic :: System :: Distributed Computing
28
28
  Requires-Dist: graphql-core (>=3.2.1,<3.3.0)
29
29
  Requires-Dist: networkx (>=3.0.0,<4.0.0)
30
- Requires-Dist: numpy (>=2.0.2,<3.0.0) ; python_version >= "3.10" and python_version < "3.13"
31
- Requires-Dist: numpy (>=2.1.0,<3.0.0) ; python_version == "3.13"
30
+ Requires-Dist: numpy (>=2.2.6,<3.0.0) ; python_version == "3.10"
31
+ Requires-Dist: numpy (>=2.4.6,<3.0.0) ; python_version == "3.11"
32
+ Requires-Dist: numpy (>=2.5.1,<3.0.0) ; python_version >= "3.12" and python_version < "3.14"
32
33
  Requires-Dist: scipy (>=1.14.1,<2.0.0) ; python_version == "3.13"
33
34
  Requires-Dist: scipy (>=1.9.3) ; python_version >= "3.10" and python_version < "3.13"
34
35
  Requires-Dist: sympy (>=1.11.1,<2.0.0)
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "qctrl-commons"
3
- version = "25.2.0"
3
+ version = "25.3.0"
4
4
  description = "Q-CTRL Commons"
5
5
  license-files = ["LICENSE"]
6
6
  requires-python = ">=3.10, <3.14"
@@ -64,8 +64,9 @@ packages = [
64
64
  [tool.poetry.dependencies]
65
65
  networkx = ">=3.0.0,<4.0.0"
66
66
  numpy = [
67
- { version = "^2.0.2", python = ">=3.10,<3.13" },
68
- { version = "^2.1.0", python = ">=3.13,<3.14" }
67
+ { version = "^2.2.6", python = ">=3.10,<3.11" },
68
+ { version = "^2.4.6", python = ">=3.11,<3.12" },
69
+ { version = "^2.5.1", python = ">=3.12,<3.14" }
69
70
  ]
70
71
  scipy = [
71
72
  { version = ">=1.9.3", python = ">=3.10,<3.13" },
@@ -13,5 +13,5 @@
13
13
 
14
14
  """qctrlcommons - a collection of common libraries for the Python language"""
15
15
 
16
- __version__ = "25.2.0"
16
+ __version__ = "25.3.0"
17
17
  __author__ = "Q-CTRL <support@q-ctrl.com>"
@@ -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
 
@@ -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