Project

General

Profile

Guide to Using FCL files in MicroBooNE

Links to external documentation (not MicroBooNE-specific)

FCL file utilities

The following command will dump the expanded parameter set that results from include file processing and parameter overrides, etc.

fhicl-dump my.fcl

The following version of the fhicl-dump command produces an annotated expanded parameter set which lists the source of each value.

fhicl-dump -a my.fcl

Note that utility program fhicl-dump belongs to the fhiclcpp ups product, and is independent of the art framework.

The lar program can also be used to produce an expanded parameter set (annotated or nonannotated) resulting from fcl file processing, including the tweaks that the art framework makes internally to the generated parameter set.

lar -c my.fcl --debug-config=/dev/stdout
lar -c my.fcl --debug-config=/dev/stdout --annotate

Services configuration

MicroBooNE provides standard services configuration include files (in uboonecode/uboone/Utilities). Here is a typical example of how these include files can be used.

#include "services_microboone_basic.fcl" 

services: {
  @table::microboone_basic_services
}

In older fcl files, you might find the following construct used instead.

event 
#include "services_microboone_basic.fcl" 

services: {
  user: @local::microboone_basic_services
}

Basic services

#include "services_microboone_basic.fcl" 
Alias Services
@table::microboone_basic_services Geometry (& geometry helper)
DetectorPropertiesService
LArPropertiesService
DetectorClocksService
DatabaseUtil
SpaceCharge
NuRandomService

Simulation services

#include "services_microboone_simulation.fcl" 
Alias Services
@table::microboone_g4_services Basic services
LArG4Parameters
LArVoxelCalculator
PhotonVisibilityService
@table::microboone_detsim_services Basic services
LArFFT
SignalShapingServiceMicroBooNE
DetPedestalService
ChannelStatusService
UBOpticalChConfig
UBOpReadoutMap
@table::microboone_simulation_services G4 services
Detsim services

Reconstruction services

#include "services_microboone.fcl" 
Alias Services
@table::microboone_services_reco Basic services
LArFFT
SignalShapingServiceMicroBooNE
DetPedestalService
ChannelStatusService
UBOpReadoutMap

Note the reconstruction services are almost the same as detector simulation services. Generally, for reconstruction of Monte Carlo events to make sense, service parameters must agree between detector simulation and reconstruction.

Analysis services (BackTracker)

#include "services_microboone.fcl" 

The BackTracker service works in conjunction with the ParticleInventory service.
services:
{
  BackTrackerService:        @local::microboone_backtrackerservice
  ParticleInventoryService:  @local::standard_particleinventoryservice
}

Art services

Time and memory tracker.

#include "time_memory_tracker_microboone.fcl" 

services:
{
  TimeTracker:    @local::microboone_time_tracker
  MemoryTracker:  @local::microboone_memory_tracker
}

SAM services (FileCatalogMetadata)

#include "sam_microboone.fcl" 

services:
{
  FileCatalogMetadata:  @local::art_file_catalog_mc
  #FileCatalogMetadata:  @local::art_file_catalog_data
}

Message service.

#include "services_microboone.fcl" 

services:
{
  message:  @local::microboone_message_services
  #message:  @local::microboone_message_services_prod
  #message:  @local::microboone_message_services_prod_debug
  #message:  @local::microboone_message_services_interactive
}

Some specific FCL parameters

This section covers some specific service and module configuration parameters that may sometimes need to be changed from their default values, or which values are different in different releases, or which have the potential to be problematic if different between detector simulation and reconstruction.

Electron drift

Service fcl parameters that affect electron drift are the electric field, LAr temperature, and electron lifetime. Each of these should eventually be read from a calibration database, but that is not the case as yet (as of v06_09_00).

services.DetectorPropertiesService.Temperature:      89
services.DetectorPropertiesService.Efield:           [0.273, 0.367,0.767] # 0.273 corresponds to 70 kV.
services.DetectorPropertiesService.Electronlifetime: 8.0e3 # Canonical word for the current lifetime, per Ben Carls

Notes:

  • MicroBoone's default LAr temperature of 89K differs from the larsoft default larsoft LAr temperature, which is 91K.
  • The first element of the Efleid vector is the electric field in the bulk. The other elements are the electric field between the readout planes, which are dependent on the bias voltages.
  • The drift velocity is a hard-wired function in DetectorProperties service of the LAr temperature and the electric field.

TPC ASIC settings and response functions.

TPC ASIC settings and response functions are handled by SignalShapingServiceMicroBooNE service via the following fcl parameters.

services.SignalShapingServiceMicroBooNE.ASICGainInMVPerFC:    [ [14.0, 14.0, 14.0], [4.7, 14.0, 14.0] ]   # Gain (mV/fC)
services.SignalShapingServiceMicroBooNE.ShapeTimeConst:       [ [2.0, 2.0, 2.0], [ 1.0, 2.0, 2.0] ]       # Shaping time (us)
services.SignalShapingServiceMicroBooNE.NConfigs:             1
services.SignalShapingServiceMicroBooNE.StretchFullResponse:  false

Notes:

  • Gain and shaping time are indexed, first, by "configuraiton number", and second, by plane number. The first configuration is the default.
  • Multiple asic configurations have been used to handle channels with misconfigured asic settings (aka "quiet wires"). The list of channels that require nondefault asic settings are stored in data file "quietWires.txt in ups product uboone_data.
  • Fcl parameter NConfigs controls whether nondefault asic settings are used.
  • Fcl parameter StretchFullResponse controls how TPC response functions are stretched to account for changes in electric field. In the default setting of "false" (which is believed to more closely match how the response depends on the electric field in data), only the field response is stretched, and the electronics response is not stretched. If StretchFullResponse is set to "true," both field and electronics responses are stretched according to the electric field. This setting is included to match how mcc7 files were detector-simulated.

TPC waveform truncation (RawDigitFilterUBooNE).

Raw digit noise filtering in module RawDigitFilterUBooNE can be configured to truncate raw digit waveforms for the purpose of reducing reconstruction time and output size. Waveform truncation is controlled by the following fcl parameters.

physics.producers.digitfilter.TruncateTicks: true        # Truncate flag.
physics.producers.digitfilter.WindowSize: 6400           # Truncated waveform size.
physics.producers.digitfilter.NumTicksToDropFront: 2400  # Truncated waveform offset.

Proper reconstruction of truncated waveforms requires some adjustments of various service fcl parameters. The following fcl parameters are used if waveform truncation is disabled.

services.DetectorClocksService.InheritClockConfig: true
services.DetectorClocksService.TriggerOffsetTPC: -1600
services.DetectorPropertiesService.NumberTimeSamples: 9600
services.DetectorPropertiesService.ReadOutWindowSize: 9600

These parameters should be changed as follows if waveform truncation is enabled.

services.DetectorClocksService.InheritClockConfig: false
services.DetectorClocksService.TriggerOffsetTPC: -400
services.DetectorPropertiesService.NumberTimeSamples: 6400
services.DetectorPropertiesService.ReadOutWindowSize: 6400

Noise filter (RawDigitFilterUBooNE).

The default configuration of module RawDigitFilterUBooNE for reconstructing data:

physics.producers.digitfilter.ProcessNoise: true
physics.producers.digitfilter.FFTAlg.TransformViewVec: [ true, false, false]
physics.producers.digitfilter.FFTAlg.ZigZagCorrectVec: [ true, true, false]

This was also the configuration used for reconstruction in mcc7. For mc, it may be desirable to turn off noise filtering in cases where post-filter noise is included in the simulation (as in mcc8):

physics.producers.digitfilter.ProcessNoise: false
physics.producers.digitfilter.FFTAlg.TransformViewVec: [ false, false, false]
physics.producers.digitfilter.FFTAlg.ZigZagCorrectVec: [ false, false, false]

Gaussian deconvolution filter

The original Wiener filter:

services.SignalShapingServiceMicroBooNE.FilterFuncVec:  [ "(x>0.0)? (gaus(0)*exp(-0.5*pow(x/[3],[4]))): 0.0", "(x>0.0)? (gaus(0)*exp(-0.5*pow(x/[3],[4]))): 0.0", "(x>0.0)? ([0]*exp(-0.5*(((x-[1])/[2])^2)^[4])) + 0*[3]: 0.0" ]
services.SignalShapingServiceMicroBooNE.FilterParamsVec:   [ [ 1.803396, 1.69, 1.55, 0.19, 3.75 ], [ 1.849030, 1.46, 1.33, 0.23, 4.89 ], [ 1.034516, 0.08, 0.15, 0.0, 2.17 ] ]
services.SignalShapingServiceMicroBooNE.FilterWidthCorrectionFactor:  [ 1.0, 1.0, 1.0 ]

Mike Mooney's Gaussian filter (introduced in uboonecode v06_01_00):

services.SignalShapingServiceMicroBooNE.FilterFuncVec:  [ "(x>0.0)*gaus", "(x>0.0)*gaus", "(x>0.0)*gaus" ]
services.SignalShapingServiceMicroBooNE.FilterParamsVec:   [ [ 1.0, 0.0, 0.1 ], [ 1.0, 0.0, 0.1 ], [ 1.0, 0.0, 0.1 ] ]
services.SignalShapingServiceMicroBooNE.FilterWidthCorrectionFactor:  [ 0.738, 0.738, 0.738 ]

Notes:

  • Parameter FilterWidthCorrectionFactor is set to 0.738 in the Gaussian filter to undo the automatic stretching of the deconvolution filter based on electric field (value of 0.738 corresponds to 70 kV). If the electric field is changed, this parameter needs to be updated.

Data GausHitFinder thresholds used with Wiener filter:

physics.producers.gaushit.MinSig:  [4.0, 4.0, 5.0]
physics.producers.gaushit.MaxMultiHit:  10

MC GausHitFinder thresholds used with Wiener filter:

physics.producers.gaushit.MinSig:  [3.8, 3.8, 4.3]
physics.producers.gaushit.MaxMultiHit:  10

Data GausHitFinder thresholds (reduced 35%) for use with Gaussian filter (introduced by Tracy into uboonecode v06_07_00):

physics.producers.gaushit.MinSig:       [2.6, 2.6, 3.25]
physics.producers.gaushit.MaxMultiHit:  4

Data GausHitFinder thresholds proposed by Davide Porzio in Oct. 4, 2016 reco meeting talk (docdb 6492):

physics.producers.gaushit.MinSig:       [4, 2.8, 4.2]
physics.producers.gaushit.MaxMultiHit:  4

MC GausHitFinder thresholds (reduced 35%) for use with Gaussian filter (introduced by Tracy into uboonecode v06_07_00):

physics.producers.gaushit.MinSig:       [2.5, 2.5, 2.8]
physics.producers.gaushit.MaxMultiHit:  4

Space Charge

The following are user-settable space charge service parameters that one might want to change.

services.SpaceCharge.EnableSimSpatialSCE: false
services.SpaceCharge.EnableSimEfieldSCE: false
services.SpaceCharge.EnableCorrSCE: false

  • Set parameter EnableSimSpatialSCE to "true" to enable simulation of spatial distortions in G4 stage.
  • Set parameter EnableSimEfieldSCE to "true" to enable simulation of effect of E-field distortions on recombination (ionization only) in G4 stage.
  • Set parameter EnableCorrSCE to "true" to enable correction of spatial distortions in 3D reconstruction (currently unimplemented).

Photon Library.

The "photon library" is actually art service PhotonVisibilityService. The fcl parameter that selects the photon library file to read is as follows.

services.PhotonVisibilityService.LibraryFile: "PhotonPropagation/LibraryData/uboone_photon_library_v5.root" 

The above (v5) file is the one that was used for mcc7.

The library file location is a relative path that is searched for using the art framework search path $FW_SEARCH_PATH. The library file is actually stored in the uboone_data ups product.

G4RefTime.

G4RefTime is a parameter of DetectorClocksService (formerly TimeService). This parameter's default value is

services.DetectorClocksService.G4RefTime: -4050

This value does not normally need to be changed. Sometimes people get the following mysterious error message.

%MSG-s ArtException:  OpenFile 15-Jun-2016 02:08:28 CDT BeforeEvents
cet::exception caught in art
---- postOpenFile BEGIN
Found historical value disagreement for G4RefTime ... -4050 != -3200
cet::exception caught in EventProcessor and rethrown
---- postOpenFile END
%MSG

This error happens when reading files swizzled using some uboonecode v04 release, which were swizzled using a TimeService configuration that had G4RefTime=-3200. If you get this error, add the following override to your job fcl file.

services.DetectorClocksService.InheritClockConfig: false

Accessing genie flux files in grid jobs.

The default method by which the GENIEGen producer module accesses genie flux files is direct access, meaning files are read using posix, which requires the directories containing flux files to be nfs-mounted. This is usually not the case for grid jobs. Genie jobs can be run on the grid if the following overrides are included in the generator job fcl file.

physics.producers.generator.FluxCopyMethod: "IFDH" 
physics.producers.generator.MaxFluxFileMB: 500

where "generator" is the module label of the GENIEGen module (your module label may be different).

The above parameters are usually not included by default in standard released fcl files. The standard workflow (project.py) may add the above overrides for generator jobs, which will work provided a) project.py recognizes that your job is a generator job, and b) your module label is "generator." At times, it may be necessary to add these overrides manually.

Use caution when using IFDH flux file access interactively. By default, GENIEGen will copy flux files to /var/tmp using IFDH, which may easily fill up the /var filesystem on gpvm nodes. You can change the location where GENIEGen copies flux files by defining environment variable $TMPDIR. This is the reason why IFDH flux file access is not the default.

TPC Noise in Detector Simulation.

Module SimWireMicroBooNE generates noise on TPC waveforms (RawDigits). This module usually has label "daq" in standard detsim fcls. The module parameter that controls noise simulation is "GenNoise". The following values are supported.

physics.producers.daq.GenNoise: 0     # No noise.
physics.producers.daq.GenNoise: 1     # Time domain (default in mcc7).
physics.producers.daq.GenNoise: 2     # Frequency domain.
physics.producers.daq.GenNoise: 3     # Data driven (default in mcc8).

Data-driven field response.

For mcc8, several new parameters were added in SignalShapingServiceMicroBooNE in support of data-driven field response and YZ-dependent field response.

The parameters that reproduce the behavior of mcc7 (new parameters indicated) are as follows:

services.SignalShapingServiceMicroBooNE.FieldResponseFVersion: [ "v0.1", "v0.1"]
services.SignalShapingServiceMicroBooNE.YZdependentResponse: false                              # New parameter
services.SignalShapingServiceMicroBooNE.datadrivenResponse: false                               # New parameter
services.SignalShapingServiceMicroBooNE.IncludeMisconfiguredU: false                            # New parameter
services.SignalShapingServiceMicroBooNE.DefaultEField: 0.5
services.SignalShapingServiceMicroBooNE.DefaultTemperature: 87
services.SignalShapingServiceMicroBooNE.FilterWidthCorrectionFactor: [ 0.738, 0.738, 0.738]     # Use 1.0 for using Wiener filter.
services.SignalShapingServiceMicroBooNE.FieldRespAmpVec:  [1.0, 1.0, 1.0]
services.SignalShapingServiceMicroBooNE.CalibResponseTOffset: [0, 0, 0]

For mcc8, the settings are as follows.

services.SignalShapingServiceMicroBooNE.FieldResponseFVersion: [ "v3.11", "v3.11"]
services.SignalShapingServiceMicroBooNE.YZdependentResponse: true                               # New parameter
services.SignalShapingServiceMicroBooNE.datadrivenResponse: true                                # New parameter
services.SignalShapingServiceMicroBooNE.IncludeMisconfiguredU: false                            # New parameter
services.SignalShapingServiceMicroBooNE.DefaultEField: 0.273
services.SignalShapingServiceMicroBooNE.DefaultTemperature: 89
services.SignalShapingServiceMicroBooNE.FilterWidthCorrectionFactor: [ 1.0, 1.0, 1.0]
services.SignalShapingServiceMicroBooNE.FieldRespAmpVec:  [ 0.555, 0.447, 1.46 ]
services.SignalShapingServiceMicroBooNE.CalibResponseTOffset: [0.0, 2.0, 0.0]

Notes:

  • The field response version (parameter FieldResponseFVersion) is linked to parameters DefaultEField, DefaultTemperature and FilterWidthCorrectionFactor.
  • Parameter YZdependentResponse can be true of false, independent of any other parameter.
  • Parameter datadrivenResponse should only be set to true with response version 3.1.

Standard MicroBooNE fcl files

Standard fcl files for simulation

Release G4 Detsim Reco1 Reco2 Anatree
v04_36_00[_xx] standard_g4_uboone.fcl standard_detsim_uboone.fcl reco_uboone_mcc7_driver_stage1.fcl reco_uboone_mcc7_driver_stage2.fcl standard_ana_uboone.fcl
v05_08_00[_xx] (xx<=04) reco_uboone_mcc7_driver_stage1.fcl reco_uboone_mcc7_driver_stage2.fcl standard_ana_uboone.fcl
v05_08_00[_xx] (xx>=05) reco_uboone_mcc7_gaussfilter_driver_stage1.fcl reco_uboone_mcc7_driver_stage2.fcl standard_ana_uboone.fcl
v06_26_01[_xx] standard_g4_uboone.fcl standard_detsim_uboone.fcl reco_uboone_mcc8_driver_stage1.fcl reco_uboone_mcc8_driver_stage2.fcl standard_ana_uboone.fcl

Recalibration fcl files for simulation

Release Recalibration
v06_26_01[_xx] reco_uboone_mcc8_driver_cali.fcl

Standard fcl files for data reconstruction

Release Series Reco1 Reco2 Anatree
v04_26_03[_xx] v1 reco_uboone_data_wflash_neutrinoID.fcl
v04_26_04[_xx] v2 reco_uboone_data_minimal_driver.fcl
v04_36_00[_xx] v3,v4 reco_uboone_data_Feb2016_driver_stage1.fcl reco_uboone_data_Feb2016_driver_stage2.fcl standard_ana_uboone_data_minimal.fcl
v05_08_00[_xx] (xx<=04) v5 reco_uboone_data_Feb2016_driver_stage1.fcl reco_uboone_data_Feb2016_driver_stage2.fcl standard_ana_uboone_data.fcl
v05_08_00[_xx] (xx>=05) reco_uboone_data_Feb2016_gaussfilter_driver_stage1.fcl reco_uboone_data_Feb2016_driver_stage2.fcl standard_ana_uboone_data.fcl
v06_26_01[_xx] reco_uboone_data_mcc8_driver_stage1.fcl reco_uboone_data_mcc8_driver_stage2.fcl standard_ana_uboone_data.fcl

Recalibration fcl files for data

Release Recalibration
v06_26_01[_xx] reco_uboone_data_mcc8_driver_cali.fcl

Standard fcl files for swizzling

Release Series Swizzle Merge
v04_26_02 v1 swizzle_with_three_filters.fcl copy_raw.fcl
v04_26_03[_xx] v1 swizzle_with_three_filters.fcl copy_raw.fcl
v04_26_04[_xx] (xx<=03) v2 swizzle_trigger_streams.fcl copy_rawbnb.fcl
copy_rawnumi.fcl
copy_rawext.fcl
copy_rawmucs.fcl
copy_rawprescale.fcl
copy_rawnotpc.fcl
v04_26_04[_xx] (xx>=05) v3 swizzle_software_trigger_streams.fcl copy_rawbnb.fcl
copy_rawbnb_unbiased.fcl
copy_rawnumi.fcl
copy_rawnumi_unbiased.fcl
copy_rawext_bnb.fcl
copy_rawext_numi.fcl
copy_rawext_unbiased.fcl
copy_rawmucs.fcl
copy_rawnotpc_specalib.fcl
v05_08_00[_xx] (xx>=03) v3 swizzle_software_trigger_streams.fcl copy_rawbnb.fcl
copy_rawbnb_unbiased.fcl
copy_rawbnb_hsnc0.fcl
copy_rawnumi.fcl
copy_rawnumi_unbiased.fcl
copy_rawext_bnb.fcl
copy_rawext_numi.fcl
copy_rawext_unbiased.fcl
copy_rawmucs.fcl
copy_rawnotpc_specalib.fcl
v06 (develop) swizzle_software_trigger_streams.fcl copy_rawbnb.fcl
copy_rawbnb_unbiased.fcl
copy_rawnumi.fcl
copy_rawnumi_unbiased.fcl
copy_rawext_bnb.fcl
copy_rawext_numi.fcl
copy_rawext_unbiased.fcl
copy_rawmucs.fcl
copy_rawnotpc_specalib.fcl