icecube.clsim.traysegments.I3CLSimMakePhotons module

icecube.clsim.traysegments.I3CLSimMakePhotons.I3CLSimMakePhotons(tray: ~icecube.icetray.i3tray.I3Tray, name: str, GCDFile: str, RandomService: phys_services.I3RandomService, UseCPUs: bool = False, UseGPUs: bool = True, UseOnlyDeviceNumber: None|int = None, UseCUDA: bool = False, MCTreeName: str = 'I3MCTree', OutputMCTreeName: None|str = None, FlasherInfoVectName: str = None, FlasherPulseSeriesName: str = None, PhotonSeriesName: str = 'PhotonSeriesMap', MCPESeriesName: str = 'MCPESeriesMap', IceModelLocation: str|simclasses.I3CLSimMediumProperties = '/Users/buildbot/actions-runner/_work/icetray/build/ice-models/resources/models/ICEMODEL/spice_mie', DisableTilt: bool = False, UnWeightedPhotons: bool = False, UnWeightedPhotonsScalingFactor: None|float = None, UseI3PropagatorService: bool = True, UseGeant4: bool = False, ParticleHistory: bool = False, ParticleHistoryGranularity: float = 20.0, CrossoverEnergyEM: None|float = None, CrossoverEnergyHadron: None|float = None, UseCascadeExtension: bool = True, StopDetectedPhotons: bool = True, SaveAllPhotons: bool = False, SaveAllPhotonsPrescale: float = 0.01, PhotonHistoryEntries: int = 0, DoNotParallelize: bool = False, EnableDoubleBuffering: bool = False, DoublePrecision: bool = False, DOMOversizeFactor: float = 5.0, UnshadowedFraction: float = 0.94, DOMEfficiency: float = 1, HoleIceParameterization: str = '/Users/buildbot/actions-runner/_work/icetray/build/ice-models/resources/models/ANGSENS/angsens/as.h2-50cm', WavelengthAcceptance: None|simclasses.I3CLSimFunction = None, DOMRadius: float = 0.1651, CableOrientation: None|str|simclasses.I3MapModuleKeyI3ExtraGeometryItemCylinder = None, OverrideApproximateNumberOfWorkItems: None|int = None, MaxNumOutputPhotonsPerStep: int|_Sentinel = <icecube.clsim.traysegments.common._Sentinel object>, PropagatorSetup: None|StepToPhotonConverterSetupCallback = None, IgnoreSubdetectors: Sequence[str] = ['IceTop'], ExtraArgumentsToI3PhotonPropagationClientModule={}, If: None|Callable[[icetray.I3Frame],bool] = None)

Do standard clsim processing up to the I3Photon level. These photons still need to be converted to I3MCPEs to be usable for further steps in the standard IceCube MC processing chain. Reads its particles from an I3MCTree and writes an I3PhotonSeriesMap.

All available OpenCL GPUs (and optionally CPUs) will be used. This will take over your entire machine, so make sure to configure your batch jobs correctly when using this on a cluster. When using nVidia cards, you can set the CUDA_VISIBLE_DEVICES environment variable to limit GPU visibility. A setting of CUDA_VISIBLE_DEVICES=”0,3” would only use cards #0 and #3 and ignore cards #1 and #2. In case you are using a batch system, chances are this variable is already set. Unfortunately, there is no corresponding setting for the AMD driver.

This segment assumes that MMC has been applied to the I3MCTree and that MMC was NOT run using the “-recc” option.

Parameters:

  • UseCPUs – Turn this on to also use CPU-based devices. (This may potentially slow down photon generation, which is also done on the CPU in parallel.)

  • UseGPUs – Turn this off to not use GPU-based devices. This may be useful if your GPU is used for display purposes and you don’t want it to slow down.

  • UseOnlyDeviceNumber – Use only a single device number, even if there is more than one device found matching the required description. The numbering starts at 0.

  • UseCUDA – Use CUDA implementation of photon propagator instead of OpenCL.

  • MCTreeName – The name of the I3MCTree containing the particles to propagate.

  • OutputMCTreeName – A copy of the (possibly sliced) MCTree will be stored as this name.

  • FlasherInfoVectName – Set this to the name of I3FlasherInfoVect objects in the frame to enable flasher simulation. The module will read I3FlasherInfoVect objects and generate photons according to assumed parameterizations.

  • FlasherPulseSeriesName – Set this to the name of an I3FlasherPulseSeries object in the frame to enable flasher/Standard Candle simulation. This cannot be used at the same time as FlasherInfoVectName. (I3FlasherPulseSeries objects are clsim’s internal flasher representation, if “FlasherInfoVectName” is used, the I3FlasherInfoVect objects are converted to I3FlasherPulseSeries objects.)

  • PhotonSeriesName – Configure this to enable writing an I3PhotonSeriesMap containing all photons that reached the DOM surface.

  • RandomService – Set this to an instance of a I3RandomService. Alternatively, you can specify the name of a configured I3RandomServiceFactory added to I3Tray using tray.AddService(). If you don’t configure this, the default I3RandomServiceFactory will be used.

  • IceModelLocation – Set this either to a directory containing a PPC-compatible ice description (icemodel.dat, icemodel.par and cfg.txt) or to a photonics ice table file. PPC-compatible ice files should generally lead to faster execution times on GPUs since it involves less interpolation between table entries (the PPC ice-specification is parametric w.r.t. wavelength, whereas the photonics specification is not).

  • DisableTilt – Do not simulate ice tilt, even if the ice model directory provides tilt information. (Photonics-based models will never have tilt.)

  • UnWeightedPhotons – Enabling this setting will disable all optimizations. These are currently a DOM oversize factor of 5 (with the appropriate timing correction) and a biased initial photon spectrum that includes the DOM spectral acceptance. Enabling this setting essentially means that all photons that would be generated in the real detector will actually be generated. This will siginificatly slow down the simulation, but the optional PhotonSeries will contain an unweighted sample of photons that arrive at your DOMs. This can be useful for DOM acceptance studies.

  • UnWeightedPhotonsScalingFactor – If UnWeightedPhotons is turned on, this can be used to scale down the overall number of photons generated. This should normally not be touched (it can be used when generating photon paths for animation). Valid range is a float >0. and <=1.

  • StopDetectedPhotons – Configures behaviour for photons that hit a DOM. If this is true (the default) photons will be stopped once they hit a DOM. If this is false, they continue to propagate.

  • PhotonHistoryEntries – The maximum number of scatterings points to be saved for every photon hitting a DOM. Only the most recent positions are saved, older positions are overwritten if the maximum size is reached.

  • UseI3PropagatorService – Use PROPOSAL and cmc to propagate initial particles (i.e. with NaN lengths) through the detector.

  • UseGeant4 – Enabling this setting will disable all cascade and muon light yield parameterizations. All particles will sent to Geant4 for a full simulation. This does not apply to muons that do have a length assigned. These are assumed to have been generated by MMC and their light is generated according to the usual parameterization.

  • ParticleHistory – Store secondary particles produced by particle propagators (e.g. Geant4, PROPOSAL) in the MCTree.

  • ParticleHistoryGranularity – When storing history in the MCTree, coalesce secondary EM cascades that are less than this distance apart.

  • CrossoverEnergyEM – If set it defines the crossover energy between full Geant4 simulations and light yield parameterizations for electro magnetic cascades. This only works when UseGeant4 is set to true. It works in conjunction with CrossoverEnergyHadron. If one of both is set to a positiv value greater 0 (GeV), the hybrid simulation is used. If CrossoverEnergyEM is set to None while CrossoverEnergyHadron is set so hybrid mode is working, GEANT4 is used for EM cascades. If CrossoverEnergyEM is set to 0 (GeV) while CrossoverEnergyHadron is set so hybrid mode is working, leptons and EM cascades will use parameterizations for the whole energy range.

  • CrossoverEnergyHadron – If set it defines the crossover energy between full Geant4 simulations and light yield parameterizations for hadronic cascades. This only works when UseGeant4 is set to true. It works in conjunction with CrossoverEnergyEM. If one of both is set to a positiv value greater 0 (GeV), the hybrid simulation is used. If CrossoverEnergyHadron is set to None while CrossoverEnergyEM is set so hybrid mode is working, GEANT4 is used for hadronic cascades. If CrossoverEnergyHadron is set to 0 (GeV) while CrossoverEnergyHadron is set so hybrid mode is working, hadronic cascades will use parameterizations for the whole energy range.

  • UseCascadeExtension – If set, the cascade light emission parameterizations will include longitudinal extension. Otherwise, parameterized cascades will be treated as point-like.

  • DoNotParallelize – Try only using a single work item in parallel when running the OpenCL simulation. This might be useful if you want to run jobs in parallel on a batch system. This will only affect CPUs and will be a no-op for GPUs.

  • DOMOversizeFactor – Set the DOM oversize factor. To disable oversizing, set this to 1.

  • UnshadowedFraction – Fraction of photocathode available to receive light (e.g. unshadowed by the cable)

  • DOMEfficiency – Sets the global energy scale relative to the unshadowed detector, independent of ice.

  • HoleIceParameterization – Set this to a hole ice parameterization file. The default file contains the coefficients for nominal angular acceptance correction due to hole ice (ice-models project is required). Use file $I3_BUILD/ice-models/resources/models/ANGSENS/angsens/as.nominal for no hole ice parameterization.

  • WavelengthAcceptance – If specified, use this wavelength acceptance to scale the generated Cherenkov spectrum rather than using the DOM acceptance modified for oversizing and angular acceptance.

  • DOMRadius – Allow the DOMRadius to be set externally, for things like mDOMs.

  • CableOrientation – Path to cable orientation file, e.g. $I3_BUILD/ice-models/resources/models/PPCTABLES/cable_position/orientation.led7.txt. If set, blocks photons that would have to pass through the best-fit position of the cable to reach a DOM. This reduces the isotropic efficiency by ~10%. Set to None to disable simulation of the cable shadow.

  • OverrideApproximateNumberOfWorkItems – Allows to override the auto-detection for the maximum number of parallel work items. You should only change this if you know what you are doing.

  • If – Python function to use as conditional execution test for segment modules.

Returns:

the dictionary of keyword arguments passed to I3PhotonPropagationClientModule

icecube.clsim.traysegments.I3CLSimMakePhotons.I3CLSimMakePhotonsWithServer(tray, name, ServerAddress, DetectorSettings, MCTreeName='I3MCTree', OutputMCTreeName=None, FlasherInfoVectName=None, FlasherPulseSeriesName=None, PhotonSeriesName='PhotonSeriesMap', MCPESeriesName='MCPESeriesMap', RandomService=None, ParticleHistory=False, ParticleHistoryGranularity=20.0, PhotonHistoryEntries=0, ExtraArgumentsToI3PhotonPropagationClientModule={}, If=<function <lambda>>)

Propagate particles and photons up to PE level. Reads its particles from an I3MCTree and writes either an I3CompressedPhotonSeriesMap, an I3MCPESeriesMap, or both.

Photon propagation is delegated to the I3PhotonPropagationServer listening at ServerAddress. This server may be shared by multiple client processes to maximize GPU utilization.

If MMCTrackListName is set, this segment will assume that MMC has been applied to the I3MCTree and that MMC was NOT run using the “-recc” option.

Parameters:

  • ServerAddress – The 0MQ address of an I3PhotonPropagationServer

  • DetectorSettings – The output of clsim.traysegments.common.setupDetector. These should be the same as those used to configure the server.

  • MCTreeName – The name of the I3MCTree containing the particles to propagate.

  • OutputMCTreeName – A copy of the (possibly sliced) MCTree will be stored as this name.

  • FlasherInfoVectName – Set this to the name of I3FlasherInfoVect objects in the frame to enable flasher simulation. The module will read I3FlasherInfoVect objects and generate photons according to assumed parameterizations.

  • FlasherPulseSeriesName – Set this to the name of an I3FlasherPulseSeries object in the frame to enable flasher/Standard Candle simulation. This cannot be used at the same time as FlasherInfoVectName. (I3FlasherPulseSeries objects are clsim’s internal flasher representation, if “FlasherInfoVectName” is used, the I3FlasherInfoVect objects are converted to I3FlasherPulseSeries objects.)

  • PhotonSeriesName – Configure this to enable writing an I3CompressedPhotonSeriesMap containing all photons that reached the DOM surface. If this is set to None, photons will be converted to PE immediately, drastically reducing memory overhead for bright events.

  • MCPESeriesName – Configure this to enable writing an I3MCPESeriesMap.

  • RandomService – Set this to an instance of a I3RandomService. Alternatively, you can specify the name of a configured I3RandomServiceFactory added to I3Tray using tray.AddService(). If you don’t configure this, the default I3RandomServiceFactory will be used.

  • ParticleHistory – Store secondary particles produced by particle propagators (e.g. Geant4, PROPOSAL) in the MCTree.

  • ParticleHistoryGranularity – When storing history in the MCTree, coalesce secondary EM cascades that are less than this distance apart.

  • If – Python function to use as conditional execution test for segment modules.

Returns:

the dictionary of keyword arguments passed to I3PhotonPropagationClientModule