idres

The program idres calculates the error matrix of the track-fit parameters for magnetic tracking-spectrometers. Tracks are described by five helix parameters at the origin. The resolution for these parameters depends on the magnetic field B, the initial track transverse momentum Pt, the track angle eta, as well as on the geometry, radiation length and resolution of the detectors that do the tracking.

The program is based on the mathematics given in the note "Parameterisation of the Inner Detector Performance" by E-J Buis, R Dankers, A Reichold, S Haywood, 21 Jan 1998 - ATLAS Inner Detector note 97-195.

Idres can now handle both perfect solenoidal fields and imperfect ones, given as a table of values of (B_r, B_z) on an (r, z) grid, carrying out the double B-integrals in the Buis et al. document.

Input

All the parameters needed by idres are supplied in an external file (a simple text file). The file contains a list of B-fields, transverse-momenta, and eta angles followed by a description of the detector layout as cylinders or discs, each with the radiation length and resolutions (precision and second coordinates) given. The data is "free-format" - items are separated by white space or end-of-lines. You can spread the input out over as many or few lines as you want. Best is to get an example file and amend it; the exact input definition is given below:

Units: magnetic field in T; lengths in m (including resolutions); momenta in GeV/c; angles as pseudo-rapidity except for B-field integration angles, which are given in radians

Key:

() groups things together (e.g. before a ...), but leave out of your file

<> Replace angle-brackets and contents with desired value

... Repeat the preceding item as often as needed

[ |  | ...] Select one of the items

Any other characters should be given literally (as keywords) (probably case-sensitive).

Input definition:

[B <b-field | files <Brfilename> <Bzfilename>  >... end |
 bIntegral <nStepsR> <rMin> <rMax> <nStepstheta> <thetaMin> <thetaMax>  | 
 eta <eta>... end |
 pt <Pt>... end |
 cylinder
    (<radius> <zstart> <zend> <%X0> <sigma-rphi> <sigma-z>)...
 end |
 disc
    (<inner-radius> <outer-radius> <z> <%X0> <sigma-rphi> <sigma-r>)...
 end |
 cone
    (<inner-radius> <z@outer-r> <z@inner-r> <Cone half angle> <%X0> <sigma-rphi> <sigma-2nd-coord-along-cone>)...
 end |
 ! <comment>
]...

A simple input file could be:

B 2.0 end
eta 0.0 0.5 1.0 1.5 2.0 2.5 end
pt 1 2 5 10 end
cylinder
    0.100 -0.800 0.800 2.5 20e-6 100e-6
    0.200 -0.800 0.800 2.5 20e-6 100e-6
    0.300 -0.800 0.800 2.5 20e-6 100e-6
end
disc
    0.100 0.400 1.0 2.0 20e-6 500e-6
    0.100 0.400 1.2 2.0 20e-6 500e-6
    0.100 0.400 1.5 2.0 20e-6 500e-6
end

Installing the program

For ATLAS users, the code is available in SVN. Packages InDetUpgradeToolFreeIn and InDetUpgradeToolIdRes are both needed. Install the FreeIn one first. Others should mail me (I stopped maintaining the tar file). Follow the instructions in the file called INSTALL.
Either make sure you have libgsl (Gnu Scientific Library) and libgslcblas installed (or re-write the matrix inversion routine matinv.cpp to use your favourite matrix-inverter).

Using the program

Create an input file to describe the detector you want; suppose it is called id.geom. Make sure the program idres is in your PATH. Then type
idres id.geom
...you should see the input file echoed to your terminal, without any error messages. And idres will create 2 output files: id.geom.R and id.geom.res.

The first is a set of R commands to draw the geometry you supplied. Currently it has also some additional pieces for the ATLAS inner detector cryostat; if this is not what you want, then either ignore this file or edit the source code in the file drawgeom.cpp to do what you want. Use it in R with
source ("id.geom.R")

The second contains the results, in columns. The first row gives a descriptive name for each column. the first three columns are the B, Pt, eta values; the next 5 are the resolutions of the five helix parameters. This file can be read in to R with
res <- read.table("id.geom.res", header = TRUE)
Then R can plot resolutions etc. for different B, eta, pt... whatever you want.
Why R? I never succeeded in crashing R. This is not true of root, which I always crashed until I switched to R.

If you want the full covariance matrix, edit the program main.cpp. There is some commented-out code to do this for you - but also you need to print out more column headers.

The program has been tested on the original ATLAS inner detector layout. The geometry file is available here. The comparison is made in this document.