structure
=========

.. py:module:: quantify_scheduler.structure 

.. autoapi-nested-parse::

   Validated and serializable data structures using :mod:`pydantic`.

   In this module we provide :class:`pre-configured Pydantic model <.DataStructure>` and
   :mod:`custom field types <.types>` that allow serialization of typical data objects
   that we frequently use in ``quantify-scheduler``, like functions and arrays.



Submodules
----------
.. toctree::
   :titlesonly:
   :maxdepth: 1

   model/index.rst
   types/index.rst


Package Contents
----------------

Classes
~~~~~~~

.. autoapisummary::

   quantify_scheduler.structure.DataStructure
   quantify_scheduler.structure.Graph
   quantify_scheduler.structure.NDArray




.. py:class:: DataStructure(/, **data: Any)

   Bases: :py:obj:`pydantic.BaseModel`


   A parent for all data structures.

   Data attributes are generated from the class' type annotations, similarly to
   `dataclasses <https://docs.python.org/3/library/dataclasses.html>`_. If data
   attributes are JSON-serializable, data structure can be serialized using
   ``json()`` method. This string can be deserialized using ``parse_raw()`` classmethod
   of a correspondent child class.

   If required, data fields can be validated, see examples for more information.
   It is also possible to define custom field types with advanced validation.

   This class is a pre-configured `pydantic <https://docs.pydantic.dev/>`_
   model. See its documentation for details of usage information.

   .. admonition:: Examples
       :class: dropdown

       .. include:: /examples/structure.DataStructure.rst


   .. py:attribute:: model_config

      Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict].


.. py:class:: Graph(incoming_graph_data=None, **attr)

   Bases: :py:obj:`networkx.Graph`


   Pydantic-compatible version of :class:`networkx.Graph`.


   .. py:method:: validate(v: Any) -> Graph
      :classmethod:


      Validate the data and cast from all known representations.



.. py:class:: NDArray(shape, dtype=float, buffer=None, offset=0, strides=None, order=None)

   Bases: :py:obj:`numpy.ndarray`


   Pydantic-compatible version of :class:`numpy.ndarray`.

   Serialization is implemented using custom methods :meth:`.to_dict` and
   :meth:`.from_dict`. Data array is encoded in Base64.


   .. py:method:: to_dict() -> dict[str, Any]

      Convert the array to JSON-compatible dictionary.



   .. py:method:: from_dict(serialized: collections.abc.Mapping[str, Any]) -> NDArray
      :classmethod:


      Construct an instance from a dictionary generated by :meth`to_dict`.

      :param serialized: Dictionary that has ``"data"``, ``"shape"`` and ``"dtype"`` keys.",
                         where data is a base64-encoded bytes array, shape is a tuple and dtype is
                         a string representation of a Numpy data type.



   .. py:method:: validate(v: Any) -> NDArray
      :classmethod:


      Validate the data and cast from all known representations.