Back to home page

Project CMSSW displayed by LXR



Warning, /HeterogeneousCore/SonicCore/ is written in an unsupported language. File is not indexed.

0001 # SONIC core infrastructure
0003 SONIC: Services for Optimized Network Inference on Coprocessors
0005 ## For analyzers
0007 The `SonicEDProducer` class template extends the basic Stream producer module in CMSSW.
0008 Similarly, `SonicEDFilter` extends the basic Stream filter module (replace `void produce` with `bool filter` below).
0010 To implement a concrete derived producer class, the following skeleton can be used:
0011 ```cpp
0012 #include "HeterogeneousCore/SonicCore/interface/SonicEDProducer.h"
0013 #include "FWCore/Framework/interface/MakerMacros.h"
0015 class MyProducer : public SonicEDProducer<Client>
0016 {
0017 public:
0018   explicit MyProducer(edm::ParameterSet const& cfg) : SonicEDProducer<Client>(cfg) {
0019     //do any necessary operations
0020   }
0021   void acquire(edm::Event const& iEvent, edm::EventSetup const& iSetup, Input& iInput) override {
0022     //convert event data to client input format
0023   }
0024   void produce(edm::Event& iEvent, edm::EventSetup const& iSetup, Output const& iOutput) override {
0025     //convert client output to event data format
0026   }
0027   static void fillDescriptions(edm::ConfigurationDescriptions & descriptions) {
0028     edm::ParameterSetDescription desc;
0029     Client::fillPSetDescription(desc);
0030     //add producer-specific parameters
0031     descriptions.add("MyProducer",desc);
0032   }
0033 };
0035 DEFINE_FWK_MODULE(MyProducer);
0036 ```
0038 The generic `Client` must be replaced with a concrete client (see next section), which has specific input and output types.
0040 The python configuration for the producer should include a dedicated `PSet` for the client parameters:
0041 ```python
0042 process.MyProducer = cms.EDProducer("MyProducer",
0043     Client = cms.PSet(
0044         # necessary client options go here
0045         mode = cms.string("Sync"),
0046         allowedTries = cms.untracked.uint32(0),
0047     )
0048 )
0049 ```
0050 These parameters can be prepopulated and validated by the client using `fillDescriptions()`.
0051 The `mode` and `allowedTries` parameters are always necessary (example values are shown here, but other values are also allowed).
0052 These parameters are described in the next section.
0054 In addition, there is a `SonicOneEDAnalyzer` class template for user analysis, e.g. to produce simple ROOT files.
0055 Only `Sync` mode is supported for clients used with One modules,
0056 but otherwise, the above template can be followed (replace `void produce(edm::Event&` with `void analyze(edm::Event const&` above).
0058 Examples of the producer, filter, and analyzer can be found in the [test](./test) folder.
0060 ## For developers
0062 To add a new communication protocol for SONIC, follow these steps:
0063 1. Submit the communication protocol software and any new dependencies to [cmsdist]( as externals
0064 2. Set up the concrete client(s) that use the communication protocol in a new package in the `HeterogeneousCore` subsystem
0065 3. Add a test producer (see above) to make sure it works
0067 To implement a concrete client, the following skeleton can be used for the `.h` file:
0068 ```cpp
0069 #ifndef HeterogeneousCore_MyPackage_MyClient
0070 #define HeterogeneousCore_MyPackage_MyClient
0072 #include "FWCore/ParameterSet/interface/ParameterSet.h"
0073 #include "HeterogeneousCore/SonicCore/interface/SonicClient.h"
0075 class MyClient : public SonicClient<Input,Output> {
0076 public:
0077   MyClient(const edm::ParameterSet& params, const std::string& debugName);
0079   static void fillPSetDescription(edm::ParameterSetDescription& iDesc);
0081 protected:
0082   void evaluate() override;
0083 };
0085 #endif
0086 ```
0088 The concrete client member function implementations, in an associated `.cc` file, should include the following:
0089 ```cpp
0090 MyClient::MyClient(const edm::ParameterSet& params, const std::string& debugName)
0091     : SonicClient(params, debugName, "MyClient") {
0092   //do any necessary operations
0093 }
0094 ```
0096 The `SonicClient` has three available modes:
0097 * `Sync`: synchronous call, blocks until the result is returned.
0098 * `Async`: asynchronous, non-blocking call.
0099 * `PseudoAsync`: turns a synchronous, blocking call into an asynchronous, non-blocking call, by waiting for the result in a separate `std::thread`.
0101 `Async` is the most efficient, but can only be used if asynchronous, non-blocking calls are supported by the communication protocol in use.
0103 In addition, as indicated, the input and output data types must be specified.
0104 (If both types are the same, only the input type needs to be specified.)
0105 The client constructor can optionally provide a value for `clientName_`,
0106 which will be used in output messages alongside the debug name set by the producers.
0108 In all cases, the implementation of `evaluate()` must call `finish()`.
0109 For the `Sync` and `PseudoAsync` modes, `finish()` should be called at the end of `evaluate()`.
0110 For the `Async` mode, `finish()` should be called inside the communication protocol callback function (implementations may vary).
0112 When `finish()` is called, the success or failure of the call should be conveyed.
0113 If a call fails, it can optionally be retried. This is only allowed if the call failure does not cause an exception.
0114 Therefore, if retrying is desired, any exception should be converted to a `LogWarning` or `LogError` message by the client.
0115 A Python configuration parameter can be provided to enable retries with a specified maximum number of allowed tries.
0117 The client must also provide a static method `fillPSetDescription()` to populate its parameters in the `fillDescriptions()` for the producers that use the client:
0118 ```cpp
0119 void MyClient::fillPSetDescription(edm::ParameterSetDescription& iDesc) {
0120   edm::ParameterSetDescription descClient;
0121   fillBasePSetDescription(descClient);
0122   //add parameters
0123   iDesc.add<edm::ParameterSetDescription>("Client",descClient);
0124 }
0125 ```
0127 As indicated, the `fillBasePSetDescription()` function should always be applied to the `descClient` object,
0128 to ensure that it includes the necessary parameters.
0129 (Calling `fillBasePSetDescription(descClient, false)` will omit the `allowedTries` parameter, disabling retries.)
0131 Example client code can be found in the `interface` and `src` directories of the other Sonic packages in this repository.