Merge pull request #357 from JeffersonLab/develop

Merge develop into v2.3.x series

.gitignore

@@ -74,3 +74,11 @@ sample_gdml.*
 #ignore log files
 *.log
 callgrind.*
+
+# jekyll
+_site
+.sass-cache
+.jekyll-cache
+.jekyll-metadata
+vendor
+Gemfile.lock

CMakeLists.txt

@@ -305,7 +305,10 @@ set(REMOLL_LOCATION /group/halla/www/hallaweb/html/12GeV/Moller/downloads/remoll
 set(REMOLL_DOWNLOADS http://hallaweb.jlab.org/12GeV/Moller/downloads/remoll/)
 set(REMOLL_MAP_DIR ${PROJECT_SOURCE_DIR}/map_directory)
 if(EXISTS ${REMOLL_LOCATION})
+  message(STATUS "Copying files directly from directory...")
   set(REMOLL_DOWNLOADS file://${REMOLL_LOCATION})
+else()
+  message(STATUS "Fieldmaps will be downloaded from web...")
 endif()
 file(DOWNLOAD
      ${REMOLL_DOWNLOADS}/hybridJLAB.txt
@@ -318,23 +321,39 @@ file(DOWNLOAD
      EXPECTED_MD5 af06ed35516c17640e89ba3aa0f5b200
      )
 file(DOWNLOAD
-     ${REMOLL_DOWNLOADS}/blockyUpstream_rm_1.1.txt
-     ${REMOLL_MAP_DIR}/blockyUpstream_rm_1.1.txt
-     EXPECTED_MD5 3e2338e1ba74b03da37545e98931f5f3
+     ${REMOLL_DOWNLOADS}/hybridJLAB_v2.txt
+     ${REMOLL_MAP_DIR}/hybridJLAB_v2.txt
+     EXPECTED_MD5 4a0d1abc9b80cf5f2c3dd495a1133e26
      )
 file(DOWNLOAD
-     ${REMOLL_DOWNLOADS}/blockyHybrid_rm_3.0.txt
-     ${REMOLL_MAP_DIR}/blockyHybrid_rm_3.0.txt
-     EXPECTED_MD5 b4bfef8f362e0df66f166b4e76a6847e
+     ${REMOLL_DOWNLOADS}/segmentedJLAB_v2.txt
+     ${REMOLL_MAP_DIR}/segmentedJLAB_v2.txt
+     EXPECTED_MD5 2a21b540f6496e3f554302f369646bbb
+     )
+file(DOWNLOAD
+     ${REMOLL_DOWNLOADS}/upstreamJLAB_v2.txt
+     ${REMOLL_MAP_DIR}/upstreamJLAB_v2.txt
+     EXPECTED_MD5 bed73f2ea44135c52222bc8e767e1954
      )
 install(FILES
      ${REMOLL_MAP_DIR}/hybridJLAB.txt
      ${REMOLL_MAP_DIR}/upstreamJLAB_1.25.txt
-     ${REMOLL_MAP_DIR}/blockyHybrid_rm_3.0.txt
-     ${REMOLL_MAP_DIR}/blockyUpstream_rm_1.1.txt
+     ${REMOLL_MAP_DIR}/hybridJLAB_v2.txt
+     ${REMOLL_MAP_DIR}/segmentedJLAB_v2.txt
+     ${REMOLL_MAP_DIR}/upstreamJLAB_v2.txt
      DESTINATION ${CMAKE_INSTALL_DATADIR}/remoll)
 if(ADDITIONAL_FIELDS)
   message(STATUS "Ensuring additional fields are available")
+  file(DOWNLOAD
+     ${REMOLL_DOWNLOADS}/blockyUpstream_rm_1.1.txt
+     ${REMOLL_MAP_DIR}/blockyUpstream_rm_1.1.txt
+     EXPECTED_MD5 3e2338e1ba74b03da37545e98931f5f3
+     )
+  file(DOWNLOAD
+     ${REMOLL_DOWNLOADS}/blockyHybrid_rm_3.0.txt
+     ${REMOLL_MAP_DIR}/blockyHybrid_rm_3.0.txt
+     EXPECTED_MD5 b4bfef8f362e0df66f166b4e76a6847e
+     )
   file(DOWNLOAD
      ${REMOLL_DOWNLOADS}/upstreamSymmetric_sensR_0.1.txt
      ${REMOLL_MAP_DIR}/upstreamSymmetric_sensR_0.1.txt
@@ -346,6 +365,8 @@ if(ADDITIONAL_FIELDS)
      EXPECTED_MD5 78fad2ffa5b5ae129df11bdf0ce25333
      )
   install(FILES
+     ${REMOLL_MAP_DIR}/blockyHybrid_rm_3.0.txt
+     ${REMOLL_MAP_DIR}/blockyUpstream_rm_1.1.txt
      ${REMOLL_MAP_DIR}/upstreamSymmetric_sensR_0.1.txt
      ${REMOLL_MAP_DIR}/hybridSymmetric_sensR_0.1.txt
      DESTINATION ${CMAKE_INSTALL_DATADIR}/remoll)

Gemfile

@@ -0,0 +1,5 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+gem "github-pages", group: :jekyll_plugins

README.Compiling.md

@@ -0,0 +1,51 @@
+# Compiling the code
+
+## Requirements
+
+* git
+* cmake > 3.5
+* Geant4 >= 4.10.00 (>= 4.10.06 recommended)
+* ROOT >= 6.0.0
+* python
+* boost (optional)
+
+## Quickstart screencast
+
+[![asciicast](https://asciinema.org/a/220728.svg)](https://asciinema.org/a/220728)
+
+## Downloading the source code
+
+To download the code, either download the source code for a recent [release](https://github.com/JeffersonLab/remoll/releases) or use git to clone this source code repository:
+```
+git clone https://github.com/JeffersonLab/remoll
+```
+You can optionally specify a directory name to clone into:
+```
+git clone https://github.com/JeffersonLab/remoll directory_name
+```
+
+## Compilation
+
+To build, create the directory you would like to build in, say `build`:
+```
+mkdir build
+cd build
+cmake ..
+make
+make install
+```
+
+## Magnetic field maps
+
+Magnetic field maps are required to run the simluations and will be downloaded automatically during the cmake step above. If for some reason you must download the field maps by hand, they are available for download on the [Hall A](http://hallaweb.jlab.org/12GeV/Moller/downloads/remoll/) page.
+
+## Running simulations with the compiled code
+
+You can run simulations from any location provided the following conditions are satisfied:
+- the `remoll` executable is in the PATH,
+- the `libremoll.so` library is in the LD_LIBRARY_PATH,
+- the graphical user interface and visualization macros are accessible from the current directory.
+
+If you are in the directory into which you cloned the source code repository, you can run the simulation as `build/remoll`.
+
+If you have run `make install` and `remoll` is now installed in a directory in your PATH, you can run the simulation in batch mode from any directory.

README.Contributing.md

@@ -0,0 +1,55 @@
+# Contributing to the repository
+
+If you participate in the development of simulations for the MOLLER experiment (code, geometry, macros, analysis), you are strongly encouraged to store your work in this repository so it is available for future use.
+
+The instructions below assume that you have cloned the repository.
+
+## Access permissions
+
+To contribute code to this repository, you must be added to the group of permitted users. Contact Rakitha Beminiwattha, Wouter Deconinck, Ciprian Gal, Paul King, or Kent Paschke.
+
+## Make changes in branches
+
+Before starting work make sure you have the latest changes from the remote repository:
+```
+git pull
+```
+
+Create a branch (see https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging for more details on branching) for the issue/improvement you are trying to add:
+```
+git checkout -b branch-name
+```
+You are now in new branch named "branch-name". Good names for branches are short and descriptive. Often they start with `bugfix-`, `feature-`, `enhancement-`, or a similar tag that allows to easily classify them.
+
+## Sharing branches with others
+
+If you want others to see your work make sure you setup tracking of this branch on the remote repository:
+```
+git push -u origin remote-branch-name
+```
+Note that the remote-branch-name can be different from the name you use on your local copy (i.e. the currently checked out branch). If remote-branch-name does not exist on the remote server yet then a new branch with that name will be created there (but not on your local copy), and your local branch will be set up to track this remote branch.
+
+## Adding and committing changes
+
+Modify any files you need to change. For any modified files, add and commit them:
+```
+git add folder/modified_file.hh
+git commit
+```
+Enter a descriptive commit message, starting with a short title line and expanding in the body of the message. Try to keep commits as small as reasonable.
+
+## Pushing commits to the repository
+
+At this point your code changes are tracked and committed on the local repository. To make changes available to others on a remote branch (can be the same as the name you use on your local copy):
+```
+git push -u origin remote-branch-name
+```
+or simply `git push` if you are already tracking a remote branch.
+
+## Submit pull request into the develop branch
+
+If, after sufficient testing, you think your changes merits inclusion in the main development branch, submit a pull request on the GitHub site.
+
+Enter a clear pull request description, and indicate what kind of testing you have completed. Tag a reviewer and wait until a maintainer merges the request into the `develop` branch. Do not merge the pull request into `develop` yourself without discussion with maintainers.
+
+Only submit pull requests for clear bug fixes against the `master` branch and do not merge these pull request into `master` yourself.

README.Docker.md

@@ -0,0 +1,29 @@
+# Docker container
+
+Simulations for the MOLLER experiment can be run using [Docker](https://www.docker.com/get-started) containers. Docker containers include a fully working simulation environment and all dependencies (Geant4, ROOT).
+
+The instructions below explicitly use the `develop` code branch. Every branch is available as a tag on Docker Hub.
+
+## Requirements
+
+- Docker service
+
+## Running
+
+You can use a pre-built image on [Docker Hub](https://hub.docker.com/r/jeffersonlab/remoll/).
+
+```
+docker run --rm \
+    -v `pwd`/output:/jlab/2.1/Linux_CentOS7.3.1611-x86_64-gcc4.8.5/remoll/rootfiles/ \
+    jeffersonlab/remoll [macro to run]
+```
+
+The ROOT files produced by remoll will be present in the output directory.
+
+## Building the Docker container locally
+
+You can build the Docker container directly from the Dockerfile in the git repository with:
+```
+docker build -t remoll .
+```
+Additional instructions are included at the top of the [Dockerfile](Dockerfile).

README.initialize.md → README.FAQ.md

@@ -1,4 +1,17 @@
-## When to run initialize?
+# FAQ
+
+We compile a list of frequently asked questions which will be integrated in the documentation at a future time.
+
+## 1. During compilation I encountered a problem related to a missing `gitinfo.hh` file
+
+In order to store the git revision information, we parse the git output when compiling the simulation. If you get errors about a missing `gitinfo.hh` file during compilation, it likely means that this file must be regenerated. Run the following commands in your `build` directory:
+```
+cmake ..
+make
+```
+If this does resolve the problem, delete your `build` directory and recompile the code.
+
+## 2. When should I use `/run/initialize`?
 
 There may be some confusion on when to run `/run/initialize`. Other simulations
 in Geant4 may not require you to run this command since all information is
@@ -19,7 +32,7 @@ specifying them on the command line, we hold off on running the initialization s
 so you can use
 ```
 /remoll/geometry/setfile geometry/mollerMother.gdml
-/remoll/parallel/setfile geometry/mollerParallel.gdml 
+/remoll/parallel/setfile geometry/mollerParallel.gdml
 ```
 before the initialization. If you don't run these commands, defaults are used.
 
@@ -28,6 +41,6 @@ photons or not), we hold off on running the initialization so you can enable or
 disable certain physics processes:
 ```
 /remoll/physlist/register QGSP_BERT_HP
-/remoll/physlist/parallel/enable 
-/remoll/physlist/optical/enable 
+/remoll/physlist/parallel/enable
+/remoll/physlist/optical/enable
 ```

README.Running.md

@@ -0,0 +1,42 @@
+# Running
+
+## Preparing to run simulations
+
+There are several options for running simulations:
+- [downloading and compiling the code](README.Compiling.md),
+- [using a docker container on any operating system](README.Docker.md),
+- [using a singularity container on linux systems](README.Singularity.md).
+
+Detailed information can be found at each of the links.
+
+## Running simulations
+
+### Interactive mode
+
+If you do not specify any arguments, the simulation will run in interactive mode. You will have access to a graphical user interface with menus and a 3D visualization of the geometry. This only works in locally compiled code or when using the singularity container.
+
+To start in interactive mode, just run the `remoll` executable without arguments:
+```
+remoll
+```
+
+To load and visualize the default geometry, use the following macro commands:
+```
+/control/execute vis/Qt.mac
+```
+Several other [visualization macros](vis/README.md) are available.
+
+### Batch mode
+
+If you specify arguments, the simulation will run in batch mode without graphical user interface. You can specify the following arguments:
+```
+Usage:
+ remoll [-g geometry] [-m macro] [-u session] [-r seed] [-t nthreads] [macro]
+```
+
+To execute the macro `macros/runexample.mac` with random seed 1234 and 4 threads, just run:
+```
+remoll -r 1234 -t 4 macros/runexample.mac
+```
+
+Several other [example macros](macros/README.md) are available.

README.Singularity.md

@@ -0,0 +1,33 @@
+# Singularity container
+
+Simulations for the MOLLER experiment can be run using [Singularity](https://sylabs.io/singularity/) containers on High Performance Computing (HPC) system.
+
+The instructions below explicitly use the `develop` code branch. Every branch is available as a pre-built Docker container on [Docker Hub](https://hub.docker.com/r/jeffersonlab/remoll/) which is used to build a local Singularity container, but only the `develop` and `master` branches are available as pre-built Singularity containers on CernVM-FS.
+
+## Requirements
+
+- Singularity >= 2.6.1
+
+On many HPC systems, the `singularity` command is either installed systemwide or available through environment modules (`module load singularity`).
+
+## Building a local Singularity container
+
+You can build a local Singularity container from the docker container with:
+```
+singularity pull docker://jeffersonlab/remoll:develop
+```
+This will create the file `jeffersonlab_remoll_develop.sif` (or similar) in your local directory.
+
+## Using the Singularity container on CernVM-FS
+
+You can use a singularity container hosted on the global CernVM-FS filesystem, courtesy of the Open Science Grid. This pre-built Singularity container is located at `/cvmfs/singularity.opensciencegrid.org/jeffersonlab/remoll:develop`. This is a directory, not a single file, but can be used instead of the file name below.
+
+## Running simulations with the Singularity container
+
+```
+singularity run jeffersonlab_remoll_develop.sif remoll -h
+```
+
+## Input and output locations
+
+In addition to the geometry and macros that are included in the Singularity container at `/jlab/remoll/`, you can also use any (user) directory in your local filesystem. By default the simulation will run in your current directory. In that directory,