WCSim is a very flexible GEANT4 based program for developing and simulating large water Cherenkov detectors.
As of August 2014 WCSim has been moved to GitHub. It can be found at:
https://github.com/WCSim/WCSim
Tutorials and information about the branches and WCSim development model can be found on the wiki:
https://github.com/WCSim/WCSim/wiki
WCSim has very few external dependencies. It relies on only ROOT and Geant4.
There is a mailing list which will send you GitHub push/checkin notifications here:
https://lists.phy.duke.edu/mailman/listinfo/wcsim-git
You can follow issues/requests etc by watching the GitHub respository.
WCSim uses GitHub Actions CI to perform build and physics tests for each pull request and commit. The scripts it runs can be found at https://github.com/WCSim/Validation
The output can be found at: https://wcsim.github.io/Validation/
More detailed information about the simulation is available in
doc/DetectorDocumentation.pdf
Additionally, doxygen documentation is available at https://wcsim.github.io/WCSim/annotated.html Note that most of the code has no doxygen comments, but all output class member variables are documented. See the WCSimRoot* classes
doxygen documentation can be built locally by running
cd $WCSIMDIR/ && doxygen WCSim_doxygen_config
For admin: A more featured doxygen build can be done & pushed using an alternative doxygen config file (requires dot
from graphviz
)
git clone -b gh-pages --single-branch [email protected]:WCSim/WCSim.git WCSim-dox
cd WCSim-dox
./get_dox.sh
You can also make this featured version locally by
cd $WCSIMDIR
git clone -b gh-pages --single-branch [email protected]:WCSim/WCSim.git WCSim-dox
doxygen WCSim-dox/WCSim_doxygen_config
- The environment variable
$WCSIMDIR
should be defined as your WCSim code directory (not the build one).
export WCSIMDIR=`pwd`
The automated building testing is currently performed inside the hk-software docker container with the prerequisites:
- Geant4 10.3.3
- ROOT 6.26/04
- gcc 8.5.0
- cmake 3.20.2
And as such this is the most supported version of the software (it is guaranteed to work)
Other versions of prerequisite software can be tried, but aren't guaranteed to work.
- Geant 4.10.03p3
- If using a newer version of Geant, it is your responsiblity to assess whether Geant physics changes are significant, relative to the officially supported 4.10.03p3
- All of the G4 data files are also required to be installed, include hadron xsec, etc.
- ROOT
- ROOT5 (e.g. v5r34p36 or v5r34p38, or potentially any v5r34) can potentially be made to work. You may need to modify
$WCSIM_BUILD_DIR/src/cmake_install.cmake
to take account of ROOT5 not producing.pcm
files - ROOT6 has been tested on an older version than above (6.20/04)
- ROOT5 (e.g. v5r34p36 or v5r34p38, or potentially any v5r34) can potentially be made to work. You may need to modify
- cmake 3.1 and above are required by
CMakeLists.txt
, but not all old versions have been tested - The compiler should support
-std=c++11
(or-std=c++0x
) e.g. gcc 4.8.5- You may need to modify
CMakeLists.txt
to change theCMAKE_CXX_STANDARD
to another version (e.g. from 14 to 17). I think this is dependent on what your prerequisties have been compiled with
- You may need to modify
CMake is cross-platform software for managing the build process in a compiler-independent way (cmake.org). It is required to build ROOT and GEANT4 also through CMake. Cmake 3.1+ is required. Using cmake, builds and source code need to well separated and make it easier to build many versions of the same software.
A recommended way to set up the directory structure in your own
preferred WCSIM_HOME
:
${WCSIM_HOME}/WCSim
: contains the src dir, typically the cloned or unzipped code from GitHub${WCSIM_HOME}/WCSim_build
: contains directories for each build, eg. for each branch you want to test or for different releases, comparing debugged versions, etc. Each subdirectory likeWCSim_dev
orWCSim_v1.2
would contain the intermediate files produced during compilation and not the finale ones${WCSIM_HOME}/WCSim_install
: contains directories for each build, eg. for each branch you want to test or for different releases, comparing debugged versions, etc. Each subdirectory likeWCSim_dev
orWCSim_v1.2
will contain the final executable and libraries, the example macros and library for ROOT.
To compile you need to have CMakeLists.txt
in the WCSim source dir.
mkdir -p ${WCSIM_HOME}/WCSim_build/mydir ; cd ${WCSIM_HOME}/WCSim_build/mydir
- Set up the environment variables
#WCSim things export WCSIMDIR=/${WCSIM_HOME}/WCSim export G4WORKDIR=$WCSIMDIR/exe #Geant4 things export G4INSTALLDIR=/path/to/geant4/install/dir/ source $G4INSTALLDIR/bin/geant4.sh source $G4INSTALLDIR/share/Geant4-10.3.3/geant4make/geant4make.sh
cmake3 ../../WCSim
: this executes the commands inCMakeLists.txt
and generates the Makefiles for both the ROOT library as the main executable.- For some OS,
cmake3
is justcmake
- For some OS,
make clean
: if necessarymake -j3 install
: will first compile the libWCSimRoot.so and libWCSimCore.so which you need for using the ROOT Dict from WCSim (e.g. to read the output files) and then compile WCSim.source bin/this_wcsim.sh
: will setup the environment variables such that you can run WCSim
To recompile:
- Typically just
make install
will be enough and also redo the cmake phase if something changed. - Sometimes you need to
make clean
first. - When there are problems, try removing
CMakeCache.txt
, and redo the cmake.
Useful cmake commands:
make edit_cache
: customize the build.make rebuild_cache
: redo the cmake phase.
-DWCSim_Geometry_Overlaps_CHECK=<ON|OFF>
If ON, turns on geometry overlap checking (slow, but important when setting new detector geometry options). Default: OFF-DWCSim_DEBUG_COMPILE_FLAG=<ON|OFF>
If ON, turns on the gcc debug compiler flag-g
. Default: OFF-DWCSIM_SAVE_PHOTON_HISTORY_FLAG=<ON|OFF>
If ON, turns on photon scattering/reflection history saving. The data classWCSimRootCherenkovHitHistory
is used in a similar way asWCSimRootCherenkovHitTime
. Default: OFF
A script allowing to build WCSim with CMake on sukap is available:
cd $WCSIMDIR
./setup/env_sukap.sh
./make.sh
Note that ./make.sh
should also work on other systems.
This script will read the current WCSim directory name and create a directory to hold the different cmake builds.
For example, in case your current WCSim directory name is 'WCSim', it will create a '../WCSim-build' directory. It will also create a ../WCSim-install
directory.
It will then create a directory for your current branch which will have the name of the current branch.
For example, in case your current branch name is hybridPMT
, you will have:
WCSim/
WCSim-build/
WCSim-build/hybridPMT/
WCSim-install/
WCSim-install/hybridPMT/
Note that by defaul, just make install
is run.
You can run make clean
before make install
by running ./make.sh clean
`GNUmakefile`` is specifically only for use with ROOT5 and is not supported otherwise. All output that needs to be trusted must use cmake. To compile:
make clean_wcsim
make rootcint
make
Docker allows you to use WCSim without compiling in an OS independant way. The Docker images are hosted on DockerHub and can be used by following the steps below.
- Install Docker cross platform instructions can be found at https://www.docker.com/
- Pull the WCSim image from docker hub by using
docker pull wcsim/wcsim:tag
wheretag
is the tagged version or use the taglatest
to get the current develop branch - Run the docker image and create a container
docker run --name=WCSim -i -t wcsim/wcsim:tag
this will give you a shell in the container's OS with WCSim already built. To save data from inside your docker image mount a local folder in the docker image at runtime and then anything placed in that directory will be available in that folder after exit. To do that run the followingdocker run -v local_folder_path:docker_mount_path -i -t wcsim/wcsim:tag
- Once you have run the docker image, you will already be in
$WCSIMDIR
and WCSim (and prerequisites) will be setup. Therefore, you can just start running WCSim as normal from this directory - To exit the docker image
exit
(Note: You only need to use the docker run
command once to create the container. Once created you changes are saved in that container instance and you can start and stop the container at any time with docker start WCSim
and docker stop WCSim
);
Extra docker commands:
- See all images
docker images
- Delete an image
docker rmi imageID
- See all containers
docker ps -a
- Delete a container
docker rm ContainerID
Note that this method currently uses make (not cmake) to build
Singularity is a similar container tool with different philosphies. The most important being that you can't run as root. This means that it may be installed and available to use on your local cluster.
You should be able to run the docker container with singularity without any problems. Just to note that $WCSIMDIR
will be read-only, therefore you should run WCSim elsewhere (if you forget you'll see a nasty seg fault - this is just because of the read-only directory).
Note that this method currently uses make (not cmake) to build
To test that WCSim is working, try running the test macro WCSim.mac
, which runs 10 electrons with 5 MeV of energy in the Super-Kamiokande detector (it should take less than a minute to run).
cd /path/to/wcsim/build/dir/
./WCSim WCSim.mac macros/tuning_parameters.mac
WCSim.mac
is well commented. Take a look inside (and also at other .mac
files in /macros/
) for the various options you can use to run WCSim
There are a few example scripts inside sample-root-scripts/
sample_readfile.C
is a general script that allows you to see (most) event-level variables- For the hybrid geometry, see
AnalyzeWSHierarchy.c
- Compile it using the
Makefile
insample-root-scripts/
(i.e. runmake
from that folder) - Execute it using
Analyzer.sh
insample-root-scripts/
(i.e. run./Analyzer.sh
from that folder)
- Compile it using the
- gamma = green
- neutrino = yellow
- electron = blue
- positron = red
- muon = white
- muon+ = silver
- proton = magenta
- neutron = cyan
WCSim development is supported by the United States National Science Foundation.