BmnGemStripFdeepModel.h

Go to the documentation of this file.

#ifndef BMNGEMSTRIPFDEEPMODEL_H
#define BMNGEMSTRIPFDEEPMODEL_H
 
// Neural network inference for the GEM strip simulation with frugally-deep (fdeep).
//
// BmnGemStripFdeepModel - a Keras model converted to fdeep .json (convert_model.py of frugally-deep):
//   2D model    (AddRealPointFull_ANNGenerator):
//                 [px, py, pz, drift, bfield, s0..s15] -> image 80 x 80
//   strip model (AddRealPointFull_ANNStripGenerator_Fdeep, AddRealPointFull_ANNStripGenerator_Fdeep_Parallel):
//                 [px, py, pz, drift, bfield, s0..s63, strip_layer, strip_order, center_frac] -> N strips
//                 (window of odd size N centered at the middle of the drift gap)
// The model must have one input and one output (both are flattened here).
//
// frugally-deep is used only in BmnGemStripFdeepModel.cxx: this header does not need it.
// Without fdeep (fdeep/fdeep.hpp not found when building, or -DBMN_WITH_FDEEP=0) the models are never loaded:
// Load() returns false, GetShared() returns nullptr and the ANN methods use the standard method.
//
// Usage (the same as BmnGemStripMLPModel):
//   auto model = BmnGemStripFdeepModel::GetShared();               // default path (strip model), shared between
//   modules auto model = BmnGemStripFdeepModel::GetShared("my.json");      // explicit path
//   BmnGemStripFdeepModel::SetDefaultPath("$VMCWORKDIR/parameters/gem/ANNModels/my_2d_model.json");   // e.g. the 2D
//   model model->Predict(input, output);                                  // input_dim floats -> output_dim floats
//   std::vector<float> out = model->Predict(input_vector);         // the same, empty vector if failed
//
// After loading the model is not modified: Predict() can be called from several threads at once.
 
#include <iostream>
#include <memory>
#include <string>
#include <vector>
 
class BmnGemStripFdeepModel
{
 
  public:
    // Constructors -------------------------------------------------------------
    BmnGemStripFdeepModel();
    explicit BmnGemStripFdeepModel(const std::string& path, bool verbose = true);   // Load(path)
    //--------------------------------------------------------------------------
 
    // Destructor
    virtual ~BmnGemStripFdeepModel();
 
    // Loading ------------------------------------------------------------------
    // Reads the fdeep .json model (without the fdeep verification on the test data of the file - fast loading).
    // Returns false (and the model stays empty) if anything is wrong; the reason is printed (LOG(error)) if verbose.
    bool Load(const std::string& path, bool verbose = true);
    void Clear();
    bool IsLoaded() const { return fLoaded; }
 
    // true if the library is built with frugally-deep (otherwise no model can be loaded)
    static bool IsBuiltWithFdeep();
    //--------------------------------------------------------------------------
 
    // Model parameters ---------------------------------------------------------
    int GetInputDim() const { return fInputDim; }     // size of the (flattened) input
    int GetOutputDim() const { return fOutputDim; }   // size of the (flattened) output
    const std::string& GetFilePath() const { return fFilePath; }
 
    void Print(std::ostream& os = std::cout) const;   // short summary
    //--------------------------------------------------------------------------
 
    // Inference ----------------------------------------------------------------
    // One sample: input[GetInputDim()] -> output[GetOutputDim()]
    bool Predict(const float* input, float* output) const;
    // The same with vectors: input.size() must be GetInputDim(); returns an empty vector if failed
    std::vector<float> Predict(const std::vector<float>& input) const;
 
    // Several samples with a common first part of the input (the same call as in BmnGemStripMLPModel):
    //   input of row r = [ common[0 .. n_common-1], specific[r*n_spec .. r*n_spec + n_spec-1] ],
    //   n_spec = GetInputDim() - n_common,
    //   output[r*GetOutputDim() .. ] - output of row r.
    // Here each row is predicted separately (no speed-up, only the common interface).
    bool PredictSplit(const float* common, int n_common, const float* specific, int n_rows, float* output) const;
    //--------------------------------------------------------------------------
 
    // Shared models (one copy per file in the process) --------------------------
    // path: "" - the default path; environment variables ($VMCWORKDIR, ~, ...) are expanded (gSystem->ExpandPathName).
    // The same file given by different strings is loaded once (the cache key is the expanded path).
    // A file that failed to load is not reloaded on each call (the warning is printed once);
    // ClearSharedCache() resets this.
    static std::shared_ptr<const BmnGemStripFdeepModel> GetShared(const std::string& path = "");
    static void SetDefaultPath(const std::string& path);
    static std::string GetDefaultPath();
    static std::string GetBuiltinDefaultPath();   // "$VMCWORKDIR/parameters/gem/ANNModels/GEM_DefaultModel.json"
    static void ClearSharedCache();
    //--------------------------------------------------------------------------
 
  private:
    BmnGemStripFdeepModel(const BmnGemStripFdeepModel&) = delete;
    BmnGemStripFdeepModel& operator=(const BmnGemStripFdeepModel&) = delete;
 
  private:
    struct Impl;                   // fdeep model (defined in BmnGemStripFdeepModel.cxx only)
    std::unique_ptr<Impl> fImpl;   // nullptr if not loaded
 
    bool fLoaded;
    int fInputDim;
    int fOutputDim;
    std::string fFilePath;
};
//------------------------------------------------------------------------------
 
#endif /* BMNGEMSTRIPFDEEPMODEL_H */