simulator tools -> better create connections (#183)

* simulator tools -> better create connections

* changes according to PR

* simulator-tools - fixed tests, added readme, moved package

* Fixes from PR

CHANGELOG.md

@@ -4,8 +4,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 ## [Unreleased]
+### Added
+- simulator - ``create_simulator_controller_connections`` can now be used to create the connections between a subset of a large cluster.
+
 ### Changed
 - config/waveform_tools - Added sampling rate argument with default value set to 1GS/s to the waveforms.
+- simulator - ``create_simulator_controller_connections`` now creates the connections with a different algorithm that uses all available optical connections.
+- simulator - ``create_simulator_controller_connections`` order of input parameters has changed.
+
+### Deprecated
+- simulator - ``qualang_tools.simulator_tools`` has been deprecated and was moved to ``qualang_tools.simulator``.
 
 ## [0.16.0] - 2024-01-25
 ### Fixed

README.md

@@ -17,6 +17,7 @@ It includes:
 * [Analysis Tools](qualang_tools/analysis/README.md) - This library includes tools for analyzing data from experiments. 
 It currently has a two-states discriminator for analyzing the ground and excited IQ blobs.
 * [Multi-user tools](qualang_tools/multi_user/README.md) - This library includes tools for working with the QOP in a multi-user or multi-process setting.
+* [Simulator tools](qualang_tools/simulator/README.md) - This library includes tools for creating simulations.
 
 * [Bakery](qualang_tools/bakery/README.md) - This library introduces a new framework for creating arbitrary waveforms and
 storing them in the usual configuration file. It allows defining waveforms in a QUA-like manner while working with 1ns resolution (or higher).

qualang_tools/__init__.py

@@ -1,5 +1,5 @@
 __all__ = [
-    "simulator_tools",
+    "simulator",
     "bakery",
     "config",
     "control_panel",

qualang_tools/results/README.md

@@ -17,10 +17,10 @@ Then the results can be fetched with the `.fetch_all()` method while the program
 from qualang_tools.results import fetching_tool
 
 n_avg = 1000
-with program as prog:
+with program() as prog:
     # QUA program with n_avg averaging iterations
 
-qmm = QuantumMachinesManager(host="127.0.0.1", port="80")
+qmm = QuantumMachinesManager(host=qop_ip, port=qop_port, cluster_name=cluster_name)
 qm = qmm.open_qm(config)
 job = qm.execute(prog)
 

qualang_tools/simulator/README.md

@@ -0,0 +1,43 @@
+# Simulator tools
+This library includes tools to help simulate programs
+
+## create_simulator_controller_connections
+Creates a list of :class:`~qm.simulate.interface.ControllerConnection` objects with the Inter-controllers connections between controllers in a way which maximizes the optical links connectivity.
+For use inside the :class:`~qm.simulate.interface.SimulationConfig` for simulating the controllers' behavior.
+It can be used to also simulate part of a small cluster: For example, the following command would create all the connections
+needed to run a simulation on 'con1', 'con4', 'con5' which are part of a 9 OPX cluster: `create_simulator_controller_connections(9, [1,4,5])`
+
+### Usage example
+A simple example for a 3 OPX cluster:
+```python
+from qualang_tools.simulator import create_simulator_controller_connections
+
+with program() as prog:
+    # QUA program 
+
+qmm = QuantumMachinesManager(host=qop_ip, port=qop_port, cluster_name=cluster_name)
+job = qmm.simulate(config,
+                   prog,
+                   SimulationConfig(simulation_duration,
+                                    controller_connections=create_simulator_controller_connections(3)))
+```
+
+A simulation running on 'con1', 'con4', 'con5' which are part of a 9 OPX cluster, which also has loopback connected between the controllers:
+```python
+from qualang_tools.simulator import create_simulator_controller_connections
+
+with program() as prog:
+    # QUA program 
+
+qmm = QuantumMachinesManager(host=qop_ip, port=qop_port, cluster_name=cluster_name)
+job = qmm.simulate(config,
+                   prog,
+                   SimulationConfig(simulation_duration,
+                                    simulation_interface=LoopbackInterface([('con1', 1, 'con4', 1),
+                                                                            ('con1', 2, 'con4', 2),
+                                                                            ('con4', 1, 'con1', 1),
+                                                                            ('con4', 2, 'con1', 2),
+                                                                            ],
+                                                                           latency=168),
+                                    controller_connections=create_simulator_controller_connections(9, [1,4,5])))
+```

qualang_tools/simulator/__init__.py

@@ -0,0 +1,5 @@
+from qualang_tools.simulator.simulator import create_simulator_controller_connections
+
+__all__ = [
+    "create_simulator_controller_connections",
+]

qualang_tools/simulator/simulator.py

@@ -0,0 +1,54 @@
+import numpy as np
+from qm import ControllerConnection, InterOpxChannel
+
+
+def create_simulator_controller_connections(
+    n_controllers, actual_controllers=None, n_connections=12, print_debug=False
+):
+    """
+    Creates a list of :class:`~qm.simulate.interface.ControllerConnection` objects with the Inter-controllers
+    connections between controllers in a way which maximizes the optical links connectivity.
+    For use inside the :class:`~qm.simulate.interface.SimulationConfig` for simulating the controllers` behavior.
+
+    :param n_controllers: The number of controllers
+    :type n_controllers: int
+    :param actual_controllers: A list of the controllers actually being used in the simulation. For `con1` & `con2` use [1,2].
+    :type actual_controllers: List[int]
+    :param n_connections: The number of optical connectors each controller has, default is 12
+    :type n_connections: int
+    :param print_debug: If true, prints the connections to the terminal
+    :type print_debug: bool
+    :returns: The ControllerConnection object
+
+    """
+    if n_controllers == 1:
+        return []
+    if not actual_controllers:
+        actual_controllers = [i + 1 for i in range(n_controllers)]
+    controller_connections = []
+    unused_connection = np.ones((n_controllers, n_connections), dtype=bool)
+    while unused_connection.any():
+        for i in range(n_controllers):
+            for j in range(i + 1, n_controllers):
+                first_con_port = np.nonzero(unused_connection[i, :])[0]
+                if first_con_port.size == 0:
+                    break
+                first_con_port = first_con_port[0]
+                second_con_port = np.nonzero(unused_connection[j, :])[0]
+                if second_con_port.size == 0:
+                    break
+                second_con_port = second_con_port[0]
+                if i + 1 in actual_controllers and j + 1 in actual_controllers:
+                    controller_connections.append(
+                        ControllerConnection(
+                            InterOpxChannel(f"con{i+1}", first_con_port), InterOpxChannel(f"con{j+1}", second_con_port)
+                        )
+                    )
+                    if print_debug:
+                        print(f"con{i + 1}:{first_con_port} <-> con{j + 1}, {second_con_port}")
+                elif print_debug:
+                    print(f"con{i + 1}:{first_con_port} <-> con{j + 1}, {second_con_port} - Skipped")
+                unused_connection[i, first_con_port] = False
+                unused_connection[j, second_con_port] = False
+
+    return controller_connections

qualang_tools/simulator_tools.py

@@ -1,49 +1,14 @@
-from qm import ControllerConnection, InterOpxChannel
-
-
-def create_simulator_controller_connections(n_controllers, n_connections=12):
-    """
-    Creates a list of :class:`~qm.simulate.interface.ControllerConnection` objects with all of the Inter-controllers
-    connections according to the `recommended schema
-    <https://qm-docs.qualang.io/hardware/opx+installation#inter-controller-optical-connectivity-scheme>`__.
-    For use inside the :class:`~qm.simulate.interface.SimulationConfig` for simulating the controllers` behavior.
-
-    :param n_controllers: The number of controllers
-    :type n_controllers: int
-    :param n_connections: The number of optical connectors each controller has, default is 12
-    :type n_connections: int
-    :returns: The ControllerConnection object
-
-    """
-    if n_controllers == 1:
-        return None
-
-    ncbc = n_connections // (n_controllers - 1)  # ncbc = number_of_connections_between_controllers
-    n_connections = ncbc * (n_controllers - 1)
-    first_controller_list = []
-    first_port_list = []
-    second_controller_list = []
-    second_port_list = []
-    for i in range(n_controllers):
-        first_controller_list = first_controller_list + [i + 1] * (n_connections - i * ncbc)
-
-        first_port_list = first_port_list + [j for j in range(i * ncbc, n_connections)]
-
-        for j in range(i + 1, n_controllers):
-            second_controller_list = second_controller_list + [j + 1] * ncbc
-
-        second_port_list = second_port_list + [j for j in range(i * ncbc, (i + 1) * ncbc)] * (n_controllers - i - 1)
-
-    controller_connections = [
-        ControllerConnection(InterOpxChannel(f"con{i}", j), InterOpxChannel(f"con{k}", l))
-        for i, j, k, l in list(
-            zip(
-                first_controller_list,
-                first_port_list,
-                second_controller_list,
-                second_port_list,
-            )
-        )
-    ]
-
-    return controller_connections
+from qualang_tools.simulator import create_simulator_controller_connections
+import warnings
+
+__all__ = [
+    "create_simulator_controller_connections",
+]
+
+warnings.warn(
+    "The 'create_simulator_controller_connections' function has been moved to 'qualang_tools.simulator'.", FutureWarning
+)
+warnings.warn(
+    "The 'create_simulator_controller_connections' function has been moved to 'qualang_tools.simulator'.",
+    DeprecationWarning,
+)