After creating an application, a config directory is created within the application directory containing application.json, network.json, and result.json. Each is described below.

application.json

The application.json file is a 'template' for your application. The file will then define a list of inputs.  After creating your application, the default application.json should look something like this (here, we assume two roles):

[
  {
    "title": "Title for this application",
    "description": "Description of this application",
    "values": [
      {
        "name": "x",
        "default_value": 0,
        "minimum_value": 0,
        "maximum_value": 1,
        "unit": "",
        "scale_value": 1.0
      }
    ],
    "input_type": "number",
    "roles": [
      "role_name1"
    ]
  },
  {
    "title": "Title for this application",
    "description": "Description of this application",
    "values": [
      {
        "name": "x",
        "default_value": 0,
        "minimum_value": 0,
        "maximum_value": 1,
        "unit": "",
        "scale_value": 1.0
      }
    ],
    "input_type": "number",
    "roles": [
      "role_name2"
    ]
  },
  {
    "title": "Title for this input",
    "description": "This input is available for multiple roles",
    "values": [
      {
        "name": "y",
        "default_value": 0,
        "minimum_value": 0,
        "maximum_value": 1,
        "unit": "",
        "scale_value": 1.0
      }
    ],
    "input_type": "number",
    "roles": [
      "role_name1",
      "role_name2",
    ]
  }
]

Each role has its own input, with all roles being merged at the last input. This is the 'template' of your application input. Each input value has a name, default_value, minimum_value, maximum_value, unit, and scale_value.

By changing this file, you can define a custom template for your application's inputs. Each value can have a different unit, which is defined as a string. This is set to an empty string by default. For example, if you are defining an angle, it can be set to "rad". This is just visual, and is used by the application editor when showing the inputs to the user.

Each input can also be scaled using the scale_value, but only when the default_value and the unit are scalable (e.g. a Boolean is not scalable). One useful example for scaling is when defining an angle (see the full example below): the unit would be "rad" and scale_value can be defined as "pi"; an input of 0.5 is then multiplied by the scaling "pi" and the resulting value would be 0.5 * 3.14 = 1.57.

The value of scale_value can be a float or string (e.g. "pi"). By default, the scale_value is 1.0, and no scaling will be done. (Note that this only affects what the QNE editor will show when asking the user for input; the actual scaling of input values must then also be done in the application source files, which you can read about here.)

Each input should also have a defined input_type. In the case of a numeric input, it can be either "number" for integers or "float" for numbers with decimal points. The input type can also be defined as "qubit" which you can see in the example below.

You can also indicate which role(s) should link to which input by entering the role names in the roles list for each input.

Below is an example showing what an application.json file might look like for a state teleportation application. The roles are named Sender and Receiver when creating the application:

[
    {
        "title": "Qubit state of Sender",
        "slug": "qubit_state_sender",
        "description": "Sender state of the state teleportation",
        "values": [
            {
                "name": "phi",
                "default_value": 0.0,
                "minimum_value": -1.0,
                "maximum_value": 1.0,
                "unit": "rad",
                "scale_value": "pi"
            },
            {
                "name": "theta",
                "default_value": 0.0,
                "minimum_value": 0.0,
                "maximum_value": 1.0,
                "unit": "rad",
                "scale_value": "pi"
            }
        ],
        "input_type": "qubit",
        "roles": [
            "Sender"
        ]
    }
]

network.json

The network.json file states what networks a user can use to run their experiment, for a given application. The networks that will be available depend on the number of roles that have been given as input. If, for example, six roles are given when creating the application, and the network 'europe' only consists of five nodes, this network can not be used and will not be shown in the network.json file. 

Furthermore, the role names should be listed in the list "roles". As soon as the application is created, the content should be properly generated in network.json and there should be no need to modify anything in this file.

An example of the network.json file is shown below using the same inputs as given for the application.json:

{
  "networks": [
    "randstad",
    "europe",
    "the-netherlands"
  ],
  "roles": [
    "Sender",
    "Receiver"
  ]
}

result.json

Similarly to application.json which defines the 'template' for application inputs, the result.json file is used as as a 'template' file for displaying the results of an experiment on the frontend. In this file, you describe the various types of data which you want to be displayed in the Result section.

Upon creating a new application with qne application create APPLICATION_NAME ROLES ..., the following result.json file is created:

{
  "round_result_view": [],
  "cumulative_result_view": [],
  "final_result_view": []
}

To display results on the Result page, you can define several components to be shown in the "round_result_view". This should have the form of a two dimensional array (e.g. [[], ...]):

{
  "round_result_view": [
    [
      <component>
    ]
  ],
  "cumulative_result_view": [],
  "final_result_view": []
}

All components have the same form: a JSON object with the output type of the component (required), a title (required), and parameters (this can be empty).

{
  "output_type": "<frontend-component>",
  "title": "<Human readable title>",
  "parameters": {}
}

There are three different types of supported components: a quantum state, text, or a table. Below, we give the required parameters and provide examples for each one.

Note that sometimes the parameters can use a JSON-path to refer to data returned from the application source file. This means that if your source file app_alice.py has a return statement such as return {"qber": qber, "final_state": state}, you can refer to this data as $.app_alice.qber or $.app_alice.final_state.

Quantum State

The quantum state of a qubit is represented by one parameter, the density matrix. This matrix is represented by a list of lists. The path pointing to the actual parameter is added in the parameters dictionary.

{
  "output_type": "quantum-state",
  "title": "<Human readable title>",
  "parameters": {
    "density_matrix": "<json-path>"
  }
}

Example:

{
  "output_type": "quantum-state",
  "title": "Quantum State of qubit 1",
  "parameters": {
    "density_matrix": "$.app_alice.states[0].density_matrix"
  }
}

Text

A text area can also be added, using either static or dynamic data. This component expects only parameter called "content" which is in markdown format. It can also display dynamic data using the mustache notation ({{ }}) which holds a JSON-path to the required variable.

{
  "output_type": "text",
  "title": "<Human readable title>",
  "parameters": {
    "content": "<markdown>"
  }
}

Example with static data:

{
  "output_type": "text",
  "title": "Suitable title",
  "parameters": {
    "content": "This text is intended to explain the intricacies of a Quantum Network algorithm."
  }
}

Example with dynamic data:

{
  "output_type": "text",
  "title": "Suitable title",
  "parameters": {
    "content": "Alice has received the {{ $.app_alice.number_of_messages }} messages"
  }
}

Table

To display a table in the results section, you can add a list of lists as a "data" parameter, depicting the raw data of the table (i.e. without headers). Headers can be optionally defined in the "headers" parameter. The component can also point to the 2D list with a JSON-path. (In the case that the return value from the simulator is not a 2D formatted object, this needs to be manually constructed and added to a single key of the return object. The table should always be constructed as a list of lists.)

{
  "output_type": "table",
  "title": "<Human readable title>"
  "parameters": {
    "data": "<json-path>",
    "headers": ["<header-title>"]
  }
}

Example:

{
  "output_type": "table",
  "title": "Alice data"
  "parameters": {
    "data": "$.app_alice.table",
    "headers": ["Header 1", "Header 2"]
  }
}

To summarise the configuration of a result.json file, we show a simple example of a complete configuration for an application whose results display all three component types. Below this example, you can also see how it is displayed in the Result section.

{
  "round_result_view": [
    [
      {
        "output_type": "quantum-state",
        "title": "Final state of a qubit",
        "parameters": {
          "density_matrix": [[0.5, 0.5], [0.5, 0.5]]
        }
      }
    ],
    [
      {
        "output_type": "text",
        "title": "Description of a protocol",
        "parameters": {
          "content": "This is a description of a protocol. It uses [markdown](https://www.markdownguide.org/cheat-sheet/) format which allows for formatting of e.g. **keywords** or `code`."
        }
      }
    ],
    [
      {
        "output_type": "table",
        "title": "Table with random data",
        "parameters": {
          "data": [[1, 2], [3, 4]],
          "headers": ["Header 1", "Header 2"]
        }
      }
    ]
  ],
  "cumulative_result_view": [],
  "final_result_view": []
}

Now that you learned a little more about how to edit your config files, it's time to start creating your src files.