:py:mod:`pygsti.baseobjs.statespace` ==================================== .. py:module:: pygsti.baseobjs.statespace .. autoapi-nested-parse:: Defines OrderedDict-derived classes used to store specific pyGSTi objects Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: pygsti.baseobjs.statespace.StateSpace pygsti.baseobjs.statespace.QuditSpace pygsti.baseobjs.statespace.QubitSpace pygsti.baseobjs.statespace.ExplicitStateSpace Functions ~~~~~~~~~ .. autoapisummary:: pygsti.baseobjs.statespace.default_space_for_dim pygsti.baseobjs.statespace.default_space_for_udim pygsti.baseobjs.statespace.default_space_for_num_qubits .. py:class:: StateSpace Bases: :py:obj:`pygsti.baseobjs.nicelyserializable.NicelySerializable` Base class for defining a state space (Hilbert or Hilbert-Schmidt space). This base class just sets the API for a "state space" in pyGSTi, accessed as the direct sum of one or more tensor products of Hilbert spaces. .. py:property:: udim :abstractmethod: Integer Hilbert (unitary operator) space dimension of this quantum state space. Raises an error if this space is *not* a quantum state space. .. py:property:: dim :abstractmethod: Integer Hilbert-Schmidt (super-operator) or classical dimension of this state space. .. py:property:: num_qubits :abstractmethod: The number of qubits in this quantum state space. Raises a ValueError if this state space doesn't consist entirely of qubits. .. py:property:: num_qudits :abstractmethod: The number of qudits in this quantum state space. Raises a ValueError if this state space doesn't consist entirely of qudits. .. py:property:: num_tensor_product_blocks :abstractmethod: The number of tensor-product blocks which are direct-summed to get the final state space. Returns ------- int .. py:property:: sole_tensor_product_block_labels The labels of the first and only tensor product block within this state space. If there are multiple blocks, a ValueError is raised. .. py:property:: tensor_product_blocks_labels :abstractmethod: The labels for all the tensor-product blocks. Returns ------- tuple of tuples .. py:property:: tensor_product_blocks_dimensions :abstractmethod: The superoperator dimensions for all the tensor-product blocks. Returns ------- tuple of tuples .. py:property:: tensor_product_blocks_udimensions :abstractmethod: The unitary operator dimensions for all the tensor-product blocks. Returns ------- tuple of tuples .. py:property:: tensor_product_blocks_types :abstractmethod: The type (quantum vs classical) of all the tensor-product blocks. Returns ------- tuple of tuples .. py:property:: is_entirely_qubits Whether this state space is just the tensor product of qubit subspaces. Returns ------- bool .. py:property:: common_dimension Returns the common super-op dimension of all the labels in this space. If not all the labels in this space have the same dimension, then `None` is returned to indicate this. This property is useful when working with stencils, where operations are created for a "stencil space" that is not exactly a subspace of a StateSpace space but will be mapped to one in the future. Returns ------- int or None .. py:property:: common_udimension Returns the common unitary-op dimension of all the labels in this space. If not all the labels in this space have the same dimension, then `None` is returned to indicate this. This property is useful when working with stencils, where operations are created for a "stencil space" that is not exactly a subspace of a StateSpace space but will be mapped to one in the future. Returns ------- int or None .. py:property:: state_space_labels Return a tuple corresponding to the concatenation of the constituent state space labels within each tensor product block of this `StateSpace` object. Returns ------- flattened_state_space_label_list : tuple A tuple containing a flattened list of all of the state space labels appearing within the tensor product blocks of this `StateSpace` objects label list. .. py:method:: cast(obj) :classmethod: Casts `obj` into a :class:`StateSpace` object if possible. If `obj` is already of this type, it is simply returned without modification. Parameters ---------- obj : StateSpace or int or list Either an already-built state space object or an integer specifying the number of qubits, or a list of labels as would be provided to the first argument of :meth:`ExplicitStateSpace.__init__`. Returns ------- StateSpace .. py:method:: label_dimension(label) :abstractmethod: The superoperator dimension of the given label (from any tensor product block) Parameters ---------- label : str or int The label whose dimension should be retrieved. Returns ------- int .. py:method:: label_udimension(label) :abstractmethod: The unitary operator dimension of the given label (from any tensor product block) Parameters ---------- label : str or int The label whose dimension should be retrieved. Returns ------- int .. py:method:: label_tensor_product_block_index(label) :abstractmethod: The index of the tensor product block containing the given label. Parameters ---------- label : str or int The label whose index should be retrieved. Returns ------- int .. py:method:: label_type(label) :abstractmethod: The type (quantum or classical) of the given label (from any tensor product block). Parameters ---------- label : str or int The label whose type should be retrieved. Returns ------- str .. py:method:: tensor_product_block_labels(i_tpb) The labels for the `iTBP`-th tensor-product block. Parameters ---------- i_tpb : int Tensor-product block index. Returns ------- tuple .. py:method:: tensor_product_block_dimensions(i_tpb) The superoperator dimensions for the factors in the `iTBP`-th tensor-product block. Parameters ---------- i_tpb : int Tensor-product block index. Returns ------- tuple .. py:method:: tensor_product_block_udimensions(i_tpb) The unitary-operator dimensions for the factors in the `iTBP`-th tensor-product block. Parameters ---------- i_tpb : int Tensor-product block index. Returns ------- tuple .. py:method:: copy() Return a copy of this StateSpace. Returns ------- StateSpace .. py:method:: is_compatible_with(other_state_space) Whether another state space is compatible with this one. Two state spaces are considered "compatible" when their overall dimensions agree (even if their tensor product block structure and labels do not). (This checks whether the Hilbert spaces are isomorphic.) Parameters ---------- other_state_space : StateSpace The state space to check compatibility with. Returns ------- bool .. py:method:: is_entire_space(labels) True if this state space is a single tensor product block with (exactly, in order) the given set of labels. Parameters ---------- labels : iterable the labels to test. Returns ------- bool .. py:method:: contains_labels(labels) True if this state space contains all of a given set of labels. Parameters ---------- labels : iterable the labels to test. Returns ------- bool .. py:method:: contains_label(label) True if this state space contains a given label. Parameters ---------- label : str or int the label to test for. Returns ------- bool .. py:method:: create_subspace(labels) Create a sub-`StateSpace` object from a set of existing labels. Parameters ---------- labels : iterable The labels to include in the returned state space. Returns ------- StateSpace .. py:method:: intersection(other_state_space) Create a state space whose labels are the intersection of the labels of this space and one other. Dimensions associated with the labels are preserved, as is the ordering of tensor product blocks. If the two spaces have the same label, but their dimensions or indices do not agree, an error is raised. Parameters ---------- other_state_space : StateSpace The other state space. Returns ------- StateSpace .. py:method:: union(other_state_space) Create a state space whose labels are the union of the labels of this space and one other. Dimensions associated with the labels are preserved, as is the tensor product block index. If the two spaces have the same label, but their dimensions or indices do not agree, an error is raised. Parameters ---------- other_state_space : StateSpace The other state space. Returns ------- StateSpace .. py:method:: difference(other_state_space) Create a state space whose labels are the difference of the labels of this space and one other. I.e. a state space containing the labels of this space which don't appear in the other. Dimensions associated with the labels are preserved, as is the tensor product block index. If the two spaces have the same label, but their dimensions or indices do not agree, an error is raised. Parameters ---------- other_state_space : StateSpace The other state space. Returns ------- StateSpace .. py:method:: create_stencil_subspace(labels) Create a template sub-`StateSpace` object from a set of potentially stencil-type labels. That is, the elements of `labels` don't need to actually exist within this state space -- they may be stencil labels that will resolve to a label in this state space later on. Parameters ---------- labels : iterable The labels to include in the returned state space. Returns ------- StateSpace .. py:class:: QuditSpace(nqudits_or_labels, udim_or_udims) Bases: :py:obj:`StateSpace` A state space consisting of N qudits. .. py:property:: qudit_labels The labels of the qudits in this state space. .. py:property:: qudit_udims Integer Hilbert (unitary operator) space dimensions of the qudits in ths quantum state space. .. py:property:: udim Integer Hilbert (unitary operator) space dimension of this quantum state space. .. py:property:: dim Integer Hilbert-Schmidt (super-operator) or classical dimension of this state space. .. py:property:: num_qudits The number of qubits in this quantum state space. .. py:property:: num_tensor_product_blocks Get the number of tensor-product blocks which are direct-summed to get the final state space. Returns ------- int .. py:property:: tensor_product_blocks_labels Get the labels for all the tensor-product blocks. Returns ------- tuple of tuples .. py:property:: tensor_product_blocks_dimensions Get the superoperator dimensions for all the tensor-product blocks. Returns ------- tuple of tuples .. py:property:: tensor_product_blocks_udimensions Get the unitary operator dimensions for all the tensor-product blocks. Returns ------- tuple of tuples .. py:property:: tensor_product_blocks_types Get the type (quantum vs classical) of all the tensor-product blocks. Returns ------- tuple of tuples .. py:method:: label_dimension(label) The superoperator dimension of the given label (from any tensor product block) Parameters ---------- label : str or int The label whose dimension should be retrieved. Returns ------- int .. py:method:: label_udimension(label) The unitary operator dimension of the given label (from any tensor product block) Parameters ---------- label : str or int The label whose dimension should be retrieved. Returns ------- int .. py:method:: label_tensor_product_block_index(label) The index of the tensor product block containing the given label. Parameters ---------- label : str or int The label whose index should be retrieved. Returns ------- int .. py:method:: label_type(label) The type (quantum or classical) of the given label (from any tensor product block). Parameters ---------- label : str or int The label whose type should be retrieved. Returns ------- str .. py:class:: QubitSpace(nqubits_or_labels) Bases: :py:obj:`QuditSpace` A state space consisting of N qubits. .. py:property:: udim Integer Hilbert (unitary operator) space dimension of this quantum state space. .. py:property:: dim Integer Hilbert-Schmidt (super-operator) or classical dimension of this state space. .. py:property:: qubit_labels The labels of the qubits .. py:property:: num_qubits The number of qubits in this quantum state space. .. py:property:: num_tensor_product_blocks Get the number of tensor-product blocks which are direct-summed to get the final state space. Returns ------- int .. py:property:: tensor_product_blocks_labels Get the labels for all the tensor-product blocks. Returns ------- tuple of tuples .. py:property:: tensor_product_blocks_dimensions Get the superoperator dimensions for all the tensor-product blocks. Returns ------- tuple of tuples .. py:property:: tensor_product_blocks_udimensions Get the unitary operator dimensions for all the tensor-product blocks. Returns ------- tuple of tuples .. py:property:: tensor_product_blocks_types Get the type (quantum vs classical) of all the tensor-product blocks. Returns ------- tuple of tuples .. py:method:: label_dimension(label) The superoperator dimension of the given label (from any tensor product block) Parameters ---------- label : str or int The label whose dimension should be retrieved. Returns ------- int .. py:method:: label_udimension(label) The unitary operator dimension of the given label (from any tensor product block) Parameters ---------- label : str or int The label whose dimension should be retrieved. Returns ------- int .. py:method:: label_tensor_product_block_index(label) The index of the tensor product block containing the given label. Parameters ---------- label : str or int The label whose index should be retrieved. Returns ------- int .. py:method:: label_type(label) The type (quantum or classical) of the given label (from any tensor product block). Parameters ---------- label : str or int The label whose type should be retrieved. Returns ------- str .. py:class:: ExplicitStateSpace(label_list, udims=None, types=None) Bases: :py:obj:`StateSpace` A customizable definition of a state space. An ExplicitStateSpace object describes, using string/int labels, how an entire Hilbert state space is decomposed into the direct sum of terms which themselves are tensor products of smaller (typically qubit-sized) Hilbert spaces. Parameters ---------- label_list : str or int or iterable Most generally, this can be a list of tuples, where each tuple contains the state-space labels (which can be strings or integers) for a single "tensor product block" formed by taking the tensor product of the spaces asociated with the labels. The full state space is the direct sum of all the tensor product blocks. E.g. `[('Q0','Q1'), ('Q2',)]`. If just an iterable of labels is given, e.g. `('Q0','Q1')`, it is assumed to specify the first and only tensor product block. If a single state space label is given, e.g. `'Q2'`, then it is assumed to completely specify the first and only tensor product block. udims : int or iterable, optional The dimension of each state space label as an integer, tuple of integers, or list or tuples of integers to match the structure of `label_list`. e.g., if `label_list=('Q0','Q1')` then `udims` should be a tuple of 2 integers, or if label_list='Q0' then `udims` should be an integer. Values specify unitary evolution state-space dimensions, i.e. 2 for a qubit, 3 for a qutrit, etc. If None, then the dimensions are inferred, if possible, from the following naming rules: - if the label starts with 'L', udim=1 (a single Level) - if the label starts with 'Q' OR is an int, udim=2 (a Qubit) - if the label starts with 'T', udim=3 (a quTrit) types : str or iterable, optional A list of label types, either `'Q'` or `'C'` for "quantum" and "classical" respectively, indicating the type of state-space associated with each label. Like `dims`, `types` must match the structure of `label_list`. A quantum state space of dimension `d` is a `d`-by-`d` density matrix, whereas a classical state space of dimension d is a vector of `d` probabilities. If `None`, then all labels are assumed to be quantum. .. py:property:: labels The labels for all the tensor-product blocks. Returns ------- tuple of tuples .. py:property:: udim Integer Hilbert (unitary operator) space dimension of this quantum state space. Raises an error if this space is *not* a quantum state space. .. py:property:: dim Integer Hilbert-Schmidt (super-operator) or classical dimension of this state space. .. py:property:: num_qubits The number of qubits in this quantum state space. Raises a ValueError if this state space doesn't consist entirely of qubits. .. py:property:: num_qudits The number of qudits in this quantum state space. Raises a ValueError if this state space doesn't consist entirely of qudits. .. py:property:: num_tensor_product_blocks The number of tensor-product blocks which are direct-summed to get the final state space. Returns ------- int .. py:property:: tensor_product_blocks_labels The labels for all the tensor-product blocks. Returns ------- tuple of tuples .. py:property:: tensor_product_blocks_dimensions The superoperator dimensions for all the tensor-product blocks. Returns ------- tuple of tuples .. py:property:: tensor_product_blocks_udimensions The unitary operator dimensions for all the tensor-product blocks. Returns ------- tuple of tuples .. py:property:: tensor_product_blocks_types The type (quantum vs classical) of all the tensor-product blocks. Returns ------- tuple of tuples .. py:attribute:: label_types .. py:attribute:: label_udims .. py:attribute:: label_dims .. py:attribute:: tpb_index .. py:attribute:: tpb_dims :value: '[]' .. py:attribute:: tpb_udims :value: '[]' .. py:method:: label_dimension(label) The superoperator dimension of the given label (from any tensor product block) Parameters ---------- label : str or int The label whose dimension should be retrieved. Returns ------- int .. py:method:: label_udimension(label) The unitary operator dimension of the given label (from any tensor product block) Parameters ---------- label : str or int The label whose dimension should be retrieved. Returns ------- int .. py:method:: label_tensor_product_block_index(label) The index of the tensor product block containing the given label. Parameters ---------- label : str or int The label whose index should be retrieved. Returns ------- int .. py:method:: label_type(label) The type (quantum or classical) of the given label (from any tensor product block). Parameters ---------- label : str or int The label whose type should be retrieved. Returns ------- str .. py:function:: default_space_for_dim(dim) Create a state space for a given superoperator dimension. Parameters ---------- dim : int The dimension. Returns ------- StateSpace .. py:function:: default_space_for_udim(udim) Create a state space for a given unitary operator dimension. Parameters ---------- dim : int The dimension. Returns ------- StateSpace .. py:function:: default_space_for_num_qubits(num_qubits) Create a state space for a given number of qubits. Parameters ---------- num_qubits : int The number of qubits. Returns ------- QubitStateSpace