Gleam User Guide:  Sources

How to use the current source infrastructure

Where the Sources Are:

In the FluxSvc package, under the /xml/ directory, there are a number of 
files, including user_library.xml, source_library.xml, and 
composite_library.xml.  Within these files, all the sources that FluxSvc 
(and therefore Gleam) can know about are defined.

The Default (already defined) sources:

Follows is a partial list of the already-defined sources in XML.  For a 
complete list, please see the current files themselves - each source is 
documented and explained within its own comment block.
default:  0.1 GeV gamma-rays coming from the vertical local direction.  Used 
for default tests.
all_gamma:  E^-1 spectrum from 18 MeV to 18 GeV and 0-90 degrees to weight all gammas
albedo_gamma:  Source that represents the Earth horizon albedo with Glast 
zenith pointing
chime:  The CHIME spectrum. angular dependence and rate are from the CHIME 
spectrum object
He:  The Helium spectrum. angular dependence and rate come from the 
HeSpectrum object.
albedo_electronpositron:  Source that represents the spalsh and re-entrant 
albedo electrons and positrons
diffuse:  diffuse extraglactic from 10 MeV: from APJ 494:523
diffuse-100mev:  Diffuse extraglactic from 100 MeV
crab-galactic:  the Crab, pulsed portion, with pointed observation, for 
photons above 100 MeV, based on Nolan APJ 409:697
electron:  galactic electron spectrum
normal_gamma:  E^-1 spectrum from 18 MeV to 18 GeV and normal incidence
muons:  special source that mimics non-interacting cosmics.
backgndmix:  standard background mixture.

How Gleam Knows where to look for Sources:

In the jobOptions file of Gleam (or one of the included jobOptions files), a 
line is declared as follows:

FluxSvc.source_lib += {"$(G4GENERATORROOT)/src/test/test_sources.xml"};

This line adds the named xml file to the list of files that Gleam can get 
sources from.  Note that the included file:
$(FLUXSVCROOT)/src/defaultOptions.txt
Also declares the file source_library.xml, so Gleam knows about it as well.

How Gleam knows which source to use:

In the JobOptions file of Gleam, the source that Gleam will use for the 
simulation is declared in the following line:

FluxAlg.source_name="muon_pencil_angle";

If it is desired, the source name can be changed to any source name that 
Gleam knows about (that is, any source name contained in an xml file that 
Gleam knows about).

Adding particle sources

Using Available Sources/Adding new sources in Gleam:

Within Gleam, sources are declared within XML files, in the FluxSvc package and elsewhere. It is quite possible to declare an xml file outside of the FluxSvc package, and send it to FluxSvc to be used, provided it conforms to the DTD file governing the form of the XML files stored in FluxSvc (the DTD is located at /xml/source.dtd in the FluxSvc package).  The external XML file must have the form:

<source_library title="descriptive name for GUI menu">

[SOURCE DECLARATION 1]

[SOURCE DECLARATION 2]

..........

</source_library>

The form of the source declarations will be discussed below.  Also, for the XML file to be inserted into the Gleam infrastructure for use, the line:

FluxSvc.source_lib += {"<pathname>/<filename.xml>"};

must be within the JobOptions file used. See the FluxSvc local jobOptions file for examples.

Adding a new source:

The XML interface, among other things, provides a way to encapsulate classes in the code as simple names, to simplify the process of calling them later.  Take the example of the XML element:

<source name="gamma_patch">
    <spectrum escale="GeV"> 
        <particle name="gamma"><energy e="0.1"/> </particle>
        <direction theta="0" phi="0" />
        <patch />
    </spectrum>
</source>

There are a lot of options available with which to construct a source like this in the XML.  Follows is a brief overview of the way sources can be  declared, and what the declarations mean:

Anatomy of an XML source

<source name="NAME" flux="###">

on this first line, we declare the name that the flux wil be called by, and (optionally) a total flux for that source.  Flux is defined to be in units of particles/sec/m^2/steradian for diffuse sources, and particles/sec/m^2 for point sources (effectively integrating over angular size of the source.)  The value of the flux defaults to 1 if it is not declared.

<spectrum escale=["MeV"|"GeV"]>

this line declares the spectrum element, and an energy scale for a declared energy (which comes later).  This has no default, and must be declared.

After this, three distinct attributes of the source get declared, how the type of particle and energy is declared, how the particle direction is declared, and how the point of origin for the particle is declared:

Type of Particle:

either a line like:

<SpectrumClass name="CHIMESpectrum">,

declaring the class (within the c++ code) to be used, or a line like:

<particle name="p">

declaring that particle attributes will be explicitly stated in XML, is used.

the SpectrumClass can take a string of information which will be fed into the class constructor of the class named, and the "particle" declaration will have either an energy or a power-law declared with their constituent parameters (as above).  If "particle" is declared, then an energy or energy scale must be specified within the particle, like so:

          <particle name="mu+"> <energy e="10"/> </particle>

  one of the following must then be declared in this way:

Note also that if "particle" is declared, a particle name must be given ("mu+" and "p" in he above examples), representing the type of incoming particles.  A partial list of available particles/names is as follows:

Direction:

lines like:

    <solid_angle mincos="-0.405" maxcos="-0.395" theta="0" /> 

are declared, with one of the following types: