qruise flow schedule

Submit a flow for scheduled execution.

Syntax¶

qruise flow schedule [OPTIONS]

Description¶

The qruise flow schedule command schedules a flow for automated, periodic execution without any human intervention. The flows can be executed either by the QruiseOS infrastructure or locally.

Options¶

Option	Description
`-f, --flow-file`	Path of the flow definition file for scheduling the flow. Default: `qruise-flow.yaml`.
`-l, --local`	If specified, the flow is scheduled for execution on the user's machine.
`-b, --branch`	The knowledge base branch to be used by the flow. Can also be set using the `QRUISE_FLOW_DEFAULT_INTEGRATION_BRANCH` env variable.
`-m, --no-merge`	If specified, the flow results will not be merged to the integration branch.
`-q, --qubits`	Limit the flow run to only specified qubits. If no qubits are specified, all qubits defined in the flow file will be used. Must have the list format.
`-s, --start`	Execute only notebooks with ordinal numbers greater than or equal to the number specified.
`-e, --end`	Execute only notebooks with ordinal numbers less than or equal to the number specified.
`-i, --interval`	Interval at which the flow should be run. Cannot be specified at the same time as `--schedule`. The value must be a string consisting of a numeral and a unit without whitespaces, e.g. `45m` (every 45 minutes) or `3h` (every 3 hours). Allowed unit values are `m`, `h`, and `d` for minutes, hours, and days, respectively.
`--schedule`	Schedule on which the flow should be run, in a cron-like format. Cannot be specified at the same time as `--interval.`
`-z, --time-zone`	Specify time zone for the cron schedule in a tz database format. If specified, `--schedule` must also be provided. Default: `UTC`
`--image`	Docker base image tag to be used.
`--tag`	Version of the Docker image to be used. If specified, `--image` option must also be present.
`--n, --no-build`	If specified, the provided image will be used as-is and pulled at runtime.
`--prepare`	If specified, scheduling is prepared but no further action is taken. Overwrites the content already present.
`-x, --inplace`	If specified, the flow is prepared for execution in the same directory and not copied. Cannot be specified at the same time as `--output-dir`.
`-o, --output-dir`	Specifies path of the build directory for the flow, where `qruise` prepares it for scheduling or execution. Cannot be specified at the same time as `--inplace`. Default: `.qruise/build/<DATE_TIME>`.
`--help`	Show a help message and exit.

Environment variables¶

Variable	Description
`QRUISE_FLOW_DEFAULT_INTEGRATION_BRANCH`	Default knowledge base to be used by the flow. See the `--branch` option.
`QRUISE_FLOW_SKIP_MERGE`	If set to `True`, the results will not be merged to the integration branch by default. See the `--no-merge` option.
`QRUISE_FLOW_CRON_SCHEDULE`	Default schedule to be used by the flow. See the `--schedule` option for details and limitations. Cannot be set at the same time as `QRUISE_FLOW_INTERVAL_SCHEDULE`.
`QRUISE_FLOW_INTERVAL_SCHEDULE`	Default interval to be use by the flow. See the `--interval` option for details and limitations. Cannot be set at the same time as `QRUISE_FLOW_CRON_SCHEDULE`.
`QRUISE_FLOW_IMAGE`	Default Docker base image tag to be used. See the `--image` option.

Examples¶

Scheduling a nightly calibration run¶

Regular calibration of the QPU is crucial for smooth and high-fidelity operation. When you finish the development of your calibration flow (and test it using the qruise flow run command), you can schedule it using a single Qruise CLI command.

Suppose your flow file is located in $HOME/flows/my-flow.yaml and you want it to run every day at 1:00 UTC during a daily downtime window. To achieve that, simply run (using the same cron-like format to define the time):

qruise flow schedule --flow-file $HOME/flows/my-flow.yaml --schedule "0 1 * * *"

In this case, you don't need to specify the time zone as UTC is the default. However, if your device is located in a different time zone, you can specify it using the --time-zone option. For instance, if you operate from Berlin, Germany, you can run:

qruise flow schedule --flow-file $HOME/flows/my-flow.yaml --schedule "0 1 * * *" --time-zone Europe/Berlin

Modifying flow parameters¶

When you schedule a flow, it will use parameter values as defined in the flow definition file. To change them, you can simply modify the flow file, but sometimes it's desirable to change them during scheduling without actually touching the flow file. For this reason, qruise flow schedule allows you to override certain parameters, as described by the following table:

Parameter	Command line option
qubits	`-q, --qubits`
start position	`-s, --start`
end position	`-e, --end`
KB intergration branch	`-b, --branch`
skip merging results	`-m, --no-merge`

See the Options section for a detailed description of each parameter.

As an example, assume you have a flow file my-flow.yaml located in your current working directory, which has the following features:

four different qubits: Q1, Q2, Q3, and Q4
experiments with ordinal numbers 10 to 80

Now let's assume you want to schedule this flow but want it to:

run for Q1 and Q4 qubits only
run only experiments numbered 15 to 75

You can achieve this by running

qruise flow schedule --flow-file ./my-flow.yaml --qubits Q1,Q4 --start 15 --end 75

Range specification

The range specified by --start and --end is inclusive on both ends. Thus, passing --start 15 and --end 75 will result in both notebooks 15 and 75 being executed (as well as everything in between).

Customising Docker image¶

Similarly to changing flow parameter default values, you might want to change the Docker image used as a base for building the flow container or its version.

For instance, assume that your base image is simply ubuntu, version 22.04. However, you'd like to see if your flow would work with another version of this container, say 24.04. You can do this by simply running

qruise flow schedule --flow-file ./my-flow.yaml --tag 24.04

where we assumed that the flow file is located in ./my-flow.yaml. Similarly, if you wanted to switch the base from ubuntu to, say, jupyterhub/jupyterhub, you can achieve it with the following:

qruise flow schedule --flow-file ./my-flow.yaml --image jupyterhub/jupyterhub

Scheduling flows on a local machine¶

You can use a local machine for scheduling flows. You can achieve this by using the --local flag:

qruise flow schedule --local --flow-file $HOME/flows/my-flow.yaml --schedule "0 1 * * *"

This will schedule the flow defined in $HOME/flows/my-flow.yaml to run locally every day at 1:00 UTC, until the process is exited either by closing the shell window or pressing Ctrl+C.