Skip to content

Using branches

Similar to the Git version control system, the knowledge base supports uses branches to manage changes in data and the schema. Branches are an extremely useful feature and can serve different purposes depending on the stage and maturity of your project. In the following sections, we'll show you a couple of examples of how branches can be used in different situations.

Managing branches

Let's start with the basics – how do you create a branch in the knowledge base? There are two ways to do it:

Bootstrapping of a new QPU

When adding a new QPU, either with the qruise add qpu command or via the dashboard, an empty knowledge base is created, with just the main branch present.

The next step would be to create a branch used solely for the purpose of bootstrapping to build the model of the QPU and check that the resulting configuration allows for jobs to go through. Once the bootstrapping branch is considered adequate, it can be merged into main so that everybody on the team can use it as a solid starting point.

Multi-user support

Branches are a great way to support multiple people working on the same QPU. Users can branch off from the main branch (which would typically be updated with nightly workflows) or from any other branch into their own isolated branch. They can then carry out any development there without affecting others who rely on main for a stable QPU configuration.

Sandbox

A variant of the previous use case is using branches to create isolated environments, which are especially helpful for onboarding and experimentation. This allows users to get familiar with the KB simply by creating, using, and then deleting a branch.

Running workflows

Workflow runs make extensive use of the branching system. The very first operation in any workflow (one you don't have to specify) is to create or checkout a branch. If the workflow completes successfully, the branch is merged into main by default, or you can specify a different branch to merge into. It's also possible to specify which branch the workflow should start from (see qruise flow run --help).

Resetting for debugging

Let's imagine that the analysis of a certain task failed during the execution of a workflow. In this situation, you'd want to checkout the workflow branch and return to a specific commit (see qruise kb log --help and qruise kb reset --help). This allows you to investigate the QPU configuration immediately before the task was executed. This ensures maximum reproducibility, as you can rerun the task with the same configuration and context that led to the faulty analysis. This speeds up debugging and knowledge sharing.

Switching between different QPU contexts

Sometimes, it’s useful to focus on a specific part of the QPU, such as a single qubit, a pair of qubits, or a particular gate. It may be the case that the optimal settings for one of these subsystems differ from those used for the overall QPU. Working in a separate, dedicated branch allows you to fine-tune parameters for the specific subsystem without affecting the global QPU configuration.

Instant setup to reproduce an interesting output

A slight variant of the two previous use cases is to use a branch to preserve the QPU configuration that produced a notable measurement output in need of discussion or clarification. Other users can then use this branch as a starting point, allowing them to instantly reproduce the setup and investigate said output. This improves reproducibility and traceability and avoids the need to pass around configuration files that can lose their meaning when the context is lost. You can view different branches and their results in the Experiment Database tab in the dashboard.