Skip to content

n2plain-improved-scaling-on-multithread - #256

Open
HarshitNagpal29 wants to merge 9 commits into
JuliaHEP:mainfrom
HarshitNagpal29:n2plain-workspace
Open

HarshitNagpal29 wants to merge 9 commits into
JuliaHEP:mainfrom
HarshitNagpal29:n2plain-workspace

Conversation

@HarshitNagpal29

Copy link
Copy Markdown
Collaborator

Summary

This PR adds an opt-in reusable workspace for full N2Plain reconstruction, covering both hadron-collider and electron-positron algorithms.

The workspace reduces repeated per-event allocations by reusing reconstruction scratch arrays, jet storage, and clustering history while preserving the complete ClusterSequence semantics.

Changes

  • Add N2PlainWorkspace with support for:
    • PseudoJet storage for pp algorithms;
    • EEJet storage for e⁺e⁻ algorithms.
  • Add callback-scoped with_n2plain_reconstruction.
  • Reuse:
    • reconstructed jet storage;
    • complete clustering history;
    • pp nearest-neighbour and distance arrays;
    • e⁺e⁻ StructArray reconstruction storage.
  • Resize scratch arrays to the exact active event length.
  • Support caller-owned reusable output buffers through:
    inclusive_jets!(output, clusterseq)
    

Compatibility

This is an additive API change. Existing users continue receiving independently owned results. High-throughput applications can opt into reusable storage and copy only the values that must be retained.

@m-fila
m-fila self-requested a review August 16, 2026 22:18
@graeme-a-stewart graeme-a-stewart added this to the 2.0.0 Release milestone Sep 5, 2026
@graeme-a-stewart

Copy link
Copy Markdown
Member

Rebased into current head of main

@codecov

codecov Bot commented Sep 9, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 96.18321% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 83.89%. Comparing base (cf96463) to head (c983384).

Files with missing lines Patch % Lines
src/Workspace.jl 94.44% 4 Missing ⚠️
src/EEAlgorithm.jl 95.00% 1 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main     #256      +/-   ##
==========================================
+ Coverage   83.14%   83.89%   +0.74%     
==========================================
  Files          24       25       +1     
  Lines        1614     1720     +106     
==========================================
+ Hits         1342     1443     +101     
- Misses        272      277       +5     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Comment thread test/runtests.jl Resolved
Co-authored-by: Mateusz Jakub Fila <37295697+m-fila@users.noreply.github.com>
Comment thread docs/src/multithreading.md Outdated
ordinary, single-threaded reconstruction: their allocation overhead is small,
and the returned result can be retained freely.
The ordinary `jet_reconstruct`, `plain_jet_reconstruct`, and
`tiled_jet_reconstruct` interfaces return an independently owned

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mention also ee_genkt_algorithm as well (gosh, those names look rather inconsistent now!)

Comment thread docs/src/multithreading.md Outdated
pattern is available through `N2PlainWorkspace`:

```julia
workspace = N2PlainWorkspace(PseudoJet)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See comment below re. how to parameterise this on algorithm, not jet type

Comment thread docs/src/multithreading.md Outdated
end
```

`N2PlainWorkspace(EEJet)` provides the same reusable storage for e⁺e⁻

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See comment below re. how to parameterise this on algorithm, not jet type

Comment thread src/PlainAlgo.jl Outdated
preprocess = preprocess_escheme,
γ::Union{Real, Nothing} = nothing,
β::Union{Real, Nothing} = nothing)
is_pp(algorithm) ||

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How could this error occur? _n2plain_reconstruct_with_workspace! is an internal function, not to be called by users.

Comment thread src/PlainAlgo.jl Outdated
is_pp(algorithm) ||
throw(ArgumentError("algorithm $algorithm requires an EEJet N2PlainWorkspace"))
isnothing(β) ||
throw(ArgumentError("β is only supported by the Valencia algorithm"))

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So here we have a parameter that had to be nothing, so then why does it exist as a parameter at all?

Comment thread src/PlainAlgoStructs.jl Outdated

Reusable full-semantics storage for one N2Plain reconstruction worker.

`J` selects the reconstruction family: use `PseudoJet` for pp algorithms and

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, this is wrong - we should not parameterise on the jet type - a user could be working with any old jet type from their EDM, or, e.g., anything that supports LorentzVectorBase. PseudoJet and EEJet are not mandatory, we transform as needed.

Much better is to parameterise on the algorithm, which the user does know. I will make another comment re. how to do this generically.

@graeme-a-stewart

Copy link
Copy Markdown
Member

Great, thanks @HarshitNagpal29! My main technical comment here is that we should use the algorithm to parameterise the workspace, not the jet type.

One thing that seems to be missing, we have with_n2plain_reconstruction but what about with_ee_reconstruction? This should be added to support the same APIs with all the algorithms.

I would also say we should:

  • Should add a convenience function get_workspace(algorithm, event) that returns the correct workspace for the algorithm/event pair (using the set particle density used for Strategy::Best in jet_reconstruction())
    • And allow for a workspace to be passed to jet_reconstruct
  • Should be documented
  • Add borrow/MT test to examples/benchmark.sh and to test.sh

However, perhaps those last points can be a separate issue/PR, to keep this one clean and focused.

@graeme-a-stewart graeme-a-stewart left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hello @HarshitNagpal29 - thanks for the changes.

Looking at this again after a few weeks I really don't like using the name N2PlainWorkspace as it ties much too closely to pp N2Plain. It's just confusing to use that for an EE algorithm. My suggestion is to switch to PlainWorkspace.

The source code organisation is also muddled now, with functions appearing in the structs source files, and EE things appearing in N2PlainStucts, which is wrong. I have made a suggestion to add a Workspace.jl for common workspace definitions and to move functions back to their natural source files. (Aside: if there's an ordering problem, and I think there might be, then add further source files, e.g., EEWorkspace.jl and N2PlainWorkspace.jl that can be included after the necessary definitions are made.)

It is worth reflecting on the consistency for the N2TiledWorkspace as well now, e.g., it would now be better named TiledWorkspace in light of the above.

Comment thread docs/src/multithreading.md Outdated
owning interface instead.

For pp events where the N2Plain strategy is appropriate, the same workspace
pattern is available through `N2PlainWorkspace`:

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rename to PlainWorkspace - see below

Comment thread src/EEAlgorithm.jl Outdated
[`with_ee_reconstruction`](@ref). The returned sequence borrows
`workspace.jets` and `workspace.history`.
"""
function _n2plain_reconstruct_with_workspace!(workspace::N2PlainWorkspace{A, EEJet},

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This name is misleading - it should probably be _reconstruct_with_workspace(), using argument dispatch to pick this specialisation.

Comment thread src/PlainAlgo.jl Outdated

# Maps index from the compact array to the clusterseq jet vector
clusterseq_index::Vector{Int} = collect(1:N)
local kt2_array::Vector{Float64}

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove the local keyword. We should only use that when it's really needed - we rightly don't use global variables that would accidentally cause confusion in functions.

Comment thread src/PlainAlgo.jl Outdated
This is the pp implementation behind [`with_n2plain_reconstruction`](@ref).
The returned sequence borrows `workspace.jets` and `workspace.history`.
"""
function _n2plain_reconstruct_with_workspace!(workspace::N2PlainWorkspace{A, PseudoJet,

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As above, I think _reconstruct_with_workspace() would do the trick here (even though it's less misleading in this context to use n2plain).

Comment thread src/PlainAlgoStructs.jl Outdated
and is overwritten by its next reconstruction. Copy values that must outlive
that operation. A workspace must not be used concurrently or reentrantly.
"""
mutable struct N2PlainWorkspace{A, J, S}

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As this workspace can serve for pp N2Plain and the ee reconstructions it's just incorrect to have it live in PlainAlgoStructs which are tied to the N2Plain strategy.

I'd suggest that this moves to a new source file Workspace.jl.

I would also rename it as PlainWorkspace, to avoid N2Plain in the name, which is just going to cause some confusion to the user when it's used with e+e-.

Comment thread src/PlainAlgoStructs.jl Outdated
throw(ArgumentError("Unsupported jet algorithm: $algorithm"))
end

function _prepare_n2plain_recombination_jets!(jets::Vector{J},

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

n2plain -> plain

Comment thread src/PlainAlgoStructs.jl Outdated
return jets
end

function prepare_n2plain_recombination_jets!(workspace::N2PlainWorkspace,

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

n2plain -> plain

Comment thread src/PlainAlgoStructs.jl Outdated
concurrently executing worker must own a distinct workspace, and the caller
must prevent concurrent or reentrant use of the same workspace.
"""
function with_n2plain_reconstruction(f::F,

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This function should move to PlainAlgo.jl - it's a reconstruction entry point, not a stuct

Comment thread src/PlainAlgoStructs.jl Outdated
the next reconstruction using this workspace. Copy values that must outlive
that operation, and do not use one workspace concurrently or reentrantly.
"""
function with_ee_reconstruction(f::F,

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This function is particularly bad to have in PlainAlgoStructs.jl should be in EEAlgorithm.jl

Comment thread test/test-n2plain-kernel.jl Outdated
@@ -0,0 +1,371 @@
# Regression tests for reusable N2Plain reconstruction storage.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bad name - how about test-plain-workspace.jl?

@HarshitNagpal29

HarshitNagpal29 commented Oct 7, 2026 •

Copy link
Copy Markdown
Collaborator Author

Hello @HarshitNagpal29 - thanks for the changes.

Looking at this again after a few weeks I really don't like using the name N2PlainWorkspace as it ties much too closely to pp N2Plain. It's just confusing to use that for an EE algorithm. My suggestion is to switch to PlainWorkspace.

The source code organisation is also muddled now, with functions appearing in the structs source files, and EE things appearing in N2PlainStucts, which is wrong. I have made a suggestion to add a Workspace.jl for common workspace definitions and to move functions back to their natural source files. (Aside: if there's an ordering problem, and I think there might be, then add further source files, e.g., EEWorkspace.jl and N2PlainWorkspace.jl that can be included after the necessary definitions are made.)

It is worth reflecting on the consistency for the N2TiledWorkspace as well now, e.g., it would now be better named TiledWorkspace in light of the above.

Hello @graeme-a-stewart Sir, Ok I will try to apply this asap. 😊

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants