:py:mod:`pygsti.modelmembers.states.purestate` ============================================== .. py:module:: pygsti.modelmembers.states.purestate .. autoapi-nested-parse:: The EmbeddedPureState class and supporting functionality. Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: pygsti.modelmembers.states.purestate.EmbeddedPureState .. py:class:: EmbeddedPureState(pure_state, evotype='default', dm_basis='pp') Bases: :py:obj:`pygsti.modelmembers.states.state.State` TODO: update docstring A state vector that is a rank-1 density matrix. This is essentially a pure state that evolves according to one of the density matrix evolution types ("denstiymx", "svterm", and "cterm"). It is parameterized by a contained pure-state State which evolves according to a state vector evolution type ("statevec" or "stabilizer"). Parameters ---------- pure_state_vec : array_like or State a 1D numpy array or object representing the pure state. This object sets the parameterization and dimension of this state vector (if `pure_state_vec`'s dimension is `d`, then this state vector's dimension is `d^2`). Assumed to be a complex vector in the standard computational basis. evotype : Evotype or str, optional The evolution type. The special value `"default"` is equivalent to specifying the value of `pygsti.evotypes.Evotype.default_evotype`. Note that the evotype of `pure_state_vec` must be compatible with this value. For example, if `pure_state_vec` has an evotype of `"statevec"` then allowed values are `"densitymx"` and `"svterm"`, or if `"stabilizer"` then the only allowed value is `"cterm"`. dm_basis : {'std', 'gm', 'pp', 'qt'} or Basis object The basis for this state vector - that is, for the *density matrix* corresponding to `pure_state_vec`. Allowed values are Matrix-unit (std), Gell-Mann (gm), Pauli-product (pp), and Qutrit (qt) (or a custom basis object). Initialize a new state Vector .. py:property:: parameter_labels An array of labels (usually strings) describing this model member's parameters. .. py:property:: num_params Get the number of independent parameters which specify this state vector. Returns ------- int the number of independent parameters. .. py:attribute:: pure_state .. py:attribute:: basis :value: "'pp'" .. py:method:: to_dense(on_space: pygsti.SpaceT = 'minimal', scratch=None) Return this state vector as a (dense) numpy array. The memory in `scratch` maybe used when it is not-None. Parameters ---------- on_space : {'minimal', 'Hilbert', 'HilbertSchmidt'} The space that the returned dense operation acts upon. For unitary matrices and bra/ket vectors, use `'Hilbert'`. For superoperator matrices and super-bra/super-ket vectors use `'HilbertSchmidt'`. `'minimal'` means that `'Hilbert'` is used if possible given this operator's evolution type, and otherwise `'HilbertSchmidt'` is used. scratch : numpy.ndarray, optional scratch space available for use. Returns ------- numpy.ndarray .. py:method:: taylor_order_terms(order, max_polynomial_vars=100, return_coeff_polys=False) Get the `order`-th order Taylor-expansion terms of this state vector. This function either constructs or returns a cached list of the terms at the given order. Each term is "rank-1", meaning that it is a state preparation followed by or POVM effect preceded by actions on a density matrix `rho` of the form: `rho -> A rho B` The coefficients of these terms are typically polynomials of the State's parameters, where the polynomial's variable indices index the *global* parameters of the State's parent (usually a :class:`Model`) , not the State's local parameter array (i.e. that returned from `to_vector`). Parameters ---------- order : int The order of terms to get. max_polynomial_vars : int, optional maximum number of variables the created polynomials can have. return_coeff_polys : bool Whether a parallel list of locally-indexed (using variable indices corresponding to *this* object's parameters rather than its parent's) polynomial coefficients should be returned as well. Returns ------- terms : list A list of :class:`RankOneTerm` objects. coefficients : list Only present when `return_coeff_polys == True`. A list of *compact* polynomial objects, meaning that each element is a `(vtape,ctape)` 2-tuple formed by concatenating together the output of :meth:`Polynomial.compact`. .. 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:: deriv_wrt_params(wrt_filter=None) :abstractmethod: 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 .. py:method:: submembers() Get the ModelMember-derived objects contained in this one. Returns ------- list