make macros all pretty for public consumption

beam.mac

+# This macro contains commands for photon emission and distribution.
+
+
 #----- Set the beam energy profile -----
 /gps/particle opticalphoton
 /gps/ene/type Gauss
@@ -9,36 +12,71 @@
 /gps/polarization 0 0 0
 
 
-
 #----- Set the beam geometry -----
-# Circular beam source. Simulates a single fiber optic
+# Circular beam source. Simulates a single fiber optic.
 #/gps/pos/type Beam
 #/gps/pos/shape Circle
 #/gps/pos/radius 0.75 mm
 #/gps/pos/radius 1.5 mm
 #/gps/pos/sigma_r 0.002 mm
 
-# Rectangular plane for infinite resolution
+# Rectangular plane source. Simulates infinite resolution.
 /gps/pos/type Plane
 /gps/pos/shape Rectangle
 /gps/pos/halfx 40 mm
 /gps/pos/halfy 68 mm
 
-# the incident surface is in the x-z plane just below the gas
+# Identify incident surface plane. Preset is in the x-z plane just below the origin.
 /gps/pos/rot1 1 0 0
 /gps/pos/rot2 0 0 1
 /gps/pos/centre 0. -0.1 0. mm
 
-# the photons are emitted around the y-axis
+# Identify photon emission axis. Preset to photons emitting around/in the positive y direction.
 /gps/ang/rot1 1 0 0
 /gps/ang/rot2 0 0 1
 /gps/ang/type beam1d
 
 #----- Set beam angular dispersion from histogram -----
+# Set to 'true' to use beam angular dispersion from hist.mac file, a cherenkov light distribution. 
 /gps/ang/surfnorm false
 /gps/ang/type user
 /control/execute hist.mac
 
-#----- Set beam angular dispersion for fiber optic -----
-# N.A. is 0.22 so acceptance cone is ~25.4 degrees
-#/gps/ang/sigma_r 25.40 deg
+#----- Set beam angular dispersion not from histogram -----
+# Defaults to straight light unless specified otherwise.
+# Sample commands are included below. More angular distribution commands
+# and instructions for use can be found in GPS manual section 2.7.3.4.
+#/gps/ang/sigma_r 15 deg
+#/gps/ang/maxtheta 5 deg
+
+#----- Set multiple light sources -----
+# Setting multiple light sources can be achieved as follows:
+# Comment out all of the above code
+# Fill in block below with desired parameters
+# Repeat the entire block for each additional source
+
+# #individual source
+# /gps/source/multiplevertex true
+# /gps/source/add 1
+# /gps/particle opticalphoton
+# /gps/ene/type Gauss
+# /gps/ene/mono 4.75 eV
+# /gps/ene/sigma 10 eV
+# /gps/ene/min 1.9 eV
+# /gps/ene/max 7.6 eV
+# /gps/ene/gradient -200 MeV
+# /gps/polarization 0 0 0
+# /gps/pos/rot1 1 0 0
+# /gps/pos/rot2 0 0 1
+# /gps/ang/rot1 1 0 0
+# /gps/ang/rot2 0 0 1
+# /gps/ang/type beam1d
+# /gps/ang/surfnorm false
+# /gps/ang/type user
+# /control/execute hist.mac
+# --- source placement and shape
+# /gps/pos/type Plane
+# /gps/pos/shape Circle
+# /gps/pos/radius 0.75 mm
+# /gps/pos/centre -22 -0.1 -3 mm #x, y, z coords of source center
+

geometry.mac

+# This macro is where you specifiy a CAD model, set material properties, 
+# and adjust palcement of CAD model (light guide) and photon sensor (PMT)
 
+
+# ----- Set world size. Must be large enough to contain CAD model. -----
 /lightGuide/worldVolume 0.25 0.25 0.25 m
 /lightGuide/envelope 89.75 113. 165. mm
 
-/lightGuide/model/PMTDiameter 53 mm
+# ----- Set PMT size -----
+# Default PMT window is circular
+/lightGuide/model/PMTDiameter 50 mm
 /lightGuide/model/nSegmentsX 1
 /lightGuide/model/nSegmentsZ 1
 
 
 
 #----- Set the light guide to be used and position it -----
-#If no model is selected, the program will default to a
-#simplified version of the 2018 testbeam light guide
+# If no model is selected, the program will default to a
+# simplified version of the 2018 testbeam light guide.
+# The four example models listed below are found in the 'models' folder
 
 /lightGuide/model/CADmodel ../models/run2.stl
 /lightGuide/model/translate 200 -125 0 mm

hist.mac

+# Angular beam dispersion information for a cherenkov light dispersion. 
+# Based on JZCAPA simualtions of cherenkov light generated in the activer area of the ZDC,
+# and then transmitted through fused silica rods. This distribution accounts for total interal reflection
+# inside the fibers. Produced by Shir Shenkar.
+
+# This file can be altered to contain any simualted or manually set angular distribution information. 
+# Further information for user defined histograms can be found in section 2.7.2.5 of the GPS user manual,
+# found at https://www.fe.infn.it/u/paterno/Geant4_tutorial/slides_further/GPS/GPS_manual.pdf.
+
+
 /gps/hist/type theta
 #/gps/hist/point -0.007400 0.000000
 /gps/hist/point 0.000000 0.000059

run1.mac

-# Macro file for lightGuide
-#
-# To be run preferably in batch, without graphics:
+# This macro contains the run file for running the simulation in batch mode.
 
 # Initialize kernel
 /run/initialize
 
-
+# ----- Graphics -----
+# Default is 0, for running is batch mode without visualizer
+# To run in GUI with graphics, verbosity can be adjusted to 1.
 /control/verbose 0
 /run/verbose 0
 /run/printProgress 0
@@ -23,7 +23,7 @@
 
 #Uncomment to use gps style of setting the beam profile
 /control/execute beam.mac
-# number of events
+# number of events (aka number of photons simulated)
 /run/beamOn 100
 ##############################################################
 ##############################################################

vis.mac

+# This macro contains setting for the visualizer (GUI).
+# You probably won't have any reason to alter this one.
+
 # Use this open statement to create an OpenGL view:
 /vis/open OGL 600x600-0+0
 #