Saving Bluesky Runs into Tiled#

Install Tiled Server#

In addition to bluesky-tiled-plugins, this tutorial requires tiled and its server dependencies.

You will need Python 3.10 or later. You can check your version of Python by typing into a terminal:

python3 --version

It is recommended that you work in an isolated “virtual environment”, so this installation will not interfere with any existing Python software:

python3 -m venv ./venv
source ./venv/bin/activate

You can now use pip to install the library and its dependencies:

python3 -m pip install bluesky-tiled-plugins "tiled[server]"

Create a conda environment.

conda create -n try-tiled
conda activate try-tiled

Install the package.

conda install -c conda-forge bluesky-tiled-plugins tiled-server

Create a project.

uv init

Add bluesky-tiled-plugins to it.

uv add bluesky-tiled-plugins "tiled[server]"

Create a workspace.

pixi init

Add bluesky-tiled-plugins to it.

pixi add bluesky-tiled-plugins tiled-server

Complete Example#

A minimal simulated example of using TiledWriter in a Bluesky plan is shown below.

from bluesky import RunEngine
import bluesky.plans as bp
from bluesky_tiled_plugins import TiledWriter
from tiled.server import SimpleTiledServer
from tiled.client import from_uri
from ophyd.sim import det
from ophyd.sim import hw

# Initialize the Tiled server and client
save_path = "/path/to/save/detector_data"
tiled_server = SimpleTiledServer(readable_storage=[save_path])
tiled_client = from_uri(tiled_server.uri)

# Initialize the RunEngine and subscribe TiledWriter
RE = RunEngine()
tw = TiledWriter(tiled_client, batch_size=1)
RE.subscribe(tw)

# Run an experiment collecting internal data
(uid,) = RE(bp.count([det], 3))
data = tiled_client[uid]["primary/det"].read()

# Run an experiment collecting external data
(uid,) = RE(bp.count([hw(save_path=save_path).img], 2))
data = tiled_client[uid]["primary/img"].read()

Details#

Run SimpleTiledServer#

This starts a Tiled server, running on a background thread. This way of running the server is intended for “first steps” and embedded deployments. See the guide on deploying Tiled for Bluesky for more details.

# Initialize the Tiled server and client
save_path = "/path/to/save/detector_data"
tiled_server = SimpleTiledServer(readable_storage=[save_path])

Connect client#

This connects to the server.

tiled_client = from_uri(tiled_server.uri)

Note

If running the server in a separate process, container, or host, provide the appropriate address, i.e.

tiled_client = from_uri("http://...")

When used with detectors that write data directory to storage (e.g. on local disk, network file system, or object storage), it is necessary to set the readable_storage parameter. This grants the server permission to serve data at certain file paths(s).

Subscribe#

This configures the RunEngine to publish all Bluesky documents to the TiledWriter callback.

# Initialize the RunEngine and subscribe TiledWriter
RE = RunEngine()
tw = TiledWriter(tiled_client, batch_size=1)
RE.subscribe(tw)

By default TiledWriter caches documents into large batches before writing them to Tiled. For “live” access to data, set batch_size=1.

Acquire Data and Access It#

# Run an experiment collecting only internal (Event) data
(uid,) = RE(bp.count([det], 3))
data = tiled_client[uid]["primary/det"].read()

# Run an experiment collecting external (detector) data
(uid,) = RE(bp.count([hw(save_path=save_path).img], 2))
data = tiled_client[uid]["primary/img"].read()