Add a tutorial about writing heterogeneous code in CMSSW

It contains various modules and data structres:

an EDProducer to convert PFJets to a simplified SoA format
  - a heterogeneous global::EDProducer running on CPU
  - SoA data structures
  - automatic data transfers from host to device

an EDProducer to apply residual jet corrections on GPU
  - an asynchronous global::EDProducer running on GPU
  - a simple 1D kernel

an ESProducer for the jet corrections
  - a new EventSetup record
  - new “portable” data structures and EventSetup conditions
  - a heterogeneous ESProducer

an EDProducer to find all jet pairs and triplets passing some selection criteria
  - a stream::SynchronizingEDProducer
  - new persistent and local SoA data structures
  - automatic copy of a configuration object to the GPUs
  - more complex 2D and 3D kernels

an EDAnalyzer to print the N-tuplets
  - a traditional edm::EDAnalyzer running on CPU
  - automatic data transfers from device to host

It also contains a configuration file to run the full job on GPUs or on CPU.

Note: these packages are distributed under the GNU GPL v3 license.

Author: fwyzard

DataFormats/HeterogeneousTutorial/BuildFile.xml

@@ -0,0 +1,10 @@
+<use name="fmt"/>
+<use name="rootcore"/>
+<use name="DataFormats/Common"/>
+<use name="DataFormats/Portable"/>
+<use name="DataFormats/SoATemplate"/>
+<use name="HeterogeneousCore/AlpakaInterface"/>
+<flags ALPAKA_BACKENDS="!serial"/>
+<export>
+  <lib name="1"/>
+</export>

DataFormats/HeterogeneousTutorial/COPYING

@@ -0,0 +1,44 @@
+# Description
+
+This package is part of a tutorial about writing heterogeneous code in CMSSW.
+It contains various modules and data structres:
+    
+an EDProducer to convert PFJets to a simplified SoA format
+  - a heterogeneous global::EDProducer running on CPU
+  - SoA data structures
+  - automatic data transfers from host to device
+    
+an EDProducer to apply residual jet corrections on GPU
+  - an asynchronous global::EDProducer running on GPU
+  - a simple 1D kernel
+    
+an ESProducer for the jet corrections
+  - a new EventSetup record
+  - new “portable” data structures and EventSetup conditions
+  - a heterogeneous ESProducer
+    
+an EDProducer to find all jet pairs and triplets passing some selection criteria
+  - a stream::SynchronizingEDProducer
+  - new persistent and local SoA data structures
+  - automatic copy of a configuration object to the GPUs
+  - more complex 2D and 3D kernels
+    
+an EDAnalyzer to print the N-tuplets
+  - a traditional edm::EDAnalyzer running on CPU
+  - automatic data transfers from device to host
+
+It also contains a configuration file to run the full job on GPUs or on CPU.    
+
+
+# License
+
+This package is free software: you can redistribute it and/or modify it under the terms of
+the GNU General Public License as published by the Free Software Foundation, either
+version 3 of the License, or (at your option) any later version.
+
+This module is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with this
+package. If not, see <https://www.gnu.org/licenses/>.

DataFormats/HeterogeneousTutorial/README.md

@@ -0,0 +1,13 @@
+#ifndef DataFormats_HeterogeneousTutorial_interface_JetsHostCollection_h
+#define DataFormats_HeterogeneousTutorial_interface_JetsHostCollection_h
+
+#include "DataFormats/HeterogeneousTutorial/interface/JetsSoA.h"
+#include "DataFormats/Portable/interface/PortableHostCollection.h"
+
+namespace tutorial {
+
+  using JetsHostCollection = PortableHostCollection<JetsSoA>;
+
+}  // namespace tutorial
+
+#endif  // DataFormats_HeterogeneousTutorial_interface_JetsHostCollection_h

DataFormats/HeterogeneousTutorial/interface/JetsHostCollection.h

@@ -0,0 +1,23 @@
+#ifndef DataFormats_HeterogeneousTutorial_interface_JetsSoA_h
+#define DataFormats_HeterogeneousTutorial_interface_JetsSoA_h
+
+#include <ostream>
+
+#include "DataFormats/SoATemplate/interface/SoALayout.h"
+
+namespace tutorial {
+
+  GENERATE_SOA_LAYOUT(JetsSoALayout,
+                      // columns: one value per element
+                      SOA_COLUMN(float, pt),
+                      SOA_COLUMN(float, eta),
+                      SOA_COLUMN(float, phi),
+                      SOA_COLUMN(float, mass))
+
+  using JetsSoA = JetsSoALayout<>;
+
+  std::ostream& operator<<(std::ostream& out, JetsSoA::View::const_element const& jet);
+
+}  // namespace tutorial
+
+#endif  // DataFormats_HeterogeneousTutorial_interface_JetsSoA_h

DataFormats/HeterogeneousTutorial/interface/JetsSoA.h

@@ -0,0 +1,13 @@
+#ifndef DataFormats_HeterogeneousTutorial_interface_TripletsHostCollection_h
+#define DataFormats_HeterogeneousTutorial_interface_TripletsHostCollection_h
+
+#include "DataFormats/HeterogeneousTutorial/interface/TripletsSoA.h"
+#include "DataFormats/Portable/interface/PortableHostCollection.h"
+
+namespace tutorial {
+
+  using TripletsHostCollection = PortableHostCollection<TripletsSoA>;
+
+}  // namespace tutorial
+
+#endif  // DataFormats_HeterogeneousTutorial_interface_TripletsHostCollection_h

DataFormats/HeterogeneousTutorial/interface/TripletsHostCollection.h

@@ -0,0 +1,22 @@
+#ifndef DataFormats_HeterogeneousTutorial_interface_TripletsSoA_h
+#define DataFormats_HeterogeneousTutorial_interface_TripletsSoA_h
+
+#include "DataFormats/SoATemplate/interface/SoALayout.h"
+
+namespace tutorial {
+
+  constexpr const int kEmpty = -1;
+
+  GENERATE_SOA_LAYOUT(TripletsSoALayout,
+                      // scalars: one value per collection
+                      SOA_SCALAR(int, size),
+                      // columns: one value per element
+                      SOA_COLUMN(int, first),
+                      SOA_COLUMN(int, second),
+                      SOA_COLUMN(int, third))
+
+  using TripletsSoA = TripletsSoALayout<>;
+
+}  // namespace tutorial
+
+#endif  // DataFormats_HeterogeneousTutorial_interface_TripletsSoA_h

DataFormats/HeterogeneousTutorial/interface/TripletsSoA.h

@@ -0,0 +1,22 @@
+#ifndef DataFormats_HeterogeneousTutorial_interface_alpaka_JetsDeviceCollection_h
+#define DataFormats_HeterogeneousTutorial_interface_alpaka_JetsDeviceCollection_h
+
+#include "DataFormats/HeterogeneousTutorial/interface/JetsHostCollection.h"
+#include "DataFormats/HeterogeneousTutorial/interface/JetsSoA.h"
+#include "DataFormats/Portable/interface/alpaka/PortableCollection.h"
+#include "HeterogeneousCore/AlpakaInterface/interface/config.h"
+
+namespace ALPAKA_ACCELERATOR_NAMESPACE::tutorial {
+
+  // Make the names from the top-level tutorial namespace visible for unqualified lookup
+  // inside the ALPAKA_ACCELERATOR_NAMESPACE::tutorial namespace.
+  using namespace ::tutorial;
+
+  using JetsDeviceCollection = PortableCollection<JetsSoA>;
+
+}  // namespace ALPAKA_ACCELERATOR_NAMESPACE::tutorial
+
+// Check that the portable device collection for the host device is the same as the portable host collection.
+ASSERT_DEVICE_MATCHES_HOST_COLLECTION(tutorial::JetsDeviceCollection, tutorial::JetsHostCollection);
+
+#endif  // DataFormats_HeterogeneousTutorial_interface_alpaka_JetsDeviceCollection_h

DataFormats/HeterogeneousTutorial/interface/alpaka/JetsDeviceCollection.h

@@ -0,0 +1,22 @@
+#ifndef DataFormats_HeterogeneousTutorial_interface_alpaka_TripletsDeviceCollection_h
+#define DataFormats_HeterogeneousTutorial_interface_alpaka_TripletsDeviceCollection_h
+
+#include "DataFormats/HeterogeneousTutorial/interface/TripletsHostCollection.h"
+#include "DataFormats/HeterogeneousTutorial/interface/TripletsSoA.h"
+#include "DataFormats/Portable/interface/alpaka/PortableCollection.h"
+#include "HeterogeneousCore/AlpakaInterface/interface/config.h"
+
+namespace ALPAKA_ACCELERATOR_NAMESPACE::tutorial {
+
+  // Make the names from the top-level tutorial namespace visible for unqualified lookup
+  // inside the ALPAKA_ACCELERATOR_NAMESPACE::tutorial namespace.
+  using namespace ::tutorial;
+
+  using TripletsDeviceCollection = PortableCollection<TripletsSoA>;
+
+}  // namespace ALPAKA_ACCELERATOR_NAMESPACE::tutorial
+
+// Check that the portable device collection for the host device is the same as the portable host collection.
+ASSERT_DEVICE_MATCHES_HOST_COLLECTION(tutorial::TripletsDeviceCollection, tutorial::TripletsHostCollection);
+
+#endif  // DataFormats_HeterogeneousTutorial_interface_alpaka_TripletsDeviceCollection_h

DataFormats/HeterogeneousTutorial/interface/alpaka/TripletsDeviceCollection.h

@@ -0,0 +1,14 @@
+#include <ostream>
+
+#include <fmt/format.h>
+
+#include "DataFormats/HeterogeneousTutorial/interface/JetsSoA.h"
+
+namespace tutorial {
+
+  std::ostream& operator<<(std::ostream& out, JetsSoA::View::const_element const& jet) {
+    out << fmt::format("SoA jet (pt, eta, phi) {:8.3f}, {:6.3f}, {:6.3f}", jet.pt(), jet.eta(), jet.phi());
+    return out;
+  }
+
+}  // namespace tutorial