Reference¶

Analyticnetwork module¶

Overview of the available classes.

`colna.analyticnetwork.Device`	Defines a device object for physical networks.
`colna.analyticnetwork.DeviceLink`	Defines a device link object for physical networks.
`colna.analyticnetwork.Edge`	Edges connect two nodes in a directed manner.
`colna.analyticnetwork.Network`	Networks consist of linear nodes and directed edges.
`colna.analyticnetwork.PhysicalNetwork`	Defines a physical network.
`colna.analyticnetwork.SymNum`	Symbolic number class.
`colna.analyticnetwork.Testbench`	Implements a Testbench.

Device¶

class colna.analyticnetwork.Device(name, devicetype='device', scattering_matrix=None, delay=None)[source]¶

Bases: colna.analyticnetwork.Network

Defines a device object for physical networks.

Device is a child class of network. It provides convenience methods to create the device from it’s complex scattering matrix (matrix describing input-output relation). Nodes are renamed automatically, based on the device type, device name and port/node number (‘devicetype:devicename:name’).

Parameters

scattering_matrix (numpy.array) – device scattering matrix, if both scattering_matrix and delay are provided, the device will be initalized with the corresponding scattering matrix and delay
delay (float) – device delay, if both scattering_matrix and delay are provided, the device will be initalized with the corresponding scattering matrix and delay
name (str) – name of the device
devicetype (str) – typename of the device

add_edge(edge)[source]¶

Add a new edge to the network

The start and end nodes of the edge must already exist in the network.

Parameters: edge (Edge) – the edge object to add
Raises: ValueError – If the start or end node of the edge does not exist in the network.

add_input(nodename, amplitude=1.0, phase=0.0, delay=0.0)[source]¶

Define an input point of the PhysicalNetwork.

The evaluation assumes signals with the given amplitude, phase and delay are propagating through the network from the given node when computing the analytical waveforms at each node.

Parameters

name (str) – name of the node that is to receive the input
amplitude (float) – amplitude of the input
phase (float) – phase of the input (relative to other inputs)
delay (float) – delay of the input (relative to other inputs)

Raises

ValueError – If the node with the provided name does not exist in the network.

add_node(nodename)[source]¶

Add a new node to the network

Parameters: name (str) – the name of the node

:raises ValueError : If a node with the same name already exists. :raises ValueError : If a nodename contains a colon (‘:’).

add_output(nodename)[source]¶

adds a node (by name) to the outputs of the physical network

Parameters: nodename (str) – name of the node to add to the outputs

init_from_phase_and_attenuation_matrix(attenuationmatrix, phasematrix, delay)[source]¶

Defines a device by its attenuation and phase matrix and a delay.

For a device with n inputs and m outputs pass a nxm matrix specifying attenuation and an nxm matrix specifiying phase-shift from input node i to output node j at matrix entry (i, j). Creates n+m nodes linked by n*m edges with the given parameters, all with time delay ‘delay’.

input node number k will be named ‘i+str(k)’ output node number k will be named ‘o+str(k)’

Use this method if you want to use symbolic numbers to define the phase and or amplitudes.

Parameters

attenuationmatrix (numpy.array) – matrix defining attenuation between input to output node
phasematrix (numpy.array) – matrix defining phase between input to output node
delay (float) – time delay from input to output

init_from_scattering_matrix(smatrix, delay=1.0)[source]¶

Defines a device by its complex scattering matrix and a delay

For a device with n inputs and m outputs pass a nxm complex matrix specifying attenuation and phase-shift from input node i to output node j at matrix entry (i, j). Creates n+m nodes linked by n*m edges with the given parameters, all with time delay ‘delay’. input node number k will be named ‘i+str(k)’ output node number k will be named ‘o+str(k)’

Warning

This method can not be used with SymNums. Use initialize_from_phase_and_attenuation_matrix() or define the nodes and edges manually instead.

Parameters

smatrix (numpy.array) – complex scattering matrix defining the input to output mapping
delay (float) – time delay from input to output

DeviceLink¶

class colna.analyticnetwork.DeviceLink(startdevice, enddevice, startnode, endnode, startdevicetype='device', enddevicetype='device', phase=0.4, attenuation=0.8, delay=1.0)[source]¶

Bases: colna.analyticnetwork.Edge

Defines a device link object for physical networks.

Device links are special edges that link devices. They are given the name of source and target device as well as source and target node within the device. Otherwise they function like the parent class Edge.

Parameters

startdevice (str) – name of the start device
enddevice (str) – name of the end device
startnode (str) – name of the node within the start device
endnode (str) – name of the node within the end device
startdevicetype (str) – name of the device type of startdevice (optional, defaults to ‘device’)
enddevicetype (str) – name of the device type of enddevice (optional, defaults to ‘device’)
phase (float) – phase shift of the device link
attenuation (float) – attenuation of the device link
delay (float) – time delay of the device link

Edge¶

class colna.analyticnetwork.Edge(start, end, phase=0.4, attenuation=0.8, delay=1.0)[source]¶

Bases: object

Edges connect two nodes in a directed manner.

Edges add a phase shift (\(\phi\)), delay (\(d\)) and attenuation (\(a\)) to the signal. The input to output relation of an edge is given by:

\[x_{out}(t) = a \cdot x_{in}(t-d) \cdot e^{j\phi}\]

Edge properties can be constant or symbolic numbers (variables).

Parameters

start (str) – name of start vertex connected by this edge
end (str) – name of end vertex connected by this edge
phase (float) – phase shift added by this element (stacks additively)
attenuation (float) – attenuation caused by element (stacks multiplicatively)
delay (float) – time delay added by this element (stacks additively)

Network¶

class colna.analyticnetwork.Network[source]¶

Bases: object

Networks consist of linear nodes and directed edges.

Networks are represented by a directed graph. COLNA computes all paths leading from input nodes to the output nodes (including recurrent paths) until the attenuation of each path falls below a given threshold.

Note

If a network contains recurrent paths (loops), the user must ensure that there is no gain in the network (i.e. attenuation < 1), otherwise the amplitude at the output will never fall below the threshold.

add_edge(edge)[source]¶

Add a new edge to the network

The start and end nodes of the edge must already exist in the network.

Parameters: edge (Edge) – the edge object to add
Raises: ValueError – If the start or end node of the edge does not exist in the network.

add_input(name, amplitude=1.0, phase=0.0, delay=0.0)[source]¶

Define an input point of the network.

The evaluation assumes signals with the given amplitude, phase and delay are propagating through the network from the given node when computing the analytical waveforms at each node.

Parameters

name (str) – name of the node that is to receive the input
amplitude (float) – amplitude of the input
phase (float) – phase of the input (relative to other inputs)
delay (float) – delay of the input (relative to other inputs)

Raises

ValueError – If the node with the provided name does not exist in the network.

add_node(name)[source]¶

Add a new node to the network

Parameters: name (str) – the name of the node
Raises: ValueError – If a node with the same name already exists.

evaluate(amplitude_cutoff=0.01, max_endpoints=100000, use_shared_default=True, feed_dict=None, hide_tqdm_progress=False)[source]¶

Evaluate the network.

The network evaluation method works by walking through the graph from all input nodes, along all possible paths. The evaluation of each path is stopped as soon as the total path amplitude falls below the amplitude_cutoff limit.

Parameters

amplitude_cutoff (float) – amplitude below which a wave is not further propagated through the network
max_endpoints (int) – evaluation is interrupted early, if more than max_endpoints exist in evaluation
use_shared_default (bool) – set to true if shared defaults should be used with SymNum’s (higher speed), set to false if the default value of each SymNum should be used instead (higher accuracy). Default: True
feed_dict (dict) – Feed dictionary for SymNum variables. Default: None

Returns

updates self.nodes_to_output a dictionary whose keys are node names. For each node name a list of quadruplets is given [(amplitude, phase, delay, path), (amplitude, phase, delay, path), …].

Note

Phases are simply added together and not reset to a finite range.

get_eval_result(name, feed_dict=None, use_shared_default=False)[source]¶

Returns a list of waves mixing at this node and evaluates symbolic numbers.

Parameters

name (str) – name of the node to get result from
use_shared_default (bool) – set to true if shared defaults should be used with SymNum’s (higher speed), set to false if the default value of each SymNum should be used instead (higher accuracy). Default: False
feed_dict (dict) – Feed dictionary for SymNum variables. Default: None

Returns

a list of waves mixing at this node, given as a tuple with entries (amplitude, phase, delay)

get_html_result(name, time_symbol='t', evaluate=False, feed_dict=None, use_shared_default=False, linebreak_limit=1, precision=0, path='out.html')[source]¶

Creates a html file with a rendered math equation describing all waves arriving at the given node.

Warning

To correctly render the equations in the browser, MathJax is required. The script is loaded automatically when you open the html file in a browser, if an internet connection is available.

Parameters

name (str or list) – Name of the node to get result from. If it is a list, results will be retrieved for all nodes in the list and compiled in a single html file.
time_symbol (str) – character used to describe time/delays in the equation
evaluate (bool) – If evaluate is True, SymNum’s will be evaluated using the feed_dict and use_shared_default values specified. Otherwise SymNums are represented by their name as variables.
feed_dict (dict) – a dictionary specifying values of variables by name. If only some variables are specified, for all other variables the default value will be used.
use_shared_default (bool) – set to true if shared defaults should be used with SymNums (higher speed) when no feed_dict is provided, set to false if the default value of each SymNum should be used instead (higher accuracy). The value is ignored if feed_dict is not None. Default: False
linebreak_limit (int) – A line break will be added roughly every linebreak_limit chars in the latex string. Set to 1 for a linebreak after each term. Set to 0 to get a latex string on a single line. Default: 1
path (str) – Output path where html file containing the MathJax code is stored. If the path does not exist it will be created automatically.
precision (int) – Number of significant digits to be output. Set to 0 to use the default value of str() method.

Raises

ValueError – If the node with the provided name does not exist in the network.
IOError – If the output file can not be created or accessed.

Returns

writes a html file at the given path

get_latex_result(name, time_symbol='t', evaluate=False, feed_dict=None, use_shared_default=False, linebreak_limit=0, precision=0)[source]¶

Returns a latex string that describes all waves arriving at the given node.

SymNums are shown as variables, unless evaluate is set to True.

Parameters

name (str) – Name of the node to get result from
time_symbol (str) – character used to describe time/delays in the equation
evaluate (bool) – If evaluate is True, SymNum’s will be evaluated using the feed_dict and use_shared_default values specified. Otherwise SymNums are represented by their name as variables.
feed_dict (dict) – a dictionary specifying values of variables by name. If only some variables are specified, for all other variables the default value will be used.
use_shared_default (bool) – set to true if shared defaults should be used with SymNums (higher speed) when no feed_dict is provided, set to false if the default value of each SymNum should be used instead (higher accuracy). The value is ignored if feed_dict is not None. Default: False
linebreak_limit (int) – A line break will be added roughly every linebreak_limit chars in the latex string. Set to 1 for a linebreak after each term. Set to 0 to get a latex string on a single line. Default: 1
precision (int) – Number of significant digits to be output. Set to 0 to use the default value of str() method.

Raises

ValueError – If the node with the provided name does not exist in the network.

Returns

a list of waves mixing at this node, given as a tuple with entries (amplitude, phase, delay)

get_paths(name)[source]¶

Find all paths leading to a node.

Parameters: name (str) – name of the node to get result from
Raises: ValueError – If the node with the provided name does not exist in the network.
Returns: all paths leading to a node

get_reduced_output(name, feed_dict=None, use_shared_default=False)[source]¶

Returns the output waves at this node. Paths with identical delay are added together.

Waves with same delay are combined into a single entry using linear superposition of phase and amplitude. Phase is reduced to cover only 2*pi range.

Parameters

name (str) – name of the node to get result from
use_shared_default (bool) – set to true if shared defaults should be used with SymNum’s (higher speed), set to false if the default value of each SymNum should be used instead (higher accuracy). Default: True
feed_dict (dict) – Feed dictionary for SymNum variables. Default: None

Returns

amplitude, phase, delay (all numpy arrays)

get_result(name)[source]¶

Returns a list of waves mixing at this node

Parameters: name (str) – name of the node to get result from
Raises: ValueError – If the node with the provided name does not exist in the network.
Returns: a list of waves mixing at this node, given as a tuple with entries (amplitude, phase, delay)

get_result_np(name)[source]¶

Returns a result at a given node as numpy array

Parameters: name (str) – name of the node to get result from
Raises: ValueError – If the node with the provided name does not exist in the network.
Returns: x; x[0]: amp, x[1]: phase, x[2]: delay

print_stats()[source]¶

Prints some statistics of the evaluated network

Currently this prints the number of evaluated path. In future implementations the statistics method might be enhanced.

static stopping_criterion(amplitude, cutoff)[source]¶

Stopping criterion

Used together with network evaluation. If the stopping criterion is fulfilled, the analysis of the current path is stopped.

Parameters

amplitude (float) – current amplitude
cutoff (float) – threshold for cutoff criterion

Returns

True if amplitude is less than cutoff, otherwise False.

visualize(show_edge_labels=True, path='network', skip_colon=False, format='pdf')[source]¶

Visualize the network

Parameters

show_edge_labels (bool) – if True, edge labels showing the amplitude, phase and delay of the edge are drawn.
path (str) – output path for file. If the path does not exist it will be created automatically.
skip_colon (bool) – Skip nodes which contain ‘:’ in their name. This is used for PhysicalNetwork visualization.
format (str) – output format (supports all format options of Graphviz), e.g. ‘pdf’, ‘svg’

Returns

Writes a dot file at the given path and renders it to the desired output format using graphviz.

Returns

Returns the path to the file (can be relative).

PhysicalNetwork¶

class colna.analyticnetwork.PhysicalNetwork[source]¶

Bases: colna.analyticnetwork.Network

Defines a physical network.

Extension of the Network class that allows for a more natural implementation of physical networks using a description as a collection of devices, device links, input and output sites.

add_device(device)[source]¶

Adds a device to the network

Adds all nodes, edges, inputs and outputs of the device to the network.

Parameters: device (Device) – device to be added to the network

add_devicelink(devicelink)[source]¶

Adds a device link to the network

Parameters: devicelink (DeviceLink) – the device link to be added
Raises: ValueError – If either the start or end nodes of the devicelink do not exist.

get_outputs()[source]¶

Get the computed wave forms at all output sites

Returns: a list of the output waves at all output nodes

visualize(show_edge_labels=True, path='network.gv', format='pdf', full_graph=False)[source]¶

Visualizes the network

Parameters

show_edge_labels (bool) – if True, edge labels showing the amplitude, phase and delay of the edge are drawn.
path (str) – output path for file
format (str) – output format (supports all format options of Graphviz), e.g. ‘pdf’, ‘svg’

Returns

Writes a dot file at the given path and renders it to the desired output format using graphviz.

Returns

Returns the path to the file (can be relative).

SymNum¶

class colna.analyticnetwork.SymNum(name, default=0.9, product=True, numerical=None)[source]¶

Bases: object

Symbolic number class.

Symbolic numbers can be used for all edge properties in analytic networks.

Parameters

name (str) – the name of the variable. The name should be unique for each SymNum present in the network.
default (float) – the default value substituted, when we evaluate this variable. Default = 0.9
product (bool) – whether this variable is composed as a product (True) or a sum (False). Product is used to distinguish attenuations (stacking multiplicatively) and phases / delays (stacking additively). Default: True
numerical (float or None) – initial value of numerical part (numerical factor for product variables, numerical addition for additive variables). Can be set to none for automatic initialization (1.0 for product variables, 0.0 for additive variables). Default: None

eval(feed_dict=None, verbose=False, use_shared_default=True)[source]¶

Evaluate the numerical value of the number

Parameters

feed_dict (dict) – a dictionary specifying values of variables by name. If only some variables are specified, for all other variables the default value will be used.
verbose (bool) – print the number in symbolic form before returning
use_shared_default (bool) – set to true if shared defaults should be used with SymNums (higher speed) when no feed_dict is provided, set to false if the default value of each SymNum should be used instead (higher accuracy). The value is ignored if feed_dict is not None. Default: True

Returns

numerical value of the number (float)

to_latex(precision=0)[source]¶

Testbench¶

class colna.analyticnetwork.Testbench(network: colna.analyticnetwork.Network, timestep=1, disable_progress_bars=True, feed_dict=None)[source]¶

Bases: object

Implements a Testbench.

Calculates the resulting output sequence for a given input signal sequence.

Parameters

timestep (float) – timestep on which the network output signal is evaluated. All delays in the network and of the input signal period should be an integer multiple of the timestep.
network (Network) – network where signals should be applied

add_const_output(bias)[source]¶

Adds a constant bias signal to the output vector.

Parameters: bias (float) – value of constant output bias signal

add_input_sequence(node_name, x, t)[source]¶

Add input signal sequence to a node

Parameters

name (str) – the name of the node that receives the signal
x (numpy.array) – input signal (complex), dimension: 1xN
t (numpy.array) – time of signal, if none we assume that the signal vector provides the signal at each time step. The value x[n] is applied to the input Node during the right-open time interval [t[n], t[n+1]), dimension: 1x(N+1). Time values must be in increasing order.

Raises

ValueError – If the dimensions of signal and time vector do not match
ValueError – If the node does not exist in the network.
OverflowError – If more than one input sequence is added to a single node.

add_output_node(node_name)[source]¶

Add an output node by name.

Output signals are calculated at each output node.

Parameters: name (str) – the name of the node

calculate_output(use_shared_default=False, n_threads=0)[source]¶

Calculates the output signals for the given input signals.

self.feed_dict is used as the feed dictionary.

Parameters

use_shared_default (bool) – set to true if shared defaults should be used with SymNum’s (higher speed), set to false if the default value of each SymNum should be used instead (higher accuracy). Default: False
n_threads (int) – Number of threads that are used for evaluation (set to 0 to disable multithreading)

Raises

ValueError – If the output node does not exist.

calculate_output_sequence(node_name, use_shared_default=False)[source]¶

Calculates the output sequence at a given node.

The output sequence is calculated for the input sequence(s) added prior to executing this method to the testbench. self.feed_dict is used as the feed dictionary.

Note

Before executing make sure evaluate_network() was executed.

Parameters

node_name (str) – Name of node for which the output is returned.
use_shared_default (bool) – set to true if global defaults should be used with SymNum’s (higher speed) when no feed_dict is provided, set to false if the default value of each SymNum should be used instead (higher accuracy). The value is ignored if feed_dict is not none. Default: False

Returns

tuple containing time and signal vector at the given output node

Return type

tuple of numpy.array

clear_inputoutput()[source]¶

Clears the input and output lists.

The input and output lists store the input nodes together with the corresponding input signals and the output node names.

evaluate_network(amplitude_cutoff=0.001, max_endpoints=1000000.0, use_shared_default=True)[source]¶

Evaluate the network.

Uses the Network.evaluate() method, self.feed_dict is used as a feed dictionary.

Parameters

amplitude_cutoff (float) – amplitude below which a wave is not further propagated through the network
max_endpoints (int) – evaluation is interrupted early, if more than max_endpoints exist in evaluation
use_shared_default (bool) – set to true if shared defaults should be used with SymNum’s (higher speed), set to false if the default value of each SymNum should be used instead (higher accuracy). Default: True

set_feed_dict(feed_dict)[source]¶

Sets the feed dict.

Parameters: feed_dict (dict) – a dictionary specifying values of variables by name. If only some variables are specified, for all other variables the default value will be used.

Lossconversion module¶

`colna.lossconversion.attenuation_to_dBcm`	Converts attenuation to dB/cm
`colna.lossconversion.attenuation_to_loss_per_meter`	Converts attenuation to loss per meter
`colna.lossconversion.dBcm_to_attenuation`	Converts dB/cm to attenuation
`colna.lossconversion.dBcm_to_loss_per_m`	Converts dB/cm to loss per meter (alpha)
`colna.lossconversion.loss_per_m_to_dBcm`	Converts loss per meter (alpha) to dB/cm
`colna.lossconversion.loss_per_meter_to_attenuation`	Converts loss per meter to attenuation

Convenience module that contains functionality do convert optical propagation loss between different units.

colna.lossconversion.attenuation_to_dBcm(attenuation, length)[source]¶

Converts attenuation to dB/cm

Parameters

attenuation (float) – Attenuation
length (float) – propagation distance in meters

Returns

loss in dB/cm

Return type

float

colna.lossconversion.attenuation_to_loss_per_meter(attenuation, length)[source]¶

Converts attenuation to loss per meter

Parameters

attenuation (float) – Attenuation
length (float) – propagation distance in meters

Returns

loss per meter

Return type

float

colna.lossconversion.dBcm_to_attenuation(dBcm, length)[source]¶

Converts dB/cm to attenuation

Parameters

dBcm (float) – Loss in dB/cm
length (float) – propagation distance in meters

Returns

Attenuation value

Return type

float

colna.lossconversion.dBcm_to_loss_per_m(dBcm)[source]¶

Converts dB/cm to loss per meter (alpha)

Parameters: dBcm (float) – Loss in dB/cm
Returns: Loss per meter (alpha)
Return type: float

colna.lossconversion.imag_index_to_dBcm(k, wavelength)[source]¶

Converts complex part of effective index to loss in dB/cm

Parameters

k (float) – complex part of mode index (neff = n+ik)
wavelength (float) – in m

Returns

loss in dB/cm

Type

float

colna.lossconversion.loss_per_m_to_dBcm(loss_per_m)[source]¶

Converts loss per meter (alpha) to dB/cm

Parameters: loss_per_m (float) – Loss per meter (alpha)
Retursn: Loss in dB/cm
Return type: float

colna.lossconversion.loss_per_meter_to_attenuation(loss_per_m, length)[source]¶

Converts loss per meter to attenuation

Parameters

loss_per_m (float) – Loss per meter (alpha)
length (float) – propagation distance in meters

Returns

Attenuation value

Return type

float