Circuit specifications

Module name: strawberryfields.circuitspecs

This subpackage implements the CircuitSpecs class, an abstract base class used to define classes or families of quantum circuits, e.g., circuits that can be executed on particular hardware or simulator backends.

The information in the CircuitSpecs instances is used by Program.compile() to validate and compile quantum programs. By querying the CircuitSpecs class representing the requested compilation target, Program.compile can

  1. Validate that the Program has the correct number of modes, and consists of valid quantum operations in the correct topology for the targeted circuit class.
  2. Compile the Program into an equivalent circuit that has the topology required by the targeted circuit class, decomposing circuit operations as required.

Note that the compilation process is not perfect and can provide false negatives: it can admit failure by raising a CircuitError even if the Program theoretically is equivalent to a circuit that belongs in the target circuit class.

Data members

circuit_db Map from circuit family short name to the corresponding class.

The circuit class database circuit_db is a dictionary mapping the circuit family short name to the corresponding CircuitSpecs instance. In particular, for each backend supported by Strawberry Fields the database contains a corresponding CircuitSpecs instance with the same short name, used to validate Programs to be executed on that backend.

Classes

CircuitSpecs Abstract base class for describing circuit classes.

CircuitSpecs methods

modes The number of modes supported by the circuit class.
local Whether the circuit class can be executed locally (i.e., within a simulator).
remote Whether the circuit class supports remote execution.
interactive Whether the circuits in the class can be executed interactively, that is, the registers in the circuit are not reset between engine executions.
primitives The primitive set of quantum operations directly supported by the circuit class.
decompositions Quantum operations that are not quantum primitives for the circuit class, but are supported via specified decompositions.
parameter_ranges Allowed parameter ranges for supported quantum operations.
graph The allowed circuit topologies or connectivity of the class, modelled as a directed acyclic graph.
circuit A rigid circuit template that defines this circuit specification.
compile(seq) Class-specific circuit compilation method.

Code details

strawberryfields.circuitspecs.circuit_db = {'chip0': <class 'strawberryfields.circuitspecs.chip0.Chip0Specs'>, 'fock': <class 'strawberryfields.circuitspecs.fock.FockSpecs'>, 'gaussian': <class 'strawberryfields.circuitspecs.gaussian.GaussianSpecs'>, 'gbs': <class 'strawberryfields.circuitspecs.gbs.GBSSpecs'>, 'tf': <class 'strawberryfields.circuitspecs.tensorflow.TFSpecs'>}

Map from circuit family short name to the corresponding class.

Type:dict[str, CircuitSpecs]
class strawberryfields.circuitspecs.CircuitSpecs[source]

Abstract base class for describing circuit classes.

This class stores information about classes of quantum circuits. For some circuit classes (e.g, ones corresponding to physical hardware chips), the specifications can be quite rigid. For other classes, e.g., circuits supported by a particular simulator backend, the specifications can be more flexible and general.

Key ingredients in a specification include: the primitive gates supported by the circuit class, the gates that can be decomposed to sequences of primitive gates, and the possible topology/connectivity restrictions.

This information is used e.g., in Program.compile() for validation and compilation.

short_name = ''

short name of the circuit class

Type:str
modes

The number of modes supported by the circuit class.

If the circuit class supports arbitrary number of modes, set this to 0.

Returns:number of supported modes
Return type:int
local

Whether the circuit class can be executed locally (i.e., within a simulator).

Returns:True if the circuit class supports local execution
Return type:bool
remote

Whether the circuit class supports remote execution.

Returns:True if the circuit class supports remote execution
Return type:bool
interactive

Whether the circuits in the class can be executed interactively, that is, the registers in the circuit are not reset between engine executions.

Returns:True if the circuit supports interactive use
Return type:bool
primitives

The primitive set of quantum operations directly supported by the circuit class.

Returns:the names of the quantum primitives the circuit class supports
Return type:set[str]
decompositions

Quantum operations that are not quantum primitives for the circuit class, but are supported via specified decompositions.

This should be of the form

{'operation_name': {'option1': val, 'option2': val,...}}

For each operation specified in the dictionary, the Operation.decompose() method will be called during Program compilation, with keyword arguments given by the dictionary value.

Returns:the quantum operations that are supported by the circuit class via decomposition
Return type:dict[str, dict]
parameter_ranges

Allowed parameter ranges for supported quantum operations.

This property is optional.

Returns:a dictionary mapping an allowed quantum operation to a nested list of the form [[p0_min, p0_max], [p1_min, p0_max], ...]. where pi corresponds to the i th gate parameter
Return type:dict[str, list]
graph

The allowed circuit topologies or connectivity of the class, modelled as a directed acyclic graph.

This property is optional; if arbitrary topologies are allowed in the circuit class, this will simply return None.

Returns:a directed acyclic graph
Return type:networkx.DiGraph
circuit

A rigid circuit template that defines this circuit specification.

This property is optional. If arbitrary topologies are allowed in the circuit class, do not define this property. In such a case, it will simply return None.

If a backend device expects a specific template for the recieved Blackbird script, this method will return the serialized Blackbird circuit in string form.

Returns:Blackbird program or template representing the circuit
Return type:Union[str, None]
compile(seq)[source]

Class-specific circuit compilation method.

If additional compilation logic is required, child classes can redefine this method.

Parameters:seq (Sequence[Command]) – quantum circuit to modify
Returns:modified circuit
Return type:List[Command]
Raises:CircuitError – the given circuit cannot be validated to belong to this circuit class

Module name: strawberryfields.circuitspecs.circuit_specs

class strawberryfields.circuitspecs.circuit_specs.CircuitSpecs[source]

Abstract base class for describing circuit classes.

This class stores information about classes of quantum circuits. For some circuit classes (e.g, ones corresponding to physical hardware chips), the specifications can be quite rigid. For other classes, e.g., circuits supported by a particular simulator backend, the specifications can be more flexible and general.

Key ingredients in a specification include: the primitive gates supported by the circuit class, the gates that can be decomposed to sequences of primitive gates, and the possible topology/connectivity restrictions.

This information is used e.g., in Program.compile() for validation and compilation.

short_name = ''

short name of the circuit class

Type:str
modes

The number of modes supported by the circuit class.

If the circuit class supports arbitrary number of modes, set this to 0.

Returns:number of supported modes
Return type:int
local

Whether the circuit class can be executed locally (i.e., within a simulator).

Returns:True if the circuit class supports local execution
Return type:bool
remote

Whether the circuit class supports remote execution.

Returns:True if the circuit class supports remote execution
Return type:bool
interactive

Whether the circuits in the class can be executed interactively, that is, the registers in the circuit are not reset between engine executions.

Returns:True if the circuit supports interactive use
Return type:bool
primitives

The primitive set of quantum operations directly supported by the circuit class.

Returns:the names of the quantum primitives the circuit class supports
Return type:set[str]
decompositions

Quantum operations that are not quantum primitives for the circuit class, but are supported via specified decompositions.

This should be of the form

{'operation_name': {'option1': val, 'option2': val,...}}

For each operation specified in the dictionary, the Operation.decompose() method will be called during Program compilation, with keyword arguments given by the dictionary value.

Returns:the quantum operations that are supported by the circuit class via decomposition
Return type:dict[str, dict]
parameter_ranges

Allowed parameter ranges for supported quantum operations.

This property is optional.

Returns:a dictionary mapping an allowed quantum operation to a nested list of the form [[p0_min, p0_max], [p1_min, p0_max], ...]. where pi corresponds to the i th gate parameter
Return type:dict[str, list]
graph

The allowed circuit topologies or connectivity of the class, modelled as a directed acyclic graph.

This property is optional; if arbitrary topologies are allowed in the circuit class, this will simply return None.

Returns:a directed acyclic graph
Return type:networkx.DiGraph
circuit

A rigid circuit template that defines this circuit specification.

This property is optional. If arbitrary topologies are allowed in the circuit class, do not define this property. In such a case, it will simply return None.

If a backend device expects a specific template for the recieved Blackbird script, this method will return the serialized Blackbird circuit in string form.

Returns:Blackbird program or template representing the circuit
Return type:Union[str, None]
compile(seq)[source]

Class-specific circuit compilation method.

If additional compilation logic is required, child classes can redefine this method.

Parameters:seq (Sequence[Command]) – quantum circuit to modify
Returns:modified circuit
Return type:List[Command]
Raises:CircuitError – the given circuit cannot be validated to belong to this circuit class