Preparing simulation results

Results to be shared on the webtool first need to be preprocessed i.e the data and error values have to be converted into a format that is parseable by the backend scripts. At present, only USRBIN score results are supported. As a first step, please ask access to cmsradsi AFS account from an authorized BRIL member. Once access is granted, you can move a .bnn file you want to publish to cmsradsi 's www/data directory. The exact steps to perform, in order to make new results available on the webtool, are listed below:

• Make a new directory for your results under www/data e.g. like: mkdir my_sim

• Copy your .bnn file(s) into the newly created directory.

• Copy a geometry file relevant to your simulation (ends with .geo.dat) to the same directory and rename it to Geometry.dat.

• Add a description file to the directory whose content will be printed on the webtool along with the plots, providing information on the simulation to the user. A description file is a simple .txt file with a "key:value"-like structure, containing important parameters for the backend and the actual description that will be printed. The value of the parameters have to be adjusted manually based on the current simulation. In principle one can just copy a description.txt from another directory in www/data and then modify since they all have the same structure. A simple example is provided below which might as well serve as a template:

          do_rate_normalization:true
          global_factor:1 
          cross_section:80
          author:BRIL Rad Sim 
          tag:v.3.7.20.0
          detail_description:
          
          FLUKA simulation of CMS cavern.
          ----------------------------------------------------------
          Some description of the simulation goes here e.g. about geometry, cut-offs or anything that might be important. 
          Copy the whole into an empty file, adjust the parameter values if needed and save it as description.txt .
          

• Make a "config" file in the simulation folder. It must be a simple .txt file and its name must be identical to that of the simulation folder (e.g if the folder is called my_sim the config file must be named my_sim_config.txt). In this file, the scoring detectors for the particle types from the USRBIN .bnn file(s) must be listed manually, one by one, along with the binning information such as bin range, number of bins and bin width. Also, an indicative name has to be given to each. An example is given below, assuming a scoring for all particles in the central region (trackers and calorimeters) from my_usrbin_output_1.bnn and protons in the whole cavern from my_usrbin_output_2.bnn . A table of (generalized) particle IDs can be found in the official FLUKA manual.

        file:my_usrbin_output_1.bnn
        scoring:0
        name_of_scoring: All particles (central region)
        particle_type:201
        x_min:0.0
        x_max:303.0
        x_n_bins:303
        x_bin_width:1.0
        y_min:-3.14159274101
        y_max:3.14159274101
        y_n_bins:1
        y_bin_width:6.28318548203
        z_min:-680.0
        z_max:680.0
        z_n_bins:680
        z_bin_width:2.0 

        file:my_usrbin_output_2.bnn
        scoring:1
        name_of_scoring: Protons (full cavern)
        particle_type:1
        x_min:0.0
        x_max:1600.0
        x_n_bins:160
        x_bin_width:10.0
        y_min:-3.14159274101
        y_max:3.14159274101
        y_n_bins:1
        y_bin_width:6.28318548203
        z_min:-2750.0
        z_max:2750.0
        z_n_bins:550
        z_bin_width:10.0 
       

• Make sure that the only files present in the simulation folder my_sim are the .bnn file(s), Geometry.dat, description.txt and my_sim_config.txt. If so, execute www/pre-process/start.py to preprocess the data in the original .bnn file(s). You need to give the path to the simulation folder as an argument. E.g. if you are in the pre-process folder, call it by typing python start.py ../data/my_sim . This will extract the data and error tables of each detector from each .bnn into separate files, make a header.txt to each .bnn with information on the simulated primaries and number of batches (lxbatch split structure) and merge the config files into a single one (in case you created one separately for each .bnn).

• All generated files can now be copied to EOS which is used as a file storage for the webtool. First, make a directory in the EOS webtool folder by typing:

  mkdir /eos/cms/store/group/dpg_bril/comm_bril/www/webtooldata-staging/my_sim

• Copy the files from the simulation folder my_sim to EOS, as shown below (assuming that you are in my_sim directory at this point). Note that www/webtooldata-staging is the storage space for the webtool's test interface. Always copy files to here! The folder www/webtooldata is used for the release version and please do not copy anything there unless it is final, discussed and approved by BRIL!

  xrdcp * /eos/cms/store/group/dpg_bril/comm_bril/www/webtooldata-staging/my_sim

• You can now visit https://test-radsim.web.cern.ch/ and your simulation should be available to plot.

Setting up remote connection to test webtool page

The test webtool is hosted internally by CERN and is not accessible unless one is connected to a CERN network. It is, however, possible to set up a tunnel for access if you want to work from outside CERN e.g. from home, by following the steps given below:

• Make a config file in your computer's .ssh folder. On Linux, type cd ~/.ssh/, or on Windows go to C:\Users\myuser\.ssh. Create a new file called config and paste the lines below:

  Host cernsocks
          HostName lxplus.cern.ch
          DynamicForward 26852
          ServerAliveInterval 5
          TCPKeepAlive yes
          StrictHostKeyChecking no
          Compression yes
          Protocol 2
          ForwardAgent yes

• Open a tunnel by typing ssh -Nf cernsocks in the terminal. This should prompt for your lxplus account's password.
  

  [Troubleshoot] Slow connection, timeout, no prompt for password: when connecting to lxplus, it assigns the user a random physical machine (node) depending on the cluster's resources i.e. the busyness of the nodes. This dynamic port forwarding might be refused by your system. In this case a simple but dirty solution is to skip forwarding and directly connect to a node by adding the node ID by writing e.g. lxplus6 instead of lxplus in the config file. Please note that since many users are using lxplus, the individual nodes might occasionally be overloaded and thus unavailable for new connections. Alternatively, you can try turning off your antivirus and firewall and try to connect like that. It might also worth trying to type ssh -C -D 26852 -Nf lxplus.cern.ch in the terminal instead of using the config file. For debugging, you can use the verbosity options -v -vv or -vvv after the ssh commands.

• Once the password is given (you shouldn't see anything in the terminal after typing the password and hitting enter), open your Firefox browser and create a new profile that will be used for accessing the webtool through lxplus. In the browser, type about:profiles into the URL field and click on Create a new profile then enter a name for the profile the click on finish.

• Then find your newly created profile in the list and click on Launch profile in new browser. This will open up a new window. In this, type about:config into the URL field. Then type proxy into the search field on the top to display proxy settings.

• Change the following values:

          network.proxy.type value 1
          network.proxy.socks value localhost
          network.proxy.socks_port value 26852
          network.proxy.socks_remote_dns value true
          network.proxy.no_proxies_on value localhost
          

  You can get a more detailed description of this step here.

• After this, go to https://test-radsim.web.cern.ch/ and it should work fine.

Webtool source code

The source code of the backend and frontend are hosted on GitLab. Please ask for access to these repositories from an authorized BRIL member. If access is granted, please follow the steps below to clone and work with the repositories:

• If you are cloning them for the first time, generate an ssh key pair by moving into the .ssh folder with cd ~/.ssh/ then typing ssh-keygen -t rsa -C "firstname.lastname@cern.ch". When the terminal prompts Enter file in which to save the key ..., type id_rsa_cern_gitlab to give this as a name to the ssh keys. Press enter to proceed, then skip the Enter passphrase ... prompts by pressing enter twice more. Now you should see the newly generated private id_rsa_cern_gitlab and public id_rsa_cern_gitlab.pub ssh keys in the .ssh directory.

• Type chmod 500 id_rsa_cern_gitlab to give yourself read and execute privileges for the private key. It is more important to block all privileges for everyone else (the last two digits are 0) for security reasons.

• Open id_rsa_cern_gitlab.pub by typing vi id_rsa_cern_gitlab.pub and copy the whole content.

• Go to your CERN GitLab profile in the browser and navigate to the SSH keys tab (or click here). On the right side of the page, paste the copied content from id_rsa_cern_gitlab.pub into the empty field under the Key paragraph. Then to the Title field type CERN Gitlab then press Add key below. This will enable your machine to communicate with GitLab through your newly generated public ssh key.

The above steps need to be done only once to establish connection to CERN GitLab. On the other hand, the following steps have to be performed each time you turn on your machine and start to work with the webtool repositories:

• Execute eval $(ssh-agent) in the terminal.

• Then add your private key by typing ssh-add ~/.ssh/id_rsa_cern_gitlab

Now you can clone, edit and push changes to the webtool repositories as follows:

• Cloning (first time download). It is parctical to clone them into your user's home directory. Move there by typing cd. Then type the following to download the source code of the front end and back end respectively:

         git clone -b dev-master ssh://git@gitlab.cern.ch:7999/cms-radiation-simulation-tools/web-tool-frontend.git
         git clone -b dev-master ssh://git@gitlab.cern.ch:7999/cms-radiation-simulation-tools/web-tool-backend.git
         

• Now move into one of the cloned directories to be able to issue git specific commands. You can check the status of your repository by typing git status or git log. The former prints out the file names that are different i.e. contain modifications compared to the current version on GitLab. The latter prints out a long history of previous commits by all editors.

• If you want to push (upload) changes, commit first by typing:

         git commit -a -m "write some short comment about the changes here" 
         

• Then type git push origin dev-master for pushing the changes. This uploads your modified files to the dev-master branch of the repository.

Pushing changes to dev-master only affects the test webtool but not the release version, which corresponds to the master branch. Please do not push anything to that branch unless it is discussed with your colleagues. After pushing you will need to wait around 1 minute for synchronization to be able to see the changes on the webtool.

Undoing changes: If you want to undo your changes and you have already pushed them, go to the GitLab repository, select the dev_master branch from the drop down on the top left, then click on History on the top right. Next, click on the title of the commit you want to undo. On the top right, click on Options and select Revert. Here make sure that you untick the Start a new merge request with these changes box and select dev-master from the drop down window, finally click on the green button Revert. Note that this will create a new commit and a new entry to the history instead of just deleting the old one that needed to be undone. Alternatively you can do the same in the terminal by typing git reset --hard ID where ID is a combination of letters and numbers and is a unique identifier of a commit and can be found either in git log or on the right side in the history entry in the browser by clicking on Copy commit SHA.