Flavour Tagging features

.github/workflows/CI.yml

@@ -3,39 +3,39 @@ on:
   push:
     branches:
       - main
-    tags: ['*']
+    tags: '*'
   pull_request:
-  workflow_dispatch:
 concurrency:
   # Skip intermediate builds: always.
   # Cancel intermediate builds: only if it is a pull request build.
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
 jobs:
   test:
-    name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }}
-    runs-on: ${{ matrix.os }}
-    timeout-minutes: 60
-    permissions: # needed to allow julia-actions/cache to proactively delete old caches that it has created
-      actions: write
-      contents: read
+    name: Julia ${{ matrix.version }} - ${{ matrix.platform.os }} - ${{ matrix.platform.arch }} - ${{ github.event_name }}
+    runs-on: ${{ matrix.platform.os }}
     strategy:
       fail-fast: false
       matrix:
+        platform:
+          - os: ubuntu-latest
+            arch: x64
+          - os: ubuntu-24.04-arm
+            arch: aarch64
         version:
-          - '1.11'
-          - '1.6'
-          - 'pre'
-        os:
-          - ubuntu-latest
-        arch:
-          - x64
+          - 'lts'
+          - '1'
     steps:
       - uses: actions/checkout@v4
       - uses: julia-actions/setup-julia@v2
         with:
           version: ${{ matrix.version }}
-          arch: ${{ matrix.arch }}
+          arch: ${{ matrix.platform.arch }}
       - uses: julia-actions/cache@v2
       - uses: julia-actions/julia-buildpkg@v1
       - uses: julia-actions/julia-runtest@v1
+      - uses: julia-actions/julia-processcoverage@v1
+      - uses: codecov/codecov-action@v5
+        with:
+            files: lcov.info
+            token: ${{ secrets.codecov_token }}

.gitignore

@@ -1 +1,12 @@
-/Manifest*.toml
+Manifest.toml
+*.DS_Store
+*.root
+examples/flavour-tagging/data/wc_pt_7classes_12_04_2023/fccee_fl.swp
+.vscode/
+
+# Misc files
+.DS_Store
+/notebooks/*
+**/profile/*
+/statprof/*
+/debug/*

CLAUDE.md

@@ -0,0 +1,65 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Common Development Commands
+
+### Build and Package Management
+- `julia --project` - Start Julia with the project environment
+- `] instantiate` - Install all dependencies from Project.toml
+- `] update` - Update dependencies
+- `] build` - Build the package
+
+### Testing
+- `julia --project -e 'using Pkg; Pkg.test()'` - Run all tests
+- `julia --project test/runtests.jl` - Run tests directly
+
+### Running Examples
+- `cd examples/flavour-tagging && julia --project simple-flavour-tagging.jl` - Run the flavour tagging example
+- First run `julia --project -e 'using Pkg; Pkg.resolve(); Pkg.instantiate()'` in the example directory
+
+### Formatting
+The repository uses automatic formatting via GitHub Actions. JuliaFormatter is used with default settings in pull requests.
+
+## High-Level Architecture
+
+JetTaggingFCC.jl is a Julia package for jet flavour tagging in high-energy physics, designed to integrate with the JetReconstruction.jl ecosystem. It uses ONNX neural network models to classify jets based on their quark flavour content (b-jets, c-jets, light jets).
+
+### Core Architecture Pattern
+
+1. **Main Module** (`JetTaggingFCC.jl`): Entry point that includes and exports the JetFlavourTagging submodule
+2. **Feature Extraction Pipeline**: Extracts 59 physics features from jet constituents:
+   - Basic kinematics (pt, energy, mass, etc.)
+   - Track parameters and covariance matrices
+   - Particle identification flags
+   - Impact parameters and relative measurements
+3. **ONNX Integration**: Uses ONNXRunTime.jl to run pre-trained neural networks for classification
+
+### Key Dependencies Integration
+
+- **EDM4hep.jl**: Provides the `ReconstructedParticle` type and event data model
+- **JetReconstruction.jl**: Core jet reconstruction algorithms (this package extends it)
+- **LorentzVectorHEP.jl**: 4-vector operations for particle physics
+- **StructArrays.jl**: Efficient storage of constituent collections
+
+### Data Flow
+
+1. Reconstructed particles → Jet reconstruction → Jet constituents
+2. Feature extraction from constituents (59 features per constituent)
+3. ONNX model inference → Flavour probabilities
+
+### Important Type Aliases
+
+```julia
+const JetConstituents = StructVector{ReconstructedParticle, <:Any}
+const JetConstituentsData = Vector{Float32}
+```
+
+Currently defined redundantly across modules - consider this when adding new types.
+
+## Development Notes
+
+- The package uses Julia's package extension mechanism - EDM4hep must be loaded to trigger the extension
+- Physical constants are centralized in `JetPhysicalConstants.jl` using PhysicalConstants.jl
+- Feature extraction functions follow the naming pattern `get_<feature_name>`
+- All "flavor" spellings have been standardized to "flavour" throughout the codebase

Project.toml

@@ -1,10 +1,26 @@
 name = "JetTaggingFCC"
 uuid = "12f500dc-52b1-4d85-9b70-29fa5347616c"
 authors = ["Harry <[email protected]> and contributors"]
-version = "1.0.0-DEV"
+version = "0.1.0"
+
+[deps]
+EDM4hep = "eb32b910-dde9-4347-8fce-cd6be3498f0c"
+JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
+JetReconstruction = "44e8cb2c-dfab-4825-9c70-d4808a591196"
+LorentzVectorHEP = "f612022c-142a-473f-8cfd-a09cf3793c6c"
+ONNXRunTime = "e034b28e-924e-41b2-b98f-d2bbeb830c6a"
+PhysicalConstants = "5ad8b20f-a522-5ce9-bfc9-ddf1d5bda6ab"
+StructArrays = "09ab397b-f2b6-538f-b94a-2f83cf4a842a"
 
 [compat]
-julia = "1.6.7"
+EDM4hep = "0.4.0"
+JSON = "0.21"
+JetReconstruction = "1.0"
+LorentzVectorHEP = "0.1.6"
+ONNXRunTime = "1.3.1"
+PhysicalConstants = "0.2.4"
+StructArrays = "0.6.18, 0.7"
+julia = "1.9"
 
 [extras]
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"

README.md

@@ -1,3 +1,22 @@
-# JetTaggingFCC
+# JetTaggingFCC.jl
 
 [![Build Status](https://github.com/JuliaHEP/JetTaggingFCC.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/JuliaHEP/JetTaggingFCC.jl/actions/workflows/CI.yml?query=branch%3Amain)
+
+Julia package for jet flavour tagging at Future Circular Collider (FCC)
+experiments using machine learning.
+
+## Overview
+
+JetTaggingFCC.jl provides tools for identifying the quark flavor content of jets
+in high-energy physics experiments. It uses ONNX neural network models to
+classify jets based on their constituent particles.
+
+## Features
+
+- Load and process EDM4hep event data to extract physics features from jet constituents
+- Run ONNX neural network inference for flavour classification
+
+See the `examples/` directory for detailed usage examples.
+
+**Important** This package need the pre-release version of `JetReconstruction`,
+so currently `Pkg.develop("JetReconstruction")` is required.

examples/flavour-tagging/Project.toml

@@ -0,0 +1,21 @@
+[deps]
+Accessors = "7d9f7c33-5ae7-4f3b-8dc6-eff91059b697"
+ArgParse = "c7e460c6-2fb9-53a9-8c5b-16f535851c63"
+CodecZlib = "944b1d66-785c-5afd-91f1-9de20f533193"
+CodecZstd = "6b39b394-51ab-5f42-8807-6242bab2b4c2"
+EDM4hep = "eb32b910-dde9-4347-8fce-cd6be3498f0c"
+EnumX = "4e289a0a-7415-4d19-859d-a7e5c4648b56"
+IJulia = "7073ff75-c697-5162-941a-fcdaad2a7d2a"
+JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
+JetReconstruction = "44e8cb2c-dfab-4825-9c70-d4808a591196"
+JetTaggingFCC = "12f500dc-52b1-4d85-9b70-29fa5347616c"
+Logging = "56ddb016-857b-54e1-b83d-db4d58db5568"
+LorentzVectorHEP = "f612022c-142a-473f-8cfd-a09cf3793c6c"
+LorentzVectors = "3f54b04b-17fc-5cd4-9758-90c048d965e3"
+MuladdMacro = "46d2c3a1-f734-5fdb-9937-b9b9aeba4221"
+ONNXRunTime = "e034b28e-924e-41b2-b98f-d2bbeb830c6a"
+PhysicalConstants = "5ad8b20f-a522-5ce9-bfc9-ddf1d5bda6ab"
+StructArrays = "09ab397b-f2b6-538f-b94a-2f83cf4a842a"
+
+[sources]
+JetTaggingFCC = {path = "../.."}

examples/flavour-tagging/README.md

@@ -0,0 +1,13 @@
+# Jet Reconstruction Flavour Tagging Module Examples
+
+## `simple-flavour-tagging.jl`
+
+```bash
+julia --project simple-flavour-tagging.jl
+```
+This script will perform a simple flavour tagging with one events only.
+It will use the `FlavourTagging` module to tag the jets in the event and print the results.
+
+## `simple-flavour-tagging.ipynb`
+
+The same as the above example, but using a Jupyter notebook.