Add template for creating client-server applications using the new SDK

Author: dieriver

examples/new-sdk/classical-client-server/doNew.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+
+./terminate.sh
+./run.sh

examples/new-sdk/classical-client-server/terminate.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env sh
+TEST_PIDS=$(ps aux | grep python | grep -E "example" | awk {'print $2'})
+if [ "$TEST_PIDS" != "" ]
+then
+        kill -9 $TEST_PIDS
+fi
+
+# Check if SimulaQron is running
+if [ -f ~/.simulaqron_pids/simulaqron_network_default.pid ]; then
+    if ! simulaqron stop
+    then
+        # Kill the process, only if simulaqron could not be stopped gracefully
+        cat $HOME/.simulaqron_pids/simulaqron_network_default.pid | xargs kill -9
+    fi
+fi
+

examples/new-sdk/teleport/README.md

@@ -12,20 +12,11 @@ First of all, make sure you are not already running existing simulaqron programs
 You can run
 
 ```shell
-simulaqron stop
-sh terminate.sh
+./terminate.sh
 ```
 
-which should get rid of all things running for the teleport example itself. If you want to be a bit
-more radical and confident you are not running other things to preserve you can run:
-
-```shell
-simulaqron stop
-pkill -9 python
-```
-
-This will kill ALL python processes run by you so beware.  If you have a debugging enabled, you may also
-wish to wipe old log files by running:
+which should get rid of all things running for the teleport example itself. If you have a
+debugging enabled, you may also  wish to wipe old log files by running:
 
 ```shell
 rm /tmp/simulaqron*
@@ -35,16 +26,10 @@ This should leave you a clear slate. We can now start the application.
 
 
 ## On a single machine
-If you are running everything on the same machine, first we start the simulaqron backend by typing
-
-```shell
-simulaqron start --node Alice,Bob
-```
-
-This needs to be done only once. Now type
+If you are running everything on the same machine, simply type:
 
 ```shell
-sh run.sh
+./run.sh
 ```
 
 WARNING: It seems restarting the simulaqron backend is needed! - There is no need to restart the simulaqron backend again if you want to re-run your example. 

examples/new-sdk/teleport/aliceTest.py

@@ -29,7 +29,7 @@ async def run_alice(reader: StreamReader, writer: StreamWriter):
         q.H()
         m1 = q.measure()
         m2 = epr.measure()
-    # Any value that comes from NetQASm *need* to be retrieved ("casted" to int)
+    # Any value that comes from NetQASM *need* to be retrieved ("casted" to int)
     # *after* the connection is closed (or after flushing the connection, untested)
     m1_val = int(m1)
     m2_val = int(m2)

examples/new-sdk/teleport/bobTest.py

@@ -40,7 +40,7 @@ async def run_bob(reader: StreamReader, writer: StreamWriter):
     # Get the socket configuration for the sockets used for the application layer
     sockets_config = SocketsConfig(network_config, "default", NodeConfigType.APP)
 
-    # Create the client
+    # Create the server
     server = SimulaQronClassicalServer(sockets_config, "Bob")
     server.register_client_handler(run_bob)
     server.start_serving()

examples/new-sdk/teleport/run.sh

@@ -1,9 +1,25 @@
-#!/bin/sh
+#!/usr/bin/env bash
 
-# Check if SimulaQron is already running
-if [ ! -f ~/.simulaqron_pids/simulaqron_network_default.pid ]; then
-    # If not, start simulaqron backend for both nodes
-    simulaqron start --nodes=Alice,Bob --network-config-file simulaqron_network.json
+# Flag used to determine whether to start simulaqron backend or not
+# This is useful when using this script to run the application in different machines.
+START_SIMULAQRON=true
+
+# Process the arguments, if any
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        -n|--no-start-simulaqron)
+            START_SIMULAQRON=false
+            shift
+            ;;
+    esac
+done
+
+if [ "$START_SIMULAQRON" = true ]; then
+    # Check if SimulaQron is already running
+    if [ ! -f ~/.simulaqron_pids/simulaqron_network_default.pid ]; then
+        # If not, start simulaqron backend for both nodes
+        simulaqron start --nodes=Alice,Bob --network-config-file simulaqron_network.json
+    fi
 fi
 
 python3 bobTest.py &

examples/new-sdk/template-client-server/README.md

@@ -0,0 +1,101 @@
+# SimulaQron Client-Server template
+This folder can be used as a template for creating client-server applications.
+This template uses SimulaQron's new SDK, to register a handler when a new client
+connects to the server. Additionally, it also provides a simple way to execute
+client code once the connection to the server has been established.
+
+
+# How to run
+
+First of all, make sure you are not already running existing simulaqron programs.
+
+
+## Initial cleanup
+
+You can run
+
+```shell
+sh terminate.sh
+```
+
+which should get rid of all things running for the teleport example itself. If you have a
+debugging enabled, you may also  wish to wipe old log files by running:
+
+```shell
+rm /tmp/simulaqron*
+```
+
+This should leave you a clear slate. We can now start the application.
+
+
+## On a single machine
+If you are running everything on the same machine, simply type:
+
+```shell
+./run.sh
+```
+
+WARNING: It seems restarting the simulaqron backend is needed! - There is no need to restart the simulaqron backend again if you want to re-run your example. 
+
+
+## On multiple machines
+
+If you are starting on two different machines run, you first need to update the network configuration
+file. To run this example on different machines, it is necessary that both machines can reach each
+other via a network (or the internet). Additionally, you need to know the IP addresses of both
+machines.
+
+Assuming that the server (alice) will run on a machine with IP `192.168.0.1` and the client (bob)
+will run on the machine with IP `192.168.0.2`, modify the `simulaqron_network.json` file *on both*
+the server and the client to look like this:
+
+```json
+[
+    {
+        "name": "default",
+        "nodes":  [
+            {
+                "Alice": {
+                    "app_socket": ["192.168.0.1", 8821],
+                    "qnodeos_socket": ["192.168.0.1", 8822],
+                    "vnode_socket": ["192.168.0.1", 8823]
+                }
+            },
+            {
+                "Bob": {
+                    "app_socket": ["192.168.0.2", 9831],
+                    "qnodeos_socket": ["192.168.0.2", 9832],
+                    "vnode_socket": ["192.168.0.2", 9833]
+                }
+            }
+        ],
+        "topology": null
+    }
+]
+```
+
+Note that the `localhost` entries from Alice were changed to `192.168.0.1`. Similarly, the
+`localhost` entries from Bob were changed to `192.168.0.2`.
+
+After these modifications, yu can start the simulaqron backends by invoking:
+
+```shell
+simulaqron start --node Alice
+simulaqron start --node Bob
+```
+
+on the machines you will use as Alice and Bob respectively. Again this needs to be run only once.
+Now you can run:
+
+* on Bob:
+```shell
+python bobTest.py
+```
+
+* on Alice:
+```shell
+python aliceTest.py
+```
+
+The code assumes you start Bob before starting Alice. Using your knowledge of network programming
+from our ping pong example - do you have an idea to make this more robust?

examples/new-sdk/template-client-server/doNew.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+
+./terminate.sh
+./run.sh

examples/new-sdk/template-client-server/nodeTest-client.py

@@ -0,0 +1,83 @@
+from asyncio import StreamReader, StreamWriter
+from pathlib import Path
+
+from simulaqron.general.host_config import SocketsConfig
+from simulaqron.sdk.protocol import SimulaQronClassicalClient
+from simulaqron.settings import network_config, simulaqron_settings
+from simulaqron.settings.network_config import NodeConfigType
+
+# This is recipe to use NetQASM with simulaqron backend.
+from netqasm.runtime.settings import set_simulator
+set_simulator("simulaqron")
+
+# Importing NetQASM connection, Qubit and EPR socket must be *after*
+# setting the simulator for NetQASM
+from netqasm.sdk.external import NetQASMConnection  # noqa: E402
+from netqasm.sdk import Qubit, EPRSocket  # noqa: E402
+
+
+# This function contains the code of the classical client
+# "reader" is an object connected to the server, which can be used to read data from the server
+# "writer" is an object connected to the server, which can be used to send data to the server
+async def run_client(reader: StreamReader, writer: StreamWriter):
+    # To send a messsage, we can simply use the "wirte" method from the "writer" object
+    # The argument *must* be a python bytes object, which we can get by encoding (using
+    # the UTF-8 charmap) any python string
+    message = "Hello World"
+    writer.write(message.encode("utf-8"))
+
+    # If you want to receive a message (such a response) from the server, you can
+    # use the "read" method from the "reader" object. The argument is an integer that
+    # configures the maximum bytes that we are allowed to read in a single operation.
+    # Note: Since "read" is a python coroutine, we need to "await" it, so python can
+    # execute other coroutines until the data becomes available to read.
+    answer = await reader.read(100)
+
+    this_node_name = "Alice"
+    other_node_name = "Bob"
+
+    # We ca create an EPR socket with the other node
+    epr_socket = EPRSocket(other_node_name)
+    # To start executing quantum operations, we need to create a NetQASM connection
+    with NetQASMConnection(this_node_name, epr_sockets=[epr_socket]) as alice:
+        # Create a qubit
+        q = Qubit(alice)
+        q.H()
+        # Create an entangled qubit with the other node
+        epr = epr_socket.create_keep()[0]
+        # Teleport
+        q.cnot(epr)
+        q.H()
+        m1 = q.measure()
+        m2 = epr.measure()
+    # Any value that comes from NetQASM *need* to be retrieved ("casted" to int)
+    # *after* the connection is closed (or after flushing the connection, untested)
+    m1_val = int(m1)
+    m2_val = int(m2)
+    return m1_val, m2_val
+
+
+if __name__ == "__main__":
+    # Load the simulaqron settings file
+    simulaqron_config_file = Path("simulaqron_settings.json")
+    simulaqron_settings.read_from_file(simulaqron_config_file)
+
+    # Load the file network configuration file
+    network_config_file = Path("simulaqron_network.json")
+    network_config.read_from_file(network_config_file)
+
+    # Some data for this node:
+    network_name = "default"  # A network with this name *must* exist in "simulaqron_network.json"
+    node_name = "YourName"  # A node with this name *must* exist in "simulaqron_network.json"
+
+    # Get the socket configuration for the sockets used for the application layer
+    sockets_config = SocketsConfig(network_config, network_name, NodeConfigType.APP)
+
+    # Name of one node to classically connect to
+    server_name = "Bob"
+
+    # Create the client
+    client = SimulaQronClassicalClient(sockets_config)
+    # Run a classical client invoking the `run_client` method. This also has the effect to
+    # immediately execute the `run_client` method.
+    results = client.run_client(server_name, run_client)

examples/new-sdk/template-client-server/nodeTest-server.py

@@ -0,0 +1,78 @@
+from asyncio import StreamReader, StreamWriter
+from pathlib import Path
+
+from simulaqron.general.host_config import SocketsConfig
+from simulaqron.sdk.protocol import SimulaQronClassicalClient
+from simulaqron.settings import network_config
+from simulaqron.settings.network_config import NodeConfigType
+
+# This is recipe to use NetQASM with simulaqron backend.
+from netqasm.runtime.settings import set_simulator
+set_simulator("simulaqron")
+
+# Importing NetQASM connection, Qubit and EPR socket must be *after*
+# setting the simulator for NetQASM
+from netqasm.sdk.external import NetQASMConnection  # noqa: E402
+from netqasm.sdk import Qubit, EPRSocket  # noqa: E402
+
+
+# This function contains the code to serve *one client ocnnected to this server*.
+# "reader" is an object connected to the client, which can be used to read data from the client
+# "writer" is an object connected to the client, which can be used to send data to the client
+async def serve_client(reader: StreamReader, writer: StreamWriter):
+    # If you want to receive a message (such a query) from the client, you can
+    # use the "read" method from the "reader" object. The argument is an integer that
+    # configures the maximum bytes that we are allowed to read in a single operation.
+    # Note: Since "read" is a python coroutine, we need to "await" it, so python can
+    # execute other coroutines (such as serving a new client) until the data becomes
+    # available to read.
+    answer = await reader.read(100)
+
+    # To send a messsage, we can simply use the "wirte" method from the "writer" object
+    # The argument *must* be a python bytes object, which we can get by encoding (using
+    # the UTF-8 charmap) any python string
+    message = "Hello World"
+    writer.write(message.encode("utf-8"))
+
+    this_node_name = "Bob"
+    other_node_name = "Alice"
+
+    epr_socket = EPRSocket(other_node_name)
+    with NetQASMConnection(this_node_name, epr_sockets=[epr_socket]) as bob:
+        # Create a qubit
+        q = Qubit(bob)
+        q.H()
+        # Create entanglement
+        epr = epr_socket.create_keep()[0]
+        # Teleport
+        q.cnot(epr)
+        q.H()
+        m1 = q.measure()
+        m2 = epr.measure()
+    # Any value that comes from NetQASM *need* to be retrieved ("casted" to int)
+    # *after* the connection is closed (or after flushing the connection, untested)
+    m1_val = int(m1)
+    m2_val = int(m2)
+    return m1_val, m2_val
+
+
+if __name__ == "__main__":
+    # Load the simulaqron settings file
+    simulaqron_config_file = Path("simulaqron_settings.json")
+    simulaqron_settings.read_from_file(simulaqron_config_file)
+
+    # Load the file network configuration file
+    network_config_file = Path("simulaqron_network.json")
+    network_config.read_from_file(network_config_file)
+
+    # Some data for this node:
+    network_name = "default"  # A network with this name *must* exist in "simulaqron_network.json"
+    node_name = "YourName"  # A node with this name *must* exist in "simulaqron_network.json"
+
+    # Get the socket configuration for the sockets used for the application layer
+    sockets_config = SocketsConfig(network_config, network_name, NodeConfigType.APP)
+
+    # Create the server
+    server = SimulaQronClassicalServer(sockets_config, node_name)
+    server.register_client_handler(serve_client)
+    server.start_serving()