earthmodel-service

now its for all uses....
see https://wiki.icecube.wisc.edu/index.php/Earthmodel-service for updates.

overview

EarthModelService provides density of the Earth at a given point in Earth-center coordinate.
Following users are strongly encouraged to use this module to make your simulation consistent.

Users who need information of density of the Earth (includes bedrook and ice, air)
Users who need to coordinate conversion between IceCube coordinate and Earth Center coordinate
Users who need to calculate muon range
Users who are using root just because they want to use TVector3

They are treated by following classes respectively.

EarthModelService
EarthModelService
EarthModelCalculator
RVector3

What you need to prepare to get your own Earth Model

Currently all density profile below Moho-boundary is hardcoded inside EarthModelService.
Upper structures such as bedrook, ice, air and the definition of the EarthRadius are provided with crust model files, which must follow following format. See details in resources/earthparams/PREM_mmc.dat .

Format should follow next three colums
upper_radius[m] density[g/cm^3] label[string]
Data must be in ascending order in upper_radius
no space before first column
delimiter must be whitespaces
data must include at least 5 lines with labels of "moho_boundary", "rockice_boundary","iceair_boundary", "earth_radius", and "atmo_radius"
density must be the density up to the defined radius, except for "moho_boundary"
density of "moho_boundary" should be same as the density of next layer
"earth_radius" is NOT the geophysical boundary. This is the definition that all simulation program regards "the radius of the Earth".
lines start from '#' or whitespace are treated as comments

Note about Earth Radius for NuGen users

If you want to use NuGen with a large injection volume that may cross over the boundary of the Earth surface (with default setting it's same as the radius of the ice surface), you have to increase earth_radius parameter so that contain all your injection volume within the radius.
In this case, the earth_radius parameter is quite similar concept of "World" volume of Geant4.
Do not forget to make all data in ascending order in upper_radius.

Classes descriptions

RVector3 (Root-style Vector3)

This is just copy of the TVector3, but is removed any root-dependency (does not delive TObject, inactivated some functions that use TVector2 etc.).
If your module depend on root just because you want to use TVector3, you may switch it to RVector3 and your module won't require root anymore.

It also offer constructors that takes I3Position or I3Direction as an argument. If you want an I3Position from a RVector3, you may use GetI3Pos() function. See examples.

// conversion from I3Position etc. to RVector3

I3Position pos;
I3Direction dir;

RVector3 p(pos);
RVector3 d(dir);

// conversion from R3Vector3 to I3Position etc.

I3Postion pos2 = p.GetI3Pos();
I3Direction dir2 = d.GetI3Dir();

I3EarthModelServiceFactory

Parameters :

ServiceName: Name of the service (default EarthModelService)
PathToDataFileDir: Full path to directry which contains crust datafile. If blank, $I3Build/earthmodel-service/resources/earthparams will be used.
EarthModel: Name of Earth model. PREM (default), PREM_FLATCORE, HOMOGENEOUS
CrustModel: Name of crust model. PREM_mmc (default), PREM_legacy, etc.
EarthDensity: Density of "HOMOGENEOUS" Earth.
CoreDensity: Density of core of "PREM_FLATCORE" Earth.
IceCapType: Type of Ice geometry. "SheetIce" (default, assumes the Earth is covered with the thick IceSheet), "NoIce"(All ice is taken away!), "SimpleIceCap" (Spherical ice cap exists around the Antarctica)
IceCapSimpleAngle: Solid angle of SimpleIceCap. default : 30 degree.
DetectorDepth: Depth of detector center [m], measured from the surface of the Ice.

EarthModelService

Coordinate conversion

EarthModelService offers coordinate conversion to get EarthCenter coordinate position from IceCube coordinate position, etc. Arguments and return value could be I3Position, I3Direction, and RVector3. See details in header comments.

GetEarthDensityInCGS, GetMedium

GetEarthDensityInCGS(point) function returns density at the given point.
REMEMBER, the return value is in CGS unit [g/cm3] !

GetMedium(point) function returns medium type which is defined in EarthModelService as enum:

INNERCORE
OUTERCORE
MANTLE
ROCK
ICE
AIR
VACUUM

EarthModelCalculator

GetMuonRange(energy, isTau, option)

This function returns muon range in m.w.e. at given energy.
if isTau is true, gives tau range instead.

The option parameter controls which equation you want to use.

0 < option < 10 : use legacy equation
10 < option < 20 : use Dima's new parameter updated in 2011
20 < option < 30 : use Gary's fitting parameter used in NUSIM

fmod(option, 10) gives a scaling parameter of return value.
If you specify option = 12.5, that uses Dima's new function and multiply by a fuctor of 2.5.

GetMuonRangeInMeter()

This function returns muon range in [m] with a given track geometory, energy and earth model.
You must choose arguments carefully to get expected behavior.

Arguments :

double energy: energy of particle
const RVector3 &endposCE, const RVector3 &dirCE: endposCE is a position that the track dies out. Suppose a track has an energy at startposCE (which we don't know unless this function is called) and lost most of it's kinetic energy at endposCE (energy at endposCE < energy threshold), the function gives the length[m] between endposCE and startposCE, with taking into account of given EarthModel and track direction (dirCE).
Both endposCE and dirCE must be in EarthCenter coordinate.
EarthModelServiceConstPtr earthservice_ptr,: pointer to the EarthModelService
bool isTau: is tau flavor or not.
default : false
bool stopAtEarthSurface: This is a flag if we limit (or trim) the return length with the EarthSurface.
For example, high-energy downgoing muon have extremely long range since their path includes Air region.
People who need how far the muon can be generated on top of the Earth need to switch off this option.
NeutrinoGenerator doesn't need this calculation, because anyway it starts simulation from the surface of the Earth. In the latter case we switch on the stopAtEarthSurface parameter and returned track length is trimmed by the surface of the Earth.
default : false
double stepsize: Since this function caluclate accumulation of column-depth, *you need to specify step size. This function use this step size unless ration of density between current step and the last step does not change grater than the amount of density_tolerance.
default : 10m
double finestepsize: this step size is used when density of a point is changed * a lot from the last step. * This is the finest step used in this calculation, in other * words, density profile is averaged out in this step size * even at the edge of earth's core, where the density changes * 50% from Mantle. * default : 1m
double density_tolerance: used to switch step size. if you set 0.05, the function switch step size to fine one when density varie over 5% from the last step.
default : 0.05
double option: Used by GetMuonRange() function.
Leave it as defaut unless you want to explicitely change the parameter.