Architecture#
OrangeQS Juice is designed with a modular architecture that emphasizes flexibility and scalability. This guide explains the key components of the architecture and how they interact to provide a robust framework for running quantum computing measurements.
This guide first provides a high-level overview of all components that make up OrangeQS Juice. Next, it dives deeper into each component separately. Finally, it explains the communication patterns used for components to interact with each other.
Components#
OrangeQS Juice is composed of several key components, including Juice services, user containers and data storage.
Overview#
The components are shown in a high-level architecture diagram below.
Below is a short description of each of the components in the architecture diagram. Each paragraph is linked to a more detailed section later in this document.
Remote Access. Users can access the system remotely through JupyterHub. JupyterHub handles authentication and authorization, for example using Gitlab as OAuth provider. When a user logs in, they are provided with their own isolated user container.
User container. After logging in, each user gets their own isolated user container. Within this container, multiple applications are running. The user interacts with the system through these applications. By default, the following applications are available:
Dashboard. Web interface for monitoring and interacting with the components of the system. Extensions or users can provide custom pages for the dashboard.
JupyterLab. The familiar Jupyter interface where users can write and execute code. Useful for running analysis scripts or interacting with the system programmatically.
File browser. A file browser for browsing user and shared files.
VS Code. A web-based version of VS Code for editing code and files.
Juice Services. Juice services are long-running IPython kernels. They manage and interact with shared hardware and system resources. The Task Manager is the central service that handles communication between services, it routes tasks and events to the appropriate services. Each service has a dedicated role, such as managing tasks, monitoring the fridge, or running experiments. Juice ships with some default services, but users can also easily configure their own custom services to fit their specific needs. Services can run code provided by Juice or regular Python programs.
Data storage. Data generated by the system, such as measurement results and logs, are stored in a centralized place.
InfluxDB2 (database). Juice ships with an integrated InfluxDB2 time-series database for storing structured data.
Shared folder (files). A shared file storage system is available for storing unstructured data, such as raw measurement data or generated figures.
User folder (files). Each user also has their own private folder for storing personal files.
Hardware. The Juice installation connects to hardware in your experimental setup. For connecting with cryogenic equipment, the Juice system monitor provides a standardized set of interfaces that hardware drivers can implement. For connecting with control electronics, Juice recommends using Quantify, but any Python control software can be used. Other hardware can be integrated as long as there is a Python interface available.
Juice Services#
Each OrangeQS Juice Service is implemented as an IPython kernel, initialized with a custom script tailored to its specific role within the framework. These services are essential for managing and interacting with shared hardware and system resources.
A standard OrangeQS Juice installation includes the following core services:
Task Manager: Coordinates task execution, manages resource access, and enforces authorization and prioritization.
System Monitor: Controls and monitors the cryogenic system, providing diagnostics and performance metrics.
Services are extensible. Users can create new services or customize existing ones to better fit their experimental setups or workflows.
Task Manager#
The task manager acts as a central coordinator for all tasks and events within the OrangeQS Juice installation. It queues and routes tasks to the appropriate services. It receives and forwards events to the relevant subscribers. See Communication for more details on how the task manager facilitates communication between components.
System Monitor#
The System Monitor is a feature primarily designed to oversee and manage your cryogenic equipment. It provides a standardized set of interfaces that hardware drivers can implement. Users can use the provided APIs to then spawn a service that monitors your equipment. This makes the System Monitor a flexible and powerful tool for maintaining control and visibility over complex experimental setups. OrangeQS provides drivers for interacting with common cryogenic equipment. For more details, see System Monitor
Device#
The device service is responsible for managing and interacting with the control electronics in your setup. It runs the main measurement loop and executes the measurement tasks sent by the task manager. As a Juice service runs as an IPython kernel, it can use any Python control software for interacting with your control electronics.
Custom services#
OrangeQS Juice allows users to easily create custom services to fit specific needs. Users can create a new service by writing a custom initialization script and registering it in the configuration. Some ideas for what a custom service could do include:
Automatic post-processing of measurement data. Such a service could subscribe to raw measurement events and perform automatic analysis or calculate long-term trends.
Forwarding data to external systems. For example, this service could subscribe to measurement events and forward the data to an external company database or monitoring system.
Receiving commands from external systems. This service could receive commands from an external system and execute them on the quantum chip. For example, this is how Juice is used as an execution backend for Quantum Inspire.
Customizing Juice
The services explained above are just the default set of services. At its core, OrangeQS Juice is a framework for building a custom measurement system. It’s a collection of standards and protocols that you can use to build your own custom system. The Juice configuration allows you to add any set of services, with arbitrary roles. This means you can build a completely different system on top of the Juice framework, while still benefiting from the features provided by Juice, such as the dashboard, data storage, and communication patterns.
User container#
The user container is an isolated container that runs all user applications. Each user gets their own user container when they log in through JupyterHub. See The JupyterHub single-user server in the JupyterHub docs for more details.
Below is a description of the applications running in the user container of OrangeQS Juice.
Dashboard#
The dashboard is the central interface for operators interacting with an OrangeQS Juice installation. After logging in, users are greeted with the dashboard, which provides a centralized place for monitoring and managing the system. The dashboard includes various widgets and pages that allow users to perform tasks such as:
Monitoring the host system status (CPU, memory, disk usage)
Monitoring the status of the services (whether they are running, their logs, etc.)
Monitoring the status of experiments (live plotting, progress, etc.)
Managing experiments (starting, stopping, scheduling, etc.)
Managing your cryogenic system (temperature readings, controlling valves, starting cooldown, etc.)
The dashboard can also be extended with custom widgets and pages to suit a lab’s needs. A tutorial to create a custom page can be found at Creating a new dashboard page.
JupyterLab#
JupyterLab provides an interface for users to write and execute code in notebooks. This is useful for running analysis scripts or interacting with the system programmatically.
File browser#
The file browser allows users to browse their own files and shared files. Under the hood, this is running the File Browser application.
VS Code#
The VS Code application provides a web-based version of VS Code for editing code and files. Under the hood, this is running the code-server application.
Data storage#
Data generated by the system, such as measurement results and logs, are stored in a centralized place. There are two main types of data storage in OrangeQS Juice: InfluxDB2 for time-series structured data and a shared folder for unstructured or large data files.
InfluxDB2#
Juice ships with an integrated InfluxDB2 time-series database for storing structured data. Only Juice services can write to InfluxDB2, but both services and user applications can read from it. InfluxDB2 is optimized for storing and querying time-series data, making it ideal for storing measurement quantities over time. Examples include fridge temperature readings, qubit performance metrics, or experiment results.
The Juice framework provides a standardized way to build schemas for your data and using these schemas to write and query data from InfluxDB2. See Database for a detailed description.
User folder#
Each user also has their own private folder for storing personal files. This folder is accessible only to the user.
Communication#
There are two main ways for components to communicate with each other in OrangeQS Juice. The first is a publish-subscribe pattern, where components can subscribe to certain events and get notified when they occur. The second is a request-reply pattern, where components can send tasks to each other and get a reply back.
Publish-subscribe#
In the publish-subscribe pattern, all components can publish events to the system and subscribe to events they are interested in. All published events are sent to the task manager, which then forwards them to the relevant subscribers.
All messages sent over the publish-subscribe pattern are called events. Each event has a topic associated with it. The topic is used to determine which subscribers should receive the event. The task manager keeps track of all subscribed topics per subscriber.
Each event is sent to the task manager by a publisher. Publishers can be both services and user applications. The task manager looks up the subscriptions for the event’s topic. It forwards the event to all subscribers that are subscribed to the topic. Both services and user applications can subscribe to events.
Request-reply#
In the request-reply pattern, services and user applications can send tasks to services and get a reply back. All tasks are sent to the task manager, which then forwards them to the requested service. The task manager receives the result and sends it back to the client.
Requests sent over the request-reply pattern are called tasks. A task has two main properties: a target service and a task type. The target service is used to determine which service should receive the task. The task type is used to determine which handler on the target service should process the task.
Each task is sent to the task manager by a client. Clients can be both services and user applications. The target service is always a Juice service, so never a user application. The task manager looks up the target service for the task and forwards it to the service. The target service looks up the registered handler for the task type and executes it. The target service sends the result back to the task manager, which then forwards it to the client.