netqasm.sdk.futures

Abstractions for classical runtime values.

This module contains the BaseFuture class and its subclasses.

exception netqasm.sdk.futures.NoValueError

Bases: RuntimeError

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception netqasm.sdk.futures.NonConstantIndexError

Bases: RuntimeError

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

netqasm.sdk.futures.as_int_when_value(cls)

A decorator for the BaseFuture class which makes is behave like an int when the property value is not None.

class netqasm.sdk.futures.BaseFuture(connection)

Bases: int

Base class for Future-like objects.

A Future represents a classical value that becomes available at some point in the future. At the moment, a Future always represents an integer value.

Futures have a value property that is either None (when the value is not yet available), or has a concrete integer value. Executing a subroutine on the quantum node controller makes the value property go from None to a concrete value, granted that the subroutine sets the value of whatever the Future represents. When the value property has a concrete value, the Future behaves like an int and can then also be used in Python expressions just like integers.

Typically, a Future instance is obtained as the result of an SDK function, and not directly instantiated in application code. For example, calling measure() on a Qubit returns a Future representing the measurement outcome. Only after the subroutine containing the operations has been executed by the quantum node controller (by flushing the subroutine), the measurement outcome will have an actual value, and the Future can be resolved into an int.

Parameters

connection (sdkconn.BaseNetQASMConnection) –

property builder
Return type

Builder

property value

Get the value of the future. If it’s not set yet, None is returned.

Return type

Optional[int]

add(other, mod=None)

Add another value to this Future’s value.

The result is stored in this Future.

Let the quantum node controller add a value to the value represented by this Future. The addition operation is compiled into a subroutine and is fully executed by the quantum node controller. This avoids the need to wait for a subroutine result (which resolves the Future’s value) and then doing the addition on the Host.

Parameters

  • other (Union[int, str, Register, BaseFuture]) – value to add to this Future’s value

  • mod (Optional[int]) – do the addition modulo mod

Return type

None

if_eq(other)
Parameters

other (Optional[T_CValue]) –

Return type

SdkIfContext

if_ne(other)
Parameters

other (Optional[T_CValue]) –

Return type

SdkIfContext

if_lt(other)
Parameters

other (Optional[T_CValue]) –

Return type

SdkIfContext

if_ge(other)
Parameters

other (Optional[T_CValue]) –

Return type

SdkIfContext

if_ez()
Return type

SdkIfContext

if_nz()
Return type

SdkIfContext

as_integer_ratio()

Return integer ratio.

Return a pair of integers, whose ratio is exactly equal to the original int and with a positive denominator.

>>> (10).as_integer_ratio()
(10, 1)
>>> (-10).as_integer_ratio()
(-10, 1)
>>> (0).as_integer_ratio()
(0, 1)
bit_length(*args, **kwargs)

Check if the value is set, otherwise raise an error

conjugate(*args, **kwargs)

Check if the value is set, otherwise raise an error

denominator(*args, **kwargs)

Check if the value is set, otherwise raise an error

from_bytes(byteorder, *, signed=False)

Return the integer represented by the given array of bytes.

bytes

Holds the array of bytes to convert. The argument must either support the buffer protocol or be an iterable object producing bytes. Bytes and bytearray are examples of built-in objects that support the buffer protocol.

byteorder

The byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use `sys.byteorder’ as the byte order value.

signed

Indicates whether two’s complement is used to represent the integer.

imag(*args, **kwargs)

Check if the value is set, otherwise raise an error

numerator(*args, **kwargs)

Check if the value is set, otherwise raise an error

real(*args, **kwargs)

Check if the value is set, otherwise raise an error

to_bytes(*args, **kwargs)

Check if the value is set, otherwise raise an error

class netqasm.sdk.futures.Future(connection, address, index)

Bases: netqasm.sdk.futures.BaseFuture

Represents a single array entry value that will become available in the future.

See BaseFuture for more explanation about Futures.

Parameters
__init__(connection, address, index)

Future constructor. Typically not used directly.

Parameters

  • connection (sdkconn.BaseNetQASMConnection) – connection through which subroutines are sent that contain the array entry corresponding to this Future

  • address (int) – address of the array

  • index (Union[int, Future, operand.Register, RegFuture]) – index in the array

add(other, mod=None)

Add another value to this Future’s value.

The result is stored in this Future.

Let the quantum node controller add a value to the value represented by this Future. The addition operation is compiled into a subroutine and is fully executed by the quantum node controller. This avoids the need to wait for a subroutine result (which resolves the Future’s value) and then doing the addition on the Host.

Parameters

  • other (Union[int, str, Register, BaseFuture]) – value to add to this Future’s value

  • mod (Optional[int]) – do the addition modulo mod

Return type

None

get_load_commands(register)

Return a list of ProtoSubroutine commands for loading this Future into the specified register.

Parameters

register (Register) –

Return type

List[Union[ICmd, BranchLabel]]

get_address_entry()

Convert this Future to an ArrayEntry object to be used an instruction operand.

Return type

ArrayEntry

as_integer_ratio()

Return integer ratio.

Return a pair of integers, whose ratio is exactly equal to the original int and with a positive denominator.

>>> (10).as_integer_ratio()
(10, 1)
>>> (-10).as_integer_ratio()
(-10, 1)
>>> (0).as_integer_ratio()
(0, 1)
bit_length(*args, **kwargs)

Check if the value is set, otherwise raise an error

property builder
Return type

Builder

conjugate(*args, **kwargs)

Check if the value is set, otherwise raise an error

denominator(*args, **kwargs)

Check if the value is set, otherwise raise an error

from_bytes(byteorder, *, signed=False)

Return the integer represented by the given array of bytes.

bytes

Holds the array of bytes to convert. The argument must either support the buffer protocol or be an iterable object producing bytes. Bytes and bytearray are examples of built-in objects that support the buffer protocol.

byteorder

The byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use `sys.byteorder’ as the byte order value.

signed

Indicates whether two’s complement is used to represent the integer.

if_eq(other)
Parameters

other (Optional[T_CValue]) –

Return type

SdkIfContext

if_ez()
Return type

SdkIfContext

if_ge(other)
Parameters

other (Optional[T_CValue]) –

Return type

SdkIfContext

if_lt(other)
Parameters

other (Optional[T_CValue]) –

Return type

SdkIfContext

if_ne(other)
Parameters

other (Optional[T_CValue]) –

Return type

SdkIfContext

if_nz()
Return type

SdkIfContext

imag(*args, **kwargs)

Check if the value is set, otherwise raise an error

numerator(*args, **kwargs)

Check if the value is set, otherwise raise an error

real(*args, **kwargs)

Check if the value is set, otherwise raise an error

to_bytes(*args, **kwargs)

Check if the value is set, otherwise raise an error

property value

Get the value of the future. If it’s not set yet, None is returned.

Return type

Optional[int]

class netqasm.sdk.futures.RegFuture(connection, reg=None)

Bases: netqasm.sdk.futures.BaseFuture

Represents a single register value that will become available in the future.

See BaseFuture for more explanation about Futures.

Parameters

  • connection (sdkconn.BaseNetQASMConnection) –

  • reg (Optional[operand.Register]) –

__init__(connection, reg=None)

RegFuture constructor. Typically not used directly.

Parameters

  • connection (sdkconn.BaseNetQASMConnection) – connection through which subroutines are sent that contain the array entry corresponding to this Future

  • reg (Optional[operand.Register]) – specific NetQASM register that will hold the Future’s value. If None, a suitable register is automatically used.

property reg
Return type

Optional[Register]

add(other, mod=None)

Add another value to this Future’s value.

The result is stored in this Future.

Let the quantum node controller add a value to the value represented by this Future. The addition operation is compiled into a subroutine and is fully executed by the quantum node controller. This avoids the need to wait for a subroutine result (which resolves the Future’s value) and then doing the addition on the Host.

Parameters

  • other (Union[int, str, Register, BaseFuture]) – value to add to this Future’s value

  • mod (Optional[int]) – do the addition modulo mod

Return type

None

as_integer_ratio()

Return integer ratio.

Return a pair of integers, whose ratio is exactly equal to the original int and with a positive denominator.

>>> (10).as_integer_ratio()
(10, 1)
>>> (-10).as_integer_ratio()
(-10, 1)
>>> (0).as_integer_ratio()
(0, 1)
bit_length(*args, **kwargs)

Check if the value is set, otherwise raise an error

property builder
Return type

Builder

conjugate(*args, **kwargs)

Check if the value is set, otherwise raise an error

denominator(*args, **kwargs)

Check if the value is set, otherwise raise an error

from_bytes(byteorder, *, signed=False)

Return the integer represented by the given array of bytes.

bytes

Holds the array of bytes to convert. The argument must either support the buffer protocol or be an iterable object producing bytes. Bytes and bytearray are examples of built-in objects that support the buffer protocol.

byteorder

The byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use `sys.byteorder’ as the byte order value.

signed

Indicates whether two’s complement is used to represent the integer.

if_eq(other)
Parameters

other (Optional[T_CValue]) –

Return type

SdkIfContext

if_ez()
Return type

SdkIfContext

if_ge(other)
Parameters

other (Optional[T_CValue]) –

Return type

SdkIfContext

if_lt(other)
Parameters

other (Optional[T_CValue]) –

Return type

SdkIfContext

if_ne(other)
Parameters

other (Optional[T_CValue]) –

Return type

SdkIfContext

if_nz()
Return type

SdkIfContext

imag(*args, **kwargs)

Check if the value is set, otherwise raise an error

numerator(*args, **kwargs)

Check if the value is set, otherwise raise an error

real(*args, **kwargs)

Check if the value is set, otherwise raise an error

to_bytes(*args, **kwargs)

Check if the value is set, otherwise raise an error

property value

Get the value of the future. If it’s not set yet, None is returned.

Return type

Optional[int]

class netqasm.sdk.futures.Array(connection, length, address, init_values=None, lineno=None)

Bases: object

Wrapper around an array in Shared Memory.

An Array instance provides methods to inspect and operate on an array that exists in shared memory. They are typically obtained as return values to certain SDK methods.

Elements or slices of the array can be captured as Futures.

Parameters

  • connection (sdkconn.BaseNetQASMConnection) –

  • length (int) –

  • address (int) –

  • init_values (Optional[List[Optional[int]]]) –

  • lineno (Optional[HostLine]) –

__init__(connection, length, address, init_values=None, lineno=None)

Array constructor. Typically not used directly.

Parameters

  • connection (sdkconn.BaseNetQASMConnection) – connection of the application this array is part of

  • length (int) – length of the array

  • address (int) – address of the array

  • init_values (Optional[List[Optional[int]]]) – initial values of the array. Must have length length.

  • lineno (Optional[HostLine]) – line number where the array is created in the Python source code

property lineno

What line in host application file initiated this array

Return type

Optional[HostLine]

property address
Return type

int

property builder
Return type

Builder

get_future_index(index)

Get a Future representing a particular array element

Parameters

index (Union[int, str, Register, RegFuture]) –

Return type

Future

get_future_slice(s)

Get a list of Futures each representing one element in a particular array slice

Parameters

s (slice) –

Return type

List[Future]

foreach()

Create a context of code that gets called for each element in the array.

Returns a future of the array value at the current index.

Code inside the context must be compilable to NetQASM, that is, it should only contain quantum operations and/or classical values that are are stored in shared memory (arrays and registers). No classical communication is allowed.

Example:

with NetQASMConnection(app_name="alice") as alice:
    outcomes = alice.new_array(10)
    values = alice.new_array(
        10,
        init_values=[random.randint(0, 1) for _ in range(10)]
    )
    with values.foreach() as v:
        q = Qubit(alice)
        with v.if_eq(1):
            q.H()
        q.measure(future=outcomes.get_future_index(i))
Return type

SdkForEachContext

enumerate()

Create a context of code that gets called for each element in the array and includes a counter.

Returns a tuple (index, future) where future is a Future of the array value at the current index.

Code inside the context must be compilable to NetQASM, that is, it should only contain quantum operations and/or classical values that are are stored in shared memory (arrays and registers). No classical communication is allowed.

Example:

with NetQASMConnection(app_name="alice") as alice:
    outcomes = alice.new_array(10)
    values = alice.new_array(
        10,
        init_values=[random.randint(0, 1) for _ in range(10)]
    )
    with values.enumerate() as (i, v):
        q = Qubit(alice)
        with v.if_eq(1):
            q.H()
        q.measure(future=outcomes.get_future_index(i))
Return type

SdkForEachContext

undefine()

Undefine (i.e. set to ‘None’) all elements in the array.

Return type

None