Package: faster-particles
faster-particles: Pixel Proposal Network (PPN) for particles images and related toolsIntroductionThis package includes the following:Toydata generatorLArCV data interface (2D and 3D)Base network: VGG(ish) and UResNetPixel Proposal Network implementationContentsInstallation1.1.Dependencies1.2.InstallUsage2.1.DatasetLicenseThis code is released under the MIT License (refer to the LICENSE file for more details).InstallationDependenciesYou must installlarcv2and its
own dependencies (ROOT, OpenCV, Numpy) in order to use LArCV data interface.
To installlarcv2:gitclonehttps://github.com/DeepLearnPhysics/larcv2.gitcdlarcv2sourceconfigure.sh
makeYou will also needTensorflow.InstallThe easiest way is to use Pip, although you will not get the latest changes:pipinstallfaster-particlesAlternatively, you can also clone the source if you want the latest updates or
participate to its development:gitclonehttps://github.com/Temigo/faster-particles.gitcdfaster-particlesUsageThe following assumes you installed with pip. If you cloned the source, make
sure you are in the root directory and replaceppnwithpython faster_particles/bin/ppn.py.DatasetToydataTo use toydata rather than LArCV data in the following sections, use the option--toydata.This is an old option which has not been tested for a while and which should be deprecated soon.Liquid Argon data filesLArCV data files should be specified with--dataoption which supports regex, e.g.ppn_p[01]*.root.
Some data files are publicly available atDeepLearnPhysicsdata challenge page.The generic usage isppn train/demo [directories options] [network architecture] [weights options] [network options] [other options].trainis for training networks,demois for running inference.Directories optionsThe program output is divided between:Output directory (option-o): with all the weightsLog directory (option-l): to store all Tensorflow logs (and visualize them with Tensorboard)Display directory (option-d): stores regular snapshots taken during training of PPN1 and PPN2 proposals compared to ground truth.
The directories will be created if they do not exist yet. At training time all of them are required. At inference time only the display directory is required.Network architectures and weights optionsTrainingNetwork trainedCommand to runPretrained weights (optional)Base network UResNet`--base-net uresnet --net base-wb uresnet.ckptBase network VGG--base-net vgg --net base-wb vgg.ckptPPN (w/ UResNet base)--base-net uresnet --net ppn-wp ppn.ckptSmall UResNet--base-net uresnet --net small_uresnet-ws small_uresnet.ckptInferenceUse the commandppn demo -d display/dir -m N_inferencesfollowed by:NetworkCommandline optionsWeights loadingBase (UResNet)--base-net uresnet --net base--wb uresnet.ckptPPN (w/ UResNet base)--base-net uresnet --net ppn--wp ppn.ckptSmall UResNet--base-net uresnet --net small_uresnet--ws model.ckptPPN + UResNet--base-net uresnet --net full--wb uresnet.ckpt --wp ppn.ckptPPN + Small UResNet--base-net uresnet --net ppn_ext--wp ppn.ckpt --ws small_uresnet.ckptMost common optionsOptionExplanation-mNumber of steps / images to run on--freezeFreeze base network layers during training.-NSize of the image-3d3D version-dataPath to data files, can use wildcards and bash syntax.More options such as thresholds are available throughppn train -handppn demo -hrespectively.ExamplesTo train PPN on 1000 steps use:ppntrain-ooutput/dir/-llog/dir/-ddisplay/dir--netppn-m1000--datapath/to/dataTo train the base network (currently VGG and UResNet available) on track/shower classification task use:ppntrain-ooutput/dir/-llog/dir/-ddisplay/dir--netbase--base-netvgg-m1000To train on 3D data, use the argument-3dand don't forget to specify the image size with-Nargument (e.g. 192 for a compression factor of 4, seelarcvdata_generator.pyfor more details).To train PPN with UResNet base network pretrained weights, while freezing the base (pre-trained) layers,
a more complete command line would beppn train -o output/dir/ -l log/dir/ -d display/dir --net ppn --base-net uresnet -wb /path/to/uresnet/weights --freeze -N 512 -m 100To run inference with a minimal score of 0.5 for predicted points:ppndemoweights_file.ckpt-ddisplay/dir/-ms0.5The display directory will contain snapshots of the results.AuthorsK.Terao, J.W. Park, L.Domine