This repository contains the code for developing a full 3D neutrino interaction reconstruction centered using outputs of a convolutional neural network.

The convolutional neural network aims to provide information that seeds the reconstruction of particles and interactions. This includes:

• good 3D space points representing the locations where charge particle tracks passed through the detector
• associations between the 3D space points and the spatial patterns in the TPC images where the points project into.
• scores indicating which 3D points are near important, key-points: track ends, shower starts, and neutrino interaction vertices.

Documentation for the library can be found at github.io/larflow.

• larmatchnet: definition of network, scripts to train and deploy network
• larflow: c++ libraries providing methods to prepare data, perform downstream reconstruction

Within the larflow folder, are the following c++ modules:

• PrepFlowMatchData: classes/methods for preparing spacepoint data from TPC images
• KeyPoints: classes/methods for preparing keypoint training info using spacepoint data from PrepFlowMatchData
• SpatialEmbed: classes/methods for preparing spatial embedding training info using spacepoint data from PrepFlowMatchData
• Reco: downstream reconstruction using output of networks to form candidate neutrino interactions
• CRTMatch: tools to combine CRT data with spacepoints and TPC data in order to provide tagged cosmic muon tracks
• Voxelizer: voxelize larmatch spacepoints, not finished. intended to help spacepoint output connect to 3D convolutional networks.
• LArFlowConstants: constants, enumerations used in the other modules
• FlowContourMatch:deprecated tools

Other folders are considered deprecated and need to be cleaned up and archived.

• testdata: default location for testdata used for development
• utils: utility scripts
• container: script to build Singularity container that will work on tufts grid

deprecated folders, kept for archival reasons

• deprecated/old_larflownet_models: different version of LArFlow models
• deprecated/old_larflownet_dataprep: scripts to make larflow input and truth images from larsoft files and then prepare crops for training
• deprecated/old_larflownet_training: training scripts
• deprecated/old_larflownet_deploy: take trained models and process test files
• deprecated/old_larflownet_ana: analysis scripts for processed test files
• deprecated/old_larflownet_weights: default location for weights
• deprecated/postprocessor: old code that used old larflow 3d points for reco

• clustering via spatial embed method [Jared]
• clustering via part affinity flows [Taritree]
• extend keypoints to be more than one class [Polina]
• develop interactoin selection
• develop analysis metrics [Ralitsa]

• ROOT (6.12/04 known to work)
• opencv (3.2.0 known to work)
• pytorch (1.3, 1.4 known to work)
• numpy (1.14.03 known to work)
• tensorboardX (from here)
• tensorboard
• cuda (currently using 10.1)
• Eigen 3

UBDL dependencies

• larlite: following X branch
• Geo2D:
• LArOpenCV:
• larcv:
• ublarcvapp:
• cilantros:
• nlohmann/json
• (to do: add missing)

• larcvdataset: wrapper class providing interface to images stored in the larcv format. converts data into numpy arrays for use in pytorch (deprecated)
• Cilantro: a library with various Clustering routines w/ C++ API (deprecated)
• Pangolin: a OpenGL viewer package, used by Cilantro (deprecated)

• This repository is intended to be build as a part of the ubdl environment. Go here to see this repo.
• clone ubdl: git clone https://github.com/larbys/ubdl
• go to the ubdl folder
• setup the ubdl environment pre-reqs: source setenv.sh
• configure the ubdl submodule environments: source configure.sh
• build all the submodules: source buildall_py2.sh

Pangolin depends on GLEW and X11. These can be provided by a package manager. However, especially for GLEW other versions can be on the system from other libraries like CUDA and/or ROOT. This can cause compilation errors.

If there are issues you can try the following:

• go into CMakeCache.txt and check the include and library entries for GLEW (search for GLEW). Change them to point to the system GLEW. On Ubuntu this will be something like:

  /usr/lib/x86_64-linux-gnu/libGLEW.so for the LIB dir and /usr/include for the INC dir
  

  If you do this, remove the directory CMakeFiles and run make clean. Then run cmake . and finally make.

• go into Pangolin/include/pangolin/gl/glplatform.h and change <GL/glew.h> to /usr/include/GL/glew.h to hack it to not rely on the include directories passed to the compiler. Note: the above path is for Ubuntu 16.04/18.4.

• setup the environment through ubdl
• go to ubdl folder (which should contain this repo as a submodule)
• source setenv.sh
• source configure.sh

If you made changes to a submodule, you need to check in that code and then check in the new commit hash of the submodule to this repo.

Say you made a change to larcv. (Same instructions basically for all submodules).

• First make sure you are not in a DEATCHED_HEAD state)

  git branch
    develop
  

  * tufts_ub

• If it says detached head, go back to head of larflow repo and run source goto_head_of_submodules.sh and come back

• stage your commits and then push

  git add [[some file you edited]]
  git commit -m "[[short description of change]]"
  git push
  

• go back to head of larflow and commit the updated submodule (in this example larcv) to this repo cd .. git add larcv git commit -m "[[which submodule you updated]]" git push