ProditionsCode: Difference between revisions

From Mu2eWiki
Jump to navigation Jump to search
No edit summary
No edit summary
Line 1: Line 1:


==Introduction==
==Introduction==
ProditionsService provides conditions data "entities".  It is a layer of code over the DbService and is the principle user interface for accessing conditions data. It allows the creating and caching quantities derived from DbService database tables and other Proditions entities, creating an unlimited stack of database-derived quantities.  It will sense if a derived quantity is out of date, because the run/subrun changed and the underlying input data changed, and update itself as the user accesses the entity.
ProditionsService is the principle user interface for accessing conditions data.  ProditionsService provides conditions data "entities", logical groups of conditions data. Each entity should be able to be filled from fcl or from the database.  The fcl version is useful for creating a nominal content, for simulation or for testing.  It is also useful if the database contents are not available for any reason.  Some entities will contain data that is constant and could be loaded from fcl (such as configuration for the code), and also run-dependent data from the conditions database.  A logical approach is to always create the fcl version, then overwrite values or add values from the database, if requested.  Every entity has a switch to turn off database access.
 
Proditions is mostly a layer of code over the DbService. It allows the creating and caching quantities derived from DbService database tables and other, lower-level Proditions entities, creating an unlimited stack of database-derived cached quantities.  It will sense if a derived quantity is out of date, because the run/subrun changed and the underlying input data changed, and update itself as the user accesses the entity.
 
This page explains how to add a Proditions entity.


This page will explain how to add a Proditions entity.
==Adding an Entity==
==Adding an Entity==
The easiest approach is to copy an existing entity, for example StrawPhysics.  There will be several new files in two directories.  This example is in TrackerConditions and TrackerConfig, but obviously calorimeter entities should be in their respective directories, etc.  '''It is crucial to maintain directory and code name patterns''', or it will be very much harder to maintain.  For each Proditions entity, there is one identifying name string, in this case "StrawDrift" which will be used everywhere.
* '''TrackerConditions/inc/StrawDrift.hh'''  The definition of the container that holds the useful data. It must
** inherit from ProditionsEntity
** initialize, hold and access its name, the name function must override the base class definition
** optionally override a base class print function
namespace mu2e {
  class StrawDrift : public ProditionsEntity {
  public:
    accessors ...
    void print(std::ostream& os) const;
    std::string const& name() const { return _name; }
  private:
    std::string _name;
    data ...
}
* '''TrackerConditions/src/StrawDrift.cc''' implementation of methods of the class.  This should only manipulate the data of the class, '''it must not access any run-dependent information other than than the class data'''. The run dependence is always explicit in the Proditions service, which creates new entities as needed.  Ideally,  this class is a simple container of data and does not even link in utility classes, unless necessary.
* '''TrackerConfig/inc/StrawDriftConfig.hh'''  This is definition of a fcl configuration that contains all the data required to initialize a nominal fcl-driven version of the entity.
** It must have the verbose and useDb flags.
namespace mu2e {
  struct StrawDriftConfig {
    using Name=fhicl::Name;
    using Comment=fhicl::Comment;
    fhicl::Atom<int> verbose{
      Name("verbose"), Comment("verbosity: 0 or 1")};
    fhicl::Atom<bool> useDb{
      Name("useDb"), Comment("use database or fcl")};
    data initialization values ....
  }
}
* '''TrackerConditions/inc/StrawDriftMaker.hh''' definition of a utility class that takes the fcl config, database tables or other proditions entities as input and fills this entity.
** it must have one constructor which takes the config as an arugment
** it must have a fromFcl() method
** it must have a fromDb() methos which take as arguments database tables and other Proditions entities
** it must cache the fcl config
namespace mu2e {
  class StrawDriftMaker {
  public:
    StrawDriftMaker(StrawDriftConfig const& config):_config(config) {}
    StrawDrift::ptr_t fromFcl();
    StrawDrift::ptr_t fromDb( /* db tables will go here*/ );
 
  private:
    // this object needs to be thread safe,
    // _config should only be initialized once
    const StrawDriftConfig _config;
  };
}
* '''TrackerConditions/src/StrawDriftMaker.cc''' implementation of how to fill the entity from the inputs.  The contents here can be complex and call other utility routines.  Any run dependency must come explicity from the arguments - db tables or other Proditions entities.
* '''TrackerConditions/inc/StrawDriftCache.hh'''
* '''TrackerConditions/src/StrawDriftCache.cc'''


==Entities depending on other entities==
==Entities depending on other entities==

Revision as of 23:32, 12 February 2020

Introduction

ProditionsService is the principle user interface for accessing conditions data. ProditionsService provides conditions data "entities", logical groups of conditions data. Each entity should be able to be filled from fcl or from the database. The fcl version is useful for creating a nominal content, for simulation or for testing. It is also useful if the database contents are not available for any reason. Some entities will contain data that is constant and could be loaded from fcl (such as configuration for the code), and also run-dependent data from the conditions database. A logical approach is to always create the fcl version, then overwrite values or add values from the database, if requested. Every entity has a switch to turn off database access.

Proditions is mostly a layer of code over the DbService. It allows the creating and caching quantities derived from DbService database tables and other, lower-level Proditions entities, creating an unlimited stack of database-derived cached quantities. It will sense if a derived quantity is out of date, because the run/subrun changed and the underlying input data changed, and update itself as the user accesses the entity.

This page explains how to add a Proditions entity.

Adding an Entity

The easiest approach is to copy an existing entity, for example StrawPhysics. There will be several new files in two directories. This example is in TrackerConditions and TrackerConfig, but obviously calorimeter entities should be in their respective directories, etc. It is crucial to maintain directory and code name patterns, or it will be very much harder to maintain. For each Proditions entity, there is one identifying name string, in this case "StrawDrift" which will be used everywhere.

  • TrackerConditions/inc/StrawDrift.hh The definition of the container that holds the useful data. It must
    • inherit from ProditionsEntity
    • initialize, hold and access its name, the name function must override the base class definition
    • optionally override a base class print function
namespace mu2e {
  class StrawDrift : public ProditionsEntity {
  public:
    accessors ...
    void print(std::ostream& os) const;
    std::string const& name() const { return _name; }
  private:
    std::string _name;
    data ...
}
  • TrackerConditions/src/StrawDrift.cc implementation of methods of the class. This should only manipulate the data of the class, it must not access any run-dependent information other than than the class data. The run dependence is always explicit in the Proditions service, which creates new entities as needed. Ideally, this class is a simple container of data and does not even link in utility classes, unless necessary.
  • TrackerConfig/inc/StrawDriftConfig.hh This is definition of a fcl configuration that contains all the data required to initialize a nominal fcl-driven version of the entity.
    • It must have the verbose and useDb flags.
namespace mu2e {
  struct StrawDriftConfig {
    using Name=fhicl::Name;
    using Comment=fhicl::Comment;
    fhicl::Atom<int> verbose{
      Name("verbose"), Comment("verbosity: 0 or 1")}; 
    fhicl::Atom<bool> useDb{
     Name("useDb"), Comment("use database or fcl")}; 
   data initialization values ....
  }
}
  • TrackerConditions/inc/StrawDriftMaker.hh definition of a utility class that takes the fcl config, database tables or other proditions entities as input and fills this entity.
    • it must have one constructor which takes the config as an arugment
    • it must have a fromFcl() method
    • it must have a fromDb() methos which take as arguments database tables and other Proditions entities
    • it must cache the fcl config
namespace mu2e {
  class StrawDriftMaker {
  public:
    StrawDriftMaker(StrawDriftConfig const& config):_config(config) {}
    StrawDrift::ptr_t fromFcl();
    StrawDrift::ptr_t fromDb( /* db tables will go here*/ );
 
  private:
    // this object needs to be thread safe, 
    // _config should only be initialized once
    const StrawDriftConfig _config;
  };
}
  • TrackerConditions/src/StrawDriftMaker.cc implementation of how to fill the entity from the inputs. The contents here can be complex and call other utility routines. Any run dependency must come explicity from the arguments - db tables or other Proditions entities.
  • TrackerConditions/inc/StrawDriftCache.hh
  • TrackerConditions/src/StrawDriftCache.cc


Entities depending on other entities