Quantum circuit variables

Module name: pennylane.variable

This module contains the Variable class, which is used to track and identify QNode parameters.

The first time a QNode is evaluated (either by calling evaluate(), __call__(), or jacobian()), the construct() method is called, which performs a ‘just-in-time’ circuit construction on the Device. As part of this construction, all arguments and keyword arguments are wrapped in a Variable as follows:

  • All positional arguments in *args, including those with multiple dimensions, are flattened to a single list, and each element wrapped as a Variable instance, indexed by its position in the list.

    This allows PennyLane to inspect the shape and type of arguments the user wishes to pass. The list can then be unflattened back to the original shape of *args.

  • The same is done for each keyword argument in **kwargs, the only difference being that the name of each contained Variable corresponds with the keyword name.

As a result, the device stores a list of operations and expectations, with all free parameters stored as Variable instances.


The QNode can be differentiated with respect to positional arguments, but not with respect to keyword arguments. This makes keyword arguments a natural location for data placeholders.


If the user defines a keyword argument, then they always have to pass the corresponding variable as a keyword argument, otherwise it won’t register.

For each successive QNode execution, the user-provided values for arguments and keyword arguments are stored in the Variable.free_param_values list and the Variable.kwarg_values dictionary respectively; these are then returned by Variable.val(), using its idx value, and, for keyword arguments, its name, to return the correct value to the operation.


The Operation.parameters() property automates the process of unpacking the Variable value. The attribute Variable.val() should not need to be accessed outside of advanced usage.

Code details

class Variable(idx=None, name=None)[source]

A reference class to dynamically track and update circuit parameters.

Represents a placeholder variable. This can either be a free quantum circuit parameter (with a non-fixed value) times an optional scalar multiplier, or a placeholder for data/other hard-coded data.

Each time the circuit is executed, it is given a vector of parameter values, and a dictionary of keyword variable values.

Variable is essentially an index into that vector.


Variables currently do not implement any arithmetic operations other than scalar multiplication.

  • idx (int) – parameter index >= 0
  • name (str) – name of the variable (optional)
free_param_values = array([-0.01311098, 0.4025823 , -0.00351909, 0.00797863, -0.24075606, -0.00113536, -0.02181527, 0.42884102, -0.00736571, -0.01047191, 0.76587178, 0.00341258, 0.00109451, -0.22018264, 0.00398482, -0.00110639, -0.17721105, 0.01300854, -0.00600508, 0.42294501, 0.00976835, 0.00424934, 0.4404757 , -0.01808748, 0.02892989, -0.52585209, 0.04536902, 0.04477782, -0.10691044, 0.03343576, 0.02622654, 0.41555752, 0.00472149, 0.00819917, 0.0090752 , -0.00585823])

current free parameter values, set in QNode.evaluate()

kwarg_values = {'angles': array([ 0.2809794 , -0. , 0. , -0.78539816, 0.78539816])}

dictionary containing the keyword argument values, set in QNode.evaluate()

idx = None

parameter index

name = None

parameter name

mult = None

parameter scalar multiplier

Type:int, float

Current numerical value of the Variable.

Returns:current value of the Variable
Return type:float