Add source examples to egs++ library documentation

Add elementary source examples in the pirs-898 documentation
automatically generated for the egs++ library, add source images, and
update source descriptions.

HEN_HOUSE/egs++/sources/egs_angular_spread/egs_angular_spread_source.h

@@ -23,7 +23,7 @@
 #
 #  Author:          Iwan Kawrakow, 2009
 #
-#  Contributors:
+#  Contributors:    Reid Townson
 #
 ###############################################################################
 */
@@ -84,6 +84,37 @@ The \c sigma input can be positive or negative.
 If it is positive, it is considered to be the sigma of the Gaussian distribution
 in degrees, if negative, the FWHM of the distribution.
 
+A simple example:
+\verbatim
+:start source definition:
+    :start source:
+        library = egs_parallel_beam
+        name = my_parallel_source
+        :start shape:
+            library = egs_rectangle
+            rectangle = -.1 -.1 .1 .1
+        :stop shape:
+        direction = 0 -1 0
+        charge = 0
+        :start spectrum:
+            type = monoenergetic
+            energy = 1.0
+        :stop spectrum:
+    :stop source:
+    
+    :start source:
+        library = egs_angular_spread_source
+        name = my_source
+        sigma = 10
+        source name = my_parallel_source
+    :stop source:
+
+    simulation source = my_source
+
+:stop source definition:
+\endverbatim
+\image html egs_angular_spread_source_s0.png "A simple example with sigma=0"
+\image html egs_angular_spread_source_s10.png "A simple example with sigma=10"
 */
 class EGS_ANGULAR_SPREAD_SOURCE_EXPORT EGS_AngularSpreadSource :
     public EGS_BaseSource {

HEN_HOUSE/egs++/sources/egs_beam_source/egs_beam_source.h

@@ -25,6 +25,7 @@
 #
 #  Contributors:    Ernesto Mainegra-Hing
 #                   Frederic Tessier
+#                   Reid Townson
 #
 ###############################################################################
 */
@@ -110,6 +111,25 @@ reject "phat" particles from a simulation using DBS.
 sure that the <code>RESTART</code> calculation option is defined in
 both, the source and the application input files.
 
+A simple example. Note that you must build the required shared library for
+the accelerator (i.e. use the command 'make library' in the BEAM_EX10MeVe 
+directory).
+\verbatim
+:start source definition:
+    :start source:
+        library = egs_beam_source
+        name    = my_source
+        beam code = BEAM_EX10MeVe
+        pegs file = 521icru
+        input file = EX10MeVe
+        particle type = all
+    :stop source:
+
+    simulation source = my_source
+
+:stop source definition:
+\endverbatim
+\image html egs_beam_source.png "A simple example"
 */
 class EGS_BEAM_SOURCE_EXPORT EGS_BeamSource : public EGS_BaseSource {
 

HEN_HOUSE/egs++/sources/egs_collimated_source/egs_collimated_source.cpp

@@ -50,7 +50,7 @@ EGS_CollimatedSource::EGS_CollimatedSource(EGS_Input *input,
         int err = input->getInput("source shape name",sname);
         if (err)
             egsWarning("EGS_CollimatedSource: missing/wrong inline source "
-                       "shape definition and missing wrong 'source shape name' input\n");
+                       "shape definition and missing/wrong 'source shape name' input\n");
         else {
             source_shape = EGS_BaseShape::getShape(sname);
             if (!source_shape)
@@ -68,10 +68,10 @@ EGS_CollimatedSource::EGS_CollimatedSource(EGS_Input *input,
         int err = input->getInput("target shape name",sname);
         if (err)
             egsWarning("EGS_CollimatedSource: missing/wrong inline target"
-                       "shape definition and missing wrong 'target shape name' input\n");
+                       "shape definition and missing/wrong 'target shape name' input\n");
         else {
             target_shape = EGS_BaseShape::getShape(sname);
-            if (!source_shape)
+            if (!target_shape)
                 egsWarning("EGS_CollimatedSource: a shape named %s"
                            " does not exist\n",sname.c_str());
         }

HEN_HOUSE/egs++/sources/egs_collimated_source/egs_collimated_source.h

@@ -24,6 +24,7 @@
 #  Author:          Iwan Kawrakow, 2005
 #
 #  Contributors:    Ernesto Mainegra-Hing
+#                   Reid Townson
 #
 ###############################################################################
 */
@@ -97,6 +98,13 @@ as a target shape in a collimated source are
 \link EGS_PolygonShape polygons \endlink and
 \link EGS_TriangleShape triangles \endlink.
 
+The fluence calculated by getFluence() is determined as \f$N/d^2\f$,
+where \c N is the number of source particles and \c d is provided by
+the user as \c distance, the minimum distance between the source and target
+shapes. This accounts for the solid angle within which particles are generated.
+If \c distance is not provided, it defaults to 1, which will likely be
+an incorrect normalization.
+
 A collimated source is defined as follows:
 \verbatim
 :start source:
@@ -111,13 +119,41 @@ A collimated source is defined as follows:
     :start spectrum:
         definition of the spectrum
     :stop spectrum:
+    distance = source-target shape min. distance
     charge = -1 or 0 or 1 for electrons or photons or positrons
 :stop source:
 \endverbatim
 It is worth noting that the functionality of sources 1, 11, 12, 14, 15 and 16
 from the RZ series of user codes and source 3 in DOSXYZnrc can be
 reproduced with the collimated source from the EGSnrc C++ class library.
 
+A simple example:
+\verbatim
+:start source definition:
+    :start source:
+        library = egs_collimated_source
+        name = my_source
+        :start source shape:
+            type = point
+            position = 0 0 5
+        :stop source shape:
+        :start target shape:
+            library   = egs_rectangle
+            rectangle = -1 -1 1 1
+        :stop target shape:
+        distance = 5
+        charge = -1
+        :start spectrum:
+            type = monoenergetic
+            energy = 20
+        :stop spectrum:
+    :stop source:
+
+    simulation source = my_source
+
+:stop source definition:
+\endverbatim
+\image html egs_collimated_source.png "A simple example"
 */
 class EGS_COLLIMATED_SOURCE_EXPORT EGS_CollimatedSource :
     public EGS_BaseSimpleSource {

HEN_HOUSE/egs++/sources/egs_isotropic_source/egs_isotropic_source.h

@@ -24,6 +24,7 @@
 #  Author:          Iwan Kawrakow, 2005
 #
 #  Contributors:    Frederic Tessier
+#                   Reid Townson
 #
 ###############################################################################
 */
@@ -70,10 +71,11 @@
 
   \ingroup Sources
 
-An isotropic source is a source that delivers particles with
-directions uniformly distributed in \f$4 \pi\f$ emitted from
-\link EGS_BaseShape any shape. \endlink
-It is defined using the following input
+An isotropic source is a source that delivers particles of a given
+\c charge with directions uniformly distributed in \f$4 \pi\f$ emitted from
+\link EGS_BaseShape any shape \endlink with \link EGS_BaseSpectrum any spectrum.
+\endlink 
+It is defined most simply using the following input:
 \verbatim
 :start source:
     library = egs_isotropic_source
@@ -85,13 +87,122 @@ It is defined using the following input
         definition of the spectrum
     :stop spectrum:
     charge = -1 or 0 or 1 for electrons or photons or positrons
-    min theta = 80  (degree)
-    max theta = 100 (degree)
+    min theta = 80  [degree] (optional)
+    max theta = 100 [degree] (optional)
+    min phi = 80  [degree] (optional)
+    max phi = 100 [degree] (optional)
 :stop source:
 \endverbatim
+
+It is also possible to generate source particles from a more complex shape
+by including or excluding geometry regions. This is done by providing
+the \c geometry name to operate on, a <tt>region selection</tt> mode, and
+<tt>selected regions</tt> for the region selection operation. The <tt>selected
+regions</tt> tag is necessary and used only for \c IncludeSelected and 
+\c ExcludeSelected modes. 
+
+The available region selection modes are described below. A particle is
+generated within the defined shape uniformly, and kept only if it meets the
+corresponding condition:
+
+\li <tt>IncludeAll</tt> - particle is inside \c geometry
+\li <tt>ExcludeAll</tt> - particle is NOT inside \c geometry
+\li <tt>IncludeSelected</tt> - particle is inside \c geometry AND in one of 
+<tt>selected regions</tt>
+\li <tt>ExcludeSelected</tt> - particle is not inside \c geometry OR not in 
+one of <tt>selected regions</tt>
+
+\verbatim
+:start source:
+    library = egs_isotropic_source
+    name = some_name
+    geometry = a geometry to modify particle generation (optional)
+    region selection = IncludeAll or ExcludeAll or IncludeSelected or ExcludeSelected (optional)
+    selected regions = regions to use (only for IncludeSelected or ExcludeSelected)
+    :start shape:
+        definition of the shape to generate particles within
+    :stop shape:
+    :start spectrum:
+        definition of the spectrum
+    :stop spectrum:
+    charge = -1 or 0 or 1 for electrons or photons or positrons
+    min theta = 80  [degree] (optional)
+    max theta = 100 [degree] (optional)
+    min phi = 80  [degree] (optional)
+    max phi = 100 [degree] (optional)
+:stop source:
+\endverbatim
+
 It is worth noting that the functionality of source 3 in the RZ series
 of user codes or source 6 in DOSXYZnrc can be reproduced with
 the isotropic source from the EGSnrc C++ class library.
+
+Here is an example of two spheres in a box emitting isotropic photons. Only
+the geometry and source blocks are provided:
+\verbatim
+:start geometry definition:
+    :start geometry:
+        name        = my_box
+        library     = egs_box
+        box size    = 1 2 3
+        :start media input:
+            media = H2O521ICRU
+        :stop media input:
+    :stop geometry:
+    :start geometry:
+        name        = sphere1
+        library     = egs_spheres
+        midpoint = 0 0 1
+        radii = 0.3
+        :start media input:
+            media = AIR521ICRU
+        :stop media input:
+    :stop geometry:
+    :start geometry:
+        name        = sphere2
+        library     = egs_spheres
+        midpoint = 0 0 -1
+        radii = 0.3
+        :start media input:
+            media = AIR521ICRU
+        :stop media input:
+    :stop geometry:
+    :start geometry:
+        name        = my_envelope
+        library     = egs_genvelope
+        base geometry = my_box
+        inscribed geometries = sphere1 sphere2
+    :stop geometry:
+
+    simulation geometry = my_envelope
+
+:stop geometry definition:
+:start source definition:
+    :start source:
+        name                = my_source
+        library             = egs_isotropic_source
+        charge              = 0
+        geometry            = my_envelope
+        region selection    = IncludeSelected
+        selected regions    = 1 2
+        :start shape:
+            type     = box
+            box size    = 1 2 3
+            :start media input:
+                media = H2O521ICRU
+            :stop media input:
+        :stop shape:
+        :start spectrum:
+            type = monoenergetic
+            energy = 1
+        :stop spectrum:
+    :stop source:
+
+    simulation source = my_source
+
+:stop source definition:
+\endverbatim
+\image html egs_isotropic_source.png "An example of two spheres emitting isotropic photons"
 */
 
 class EGS_ISOTROPIC_SOURCE_EXPORT EGS_IsotropicSource :

HEN_HOUSE/egs++/sources/egs_parallel_beam/egs_parallel_beam.h

@@ -23,7 +23,7 @@
 #
 #  Author:          Iwan Kawrakow, 2005
 #
-#  Contributors:
+#  Contributors:    Reid Townson
 #
 ###############################################################################
 */
@@ -95,6 +95,32 @@ from the RZ series of user codes and sources 0 and 1
 in DOSXYZnrc can be reproduced with
 the parallel beam source from the EGSnrc C++ class library.
 
+A simple example:
+\verbatim
+:start source definition:
+    :start source:
+        library = egs_parallel_beam
+        name = my_source
+        :start shape:
+            type = cylinder
+            radius   = 1
+            height   = 2
+            axis     = 0 0 1
+            midpoint = 0
+        :stop shape:
+        direction = 0 0 1
+        charge = 0
+        :start spectrum:
+            type = monoenergetic
+            energy = 6
+        :stop spectrum:
+    :stop source:
+
+    simulation source = my_source
+
+:stop source definition:
+\endverbatim
+\image html egs_parallel_beam.png "A simple example"
 */
 class EGS_PARALLEL_BEAM_EXPORT EGS_ParallelBeam :
     public EGS_BaseSimpleSource {