IRAST

Definition of the abstract syntax tree (AST) for Qadence 2 IR.

This module defines the abstract syntax tree (AST) in Qadence 2 IR. The AST is used in the front- end to IR compilation. Implementations of IRBuilder, defined in qadence2-ir.irbuilder, translate front-end code to the AST defined here. Then, the tools in qadence2-ir.factory_tools can be used to manipulate an AST instance and build valid IR instructions from the AST.

AST

Represents an instruction sequence as an abstract syntax tree (AST).

The initialization of this class must be done using the specific constructors.

Constructors:

• AST.numeric(value): For numerical values.
• AST.input_variable(name, size, trainable): For literal variables.
• AST.callable(fn_name, *args): For classical functions.
• AST.support(target, control): For qubit indices.
• AST.quantum_op(name, support, *args): For quantum operators with and without parameters.
• AST.sequence(*q_ops): For sequences of quantum operations.
• AST.add(lhs, rhs): For addition, lhs + rhs.
• AST.sub(lhs, rhs): For subtraction, lhs - rhs.
• AST.mul(lhs, rhs): For multiplication, lhs * rhs.
• AST.div(lhs, rhs): For division, lhs / rhs.
• AST.rem(lhs, rhs): For remainder, lhs % rhs.
• AST.pow(base, power): For power, base ** power.

__construct__(tag, head, *args, **attrs) classmethod

Base constructor method.

To void arbitrary initialization, this class must be initialized with one of the standard constructors provided. This method hides the initialization from the regular __new__ to enforce that.

PARAMETER	DESCRIPTION
tag	A Tag indicating the AST type. Has one of the following values: QuantumOperator, Sequence, Support, Call, InputVariable, Numeric. TYPE: Tag
head	A string identifier of the AST object. TYPE: str
args	Optional arguments for specific constructors. TYPE: Any DEFAULT: ()
attrs	Optional attributes for specific constructors. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
ast	A newly constructed AST object. TYPE: AST

Source code in qadence2_ir/irast.py

@classmethod
def __construct__(cls, tag: Tag, head: str, *args: Any, **attrs: Any) -> AST:
    """Base constructor method.

    To void arbitrary initialization, this class must be initialized with one of the standard
    constructors provided. This method hides the initialization from the regular `__new__` to
    enforce that.

    Args:
        tag: A Tag indicating the AST type. Has one of the following values: `QuantumOperator`,
            `Sequence`, `Support`, `Call`, `InputVariable`, `Numeric`.
        head: A string identifier of the AST object.
        args: Optional arguments for specific constructors.
        attrs: Optional attributes for specific constructors.

    Returns:
        ast: A newly constructed AST object.
    """

    token = super().__new__(cls)
    token._tag = tag
    token._head = head
    token._args = args
    token._attrs = attrs
    return token

add(lhs, rhs) classmethod

Create an AST-arithmetic addition.

PARAMETER	DESCRIPTION
lhs	Left-hand side operand. TYPE: AST
rhs	Right-hand side operand. TYPE: AST

RETURNS	DESCRIPTION
ast	An AST callable adding lhs and rhs. TYPE: AST

Source code in qadence2_ir/irast.py

@classmethod
def add(cls, lhs: AST, rhs: AST) -> AST:
    """Create an AST-arithmetic addition.

    Args:
        lhs: Left-hand side operand.
        rhs: Right-hand side operand.

    Returns:
        ast: An AST callable adding `lhs` and `rhs`.
    """

    return cls.callable("add", lhs, rhs)

callable(name, *args) classmethod

Create an AST-function object.

PARAMETER	DESCRIPTION
name	The function name. TYPE: str
args	Arguments to be passed to the function. TYPE: AST DEFAULT: ()

RETURNS	DESCRIPTION
ast	A callable AST. TYPE: AST

Source code in qadence2_ir/irast.py

@classmethod
def callable(cls, name: str, *args: AST) -> AST:
    """Create an AST-function object.

    Args:
        name: The function name.
        args: Arguments to be passed to the function.

    Returns:
        ast: A callable AST.
    """

    return cls.__construct__(cls.Tag.Call, name, *args)

div(lhs, rhs) classmethod

Create an AST-arithmetic division.

PARAMETER	DESCRIPTION
lhs	Left-hand side operand. TYPE: AST
rhs	Right-hand side operand. TYPE: AST

RETURNS	DESCRIPTION
ast	An AST callable dividing lhs by rhs. TYPE: AST

Source code in qadence2_ir/irast.py

@classmethod
def div(cls, lhs: AST, rhs: AST) -> AST:
    """Create an AST-arithmetic division.

    Args:
        lhs: Left-hand side operand.
        rhs: Right-hand side operand.

    Returns:
        ast: An AST callable dividing `lhs` by `rhs`.
    """

    return cls.callable("div", lhs, rhs)

input_variable(name, size, trainable, **attributes) classmethod

Create an AST-input variable.

PARAMETER	DESCRIPTION
name	The variable's name. TYPE: str
size	Number of slots to be reserved for the variable, 1 for scalar values and n>1 for array variables. TYPE: int
trainable	A boolean flag to indicate if the variable is intend to be optimized or used as a constant during the run. TYPE: bool
attributes	Extra flags, values or dictionaries that can provide more context to the backends. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
ast	An input variable AST. TYPE: AST

Source code in qadence2_ir/irast.py

@classmethod
def input_variable(cls, name: str, size: int, trainable: bool, **attributes: Any) -> AST:
    """Create an AST-input variable.

    Args:
        name: The variable's name.
        size: Number of slots to be reserved for the variable, 1 for scalar values and n>1 for
            array variables.
        trainable: A boolean flag to indicate if the variable is intend to be optimized or
            used as a constant during the run.
        attributes: Extra flags, values or dictionaries that can provide more context to the
            backends.

    Returns:
        ast: An input variable AST.
    """

    return cls.__construct__(cls.Tag.InputVariable, name, size, trainable, **attributes)

mul(lhs, rhs) classmethod

Create an AST-arithmetic multiplication.

PARAMETER	DESCRIPTION
lhs	Left-hand side operand. TYPE: AST
rhs	Right-hand side operand. TYPE: AST

RETURNS	DESCRIPTION
ast	An AST callable multiplying lhs and rhs. TYPE: AST

Source code in qadence2_ir/irast.py

@classmethod
def mul(cls, lhs: AST, rhs: AST) -> AST:
    """Create an AST-arithmetic multiplication.

    Args:
        lhs: Left-hand side operand.
        rhs: Right-hand side operand.

    Returns:
        ast: An AST callable multiplying `lhs` and `rhs`.
    """

    return cls.callable("mul", lhs, rhs)

numeric(value) classmethod

Create an AST-numeric object.

PARAMETER	DESCRIPTION
value	Numerical value to be converted in the Qadence2-IR AST. TYPE: complex | float

RETURNS	DESCRIPTION
ast	A numerical value AST. TYPE: AST

Source code in qadence2_ir/irast.py

@classmethod
def numeric(cls, value: complex | float) -> AST:
    """Create an AST-numeric object.

    Args:
        value: Numerical value to be converted in the Qadence2-IR AST.

    Returns:
        ast: A numerical value AST.
    """

    return cls.__construct__(cls.Tag.Numeric, "", value)

pow(base, power) classmethod

Create an AST-arithmetic power.

PARAMETER	DESCRIPTION
base	Base operand. TYPE: AST
power	Power operand. TYPE: AST

RETURNS	DESCRIPTION
ast	An AST callable of base to the power power. TYPE: AST

Source code in qadence2_ir/irast.py

@classmethod
def pow(cls, base: AST, power: AST) -> AST:
    """Create an AST-arithmetic power.

    Args:
        base: Base operand.
        power: Power operand.

    Returns:
        ast: An AST callable of `base` to the power `power`.
    """

    return cls.callable("pow", base, power)

quantum_op(name, target, control, *args, **attributes) classmethod

Create an AST-quantum operator.

PARAMETER	DESCRIPTION
name	Operator's name. TYPE: str
target	A tuple of indices a quantum operator is acting on. TYPE: tuple[int, ...]
control	A tuple of indices a quantum operator uses as control qubits. TYPE: tuple[int, ...]
args	Arguments to be passed to parameteric quantum operators. Non-parametric operators like Puali gates are treated as a parametric operator with no arguments. TYPE: Any DEFAULT: ()
attributes	Extra flags, values or dictionaries that can provide more context to the backends. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
ast	A quantum operator AST. TYPE: AST

Source code in qadence2_ir/irast.py

@classmethod
def quantum_op(
    cls,
    name: str,
    target: tuple[int, ...],
    control: tuple[int, ...],
    *args: Any,
    **attributes: Any,
) -> AST:
    """Create an AST-quantum operator.

    Args:
        name: Operator's name.
        target: A tuple of indices a quantum operator is acting on.
        control: A tuple of indices a quantum operator uses as control qubits.
        args: Arguments to be passed to parameteric quantum operators. Non-parametric
            operators like Puali gates are treated as a parametric operator with no arguments.
        attributes: Extra flags, values or dictionaries that can provide more context to the
            backends.

    Returns:
        ast: A quantum operator AST.
    """

    support = cls.support(target, control)
    return cls.__construct__(cls.Tag.QuantumOperator, name, support, *args, **attributes)

rem(lhs, rhs) classmethod

Create an AST-arithmetic remainder.

PARAMETER	DESCRIPTION
lhs	Left-hand side operand. TYPE: AST
rhs	Right-hand side operand. TYPE: AST

RETURNS	DESCRIPTION
ast	An AST callable; remainder or lhs and rhs. TYPE: AST

Source code in qadence2_ir/irast.py

@classmethod
def rem(cls, lhs: AST, rhs: AST) -> AST:
    """Create an AST-arithmetic remainder.

    Args:
        lhs: Left-hand side operand.
        rhs: Right-hand side operand.

    Returns:
        ast: An AST callable; remainder or `lhs` and `rhs`.
    """

    return cls.callable("rem", lhs, rhs)

sequence(*quantum_operators) classmethod

Create an AST-sequence of quantum operators objects.

PARAMETER	DESCRIPTION
quantum_operators	Sequence of quantum operators to be applied by the backend in the given order. TYPE: Any DEFAULT: ()

RETURNS	DESCRIPTION
ast	An AST-sequence of quantum operators. TYPE: AST

Source code in qadence2_ir/irast.py

@classmethod
def sequence(cls, *quantum_operators: Any) -> AST:
    """Create an AST-sequence of quantum operators objects.

    Args:
        quantum_operators: Sequence of quantum operators to be applied by the backend in the
            given order.

    Returns:
        ast: An AST-sequence of quantum operators.
    """

    return cls.__construct__(cls.Tag.Sequence, "", *quantum_operators)

sub(lhs, rhs) classmethod

Create an AST-arithmetic subtraction.

PARAMETER	DESCRIPTION
lhs	Left-hand side operand. TYPE: AST
rhs	Right-hand side operand. TYPE: AST

RETURNS	DESCRIPTION
ast	An AST callable subtracting rhs from lhs. TYPE: AST

Source code in qadence2_ir/irast.py

@classmethod
def sub(cls, lhs: AST, rhs: AST) -> AST:
    """Create an AST-arithmetic subtraction.

    Args:
        lhs: Left-hand side operand.
        rhs: Right-hand side operand.

    Returns:
        ast: An AST callable subtracting `rhs` from `lhs`.
    """

    return cls.callable("sub", lhs, rhs)

support(target, control) classmethod

Create an AST-support object used to indicate to which qubits a quantum operation is applied.

PARAMETER	DESCRIPTION
target	A tuple of indices a quantum operator is acting on. TYPE: tuple[int, ...]
control	A tuple of indices a quantum operator uses as control qubits. TYPE: tuple[int, ...]

RETURNS	DESCRIPTION
ast	A support AST. TYPE: AST

Source code in qadence2_ir/irast.py

@classmethod
def support(cls, target: tuple[int, ...], control: tuple[int, ...]) -> AST:
    """Create an AST-support object used to indicate to which qubits a quantum operation is
    applied.

    Args:
        target: A tuple of indices a quantum operator is acting on.
        control: A tuple of indices a quantum operator uses as control qubits.

    Returns:
        ast: A support AST.
    """

    return cls.__construct__(cls.Tag.Support, "", target, control)