Deprecate Array class (#343)

docs/tutorials/optimizing_pulse_sequence.rst

@@ -254,10 +254,6 @@ entry on :ref:`JAX-compatible pulse schedules <how-to use pulse schedules for ja
 
 .. jupyter-execute::
 
-    # how to get rid of this?
-    from qiskit_dynamics.array import Array
-    Array.set_default_backend("jax")
-
     import sympy as sym
     from qiskit import pulse
 

qiskit_dynamics/array/__init__.py

@@ -19,6 +19,17 @@
 
 .. currentmodule:: qiskit_dynamics.array
 
+
+.. warning::
+
+    The ``array`` and ``dispatch`` submodules of Qiskit Dynamics have been deprecated as of version
+    0.5.0. The use of the ``Array`` class is no longer required to work with different array
+    libraries in Qiskit Dynamics, and is broken in some cases. Refer to the :ref:`user guide entry
+    on using different array libraries with Qiskit Dynamics <how-to use different array libraries>`.
+    Users can now work directly with the supported array type of their choice, without the need to
+    wrap them to enable dispatching. The ``array`` and ``dispatch`` submodules will be removed in
+    version 0.6.0.
+
 This module contains an :class:`Array` class that wraps N-dimensional array objects from different
 libraries. It enables working with different array libraries through a common NumPy-based interface,
 along with other functionality for writing array-library agnostic code.
@@ -41,6 +52,13 @@
 Basic Usage
 -----------
 
+.. jupyter-execute::
+    :hide-code:
+    
+    # suppress deprecation warnings
+    import warnings
+    warnings.simplefilter('ignore', category=DeprecationWarning)
+
 When using the default ``numpy`` backend :class:`Array`, objects can be used interchangably with
 ``numpy.ndarray``. When ``numpy`` functions are applied to an :class:`Array` object the return type
 will be an :class:`Array` instead of an ``numpy.ndarray``.

qiskit_dynamics/array/array.py

@@ -9,9 +9,11 @@
 # Any modifications or derivative works of this code must retain this
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
+# pylint: disable=invalid-name,global-statement
 
 """Array Class"""
 
+import warnings
 import copy
 from functools import wraps
 from types import BuiltinMethodType, MethodType
@@ -25,9 +27,29 @@
 
 __all__ = ["Array"]
 
+_deprecation_raised = False
+
+
+def _array_deprecation_warn():
+    global _deprecation_raised
+    if not _deprecation_raised:
+        warnings.warn(
+            """The array and dispatch submodules of Qiskit Dynamics have been deprecated as of
+            version 0.5.0. The use of the Array class is no longer required to work with different
+            array libraries in Qiskit Dynamics, and is broken in some cases. Refer to the user guide
+            entry on using different array libraries with Qiskit Dynamics. Users can now work
+            directly with the supported array type of their choice, without the need to wrap them to
+            enable dispatching. The array and dispatch submodules will be removed in version 0.6.0.
+            """,
+            DeprecationWarning,
+            stacklevel=3,
+        )
+        _deprecation_raised = True
+
 
 class Array(NDArrayOperatorsMixin):
-    """Qiskit array class.
+    """Qiskit array class. This class is deprecated as of version 0.5.0 and will be removed in
+    version 0.6.0.
 
     This class provides a Numpy compatible wrapper to supported Python array libraries. Supported
     backends are ``"numpy"`` and ``"jax"``.
@@ -55,7 +77,7 @@ def __init__(
         Raises:
             ValueError: If input cannot be converted to an :class:`Array`.
         """
-
+        _array_deprecation_warn()
         # Check if we can override setattr and
         # set _data and _backend directly
         if (
@@ -108,18 +130,21 @@ def backend(self, value: str):
     @classmethod
     def set_default_backend(cls, backend: Union[str, None]):
         """Set the default array backend."""
+        _array_deprecation_warn()
         if backend is not None:
             Dispatch.validate_backend(backend)
         Dispatch.DEFAULT_BACKEND = backend
 
     @classmethod
     def default_backend(cls) -> str:
         """Return the default array backend."""
+        _array_deprecation_warn()
         return Dispatch.DEFAULT_BACKEND
 
     @classmethod
     def available_backends(cls) -> Set[str]:
         """Return a tuple of available array backends."""
+        _array_deprecation_warn()
         return Dispatch.REGISTERED_BACKENDS
 
     def __repr__(self):

qiskit_dynamics/dispatch/__init__.py

@@ -19,8 +19,18 @@
 
 .. currentmodule:: qiskit_dynamics.dispatch
 
-This module contains dispatch methods used by the
-:class:`~qiskit_dynamics.array.Array` class.
+.. warning::
+
+    The ``array`` and ``dispatch`` submodules of Qiskit Dynamics have been deprecated as of version
+    0.5.0. The use of the ``Array`` class is no longer required to work with different array
+    libraries in Qiskit Dynamics, and is broken in some cases. Refer to the :ref:`user guide entry
+    on using different array libraries with Qiskit Dynamics <how-to use different array libraries>`.
+    Users can now work directly with the supported array type of their choice, without the need to
+    wrap them to enable dispatching. The ``array`` and ``dispatch`` submodules will be removed in
+    version 0.6.0.
+
+
+This module contains dispatch methods used by the :class:`~qiskit_dynamics.array.Array` class.
 
 
 Dispatch Functions

releasenotes/notes/dispatch-array-deprecation-fb945946caba447a.yaml

@@ -0,0 +1,10 @@
+---
+upgrade:
+  - |
+    The ``array`` and ``dispatch`` submodules of Qiskit Dynamics have been deprecated as of version
+    0.5.0. The use of the ``Array`` class is no longer required to work with different array
+    libraries in Qiskit Dynamics, and is broken in some cases. Refer to the :ref:`user guide entry
+    on using different array libraries with Qiskit Dynamics <how-to use different array libraries>`.
+    Users can now work directly with the supported array type of their choice, without the need to
+    wrap them to enable dispatching. The ``array`` and ``dispatch`` submodules will be removed in
+    version 0.6.0.