:py:mod:`pygsti.modelmembers.states.tpstate`
============================================

.. py:module:: pygsti.modelmembers.states.tpstate

.. autoapi-nested-parse::

   The TPState class and supporting functionality.






Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   pygsti.modelmembers.states.tpstate.TPState




.. py:class:: TPState(vec, basis=None, evotype='default', state_space=None)


   Bases: :py:obj:`pygsti.modelmembers.states.densestate.DenseState`, :py:obj:`pygsti.modelmembers.torchable.Torchable`

   A fixed-unit-trace state vector.

   This state vector is fully parameterized except for the first element, which
   is frozen to be `1/(d**0.25)`.  This is so that, when the state vector is
   interpreted in the Pauli or Gell-Mann basis, the represented density matrix
   has trace == 1.  This restriction is frequently used in conjuction with
   trace-preserving (TP) gates, hence its name.

   Parameters
   ----------
   vec : array_like or State
       a 1D numpy array representing the state.  The
       shape of this array sets the dimension of the state.

   basis : Basis or str
       The basis that `vec` is in.

   evotype : Evotype or str, optional
       The evolution type.  The special value `"default"` is equivalent
       to specifying the value of `pygsti.evotypes.Evotype.default_evotype`.

   state_space : StateSpace, optional
       The state space for this operation.  If `None` a default state space
       with the appropriate number of qubits is used.

   Initialize a new state Vector 

   .. py:property:: columnvec

      Direct access the the underlying data as column vector, i.e, a (dim,1)-shaped array.


   .. py:property:: num_params

      Get the number of independent parameters which specify this state vector.

      Returns
      -------
      int
          the number of independent parameters.


   .. py:method:: set_dense(vec)

      Set the dense-vector value of this state vector.

      Attempts to modify this state vector's parameters so that the raw
      state vector becomes `vec`.  Will raise ValueError if this operation
      is not possible.

      Parameters
      ----------
      vec : array_like or State
          A numpy array representing a state vector, or a State object.

      Returns
      -------
      None


   .. py:method:: to_vector()

      Get the state vector parameters as an array of values.

      Returns
      -------
      numpy array
          The parameters as a 1D array with length num_params().


   .. py:method:: from_vector(v, close=False, dirty_value=True)

      Initialize the state vector using a 1D array of parameters.

      Parameters
      ----------
      v : numpy array
          The 1D vector of state vector parameters.  Length
          must == num_params()

      close : bool, optional
          Whether `v` is close to this state vector's current
          set of parameters.  Under some circumstances, when this
          is true this call can be completed more quickly.

      dirty_value : bool, optional
          The value to set this object's "dirty flag" to before exiting this
          call.  This is passed as an argument so it can be updated *recursively*.
          Leave this set to `True` unless you know what you're doing.

      Returns
      -------
      None


   .. py:method:: stateless_data() -> Tuple[int]

      Return this ModelMember's data that is considered constant for purposes of model fitting.

      Note: the word "stateless" here is used in the sense of object-oriented programming.


   .. py:method:: torch_base(sd: Tuple[int], t_param: torch.Tensor) -> torch.Tensor
      :staticmethod:

      Suppose "obj" is an instance of some Torchable subclass. If we compute

          vec = obj.to_vector()
          t_param = torch.from_numpy(vec)
          sd = obj.stateless_data()
          t = type(obj).torch_base(sd, t_param)

      then t will be a PyTorch Tensor that represents "obj" in a canonical numerical way.

      The meaning of "canonical" is implementation dependent. If type(obj) implements
      the ``.base`` attribute, then a reasonable implementation will probably satisfy

          np.allclose(obj.base, t.numpy()).


   .. py:method:: deriv_wrt_params(wrt_filter=None)

      The element-wise derivative this state vector.

      Construct a matrix whose columns are the derivatives of the state vector
      with respect to a single param.  Thus, each column is of length
      dimension and there is one column per state vector parameter.

      Parameters
      ----------
      wrt_filter : list or numpy.ndarray
          List of parameter indices to take derivative with respect to.
          (None means to use all the this operation's parameters.)

      Returns
      -------
      numpy array
          Array of derivatives, shape == (dimension, num_params)


   .. py:method:: has_nonzero_hessian()

      Whether this state vector has a non-zero Hessian with respect to its parameters.

      Returns
      -------
      bool