Skip to content

TASKS

Jump to bottom
verenamh edited this page Jul 29, 2025 · 7 revisions

More detail about some of the commands in the TASKS menu.

SET_TOA

This function can be called upon in TASKS commands to set the TOA threshold of a given channel. Currently, this function works on the TOA calibration method as described in https://doi.org/10.1016/j.nima.2022.167863. However, other methods of calibration exist and should be analyzed (https://github.com/LDMX-Software/pflib/pull/177#issuecomment-3073984379). This function is meant as a baseline for implementing other, and more in-depth, calibrations.

Instead of using a writer for the daq runs, the function utilizes the pflib::DecodeAndBuffer class which keeps a buffer of event packets from the most recent run. This buffer can then be read out and analyzed between every run. The TOA threshold is set to the first threshold with TOA efficiency equal to 1.

Inputs

  • Target
  • Target class instance tgt that is used for charge injections.
  • ROC
  • ROC class instance roc that is used to apply parameters.
  • Channel
  • This is the channel where the charge injections take place.

Returns

This function doesn't return anything, but applies the TOA_VREF (global TOA threshold) parameter to the ROC.

Usage

This function is called with the following line: set_toa(tgt, roc, channel);

GEN_SCAN

This is an attempt to generalize the scanning infrastructure so that folks can avoid writing C++ if they are just testing out a different parameter scan.

Caution

If you find yourself re-using a scan frequently or you expect a scan to be done on multiple HGCROCs, you should spend time translating it into its own C++ menu command to ease reproducibility.

The basic idea here is that the user supplies a "parameter points file" which is just a CSV containing the different parameter values to test. The command then goes through the different rows of the CSV and does a data collection run for each of those "parameter points".

Inputs

  • Number of events per parameter point
    • Since the total number of rows in the output data file is the number of input rows times the number of events, it is a good idea to keep this number small when starting out.
  • Channel to select
    • This is the channel whose samples will be written into the output file. All other channel data will be discarded.
  • Trigger type
    • either PEDESTAL or CHARGE, choice of fast control command to send to the chip
  • Scan Wide Parameters
    • The user can additionally set any number of "scan wide" parameters which will be applied for the all of the runs within the scan. The scan wide parameters along with the other inputs are written into the JSON header of the output CSV file.
  • File of parameter points
    • The CSV file containing the parameter points to scan
    • The reason we use an intermediate file is so that you (the user) can construct the CSV file however you like. For example, a simple Python script could prepare a parameter points file containing arbitrary parameters and values for you.
  • Output file path
    • path to output pflib CSV file

Output

The output file will look like a CSV except with the first line being JSON starting with a #. This is keeping with the format of a "pflib CSV" that can be read with a Python function in pflib/ana

Example

You can use this infrastructure to do a rough calibration amplitude scan.

rough-calib-ampl-scan.csv:

referencevoltage_0.calib
64
128
256
512
1024
2048

Example pftool input/output view:

 > GEN_SCAN 
Number of events per parameter point:  [1] 
Channel to select:  [42] 0
Trigger type: CHARGE 
Are there parameters to set constant for the whole scan?  (Y/N)  [N] Y
Page: REFERENCEVOLTAGE_0
Parameter: INTCTEST 
Value: 1
Done?  (Y/N)  [N] 
Page: CH_0 
Parameter: LOWRANGE 
Value: 1
Done?  (Y/N)  [N] Y
File of parameter points: rough-calib-ampl-scan.csv 
(2025-06-11 20:07:20) [pftool.tasks]  info: loading parameter points file...
(2025-06-11 20:07:20) [pftool.tasks]  info: successfully loaded parameter points
Filename:  [../data/rough-calib-ampl-scan-2025-06-11-200720.csv] 
(2025-06-11 20:08:29) [pftool.tasks]  info: running test parameter point 0 / 6
(2025-06-11 20:08:29) [pftool.tasks]  info: running test parameter point 1 / 6
(2025-06-11 20:08:29) [pftool.tasks]  info: running test parameter point 2 / 6
(2025-06-11 20:08:29) [pftool.tasks]  info: running test parameter point 3 / 6
(2025-06-11 20:08:29) [pftool.tasks]  info: running test parameter point 4 / 6
(2025-06-11 20:08:29) [pftool.tasks]  info: running test parameter point 5 / 6

And the output file looks like

# {"parameter_points_file":"rough-calib-ampl-scan.csv","channel":0,"nevents_per_point":1,"trigger":"CHARGE","scan_wide_params":{"CH_0":{"LOWRANGE":1},"REFERENCEVOLTAGE_0":{"INTCTEST":1}}}
referencevoltage_0.calib,Tp,Tc,adc_tm1,adc,tot,toa
64,false,false,198,206,-1,0
128,false,false,199,211,-1,0
256,false,false,195,226,-1,0
512,false,false,199,251,-1,0
1024,false,false,198,305,-1,0
2048,false,false,199,410,-1,0

PARAMETER_TIMESCAN

The user can do a timescan and see how the ADC is affected for a varying parameter. The timescan takes a sample once per pulse for a selected BX offset relative to the start of the pulse (charge_to_l1a) and a selected phase (phase_strobe) within that BX.

Inputs

  • Number of events per parameter point
    • Since the total number of rows in the output data file is the number of input rows times the number of events, it is a good idea to keep this number small when starting out.
  • preCC (pre-current conveyor)
    • The user can select if they want to do a charge injection with the pre-current conveyor capacitor.
  • Highrange
    • The user can select between a highrange or lowrange charge injection, given that preCC is false.
  • totscan
    • If the user would like to scan TOT, this option reduced the samples per BX to 1, to not reproduce multiple TOT triggers per BX.
  • TOA threshold
    • The user can select a TOA threshold, keeping in mind that there are values of the TOA threshold where the TOT doesn't trigger, given that totscan is true.
  • TOT threshold
    • The user can select a TOT threshold, given that totscan is true.
  • Calib
    • Select pulse charge height.
  • Channel to select
    • The channels that charge will be simultaneously injected into. The options are either all channels from 0 to 71, or only injecting into channel 61.
  • Start BX
    • The BX to start scanning in
  • Number of BX
    • The number of BXs to scan.
  • Output file path
    • path to output pflib CSV file.
  • File of parameter points
    • The CSV file containing the parameter points to scan
    • The reason we use an intermediate file is so that you (the user) can construct the CSV file however you like. For example, a simple Python script could prepare a parameter points file containing arbitrary parameters and values for you.

Output

The CSV output format is the standard pflib format as in GEN_SCAN. The second row will contain information of the given parameter.

Example

A rough calib scan.

param_calib.csv:

REFERENCEVOLTAGE_0.CALIB
0
20
40
60

Example pftool input/output view:

 > PARAMETER_TIMESCAN 
How many events per time point?  [1] 
Use pre-CC charge injection?  (Y/N)  [N] 
Use highrange (Y) or lowrange (N)?  (Y/N)  [N] y
Scan TOT? This setting reduced the samples per BX to 1  (Y/N)  [N] 
Setting for calib pulse amplitude?  [64] 
Pulse into channel 61 (N) or all channels (Y)?  [N] Y
Starting BX?  [-1] 
Number of BX?  [3] 10
Filename:  [param-time-scan_20250717_100505.csv] 
File of parameter points: ~/paramCsv/param_calib.csv
(2025-07-17 10:05:32) [pftool.tasks]  info: loading parameter points file...
(2025-07-17 10:05:32) [pftool.tasks]  info: successfully loaded parameter points
(2025-07-17 10:05:32) [pftool.tasks]  info: CALIB = 0
(2025-07-17 10:05:32) [pftool.tasks]  info: charge_to_l1a = 15
(2025-07-17 10:05:32) [pftool.tasks]  info: TOP.PHASE_STROBE = 0
(2025-07-17 10:05:32) [pftool.tasks]  info: TOP.PHASE_STROBE = 1
(2025-07-17 10:05:32) [pftool.tasks]  info: TOP.PHASE_STROBE = 2
...

And the output file looks like

# {"highrange":true,"preCC":false}
time,REFERENCEVOLTAGE_0.CALIB,channel,Tp,Tc,adc_tm1,adc,tot,toa
0,0,0,true,false,191,191,-1,0
0,0,1,true,false,239,238,-1,0
0,0,2,true,false,191,189,-1,0
0,0,3,true,false,222,221,-1,0
0,0,4,true,false,235,235,-1,0
0,0,5,true,false,203,205,-1,0
...

VT50_SCAN

The purpose of this command is to scan the calib range for the V_t50 of the TOT. The V_t50 is the calib value when the tot efficiency is 50%. To achieve this goal, the command checks the value of the TIT efficiency at selected calib values. The V_t50 is "honed in on" in with one of two methods: the binary and bisectional search methods. Both methods seem to provide the same results, and the reason why a second method was produced was to verify the other.

Inputs

  • Number of events per parameter point
    • This number determines the resolution of the TOT efficiency. A higher number gives better resolution.
  • preCC (pre-current conveyor)
    • The user can select if they want to do a charge injection with the pre-current conveyor capacitor.
  • Highrange
    • The user can select between a highrange or lowrange charge injection, given that preCC is false.
  • Search method
    • The search method for honing in on the V_t50. Choose between binary and bisectional.
  • Channel to select
    • This is the channel whose samples will be written into the output file. All other channel data will be discarded.
  • TOA threshold
    • The user can select a TOA threshold, keeping in mind that there are values of the TOA threshold where the TOT doesn't trigger.
  • Vref lower
    • The smallest TOT threshold value to scan.
  • Vref upper
    • The largest TOT threshold value to scan.
  • nsteps
    • The number of steps between TOT thresholds.
  • Output file path
    • path to output pflib CSV file.

Output

The CSV output format is the standard pflib format as in GEN_SCAN. The second and third row will contain information of the TOT threshold and calib value, respectively. Using vt50_scan.py in pflib/ana/charge/ the user can plot the tot efficiency curves for all scanned TOT thresholds.

Example

A VT50 scan.

Example pftool input/output view:

> VT50_SCAN 
How many events per time point? Remember that the tot efficiency's granularity depends on this number.  [20] 30
Use pre-CC charge injection?  (Y/N)  [N] 
Use highrange (Y) or lowrange (N)?  (Y/N)  [N] y
Use binary (Y) or bisectional search (N)?  (Y/N)  [N] n
Channel to pulse into?  [61] 14
Value for TOA threshold:  [250] 
Smallest tot threshold value (min = 0):  [300] 
Largest tot threshold value (max = 4095):  [600] 400
Number of steps between tot values:  [10] 
Filename:  [vt50-scan_20250717_100957.csv] 
(2025-07-17 10:10:00) [pftool.tasks]  info: TOT_VREF = 300
(2025-07-17 10:10:04) [pftool.tasks]  info: Final calib is : 262 with tot_eff = 0.466667
(2025-07-17 10:10:04) [pftool.tasks]  info: TOT_VREF = 310
(2025-07-17 10:10:13) [pftool.tasks]  info: Ended after 25 iterations!
Final calib is : 253 with tot_eff = 0.333333
(2025-07-17 10:10:13) [pftool.tasks]  info: TOT_VREF = 320
(2025-07-17 10:10:20) [pftool.tasks]  info: Final calib is : 294 with tot_eff = 0.4
(2025-07-17 10:10:20) [pftool.tasks]  info: TOT_VREF = 330
...

And the output file looks like

# {"channel":14,"highrange":true,"preCC":false}
time,REFERENCEVOLTAGE_0.TOT_VREF,REFERENCEVOLTAGE_0.CALIB,Tp,Tc,adc_tm1,adc,tot,toa
true,300,2047,true,true,238,-1,613,918
true,300,2047,true,true,239,-1,614,918
true,300,2047,true,true,239,-1,614,919
true,300,2047,true,true,239,-1,614,918
...
Clone this wiki locally