Skip to content

Commit 3ad36d4

Browse files
dieriverdieriver
committed
Update the template for native mode applications
1 parent c2ad9ff commit 3ad36d4

6 files changed

Lines changed: 183 additions & 9 deletions

File tree

‎examples/nativeMode/template/README.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# SimulaQron native mode template
2+
3+
You can use the files in this folder as a template for implementing new SimulaQron applications.
4+
Please check the comments inside the `nodeTest.py` file to learn how to modify it.
5+
6+
7+
# Update network configuration
8+
9+
Additionally, this template also contains a file that you can use for defining the network:
10+
`network_config.json`.
11+
12+
This file contains a single network, named "default". This network contains 4 nodes named
13+
"Alice", "Bob", "Charlie" and "David".
14+
15+
Each one of those nodes defines 3 entries:
16+
* `app_socket`: The hostname and port used by other nodes to send classical messages to this node.
17+
SimulaQron applications will bind to this hostname and port to listen for classical messages coming
18+
from other nodes.
19+
* `qnodeos_socket`: The hostname and port to bind the QNodeOS server. This configuration is required
20+
when using SimulaQron's NetQASM interface.
21+
* `vnode_socket`: The hostname and port to bind SimulaQron's Virtual Node server. This server is in
22+
charge of executing the quantum simulation. Configuring this entry is required in all cases.s
23+
24+
25+
## Adding new nodes
26+
27+
To add a new node named "Eva", follow these steps:
28+
1. Open the config.json file in a text editor.
29+
2. Locate the "nodes" array inside the "default" object.
30+
3. Add a new object to the "nodes" array for "Eva". The structure should match the existing nodes:
31+
```json
32+
{
33+
"Eva": {
34+
"app_socket": ["localhost", PORT_NUMBER],
35+
"qnodeos_socket": ["localhost", PORT_NUMBER],
36+
"vnode_socket": ["localhost", PORT_NUMBER]
37+
}
38+
}
39+
```
40+
Replace PORT_NUMBER with unique port numbers for each socket type (e.g., 8851, 8852, 8853). The result should
41+
look like:
42+
```json
43+
Copy
44+
45+
{
46+
"name": "default",
47+
"nodes": [
48+
{"Alice": {...}},
49+
{"Bob": {...}},
50+
{"Charlie": {...}},
51+
{"David": {...}},
52+
{
53+
"Eva": {
54+
"app_socket": ["localhost", 8851],
55+
"qnodeos_socket": ["localhost", 8852],
56+
"vnode_socket": ["localhost", 8853]
57+
}
58+
}
59+
],
60+
"topology": null
61+
}
62+
```
63+
64+
4. Save the file after making the changes.
65+
66+
67+
# Additional tools
68+
69+
This folder also contains a few bash scripts you can use for executing you application.
70+
71+
72+
## `run.sh`
73+
74+
This script is a helper to quickly start the SimulaQron backend for a list of specified nodes, and then
75+
start the application code for those same nodes.
76+
77+
This script needs a small change depending on how many nodes you want to run *on the current machine*.
78+
If you open this file, you can see this content:
79+
```shell
80+
#!/usr/bin/env bash
81+
82+
# Check if SimulaQron is already running
83+
if [ ! -f ~/.simulaqron_pids/simulaqron_network_default.pid ]; then
84+
if ! simulaqron start --nodes=Alice,Bob --network-config-file network_config.json
85+
then
86+
echo "SimulaQron could not start correctly"
87+
exit 1
88+
fi
89+
fi
90+
91+
92+
# Run the files for Alice, Bob or whatever nodes you construct
93+
python3 bobTest.py &
94+
python3 aliceTest.py
95+
```
96+
97+
Change the `--nodes` option of the `simulaqron start` command, with the list (separated with commas, no spaces)
98+
of nodes you want to start locally. Also, change the `python3` lines to also start all your python programs
99+
that implement the nodes.
100+
101+
Finally, if you changed the name of the network configuration file, also reflect this change by changing
102+
the argument next to the `--network-config-file` option.
103+
104+
105+
## `terminate.sh`
106+
107+
This script can be used to stop the SimulaQron backend and terminate all the applications processes
108+
that are still running.
109+
110+
111+
## `doNew.sh`
112+
113+
This is ascript that you can use to start a new instance of your application from a clean state.
114+
This scrip simply invokes `terminate.sh` and `run.sh` sequentially.

‎examples/nativeMode/template/doNew.sh‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
#!/usr/bin/env bash
2+
3+
./terminate.sh
4+
./run.sh

‎examples/nativeMode/template/network_config.json‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
[
2+
{
3+
"name": "default",
4+
"nodes": [
5+
{
6+
"Alice": {
7+
"app_socket": ["localhost", 8821],
8+
"qnodeos_socket": ["localhost", 8822],
9+
"vnode_socket": ["localhost", 8823]
10+
}
11+
},
12+
{
13+
"Bob": {
14+
"app_socket": ["localhost", 8831],
15+
"qnodeos_socket": ["localhost", 8832],
16+
"vnode_socket": ["localhost", 8833]
17+
}
18+
},
19+
{
20+
"Charlie": {
21+
"app_socket": ["localhost", 8841],
22+
"qnodeos_socket": ["localhost", 8842],
23+
"vnode_socket": ["localhost", 8843]
24+
}
25+
},
26+
{
27+
"David": {
28+
"app_socket": ["localhost", 8871],
29+
"qnodeos_socket": ["localhost", 8872],
30+
"vnode_socket": ["localhost", 8873]
31+
}
32+
}
33+
],
34+
"topology": null
35+
}
36+
]

‎examples/nativeMode/template/nodeTest.py‎

Lines changed: 0 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -144,14 +144,6 @@ def main():
144144
virtualNet = SocketsConfig(network_config, config_type=NodeConfigType.VNODE)
145145
classicalNet = SocketsConfig(network_config, config_type=NodeConfigType.APP)
146146

147-
# By default, *all nodes* described in the network configuration will be loaded in the SocketsConfig
148-
# object. With this information, SimulaQron will start all of those nodes, either as local classical
149-
# or virtual nodes (depending on the specified configuration type).
150-
# In some cases, this is not desired, and we want ot start *a subset* of these nodes.
151-
# To do this, we can use the method "filter" from the SocketsConfig object to specify the nodes
152-
# we want to keep (and hence, start)
153-
classicalNet.filter(["Alice", "Bob"])
154-
155147
# Check if we should run a local classical server. If so, initialize the code
156148
# to handle remote connections on the classical communication network
157149
if myName in classicalNet.hostDict:

‎examples/nativeMode/template/run.sh‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,16 @@
1-
#!/bin/sh
1+
#!/usr/bin/env bash
2+
3+
# Check if SimulaQron is already running
4+
if [ ! -f ~/.simulaqron_pids/simulaqron_network_default.pid ]; then
5+
# TODO - Modify the list of nodes to start on this machine
6+
# TODO - Change the filename of the network configuration if you changed that
7+
if ! simulaqron start --nodes=Alice,Bob --network-config-file network_config.json
8+
then
9+
echo "SimulaQron could not start correctly"
10+
exit 1
11+
fi
12+
fi
13+
214

315
# Run the files for Alice, Bob or whatever nodes you construct
416
python3 bobTest.py &

‎examples/nativeMode/template/terminate.sh‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
#!/usr/bin/env sh
2+
TEST_PIDS=$(ps aux | grep python | grep -E "Test" | awk {'print $2'})
3+
if [ "$TEST_PIDS" != "" ]
4+
then
5+
kill -9 $TEST_PIDS
6+
fi
7+
8+
# Check if SimulaQron is running
9+
if [ -f ~/.simulaqron_pids/simulaqron_network_default.pid ]; then
10+
if ! simulaqron stop
11+
then
12+
# Kill the process, only if simulaqron could not be stopped gracefully
13+
cat $HOME/.simulaqron_pids/simulaqron_network_default.pid | xargs kill -9
14+
fi
15+
fi
16+

0 commit comments

Comments
 (0)