# Network API¶

This page describes the interface of a quantum network data structure in tweedledum.

Warning

This part of the documentation makes use of a class called network. This class has been created solely for the purpose of creating this documentation and is not meant to be used in code. Custom network implementation do not have to derive from this class, but only need to ensure that, if they implement a function of the interface, it is implemented using the same signature.

## Mandatory types and constants¶

The interaction with a network data structure is performed using four types for which no application details are assumed. The following four types must be defined within the network data structure. They can be implemented as nested type, but may also be exposed as type alias.

template<typename GateType>
class network

Public Types

template<>
using base_type = network

A yype referring to itself.

The base_type is the network type itself. It is required, because views may extend networks, and this type provides a way to determine the underlying network type.

template<>
using gate_type = GateType

A type representing a gate.

A gate is an operation that can be applied to a collection of I/Os. It could be a meta operation, such as, primary input and a primary output, or a unitary operation gate.

struct node_type

A type representing a node in the graph (network).

NOTE: Each node must contain a gate.

struct storage_type

A type representing the storage.

A storage is some container that can contain all data necessary to store the network. It can constructed outside of the network and passed as a reference to the constructor. It may be shared among several networks. A std::shared_ptr<T> is a convenient data structure to hold a storage.

Further, a network must expose the following compile-time constants:

static constexpr uint32_t min_fanin_size;
static constexpr uint32_t max_fanin_size;


The struct is_network_type can be used to check at compile time whether a given type contains all required types and constants to implement a network type. It should be used in the beginning of an algorithm that expects a network type:

template<typename Network>
void algorithm(Network const& ntk) {
static_assert(is_network_type_v<Network>, "Network is not a network type");
}


## Methods¶

### Constructors¶

template<typename GateType>
class network

### Qubits and Ancillae¶

template<typename GateType>
class network

Public Functions

io_id add_qubit(std::string const &label)

Creates a labeled qubit in the network and returns its io_id

io_id add_qubit()

Creates a unlabeled qubit in the network and returns its io_id

NOTE: Since all I/Os in a network must be labeled, this function will create a generic label with the form: qN, where N is the io_id.

### Structural properties¶

template<typename GateType>
class network

Public Functions

uint32_t size() const

Returns the number of nodes.

uint32_t num_qubits() const

Returns the number of qubits.

uint32_t num_gates() const

Returns the number of gates, i.e., nodes that hold unitary operations.

### Node iterators¶

template<typename GateType>
class network

Public Functions

template<typename Fn>
void foreach_qubit(Fn &&fn) const

Calls fn on every qubit in the network.

The paramater fn is any callable that must have one of the following three signatures.

• void(io_id id)

• void(string const& label)

• void(io_id id, string const& label)

template<typename Fn>
void foreach_input(Fn &&fn) const

Calls fn on every input node in the network.

The paramater fn is any callable that must have one of the following two signatures.

• void(node_type const& node)

• void(node_type const& node, uint32_t node_index)

template<typename Fn>
void foreach_output(Fn &&fn)

Calls fn on every output node in the network.

The paramater fn is any callable that must have one of the following two signatures.

• void(node_type const& node)

• void(node_type const& node, uint32_t node_index)

template<typename Fn>
void foreach_gate(Fn &&fn, uint32_t start = 0u) const

Calls fn on every unitrary gate node in the network.

The paramater fn is any callable that must have one of the following four signatures.

• void(node_type const& node)

• void(node_type const& node, uint32_t node_index)

• bool(node_type const& node)

• bool(node_type const& node, uint32_t node_index)

The paramater start is a index to a starting point.

If fn returns a bool, then it can interrupt the iteration by returning false.

template<typename Fn>
void foreach_node(Fn &&fn) const

Calls fn on every node in the network.

The paramater fn is any callable that must have one of the following four signatures.

• void(node_type const& node)

• void(node_type const& node, uint32_t node_index)

• bool(node_type const& node)

• bool(node_type const& node, uint32_t node_index)

If fn returns a bool, then it can interrupt the iteration by returning false.