# Survey

In this webpage you can find some general information about the mechanisms put in place for the use of Survey data for Alignment in ALICE.

You are probably looking for one of these three sections:

## Survey Status Table

OVERVIEW ACORDE EMCAL FMD HMPID ITS MUON PHOS PMD TOF TPC TRD T0 VZERO
SPD SDD SSD
Surveyed         O
Data in Survey Depot (DCDB)         O
Code in CVS         O
Uses AliSurveyObj         O
Produces AliAlignObj         O

Due date for task in planning tool 30/10
2007
01/01
2008
13/10
2007
15/05
2007
(~)Done!
16/03
2007
03/10
2006
03/10
2006
31/05
2007
(~)Done!
13/04
2007
(~)Done!
03/10
2006
18/04
2007
(~)Done!
15/09
2007
31/03
2007
(~)Done!
31/10
2007
26/03
2007
Done!

Last table update: 18/02/2008 (Raffaele Grosso)

## Survey Information

### Introduction

Survey data is used for the initial alignment of a detector. The survey consists of the measured positions of points for which the position in the ideal geometry is known. Using the differences between these points in the ideal geometry and the measured positions it is possible to calculate the displacements and Euler angles for each alignable volume. These values are stored as an alignment object (AliAlignObj) that contains the initial alignment.

### Survey data sources

There are two main survey data sources: the TS/SU group at CERN and the individual detectors teams, the so called “Internal Survey”.

• TS/SU (usually refered to as “Survey Group”) - This is the main source for all the survey measurements made at CERN. They store all the produced reports in EDMS in the form of PDF files.
• Internal Survey - This refers to any survey produced internally during the assembly of a detector for example. “Internally” by the detector’s group. This happens frequently in detectors assembled outside CERN in some institutes, for example some of the different ITS detectors have been surveyed by their respective groups when performing the assembly.

### EDMS

EDMS is a “ electronic document management system” widely used at CERN. The EDMS Document Number (and Version) can be used to uniquely identify any document stored in EDMS and, consequently, any survey report produced by the TS/SU group. Since the main source of survey data is this group we have decided to use the EDMS Report Number to uniquely identify each survey report. The implies that any survey data that is to be made available through the standard framework provided by the ALICE Offline has to be stored initially in EDMS. This will make the data publicly available in a central repository to everyone who whishes to consult the original report, which anyway is almost always necessary to properly interpret and use the data.

EDMS is however a system designed to be used by humans who want to look into a single document at a time. It isn’t meant to be accessed automatically by any program. So, although this is our reference storage location for the “initial” form of the survey data this can’t be the storage from where the data is read by a computer program.

### Text file (Raw Survey)

To create the bridge between the reports stored in EDMS and AliROOT a text file format has been defined in cooperation with the survey group. It has been agreed that they will provide all the necessary reports in this format in parallel with the usual (and necessary) PDF report stored in EDMS. This file will be created for all the measurements made in the cavern from the moment the format has been fixed, and also for any other measurements by request on a case by case basis.

These files are designated as “raw survey files”, they contain a brief description of the report and the measured points coordinates. It’s a simple file which doesn’t include information about the survey targets (if any), the particular conditions of the measurements and any particular observations. This means that in order to properly use the information contained in these files it is necessary to look into the original PDF report.

The raw survey files have a defined syntax which must be followed, the keywords defined and for some of the data fields there is also a limited range of valid values.

The syntax rules are:

• Each line contains either a keyword or a value, it’s not possible to include both in the same line;
• Only one value line is allowed for keyword line except for the “General Observations” and “ Data ” keywords;
• Each keyword line must be followed by at least one value line;
• The values shouldn’t be inside any kind of delimiter, (), or for example;
• There should be an empty line at the end of the file;
• Only the subdetectors/structures listed in the template below are allowed, the same applies for the coordinate systems;
• The Report URL must be in the form

or

• Column names restrictions:
• The column names for the values of X, Y and Z must always start with X, Y and Z but their order is not important;
• The Precision can be specified globally or separately for each coordinate or a mix of the two. However, the order should be from the less specific to the more specific:
"Point Name,XPH,YPH,ZPH,Point Type,Target Used,Precision(mm),PrecisionX(mm)"

"Point Name,XPH,YPH,ZPH,Point Type,Target Used,PrecisionX(mm),Precision(mm)"

The precision for different axis can also be grouped:

"Point Name,XPH,YPH,ZPH,Point Type,Target Used,PrecisionXY(mm),PrecisionZ(mm)"
• The column names “Point Name”, “X...”, “Y...”, “Z...”, “Point Type” and “Precision” (for all three axis) must always be present;
• The number of columns must match the number of column names and the number of columns in each and every data line;

These rules are as far as possible enforced by the parser (in class AliSurveyObj in AliROOT). If a rule is broken the parser will fail displaying an error message.

This is the standard template with all the permited values for some of the keywords:

> Title:
Insert title here. One line.
> Date:
DD/MM/YYYY
> Subdetector: (choose one)
TPC
HMPID
PHOS
MUON
ITS
EMCAL
T0
VZERO
FMD
TRD
TOF
PMD
ZDC
ACORDE
Spaceframe
L3 Magnet
Backframe
Babyframe
Superstructure
MUON Dipole
MUON Absorvers
> Report URL:
https://edms.cern.ch/document/nnnnnn
> Version:
n
> General Observations:
Any observations necessary. Can span over several lines.
Example of a second line: Point Types: M(easured), T(ransformed), R(eference)
> Coordinate System: (choose one)
ALICEPH
ALICESU
LOCAL
> Units: (choose one)
m
cm
mm
etc...
> Nr Columns:
6
> Column Names: (choose one)
Point Name,XPH,YPH,ZPH,Point Type,Target Used,Precision(mm)
Point Name,XSU,YSU,ZSU,Point Type,Target Used,Precision(mm)
Point Name,XLOCAL,YLOCAL,ZLOCAL,Point Type,Target Used,Precision(mm)
> Data:
TRD_sm08ah1 -3.6504 0.3337 3.5311 M Y 3
TRD_sm08ah0 -3.5451 0.9294 3.5306 M N 3

This is an actual survey report for V0:

> Title:
Alignment of the V0 and the beam pipe support on the Front Absorber
> Date:
04.04.2007
> Subdetector:
VZERO
> Report URL:
https://edms.cern.ch/document/835615
> Version:
1
> General Observations:
V0 is measured in several iterations. Only the measurement results of the last session (session 8, chapter 6.9) are given below.
The center of Circle fitted through 6XXX points on V0 is called CenterV0.
> Coordinate System:
\ALICEPH
> Units:
mm
> Nr Columns:
7
> Column Names:
Point Name,XPH,YPH,ZPH,Point Type,Target Used,Precision(mm)
> Data:
2001 185.41 345.49 -904.49 M Y 1
2002 -386.09 12.72 -902.91 M Y 1
2003 -139.74 -359.09 -902.67 M Y 1
2004 391.01 17.97 -904.45 M Y 1
3001 17.25 391.04 -903.91 M Y 1
3002 -197.10 338.09 -903.66 M Y 1
3003 -386.78 45.69 -903.52 M Y 1
3004 -305.16 -244.56 -903.13 M Y 1
3005 -22.64 -393.08 -902.82 M Y 1
3006 298.36 -257.06 -903.68 M Y 1
3007 393.68 -21.47 -904.65 M Y 1
6001 -226.41 -226.00 -851.08 M Y 1
6002 -226.92 226.58 -851.62 M Y 1
6003 227.27 -226.18 -851.83 M Y 1
6004 226.93 226.29 -852.69 M Y 1
CenterV0 0.19 0.22 -851.81 T Y 1

### DCDB

The DCDB is an intermediate storage place for the raw survey files. It was chosen because it has an access control mechanism and a intuitive, user-friendly interface was quickly created. This creates a minimal disruption in the (previously) default workflow of the survey producers (mainly the TS/SU group). After uploading the PDF report to EDMS they simply create the text file and using the same basic identifiers upload the raw survey file to the DCDB.

Normal users of the survey data can use the DCDB to make sure the raw survey files they’ll need are available and in case they can’t find these files in the DCDB should request them directly to the survey group at CERN or to the responsible for the survey in their own group (in the case of external survey).

The interface to access the survey data depot in the DCDB is at http://dcdb.cern.ch/surveydepot-production/. You can freely browse the the survey section of the DCDB using the username/password:

guest/visitor

. If you are a survey data producer you can request a personal account by contacting me: Ricardo Silva, only these accounts have permissions to upload new data or to replace existing reports with newer versions.

When uploading data there are 3 key fields which are then used to access/browse the report: Subdetector, EDMS Report Number and EDMS Report Version. The report number and version are enough to uniquely identify a survey report, but for ease of use the Subdetector is also available.

### GRID

The GRID is the final storage place for the raw survey files. There will be an mechanism in place to automatically store the files uploaded to the DCDB in the GRID following a specific schema. This is the location from where the AliSurveyObj class in AliROOT will read the raw survey files. The schema used to store the raw survey files is:

Base folder:

/alice/data/Reference/

Specific Folder:

/RawSurvey/

Filename:

_v.txt

Example:

/alice/data/Reference/HMPID/RawSurvey/2005/598379_v1.txt

The base folder and the first level of the specific folder are generic and can be used to store other “immutable” data (i.e. not year/run dependent as the current schema for the OCDB and other Reference data implies).

The user can browse these folders to make sure the data is there but this is not necessary as this folder structure is automatically syncronized with the DCDB.

### AliSurveyObj

This is a class, available in AliROOT, used to parse the raw survey files into an AliSurveyObj. It can parse both local files and remote files. Remote files are the raw survey files stored on the GRID, they can be accessed by simply specifying the Detector, and Report Number (and optionally the Report Version).

This class can also be used to list the available reports on the GRID and the valid detectors/structures. Bellow a few usage examples are shown:

// Static method which prints a list with the valid detectors and structures
// that can be used to query for available reports and to fill the class.
AliSurveyObj::ListValidDetectors();

// Declare a new AliSurveyObj
AliSurveyObj * s1 = new AliSurveyObj();

// To be able to use the ListReports method it's necessary to previously set
// the username used when connecting to the GRID

// List all available reports
s1->ListReports();

// List all available reports for HMPID
s1->ListReports("HMPID");

// List all available reports for SPACEFRAME (actually lists all reports
// stored in the GRP folder as the SPACEFRAME doesn't have a folder of
// it's own. AliSurveyObj::ListValidDetectors() gives a brief explanation)
// The second command has the exact same effect.
s1->ListReports("SPACEFRAME");
s1->ListReports("GRP");

// List all available reports from 2006
s1->ListReports("", 2006);

// List all available reports from 2007 for TRD
s1->ListReports("TRD", 2007);

// List all versions of report 816582. Will only list more than one if there
// are several versions of the same report as the report number is unique.
s1->ListReports("", -1, 816582);

// List all version 2 reports (not really useful for the normal user)
s1->ListReports("", -1, -1, 2);

// Fill the object with report 816582 for TRD (the highest available version
// is automatically selected)
s1->Fill("TRD", 816582);

// Same operation but manually specifying report version 1
s1->Fill("TRD", 816582, 1);

// In the case the GRID user was not previously set (using SetGridUser(..),
// only really useful when using the ListReports(..) method) the username can
// also be specified as a parameter of Fill(..)
// ---> This is the DEFAULT USE CASE to fill AliSurveyObj s1->Fill("TRD", 781282, "other_grid_user"); // // or
s1->Fill("TRD", 781282, 2, "other_grid_user"); // To select a specific version

// Or fill from a local file:
s1->FillFromLocalFile("~/tmp/781282_v1.txt");

After being successfully filled the AliSurveyObj contains all the information present in the raw survey files, there are getters for all the fields and the points coordinates are stored in a TObjArray, each set of coordinates for a point being an AliSurveyPoint.

AliSurveyPoint getters (from AliSurveyPoint.h):

TString GetPointName() {return fPointName;};
Float_t GetX() {return fX;};
Float_t GetY() {return fY;};
Float_t GetZ() {return fZ;};
Float_t GetPrecisionX() {return fPrecisionX;};
Float_t GetPrecisionY() {return fPrecisionY;};
Float_t GetPrecisionZ() {return fPrecisionZ;};
Char_t GetType() {return fType;};
Bool_t GetTarget() {return fTargetUsed;};

There is a macro which contains an example of AliSurveyObj’s usage in the macros folder in AliROOT:

\$ALICE_ROOT/macros/SurveyAliSurveyObjExample.C

void st2()
{
AliSurveyObj *so = new AliSurveyObj();
Int_t size = so->GetEntries();
printf("-> %d\n", size);

so->FillFromLocalFile("~/survey/real_data/Survey_781282_HMPID.txt");
size = so->GetEntries();
printf("--> %d\n", size);

Printf("Title: \"%s\"", so->GetReportTitle().Data());
Printf("Date: \"%s\"", so->GetReportDate().Data());
Printf("Detector: \"%s\"", so->GetDetector().Data());
Printf("URL: \"%s\"", so->GetURL().Data());
Printf("Number: \"%d\"", so->GetReportNumber());
Printf("Version: \"%d\"", so->GetReportVersion());
Printf("Observations: \"%s\"", so->GetObservations().Data());
Printf("Coordinate System: \"%s\"", so->GetCoordSys().Data());
Printf("Measurement Units: \"%s\"", so->GetUnits().Data());
Printf("Nr Columns: \"%d\"", so->GetNrColumns());

TObjArray *colNames = so->GetColumnNames();
for (Int_t i = 0; i GetEntries(); ++i)
Printf(" Column %d --> \"%s\"", i, ((TObjString *) colNames->At(i))->GetString().Data());

Printf("Points:");
TObjArray *points = so->GetData();
for (Int_t i = 0; i GetEntries(); ++i)
Printf(" Point %d --> \"%s\"", i, ((AliSurveyPoint *) points->At(i))->GetPointName().Data());

// See "STEER/AliSurveyPoint.h" for more getters

return;
}

IMPORTANT NOTE: The coordinates stored in the original survey reports in EDMS and, consequently, in AliSurveyObj, are the coordinates of the measured fiducial marks including targets inserted by the surveyors. This means that to use the data properly the type of target used and it's placement has to be taken into account. The only and final place where the user can find this information is in the original EDMS Survey Report.

NOTE: At the moment (Jun 2007) the automatic interface between the DCDB and the GRID is not yet in place, in order to use any survey files you’ll need to manually download them from the DCDB interface and use the AliSurveyObj::GetFromLocalFile(”...”) method.

## General procedure to use Survey Data for alignment

1. Check the existing survey reports in EDMS and create a list of EDMS Report Numbers with all the reports needed to align a specific detector.
2. Verify that all the reports in that list are present in DCDB. In the case they are not available the producer of the orignal report found in EDMS should be contacted and asked to upload the raw survey text file. (The "producer" is usually the Survey Group (TS/SU) when the measurements were done at CERN.
3. Once all the files needed are in DCDB, the AliSurveyObj class is used to retrieve the data for each file. You need one AliSurveyObj per Survey Report.
4. The information retrieved is used, along with the ideal positions of the measured points, to determine the Euler angles and rotations of each alignable volume in the detector’s geometry. (If a specific volume which should be alignable is not, the detector’s hardcoded geometry must be changed to realistically reflect which volumes can be aligned.)

Steps 3 and 4 are the detector procedures and must have as output an AliAlignObj .

Last update: 17/10/2008 (Raffaele Grosso)

Author: Ricardo Silva