pygsti.forwardsims.torchfwdsim

Defines a ForwardSimulator class called “TorchForwardSimulator” that can leverage the automatic differentation features of PyTorch.

This file also defines two helper classes: StatelessCircuit and StatelessModel.

See also: pyGSTi/modelmembers/torchable.py.

Module Contents

Classes

StatelessCircuit	Helper data structure for specifying a quantum circuit (consisting of prep,
StatelessModel	A container for the information in an ExplicitOpModel that's "stateless" in the sense of
TorchForwardSimulator	A forward simulator that leverages automatic differentiation in PyTorch.

Attributes

TORCH_ENABLED

pygsti.forwardsims.torchfwdsim.TORCH_ENABLED = 'True'

class pygsti.forwardsims.torchfwdsim.StatelessCircuit(spc: pygsti.circuits.circuit.SeparatePOVMCircuit)

Helper data structure for specifying a quantum circuit (consisting of prep, applying a sequence of gates, and applying a POVM to the output of the last gate).

prep_label

op_labels

povm_label

outcome_probs_dim

class pygsti.forwardsims.torchfwdsim.StatelessModel(model: pygsti.models.explicitmodel.ExplicitOpModel, layout: pygsti.layouts.copalayout.CircuitOutcomeProbabilityArrayLayout)

A container for the information in an ExplicitOpModel that’s “stateless” in the sense of object-oriented programming:

• A list of StatelessCircuits

• Metadata for parameterized ModelMembers

StatelessModels have instance functions to facilitate computation of (differentable!) circuit outcome probabilities.

Design notes

Much of this functionality could be packed into the TorchForwardSimulator class. Keeping it separate from TorchForwardSimulator helps clarify that it uses none of the sophiciated machinery in TorchForwardSimulator’s base class.

outcome_probs_dim = '0'

circuits = '[]'

param_metadata = '[]'

params_dim = 'None'

default_to_reverse_ad = 'None'

get_free_params(model: pygsti.models.explicitmodel.ExplicitOpModel) → Tuple[torch.Tensor]

Return a tuple of Tensors that encode the states of the provided model’s ModelMembers (where “state” in meant the sense of object-oriented programming).

We compare the labels of the input model’s ModelMembers to those of the model provided to StatelessModel.__init__(…). We raise an error if an inconsistency is detected.

get_torch_bases(free_params: Tuple[torch.Tensor]) → Dict[pygsti.baseobjs.label.Label, torch.Tensor]

Take data of the kind produced by get_free_params and format it in the way required by circuit_probs_from_torch_bases.

Note

If you want to use the returned dict to build a PyTorch Tensor that supports the .backward() method, then you need to make sure that fp.requires_grad is True for all fp in free_params. This can be done by calling fp._requires_grad(True) before calling this function.

circuit_probs_from_torch_bases(torch_bases: Dict[pygsti.baseobjs.label.Label, torch.Tensor]) → torch.Tensor

Compute the circuit outcome probabilities that result when all of this StatelessModel’s StatelessCircuits are run with data in torch_bases.

Return the results as a single (vectorized) torch Tensor.

circuit_probs_from_free_params(*free_params: Tuple[torch.Tensor], enable_backward=False) → torch.Tensor

This is the basic function we expose to pytorch for automatic differentiation. It returns the circuit outcome probabilities resulting when the states of ModelMembers associated with this StatelessModel are set based on free_params.

If you want to call PyTorch’s .backward() on the returned Tensor (or a function of that Tensor), then you should set enable_backward=True. Keep the default value of enable_backward=False in all other situations, including when using PyTorch’s jacrev function.

class pygsti.forwardsims.torchfwdsim.TorchForwardSimulator(model: pygsti.models.explicitmodel.ExplicitOpModel | None = None)

Bases: pygsti.forwardsims.forwardsim.ForwardSimulator

A forward simulator that leverages automatic differentiation in PyTorch.

ENABLED = 'True'

model = 'None'