Running a real-time experiment

You can open a real-time connection to a chamber and use it to send instructions and collect data. This is particularly suited for situations that require interaction, e.g., to test active learning, experiment design, or control algorithms—learn more in our case studies.

Basic workflow

You can find a complete example below.

1

Open a real-time connection to a chamber

Begin by opening a connection to a chamber—specified by its chamber_id—and loading a hardware configuration (given by config). The chamber will reset and set all inputs and sensor parameters to their default values.

Credentials file

If you stored your credentials in a file

import causalchamber.lab as lab

chamber = lab.Chamber(chamber_id, config, credentials_file = 'path/to/file')

Environment variables

2

Send instructions and receive data

You can now send instructions to the chamber and receive data in real time. There are three types of instructions.

SET instruction

chamber.set(target, value)

This sets the variable target to the given value, returning when the change has been made in the hardware. The above call returns None.

See the configuration docs for a list of variables and their valid / default values.

MEASURE instruction

WAIT instruction

To ensure experimental consistency, the chamber accepts only one active connection at a time; starting a new connection will invalidate the previous one. For long-running experiments and multiple users, we recommend using the experiment queue.

A complete example

Let's connect to a Light Tunnel Mk2 and collect images in real time.

import causalchamber.lab as lab

# Open a real-time connection
chamber = lab.Chamber(chamber_id = 'lt-demo-ch4lu',
                      config = 'camera_fast',
                      credentials_file = '.credentials')

# Turn on the light source to red and take one image
chamber.set('red', 255)
df, images = chamber.measure(n=1)

The returned data consists of two parts: df is a dataframe containing the sensor measurements, and images an array with the collected images (only one in this case).

Let's have a look at the resulting image.

# Plot the image
import matplotlib.pyplot as plt
plt.imshow(images[0])

Submitting multiple instructions at once

You can submit multiple instructions in a single batch. This saves you the round-trip to the chamber for each instruction and ensures consistent timing between instructions.

The data produced during the execution of the batch will be returned in batch.submit().

# Start a new batch
batch = chamber.new_batch()

# Add instructions
batch.set('red', 128)
batch.measure(n=1) # Image 1: red
batch.set('blue', 128)
batch.measure(n=1) # Image 2: purple
batch.set('pol_1', 90)
batch.measure(n=1) # Image 3: purple + crossed polarizers

# Submit the batch and receive the data
df, images = batch.submit()

To plot the resulting images:

# Plot the images
plt.figure(figsize=(9,3))
for i,im in enumerate(images):
    plt.subplot(1,3,i+1)
    plt.imshow(im)