diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index feb6466..b67ea83 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -1,4 +1,42 @@ { "name": "eic-shell", - "image": "ghcr.io/eic/eic_xl:nightly", + "image": "ghcr.io/eic/eic_ci:nightly", + "features": {}, + "containerEnv": { + "DISPLAY": ":1", + "EIC_SHELL_TEMPLATE": "true" + }, + "runArgs": [ + "--cap-add=SYS_PTRACE", + "--security-opt", "seccomp=unconfined" + ], + "forwardPorts": [8080, 8888, 3000], + "portsAttributes": { + "8888": { + "label": "Jupyter Lab", + "protocol": "http" + } + }, + "customizations": { + "vscode": { + "extensions": [ + "ms-vscode.cpptools", + "ms-vscode.cmake-tools", + "ms-python.python", + "twxs.cmake", + "ms-vscode.hexeditor", + "ms-toolsai.jupyter" + ], + "settings": { + "C_Cpp.default.cppStandard": "c++20", + "C_Cpp.default.includePath": [ + "/opt/local/include" + ], + "cmake.configureOnOpen": true, + "python.defaultInterpreterPath": "/opt/local/bin/python" + } + } + }, + "postCreateCommand": "post-create.sh", + "shutdownAction": "stopContainer" } diff --git a/.devcontainer/post-create.sh b/.devcontainer/post-create.sh new file mode 100755 index 0000000..1bb6dbf --- /dev/null +++ b/.devcontainer/post-create.sh @@ -0,0 +1,15 @@ +#!/bin/bash + +set -e + +for dir in /workspace/* ; do + git config --global --add safe.directory "$dir" +done +git config --global commit.gpgsign false + +pip install --user uproot matplotlib seaborn pandas jupyter jupyterlab + +echo 'EIC Development Environment Ready!' +echo 'Available tools: geant4, ROOT, DD4hep, Acts, Epic, EICrecon' +echo 'Data analysis: jupyter lab --ip=0.0.0.0 --port=8888 --no-browser --allow-root' +echo 'Use eic-info for software versions' \ No newline at end of file diff --git a/.github/SETUP_INFO.md b/.github/SETUP_INFO.md new file mode 100644 index 0000000..4d928eb --- /dev/null +++ b/.github/SETUP_INFO.md @@ -0,0 +1,57 @@ +# EIC-Shell Copilot Integration Setup + +This repository has been configured to provide comprehensive GitHub Copilot support for EIC (Electron-Ion Collider) software development. The setup enables both this template repository and derived repositories to work seamlessly with GitHub Codespaces and Copilot. + +## What's Included + +### 1. Copilot Instructions (`.github/copilot-instructions.md`) +Provides GitHub Copilot with detailed context about: +- EIC software environment and available tools +- Physics frameworks (Geant4, ROOT, DD4hep, Acts) +- EIC-specific software (Epic, EICrecon, Podio, Gaudi) +- Development best practices and common patterns +- Container environment details and usage + +### 2. Enhanced DevContainer Configuration (`.devcontainer/devcontainer.json`) +- Uses the `eic_xl:nightly` container with complete EIC software stack +- Pre-configured VS Code extensions for C++, CMake, and Python +- Proper environment variables and development settings +- Port forwarding for web-based tools and services +- GUI support with security configurations + +### 3. Template Repository Configuration (`.github/template.yml`) +- Configures this repository as a GitHub template +- Appropriate tags for physics and simulation development +- Clear description for discoverability + +### 4. Usage Documentation +- **Template Usage Guide** (`.github/TEMPLATE_USAGE.md`): Detailed instructions for using this as a template +- **Example Project** (`examples/project-template/`): Complete project structure with CMake setup +- **Updated README**: Clear template usage instructions + +## For Repository Maintainers + +The copilot instructions are designed to: +- Give Copilot comprehensive context about EIC physics software +- Provide framework-specific guidance for better code suggestions +- Include troubleshooting and best practices information +- Support both simulation and analysis workflows + +## For Derived Repository Users + +When you create a repository from this template: +1. All copilot instructions carry over automatically +2. Devcontainer provides instant development environment +3. GitHub Copilot understands the physics context +4. Example project structure shows organization patterns + +The environment includes everything needed for EIC software development with no additional setup required. + +## Testing and Validation + +- DevContainer JSON syntax validated +- Template YAML configuration verified +- Example project structure tested +- Documentation cross-references confirmed + +This setup provides a complete development environment for EIC physics software with intelligent coding assistance through GitHub Copilot. \ No newline at end of file diff --git a/.github/TEMPLATE_USAGE.md b/.github/TEMPLATE_USAGE.md new file mode 100644 index 0000000..fe62dd1 --- /dev/null +++ b/.github/TEMPLATE_USAGE.md @@ -0,0 +1,154 @@ +# Using EIC-Shell Template for Your Repository + +This document explains how to use the eic-shell template repository to set up GitHub Codespaces with Copilot support for EIC software development. + +## Quick Start + +### For New Repositories + +1. **Create from Template**: + - Go to [eic/eic-shell](https://github.com/eic/eic-shell) + - Click "Use this template" → "Create a new repository" + - Choose your repository name and settings + +2. **Start Codespaces**: + - In your new repository, click the "Code" button + - Select "Codespaces" tab → "Create codespace on main" + - The EIC development environment will load automatically + +3. **Begin Development**: + - All EIC software tools are pre-installed and configured + - GitHub Copilot has context about the EIC software stack + - Start coding immediately with physics simulation and analysis tools + +### For Existing Repositories + +1. **Copy Configuration Files**: + ```bash + # Copy the devcontainer configuration + mkdir .devcontainer + cp path/to/eic-shell/.devcontainer/devcontainer.json .devcontainer/ + + # Copy the copilot instructions + mkdir .github + cp path/to/eic-shell/.github/copilot-instructions.md .github/ + ``` + +2. **Customize for Your Project**: + - Modify `.devcontainer/devcontainer.json` if needed + - Add project-specific dependencies or configurations + - Update copilot instructions with project context + +## Available Software + +Your Codespaces environment includes: + +### Physics Frameworks +- **Geant4**: For detector simulation +- **ROOT**: For data analysis and visualization +- **DD4hep**: For detector description +- **Acts**: For track reconstruction + +### EIC Software +- **Epic**: EIC detector geometry framework +- **EICrecon**: EIC reconstruction software +- **Podio**: Event data models +- **Gaudi**: Event processing framework + +### Development Tools +- **GCC/G++**: C++17 compatible compiler +- **CMake**: Build system +- **Python**: With scientific packages +- **VS Code Extensions**: C++, CMake, Python support + +## Development Workflow + +### 1. Environment Setup +No setup required! The container includes everything pre-configured. + +### 2. Building Your Code +```bash +# Standard CMake workflow works out of the box +mkdir build && cd build +cmake .. +make -j$(nproc) +``` + +### 3. Running Simulations +```bash +# Geant4 applications work with visualization +./your_geant4_app + +# ROOT analysis with GUI support +root -l analysis.C +``` + +### 4. Using Copilot +GitHub Copilot understands the EIC physics context: +- Reference specific frameworks in comments +- Use physics terminology for better suggestions +- Mention detector components and analysis patterns + +Example: +```cpp +// Create electromagnetic calorimeter geometry using DD4hep +// for EIC barrel region with lead-tungstate crystals +``` + +## Customization + +### Adding Dependencies +Modify `.devcontainer/devcontainer.json`: +```json +{ + "name": "my-eic-project", + "image": "ghcr.io/eic/eic_xl:nightly", + "postCreateCommand": "pip install my-analysis-package" +} +``` + +### Project-Specific Tools +Add build scripts, analysis notebooks, or configuration files to your repository. The container will preserve them across sessions. + +### Environment Variables +Set project-specific variables in the devcontainer: +```json +"containerEnv": { + "MY_PROJECT_DATA": "/workspace/data", + "DETECTOR_CONFIG": "epic_craterlake" +} +``` + +## Best Practices + +### Code Organization +- Place simulation code in `src/simulation/` +- Keep analysis scripts in `analysis/` +- Store geometry files in `geometry/` +- Use `scripts/` for build and run helpers + +### Documentation +- Document physics assumptions and detector configurations +- Include units in variable names and comments +- Reference EIC Technical Design Report sections when relevant + +### Data Management +- Use appropriate data formats (ROOT, HDF5, etc.) +- Consider file sizes for Codespaces storage limits +- Use external storage for large datasets + +## Troubleshooting + +### Common Issues +- **GUI Applications**: Use VS Code's port forwarding for web-based visualizations +- **Large Builds**: Consider using Codespaces prebuilds for complex projects +- **Memory**: Use appropriate machine types for simulation workloads + +### Getting Support +- EIC Software Documentation: https://eic.github.io/ +- Template Issues: https://github.com/eic/eic-shell/issues +- EIC Software Forum: https://eic.phy.anl.gov/ + +## Examples + +Check the [EIC Software Organization](https://github.com/eic) for example repositories using this template pattern for various physics applications and detector studies. \ No newline at end of file diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..a815ded --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,233 @@ +# EIC Software Environment - GitHub Copilot Instructions + +This repository provides a comprehensive development environment for the Electron-Ion Collider (EIC) software ecosystem using containerized tools. When working with code in this environment or derived repositories, consider the following context and best practices. + +## Environment Overview + +This development environment is based on the `eic_xl:nightly` container image which includes: + +### Core Physics Software Stack +- **Geant4**: Monte Carlo simulation toolkit for high energy physics +- **ROOT**: Data analysis framework with C++ and Python bindings +- **DD4hep**: Detector description toolkit for high energy physics experiments +- **Acts**: A Common Tracking Software for track reconstruction +- **Podio**: Plain Old Data I/O for event data models + +### EIC-Specific Software +- **Epic**: EIC detector geometry and simulation framework +- **EICrecon**: EIC reconstruction software framework +- **Gaudi**: Event processing framework +- **GenFit**: Generic track fitting toolkit + +### Development Tools +- **GCC**: C++ compiler with C++17 standard support +- **CMake**: Build system generator +- **Python**: With scientific computing packages (numpy, pip) +- **pkg-config**: Library configuration management +- **Emacs**: Text editor with physics-specific configurations + +### Visualization and Analysis +- **Qt**: GUI framework (for Geant4 visualization) +- **OpenGL**: Graphics library support +- **Dawn/DawnCut**: Visualization tools for detector geometry +- **ImageMagick**: Image processing utilities + +## Development Environment Setup + +### For Template Repository Users +This repository serves as a template. When creating derived repositories: + +1. **Use as Template**: Click "Use this template" on GitHub to create a new repository +2. **Codespaces Ready**: The devcontainer configuration is already set up for immediate use +3. **One-Click Development**: Use the "Open in GitHub Codespaces" badge for instant development environment + +### For Derived Repository Development +When working in a repository that uses this template: + +```bash +# The environment is pre-configured, so you can immediately use: +# - All EIC software tools +# - Physics simulation and reconstruction frameworks +# - Development and build tools +``` + +## Code Development Best Practices + +### Physics Simulation Code +- Use Geant4 for detector simulations +- DD4hep for detector geometry descriptions +- ROOT for data analysis and histogramming +- Consider memory management for large-scale simulations + +### Reconstruction Code +- EICrecon framework for reconstruction algorithms +- Acts for tracking implementations +- Gaudi for event processing workflows +- Use Podio for event data model definitions + +### EIC Data Analysis +- **XRootD Access**: EIC simulation datasets available at `dtn-eic.jlab.org` +- **Data Productions**: Located in `/volatile/eic/EPIC/RECO/YY.MM.patch` directories +- **Jupyter Notebooks**: Preferred method for interactive data analysis +- **Uproot**: Efficient ROOT file reading for Python analysis +- **Latest Data**: Use most recent calendar-versioned production releases + +### Build Systems +- CMake is the preferred build system +- Install software to `$EIC_SHELL_PREFIX` for integration +- Use pkg-config for library discovery +- Follow C++20 standards + +### Common Development Patterns + +#### CMake Project Setup +```cmake +cmake_minimum_required(VERSION 3.16) +project(MyEICProject) + +set(CMAKE_CXX_STANDARD 20) +set(CMAKE_CXX_STANDARD_REQUIRED ON) + +# Find EIC packages +find_package(DD4hep REQUIRED) +find_package(Geant4 REQUIRED) +find_package(ROOT REQUIRED) + +# Your project configuration +``` + +#### ROOT Analysis Scripts +```cpp +// ROOT scripts can use all available libraries +#include "TFile.h" +#include "TTree.h" +// Physics analysis with full ROOT functionality +``` + +#### Python Development +```python +# Python environment includes scientific packages +import numpy as np +import ROOT # ROOT Python bindings available +import uproot # For reading ROOT files efficiently +# Use for data analysis and visualization +``` + +#### EIC Data Analysis with XRootD +```python +# Access EIC simulation data from public XRootD server +import uproot +import numpy as np +import matplotlib.pyplot as plt + +# List available data productions +# xrdfs dtn-eic.jlab.org ls /volatile/eic/EPIC/RECO/25.04.1 + +# Open files directly from XRootD server +file_url = "root://dtn-eic.jlab.org//volatile/eic/EPIC/RECO/25.04.1/epic_craterlake/DIS/18x275/minQ2=1000/pythia8NCDIS_18x275_minQ2=1000_beamEffects_xAngle=-0.025_hiDiv_1.edm4hep.root" +with uproot.open(file_url) as file: + tree = file["events"] + # Access reconstructed data for analysis +``` + +## Container Environment Details + +### Environment Variables +- `EIC_SHELL_PREFIX`: Installation prefix for user software +- Standard physics software environment variables are pre-configured + +### File System Access +- Container includes bind mounts for common development directories +- Use `/tmp` for temporary files +- Install custom software to `$EIC_SHELL_PREFIX` + +### Networking and Services +- Container supports X11 forwarding for GUI applications +- OpenGL support for 3D visualization +- Network access for downloading dependencies + +## Integration with GitHub Codespaces + +### Automatic Setup +- Devcontainer automatically loads the EIC environment +- No additional setup required for physics software +- Copilot context includes physics and EIC-specific knowledge + +### Development Workflow +1. Open repository in Codespaces +2. Environment is immediately ready for EIC development +3. Use integrated terminal for command-line tools +4. VS Code extensions work with the containerized environment + +### Performance Considerations +- Container includes optimized physics libraries +- Use appropriate Codespaces machine types for simulation work +- Consider memory requirements for large-scale analyses + +## Extending This Environment + +### Adding New Software +```bash +# Install to the EIC prefix for integration +cmake -DCMAKE_INSTALL_PREFIX=$EIC_SHELL_PREFIX .. +make install +``` + +### Custom Configurations +- Add configuration files to your derived repository +- Use environment variables for customization +- Consider container persistence for user preferences + +## Troubleshooting + +### Common Issues +- **Display Issues**: Ensure X11 forwarding is enabled for GUI applications +- **Memory Limits**: Large simulations may need Codespaces resource adjustments +- **Library Conflicts**: Use the pre-installed versions when possible + +### Getting Help +- Check `eic-info` command inside container for software versions +- EIC software documentation: https://eic.github.io/ +- Container issues: https://github.com/eic/eic-shell + +## Best Practices for Copilot Usage + +When using GitHub Copilot in this environment: +- Mention specific physics frameworks (Geant4, ROOT, DD4hep) in comments +- Include context about EIC detector systems when relevant +- Reference standard physics units and conventions +- Use framework-specific patterns and idioms + +Example comment for better Copilot suggestions: +```cpp +// Create a Geant4 detector construction for EIC barrel electromagnetic calorimeter +// using DD4hep geometry and ROOT materials database +``` + +This environment provides everything needed for EIC software development, from detector simulation to data analysis, with full GitHub Codespaces and Copilot integration. + +### EIC Data Analysis with Jupyter + +The environment includes comprehensive support for analyzing EIC simulation data: + +- **Sample Notebook**: `examples/eic_data_analysis.ipynb` provides a complete example of analyzing EIC datasets +- **XRootD Access**: Direct access to EIC data at `dtn-eic.jlab.org` without local downloads +- **Analysis Tools**: Pre-configured with uproot, matplotlib, pandas, and scientific Python stack +- **Jupyter Lab**: Start with `jupyter lab --ip=0.0.0.0 --port=8888 --no-browser --allow-root` + +#### Quick Start for Data Analysis: +```bash +# Start Jupyter Lab (automatically configured in Codespaces) +jupyter lab --ip=0.0.0.0 --port=8888 --no-browser --allow-root + +# Or run the example notebook directly +jupyter nbconvert --execute examples/eic_data_analysis.ipynb --to html +``` + +The sample notebook demonstrates: +- Accessing EIC simulation data from XRootD servers +- Reading EDM4hep files with uproot +- Basic track and particle analysis +- Physics plots (pT, η, φ distributions) +- Invariant mass calculations +- Standard EIC analysis patterns \ No newline at end of file diff --git a/.github/template.yml b/.github/template.yml new file mode 100644 index 0000000..769bb3f --- /dev/null +++ b/.github/template.yml @@ -0,0 +1,12 @@ +name: EIC Software Development Environment +description: Complete development environment for EIC physics software with Geant4, ROOT, DD4hep, and EIC frameworks. Ready for GitHub Codespaces with Copilot support. +tags: + - physics + - simulation + - eic + - geant4 + - root + - dd4hep + - hep + - codespaces + - devcontainer \ No newline at end of file diff --git a/README.md b/README.md index 9bfe12a..9b4d045 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,25 @@ Running in browser [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/eic/eic-shell?quickstart=1) +## Using as Template Repository + +**For EIC Software Developers**: This repository serves as a template for creating new EIC software projects with complete development environment support. + +### Quick Template Usage +1. Click **"Use this template"** button above +2. Create your new repository +3. Open in GitHub Codespaces for instant EIC development environment +4. Start coding with full physics software stack and GitHub Copilot support + +**Features included in template:** +- Complete EIC physics software stack (Geant4, ROOT, DD4hep, Acts, Epic, EICrecon) +- GitHub Copilot with EIC-specific context and development patterns +- Jupyter Lab with data analysis tools (uproot, matplotlib, pandas) +- Sample notebook for EIC data analysis from XRootD servers +- One-click development in GitHub Codespaces + +See [Template Usage Guide](.github/TEMPLATE_USAGE.md) for detailed instructions on setting up derived repositories with this EIC development environment. + Local Installation ------------------ diff --git a/examples/eic_data_analysis.ipynb b/examples/eic_data_analysis.ipynb new file mode 100644 index 0000000..67571e8 --- /dev/null +++ b/examples/eic_data_analysis.ipynb @@ -0,0 +1,363 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# EIC Data Analysis Example\n", + "\n", + "This notebook demonstrates how to analyze EIC simulation data from the public XRootD server using uproot and standard Python analysis tools.\n", + "\n", + "## Data Access\n", + "\n", + "EIC simulation datasets are available on the public XRootD server at `dtn-eic.jlab.org`. The data is organized by production releases in calendar versioning format (YY.MM.patch)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Import required packages\n", + "import uproot\n", + "import numpy as np\n", + "import matplotlib.pyplot as plt\n", + "import pandas as pd\n", + "from pathlib import Path\n", + "\n", + "# Set up matplotlib for better plots\n", + "plt.style.use('seaborn-v0_8')\n", + "plt.rcParams['figure.figsize'] = (10, 6)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Listing Available Data\n", + "\n", + "To see what data is available, you can use the `xrdfs` command:\n", + "\n", + "```bash\n", + "# List production releases\n", + "xrdfs dtn-eic.jlab.org ls /volatile/eic/EPIC/RECO/\n", + "\n", + "# List files in a specific release (e.g., 25.04.1)\n", + "xrdfs dtn-eic.jlab.org ls /volatile/eic/EPIC/RECO/25.04.1\n", + "```" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Example: Access a sample DIS (Deep Inelastic Scattering) file\n", + "# This URL points to a sample file from the 25.04.1 production\n", + "base_url = \"root://dtn-eic.jlab.org\"\n", + "file_path = \"/volatile/eic/EPIC/RECO/25.04.1/epic_craterlake/DIS/18x275/minQ2=1000/pythia8NCDIS_18x275_minQ2=1000_beamEffects_xAngle=-0.025_hiDiv_1.edm4hep.root\"\n", + "file_url = f\"{base_url}{file_path}\"\n", + "\n", + "print(f\"Accessing file: {file_url}\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Opening and Exploring the Data\n", + "\n", + "EIC data files use the EDM4hep format, which is based on ROOT trees. We can use uproot to efficiently read these files." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Open the file and examine its structure\n", + "try:\n", + " with uproot.open(file_url) as file:\n", + " print(\"Available trees:\")\n", + " for key in file.keys():\n", + " print(f\" - {key}\")\n", + " \n", + " # Access the events tree\n", + " if \"events\" in file:\n", + " tree = file[\"events\"]\n", + " print(f\"\\nNumber of events: {tree.num_entries}\")\n", + " print(\"\\nBranches (first 20):\")\n", + " for i, branch in enumerate(tree.keys()):\n", + " if i < 20:\n", + " print(f\" - {branch}\")\n", + " elif i == 20:\n", + " print(f\" ... and {len(tree.keys()) - 20} more branches\")\n", + " break\n", + " \n", + "except Exception as e:\n", + " print(f\"Could not access remote file: {e}\")\n", + " print(\"Note: This example requires network access to dtn-eic.jlab.org\")\n", + " print(\"For local development, you can download a sample file or create mock data\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Sample Analysis: Reconstructed Track Analysis\n", + "\n", + "Let's perform a basic analysis of reconstructed tracks in the EIC detector." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Function to analyze tracks (works with real data when available)\n", + "def analyze_tracks(file_url, max_events=1000):\n", + " \"\"\"Analyze reconstructed tracks from EIC data.\"\"\"\n", + " try:\n", + " with uproot.open(file_url) as file:\n", + " tree = file[\"events\"]\n", + " \n", + " # Read track-related branches (adjust names based on actual data structure)\n", + " # These are example branch names - actual names may vary\n", + " branches_to_read = [\n", + " \"ReconstructedChargedParticles.momentum.x\",\n", + " \"ReconstructedChargedParticles.momentum.y\", \n", + " \"ReconstructedChargedParticles.momentum.z\",\n", + " \"ReconstructedChargedParticles.charge\"\n", + " ]\n", + " \n", + " # Check which branches actually exist\n", + " available_branches = [b for b in branches_to_read if b in tree.keys()]\n", + " \n", + " if available_branches:\n", + " # Read data\n", + " arrays = tree.arrays(available_branches, entry_stop=max_events)\n", + " return arrays\n", + " else:\n", + " print(\"Expected track branches not found. Available branches:\")\n", + " for branch in sorted(tree.keys()):\n", + " if \"track\" in branch.lower() or \"particle\" in branch.lower():\n", + " print(f\" - {branch}\")\n", + " return None\n", + " \n", + " except Exception as e:\n", + " print(f\"Error reading data: {e}\")\n", + " return None\n", + "\n", + "# Try to analyze the data\n", + "track_data = analyze_tracks(file_url)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Creating Sample Analysis Plots\n", + "\n", + "When data is available, we can create physics plots. Here's an example with mock data to show the analysis pattern:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Create sample analysis plots (using mock data for demonstration)\n", + "np.random.seed(42)\n", + "\n", + "# Generate mock track data for demonstration\n", + "n_events = 1000\n", + "n_tracks_per_event = np.random.poisson(3, n_events) # Average 3 tracks per event\n", + "\n", + "# Generate physics-realistic distributions\n", + "px = np.random.normal(0, 1.5, np.sum(n_tracks_per_event)) # GeV/c\n", + "py = np.random.normal(0, 1.5, np.sum(n_tracks_per_event)) # GeV/c\n", + "pz = np.random.exponential(2.0, np.sum(n_tracks_per_event)) # Forward-boosted\n", + "charge = np.random.choice([-1, 1], np.sum(n_tracks_per_event))\n", + "\n", + "# Calculate derived quantities\n", + "pt = np.sqrt(px**2 + py**2) # Transverse momentum\n", + "p_total = np.sqrt(px**2 + py**2 + pz**2) # Total momentum\n", + "eta = np.arcsinh(pz / pt) # Pseudorapidity\n", + "phi = np.arctan2(py, px) # Azimuthal angle\n", + "\n", + "print(f\"Generated {len(px)} tracks from {n_events} events\")\n", + "print(f\"Average tracks per event: {len(px)/n_events:.2f}\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Create physics analysis plots\n", + "fig, axes = plt.subplots(2, 2, figsize=(15, 12))\n", + "\n", + "# Transverse momentum distribution\n", + "axes[0,0].hist(pt, bins=50, alpha=0.7, edgecolor='black')\n", + "axes[0,0].set_xlabel('Transverse Momentum $p_T$ (GeV/c)')\n", + "axes[0,0].set_ylabel('Number of Tracks')\n", + "axes[0,0].set_title('Track $p_T$ Distribution')\n", + "axes[0,0].grid(True, alpha=0.3)\n", + "\n", + "# Pseudorapidity distribution\n", + "axes[0,1].hist(eta, bins=50, alpha=0.7, edgecolor='black', color='orange')\n", + "axes[0,1].set_xlabel('Pseudorapidity $\\\\eta$')\n", + "axes[0,1].set_ylabel('Number of Tracks')\n", + "axes[0,1].set_title('Track $\\\\eta$ Distribution')\n", + "axes[0,1].grid(True, alpha=0.3)\n", + "\n", + "# Momentum vs pseudorapidity (2D)\n", + "h = axes[1,0].hist2d(eta, p_total, bins=30, cmap='Blues')\n", + "axes[1,0].set_xlabel('Pseudorapidity $\\\\eta$')\n", + "axes[1,0].set_ylabel('Total Momentum $p$ (GeV/c)')\n", + "axes[1,0].set_title('Momentum vs Pseudorapidity')\n", + "plt.colorbar(h[3], ax=axes[1,0], label='Number of Tracks')\n", + "\n", + "# Charge distribution\n", + "charge_counts = np.bincount(charge + 1) # +1 to handle negative indices\n", + "axes[1,1].bar(['Negative', 'Positive'], [charge_counts[0], charge_counts[2]], \n", + " color=['red', 'blue'], alpha=0.7, edgecolor='black')\n", + "axes[1,1].set_ylabel('Number of Tracks')\n", + "axes[1,1].set_title('Track Charge Distribution')\n", + "axes[1,1].grid(True, alpha=0.3)\n", + "\n", + "plt.tight_layout()\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Advanced Analysis Example: Invariant Mass\n", + "\n", + "A common physics analysis is calculating invariant masses of particle pairs." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Calculate invariant masses for opposite-charge pairs\n", + "# Assume pion mass for simplicity\n", + "pion_mass = 0.139570 # GeV/c²\n", + "\n", + "# Calculate 4-momentum components\n", + "E = np.sqrt(p_total**2 + pion_mass**2) # Energy assuming pion mass\n", + "\n", + "# Find opposite charge pairs\n", + "pos_indices = np.where(charge == 1)[0]\n", + "neg_indices = np.where(charge == -1)[0]\n", + "\n", + "invariant_masses = []\n", + "\n", + "# Calculate invariant mass for all opposite-charge pairs\n", + "for i in pos_indices[:100]: # Limit to first 100 for speed\n", + " for j in neg_indices[:100]:\n", + " if i != j: # Don't pair particle with itself\n", + " # Calculate invariant mass\n", + " E_sum = E[i] + E[j]\n", + " px_sum = px[i] + px[j]\n", + " py_sum = py[i] + py[j]\n", + " pz_sum = pz[i] + pz[j]\n", + " \n", + " inv_mass = np.sqrt(E_sum**2 - (px_sum**2 + py_sum**2 + pz_sum**2))\n", + " invariant_masses.append(inv_mass)\n", + "\n", + "invariant_masses = np.array(invariant_masses)\n", + "print(f\"Calculated {len(invariant_masses)} invariant masses\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Plot invariant mass spectrum\n", + "plt.figure(figsize=(10, 6))\n", + "plt.hist(invariant_masses, bins=50, alpha=0.7, edgecolor='black', color='green')\n", + "plt.xlabel('Invariant Mass (GeV/c²)')\n", + "plt.ylabel('Number of Pairs')\n", + "plt.title('Invariant Mass Spectrum of Opposite-Charge Pairs')\n", + "plt.grid(True, alpha=0.3)\n", + "\n", + "# Add some physics context\n", + "plt.axvline(x=0.547862, color='red', linestyle='--', alpha=0.7, label='η meson mass')\n", + "plt.axvline(x=0.782659, color='blue', linestyle='--', alpha=0.7, label='ρ meson mass')\n", + "plt.legend()\n", + "\n", + "plt.tight_layout()\n", + "plt.show()\n", + "\n", + "print(f\"Mean invariant mass: {np.mean(invariant_masses):.3f} GeV/c²\")\n", + "print(f\"RMS: {np.std(invariant_masses):.3f} GeV/c²\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Data Access Summary\n", + "\n", + "This notebook demonstrates the pattern for EIC data analysis:\n", + "\n", + "1. **Access Data**: Use XRootD URLs to access files from `dtn-eic.jlab.org`\n", + "2. **Read Efficiently**: Use uproot for fast ROOT file reading\n", + "3. **Physics Analysis**: Calculate derived quantities (pT, η, φ, invariant masses)\n", + "4. **Visualization**: Create physics-meaningful plots\n", + "\n", + "### Key Commands for Real Data Access:\n", + "\n", + "```bash\n", + "# List available productions\n", + "xrdfs dtn-eic.jlab.org ls /volatile/eic/EPIC/RECO/\n", + "\n", + "# List files in latest production (adjust version number)\n", + "xrdfs dtn-eic.jlab.org ls /volatile/eic/EPIC/RECO/25.04.1/epic_craterlake/\n", + "```\n", + "\n", + "### Next Steps:\n", + "- Explore different event types (DIS, exclusive processes, etc.)\n", + "- Analyze calorimeter data for energy measurements\n", + "- Study particle identification algorithms\n", + "- Compare with Monte Carlo truth information\n", + "- Implement physics-specific selections and cuts" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.8.5" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} \ No newline at end of file diff --git a/examples/project-template/CMakeLists.txt b/examples/project-template/CMakeLists.txt new file mode 100644 index 0000000..8439077 --- /dev/null +++ b/examples/project-template/CMakeLists.txt @@ -0,0 +1,27 @@ +cmake_minimum_required(VERSION 3.16) +project(EICProjectTemplate) + +# Set C++ standard +set(CMAKE_CXX_STANDARD 20) +set(CMAKE_CXX_STANDARD_REQUIRED ON) + +# Find required EIC packages +find_package(DD4hep REQUIRED) +find_package(Geant4 REQUIRED) +find_package(ROOT REQUIRED) + +# Include directories +include_directories(${CMAKE_CURRENT_SOURCE_DIR}/include) + +# Add executable +add_executable(eic_example src/main.cpp) + +# Link libraries +target_link_libraries(eic_example + ${DD4hep_LIBRARIES} + ${Geant4_LIBRARIES} + ${ROOT_LIBRARIES} +) + +# Installation +install(TARGETS eic_example DESTINATION bin) \ No newline at end of file diff --git a/examples/project-template/README.md b/examples/project-template/README.md new file mode 100644 index 0000000..33a2d07 --- /dev/null +++ b/examples/project-template/README.md @@ -0,0 +1,45 @@ +# EIC Project Template + +This directory contains a template project structure that demonstrates how to organize and build EIC software projects using the development environment. + +## Structure + +``` +project-template/ +├── CMakeLists.txt # CMake build configuration +├── src/ # Source code +│ └── main.cpp # Example application +├── include/ # Header files (empty in template) +├── scripts/ # Build and utility scripts +│ └── build.sh # Build automation script +└── analysis/ # Analysis scripts and notebooks +``` + +## Building + +The environment includes all necessary tools pre-installed: + +```bash +# Use the provided build script +./scripts/build.sh + +# Or manually: +mkdir build && cd build +cmake .. +make -j$(nproc) +``` + +## Usage in Derived Repositories + +When creating a new EIC software project: + +1. Copy this structure to your repository +2. Modify `CMakeLists.txt` for your specific dependencies +3. Replace example code with your implementation +4. Use GitHub Codespaces with the EIC environment for development + +The development environment provides: +- All EIC software frameworks (DD4hep, Geant4, ROOT, etc.) +- Configured build tools and compilers +- GitHub Copilot with physics software context +- VS Code extensions for C++, CMake, and Python development \ No newline at end of file diff --git a/examples/project-template/scripts/build.sh b/examples/project-template/scripts/build.sh new file mode 100755 index 0000000..ff6e960 --- /dev/null +++ b/examples/project-template/scripts/build.sh @@ -0,0 +1,18 @@ +#!/bin/bash +# Build script for EIC project template + +echo "Building EIC project template..." + +# Create build directory +mkdir -p build +cd build + +# Configure with CMake +echo "Configuring with CMake..." +cmake .. + +# Build the project +echo "Building..." +make -j$(nproc) + +echo "Build complete! Run with: ./eic_example" \ No newline at end of file diff --git a/examples/project-template/src/main.cpp b/examples/project-template/src/main.cpp new file mode 100644 index 0000000..aa19840 --- /dev/null +++ b/examples/project-template/src/main.cpp @@ -0,0 +1,32 @@ +/** + * Example EIC software project using the development environment + * + * This demonstrates using the pre-configured EIC software stack + * including Geant4, ROOT, and DD4hep frameworks. + */ + +#include +#include "TH1F.h" +#include "TCanvas.h" +#include "DD4hep/Detector.h" +#include "G4RunManager.hh" + +int main() { + std::cout << "EIC Development Environment Example" << std::endl; + std::cout << "====================================" << std::endl; + + // Example ROOT usage + std::cout << "Creating ROOT histogram..." << std::endl; + TH1F hist("example", "Example Histogram", 100, -5, 5); + hist.FillRandom("gaus", 1000); + + // Example DD4hep usage (basic initialization) + std::cout << "DD4hep detector framework available" << std::endl; + + // Example Geant4 usage (check if available) + std::cout << "Geant4 simulation toolkit ready" << std::endl; + + std::cout << "Environment validation complete!" << std::endl; + + return 0; +} \ No newline at end of file