source: trunk/documents/UserDoc/DocBookUsersGuides/ForApplicationDeveloper/xml/Detector/digitization.xml@ 1185

<!-- ******************************************************** -->
<!--                                                          -->
<!--  [History]                                               -->
<!--    Converted to DocBook: Katsuya Amako, Aug-2006         -->
<!--    Changed by: Katsuya Amako, 21-Sep-1998                -->
<!--    Changed by: Dennis Wright, 27-Nov-2001                -->
<!--    Proof read by: Joe Chuma,  30-Jun-1999                -->
<!--                                                          -->
<!-- ******************************************************** -->


<!-- ******************* Section (Level#1) ****************** -->
<sect1 id="sect.Digi">
<title>
Digitization
</title>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.Digi.Digi">
<title>
Digi
</title>

<para>
A hit is created by a sensitive detector when a step goes through
it. Thus, the sensitive detector is associated to the corresponding
<emphasis>G4LogicalVolume</emphasis> object(s). On the other hand, a digit is
created using information of hits and/or other digits by a
digitizer module. The digitizer module is not associated with any
volume, and you have to implicitly invoke the <literal>Digitize()</literal>
method of your concrete <emphasis>G4VDigitizerModule</emphasis> class.
</para>

<para>
Typical usages of digitizer module include:

<itemizedlist spacing="compact">
  <listitem><para>
    simulate ADC and/or TDC
  </para></listitem>
  <listitem><para>
    simulate readout scheme
  </para></listitem>
  <listitem><para>
    generate raw data
  </para></listitem>
  <listitem><para>
    simulate trigger logics
  </para></listitem>
  <listitem><para>
    simulate pile up
  </para></listitem>
</itemizedlist>
</para>


<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
G4VDigi
</bridgehead>

<para>
<emphasis>G4VDigi</emphasis> is an abstract base class which represents a
digit. You have to inherit this base class and derive your own
concrete digit class(es). The member data of your concrete digit
class should be defined by yourself. <emphasis>G4VDigi</emphasis> has two virtual
methods, <literal>Draw()</literal> and <literal>Print()</literal>.
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
G4TDigiCollection
</bridgehead>

<para>
<emphasis>G4TDigiCollection</emphasis> is a template class for digits
collections, which is derived from the abstract base class
<emphasis>G4VDigiCollection</emphasis>. <emphasis>G4Event</emphasis> has a
<emphasis>G4DCofThisEvent</emphasis> object, which is a container class of
collections of digits. The usages of <emphasis>G4VDigi</emphasis> and
<emphasis>G4TDigiCollection</emphasis> are almost the same as <emphasis>G4VHit</emphasis> and
<emphasis>G4THitsCollection</emphasis>, respectively, explained in the previous
section.
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.Digi.DigMod">
<title>
Digitizer module
</title>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
G4VDigitizerModule
</bridgehead>

<para>
<emphasis>G4VDigitizerModule</emphasis> is an abstract base class which
represents a digitizer module. It has a pure virtual method,
<literal>Digitize()</literal>. A concrete digitizer module must have an
implementation of this virtual method. The Geant4 kernel classes do
not have a ``built-in'' invocation to the <literal>Digitize()</literal>
method. You have to implement your code to invoke this method of
your digitizer module.
</para>

<para>
In the <literal>Digitize()</literal> method, you construct your
<emphasis>G4VDigi</emphasis> concrete class objects and store them to your
<emphasis>G4TDigiCollection</emphasis> concrete class object(s). Your
collection(s) should be associated with the <emphasis>G4DCofThisEvent</emphasis>
object.
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
G4DigiManager
</bridgehead>

<para>
<emphasis>G4DigiManager</emphasis> is the singleton manager class of the
digitizer modules. All of your concrete digitizer modules should be
registered to <emphasis>G4DigiManager</emphasis> with their unique names.

<informalexample>
<programlisting>
     G4DigiManager * fDM = G4DigiManager::GetDMpointer();
     MyDigitizer * myDM = new MyDigitizer( "/myDet/myCal/myEMdigiMod" );
     fDM-&gt;AddNewModule(myDM);
</programlisting>
</informalexample> 
</para>

<para>
Your concrete digitizer module can be accessed from your code using
the unique module name.

<informalexample>
<programlisting>
     G4DigiManager * fDM = G4DigiManager::GetDMpointer();
     MyDigitizer * myDM = fDM-&gt;FindDigitizerModule( "/myDet/myCal/myEMdigiMod" );
     myDM-&gt;Digitize();
</programlisting>
</informalexample>  
</para>

<para>
Also, <emphasis>G4DigiManager</emphasis> has a <emphasis>Digitize()</emphasis> 
method which takes the unique module name.

<informalexample>
<programlisting>
     G4DigiManager * fDM = G4DigiManager::GetDMpointer();
     MyDigitizer * myDM = fDM-&gt;Digitize( "/myDet/myCal/myEMdigiMod" );
</programlisting>
</informalexample> 
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
How to get hitsCollection and/or digiCollection
</bridgehead>

<para>
<emphasis>G4DigiManager</emphasis> has the following methods to access to the
hits or digi collections of the currently processing event or of
previous events.
</para>

<para>
First, you have to get the collection ID number of the hits or
digits collection.

<informalexample>
<programlisting>
     G4DigiManager * fDM = G4DigiManager::GetDMpointer();
     G4int myHitsCollID = fDM-&gt;GetHitsCollectionID( "hits_collection_name" );
     G4int myDigiCollID = fDM-&gt;GetDigiCollectionID( "digi_collection_name" );
</programlisting>
</informalexample> 
</para>

<para>
Then, you can get the pointer to your concrete
<emphasis>G4THitsCollection</emphasis> object or 
<emphasis>G4TDigiCollection</emphasis> object of the currently processing event.

<informalexample>
<programlisting> 
     MyHitsCollection * HC = fDM-&gt;GetHitsCollection( myHitsCollID );
     MyDigiCollection * DC = fDM-&gt;GetDigiCollection( myDigiCollID );
</programlisting>
</informalexample> 
</para>

<para>
In case you want to access to the hits or digits collection of
previous events, add the second argument.

<informalexample>
<programlisting> 
     MyHitsCollection * HC = fDM-&gt;GetHitsCollection( myHitsCollID, n );
     MyDigiCollection * DC = fDM-&gt;GetDigiCollection( myDigiCollID, n );
</programlisting>
</informalexample>  

where, <literal>n</literal> indicates the hits or digits collection of the
<literal>n</literal><superscript>th</superscript> previous event.
</para>

</sect2>
</sect1>