:py:mod:`pygsti.extras.drift.probtrajectory` ============================================ .. py:module:: pygsti.extras.drift.probtrajectory .. autoapi-nested-parse:: Functions for Fourier analysis of equally spaced time-series data Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: pygsti.extras.drift.probtrajectory.ProbTrajectory pygsti.extras.drift.probtrajectory.ConstantProbTrajectory pygsti.extras.drift.probtrajectory.CosineProbTrajectory Functions ~~~~~~~~~ .. autoapisummary:: pygsti.extras.drift.probtrajectory.negloglikelihood pygsti.extras.drift.probtrajectory.probsdict_negloglikelihood pygsti.extras.drift.probtrajectory.maxlikelihood pygsti.extras.drift.probtrajectory.amplitude_compression .. py:class:: ProbTrajectory(outcomes, hyperparameters, parameters) Bases: :py:obj:`object` Encapulates a time-dependent probability distribution, as a sum of time-dependent basis functions. Initializes a ProbTrajectory object. Parameters ---------- outcomes : list What the probability distribution is over. Typically, all possible outcomes for the circuit that this is a probability trajectory for. hyperparameters : list Each derived ProbTrajectory object is intended to encompass a family of parameterized models for a time-varying probability, and this specifies the specific parameterized model in the class. For example, the CosineProbTrajectory object is a derived class whereby each probability is the summation of some number of cosines, and this specifies the number and frequencies of those cosines. The probability trajectory for *each* outcome is parameterized by a value for each hyperparameter. parameters : A dictonary where the keys are all but the last element of `outcomes`, and the elements are lists of the same lengths as `hyperparameters`. These are the parameters of the parameterized model defined by (the derived class) and `hyperparameters`. The parameter values for the final outcome are assumed to be entirely fixed by the necessity for the probability trajectories to sum to 1 at all times. Returns ------- A new ProbTrajectory object. .. py:attribute:: outcomes .. py:attribute:: numoutcomes .. py:method:: copy() .. py:method:: basisfunction(i, times) :abstractmethod: The ith basis function of the model, evaluated at the times in `times`. **Defined in a derived class** Parameters ---------- i : Type specified by derived class. The basis function specified by the hyperparameter `i`. This method should expect all possible hyperparameter values (often ints in some range, or a float) as this input times : list The times to evaluate the basis function at. Returns ------- list The values of the basis function at the specified times. .. py:method:: set_hyperparameters(hyperparameters, parameters) Sets the hyperparameters -- i.e., defines a new parameterized model -- and the parameters (see init for details). .. py:method:: set_parameters(parameters) Sets the parameters of the model (see init for details). .. py:method:: set_parameters_from_list(parameterslist) Sets the parameters of the model from a list Parameters ---------- parametersaslist : list The new parameter values as a list, where the first len(self.hyperparameters) values are the parameter values for the first outcome (the first element of self.outcomes), the second set of len(self.hyperparameters) values are for the second outcome in this list, and so on, up to the second last value of self.outcomes. Returns ------- None .. py:method:: parameters_as_list() Returns the parameters as a list, in the same format as when input to `set_parameters_from_list`. See the docstring of that method for more info. .. py:method:: parameters_copy() Returns the values of the parameters, in the dictionary form in which it is internally stored. .. py:method:: probabilities(times, trim=True) Returns the probability distribution for each time in `times`. Parameters ---------- times : list A list of times, to return the probability distributions for. time : bool, optional Whether or not to set probability > 1 to 1 and probabilities < 0 to 0. If set to True then there is no guarantee that the probabilities will sum to 1 at all times anymore. Returns ------- dict A dictionary where the keys are the possible outcomes, and the value for a key is a list (of the same lengths as `times`) containing the probability for that outcome at the times in `times`. .. py:class:: ConstantProbTrajectory(outcomes, probabilities) Bases: :py:obj:`ProbTrajectory` Encapulates a time-dependent probability distribution that is actually a constant. Useful when wanting to encode a constant probability distribution in a way that can be used consistently with any other ProbTrajectory object. Initializes a ConstantProbTrajectory object. Parameters ---------- outcomes : list What the probability distribution is over. Typically, all possible outcomes for the circuit that this is a probability trajectory for. probabilities : dict The static probability to obtained all but the last outcome (which is set by the other probabilities). Returns ------- A new ConstantProbTrajectory object. .. py:method:: basisfunction(i, times) .. py:class:: CosineProbTrajectory(outcomes, hyperparameters, parameters, starttime, timestep, numtimes) Bases: :py:obj:`ProbTrajectory` Encapulates a time-dependent probability distribution that is parameterized as a sum of cosines. Specifically, it is parameterized as the sum of the Type-II DCT basis functions. Initializes a CosineProbTrajectory object. Parameters ---------- outcomes : list What the probability distribution is over. Typically, all possible outcomes for the circuit that this is a probability trajectory for. hyperparameters : list A set of integers, that specify the indices of the the DCT basis functions to include. This *must* include 0 as the first element, corresponding to the constant component of the probability trajectories. parameters : dict A dictonary where the keys are all but the last element of `outcomes`, and the elements are lists of the same lengths as `hyperparameters`. These are amplitudes for the DCT basis functions, for each outcome. The first element of each list is the constant component of the that probability trajectory. starttime : float The start time of the time period over which the DCT basis functions are being defined. This is typically set to the first data collection time of the circuit that this probability trajectory is being defined for. timestep : float The size of the time step used to define the DCT basis functions. This is typically set to the time step between the data collection times of the circuit that this probability trajectory is being defined for numtimes : int The number of data collection times defining the DCT basis functions (defines the total number of DCT basis functions: the hyperparameters list is then a subset of this `[0,1,2,...,numtimes-1]`). This is typically set to the number of data collection times for the circuit that this probability trajectory is being defined for. Returns ------- A new CosineProbTrajectory object. .. py:attribute:: starttime .. py:attribute:: timestep .. py:attribute:: numtimes .. py:method:: basisfunction(i, times) The ith Type-II DCT basis function, evaluated at the specified times, where the DCT basis functions under consideration are defined by the time parameters set in the initialization. The normalization of the functions is such that the max/min of each function is +1/-1. Parameters ---------- i : int The frequency index of the DCT basis function. times : list The times to evaluate the basis function at Returns ------- array The value of the basis function at the specified times. .. py:function:: negloglikelihood(probtrajectory, clickstreams, times, minp=0.0, maxp=1.0) The negative log-likelihood of a ProbTrajectory, modelling a time-dependent probability distribution. Parameters ---------- model : ProbTrajectory The model to find the log-likelihood of. data : dict The data, consisting of a counts time-series for each measurement outcome. This is a dictionary whereby the keys are the outcome labels and the values are list (or arrays) giving the number of times that measurement outcome was observed at the corresponding time in the `times` list. times : list or array The times associated with the data. The probabilities are extracted from the model at these times, using the model.get_probabilites method . minp : float, optional A positive value close to zero. The value of `p` below which x*log(p) is approximated using a Taylor expansion (used to smooth out the parameter boundaries and obtain better fitting performance). The default value of 0. give the true log-likelihood. maxp : float, optional A positive value close to and <= 1. The value of `p` above which x*log(p) the boundary on p being <= 1 is enforced using a smooth, quickly growing function. If set to 1. it gives the true log-likelihood. Returns ------- float The log-likehood of the model given the time-series data. .. py:function:: probsdict_negloglikelihood(probs, clickstreams, minp=0.0, maxp=1.0) The negative log-likelihood of varying probabilities `probs`, evaluated for the data streams in `clickstreams`. Parameters ---------- probs : dict A dictionary where the keys are the outcome strings in the clickstream (its keys) and the value for an outcome is the time-dependent probability list for that outcome, at the times associated with the data in the clickstreams. clickstreams : dict A dictionary where the keys are the different measurement outcomes, and the values are lists that give counts for that measurement outcome. Returns ------- float The negative logi-likelihood of the probability trajectories given the clickstream data. .. py:function:: maxlikelihood(probtrajectory, clickstreams, times, minp=0.0001, maxp=0.999999, method='Nelder-Mead', return_opt_output=False, options=None, verbosity=1) Implements maximum likelihood estimation over a model for a time-resolved probabilities trajectory, and returns the maximum likelihood model. Parameters ---------- model : ProbTrajectory The model for which to maximize the likelihood of the parameters. The value of the parameters in the input model is used as the seed. clickstreams : dict The data, consisting of a counts time-series for each measurement outcome. This is a dictionary whereby the keys are the outcome labels and the values are list (or arrays) giving the number of times that measurement outcome was observed at the corresponding time in the `times` list. times : list or array The times associated with the data. The probabilities are extracted from the model at these times (see the model.get_probabilites method), to implement the model parameters optimization. minp : float, optional A positive value close to zero. The value of `p` below which x*log(p) is approximated using a Taylor expansion (used to smooth out the parameter boundaries and obtain better fitting performance). The default value should be fine. maxp : float, optional A positive value close to and <= 1. The value of `p` above which x*log(p) the boundary on p being <= 1 is enforced using a smooth, quickly growing function. The default value should be fine. method : str, optional Any value allowed for the method parameter in scipy.optimize.minimize(). verbosity : int, optional The amount of print to screen. return_opt_output : bool, optional Whether or not to return the output of the optimizer. Returns ------- ProbTrajectory The maximum likelihood model returned by the optimizer. if return_opt_output: optout The output of the optimizer. .. py:function:: amplitude_compression(probtrajectory, times, epsilon=0.0, verbosity=1) Reduces the amplitudes in a CosineProbTrajectory model until the model is valid, i.e., all probabilities are within [0, 1]. Also rectifies any of the constant components of the probability trajectories that are slightly outside [0, 1]. Parameters ---------- probtrajectory: CosineProbTrajectory The model on which to perform the amplitude reduction times: list The times at which to enforce the validity of the model (this algorithm does *not* guarantee that the probabilities will be within [0, 1] at *all* times in the reals). epsilon: float, optional The amplitudes are compressed so that all the probabilities are within [0+epsilon,1-epsilon] at all times. Setting this to be larger than 0 can be useful as it guarantees that the resultant probability trajectory has a non-zero likelihood. Returns ------- CosineProbTrajectory The new model, that may have had the amplitudes reduced Bool Whether or not the function did anything non-trivial, i.e, whether any compression was required.