In case this README is missing some important information or is unclear do not
hesitate to contact me (Tomáš Křižák) on slack or email - tomas.krizak@cvut.cz

===============================================================================
	USAGE OPTIONS:
===============================================================================

Class TKEvent can be used in two ways: 
	1. online on cluster (installation bellow)
		a) you can use TKEvent objects and functions in your RED scripts
			(similat as in provided 'red_to_tk' script)
		b) you can use the 'red_to_tk' script to convert necessary data
			to root and then simply write root scripts
			(similar to provided 'load_ev' script in 'ANALYSIS_MACROS' folder)
		
	2. offline on your device (optional but very practical)
		- requires: installing TKEvent library and RED to TKEvent converter on cluster,
			    installing TKEvent library on your device,
			    converted data on your device
		- installation: use installation bellow but skip steps 2. and 4.

===============================================================================
	INSTALlATION:
===============================================================================

	1. git clone TKEvent on your cluster environment:	
		$ git clone https://github.com/TomasKrizak/TKEvent.git
		$ cd TKEvent/
	
	2. source environment:
		$ cd RED_to_TK/
		
		for runs up to 812 use:
		$ source load_environment_v1.sh
		
		for runs from 813 to 1045 use:
		$ source load_environment_v2.sh

		for runs 1046 and higher use:
		$ source load_environment_v3.sh
		
	3. install TKEvent libraby on your cluster: 
		$ cd ../TKEvent/
		$ chmod 755 install.sh
		$ ./install.sh
		
	4. install RED to TKEvent converter:
		$ cd ../RED_to_TK/

		!!! only one version coresponding to the loaded environment can be installed.
		For example, if you sourced "load_environment_v1.sh" only "red_to_tk_v1.cxx" 
		can be installed. To prevent the compiling from failing, either remove other
		versions of red_to_tk or change their ".cxx" extension to anything else as
		the compiler tries to process everything with ".cxx" extention !!! 

		$ chmod 755 install.sh
		$ ./install.sh
	
===============================================================================
	HOW TO USE:
===============================================================================

	1. First step after installing the library is to convert a run or its part into the TKEvent root format.
	To do that go to "RED_to_TK/build" folder and run:

		$ ./red_to_TK_new -r "RUN_NUMBER" -e "STOP_EVENT"
		 
	for runs 813 and higher and 

		$ ./red_to_TK -r "RUN_NUMBER" -e "STOP_EVENT"

	for older runs. The "-e" is optional and marks the number of the last event you want converted.
	This is so you do not have to convert always entire run.

	Note: if you already have installed your TKEvent library, make sure to run   
		
		$ source load_environment_new.sh

	This has to be done every time you connect to CCLyon and want to convert a run. 

	2. After converting the runs go to ANALYSIS_MACROS folder. A demonstration script 
	"load_ev.cpp" is provided there. This script shows the usage of the most important
	 and useful functions including visualization and reconstruction. Run it with
	 
	 	$ root load_ev.cpp
	
	This script creates a png picture of every event and stores it in the EVENTS_VISU folder
	so do not run this on more than few hundreds of events at most! 
	
	3. The load_ev.cpp also creates a 3D scene of the event and creates a file containing 
	the 3D information as a root file in EVENTS_VISU folder. To open this 3D view use provided 
	"visu.cpp" script by running
	
		$ root visu.cpp

	RECOMMENDATION: try using keys H,J,K,L,U,I while in the 3D interactive scene. 
	(More detail below)
	
===============================================================================
	DATA STRUCTURE: 
===============================================================================

TKEvent is a library made specifically as a tool for development of tracking 
algorithm however it can do more than that. Class TKEvent extracts most important
information about given event and stores them in vectors of smaller objects:
	- vector of OM hits (TKOHhit),
	- vector of tracker cell hits (TKTrhit),
	- vector of tracks (TKtrack),
	- vector of clusters (TKcluster)
	
In constrast to RED format these classes can contain some processed information like:
	- x,y,z coordinates of tracker cell hits (calculated from timestamps and cell number)
	- radii of tracker cell hits (you can switch drift models)
	- x,y,z coordinates of OM hits
These values however might be improved in the future and are not in their final state yet. 

It also contains information about geometry of the detector given by a series of
constants which might differ from reality - must be taken with caution (work in progress)

=============================================================================== 
	TRACK RECONSTRUCTION:
===============================================================================

At the moment there are several different versions:
	1. reconstruct_single():
	This algorithm finds one best possible track for each side of the tracker 
	based on Legendre transform of tracker hits (if the side has at least 3 usable hits 
	- usable means not missing timestamp t0 and has a radius smaller than 35mm). 
	The search invovles uncertainties (Gauss distribution with sigma = 2mm by default). 

	2. reconstruct_multi():
	multi_track version of 1. It is a bit slower but searches for more possible candidates for tracks. 

	3. reconstruct_ML(): (RECOMMENDED ALGORITHM)
	Implementation of Maximum likelihood method for tracking. Uses a basic pre-clustering algorithm
	which filters obvious noise and other noise tracks. Then uses maximum likelihood method on the 
	cluster, providing the most probable solution. In addition it detects all ambiguities and 
	analyticaly computes the mirror track  

The track is described by four parameters a,b,c,d in form:
	y = ax + b
	z = cx + d
	(x,y,z coordinates corespond to Falaise, origin in center of detector)

And equivalently in the form:
 	x(t) = cos(phi)*cos(theta)*t + r*sin(phi)
 	y(t) = sin(phi)*cos(theta)*t - r*cos(phi)
 	z(t) = sin(theta)*t + h

Both parametrizations are calculated during the tracking and are convenient for different purposes.

If needed, here is the set of transformations:
	a = tan(phi)
	b = -r/cos(phi)
	c = tan(theta)/cos(phi)
	d = h - r*tan(phi)*tan(theta)

	phi = atan(a) 
	r = -b/sqrt(a*a+1.0)
	theta = atan(c/sqrt(a*a+1.0))
	h = d - a*b*c/(a*a+1.0)


===============================================================================
	VISUALIZATION:
===============================================================================

TKEvent has two visualization options:

	1. Top projection - calling a function 'make_top_projection(int option)' on obejct TKEvent (given event) 
		creates and saves png picture (in '/ANAlYSIS_MACROS/Events_visu/' by default) of the detector
		from above with highlighted OM hits and tracker cells hits. If tracks were calculated in this
		event then it depicts them too.

	2. 3D visualization - calling a function 'build_event()' on obejct TKEvent creates and saves a root
		file called 'Run-XXX_event-XXX_3D.root' in '/ANAlYSIS_MACROS/Events_visu/' folder. This stores
		all basic detector geometry as root geometry objects. Can be then visualized using provided
		'visu.cpp' skript in 'ANALASIS_MACROS'.
	
===============================================================================
	Mathematical derivation of the maximum likelihood method:
===============================================================================

	https://www.overleaf.com/read/qpccqmvqfbby#c4c822