1.2. PyRates.pyrates.ir

1.2.1. pyrates.ir module (intermediate representation)

This module contains classes relevant for the intermediate representation (IR) in PyRates. All variations of PyRates frontends should produce valid instances of IR classes defined in this module and all backends should accept only these instances as input. Thus the intermediate representation is assumed to be consistent across different frontends and backends.

1.2.2. pyrates.ir.abc module

class pyrates.ir.abc.AbstractBaseIR(label: str, template: str | None = None)

Bases: object

Abstract base class for intermediate representation classes

__getitem__(key: str)

Custom implementation of __getitem__ that dissolves strings of form “key1/key2/key3” into lookups of form self[key1][key2][key3].

Parameters:

key –

Return type:

item

classmethod from_file(filename: str, filetype: str = 'pickle', error_on_instance_check: bool = True)

Load an IR instance from file. The function verifies that the loaded object is indeed an instance of the class this function was called from.

Parameters:

• filename – Path to file (relative or absolute)

• filetype – Indicate which file type to expect

• error_on_instance_check – Toggle whether or not to raise an error if the instance check fails.

Return type:

Any

getitem_from_iterator(key: str, key_iter: Iterator[str])

Invoked by __getitem__ or [] slicing. Needs to be implemented in subclass.

label

property template

to_file(filename: str, filetype: str = 'pickle', template_name: str | None = None) → None

Save an IR object to file. The filetype ‘pickle’ save the object as is to a file, whereas the ‘yaml’ option creates a template from the IR object. In the latter case you need to define a template_name that is used in the YAML file.

Parameters:

• filename – Path to file (absolute or relative).

• filetype – Chooses which loader to use to load the file. Allowed types: pickle, yaml

• template_name – This is required for the ‘yaml’ format, in order to define the name of the newly created template.

Return type:

None

1.2.3. pyrates.ir.circuit module

class pyrates.ir.circuit.CircuitIR(label: str = 'circuit', nodes: Dict[str, NodeIR] | None = None, edges: list | None = None, template: str | None = None, step_size_adaptation: bool = False, step_size: float | None = None, verbose: bool = True, backend: str | None = None, scalar_shape: tuple | None = None, **kwargs)

Bases: AbstractBaseIR

Custom graph data structure that represents a backend of nodes and edges with associated equations and variables.

clear()

Clears the backend graph from all operations and variables.

property edges

Shortcut to self.graph.edges. See documentation of networkx.MultiDiGraph.edges.

get_frontend_varname(var: str) → str

Returns the original frontend variable name given the backend variable name var.

Parameters:

var – Name of the backend variable.

Returns:

Name of the frontend variable

Return type:

str

get_run_func(func_name: str, file_name: str | None = None, **kwargs) → tuple

get_var(var: str, get_key: bool = False) → str | ComputeVar

Extracts variable from the backend (i.e. the ComputeGraph instance).

Parameters:

• var – Name of the variable.

• get_key – If true, the backend variable name will be returned

Returns:

Either the backend variable or its name.

Return type:

Union[str, ComputeVar]

getitem_from_iterator(key: str, key_iter: Iterator[str])

Invoked by __getitem__ or [] slicing. Needs to be implemented in subclass.

graph

label

network_to_computegraph(graph: NetworkGraph, inplace_vectorfield: bool = True, **kwargs)

property nodes

Shortcut to self.graph.nodes. See documentation of networkx.MultiDiGraph.nodes.

run(simulation_time: float, outputs: dict | None = None, sampling_step_size: float | None = None, solver: str = 'euler', **kwargs) → dict

Simulate the backend behavior over time via a tensorflow session.

Parameters:

• simulation_time – Simulation time in seconds.

• outputs – Output variables that will be returned. Each key is the desired name of an output variable and each value is a string that specifies a variable in the graph in the same format as used for the input definition: ‘node_name/op_name/var_name’.

• sampling_step_size – Time in seconds between sampling points of the output variables.

• solver – Numerical solving scheme to use for differential equations. Currently supported ODE solving schemes: - ‘euler’ for the explicit Euler method - ‘scipy’ for integration via the scipy.integrate.solve_ivp method.

• kwargs – Keyword arguments that are passed on to the chosen solver.

Returns:

Output variables in a dictionary.

Return type:

dict

class pyrates.ir.circuit.NetworkGraph(label: str = 'circuit', nodes: Dict[str, NodeIR] | None = None, edges: list | None = None, template: str | None = None, step_size: float = 0.001, step_size_adaptation: bool = True, verbose: bool = True, **kwargs)

Bases: AbstractBaseIR

View on the entire network as a graph. Translates edge operations and attributes into a form that allows to parse the network graph into a final compute graph.

__getitem__(key: str)

Custom implementation of __getitem__ that dissolves strings of form “key1/key2/key3” into lookups of form self[key1][key2][key3].

Parameters:

key –

Return type:

item

add_edge(source: str, target: str, edge_ir: EdgeIR | None = None, weight: float = 1.0, delay: float | None = None, spread: float | None = None, **data)

Parameters:

• source –

• target –

• edge_ir –

• weight –

• delay –

• spread –

• data – If no template is given, data is assumed to conform to the format that is needed to add an edge. I.e., data needs to contain fields for weight, delay, edge_ir, source_var, target_var.

property edges

Shortcut to self.graph.edges. See documentation of networkx.MultiDiGraph.edges.

getitem_from_iterator(key: str, key_iter: Iterator[str])

Invoked by __getitem__ or [] slicing. Needs to be implemented in subclass.

label

property nodes

Shortcut to self.graph.nodes. See documentation of networkx.MultiDiGraph.nodes.

1.2.4. pyrates.ir.node module

class pyrates.ir.node.NodeIR(label: str, operators: OperatorGraph, values: dict | None = None, template: str | None = None)

Bases: AbstractBaseIR

__iter__()

Return an iterator containing all operator labels in the operator graph.

getitem_from_iterator(key: str, key_iter: Iterator[str])

Alias for self.op_graph.getitem_from_iterator

property op_graph

property operators

values

class pyrates.ir.node.VectorizedNodeIR(label: str, operators: OperatorGraph, values: dict | None = None, template: str | None = None)

Bases: AbstractBaseIR

Alternate version of NodeIR that takes a full NodeIR as input and creates a vectorized form of it.

__iter__()

Return an iterator containing all operator labels in the operator graph.

__len__()

Returns size of this vector node as recorded in self._length.

Return type:

self._length

add_op(op_key: str, inputs: dict, output: str, equations: list, variables: dict)

Wrapper for internal op_graph.add_operator that adds any values to node-level values dictionary for quick access

Parameters:

• op_key – Name of operator to be added

• inputs – dictionary definining input variables of the operator

• output – string defining name of single output variable

• equations – list of equations (strings)

• variables – dictionary describing variables

add_op_edge(source_op_key: str, target_op_key: str, **attr)

Alias to self.op_graph.add_edge

Parameters:

• source_op_key –

• target_op_key –

• attr –

extend(node: NodeIR) → dict

Extend variables vectors by values from one additional node.

Parameters:

node – A node whose values are used to extend the vector dimension of this vectorized node.

Returns:

Dictionary containing the indices of the appended variable values in the overall vectorized variables.

Return type:

dict

getitem_from_iterator(key: str, key_iter: Iterator[str])

Alias for self.op_graph.getitem_from_iterator

length

op_graph

property operators

pyrates.ir.node.cache_func(label: str, operators: dict, values: dict | None = None, template: str | None = None, ir_class: Callable | None = None, **kwargs)

pyrates.ir.node.clear_ir_caches()

1.2.5. pyrates.ir.edge module

class pyrates.ir.edge.EdgeIR(label: str, operators: OperatorGraph | None = None, values: dict | None = None, template: str | None = None)

Bases: VectorizedNodeIR

get_inputs()

Find all input variables of operators that need to be mapped to source variables in a source node.

property inputs

Detect input variables of edge. This also references the operator the variable belongs to.

Note: As of 0.9.0 multiple source/input variables are allowed per edge.

length

property n_inputs

Computes number of input variables that need to be informed from outside the edge (meaning from some node).

op_graph

property output

Detect output variable of edge, assuming only one output variable exists.

1.2.6. pyrates.ir.operator module

class pyrates.ir.operator.OperatorIR(equations: List[str], variables: List[tuple], inputs: List[str], output: str, template: str | None = None)

Bases: AbstractBaseIR

This implementation of the Operator IR is aimed to be hashable and immutable. Following Python standards, we assume that users are consenting adults. Objects are thus not actually immutable, just slightly protected. This might change in the future.

property equations

getitem_from_iterator(key: str, key_iter: Iterator[str])

Checks if a variable named by key exists in an equations. :param key: :param key_iter:

Return type:

key

property inputs

property output

property variables

class pyrates.ir.operator.ProtectedVariableDict(variables: List[tuple])

Bases: object

Hashable dictionary-like object as container for variable definitions. It does not support item assignment after creation, but is strictly speaking not immutable. There may also be faster implementations, but this works for now.

add_parsed_variable(key, props)

Add parsed representation to a variable from compilation.

items()

keys()

to_dict()

values()

class pyrates.ir.operator.Variable(vtype, dtype, shape)

Bases: tuple

dtype

Alias for field number 1

shape

Alias for field number 2

vtype

Alias for field number 0

1.2.7. pyrates.ir.operator_graph module

class pyrates.ir.operator_graph.OperatorGraph(operators: Dict[str, OperatorIR] | None = None, template: str = '')

Bases: DiGraph

Intermediate representation for nodes and edges.

__iter__()

Return an iterator containing all operator labels in the operator graph.

getitem_from_iterator(key: str, key_iter: Iterator[str])

Helper function for Python magic __getitem__. Accepts an iterator that yields string keys. If key_iter contains one key, an operator will be (looked for and) returned. If it instead contains two keys, properties of a variable that belong to an operator is returned.

Parameters:

• key –

• key_iter –

Returns:

operator or variable properties

Return type:

item

operators(get_ops=False, get_vals=False)

Alias for self.nodes

class pyrates.ir.operator_graph.VectorizedOperatorGraph(op_graph: OperatorGraph | None = None, values: dict | None = None)

Bases: DiGraph

Alternate version of OperatorGraph that is produced during vectorization. Contents of this version are not particularly protected and the instance is not cached.

add_operator(*args, **kwargs)

Alias for self.add_node

append_values(value_dict: dict) → dict

Append value along vector dimension of operators.

Parameters:

value_dict –

Returns:

Dictionary containing the indices of the appended variable values in the overall vectorized variables.

Return type:

dict

getitem_from_iterator(key: str, key_iter: Iterator[str])

Helper function for Python magic __getitem__. Accepts an iterator that yields string keys. If key_iter contains one key, an operator will be (looked for and) returned. If it instead contains two keys, properties of a variable that belong to an operator is returned.

Parameters:

• key –

• key_iter –

Returns:

operator or variable properties

Return type:

item

property operators

Alias for self.nodes

property var_lengths: dict

Dictionary containing the length of each variable of each operator.