Merge pull request #42 from bqth29/v1.2.1

V1.2.1

CITATION.cff

@@ -9,6 +9,6 @@ authors:
 - family-names: Pugliese
   given-names: Lorenzo
 title: "Simulated Bifurcation (SB) algorithm for Python"
-version: 1.2.0
+version: 1.2.1
 date-released: 2023-08-11
 url: "https://github.com/bqth29/simulated-bifurcation-algorithm"

README.md

@@ -70,7 +70,7 @@ This can also be seen as the sum of a quadratic form, a linear form and a consta
 
 The `minimize` and `maximize` functions allow to respectively minimize and maximize the value of such polynomials for a given type of input values, relying on the SB algorithm. They both return the optimal polynomial value found by the SB algorithm, along with its associated input vector.
 
-The input types must be passed to the `input_type` argument:
+The input types must be passed to the `domain` argument:
 
 - `spin` (default value) for a spin optimization: the optimal vector will only have ±1 values
 - `binary` for a binary optimization: the optimal vector will only have 0 or 1 values
@@ -92,26 +92,26 @@ constant = 2.0
 
 ```python
 # Spin minimization
-spin_value, spin_vector = sb.minimize(matrix, vector, constant, input_type='spin')
+spin_value, spin_vector = sb.minimize(matrix, vector, constant, domain='spin')
 
 # Binary minimization
-binary_value, binary_vector = sb.minimize(matrix, vector, constant, input_type='binary')
+binary_value, binary_vector = sb.minimize(matrix, vector, constant, domain='binary')
 
 # 3-bits integer minimization
-int_value, int_vector = sb.minimize(matrix, vector, constant, input_type='int3')
+int_value, int_vector = sb.minimize(matrix, vector, constant, domain='int3')
 ```
 
 #### Maximization
 
 ```python
 # Spin maximization
-spin_value, spin_vector = sb.maximize(matrix, vector, constant, input_type='spin')
+spin_value, spin_vector = sb.maximize(matrix, vector, constant, domain='spin')
 
 # Binary maximization
-binary_value, binary_vector = sb.maximize(matrix, vector, constant, input_type='binary')
+binary_value, binary_vector = sb.maximize(matrix, vector, constant, domain='binary')
 
 # 10-bits integer maximization
-int_value, int_vector = sb.maximize(matrix, vector, constant, input_type='int10')
+int_value, int_vector = sb.maximize(matrix, vector, constant, domain='int10')
 ```
 
 > For both functions, only the matrix is required, the vector and constant terms are optional.
@@ -266,7 +266,7 @@ If you are using this code for your own projects please cite our work:
     month = aug,
     title = {{Simulated Bifurcation (SB) algorithm for Python}},
     url = {https://github.com/bqth29/simulated-bifurcation-algorithm},
-    version = {1.2.0},
+    version = {1.2.1},
     year = {2023},
 }
 ```

setup.py

@@ -5,7 +5,7 @@
 
 
 # !MDC{set}{package_version = "{version}"}
-package_version = "1.2.1.dev0"
+package_version = "1.2.1"
 
 
 dependencies = [

src/simulated_bifurcation/__init__.py

@@ -35,18 +35,28 @@
 Code snippets are indicated by three greater-than signs:
 
   >>> x = 42
-  >>> x = x + 1
+  >>> x += 1
 
 .. deprecated:: 1.2.1
-    `BinaryPolynomial` will be modified in simulated-bifurcation 1.3.0, it
-    is replaced by `BinaryQuadraticPolynomial` in prevision of the addition
-    of multivariate polynomials of an arbitrary degree.
-    `IntegerPolynomial` will be modified in simulated-bifurcation 1.3.0, it
-    is replaced by `IntegerQuadraticPolynomial` in prevision of the
-    addition of multivariate polynomials of an arbitrary degree.
-    `SpinPolynomial` will be modified in simulated-bifurcation 1.3.0, it is
-    replaced by `SpinQuadraticPolynomial` in prevision of the addition of
-    multivariate polynomials of an arbitrary degree.
+    The functions `sb.optimize`, `sb.minimize`, and `sb.maximize` will be
+    modified in simulated-bifurcation 1.3.0. The `matrix`, `vector`, and
+    `constant` parameters will become positional-only parameters; the other
+    parameters will become keyword-only parameters.
+
+    In simulated-bifurcation 1.3.0, parameters `input_type` will be
+    removed. Use `domain` instead.
+
+    `BinaryPolynomial`, `BinaryQuadraticPolynomial`, `IntegerPolynomial`,
+    `IntegerQuadraticPolynomial`, `SpinPolynomial`, and
+    `SpinQuadraticPolynomial` will be removed in simulated-bifurcation
+    1.3.0.  From version 1.3.0 onwards, polynomials will no longer have a
+    definition domain. The domain only needs to be specified when creating
+    an Ising model, and conversely when converting spins back into the
+    original domain.
+
+    `BaseMultivariateQuadraticPolynomial` and `IsingPolynomialInterface`
+    will be removed in simulated-bifurcation 1.3.0. They are replaced by
+    `QuadraticPolynomial`.
 
 Notes
 -----
@@ -168,4 +178,4 @@
 
 
 # !MDC{set}{__version__ = "{version}"}
-__version__ = "1.2.1.dev0"
+__version__ = "1.2.1"

src/simulated_bifurcation/models/ising.py

@@ -24,6 +24,8 @@ def __init__(
         dtype: Optional[torch.dtype] = None,
         device: Optional[Union[str, torch.device]] = None,
     ) -> None:
-        super().__init__(-0.5 * J, h, None, dtype, device)
+        super().__init__(
+            -0.5 * J, h, None, dtype, device, silence_deprecation_warning=True
+        )
         self.J = J
         self.h = h

src/simulated_bifurcation/models/knapsack.py

@@ -28,7 +28,14 @@ def __init__(
         self.max_weight = max_weight
         matrix = self.__make_matrix(dtype, device)
         vector = self.__make_vector(dtype, device)
-        super().__init__(matrix, vector, self.__make_penalty(), dtype, device)
+        super().__init__(
+            matrix,
+            vector,
+            self.__make_penalty(),
+            dtype,
+            device,
+            silence_deprecation_warning=True,
+        )
 
     @property
     def summary(self) -> Dict[str, Union[int, float, List[int]]]:

src/simulated_bifurcation/models/markowitz.py

@@ -39,7 +39,15 @@ def __init__(
         )
 
         matrix, vector, constant = self.compile_model()
-        super().__init__(matrix, vector, constant, number_of_bits, dtype, device)
+        super().__init__(
+            matrix,
+            vector,
+            constant,
+            number_of_bits,
+            dtype,
+            device,
+            silence_deprecation_warning=True,
+        )
 
     def compile_model(self) -> Tuple[torch.Tensor, torch.Tensor, float]:
         matrix = self.__compile_matrix()

src/simulated_bifurcation/models/number_partitioning.py

@@ -23,7 +23,14 @@ def __init__(
         tensor_numbers = torch.tensor(self.numbers, dtype=dtype, device=device).reshape(
             -1, 1
         )
-        super().__init__(tensor_numbers @ tensor_numbers.t(), None, None, dtype, device)
+        super().__init__(
+            tensor_numbers @ tensor_numbers.t(),
+            None,
+            None,
+            dtype,
+            device,
+            silence_deprecation_warning=True,
+        )
 
     @property
     def partition(self) -> Dict[str, Dict[str, Union[List[int], int, None]]]:

src/simulated_bifurcation/models/qubo.py

@@ -21,5 +21,5 @@ def __init__(
         dtype: Optional[torch.dtype] = None,
         device: Optional[Union[str, torch.device]] = None,
     ) -> None:
-        super().__init__(Q, None, None, dtype, device)
+        super().__init__(Q, None, None, dtype, device, silence_deprecation_warning=True)
         self.Q = self.matrix

src/simulated_bifurcation/polynomial/__init__.py

@@ -2,19 +2,17 @@
 Implementation of multivariate degree 2 polynomials.
 
 .. deprecated:: 1.2.1
-    `IsingPolynomialInterface` will be removed in simulated-bifurcation
-    1.3.0, it is replaced by `BaseMultivariateQuadraticPolynomial` in
-    prevision of the addition of multivariate polynomials of an arbitrary
-    degree.
-    `BinaryPolynomial` will be modified in simulated-bifurcation 1.3.0, it
-    is replaced by `BinaryQuadraticPolynomial` in prevision of the addition
-    of multivariate polynomials of an arbitrary degree.
-    `IntegerPolynomial` will be modified in simulated-bifurcation 1.3.0, it
-    is replaced by `IntegerQuadraticPolynomial` in prevision of the
-    addition of multivariate polynomials of an arbitrary degree.
-    `SpinPolynomial` will be modified in simulated-bifurcation 1.3.0, it is
-    replaced by `SpinQuadraticPolynomial` in prevision of the addition of
-    multivariate polynomials of an arbitrary degree.
+     `BinaryPolynomial`, `BinaryQuadraticPolynomial`, `IntegerPolynomial`,
+    `IntegerQuadraticPolynomial`, `SpinPolynomial`, and
+    `SpinQuadraticPolynomial` will be removed in simulated-bifurcation
+    1.3.0. From version 1.3.0 onwards, polynomials will no longer have a
+    definition domain. The domain only needs to be specified when creating
+    an Ising model, and conversely when converting spins back into the
+    original domain.
+
+    `BaseMultivariateQuadraticPolynomial` and `IsingPolynomialInterface`
+    will be removed in simulated-bifurcation 1.3.0. They are replaced by
+    `QuadraticPolynomial`.
 
 Multivariate degree 2 polynomials are the sum of a quadratic form and a
 linear form plus a constant term:

src/simulated_bifurcation/polynomial/base_multivariate_polynomial.py

@@ -1,9 +1,8 @@
 """
 .. deprecated:: 1.2.1
-    `IsingPolynomialInterface` will be removed in simulated-bifurcation
-    1.3.0, it is replaced by `BaseMultivariateQuadraticPolynomial` in
-    prevision of the addition of multivariate polynomials of an arbitrary
-    degree.
+    `BaseMultivariateQuadraticPolynomial` and `IsingPolynomialInterface`
+    will be removed in simulated-bifurcation 1.3.0. They are replaced by
+    `QuadraticPolynomial`.
 
 """
 
@@ -25,6 +24,10 @@ class BaseMultivariateQuadraticPolynomial(ABC):
     be translated as an equivalent Ising problem to be solved with the
     Simulated Bifurcation algorithm.
 
+    .. deprecated:: 1.2.1
+      `BaseMultivariateQuadraticPolynomial` will be removed in
+      simulated-bifurcation 1.3.0. It is replaced by `QuadraticPolynomial`.
+
     The polynomial is the combination of a quadratic and a linear form plus a
     constant term:
 
@@ -41,6 +44,8 @@ def __init__(
         accepted_values: Union[torch.Tensor, np.ndarray, List[int], None] = None,
         dtype: Optional[torch.dtype] = None,
         device: Optional[Union[str, torch.device]] = None,
+        *,
+        silence_deprecation_warning=False,
     ) -> None:
         """
         Parameters
@@ -66,6 +71,14 @@ def __init__(
             the device on which to perform the computations of the Simulated
             Bifurcation algorithm (default `"cpu"`)
         """
+        if not silence_deprecation_warning:
+            # 2023-11-21, 1.2.1
+            warnings.warn(
+                "`BaseMultivariateQuadraticPolynomial` will be removed in "
+                "simulated-bifurcation 1.3.0. It is replaced by `QuadraticPolynomial`.",
+                DeprecationWarning,
+                stacklevel=3,
+            )
         self.__check_device(device)
         self.__init_matrix(matrix, dtype, device)
         self.__init_vector(vector, dtype, device)
@@ -622,9 +635,7 @@ class IsingPolynomialInterface(BaseMultivariateQuadraticPolynomial, ABC):
     """
     .. deprecated:: 1.2.1
         `IsingPolynomialInterface` will be removed in simulated-bifurcation
-        1.3.0, it is replaced by `BaseMultivariateQuadraticPolynomial` in
-        prevision of the addition of multivariate polynomials of an
-        arbitrary degree.
+        1.3.0, it is replaced by `QuadraticPolynomial`.
 
     """
 
@@ -633,8 +644,8 @@ def __init__(self, *args, **kwargs) -> None:
         warnings.warn(
             "`IsingPolynomialInterface` is deprecated as of simulated-bifurcation "
             "1.2.1, and will be removed in simulated-bifurcation 1.3.0. Please use "
-            "`BaseQuadraticMultivariatePolynomial` instead.",
+            "`QuadraticPolynomial` instead.",
             DeprecationWarning,
             stacklevel=3,
         )
-        super().__init__(*args, **kwargs)
+        super().__init__(*args, **kwargs, silence_deprecation_warning=True)

src/simulated_bifurcation/polynomial/binary_polynomial.py

@@ -2,9 +2,11 @@
 Implementation of multivariate degree 2 polynomials over binary vectors.
 
 .. deprecated:: 1.2.1
-    `BinaryPolynomial` will be modified in simulated-bifurcation 1.3.0, it
-    is replaced by `BinaryQuadraticPolynomial` in prevision of the addition
-    of multivariate polynomials of an arbitrary degree.
+  `BinaryPolynomial` and `BinaryQuadraticPolynomial` will be removed in
+  simulated-bifurcation 1.3.0. From version 1.3.0 onwards, polynomials will
+  no longer have a definition domain. The domain only needs to be specified
+  when creating an Ising model, and conversely when converting spins back
+  into the original domain.
 
 Multivariate degree 2 polynomials are the sum of a quadratic form and a
 linear form plus a constant term:
@@ -48,6 +50,13 @@ class BinaryQuadraticPolynomial(BaseMultivariateQuadraticPolynomial):
     """
     Multivariate degree 2 polynomials over binary vectors.
 
+    .. deprecated:: 1.2.1
+      `BinaryQuadraticPolynomial` will be removed in simulated-bifurcation
+      1.3.0. From version 1.3.0 onwards, polynomials will no longer have a
+      definition domain. The domain only needs to be specified when
+      creating an Ising model, and conversely when converting spins back
+      into the original domain.
+
     Multivariate degree 2 polynomials are the sum of a quadratic form and a
     linear form plus a constant term:
     `ΣΣ Q(i,j)x(i)x(j) + Σ l(i)x(i) + c`
@@ -113,8 +122,30 @@ def __init__(
         constant: Union[float, int, None] = None,
         dtype: Optional[torch.dtype] = None,
         device: Optional[Union[str, torch.device]] = None,
+        *,
+        silence_deprecation_warning=False,
     ) -> None:
-        super().__init__(matrix, vector, constant, [0, 1], dtype, device)
+        if not silence_deprecation_warning:
+            # 2023-11-21, 1.2.1
+            warnings.warn(
+                "`BinaryQuadraticPolynomial` is deprecated as of simulated-bifurcation "
+                "1.2.1, and it will be removed in simulated-bifurcation 1.3.0. "
+                "From version 1.3.0 onwards, polynomials will no longer have a "
+                "definition domain. The domain only needs to be specified when "
+                "creating an Ising model, and conversely when converting spins "
+                "back into the original domain.",
+                DeprecationWarning,
+                stacklevel=3,
+            )
+        super().__init__(
+            matrix,
+            vector,
+            constant,
+            [0, 1],
+            dtype,
+            device,
+            silence_deprecation_warning=True,
+        )
 
     def to_ising(self) -> IsingCore:
         symmetrical_matrix = IsingCore.symmetrize(self.matrix)
@@ -152,19 +183,23 @@ class BinaryPolynomial(BinaryQuadraticPolynomial):
 
     """
     .. deprecated:: 1.2.1
-        `BinaryPolynomial` will be modified in simulated-bifurcation 1.3.0,
-        it is replaced by `BinaryQuadraticPolynomial` in prevision of the
-        addition of multivariate polynomials of an arbitrary degree.
+      `BinaryPolynomial` will be removed in simulated-bifurcation 1.3.0.
+      From version 1.3.0 onwards, polynomials will no longer have a
+      definition domain. The domain only needs to be specified when
+      creating an Ising model, and conversely when converting spins back
+      into the original domain.
 
     """
 
     def __init__(self, *args, **kwargs) -> None:
         # 2023-10-03, 1.2.1
         warnings.warn(
             "`BinaryPolynomial` is deprecated as of simulated-bifurcation 1.2.1, and "
-            "its behaviour will change in simulated-bifurcation 1.3.0. Please use "
-            "`BinaryQuadraticPolynomial` instead.",
+            "it will be removed in simulated-bifurcation 1.3.0. From version 1.3.0 "
+            "onwards, polynomials will no longer have a definition domain. The domain "
+            "only needs to be specified when creating an Ising model, and conversely "
+            "when converting spins back into the original domain.",
             DeprecationWarning,
             stacklevel=3,
         )
-        super().__init__(*args, **kwargs)
+        super().__init__(*args, **kwargs, silence_deprecation_warning=True)