Warning, /firebird/docs/tutorials/02_run_local.md is written in an unsupported language. File is not indexed.
0001 # Running Firebird Locally
0002
0003 This tutorial explains how to run the Firebird backend (**Pyrobird**) on your local machine. This allows you to:
0004 - Load geometry and event files from your local disk.
0005 - Process large files without uploading them.
0006 - Use Firebird with your own simulation data.
0007
0008 ## 1. Install Pyrobird
0009
0010 Pyrobird is a Python package that serves as the backend for Firebird. You need Python 3.8 or newer.
0011
0012 Open your terminal and install it via pip:
0013
0014 ```bash
0015 python -m pip install --upgrade pyrobird
0016 ```
0017
0018 ## 2. Download Example Data
0019
0020 Let's download some example files to test your local setup. We'll use the `epic_craterlake` geometry and a sample collision event.
0021
0022 Create a directory for your data and download the files:
0023
0024 ```bash
0025 # Create a directory
0026 mkdir -p firebird_data
0027 cd firebird_data
0028
0029 # Download Geometry (ROOT file)
0030 wget https://github.com/eic/firebird/raw/main/firebird-ng/src/assets/data/epic_craterlake.root
0031
0032 # Download Events (Firebird ZIP format)
0033 wget https://github.com/eic/firebird/raw/main/firebird-ng/src/assets/data/py8_dis-cc_18x275_minq2-1000_minp-150mev_vtxcut-5m_nevt-5.v0.4.firebird.zip
0034 ```
0035
0036 ## 3. Start the Server
0037
0038 Now, start the Pyrobird server. By default, it serves files from the current directory (and its subdirectories).
0039 You can also manually specify a different directory using the `--work-path` option.
0040
0041 ```bash
0042 # Serve from the current directory (default)
0043 # (assuming you are in the firebird_data directory)
0044 pyrobird serve
0045
0046 # OR serve from a specific directory
0047 pyrobird serve --work-path=/firebird_data
0048 ```
0049
0050 You should see output indicating the server is running, usually on port `5454`.
0051
0052 > **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.
0053
0054 ## 4. Open Firebird and Load Local Files
0055
0056 1. Open Firebird in your browser (e.g., [https://eic.github.io/firebird](https://eic.github.io/firebird) or your local development version).
0057 2. Click **Configure** in the top menu.
0058 3. Scroll down to **Server API Configuration**.
0059 4. Toggle **"Use specific backend"** to **ON**.
0060 5. Ensure the URL is set to `http://localhost:5454` (this is the default).
0061 6. In the **Geometry** section, enter:
0062 ```
0063 local://epic_craterlake.root
0064 ```
0065 7. In the **Event Source: JSON** section, enter:
0066 ```
0067 local://py8_dis-cc_18x275_minq2-1000_minp-150mev_vtxcut-5m_nevt-5.v0.4.firebird.zip
0068 ```
0069 *(Tip: You can use the full filename you downloaded)*
0070
0071 8. Click **DISPLAY**.
0072
0073 You should now see the detector and events loaded from your local machine!
0074
0075 ## 5. Supported File Formats
0076
0077 Firebird and Pyrobird work together to support various file formats:
0078
0079 ### Geometry
0080 - **ROOT Files (`.root`)**: Standard ROOT geometry files (TGeo). This is the primary format for detector geometry.
0081
0082 ### Events
0083 - **DEX (JSON)**: The native ["Display Event Exchange"](../dex) format. It's a JSON-based format optimized for web display.
0084 - **Zipped DEX (`.zip`)**: A compressed archive containing DEX JSON files. This is efficient for sharing multiple events and large datasets.
0085 - **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.
0086
0087 > **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.
0088
0089 ## Next Steps
0090
0091 Now that you have a local setup, you can explore more advanced topics:
0092
0093 - **[Generating Trajectories](../dd4hep-plugin)**: Learn how to use the DD4Hep plugin to generate true particle trajectories from your simulations.
0094 - **[DEX Format](../dex)**: Learn about the Firebird Display Event Exchange format for event data.
