ROAst
 All Classes Functions Variables Enumerations
ROAst Documentation

ROOT capabilities adding packages and tools for astrophysical research. The main contributions will be:

1)Create an interfaces to import and manipulate astronomical catalogues.

2)Create a set of interfaces as bridge to other software such as data-sets and numerical simulations software for relevant astrophysical phenomenology.

Most of the definition are contained in the roast.h file and it is defined a global namespace ROAst Next are described the relevant classes and structures from the user point of view and the develop one:

User:

The previous structure defines the celestial equatorial coordinates parametrized by the declination (double Decl) and the right ascension (double RA). The declination measures the angular distance of an object perpendicular to the celestial equator, negative to the south and positive to the north. The celestial equator represent the origin of declination and is the projection of the terrestrial equator onto the celestial sphere. The right ascension (abbreviated RA) measures the angular distance of an point along the celestial equator from the vernal equinox, passing through the point, to the hour circle. The vernal equinox is defined as one of the two point where the ecliptic intersects the celestial equator. It is analogous to terrestrial longitude and can be measured in sidereal hours, minutes and seconds or degrees. Right ascension and declination are usually abbreviated RA/Decl. They can be accessed and modified as a usual members of a structure and are used as coordinate system of the astronomical part of the library.

Develop:

The EqAstCoord structure is used as datatype in several following classes, it used to identify a position in the AstroObject structure. All different coordinate system can be converted to the equatorial coordinates in order to be used in most of the subsequent methods and in the AstroObject structure itself.

User:

The GalactiCoord structure represent the galactic coordinates which is a celestial coordinate system parametrized by the longitude (double AstLat) measures the angular distance of an object eastward along the galactic equator from the galactic center. Galactic longitude is usually measured in degrees and is the analogous of the terrestrial longitude. Latitude (double AstLong) measures the angular distance of an object perpendicular to the galactic equator. Galactic latitude is analogous to terrestrial latitude and is measured in degrees. The galactic coordinate system is a spherical coordinates system, with the Sun as its center, the primary direction is aligned with the approximate center of the Milky Way, and the fundamental plane approximately in the galactic plane. They can be accessed and modified as a usual members of a structure, however galactic coordinates si not the coordinate system of the library astronomical methods. ROAst provideds a mechanism to convert the GalactiCoord structure to the EqAstCoord structure.

Develop:

The GalactiCoord structure is used as datatype, in the library are present class methods to convert galactic coordinates between celestial system and geographical coordinate system . All different coordinate system will converted to equatorial coordinate in order to be used in most of the subsequent methods and in the AstroObject structure itself.

User:

This structure represents the geographic coordinate system which is a coordinate system that identify every location on the Earth using the coordinates latitude (double GeoLat) and longitude (double GeoLong). In addiction the structure contains a time coordinate which specify the date and the exact time, this additional parameter is needed for the coordinate conversion from the geographic coordinate system to a celestial coordinate system. This coordinates can be accessed and modified as a usual members of a structure and are provided operator to convert the GeoCoord structure to the EqAstCoord structure and vice versa.

Develop:

The GeoCoord structure is used as datatype. Most of the simulation program use geographic coordinate system therefore it indispensable to define this datatype in order to call an eexternal simulation program in the particle simulation part of the library, Beside, in order to connect the astronomical part of the library and the particle generation one are provide two classes which contains method to convert to one coordinate system to another. The Geotime variable is of the type "tm" which is a datatype defined in the library "ctime".

User:

The previous classes provides a mechanism for the conversion among the various coordinate system previously defined. Using the methods defined it is possible to convert a point parametrized in one coordinate system to another just applying this operator to the variable. The possible conversion are:EqAstCoord<->GeoCoord, GalactiCoord<->EqAstCoord, GalactiCoord->GeoCoord and the conversion GeoCoord<->GalactiCoord.

Develop:

The conversion methods are defined as public functions of the class which acts between objects derived by the previous coordinate structure. The conversion will be executed using the well known conversion formulae between the coordinate system.

User:

The SpectralMagnitude structure contains the magnitude (double Magnitude) of the astronomical object under consideration, the magnitude is referred to a fixed wave length (double Lambda). This structure will be present in the AstroObject structure as a vector since, depending on the catalogue, can be reported various magnitude for the same object.

Develop:

The SpectralMagnitude structure is used as datatype for a vector in the struct AstroObject, it contains two double variables which are physically bounded so gather them in a single structure is a useful solution

User:

This structure contains the parameters to identify one or more astronomical objects. The physical parameters are: position, magnitudes at fixed lambda (depending on the catalogue used) expressed in manometer, colour and red-shift. Beside, there is the enumerated variable ObjectType which contains the type of object i.e.: STAR = 0 GALAXY = 1, ecc... This structure is designed to identify one single astronomical object or all the object in the range specified by the min and max of each variable (in this case the position variable is not used), of course one object is identified when min and max are all equal and position is defined.

Develop:

This structure contains the previously defined structure EqAstCoord for the position of the object and two standard vector of the structure SpectralMagnitude. This structure AstroObject will be used to create a container for all the astronomical object contained in an imported catalogue on a particular region. Beside will be used to identify multiple astronomical objects in the GetInObjects and ExecuteEvent methods.

User:

Using this class the user is able to load a catalogue in two way: from a stored file just specifying the full path or from a pre-loaded image in ROOT. Once After chosen one of this two methods the vectorial variable Container will be populated with the contents of the catalogue and, as a public member of the class, this container can be acceded from any external procedure.

Develop:

This class is responsible to import the catalogue using the methods:

   Catalogue(std::string const &filename);

   Catalogue(fitsfile fptr);

The first method imports the catalogue from file while the second use a datatype included from the ROOT libraries in order to import a preloaded image in ROOT. Container variable is a standard vector of AstroObject and it is used to contain all the astronomical object of the imported catalogue. The Container variable is in the public part of the class in order to accessed globally.

{

   protected:

   EqAstCoord Centre;                     /** Centre of the region **/

   public:

   Region(EqAstCoord centre);             /** Set the Centre of the region  **/

   virtual ~Region() ;                    /** Destructor **/

   EqAstCoord GetRegCentre() const;       /** Returns Centre - position of centre **/

   void SetRegCentre(EqAstCoord centre);  /** Returns Centre - position of centre **/

   virtual void WriteRegion(std::string const &file) = 0;                                 /** Writes to a file the selected region **/

   virtual std::vector<AstroObject>  GetInObjects( AstroObject const &filter) const = 0 ; /** Extracts the all the astronomical objects specified by filter present in the selected region **/

   virtual bool ExecuteEvent(AstroObject const &ConditionObject) const = 0  ;            /** Returns true if  the ConditionObject is found in the region **/

   virtual void PopulateRegion() = 0 ;                                                    /**  Project the objects on the region populating its container. **/

   virtual void Clear() = 0;                                                              /** Clears the region, which can then be reused. **/

   virtual std::string GetRegionShape() const = 0;                                        /** Returns the type of region **/

};

User:

Once the catalogue is imported, the user should to be able to manipulate the astronomical objects performing actions such as: selecting a specific region, filter from that region only a particular class of of object or trigger some event when a particular object is found in the selected region. The following classes provide to the user the proper methods in order to perform this tasks. The Region class permit to specify the centre of the region of interest using celestial equatorial coordinates, the shape and the area of this region will be fixed using its sub-classes. Once the region is fully defined the class provide a method to project the full catalogue to the selected region. Finally, methods GetInObjects and ExecuteEvent perform the mentioned tasks using an AstroObject object to select one or more astronomical objects to looking for.

Develop:

The Region class is the mother class for all the subsequent geometrical regions. In this class, through the constructor:

   Region(EqAstCoord centre);

can be fixed the centre of the region of interest, the dimensions and the shape of the region will be set using one of the daughter classes. In this region are present methods to get the centre of the region or modify it. Beside here are defined all the common method among the daughter classes which will be defined locally too. The virtual method PopulateRegion is one of the most relevant since it is responsible to populate the region projecting the variable Container present in the Catalogue class to the local container variable of each region. The region container can the be cleared using the Clear method for a reuse. The two virtual method GetInObjects and ExecuteEvent checks if the objects placed in their arguments are present in the local container, if the condition is satisfied the first method returns all the objects that meet the request, meanwhile the second method just returns true. The GetRegionShape returns the type ( the shape ) of the region selected as a string stored in the RegionShape local variable. At last, the WriteRegion method saves the content of the region container into a file.

{

   protected:

   EqAstCoord RMaxExtent;     /** One end point of the max radius of the ellipse **/

   double RMinExtent;         /** Min radius  of the ellipse **/

   std::string  RegionShape;  /** The shape of the region **/

   public:

   std::vector<AstroObject> EllipseContainer; /** A container with the astronomical object of the ellipse **/

   Ellipse(EqAstCoord rmaxextent, double rminextent); /** Creates an elliptic region **/

   virtual ~Ellipse() ;                               /** Destructor **/

   virtual void WriteRegion(std::string &file) const; /** Local method to write in a file the selected region **/

   EqAstCoord GetRegRMaxExtent() const;               /** Retruns RMaxExtent **/

   double GetRegRMinExtent() const;                   /** Retruns RMinExtent **/  

   virtual std::string  GetRegionShape() const;       /** Local method to return the region shape **/

   void SetRMaxExtent(EqAstCoord rmaxextent);         /** Changes RMaxExtent **/

   void SetRMaxExtent(double RMinExtent);             /** Changes RMinExtent **/

   virtual std::vector<AstroObject>  GetInObjects(AstroObject const &filter) const; /** Local method to extract the all the astronomical objects specified by filter present in the selected region **/

   virtual bool  ExecuteEvent(AstroObject  &ConditionObject) const;                 /** Local method to return true if  the ConditionObject is found in the region **/

   virtual void PopulateRegion();                                                   /** local mathod to project the objects on the region populating its container. **/

   virtual void Clear();                                                            /** Local method to clear the region, which can then be reused. **/

};

User:

Using the constructor of this Ellipse class the user can configure a region of elliptic shape. The ellipse is parametrized by the length of its minor radius (double RMinExtent) and the position, in celestial equatorial coordinate, of one end point of the larger radius (EqAstCoord RMaxExtent). Using the constructor Ellipse(EqAstCoord rmaxextent, double rminextent) the region is created with the provided parameters for the position and the length of the radius, the centre (the intersection of the radius) is specified by the Centre variable defined in the mother class Region. For the subclass ellipse are defined locally all the mentioned above methods to project the catalogue on the local region container, to filter the astronomical object in the region, check if it is present some particular object, and save on file the local container. Beside, are defined methods to retrieve the shape of the region, discover parameters for the position and the length of the radius and eventually change them.

Develop:

This Ellipse class is a subclass of the mother class region in which are defined as protected a set of variable used to set the size of the ellipse without ambiguity. Beside, are present in the public part all the local methods defined in the mother class. All this methods will implement the required task adapting the procedure to the specific region shape.

    protected:

    double RegR; /** Radius of the cicle region **/ 

    std::string  RegionShape;  /** The shape of the region **/

    public:

    std::vector<AstroObject> CircleContainer; /** A container with the astronomical object of the circle **/

    Circle(double R); /** Creates an circle region  of radius R  **/

    virtual ~Circle() ;                       /** Destructor **/

    virtual void WriteRegion(std::string const &file) const; /** Local method to write in a file the selected region **/

    double GetRegR() const;                  /** Retruns RegR **/       

    virtual std::string  GetRegionShape() const;      /** Local method to return the region shape **/

    void SetRegR(double R);                /** Changes RegR **/

    virtual std::vector<AstroObject> GetInObjects(AstroObject const &filter) const; /** Local member to extract the all the astronomical objects specified by filter present in the selected region **/

    virtual bool ExecuteEvent(AstroObject const &ConditionObject) const; /** Local method to return true if  the ConditionObject is found in the region **/

    virtual void PopulateRegion() ; /** local mathod  to project the objects on the region populating its container. **/

    virtual void Clear() ; /** Local method to clear the region, which can then be reused. **/

};

User:

As for the Ellipse class, with the constructor of this Circle class the user configure a region of circular shape. The circle is parametrized by the length of its radius (double RegR). Using the constructor Circle(double R) the region is created with the provided radius, the centre is specified by the Centre variable defined in the mother class Region. For the sub-class circle are defined locally all the mentioned above methods to project the catalogue on the local region container, filter the astronomical object in the region, check if is present some particular object, and save on file the local container. Beside are defined methods to retrieve the shape of the region, discover length of the radius and eventually change it.

Develop:

This Circle class is a subclass of the mother class region in which are defined as protected a of variable, the radius, used to set the size of the circle without ambiguity. Beside, are present in the public part all the local methods defined in the mother class. All this methods will implement the required task adapting the procedure to the specific region shape.

{

    protected:

    EqAstCoord RegVertex;     /** One vertex of the box region **/

    double RegHeight;         /** Height of the box region **/

    double RegWidth;          /** Width of the box region **/

    std::string  RegionShape; /** The shape of the region **/

    public:

    std::vector<AstroObject> BoxContainer; /** A container with the astronomical object of the box **/

    Box(EqAstCoord regvertex, double regheight,double regwidth); /** Creates an box region of Height "regheight" and width "regwidth" and vertex "regvertex"**/  

    virtual ~Box() ;                       /** Destructor **/

    virtual void WriteRegion(std::string const &file) const; /** Local method to write in a file the selected region **/

    EqAstCoord GetVertex() const;          /** Retruns RegVertex **/

    double GetRegHeight() const;           /** Retruns RegHeight **/

    double GetRegWidth() const;            /** Retruns RegWidth **/

    virtual std::string  GetRegionShape() const;      /** Local method to return the region shape **/

    void SetRegVertex(EqAstCoord regvertex);      /** Changes RegVertex **/

    void SetRegHeight(double regheight);          /** Changes RegHeight **/

    void SetRegWidth(double regwidth);            /** Changes RegWidth **/

     virtual std::vector<AstroObject> GetInObjects(AstroObject const &filter) const; /** Local member to extract the all the astronomical objects specified by filter present in the selected region **/

    virtual bool ExecuteEvent(AstroObject const &ConditionObject) const; /** Local method to return true if  the ConditionObject is found in the region **/

    virtual void PopulateRegion() ; /** local mathod  to project the objects on the region populating its container. **/

    virtual void Clear() ; /** Local method to clear the region, which can then be reused. **/

};

User:

As for the Ellipse class, with the constructor of this Box class the user configure a region of box shape. The box is parametrized by the length of its sides (double RegHeight, double RegWidth) and the position of one vertex in celestial equatorial coordinate (EqAstCoord RegVertex). Using the constructor Box(EqAstCoord regvertex, double regheight,double regwidth) the region is created with the provided parameters for the position and the length of the sides, the centre is specified by the Centre defined in the mother class variableRegion. For the sub-class box are defined locally all the mentioned above methods to project the catalogue on the local region container, filter the astronomical object in the region, check if are present one or more particular objects, and save on file the local container. Beside are defined methods to retrieve the shape of the region, discover length an position of the sides and eventually change them.

Develop:

This Box class is a subclass of the mother class region in which are defined as protected a of variable, the length of its sides and the position of one vertex, used to set the size of the box without ambiguity. Beside, are present in the public part all the local methods defined in the mother class. All this methods will implement the required task adapting the procedure to the specific region shape.

{

    protected:

    EqAstCoord   RegSecondPoint;     /** Position of the second end point of line **/

    std::string  RegionShape;  /** The shape of the region **/

    public:

    std::vector<AstroObject>  LineContainer; /** A container with the astronomical object of the line **/

    Line(EqAstCoord RegSecondPoint); /** Creates an line region of extreme regsecondpoint and the center on the region**/

    virtual ~Line() ;                /** Destructor **/

    EqAstCoord GetRegSecondPoint() const;    /** Returns RegSecondPoint **/

    virtual std::string  GetRegionShape() const;      /** Local method to return the region 

    virtual void WriteRegion(std::string const &file) const; /** Writes to a file the selected region **/

    void SetRegSecondPoint(EqAstCoord regsecondpoint);  /** Changes RegSecondPoint **/

    virtual std::vector<AstroObject> GetInObjects(AstroObject const &filter) const; /** Local member to extract the all the astronomical objects specified by filter present in the selected region **/

    virtual bool ExecuteEvent(AstroObject const &ConditionObject) const; /** Local method to return true if  the ConditionObject is found in the region **/

    virtual void PopulateRegion() ; /** local mathod  to project the objects on the region populating its container. **/

    virtual void Clear() ; /** Local method to clear the region, which can then be reused. **/

};

User:

As for the Ellipse class, with the constructor of this Line class the user can configure a region of linear shape. The Line is parametrized by the position of the second end point (EqAstCoord RegSecondPoint ) in celestial equatorial coordinate. Using the constructor Line(EqAstCoord RegSecondPoint) the region is created with the provided parameters for the position, the centre is specified by the Centre variable defined in the mother class Region. For the sub-class box are defined locally all the mentioned above methods to project the catalogue on the local region container, filter the astronomical object in the region, check if are present one or more particular objects, and save on file the local container. Beside, are defined methods to retrieve the shape of the region, discover the position of the second end point and eventually change it.

Develop:

This Line class is a subclass of the mother class region in which is defined as protected the position of the second end point used to set the size of the box without ambiguity. Beside, are present in the public part all the local methods defined in the mother class. All this methods will implement the required task adapting the procedure to the specific region shape.

{

    protected:

    std::string PointName;    /** Name of the point region **/

    std::string RegionShape;  /** The shape of the region **/

    public:

    AstroObject PointContainer;   /** A container with the astronomical objects of the box **/

    Point();/** Creates an point region consisting in the center on of the  region **/

    virtual ~Point() ;            /** Destructor **/

    void WriteRegion(std::string const &file) const;  /** Writes to a file the selected region **/

    virtual std::string  GetRegionShape() const;      /** Local method to return the region shape **/

    virtual std::vector<AstroObject> GetInObjects(AstroObject const &filter) const; /** Local member to extract the all the astronomical objects specified by filter present in the selected region **/

    virtual bool ExecuteEvent(AstroObject const &ConditionObject) const; /** Local method to return true if  the ConditionObject is found in the region **/

    virtual void PopulateRegion() ; /** local mathod  to project the objects on the region populating its container. **/

    virtual void Clear() ; /** Local method to clear the region, which can then be reused. **/

};

User:

The last and smallest region subclass is the Point class, with the constructor Point() the user can configure a region concerning of just one point: the centre. The centre is specified by the Centre variable defined in the mother class Region. For the sub-class point are defined locally some of the methods mentioned above: to project the catalogue on the local region container, to check if are present a particular objects and save on file the local container. Beside, is defined a method to retrieve the shape of the region.

Develop:

This Point class is a subclass of the mother class region, there is no position parameter since is already fully localized by the Centre variable defined in the mother class. In the public part all the relevant local methods defined in the mother class (some methods are non implemented since non applicable to an one point region) . This methods will implement the required task adapting the procedure to the specific region shape.

{

    unsigned long long PDGId; /** Particle Data Group Id  **/

    double Energy; /** Enegrgy of the particle [GeV] **/

    GeoCoord From; /** Source of the particle  **/

};

User:

This structure contains the parameters to characterize a cosmic particle: the ID, the energy and the position of source of the particle. The integer variable PDGId is the identification number in the well known Particle Data Group classification which identify all the discovered particles. The energy of particle is defined in Gev and the position source particles are parametrized the using geographic coordinate system since the majority of particle simulation program use this coordinate system.

Develop:

This structure is used as datatype for the single particle output of a general particle simulated generation. The final output of the external simulation program will by cast in form of a tree dataype (TTree) imported from the ROOT datatypes, the branches of this tree will be based on the CosmicParticle structure.

{

    protected:

    unsigned long long RunNumber;  /** A int number to identify the simulation RUN **/

    std::string SaveFileName; /** The file where to save the outcome **/ 

    public:

    CosmicParticleGenerator(std::string const &filename, unsigned long long rn); /** Set the RunNumber and  the output file **/  

    virtual ~CosmicParticleGenerator();                            /** Destructor **/

    virtual std::string GetSaveFileName() const = 0;               /**  Returns the SaveFileName **/

    virtual void SetSaveFileName(std::string const &file) = 0;     /** Set the SaveFileName **/

    virtual TTree *Run(unsigned long long run, std::string SaveFileName) = 0;  /** Starts a particle simulation and copy the output in a root-file **/

    virtual TTree *FromFile(std::string cont &file) = 0; /** Import a particle simulation from  file previusly generated **/

};

User:

The class CosmicParticleGenerator and following classes concern the particle generation parts, which give the ability to ROOT (and therefore to the user) to use external cosmic particle simulation software. The CosmicParticleGenerator class contains methods to set the RunNumber, a integer positive number used to identify the simulation run, and the SaveFileName variable which identify the full path for the output file of the simulations. The class provide two different method to import a simulation: from a previously generate file or directly calling an external program with the proper inputs. This two methods are and FromFile(std::string cont &file) and Run(unsigned long long run, unsigned long long particles) respectively . The imported simulations output is stored in form of a tree dataype (TTree) imported from the ROOT datatypes, the branches of this tree will be based on the CosmicParticle structure.

Develop:

The CosmicParticleGenerator class is the mother class for all the subsequent XXXParticleGenerator classes. In this class, through the constructor:

    CosmicParticleGenerator(std::string const &filename, unsigned long long rn)

can be fixed the RunNumber and the output file of the simulation, the type of particle generated will be chosen using one of the daughter classes. In this class are defined all the common method among the daughter classes which will be defined locally too. The virtual method Run(unsigned long long run, unsigned long long particles) is one of the most relevant since is responsible to start a particular simulation calling an external simulation program returning the output in a form of tree datatype and saving it in file. The other very import method is the virtual method FromFile(std::string cont &file) which, as the previous method, returns the output of a simulation in a form of tree datatype but imports this simulation result from a previously generate file, the procedure to convert the particular output file to the TTree datatype are defined locally on the last daughter class.

{

    protected:

    std::string DetectorFileName; /** The geometry detector file **/ 

    public:

    NeutrinoGenerator(std::string const &filename); /** Set the geometry detector file **/ 

    virtual ~NeutrinoGenerator();                        /** Destructor **/

};

User:

In order to catheterize different type of simulations we have chose to create different sub-class for each simulation family. Starting from the charged and non charged splitting, which corresponds to NeutralParticleGenerator and ChargedParticleGenerato, hence we have defined PhotonGenerator, NeutrinoGenerator and NeutronGenerator as sub-class of NeutralParticleGenerator, ElectronGenerator and ChargedBarionGenerator as subclass of NeutralParticleGenerator.As a first use case we have considered neutrino flux generation adding the The constructor method ofNeutrinoGenerator sets the location of the geometry detector file which is shared among various cosmic neutrino simulation.

};

User:

As a first application we have used the GENHEN cosmic neutrino simulation program. In order to produce a neutrino flux GENHEN require a set of physical parameter usually called datacard, In this GENHENGenerator class are provided methods to import the datacard from a file or retrieve the current datacard. The datacard are organized in a structure called GENHENDatacard in which all the required physical parameter are named in a human readable way and commented in order to explain the physical content. As already explained the class contains two locals method to run a new flux neutrino simulation or load a previous executed simulation importing a file.

Develop:

This GENHENGenerator class is a subclass of NeutrinoGenerator class, The definition of the GENHENGenerator ant its related structure are written in a separate header file called GENHEH.h in order to improve the modularity respect the external program used. Beside, the GENHENDatacard structure, which contains the all the required physical parameters, it is defined the GENHENSysConfig structure used to configure all the GEHHEN paths. In the public part of the class are present all the local methods defined in the mother class CosmicParticleGenerator. All this methods will implement the required task adapting the procedure to the specific simulation program.