qruise flow init

Initialise directory structure for a Qruise flow.

Syntax

qruise flow init [OPTIONS]

Description

The qruise flow init command initialises a directory with the basic scaffolding for a Qruise flow. The following files will be created:

• .QKB.json - basic configuration of the knowledge base
• 01-schema.ipynb - Jupyter notebook for schema migration during flow execution
• 02-bootstrap-kb.ipynb - Jupyter notebook for bootstrapping the data in the knowledge base
• bootstrap.yaml - used by 02-bootstrap-kb.ipynb to bootstrap the knowledge base
• config.py - basic Python configuration file
• qruise-flow.yaml - basic flow file
• schema.py - empty schema file to be used by the flow
• utils.py - a collection of utility functions to be used in the flow notebooks

Manual steps after running qruise flow init

After running the qruise flow init the flow is not ready to be run immediately. See the text below for details.

The exact contents of the above-mentioned files depends on the command-line parameters used (see also the Examples section). At the very least, you must provide the contents of the bootstrap.yaml and schema.py files. Furthermore, if the --profile flag was not used, you have to manually edit the .QKB.json and config.py files and put it there.

Autogenerated flags

The flow defined by the autogenerated qruise-flow.yaml file will only excute the 02-bootstrap-kb.ipynb notebook if the bootstrap flag is provided. Read more about running flows with flags here.

Options

Option	Description
-n, --name	Name of the flow to use. Default: Qruise flow (autogenerated)
-d, --directory	Path of the directory to initialise. If no path is specified, the current working directory will be used.
-q, --qubits	Specify qubits present on the QPU. Must have the list format.
-c, --couplings	Specify couplings between the qubits on the QPU. Must have the pair list format.
-f, --force	Overwrite files in the target directory.
-p, --profile	Specify default profile for the flow.
--help	Show a help message and exit.

Examples

Basic usage

To create a basic directory structure for running QruiseOS flows, start by creating an empty directory and switching to it:

mkdir -p $HOME/flows/my-flow
cd $HOME/flows/my-flow

Then simply call qruise flow init without any parameters:

qruise flow init

The autogenerated qruise-flow.yaml file should have the following content:

name: Qruise flow (autogenerated)
qubits:
- Q1
- Q2
- Q3
couplings:
- - Q1
  - Q2
- - Q2
  - Q3
stages:
  init:
  - name: schema
  - dependencies:
    - schema
    name: bootstrap-kb
    conditions:
      run_on_flags:
      - bootstrap
  experiments:
    qubit: []
    coupling: []
  final: []

Before running the flow, however, you have to perform the following steps:

1. Change the flow name and specify qubits and couplings
   Open the qruise-flow.yaml file and edit name, qubits, and couplings fields to match the layout of your QPU.
2. Provide the profile name in the .QKB.json file
   Open the .QKB.json file in a text editor of choice and find the line containing "profile": null. Replace the null with the profile name in double quotation marks.
3. Provide the profile name in the config.py file
   Open the config.py file in a text editor of choice and find the line containg PROFILE = "<PROFILE>". Replace <PROFILE> with the profile name.
4. Provide a valid schema for the flow
   Edit the schema.py and provide a correct schema.
5. Provide valid bootstrap data
   Edit the bootstrap.yaml file and provide correct bootstrap data.

After completing the above steps, your flow should be ready to run. You can verify it by running the following:

qruise flow run --flags bootstrap

The above command should start a flow in the bootstrap mode, and a long log should be printed to the output. If no errors are present in the log, it means your setup is complete and you can now start developing your flow and experiments!

Specifying qubits, couplings, and profile

The process of generating the flow file can be simplfied by providing appropriate options to the CLI. For instance, assume that you have a 5-qubit QPU with linear topology, as shown in the diagram below:

Linear topology QPU with 5 qubits and 4 couplers.

Furthermore, assume that you want to use a profile called linear-5-qubits and name the resulting flow Daily flow. You can achieve this in a single CLI call in the following way:

qruise flow init --name "Daily flow" --profile linear-5-qubits --qubits Q1,Q2,Q3,Q4,Q5 --couplings Q1-Q2,Q2-Q3,Q3-Q4,Q4-Q5

Passing lists in Qruise CLI

Note the syntax for the list of qubits and couplings. You can read more about it here

The resulting flow file will now have the following structure:

name: Daily flow
qubits:
- Q1
- Q2
- Q3
- Q4
- Q5
couplings:
- - Q1
  - Q2
- - Q2
  - Q3
- - Q3
  - Q4
- - Q4
  - Q5
stages:
  init:
  - name: schema
  - dependencies:
    - schema
    name: bootstrap-kb
    conditions:
      run_on_flags:
      - bootstrap
  experiments:
    qubit: []
    coupling: []
  final: []

As you can see, we're ready to add experiments without any further modifications. Similarly, both .QKB.json and config.py files are correctly initialised with the profile name.

This method of creating flows is especially useful for automation purposes or when working with bigger QPUs, for which managing all qubits and couplings manually is too cumbersome.

Overwriting directory content

By default, running qruise flow init in a non-empty directory will fail:

$ mkdir -p $HOME/flows/my-flow
$ cd $HOME/flows/my-flow
$ touch empty-file.txt
$ qruise flow init
Failed to initialise flow: target directory is not empty, and no force-overwrite flag was specified.

This behaviour is meant to prevent accidental overwriting and loss of sensitive flow files. However, it can be changed by specifying a --force flag:

qruise flow init --force

With great power comes great responsibility...

If you do not use any other forms of protection, e.g. version control or regular backups, using the --force flag can lead to an irreversible loss of data. Use with care.