source: trunk/documents/UserDoc/DocBookUsersGuides/ForApplicationDeveloper/xml/Detector/commandScore.xml

<!-- ******************************************************** -->
<!--                                                          -->
<!--  [History]                                               -->
<!--    Created by: Makoto Asai,   25-Nov-2007                -->
<!--                                                          -->
<!-- ******************************************************** -->


<!-- ******************* Section (Level#1) ****************** -->
<sect1 id="sect.CommandScore">
<title>
Command-based scoring
</title>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.CommandScore.Intro">

<para>
Command-based scoring in Geant4 utilizes parallel navigation in a parallel
world volume as descibed in the previous sections. Through interactive commands,
the user can define :

<itemizedlist spacing="compact">
  <listitem><para>
 A parallel world for scoring and three-dimensional mesh in it
  </para></listitem>
  <listitem><para>
 Arbitrary number of physics quantities to be scored and filters
  </para></listitem>
</itemizedlist>

After scoring (i.e. a run), the user can visualize the score and dump
scores into a file. All available UI commands are listed in 
<ulink url="./AllResources/Control/UIcommands/_score_.html">
List of built-in commands</ulink>.
</para>

<para>
Command-based scoring is an optional functionality and the user has
to explicity define its use in the <literal>main()</literal>.
To do this, the method <literal>G4ScoringManager::GetScoringManager()</literal>
must be invoked <emphasis role="color_red">right after</emphasis>
the instantiation of <literal>G4RunManager</literal>.

<example>
<title>
A user <literal>main()</literal> to use the command-based scoring
</title>
<programlisting>

#include "G4RunManager.hh"
<emphasis role="color_red">#include "G4ScoringManager.hh"</emphasis>

int main(int argc,char** argv)
{
 // Construct the run manager
 G4RunManager * runManager = new G4RunManager;

 // Activate command-based scorer
 <emphasis role="color_red">G4ScoringManager::GetScoringManager();</emphasis>

 ...

}
</programlisting>
</example>
</para>    

</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.CommandScore.Mesh">
<title>
Defining a scoring mesh
</title>

<para>
To define a scoring mesh, the user has to specify the followings.
<itemizedlist spacing="compact">
  <listitem><para>
 Shape and name of the 3D scoring mesh. Currently, box is the only available shape.
  </para></listitem>
  <listitem><para>
 Size of the scoring mesh. Mesh size must be specified as "half width" similar to the
 arguments of <literal>G4Box</literal>.
  </para></listitem>
  <listitem><para>
 Number of bins for each axes. Note that too hugh number causes immense memory consumption.
  </para></listitem>
  <listitem><para>
 Optionally, position and rotation of the mesh. If not specified, the mesh is positioned
 at the center of the world volume without rotation.
  </para></listitem>
</itemizedlist>
</para>

<para>
For a scoring mesh the user can have arbitrary number of quantities to be scored for
each cell of the mesh.
For each scoring quantity, the use can set one filter.
Please note that <literal>/score/filter</literal> affects on the preceding scorer.
Names of scorers and filters must be unique for the mesh.
It is possible to define more than one scorer of same kind with different names
and, likely, with different filters.
</para>

<para>
Defining a scoring mesh and scores in the mesh should terminate with the
<literal>/score/close</literal> command. The following sample UI commands
define a scoring mesh named <literal>boxMesh_1</literal>, size of which is
2 m * 2 m * 2 m, and sliced into 30 cells along each axes.
For each cell energy deposition, number of steps of gamma, number of steps
of electron and number of steps of positron are scored.
<example>
<title>
UI commands to define a scoring mesh and scorers
</title>
<programlisting>

#
# define scoring mesh
#
/score/create/boxMesh boxMesh_1
/score/mesh/boxSize 100. 100. 100. cm
/score/mesh/nBin 30 30 30
#
# define scorers and filters
#
/score/quantity/energyDeposit eDep
/score/quantity/nOfStep nOfStepGamma
/score/filter/particle gammaFilter gamma
/score/quantity/nOfStep nOfStepEMinus
/score/filter/particle eMinusFilter e-
/score/quantity/nOfStep nOfStepEPlus
/score/filter/particle ePlusFilter e+
#
<emphasis role="color_red">/score/close</emphasis>
#

</programlisting>
</example>
</para>

</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.CommandScore.Draw">
<title>
Drawing scores
</title>

<para>
Once scores are filled, it is possible to visualize the scores. The score is 
drawn on top of the mass geometry with the current visualization settings.

<figure id="fig.CommandScore_1">
<title>
Drawing scores in slices (left) and projection (right)
</title>
<mediaobject>
  <imageobject role="fo">
    <imagedata fileref="./AllResources/Detector/hit.src/scoreCombinedPicture.jpg"
               format="JPG" contentwidth="12.0cm" align="center" />
  </imageobject>
  <imageobject role="html">
    <imagedata fileref="./AllResources/Detector/hit.src/scoreCombinedPicture.jpg"
               format="JPG" contentwidth="16.0cm" align="center" />
  </imageobject>
</mediaobject>
</figure>
</para>

<para>
By default, entries are linearly mapped to colors (gray - blue - green - red).
This color mapping is implemented in <literal>G4DefaultLinearColorMap</literal>
class, and registered to <literal>G4ScoringManager</literal> with the color map
name <literal>"defaultLinearColorMap"</literal>. The user may alternate color map
by implementing a customised color map class derived from
<literal>G4VScoreColorMap</literal> and register it to
<literal>G4ScoringManager</literal>. Then, for each <literal>draw</literal>
command, one can specify the preferred color map.
</para>

</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.CommandScore.Dump">
<title>
Writing scores to a file
</title>

<para>
It is possible to dump a score in a mesh (<literal>/score/dumpQuantityToFile</literal>
command) or all scores in a mesh (<literal>/score/dumpAllQuantitiesToFile</literal>
command) to a file.
The default file format is the simple CSV. To alternate the file format, one should
overwrite <literal>G4VScoreWriter</literal> class and register it to
<literal>G4ScoringManager</literal>.
Please refer to <literal>/examples/extended/runAndEvent/RE03</literal> for details.
</para>

</sect2>
</sect1>