# muon150_algorithm

**Repository Path**: xlab-muon/muon150_algorithm

## Basic Information

- **Project Name**: muon150_algorithm
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-08-28
- **Last Updated**: 2024-09-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# common chain sequence

1. __usb_data_separate_ (system-level)
   - steps:
     - seperate original raw binary data into multiple board-level (layer-level) raw binary files
   - important cmd args:
     - *-f* : input file
     - *-r* : byte-order (little endian or big endian, 32-bits), (madatory for muon150)
     - *-D* : save log message into log file in current directory
     - *-o* : sufftix of output file (default: 'mt')
     - *-O* : output directory (default: 'seperate_out' under the input file)
   - input: single raw binary file
   - output: multiple raw binary file, each corresponding to one layer or one FEC board

2. _adas_data_unpack_ (board-level)
   - steps:
     - unpack FEC raw binary files into ADC-level root file
   - important cmd args:
     - *-f* : input file
     - *-L* : LSB (default: 15, for L = LSB * 2.048 * 0.15492 * 0.001)
     - *-i* : number of chips on board (default: 6)
     - *-b* : flagging baseline data (defualt: false)
     - *-O* : output directory (default: 'unpack_result' under the input file)
   - output:
     - root file (only for normal trigger-mode, no root output for baseline data):
       - tree name: *adas_initial_data*
       - branches: *nhits/I:triggerid/I:adas_hit_idx[nhits]/I:adas_hit_chl[nhits]/I:adas_hit_amp[nhits]/I*
         - *adas_hit_idx* : adc chip index ([0, 5])
         - *adas_hit_chl* : channel index in adc chip ([0, 127])
         - *adas_hit_amp* : adc counts
     - png with pedestal mean and sigma distribution
     - txt file with extracetd pedestal mean (in adc counts) and sigma (in fC)
     - txt file with threshold settings

3. _adas_data_decode_ : (board-level)
   - steps:
     1. select events with both x & y fired
     2. subtract pedestal mean from adc counts
     3. reindex the elctronic channels based on x/y plane (i.e. aggregate channel data from same plane, idx = (0,1), chl= [0,383])
     4. clustering (todo): based on the adjancency of the strips, and the strip indexing are orderly arranged in the output tree
   - important cmd args:
     - *-f* : input file (one of the board-level root files from previous step)
     - *-O* : output directory (default: dec_result)
     - *-a* : the passed pedestal files are absolute path (by the default only filename is passed and searched under the same directory of the input file)
     - *-b* : extracted pedestal mean file (should under the same directory of the input )
     - *-n* : extracted pedestal rms file (should under the same directory of the input, not used actually)
     - *-i* : number of chips on board (defualt: 6)
     - *-L* : LSB (default: 15, for L = LSB * 2.048 * 0.15492 * 0.001)
     - *-e* : channel mapping file (muon15.csv for 150, muon400.csv for 400)
   - output:
     - root file
       - tree: *asic_hit_data*
       - branches: *nhits/I:dimension_idx[nhits]/I:hit_strips[nhits]/I:hit_asic_chn[nhits]/I:hit_amp[nhits]/I:cluster_number/I:cluster_holed_num[cluster_number]/I:cluster_size[cluster_number]/I*
         - *dimension_idx* : 0 for chip_id (0, 1, 2) ; 1 for chip_id (3, 4, 5)
         - *hit_amp* : adc counts substracted baseline mean
         - *hit_asic_chn* : electronic channel index (0-383 for x, 512-895 for y) (todo)
         - *hit_strips* : detector channels (0-383 for x/y)

4. _hit_position_reconstruct_ (board-to-system)
   - steps:
     - extract cluster position and amplitude for each layer
     - aggregate all layers into the same tree entry (with separate branches though)
   - important cmd args:
     - *-f* : input file (first one of the board-level root files from previous step)
     - *-l* : the total number of layers used (default: 0, should be: 6)
     - *-L* : board filename suffix bit-mask indicating which layers are used (default:0, should be 0x3F if all 6 layers are used)
     - *-p* : layer indexing settings
     - *-z* : layer position in z-axis (unit: cm)
   - output:
     - root file
       - tree: *fec_hit_data*
       - branches:
         - *trigger_id_all*
         - *total_layer_num*
         - *dector<x>* : *x_nhits/I:y_nhits/I:x[25]/D:y[25]/D:z/D:x_amp[25]/D:y_amp[25]/D:x_chn_num[25]/I:y_chn_num[25]/I:x_cluster_hole[25]/I:y_cluster_hole[25]/I*
           - *x* and *y* : amplitude-weighted cluster center position in this layer (unit: strip indexing)
           - *z* : layer position in z-axis (unit: cm)
           - *x_amp* and *y_amp* : sum of baseline-substracted adc counts of all strips in the cluster
           - *x_chn_num* and *y_chn_num* : nr of strips in the cluster
           - *x_cluster_hole* and *y_cluster_hole* :  [todo]

5. _adas_muxbrd_fit_  (system-level)
   - steps:
   - important cmd args:
     - *-f* : input file (root files from previous step)
     - *-l* : the total number of layers used (default: 6)
     - *-u*
     - *-v*
     - *-a*
     - *-r*
     - *-g*
     - *-L* : LSB (default: 15, for L = LSB * 2.048 * 0.15492 * 0.001)
     - *-R*
     - *-s*
     - *-A*
     - *-G*
     - *-t*
   - output:
     - root file
       - tree:
       - branches:

6. _track_seeker_ : (system-level)
   - steps: 
     - for each event, loop through all cluster combinations to find the best track
   - important cmd args:
     - *-f* : input file (root files from previous step)
     - *-e* : max rmse allowed (unit: mm, defualt: 10)
     - *-N* : max clusters used in one layer (default: 5)
     - *-L* : min nr of layers needed for a good track (default: 3)
     - *-l* : bi-mask the layers used for track seek, warning: it's not link mask (default: 0xFF, should: 0x3F for 6 layers)
     - *-T* : transimission system (default: false)
     - *-D* : total nr of layers exists (defualt: 4)
     - *-r* : alignment file (both offset and rotation, defualt: empty, i.e. no alingment)
     - *-t* : starting timestamp of these events
     - *-j* : export to json
     - *-O* : specify a target layer
   - output:
     - root file
       - tree: hit_tracker
       - branches:
         - *trigger_di*
         - *kx/ky*
         - *bx/by*
         - *rmse_x/y*
         - *r2_x/y*
         - *x/y/z*
         - *x_amp/y_amp*
         - *x_strip_num/y_strip_num*
     - text file:
       - hit : the original hit position in each layer
       - hit_aligned : aligned hit position

The root file from the last step _hit_position_reconstruct_ (i.e. *fec_hit_data*) is the input 
of all following analysis.

# batch processing
## _data_process.sh_

Key options:
- _-e_

## typical useage

## pedestal data
```bash
./data_process.sh -N -d <filename> -L <link_mask>
```

## muon data
```bash
./data_process.sh -d <filename> -L <link_mask> -m <link_mapping> -z <z_position> -c <system_json>
```

# archive
脚本 data_process.sh 用于将6层muon系统的数据分析步骤整合（分包、解码、对应探测器实际位置、寻track、产生json文件）
  主要参数
  -S 分析软件位置
  -A json文件产生位置
  -L link参数，描述使用的板号
  -d 待分析文件名
  -D 是否跳过分包
  -F 是否跳过解包
  -H 是否跳过位置重建
  -T 是否跳过经迹寻找


用例
  bash data_process.sh -d /home/wangying/work/data/muon-7.dat -L 0x3f -D -F -H -T -A /home/wangying/ -S /home/wangying/work/JW_muon150_ana/cpp/

  待分析初始文件： /home/wangying/work/data/muon-7.dat
  使用板号: (0b00111111) 0, 1, 2, 3, 4, 5块
  json文件生成位置： /home/wangying
  分析软件所在位置： /home/wangying/work/JW_muon150_ana/cpp/
  所有步骤都执行

# analysis

## _adas_muxbrd_sync_ for getting the position resolution, detection efficiency and energy resolution using muon test data

```bash
./adas_muxbrd_sync -f <fec_hit_data> -a <alignment.txt> -R <hitrange.txt> -r 1 -u -v <target_layer_index>
```

"target_layer_index" should be 0~5.