qne-adk 0.4.0

Description:

qneadk 0.4.0

Quantum Network Explorer ADK
The QNE-ADK is a Quantum Network Explorer - Application Development Kit that allows you to create your own applications and experiments and run them on a simulator.
Local development
With the ADK you can create your own application from scratch using the qne application create command
(see section 'Commands' below for more information about the individual commands). An application directory is created with all the necessary files for you to configure.
When configuring an application, you specify the different roles and what types of inputs your
application uses. In addition, you write the functionality of your application using the NetQASM library.
After creating and configuring an application, you can create an experiment for it using the qne experiment create
command. A separate experiment directory is created with all the necessary files. When configuring your experiment
you can give values to the inputs that were specified when creating your application. You also choose which channels
and nodes you use in your network and which role is linked to which node. A network consists of channels and each
channel consists of two nodes. The nodes can communicate with each other using the channel between them.
Once your experiment is configured you are ready to run it using the qne experiment run command. Your experiment
is parsed and sent to the NetSquid simulator. After some time your experiment run will be finished and a results
directory will be generated in which all the results of your experiment are stored. An alternative is to use the
qne experiment results command to show the results on screen.
Publishing applications
When your application is finished and you want to share it with the world, an application can be uploaded and
published after which it can be selected by other users on the QNE platform. After uploading the application
qne application upload a remote experiment must be created qne experiment create --remote and run
qne experiment run first on the QNE simulator backend successfully before the application can be
published qne application publish. After the application is published successfully, it can be used by others.
For commands interacting with the remote QNE server you must log in first qne login.
Instead of starting from scratch an existing QNE application can be cloned using the qne application clone command.
A copy of a working application is made to your application directory and can be used as starting point
for application development.
Prerequisites

A modern Linux or macOS (10 or 11) 64-bit (x86_64) operating system. If you don’t have Linux or macOS you could run it via virtualization, e.g. using VirtualBox. If you have Windows 10 or 11 you can also use the Bash on Ubuntu subsystem.
A virtual environment should be created and activated before creating an application.
Python version 3.8 or higher.
NetQASM makes use of SquidASM for which you need credentials in order to use it. These credentials can be obtained by registering on the forum of NetSquid.

Installation
To install all the required packages, execute the following command:
pip install qne-adk

After installing the qne-adk, you can install SquidASM. Replace '{netsquid-user-name}' and '{netsquid-password}' with the credentials you registered on NetSquid:
pip install squidasm --extra-index-url=https://{netsquid-user-name}:{netsquid-password}@pypi.netsquid.org

Now everything should be setup and ready in order to create your own applications and experiments and run them on the simulator!
Commands
The QNE-ADK uses various commands to create and run your applications and experiments. All the commands are listed below:


qne application list
Show a list of all applications and relevant information for each of them.
For listing remote applications, the user must be logged in.

qne application list [OPTIONS]

Options:
--remote List remote applications [default: False]
--local List local applications [default: False].
--help Show this message and exit.

Example:
qne application list --remote




qne application init
Initialize an existing application in the current path which is not already registered to QNE-ADK.
This is needed for applications not created with QNE-ADK, for example when the files come from a
repository or are directly copied to the file system.
Two subdirectories src and config will be created when not already there.
When application files are in the root directory, but belong to one of the subdirectories, they are moved.

qne application init [OPTIONS] APPLICATION_NAME

./application_name is taken as application directory

Arguments:
APPLICATION_NAME Name of the application [required]

Options:
--help Show this message and exit.

Example:
qne application init application_name




qne application create
Create a new application in your current directory containing all the files that are needed to write your application.
The application directory name will be based on the value given to application_name.
Two subdirectories src and config will be created, along with the default files.

qne application create [OPTIONS] APPLICATION_NAME ROLES...

Arguments:
APPLICATION_NAME Name of the application [required]
ROLES... Names of the roles to be created [required]

Options:
--help Show this message and exit.

Example:
qne application create my_application Alice Bob




qne application clone
Clone an existing remote or local application and use it as a starting point for new application development.
Cloning an application will copy the application files to the current directory.
The public available (or latest) version of the application is copied.
When a new application name is not given as an argument (remote only) the application will have the same name as
the cloned application. An application with the new application name may not already exist locally.
A local application must be valid before it can be cloned. For cloning a remote application the user must be logged in.

qne application clone [OPTIONS] APPLICATION_NAME [NEW_APPLICATION_NAME]

Arguments:
APPLICATION_NAME Name of the application to clone [required]
[NEW_APPLICATION_NAME] New name for the cloned application

Options:
--remote Clone remote application [default: False]
--help Show this message and exit.

Example:
qne application clone existing_application new_application




qne application fetch
Fetching an existing remote application will copy the application files to the current directory.
The highest version of the application files are copied which may not be the current public version but a draft version.
Fetching applications is limited to the applications for which the user is the author.
For fetching a remote application the user must be logged in.

qne application fetch [OPTIONS] APPLICATION_NAME

Arguments:
APPLICATION_NAME Name of the application to fetch [required]

Options:
--help Show this message and exit.

Example:
qne application fetch existing_application




qne application delete
Delete the files of an application. Will try to delete the application directory
structure but keeps the files that are not part of the application.
For deleting remote parts of the application, the user must be logged in.

qne application delete [OPTIONS] [APPLICATION_NAME]

When application_name is given ./application_name is taken as application
directory, when this directory does not contain an application the
application directory is fetched from the application configuration. When
application_name is not given, the current directory is taken as
application directory.

Arguments:
[APPLICATION_NAME] Name of the application

Options:
--help Show this message and exit.

Example:
qne application delete application_name




qne application validate
Validate the application created locally.

qne application validate [OPTIONS] [APPLICATION_NAME]

When application_name is given ./application_name is taken as application
directory, when this directory does not contain an application the
application directory is fetched from the application configuration. When
application_name is not given, the current directory is taken as
application directory.

Arguments:
[APPLICATION_NAME] Name of the application

Options:
--help Show this message and exit.

Example:
qne application validate application_name




qne application upload
Create or update a remote application.
For creating or updating remote applications, the user must be logged in.

qne application upload [OPTIONS] [APPLICATION_NAME]

When application_name is given ./application_name is taken as application
directory, when this directory does not contain an application the
application directory is fetched from the application configuration. When
application_name is not given, the current directory is taken as
application directory.

Arguments:
[APPLICATION_NAME] Name of the application

Options:
--help Show this message and exit.

Example:
qne application upload application_name




qne application publish
Request the application to be published online.
For publishing a new version of a remote application, the author of the application
must have run at least one successful experiment on the remote backend for the new
version of the application.
For publishing a new version of remote applications, the user must be logged in.

qne application publish [OPTIONS] [APPLICATION_NAME]

When application_name is given ./application_name is taken as application
directory, when this directory does not contain an application the
application directory is fetched from the application configuration. When
application_name is not given, the current directory is taken as
application directory.

Arguments:
[APPLICATION_NAME] Name of the application

Options:
--help Show this message and exit.

Example:
qne application publish application_name




qne experiment list
List remote experiments.
For listing remote experiments, the user must be logged in.

qne experiment list [OPTIONS]

Options:
--help Show this message and exit.

Example:
qne experiment list




qne experiment create
Create a new experiment, based on an application name and a chosen network.
When the experiment is created for a remote application the user must be logged in.

qne experiment create [OPTIONS] EXPERIMENT_NAME APPLICATION_NAME NETWORK_NAME

Arguments:
EXPERIMENT_NAME Name of the experiment. [required]
APPLICATION_NAME Name of the application. [required]
NETWORK_NAME Name of the network to be used. [required]

Options:
--remote Use remote application configuration [default: False]
--help Show this message and exit.

Example:
qne experiment create experiment_name application_name europe




qne experiment delete
Delete experiment files.

qne experiment delete [OPTIONS] [EXPERIMENT_NAME]

Local: When deleting an experiment locally, argument EXPERIMENT_NAME_OR_ID
is the local experiment name, which is the subdirectory containing the
experiment files. When the argument is empty the current directory is
taken as experiment directory. The local experiment files are deleted,
when the experiment was created with '--remote' and the experiment was run
remotely, the remote experiment is also deleted.

Remote: the argument EXPERIMENT_NAME_OR_ID is the remote experiment id to
delete. No local files are deleted.

Arguments:
[EXPERIMENT_NAME_OR_ID] Name of the experiment or remote id

Options:
--remote Delete a remote experiment [default: False]
--help Show this message and exit.

Example:
qne experiment delete experiment_name




qne experiment validate
Validate the local experiment.

qne experiment validate [OPTIONS] [EXPERIMENT_NAME]

When experiment_name is given ./experiment_name is taken as experiment directory.
When experiment_name is not given, the current directory is taken as experiment
directory.

Arguments:
[EXPERIMENT_NAME] Name of the experiment

Options:
--help Show this message and exit.

Example:
qne experiment validate experiment_name




qne experiment run
This command will parse all experiment files and run them on the NetSquid simulator.

qne experiment run [OPTIONS] [EXPERIMENT_NAME]

When experiment_name is given ./experiment_name is taken as experiment directory.
When experiment_name is not given, the current directory is taken as experiment
directory.
Block (remote experiment runs only) waits for the experiment to finish before
returning (and results are available). Local experiment runs are blocked by default.
Timeout (optional) limits the wait (in seconds) for a blocked experiment to finish.
In case of a local experiment, a timeout will cancel the experiment run. A remote
experiment run is not canceled after a timeout and results can be fetched at a later
moment.

Arguments:
[EXPERIMENT_NAME] Name of the experiment

Options:
--block Wait for the (remote) experiment to finish. [default: False]
--timeout Limit the wait for a blocked experiment to finish (in seconds).
[default: no timeout]
--help Show this message and exit.

Example:
qne experiment run --block --timeout=30 experiment_name




qne experiment results
Get results for an experiment that run successfully.

qne experiment results [OPTIONS] [EXPERIMENT_NAME]

When experiment_name is given ./experiment_name is taken as experiment directory.
When experiment_name is not given, the current directory is taken as experiment
directory.

Arguments:
[EXPERIMENT_NAME] Name of the experiment

Options:
--all Get all results for this experiment. [default: False]
--show Show the results on screen instead of saving to file. [default:
False]
--help Show this message and exit.

Example:
qne experiment results experiment_name




qne login
Log in to a Quantum Network Explorer.

qne login [OPTIONS] [HOST]

Arguments:
[HOST] Name of the host to log in to

Options:
--email TEXT Email of the remote user [required]
--password TEXT Password of the remote user [required]
--help Show this message and exit.

Example:
qne login [email protected] --password=my_password https://api.quantum-network.com




qne logout
Log out from Quantum Network Explorer.

qne logout [OPTIONS] [HOST]

Arguments:
[HOST] Name of the host to log out from

Options:
--help Show this message and exit.

Example:
qne logout https://api.quantum-network.com




qne network list
List available networks. For listing remote networks, the user must be logged in.

qne network list [OPTIONS]

Options:
--remote List remote networks [default: False]
--local List local networks [default: True]
--help Show this message and exit.

Example:
qne network list --remote




qne network update
Get remote networks and update local network files.
For updating local networks, the user must be logged in.

qne network update [OPTIONS]

Options:
--overwrite Overwrite local networks [default: False]
--help Show this message and exit.


Example:
qne network update --overwrite


More documentation
More documentation about these commands and about the files that are generated can be found in the QNE-ADK user guide on the Quantum Network Explorer knowledge base.