Port generic alpaka phi functions to DataFormats/Math

[VourMa]

During the review of the LST integration PR #45117 it was identified that some of the math functions rewritten in the alpaka framework for usage in the LST algorithm could be made more widely available in CMSSW by porting them to a more central package:

• CMSSW Integration of LST #45117 (comment)
• CMSSW Integration of LST #45117 (comment)

This PR follows up on those comments. After the initial PR review, the choice made was to port these functions under Heterogeneous/AlpakaMath. The function logic is as close as possible to the non-alpaka equivalent DataFormats/Math/interface/deltaPhi.h file.

This PR only introduces the new function to CMSSW + the relevant unit tests. A follow-up PR will be made to actually use these functions in the LST algorithm and delete the LST-specific implementations.

[cmsbuild]

cms-bot internal usage

[cmsbuild]

+code-checks

Logs: https://cmssdt.cern.ch/SDT/code-checks/cms-sw-PR-47033/43155

[cmsbuild]

A new Pull Request was created by @VourMa for master.

It involves the following packages:

• DataFormats/Math (reconstruction)

@cmsbuild, @jfernan2, @mandrenguyen can you please review it and eventually sign? Thanks.
@fabiocos, @felicepantaleo, @makortel, @missirol, @mmusich, @rovere this is something you requested to watch as well.
@antoniovilela, @mandrenguyen, @rappoccio, @sextonkennedy you are the release manager for this.

cms-bot commands are listed here

[makortel]

@cms-sw/heterogeneous-l2 (not sure if this PR would need to be assigned to heterogeneous as well)

The choice made was to port these functions under DataFormats/Math, creating a new folder, interface/alpaka but the exact placement could be discussed. The function logic is as close as possible to the non-alpaka equivalent DataFormats/Math/interface/deltaPhi.h file.

Thinking out loud

• Considering package dependencies, making DataFormats/Math to depend on Alpaka would add an unnecessary dependence on Alpaka to nearly all packages that presently depend on DataFormats/Math (376 direct dependents)
  • A proper dependence would need to be added to DataFormats/Math/BuildFile.xml
  • From dependency standpoint e.g. HeterogeneousCore/AlpakaInterface would be a natural placement. We could also think of a new package, e.g. AlpakaMath.
• Per https://github.com/cms-sw/cmssw/blob/master/HeterogeneousCore/AlpakaCore/README.md#overall-guidelines the header does not need to be in interface/alpaka, because it does not depend on ALPAKA_ACCELERATOR_NAMESPACE. The wording there doesn't preclude it though, although we have generally preferred to place such headers directly to interface directory.

[makortel]

I'd suggest to add unit tests.

[slava77]

Considering package dependencies, making DataFormats/Math to depend on Alpaka would add an unnecessary dependence on Alpaka to nearly all packages that presently depend on DataFormats/Math (376 direct dependents)

* A proper dependence would need to be added to `DataFormats/Math/BuildFile.xml`

is there a way to keep the dependence only via /alpaka directory includes? ... I guess the question goes in the direction of having it in a separate directory, effectively.

[makortel]

Considering package dependencies, making DataFormats/Math to depend on Alpaka would add an unnecessary dependence on Alpaka to nearly all packages that presently depend on DataFormats/Math (376 direct dependents)

* A proper dependence would need to be added to `DataFormats/Math/BuildFile.xml`

is there a way to keep the dependence only via /alpaka directory includes? ... I guess the question goes in the direction of having it in a separate directory, effectively.

No. For link-time dependencies that wouldn't work. Some source-level operations, like IIRC git cms-checkdeps -a, operate based on what files have been modified.

[VourMa]

Thinking out loud

• Considering package dependencies, making DataFormats/Math to depend on Alpaka would add an unnecessary dependence on Alpaka to nearly all packages that presently depend on DataFormats/Math (376 direct dependents)

  • A proper dependence would need to be added to DataFormats/Math/BuildFile.xml
  • From dependency standpoint e.g. HeterogeneousCore/AlpakaInterface would be a natural placement. We could also think of a new package, e.g. AlpakaMath.

• Per https://github.com/cms-sw/cmssw/blob/master/HeterogeneousCore/AlpakaCore/README.md#overall-guidelines the header does not need to be in interface/alpaka, because it does not depend on ALPAKA_ACCELERATOR_NAMESPACE. The wording there doesn't preclude it though, although we have generally preferred to place such headers directly to interface directory.

Based on this and the follow up discussion, I understand that the current placement is not ideal, since the dependencies cannot be reduced. During our internal review, I had this initially placed under a new DataFormats subpackage, so I revert and put it under DataFormats/AlpakaMath/interface (i.e. also dropping the alpaka directory).

[VourMa]

I'd suggest to add unit tests.

Sure. Do you have in mind some unit test that I can use as a template (to speed up the work and to make sure that I cover what needs to be tested)?

[slava77]

Based on this and the follow up discussion, I understand that the current placement is not ideal, since the dependencies cannot be reduced. During our internal review, I had this initially placed under a new DataFormats subpackage, so I revert and put it under DataFormats/AlpakaMath/interface (i.e. also dropping the alpaka directory).

IIUC, HeterogeneousCore/ subsystem was mentioned earlier by Matti, not DataFormats.

[VourMa]

Based on this and the follow up discussion, I understand that the current placement is not ideal, since the dependencies cannot be reduced. During our internal review, I had this initially placed under a new DataFormats subpackage, so I revert and put it under DataFormats/AlpakaMath/interface (i.e. also dropping the alpaka directory).

IIUC, HeterogeneousCore/ subsystem was mentioned earlier by Matti, not DataFormats.

Ah, sorry, I misinterpreted the comment to mean that the new subpackage would be under DataFormats. It's clear now, thanks.

[slava77]

Ah, sorry, I misinterpreted the comment to mean that the new subpackage would be under DataFormats. It's clear now, thanks.

I guess @makortel could confirm the preference to avoid further confusion.

[makortel]

I'd suggest to add unit tests.

Sure. Do you have in mind some unit test that I can use as a template (to speed up the work and to make sure that I cover what needs to be tested)?

By quick look I see the existing reco::deltaPhi() and reco::reduceRange() being used in assertive way in

cmssw/DataFormats/Math/test/testAtan2.cpp

Lines 187 to 189 in f55e6a5

	ok(deltaPhi(phi1, phi2), int2phi(ip1 - ip2));
	ok(deltaPhi(phi2, phi1), int2phi(ip2 - ip1));
	ok(toPhi(phi2 + phi1), int2phi(ip1 + ip2));

(and even there it is not immediately clear whether reduceRange() or int2phi() is the one being tested).

I'd say the primary objective would be to ensure all functions can be called for the relevant data types (I suppose both float and double) can be used in the kernel code for all backends, and ideally at least for some inputs the functions return expected values (trying to cover all corner cases is a potential rabbit hole though).

Here are a few rather simple Alpaka-using unit tests

• https://github.com/cms-sw/cmssw/blob/master/HeterogeneousCore/AlpakaInterface/test/alpaka/testAtomicPairCounter.dev.cc
• https://github.com/cms-sw/cmssw/blob/master/MagneticField/ParametrizedEngine/test/alpaka/testParabolicParametrizedMagneticField.dev.cc

I personally prefer the Catch2 unit test framework (used in testAtomicPairCounter.dev.cc), but that is not required.

[makortel]

Ah, sorry, I misinterpreted the comment to mean that the new subpackage would be under DataFormats. It's clear now, thanks.

I guess @makortel could confirm the preference to avoid further confusion.

I'd wait for next week before moving things around to get more feedback (after more people will presumably be back)

I would not be against DataFormats/AlpakaMath, but I'd ask the questions

• What is the probability these functions will be used in DataFormats code?
  • If guessed to be at most tiny, the package could well be placed in other subsystem to avoid placing non-DataFormat code in DataFormats
• What is the probability there will be more Alpaka-based math algorithms?
  • If guessed at most tiny, perhaps an existing package would be less of a burden than a new package for one header
  • If guessed to be above tiny (I could imagine this to be the case), a new package could be justified

[VourMa]

I would not be against DataFormats/AlpakaMath, but I'd ask the questions

• What is the probability these functions will be used in DataFormats code?

  • If guessed to be at most tiny, the package could well be placed in other subsystem to avoid placing non-DataFormat code in DataFormats

My estimation is that it's tiny, so I will not go with that option.

• What is the probability there will be more Alpaka-based math algorithms?

  • If guessed at most tiny, perhaps an existing package would be less of a burden than a new package for one header
  • If guessed to be above tiny (I could imagine this to be the case), a new package could be justified

I cannot really predict and I don't have a use case right now, but I can see people needing, e.g., deltaR in Alpaka code sooner than later. Based on that, I would go ahead and make a new AlpakaMath package. I will do so tomorrow, unless someone comes up with a strong preference.

[cmsbuild]

-code-checks

Logs: https://cmssdt.cern.ch/SDT/code-checks/cms-sw-PR-47033/43221

Code check has found code style and quality issues which could be resolved by applying following patch(s)

• code-format:
  https://cmssdt.cern.ch/SDT/code-checks/cms-sw-PR-47033/43221/code-format.patch
  e.g. curl -k https://cmssdt.cern.ch/SDT/code-checks/cms-sw-PR-47033/43221/code-format.patch | patch -p1
  You can also run scram build code-format to apply code format directly

[cmsbuild]

Pull request #47033 was updated. @cmsbuild can you please check and sign again.

[VourMa]

Thanks for the extra suggestions, @makortel, I applied all of them.

[slava77]

@cmsbuild please test

[cmsbuild]

+1

Size: This PR adds an extra 24KB to repository
Summary: https://cmssdt.cern.ch/SDT/jenkins-artifacts/pull-request-integration/PR-4e8216/43764/summary.html
COMMIT: b8880cf
CMSSW: CMSSW_15_0_X_2025-01-14-1100/el8_amd64_gcc12
Additional Tests: GPU
User test area: For local testing, you can use /cvmfs/cms-ci.cern.ch/week0/cms-sw/cmssw/47033/43764/install.sh to create a dev area with all the needed externals and cmssw changes.

Comparison Summary

Summary:

• No significant changes to the logs found
• Reco comparison results: 7 differences found in the comparisons
• DQMHistoTests: Total files compared: 49
• DQMHistoTests: Total histograms compared: 3819085
• DQMHistoTests: Total failures: 40
• DQMHistoTests: Total nulls: 0
• DQMHistoTests: Total successes: 3819025
• DQMHistoTests: Total skipped: 20
• DQMHistoTests: Total Missing objects: 0
• DQMHistoSizes: Histogram memory added: 0.0 KiB( 48 files compared)
• Checked 214 log files, 184 edm output root files, 49 DQM output files
• TriggerResults: no differences found

GPU Comparison Summary

Summary:

• No significant changes to the logs found
• Reco comparison results: 24 differences found in the comparisons
• DQMHistoTests: Total files compared: 7
• DQMHistoTests: Total histograms compared: 53071
• DQMHistoTests: Total failures: 864
• DQMHistoTests: Total nulls: 0
• DQMHistoTests: Total successes: 52207
• DQMHistoTests: Total skipped: 0
• DQMHistoTests: Total Missing objects: 0
• DQMHistoSizes: Histogram memory added: 0.0 KiB( 6 files compared)
• Checked 24 log files, 30 edm output root files, 7 DQM output files
• TriggerResults: no differences found

[fwyzard]

Just curious: why not simply

Suggested change

	T n = alpaka::math::round(acc, x * o2pi);
	T n = alpaka::math::round(acc, x / (T{2} * std::numbers::pi_v<T>));

or

Suggested change

	T n = alpaka::math::round(acc, x * o2pi);
	T n = alpaka::math::round(acc, x * std::numbers::inv_pi_v<T> * T{0.5});

?

[VourMa]

As initially mentioned, this was meant to be an alpaka-adjusted copy of the reco::reduceRange function

cmssw/DataFormats/Math/interface/deltaPhi.h

Lines 18 to 24 in a475844

	constexpr T reduceRange(T x) {
	constexpr T o2pi = 1. / (2. * M_PI);
	if (std::abs(x) <= T(M_PI))
	return x;
	T n = std::round(x * o2pi);
	return x - n * T(2. * M_PI);
	}

hence I didn't apply any other simplifications, apart from the ones suggested in this PR.

[fwyzard]

ok

[VourMa]

Anything still pending for this PR? Or can it be merged so that I can continue with the follow up PRs?

[makortel]

Anything still pending for this PR? Or can it be merged so that I can continue with the follow up PRs?

We can't formally sign until cms-sw/cms-bot#2413 gets merged and the package assigned

[cmsbuild]

Pull request #47033 was updated. @fwyzard, @makortel can you please check and sign again.

[smuzaffar]

cms-sw/cms-bot#2413 is merged now

[fwyzard]

+heterogeneous

[cmsbuild]

This pull request is fully signed and it will be integrated in one of the next master IBs (tests are also fine). This pull request will now be reviewed by the release team before it's merged. @rappoccio, @antoniovilela, @mandrenguyen, @sextonkennedy (and backports should be raised in the release meeting by the corresponding L2)

[mandrenguyen]

+1