Double Chooz Tutorial

Madrid, Spain -- March 6, 2007
Chicago, Illinois -- May 15, 2007
Updated for Prod-03-02 on SL4 linux at CC-IN2P3 on May 23, 2008

How to Setup the Environment
How to Setup CVS
How to Checkout the Code
Simple Root and Ntuple Tutorial
How to configure DCGLG4sim mac files
Monte Carlo configuration files
Event Generators
Event Graphics
Simple Root TTree Contents
Monte Carlo Ntuple Contents
Usefull Links

Setup the Double Chooz Environment

To setup the environment at IN2P3 in an SL4 system source the setup files in $THRONG_DIR

source $THRONG_DIR/configDChooz_Lyon.sh

source $THRONG_DIR/configDChooz_Lyon.csh

Double Chooz CVS Tutorial

Configure CVS as described in the IN2P3 CVS Introduction

The Double Chooz CVS contact is Michel Obolensky (obolen@in2p3.fr or Michel.Obolensky@in2p3.fr). You need to send him the info described in CVS account information

If you want to access CVS from more than one host you need to set up a config file. Create $HOME/.ssh/config or append if it exists with:

Host cvs.in2p3.fr
User YOUR CVS USER ID
RSAAuthentication yes
PubkeyAuthentication yes
Protocol 2
ForwardX11 no
ForwardAgent no
IdentityFile ~/.ssh/key_for_cvs.in2p3.fr

Where ~/.ssh/key_for_cvs.in2p3.fr is the file that holds the private key that matches the public key you sent to IN2P3 when you established your CVS account. You may be able to find this key at $HOME/.ssh/id_rsa of your computer. Also see how to protect your key.

How to Checkout the Code

Change to your $THRONG_DIR/$USER directory
If you already have a DOGS directory move it or delete it. "mv DOGS DOGS-old" or "rm -rf DOGS"
Type "cvs checkout -r Prod-03-02 DOGS"
Type "cd DOGS"
This will give you a tested version of the code that works with this tutorial. Prod-03-02 is a specific tag of cvs that may not include recent unstable code changes. The default detector configuration in the Prod-03-02 tag is 390 10 inch photomultiplier tubes with individual magnetic shields. The buffer walls are 40% reflecting bare stainless steel.

Double Chooz Simple Root and Ntuple Access Tutorial

Configure the Double Chooz environment.
If you have not already done so checkout the release used for this tutorial.
To produce different outputs from the DCGLG4sim Monte Carlo use the ./configure command and choose simple-ROOT for simple ROOT output or simple-HBOOK for Ntuple output.
One also needs to use GLG4sim configured the same way.
simple ROOT output can be accessed from the root command line.
Ntuple output can be accessed from the paw command line.
Each time you build DCGLG4sim $THRONG_DIR/$USER/DOGS/bin/dcglg4sim is replaced. If you want to keep multiple versions of $THRONG_DIR/$USER/DOGS/bin/dcglg4sim you should rename it before building a new version.
Be warned that $THRONG_DIR/$USER/DOGS/bin/dcglg4sim is a symbolic link so copying it may not do what you want.
To configure and build the code:
First build the DCDB libraries and DCBase.
```
cd DCDB
make
cd ../DCBase
make
cd ../..
```
Then configure and build the simulation
```
cd DOGS/DCGLG4sim/GLG4sim/
./configure
```
Pick 3 for hbook or 2 for root
```
make
cd ..
./configure
```
Pick the same as you did for GLG4sim
```
make
```
simple-ROOT can produce 2 different TTrees for output. The normal TTree is a subset of the one produced when DCGLG4sim is run with
```
/event/output_mode full
```
The use of the full output mode with the Ntuple format produces 2 additional Ntuples. Space limitations make it difficult to get all of the hit information of the full output mode into a single Ntuple.
For the rest of this tutorial we will assume that we do not have "full" output.
As an example let us run 500 simulated antineutrino interactions.
The Antineutrino_hepevt.mac file would generate 500 antineutrino interactions in the detector when run.

You can run it with the command

$THRONG_DIR/$USER/DOGS/bin/dcglg4sim mac/Antineutrino_hepevt.mac 1>Antineutrino_hepevt.out 2>Antineutrino_hepevt.err

This runs $THRONG_DIR/$USER/DOGS/bin/dcglg4sim and directs the standard output and standard error to files.
The job could also be submitted to the batch queues at CC-IN2P3. Here is a sample batch script. Modify it for your needs.

#!/bin/bash
# Run with: qsub -eo -l t=200000,M=512MB,platform=LINUX,scr=500MB  Batch.sh
cd $THRONG_DIR/$USER/DOGS/DCGLG4sim
source $THRONG_DIR/configDChooz_Lyon.sh
$THRONG_DIR/$USER/DOGS/bin/dcglg4sim mac/Antineutrino_hepevt.mac 1>Antineutrino_hepevt.out 2>Antineutrino_hepevt.err

This should take about 30 minutes to run at CC-IN2P3.
So we will not wait for it to finish.
To continue the tutorial copy the results of the Monte Carlo from
$THRONG_DIR/DATA4ALL/hepevt_dcgen500t.hbook
or
$THRONG_DIR/DATA4ALL/hepevt_DCgen500t.root

To access the simple root file with the root program start root:

root -l
TFile tf("hepevt_DCgen500t.root");
event_tree->Draw("totScintEdep");
event_tree->Draw("totScintEdep","pdg_code==2112");
event_tree->SetLineColor(kRed);
event_tree->Draw("totScintEdep","pdg_code==-11","same");
event_tree->SetLineColor(kBlack);
event_tree->Draw("totScintEdep","pdg_code==22");
event_tree->Draw("delta_UT","delta_UT<1.e5");
event_tree->Draw("totScintEdep","delta_UT<1.e5");
event_tree->Draw("x0:y0","pdg_code==-11");
event_tree->Draw("z0:sqrt(x0*x0+y0*y0)","pdg_code==-11");
.q

To access the hbook file with paw, start paw:

$CERN_BIN/pawX11
h/fil 1 hepevt_dcgen500t.hbook 32768
n/plo 1.totscintedep
n/plo 1.totscintedep pdg_code.eq.2112
set hcol 2
n/plo 1.totscintedep pdg_code.eq.-11 ! ! ! s
set hcol 1
n/plo 1.totscintedep pdg_code.eq.22
n/plo 1.delta_UT delta_UT.lt.1.e5
n/plo 1.totscintedep delta_UT<1.e5
n/plo 1.x0%y0 pdg_code.eq.-11
n/plo 1.z0%(x0**2+y0**2) pdg_code.eq.-11
quit

Interactive access to the data via root or paw is nice but to do serious studies such as reconstruction requires program access to these files.

There are programs in DOGS/DCGLG4sim/examples to do this.
DOGS/DCGLG4sim/examples/readntuple.f is a sample code to read the DCGLG4sim Ntuple, do some simple calculations, and output a different Ntuple. To be usefull you need to add your own code to readntuple.f where indicated near the end of the program.
Access to the Ntuple is via the following code:
```
      call HLIMIT(NWPAWC)
C
C Set up the input Ntuple
C
      call HROPEN(17,'dcglg4sim', FileName ,'P',LRECL,ISTAT)
      if( istat.ne.0 ) then
         print *,'HROPEN: istat = ',istat
      endif
      call HRIN(1,999999,0)
      CALL HBNAME(1,'DATA',izero,'$CLEAR')
      CALL HBNAME(1,'DATA',eventID,'$SET')
C
      call HNOENT(1,entries)
      write(6,100)entries
 100  format('Number of entries ',i6)
...
C
C loop over all the events of the input ntuple
C
      do 10 j=1, entries
      if( j.ne.1) then
C fast call
      call HGNTF(1,j,ierr)
      else
      call hgnt(1,j,ierr) 
      endif
...
```
DOGS/DCGLG4sim/examples/RecoVS.cc is a sample code to read the DCGLG4sim simple root format, do some calculations, and output an Ntuple. The reconstruction in this code is based on Minuit and is contained in the MinFit routine near the end.
Access to the TTree is via the following code:
```
  //Open up the root tree from the simulation
  TFile InFile(argc[1],"READ");

  TTree *InTree = (TTree *) InFile.Get("event_tree");
  TEvent_TreeV *Tevent=new TEvent_TreeV(InTree);
  Int_t nevent = InTree->GetEntries();
...
  for (Int_t j=0;j<nevent-1;j++){
    //Get the event
    InTree->GetEntry(j);
...
    for(int i=0;i<Tevent->photon_hit_n_photon_hits;i++){
      PHeight=Tevent->photon_hit_hit_count[i];
      Tnum=(int)Tevent->photon_hit_hit_pmt[i];
...
```
There is also DOGS/DCGLG4sim/examples/ReadDCEDOGS.cc that can be compiled to read, process and histogram DOGS formated files. The version of ReadDCEDOGS in release Prod-03-02 has not been checked against the current version of DOGS formated files. Due to rapid evolution of the format ReadDCEDOGS may not be useable at present. An attempt to build the version in the Prod-03-02 release at CC-IN2P3 has shown that it is incompatible with the current DCEVENT and PulseThInfo classes.
Homework
- For the purposes of this tutorial one needs to set $GLG4DATA. For the moment do:
```
export GLG4DATA=$THRONG_DIR/losecco/DOGS/DCGLG4sim/examples
```
  or
```
setenv GLG4DATA $THRONG_DIR/losecco/DOGS/DCGLG4sim/examples
```
- Compile readntuple and RecoVS. In the DOGS/DCGLG4sim/examples directory
```
g77 -o readntuple readntuple.f -L$CERN/$CERN_LEVEL/lib -lpacklib_noshift
FC=f77 make RecoVS
```
- Run readntuple and RecoVS on the hepevt_dcgen500t.hbook and hepevt_DCgen500t.root files you used above.
```
./readntuple ../hepevt_dcgen500t.hbook
./RecoVS ../hepevt_DCgen500t.root
```
- Explore the Ntuples produced by readntuple and RecoVS. These are hepevt_dcgen500t.hb4 from readntuple and hepevt_dcgen500tvs.hbook from RecoVS.
```
$CERN_BIN/pawX11
h/fil 1 hepevt_dcgen500t.hb4 32768
...
```
  and
```
$CERN_BIN/pawX11
h/fil 2 hepevt_dcgen500tvs.hbook 32768
...
```
- For extra credit compile and run ReadDCEDOGS. It requires that DCEvent already be built. It runs on DOGS formated DCGLG4sim files. The output of ReadDCEDOGS is named *.hbook. Where * was the basename of the input used when running ReadDCEDOGS. The ReadDCEDOGS output is the same as the output from RecoVS.
No geometry information is stored in the DCGLG4sim output. All reconstruction code must get the tube positions independently. Problems can arise if the geometry used in the analysis differs from the geometry used in the event generation. The readntuple and RecoVS codes get the phototube position information from $GLG4DATA/pmtcoordinates_optical_id.dat
pmtcoordinates_optical_id.dat has been removed from the Prod-03-02 release. $GLG4DATA also no longer exists. The fallback directory DCGLG4sim/data has been removed.
The instructions above, in the Homework section, set $GLG4DATA to a location that has the correct coordinate files.

How to configure DCGLG4sim mac files

A typical macro file used with DCGLG4sim is mac/Antineutrino_hepevt.mac used above. It is printed here.
Annotated instructions

#$Id: Antineutrino_hepevt.mac,v 1.5 2007/05/15 05:43:23 gahs Exp $
/run/particle/setCut 1.0 mm
/glg4debug/glg4param omit_muon_processes  1.0
/glg4debug/glg4param omit_hadronic_processes  0.0
/run/initialize

/generator/pos/set 10 0 0 0

# Set event window to 100 nanosecond

/generator/event_window 100

# set hepevt input file
/generator/vtx/set 18 "/afs/in2p3.fr/throng/dchooz/DATA/DCgen500-HEPEvt"
# anti-neutrino hepevt generator rates Way to high
#More realistic rate at far detector about 20000 events/year
/generator/rates 38 0.0008

# only defer certain types of particles to later events
/process/inactivate DeferTrackProc all
/process/activate DeferTrackProc gamma
/process/activate DeferTrackProc e-
/process/activate DeferTrackProc e+

# uncomment next lines to turn off optical photon tracking -- big speedup!
# /glg4scint/off
# /process/inactivate Cerenkov

/glg4scint/on
/process/activate Cerenkov

/event/output_file hepevt_DCgen500

/run/verbose 1
/run/beamOn 10000
/event/output_file

Monte Carlo Configuration Files

Annotated instructions for settings.dat and settings_cylindrical.dat.

THE FOLLOWING HAS NOT BEEN CHECKED AS OF MAY 23, 2008
$GLG4DATA no longer exists in release Prod-03-02

They are located in $GLG4DATA

pmtcoordinates_cylindrical_id.dat
Inner detector tube base positions.

pmtcoordinates_cylindrical_veto.dat
Inner veto tube positions.

pmtcoordinates_optical_id.dat
A shifted form of pmtcoordinates_cylindrical_id.dat.

materials.dat
Generic material properties.

DCmaterials.dat
Double Chooz specific material properties.

settings.dat

settings_cylindrical.dat
Detector dimensions.

fluids_card.dat
Fluid properties. See optics_howto.txt.

DChoozOptics.dat
Generated by the Monte Carlo.

Event Generators

DCGLG4sim has many event generators built into it. In addition it has the ability to read events in hepevt format. Double Chooz has several programs to generate calibration events and neutrino signal events in hepevt format. These hepevt events can be sent to DCGLG4sim, using DCGLG4sim rate code 38. This is illustrated in the macro section above.

A simpler way to produce events is to use an internal generator. Examples of this are:

# Arguments to /generator/gun command are
#   opticalphoton x y z  p_x p_y p_z  E_eV pol_x pol_y pol_z N_photons
#
# Here we ask for 337 nm, at origin, isotropic, rndm polarization, 100/flash
/generator/gun opticalphoton 0 0 0  0 0 0  3.68e-6 0 0 0 100

other examples

/generator/gun e+ 0 0 0  0 0 0  0
/generator/gun mu- -500 -750 2887 0.1 0.2 -0.9746794 1100.
/generator/gun gamma 0 0 0  1 0 0  1.022
/generator/gun neutron 0 0 2950 0 0 -1  6.0  0 1 0

/generator/gun particle-name x y z px py pz K [polx poly polz]

This command is a convenient way of setting the user-controlled test gun parameters. It is really an alias for the two commands:

/generator/pos/set 9 x y z
/generator/vtx/set 17 particle_name px py pz K polx poly polz

For isotropic direction vectors, leave (px,py,pz) all zero and set K. For other options, such as uniformly filling a volume or uniformly painting a surface, use

/generator/pos/set 9

directly.

or from DOGS/DCGLG4sim/mac/pmt_Bi214-bkg_demo.mac

/generator/pos/set 9 "2400. 335. 254. fill"
/generator/vtx/set 17 "Bi214 0 0 0  0."

or for Boron 12, Sodium 21, Helium 8 or 9 and Lithium 7

/generator/pos/set 9 "0 0 0 fill"
/generator/vtx/set 17 "B12 0 0 0  0"
/generator/vtx/set 17 "Na21 0 0 0  0"
/generator/vtx/set 17 "He8 0 0 0  0"
/generator/vtx/set 17 "He9 0 0 0  0"
/generator/vtx/set 17 "Li7 0 0 0  0"

Some information on DCGLG4sim internal generators can be found here.
Hepevt event generators include calibration event generators in DOGS/DCGLG4sim/GLG4sim/generators/misc/ (Cf252, ambe, cs137_gammas, co60_gammas, ge68_gammas) and the neutrino event generator in DOGS/DCNuGen.
DCNuGen needs a converter, DOGS/DCGLG4sim/generators/Convert-JP-HEPEvt.cc to convert the neutrino events into the hepevt format.
A full tutorial on using DCNuGen can be found here.
A supernova event generator can be found in DOGS/DCGLG4sim/generators/SuperNova.c. Only charged current quasielastic electron antineutrino interactions on hydrogen are currently supported by the supernova event generator.

Double Chooz Graphics Tutorial

Graphics is a project which is still in process.

Current graphics software is in DOGS/DCGLG4sim/examples

It uses OpenGL and the GLaux and the TK toolkit

It uses a networked, client server model.
The server, client and display can run on different machines.

To link the code you will need to compile libaux.a and libtk.a
The source code for these can be found at CC-IN2P3 in

~losecco/Chooz/DOGS/DCGLG4sim/examples/libaux.tar.Z

and

~losecco/Chooz/DOGS/DCGLG4sim/examples/libtk.tar.Z

Compiled versions, libaux.a and libtk.a, are also in this directory.

To use the graphics code you must build at least ServChooz and DisDChooz.
You must set your environment just as it was to build DCGLG4sim.
The ServChooz code needs access to root headers and libraries.

make ServChooz

and

make DisDChooz

in the DOGS/DCGLG4sim/examples directory.
The DOGS/DCGLG4sim/examples directory must have libaux.a and libtk.a which you can either copy from

~losecco/Chooz/DOGS/DCGLG4sim/examples/libaux.a

and

~losecco/Chooz/DOGS/DCGLG4sim/examples/libtk.a

or build from the sources in the same directory.

This version of ServChooz distributes data from files in the simple root format.
It was written before any other format was functional.
It would be easy to adapt the ServChooz code for other formats.
The display part would not need to change.

To start the server you should have a DCGLG4sim simple root format file.
You can use $THRONG_DIR/DATA/muon-120t.root if you have no other.
Start the server with the command

ServChooz $THRONG_DIR/DATA/muon-120t.root

In general the command to start the server is (path to server code)/ServChooz (location of simple root DCGLG4sim file)
Only one ServChooz can be run per computer unless efforts are made to utilize a different network socket for the different copies of ServChooz. The second version of ServChooz would exit with the message

binding stream socket: Address already in use

Once started the ServChooz program reads through the entire root file. When ready it prints the line

Input file contains xxx events

. ServChooz can be run in the background or it can be put in the background after being started.

The actual graphics program is DisDChooz. DisDChooz has several options. There is a mode to read from a special formated ascii file, that was only used for debugging. To get a list of options

DisDChooz -h

To run the display

./DisDChooz -t2 -q1 -s1 -dlocalhost

if you are running the display on the same machine that you ran ServChooz.
If you are running the DisDChooz code on a different computer the last option should be

-dSERVER_NAME

where SERVER_NAME is the IP name of the machine on which the server is running.
A window should pop up on $DISPLAY

The surface area of a displayed sphere is an indicator of its pulse height. The color indicates relative timing. There are 2 display algorithms for timing and 2 for pulse heights.

The display is managed from the display window.

"n" will fetch the next event, "b" will get the previous event. You can not go backward past the first event nor can you go past the last event.

"d" will zoom in and "u" will zoom out.

Hold and drag the left mouse button to rotate the view.

"p" will produce a color postscript image named DisDChooz.eps. Another "p" will overwrite the last one.

"q" will exit the display program

Other options when starting DisDChooz include:

-t1             Set the time format to log

-t2             Set the time format to sorted linear

-q1             Set the pulse height format to saturate at 25 pe

-q2             Set the pulse height format to rescale for each event

Only the tube numbers, earliest hit time and total pulse height is sent to the DisDChooz program.
DisDChooz uses the tube positions in

$GLG4DATA/pmtcoordinates_optical_id.dat

ServChooz is multithreaded. Multiple DisDChooz clients can connect to the same ServChooz program and view an independent set of events.

The server and client communicate over socket port number 6001 but this can be changed with the command

-pPORTNUMBER  Set the host socket port number

Simple Root TTree Contents

Br    0 :fStartRealTime :
Br    1 :fStopRealTime :
Br    2 :fStartCpuTime :
Br    3 :fStopCpuTime :
Br    4 :fTotalCpuTime :
Br    5 :fTotalRealTime :
Br    6 :fCounter  :
Br    7 :fUniqueID :
Br    8 :fBits     :
Br    9 :event_info : eventID/I:runID/I:UT/F:delta_UT/F:eventType/I
Br   10 :vertex_info.n_particles : n_particles/I
Br   11 :vertex_info.t0 : t0[n_particles]/F
Br   12 :vertex_info.x0 : x0[n_particles]/F
Br   13 :vertex_info.y0 : y0[n_particles]/F
Br   14 :vertex_info.z0 : z0[n_particles]/F
Br   15 :vertex_info.pdg_code : pdg_code[n_particles]/I
Br   16 :vertex_info.px : px[n_particles]/F
Br   17 :vertex_info.py : py[n_particles]/F
Br   18 :vertex_info.pz : pz[n_particles]/F
Br   19 :vertex_info.polx : polx[n_particles]/F
Br   20 :vertex_info.poly : poly[n_particles]/F
Br   21 :vertex_info.polz : polz[n_particles]/F
Br   22 :vertex_info.ke : ke[n_particles]/F
Br   23 :vertex_summary : vketot/D:vcentroid_x/F:vcentroid_y:vcentroid_z
Br   24 :photon_hit.n_photon_hits : n_photon_hits/I
Br   25 :photon_hit.hit_time : hit_time[n_photon_hits]/D
Br   26 :photon_hit.hit_pmt : hit_pmt[n_photon_hits]/s
Br   27 :photon_hit.hit_count : hit_count[n_photon_hits]/I
Br   28 :oveto_hit.n_oveto_hits : n_oveto_hits/I
Br   29 :oveto_hit.hit_time : vhit_time[n_oveto_hits]/D
Br   30 :oveto_hit.hit_energy : vhit_energy[n_oveto_hits]/D
Br   31 :oveto_hit.hit_pt : vhit_pt[n_oveto_hits]/s
Br   32 :inner     : n_pmt_hits/I:n_hit_pmts/I
Br   33 :outer     : n_pmt_hits/I:n_hit_pmts/I
Br   34 :GLG4scint : totScintEdep/F:totScintEdepQuenched:scint_centroid_x:scint_centroid_y:scint_centroid_z

An annotated list of the event_tree TTree

Monte Carlo Ntuple Contents

 1   * I*4  * eventID
 2   * I*4  * runID
 3   * R*4  * UT
 4   * R*4  * delta_UT
 5   * I*4  * eventType
 6   * I*4  * n_particles[0,16]
 7   * R*4  * t0(n_particles)
 8   * R*4  * x0(n_particles)
 9   * R*4  * y0(n_particles)
10   * R*4  * z0(n_particles)
11   * I*4  * pdg_code(n_particles)
12   * R*4  * px(n_particles)
13   * R*4  * py(n_particles)
14   * R*4  * pz(n_particles)
15   * R*4  * polx(n_particles)
16   * R*4  * poly(n_particles)
17   * R*4  * polz(n_particles)
18   * R*4  * ke(n_particles)
19   * R*4  * vcentroid_x
20   * R*4  * vcentroid_y
21   * R*4  * vcentroid_z
22   * R*4  * vketot
23   * I*4  * inner_n_pmt_hits
24   * I*4  * inner_n_hit_pmts
25   * R*4  * totScintEdep
26   * R*4  * totScintEdepQuenched
27   * R*4  * scint_centroid_x
28   * R*4  * scint_centroid_y
29   * R*4  * scint_centroid_z
30   * I*4  * n_oveto_hits[0,540]
31   * R*4  * ovhit_time(n_oveto_hits)
32   * R*4  * ovhit_energy(n_oveto_hits)
33   * I*4  * hit_pt(n_oveto_hits)
34   * I*4  * n_photon_hits[0,5400]
35   * I*4  * hit_pmt(n_photon_hits)
36   * R*4  * hit_time(n_photon_hits)
37   * I*4  * hit_count(n_photon_hits)

Useful Links

IN2P3 CVS Introduction
Getting Started with Double Chooz Software
DOGS Tutorial -- Warning the word "DOGS" has 2 different meanings in these pages
Double-Chooz French Site
Double-Chooz CVS repository at IN2P3
Double-Chooz software mailing list archive
Double Chooz E-Log at KSU
Software Wiki at Aachen
Monte Carlo DOGS output setup. (advanced)
Double-Chooz EDMS documentation repository at IN2P3
IN2P3 Computing

Email the author

Updated: November 21, 2007 After setting up CVS they can be accessed and run with

cvs co -r 1.3 config/Setup.sh
source config/Setup.sh

cvs co -r 1.3 config/Setup.csh
source config/Setup.csh