Revision as of 16:53, 8 May 2017

introduction

Here is the information hub for the SoLID software for physics study.

Physics event generation is a collection of independent software packages.

Detector simulation is based on Geant4 based simulation framework GEMC http://gemc.jlab.org

The instruction for installation and how to use do event generation, simulation and reconstruction are listed below.

quick demo

This is the quickest way to run the simulation in graphic mode on jlab ifarm machine with the official installation. Use it to get a feeling how it works.

ssh -XY your_lab_username@ifarm          (login with Xwindow forwarding enabled)
xclock &                                 (test if Xwindow forwarding works)                                            
source /group/solid/solid_svn/set_solid        (setup env with official installation framework and official repo)
cd $SoLID_GEMC/script                      (enter the official repo script dir)
solid_gemc solid_SIDIS_He3_full.gcard          (two graphic windows should appear, one has control and one shows the detector)
solid_gemc solid_SIDIS_He3_full.gcard -USE_GUI=0 (batch mode, information shows in terminal)

If you have any problem or it runs very slow, go to SoLID_Software#on_ifarm

Installation

general instruction

We have a unified framework of installing GEMC and all their dependences

all SoLID software based on the framework is in SoLID repository

You need both the framework and SoLID repository to use the software

• installation of framework
  • The framework use environmental variable JLAB_ROOT to control installation path and JLAB_VERSION to control version
  • See detailed instruction for installation of framework
• installation of SoLID repository
  • SoLID repository is in SVN, everyone has read right, only jlab account within "solid" group can write
  • checkout by "svn co https://jlabsvn.jlab.org/svnroot/solid solid_svn"
  • access its WebSVN interface at https://jlabsvn.jlab.org/solid
  • two ways to get auto notification about any change to SVN, use a graphic SVN client ("kdesvn" is good) or use RSS feed on the Websvn interface
  • it directory structure
    • "evgen", some event generators, (the others are in other repositories, see event generation section for details)
    • "solid_gemc", GEMC 1.x related files for SoLID simulation
    • "solid_gemc2", GEMC 2.x related files for SoLID simulation
    • "subsystem" for individual subsystems
    • "study" for studies involving different subsystems

default version and official location

The default framework version is JLAB_VERSION=1.3 (as in 2017/05)

The default system for the default framework is CentOS7.2.1511-x86_64 on ifarm.jlab.org (alias to ifarm1401 and ifarm1402) (as in 2017/05)

(The framework was tested on many platforms, but for our use, it's only fully tested on current jlab ifarm system.)

The official framework installation on jlab ifarm and jlab internal computers is at /group/solid/apps/jlab_root (as in 2017/05)

The official SoLID repository checkout is at /group/solid/solid_svn (as in 2017/05)

(You should have your own checkout if you want to make any changes)

step by step guide

This is a step by step guide to setup and run simulation etc.

make sure you meet the requirement before you do anything

requirement

Do following before installing, updating and running the code no matter what machine you are using

• check "echo $SHELL" to check if you are using tcsh shell. If it's not your default shell after login, first open a clean terminal and run "tcsh"

• clean your env variables. For example, remove your environment variable setup in your login script like .cshrc and .login or disable them temporally by "mv .cshrc cshrc" and "mv .login login". This is to avoid conflict from other software environment variables. Vice versa, don't put our environment variables into your login script either, set it up every time you login a terminal instead

on ifarm

tested on ifarm (alias to ifarm1401 and ifarm1402) with CentOS7.2.1511-x86_64 (as of 2017/05)

This allow users to run it from anywhere and test code before submitting jobs to jlab farm. You don't need to install the framework and you can choose to use official repo or your own repo.

(additional requirement for graphic mode)
If you want to run it on ifarm in graphic mode, see help at [graphic mode on ifarm] first. 
If you want to run it on ifarm in batch mode without graphic, simply ssh into ifarm, then go to next step
if you can't ssh into ifarm, ask jlab computer center help@jlab.org to allow your account access ifarm

(use official installation of framework with official repo which you can't modify)
source /group/solid/solid_svn/set_solid        

(use official installation of framework with your repo so that you can make changes) 
cd your_choice_of_solid_repo_path
svn co https://jlabsvn.jlab.org/svnroot/solid solid_svn  (checkout the repo)
cd solid_svn
cp set_solid set_solid_mine                         (create your copy of env script)    
edit set_solid_mine by following the instruction within, you only need to change $SoLID_GEMC
source set_solid_mine  (setup env with your repo)
cd $SoLID_GEMC/source/$GEMC_VERSION    (enter the source dir for solid_gemc)
scons OPT=1                          (compile solid_gemc) 
source set_solid_mine                  (optional step if solid_gemc can't be found in default PATH. if it does work for the first time, try it in a clean terminal)

(now you can run it)
cd $SoLID_GEMC/script                        (enter the script dir) 
solid_gemc solid_SIDIS_He3_full.gcard            (graphic mode, one windows has control and the other shows the detector)
solid_gemc solid_SIDIS_He3_full.gcard -USE_GUI=0 (batch mode, information shows in terminal)

on jlab internal machine

supported pre-compiled framework on jlab internal machine (RHEL6.9_x86_64) (as of 2017/05)

If your machine is on jlab internal network, you can use the pre-compiled framework shared over jlab network.

more /etc/redhat-release       (check if your machine is supported, otherwise you need to change or update to the support system)
                               
ls /group/solid/apps/jlab_root (check if you can access the pre-compiled framework)
(if you don't have access, you have two choices
   1. ask jlab computer center help@jlab.org to add it for your machine 
   2. use sshfs 
      su -l
      mkdir /group
      chmod your_jlab_username.your_jlab_group /group
      exit
      sshfs -o workaround=all ifarm1402:/u/group /group
 )     

(use official installation of framework with your repo so that you can make changes) 
cd your_choice_of_solid_repo_path
svn co https://jlabsvn.jlab.org/svnroot/solid solid_svn  (checkout the repo)
cd solid_svn
cp set_solid set_solid_mine                         (create your copy of env script)    
edit set_solid_mine by following the instruction within, you only need to change SoLID_GEMC
source set_solid_mine  (setup env with your repo)
cd $SoLID_GEMC/source/$GEMC_VERSION    (enter the source dir for solid_gemc)
scons OPT=1                          (compile solid_gemc) 
source set_solid_mine                  (optional step if solid_gemc can't be found in default PATH. if it does work for the first time, try it in a clean terminal)

(now you can run it)
cd $SoLID_GEMC/script                        (enter the script dir) 
solid_gemc solid_SIDIS_He3_full.gcard            (graphic mode, one windows has control and the other shows the detector)
solid_gemc solid_SIDIS_He3_full.gcard -USE_GUI=0 (batch mode, information shows in terminal)

If you have any problem running official installation of framework, double check if your system is supported. It could be some needed packages were not installed on your local machine and you need to install them as root. refer to "prepare for installation" at [1]

If you have any problem running official installation of framework, go to SoLID_Software#on_any_machine

on any machine

This gives you maximum freedom to use your installation of framework and your repo

install the default version of framework by following installation instruction
cd your_choice_of_solid_repo_path
svn co https://jlabsvn.jlab.org/svnroot/solid solid_svn  (checkout the repo)
cd solid_svn
cp set_solid set_solid_mine                         (create your copy of env script)    
edit set_solid_mine by following the instruction within, you need to change SoLID_GEMC and JLAB_ROOT
source set_solid_mine  (setup env with your repo)
Check if the version you installed need these fixes by following Jlab_software_tmp_fix
cd $SoLID_GEMC/source/$GEMC_VERSION    (enter the source dir for solid_gemc)
scons OPT=1                          (compile solid_gemc) 
source set_solid_mine                  (optional step if solid_gemc can't be found in default PATH. if it does work for the first time, try it in a clean terminal)

(now you can run it)
cd $SoLID_GEMC/script                        (enter the script dir) 
solid_gemc solid_SIDIS_He3_full.gcard            (graphic mode, one windows has control and the other shows the detector)
solid_gemc solid_SIDIS_He3_full.gcard -USE_GUI=0 (batch mode, information shows in terminal)

Coordinate System

SoLID uses the coordinate system below in lab frame for event generator output, detector arrangement and reconstruction

electron beam goes along +z axis and at x=0,y=0
The solenoid coil center at the origin (x=0,y=0,z=0),axis along electron beam
y axis is vertical and +y pointing up relative to the ground
x axis is horizontal and +x pointing left when riding the electron beam
+x axis has phi angle 0 deg,  +y axis has phi angle 90 deg
phi angle coverage is from -180 to 180 which can be obtain by atan2(y,x)*180/Pi or TVector3.Phi()*180/Pi

Physics Event Generation

Detector Simulation

Event Reconstruction

Study

Info

emaillist

• mailing list solid_software@jlab.org (registration and archive)

linux group

SoLID Linux group is "12gev_solid"

check your account groups by command "groups username" or "id username"

Please ask Ole <ole at jlab.org> to add your jlab account to the group if you want to use SoLID related computing resource at jlab.

Batch Farm Project

jobs should go to the 'solid' project

Disk Space

We have disk space on the CUE

The cache and volatile files there are expected to have an expiration date of six months. Please use /volatile for larger data sets and /work for sources and reduced datasets you need to keep. You must belong to the group 12gev_solid for access, ask "Ole at jlab.org" to add you.

To avoid disk quota problems, please make sure that all files that you place in the SoLID directories are owned by Linux group 12gev_solid. If you've already created files that have the wrong group, just change the group ID of your directory and all its files and subdirectories to the correct one. You only should have to do this once:

chgrp -R 12gev_solid your-directory

To make this happen automatically for all newly created files in this directory, set the sgid bit on it:

chmod g+s your-directory

Better yet, set this bit for all subdirectories as well:

find your-directory -type d -exec chmod g+s {} \;

Again, you should only have to do this once.

Additionally, to reduce the chance of file access problems, every time you log in and before starting work in SoLID disk areas, switch your effective group ID to 12gev_solid:

newgrp 12gev_solid

Exit from the shell when done; that will return you to where you were before issuing the newgrp command.

old simulation software (for record keeping only, don't use it!)

• SoLID GEMC (simulation in GEANT4 with GEMC 1.x, used for later proposals and pCDR)

• SoLID Comgeant (simulation in GEANT3 used for the early proposals)