Update documentation of the simulaqron.sdk package

Author: dieriver

docs/simulaqron.sdk.rst

@@ -1,19 +1,32 @@
 simulaqron.sdk package
 ======================
 
-.. warning:: UPDATE THIS STRUCTURE!
-
 Submodules
 ----------
 
-simulaqron.run.run module
+simulaqron.sdk.broadcast_channel module
+-------------------------
+
+.. automodule:: simulaqron.sdk.broadcast_channel
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+simulaqron.sdk.connection module
 -------------------------
 
-.. automodule:: simulaqron.run.run
+.. automodule:: simulaqron.sdk.connection
     :members:
     :undoc-members:
     :show-inheritance:
 
+simulaqron.sdk.socket module
+-------------------------
+
+.. automodule:: simulaqron.sdk.socket
+    :members:
+    :undoc-members:
+    :show-inheritance:
 
 Module contents
 ---------------

simulaqron/sdk/broadcast_channel.py

@@ -4,4 +4,9 @@
 
 
 class BroadcastChannel(BroadcastChannelBySockets):
+    """
+    Implement a Broadcast channel over sockets
+
+    .. warning:: This class is candidate to be deleted. Test and delete if possible!
+    """
     _socket_class = Socket

simulaqron/sdk/connection.py

@@ -48,6 +48,30 @@ def __init__(
             conn_retry_time: float = 0.1,
             network_name: str = "default",
     ):
+        """
+        Main class representing the connection from NetQASM to the SimulaQron simulator.
+        This class implements the
+
+        :param app_name: Name of the app to run.
+        :type app_name: str
+        :param app_id: The ID of the application. If not given, a new one will be created.
+        :type app_id: int | None
+        :param max_qubits: Maximum number of qubits tu simulate in the simulator.
+        :type max_qubits: int
+        :param log_config: Configuration of the logging. Check the documentation of
+                           ``netqasm.sdk.config.LogConfig`` for more information about this.
+        :type log_config: LogConfig
+        :param epr_sockets: List of ``EPRSocket``s to use in the simulator.
+        :type epr_sockets: List[EPRSocket]
+        :param compiler: A transpiler object that transpiles the NetQASM instructions.
+        :type compiler: Type[SubroutineTranspiler] | None
+        :param socket_address: A tuple containing a hostname and port to use to connect to the QNodeOS server.
+        :type socket_address: Tuple[str, int]
+        :param conn_retry_time: Maximum time in seconds to wait between attempts to connect to the QNoseOS server.
+        :type conn_retry_time: float
+        :param network_name: The name of the network to connect to
+        :type network_name: str
+        """
         super().__init__(
             app_name=app_name,
             # NOTE currently node_name and app_name are the same in simulaqron
@@ -98,6 +122,21 @@ def try_connection(
             socket_address: Optional[Tuple[str, int]] = None,
             network_name: str = "default",
     ):
+        """
+        Try to establish a connection to the specified node name. The connection can be made
+        by specifying the ``socket_address`` tuple (as a hostname and port number tuple) or
+        by specifying the node and network names. In the latter case, SimulaQron will search
+        for that node and network names on the loaded network configuration, and get the
+        corresponding socket configuration (hostname and port number) to connect to.
+
+        :param name: The name of the node to connect to.
+        :type name: str
+        :param socket_address: A hostname-port pair to specify the hostname and port number
+                               to connect to. This argument is optional.
+        :type socket_address: Tuple[str, int] | None
+        :param network_name: The name of the network to search the node name.
+        :type network_name: str
+        """
         # NOTE using retry_time=None causes an error to be raised of the connection cannot
         # be established, which can be used to check if the connection is available
         logger.debug("Trying if connection is up yet")
@@ -325,6 +364,9 @@ def _handle_reply(self) -> int:
                     raise NotImplementedError(f"Unknown return message of type {type(ret_msg)}")
 
     def block(self):
+        """
+        Blocks the handling of new messages until all the pending message IDs are acknowledged.
+        """
         while len(self._waiting_msg_ids) > 0:
             self._logger.debug(
                 "Blocking and waiting for msg IDs %s", self._waiting_msg_ids
@@ -417,6 +459,15 @@ class GetQubitStateMessage(Message):
     TYPE = NewMessageType.GET_QUBIT_STATE
 
     def __init__(self, app_id: int = 0, qubit_id: int = 0):
+        """
+        Implements a specific NetQASM message to get the state of a qubit from the
+        SimulaQron simulator.
+
+        :param app_id: The app ID to get the qubit from.
+        :type app_id: int
+        :param qubit_id: The qubit ID to retrieve the state.
+        :type qubit_id: int
+        """
         super().__init__(self.TYPE.value)
         self.app_id = app_id
         self.qubit_id = qubit_id
@@ -431,8 +482,6 @@ class NewReturnMessageType(Enum):
 
 
 class RichErrorMessage(ReturnMessage):
-    """Enriched message to the Host that an error occurred at the quantum node controller."""
-
     _fields_ = [
         ("err_code", ctypes.c_uint8),
         ("err_msg_len", ctypes.c_uint32),
@@ -443,6 +492,14 @@ class RichErrorMessage(ReturnMessage):
     TYPE = NewReturnMessageType.ERR
 
     def __init__(self, err_code: ErrorCode, err_msg: str):
+        """
+        Enriched message to the Host that an error occurred at the quantum node controller.
+
+        :param err_code: The error code to report.
+        :type err_code: ErrorCode
+        :param err_msg: The error message.
+        :type err_msg: str
+        """
         super().__init__(self.TYPE.value)
         err_bytes = err_msg.encode("utf-8")
         if len(err_bytes) > MAX_ERR_MSG_LEN:
@@ -471,6 +528,16 @@ class ReturnQubitStateMessage(ReturnMessage):
     TYPE = NewReturnMessageType.RET_QUBIT_STATE
 
     def __init__(self, qubit_id: int, real_part: List[List[float]], imag_part: List[List[float]]):
+        """
+        Specific NetQASM message used to transmit the qubit state back to the application.
+
+        :param qubit_id: The qubit ID.
+        :type qubit_id: int
+        :param real_part: The real part of the qubit state.
+        :type real_part: List[List[float]]
+        :param imag_part: The imaginary part of the qubit state.
+        :type imag_part: List[List[float]]
+        """
         super().__init__(self.TYPE.value)
 
         # Sanity checks - given matrices are square
@@ -558,12 +625,26 @@ def _get_node_name(cls, node_id: int) -> str:
 
     @classmethod
     def get_node_id_for_app(cls, app_name: str) -> int:
-        """Returns the node id for the app with the given name"""
+        """
+        Returns the node id for the app with the given name.
+
+        :param app_name: The app name.
+        :type app_name: str
+        :return: The node ID.
+        :rtype: int
+        """
         # NOTE app_name and node_name are for now the same in simulaqron
         return cls._get_node_id(node_name=app_name)
 
     @classmethod
     def get_node_name_for_app(cls, app_name: str) -> str:
-        """Returns the node name for the app with the given name"""
+        """
+        Returns the node name for the app with the given name.
+
+        :param app_name: The app name.
+        :type app_name: str
+        :return: The node name.
+        :rtype: str
+        """
         # NOTE app_name and node_name are for now the same in simulaqron
         return app_name

simulaqron/sdk/socket.py

@@ -44,21 +44,42 @@ def __del__(self):
         self.close()
 
     def close(self):
+        """
+        Closes this socket. Mo more messages can be sent or received after
+        invoking this method.
+        """
         if self._app_socket:
             self._app_socket.close()
 
     def send(self, msg: str):
-        """Sends a message to the remote node."""
+        """
+        Sends a message to the remote node.
+
+        :param msg: The message to send.
+        :type msg: str
+        """
         self._logger.debug("Sending msg '%s'", msg)
         raw_msg = self._serialize_msg(msg=msg)
         self._app_socket.send(raw_msg)
 
     def send_structured(self, msg: StructuredMessage):
+        """
+        Sends a message to the remote node as a ``StructuredMessage`` object.
+
+        :param msg: The message to send.
+        :type msg: StructuredMessage
+        """
         self._logger.debug("Sending structured msg '%s'", msg)
         raw_msg = self._serialize_structured_msg(msg=msg)
         self._app_socket.send(raw_msg)
 
     def send_silent(self, msg: str):
+        """
+        Sends a message to the remote node without logging it.
+
+        :param msg: The message to send.
+        :type msg: str
+        """
         self.send(msg)
 
     def _base_recv(self, block: bool, timeout: float, maxsize: int) -> bytes:
@@ -80,7 +101,18 @@ def recv(
             timeout: Optional[float] = None,
             maxsize: Optional[int] = 1024
     ) -> str:
-        """Receive a message from the remote node."""
+        """
+        Receive a message from the remote node.
+
+        :param block: Whether the underlying read operation should be blocking or not.
+        :type block: bool
+        :param timeout: Max time (in seconds) to wait for a message from the remote.
+        :type timeout: float | None
+        :param maxsize: Maximum size of bytes to read from the remote.
+        :type maxsize: int | None
+        :return: The received message as a string.
+        :rtype: str
+        """
         self._logger.debug("Receiving msg")
         raw_msg = self._base_recv(block, timeout, maxsize)
         msg = self._deserialize_msg(raw_msg=raw_msg)
@@ -93,6 +125,18 @@ def recv_structured(
             timeout: Optional[float] = None,
             maxsize: Optional[int] = 1024,
     ) -> StructuredMessage:
+        """
+        Receives a message from the remote node and parses it as a ``StructuredMessage``.
+
+        :param block: Whether the underlying read operation should be blocking or not.
+        :type block: bool
+        :param timeout: Max time (in seconds) to wait for a message from the remote.
+        :type timeout: float | None
+        :param maxsize: Maximum size of bytes to read from the remote.
+        :type maxsize: int | None
+        :return: The parsed message.
+        :rtype: StructuredMessage
+        """
         self._logger.debug("Receiving structured msg")
         raw_msg = self._base_recv(block, timeout, maxsize)
         msg = self._deserialize_structured_msg(raw_msg=raw_msg)
@@ -105,6 +149,20 @@ def recv_silent(
             timeout: Optional[float] = None,
             maxsize: Optional[int] = None,
     ) -> str:
+        """
+        Receives a message without logging it. All arguments passed to this
+        invocation are ignored. For more fine-grain control, please check the
+        :py:meth:`recv` method.
+
+        :param block: Ignored
+        :type block: bool
+        :param timeout: Ignored
+        :type timeout: float | None
+        :param maxsize: Ignored
+        :type maxsize: int | None
+        :return: The received message.
+        :rtype: str
+        """
         return self.recv()
 
     @staticmethod
@@ -125,6 +183,15 @@ def _deserialize_structured_msg(raw_msg: bytes) -> StructuredMessage:
 
     @property
     def is_server(self) -> bool:
+        """
+        Check whether the local end of this socket will be acting as server or not. The decision
+        is made based on the node names: the name which is alphabetically before will act as server.
+        For example: If the socket connects "Alice" with "Bob", "Alice" will act as server, since
+        the string "Alice" comes lexicographically before the string "Bob".
+
+        :return: Whether this end of the socket should act as server or not.
+        :rtype: bool
+        """
         # Server will always be the "first"
         return self._node_name < self._remote_node_name