Firebird Doc

Running Firebird Locally ​

This tutorial explains how to run the Firebird backend (Pyrobird) on your local machine. This allows you to:

  • Load geometry and event files from your local disk.
  • Process large files without uploading them.
  • Use Firebird with your own simulation data.

1. Install Pyrobird ​

Pyrobird is a Python package that serves as the backend for Firebird. You need Python 3.10 or newer.

Open your terminal and install it via pip:

bash
python -m pip install --upgrade pyrobird

2. Download Example Data ​

To test the local setup, download the epic_craterlake geometry and a file of sample collision events into a directory of their own:

bash
# Create a directory
mkdir -p firebird_data
cd firebird_data

# Download Geometry (ROOT file)
wget https://seeeic.org/g/epic/artifacts/tgeo/epic_craterlake.root

# Download Events (DEX 1.0, zipped)
wget https://seeeic.org/d/py8dis-nc_10x100_minq2-1000_minp-250mev_nevt-5.v1.firebird.zip

3. Start the Server ​

Now, start the Pyrobird server. By default, it serves files from the current directory (and its subdirectories). You can also manually specify a different directory using the --work-path option.

bash
# Serve from the current directory (default)
# (assuming you are in the firebird_data directory)
pyrobird serve --allow-cors

# OR serve from a specific directory
pyrobird serve --allow-cors --work-path=/path/to/firebird_data

You should see output indicating the server is running, usually on port 5454.

--allow-cors lets a Firebird page served from another address (the hosted display, or a development server on port 4200) call this server. You can leave it out when you open Firebird from pyrobird itself at http://localhost:5454: the page then uses the server it came from, and you can skip the backend settings in the next section.

Note on Security: By default, pyrobird only allows access to files in the directory specified by --work-path. This is a security feature to prevent accidental exposure of your system files.

4. Open Firebird and Load Local Files ​

  1. Open Firebird in your browser: the hosted display at https://seeeic.org, or a development server.

  2. Click Configure in the top menu.

  3. Scroll down to Server API Configuration.

  4. Toggle "Use specific backend" to ON.

  5. Ensure the URL is set to http://localhost:5454 (this is the default). Under Backend Details, Backend in use now shows this address. The browser may ask whether the page may access devices on your local network; allow it.

  6. Scroll back up to Select Geometry and Events and open the Manual tab.

  7. In the Geometry field, enter:

    local://epic_craterlake.root

  8. In the Events field, enter:

    local://py8dis-nc_10x100_minq2-1000_minp-250mev_nevt-5.v1.firebird.zip

    (Tip: You can use the full filename you downloaded)

  9. Click Display.

You should now see the detector and events loaded from your local machine!

5. Supported File Formats ​

Firebird and Pyrobird work together to support various file formats:

Geometry ​

  • ROOT Files (.root): Standard ROOT geometry files (TGeo). This is the primary format for detector geometry.

Events ​

  • DEX (JSON): The native Firebird Data Exchange format, JSON designed for web display.
  • Zipped DEX (.zip): A compressed archive containing DEX JSON files. This is efficient for sharing multiple events and large datasets.
  • EDM4EIC (.root): The standard data model for the EIC. Pyrobird can automatically convert these files to DEX format on-the-fly when you request them.

Note: When using pyrobird serve, you can point to any of these files using the local:// prefix, and the server will handle the necessary conversions.

Next Steps ​

Now that you have a local setup, you can explore more advanced topics:

  • Generating Trajectories: Learn how to use the DD4Hep plugin to generate true particle trajectories from your simulations.
  • DEX Format: Learn about the Firebird Data Exchange format for event data.