sf.parameters

Warning

Unless you are a Strawberry Fields developer, you likely do not need to use these classes directly.

The classes in this module represent parameters passed to the quantum operations represented by Operation subclasses.

Parameter types

There are three basic types of parameters:

  1. Numerical parameters (bound and fixed): An immediate, immutable numerical object (float, complex, int, numerical array). Implemented as-is, not encapsulated in a class.

  2. Measured parameters (bound but not fixed): Certain quantum circuits/protocols require that Operations can be conditioned on measurement results obtained during the execution of the circuit. In this case the parameter value is not known/fixed until the measurement is made (or simulated). Represented by MeasuredParameter instances. Constructed from the RegRef instance storing the measurement result using the RegRef.par() method.

  3. Free parameters (not bound nor fixed): A parametrized circuit template is a circuit that depends on a number of unbound (free) parameters. These parameters need to be bound to fixed numerical values before the circuit can be executed on a hardware quantum device or a numeric simulator. Represented by FreeParameter instances. Simulators with symbolic capability can accept a parametrized circuit as input (and should return symbolic expressions representing the measurement results, with the same free parameters, as output). Free parameters belong to a single Program instance, are constructed using the Program.params() method, and are bound using Program.bind_params().

Operation subclass constructors accept parameters that are functions or algebraic combinations of any number of these basic parameter types. This is made possible by MeasuredParameter and FreeParameter inheriting from sympy.Symbol.

Note

Binary arithmetic operations between sympy symbols and numpy arrays produces numpy object arrays containing sympy symbols.

Operation lifecycle

The normal lifecycle of an Operation object and its associated parameters is as follows:

  • An Operation instance is constructed, and given some input arguments. In Operation.__init__(), the RegRef dependencies of measured parameters are added to Operation._measurement_deps.

  • The Operation instance is applied using its __or__() method inside a Program context. This creates a Command instance that wraps the Operation and the RegRefs it acts on, which is appended to Program.circuit.

  • Before the Program is run, it is compiled and optimized for a specific backend. This involves checking that the Program only contains valid Operations, decomposing non-elementary Operations using decompose(), and finally merging and commuting Commands inside the graph representing the quantum circuit. The circuit graph is built using the knowledge of which subsystems the Commands act and depend on.

  • Decompositions, merges, and commutations often involve the creation of new Operations with algebraically transformed parameters. For example, merging two Gate instances of the same subclass involves adding their first parameters after equality-comparing the others. This is easily done if all the parameters have an immediate numerical value. Measured and free parameters are handled symbolically by Sympy.

  • The compiled Program is run by a BaseEngine instance, which calls the apply() method of each Operation in turn.

  • apply() then calls _apply() which is redefined by each Operation subclass. It evaluates the value of the parameters using par_evaluate(), and may perform additional numeric transformations on them. The parameter values are finally passed to the appropriate backend API method. It is up to the backend to either accept NumPy arrays and Tensorflow objects as parameters, or not.

What we cannot do at the moment:

  • Use anything except integers and RegRefs (or Sequences thereof) as the subsystem argument for the __or__() method. Technically we could allow any parameters that evaluate into an integer.

Functions

heaviside(x)

Heaviside step function.

is_object_array(p)

Returns True iff p is an object array.

par_convert(args, prog)

Convert Blackbird symbolic Operation arguments into their SF counterparts.

par_evaluate(params)

Evaluate an Operation parameter sequence.

par_is_symbolic(p)

Returns True iff p is a symbolic Operation parameter instance.

par_regref_deps(p)

RegRef dependencies of an Operation parameter.

par_str(p)

String representation of the Operation parameter.

wrap_mathfunc(func)

Applies the wrapped sympy function elementwise to numpy arrays.

Classes

FreeParameter(name)

Symbolic Operation parameter.

MeasuredParameter(regref)

Single measurement result used as an Operation parameter.

ParameterError

Exception raised when the Parameter classes encounter an illegal operation.

Variables

parfuncs

Namespace of mathematical functions for manipulating Parameters.

Class Inheritance Diagram

Inheritance diagram of strawberryfields.parameters.FreeParameter, strawberryfields.parameters.MeasuredParameter, strawberryfields.parameters.ParameterError