mcpartools Documentation¶
Contents:
Getting Started with mcpartools¶
Brief overview of mcpartools and how to install it.
Introduction¶
mcpartools is a software simplifying time consuming simulation of particle transport using Monte Carlo codes (Fluka, SHIELDHIT12A). We assume user has access to a computing cluster with batch processing software installed (i.e. slurm, torque) and wants to parallelize simulation by running it simultaneously on many computing nodes. mcpartools simplifies this process by generating necessary directory structures and scripts for starting calculations and collecting the results.
mcpartools provides a command line application called generatemc
which works under Linux operating system
(interpreter of Python programming language has to be also installed).
No programming knowledge is required from user, but basic skills in working with terminal console are needed.
Quick installation guide¶
First be sure to have Python framework installed, then type:
pip install mcpartools
This command will automatically download and install mcpartools for all users in your system.
In case you don’t have administrator rights, add --user
flag to pip
command.
In this situation converter will be probably installed in ~/.local/bin
directory.
For more detailed instruction, see installation guide.
Using generatemc command¶
Let us start with simple simulation of 10^6 of particles using Fluka MC code. Such simulation would probably take few hours when running on single CPU. It can be however faster, when you submit 100 parallel jobs, each running simulation of 10^4 particles. We assume that:
- you are logged in to the computing cluster, all commands are executed there
- mcpartools is installed on the cluster
- cluster has working
slurm
batch job software - Fluka in installed on the cluster and
rfluka
command is available - an example Fluka input file is located in
$HOME/sample.inp
First step is to generate necessary scripts and directory structure. To accomplish this, type in terminal:
generatemc --jobs_no 100 --particle_no 100000 $HOME/sample.inp
New directory with a name similar to $HOME/run_20160913_084601
will be created. To start simulation, we call
appropriate script:
$HOME/run_20160913_084601/submit.sh
After the simulation is done (it may take few minutes), run following script to gather the results in a single directory:
$HOME/run_20160913_084601/collect.sh
Output files from 100 parallel jobs will be saved in $HOME/run_20160913_084601/output
directory,
ready to be analyzed or merged.
In case the output is not satisfactory, new workspace can be created and whole process repeated from scratch.
More documentation dealing with advanced options can be found here https://mcpartools.readthedocs.io/
Features¶
- user-friendly parallelism of particle transport simulations
- output collected in single directory
- workspace with logs and input files saved for bookkeeping
- Monte-Carlo codes support: SHIELD-HIT12A and Fluka
- cluster batch software support: slurm
- python2 and python3 compatible
- no external libraries needed
Support¶
Bugs can be submitted through the issue tracker. Besides the example directory, cookbook recipes are encouraged to be posted on the wiki page
User’s Guide¶
Directory layout and basic workflow¶
generatemc will create following directory structure for each run:
run_20170219_122904 # main directory, new one is created for each generatemc call
collect.sh # call to copy output files to output directory
input # reference directory with copy of input files
sample_fluka.inp # non-modified copy of original Fluka input files
submit.sh # call to submit jobs to the cluster
workspace # workspace used to store modified input files and temporary storage for output
main_run.sh # this script will be called by batch system and redirect the execution to specific worker
job_0001 # working directory of worker no 1
sample_fluka.inp # copy of input file, with adapted RNG seed and output file path
run.sh # run script executed by worker no 1
job_0002
sample_fluka.inp
run.sh
job_0003
sample_fluka.inp
run.sh
After executing submit.sh script, output files will be created in the workspace directory. Each parallel job will store its output in separate directory:
run_20170219_122904
collect.sh
input
sample_fluka.inp
submit.sh
workspace
main_run.sh
job_0001
sample_fluka.inp
run.sh
TODO # TODO
job_0002
sample_fluka.inp
run.sh
TODO # TODO
job_0003
sample_fluka.inp
run.sh
TODO # TODO
In order to collect all files in a single place, run collect.sh script. This will result in following new files:
run_20170219_122904
collect.sh
input
sample_fluka.inp
submit.sh
output # TODO
TODO # TODO
workspace
main_run.sh
job_0001
sample_fluka.inp
run.sh
job_0002
sample_fluka.inp
run.sh
job_0003
sample_fluka.inp
run.sh
Advanced options¶
There are several advanced options in the generator, customising the workflow.
After executing generatemc command a directory will be created (i.e. run_20170219_122904), by default in the same location as the input configuration files. In order to change the location of generated directory, use the –workspace option. For example after typing:
generatemc.py -p 10000 -j 20 tests/res/sample_fluka.inp
A directory tests/res/run_20170717_195410 will be created. Now providing a workspace option:
generatemc.py -p 10000 -j 20 tests/res/sample_fluka.inp --workspace mydir
will result in new directory mydir/run_20170717_195557
Another useful option is the ability to provide additional options for scheduler and for Monte-Carlo binary. The first one can be used i.e. to specify directly the walltime for job execution:
generatemc.py -p 10000 -j 20 tests/res/sample_fluka.inp --scheduler_options "[--time=2:00:00]"
Note additional square brackets added to distinguish between generatemc and scheduler options.
There is also a possibility to do automatic collection of data after calculation. User can also specify desired format of collected data:
generatemc.py -p 10000 -j 20 tests/res/sample_fluka.inp -c image
Data will be collected automatically after calculation (in this example to the images) so there is no need to run additional ./collect.sh script. Right now available options are mv, cp, image, plotdata and custom. User could also provide his own script for collecting the data. In such case the program can be run in following way:
CUSTOM_COLLECT=usercollect.sh generatemc.py -p 10000 -j 20 tests/res/sample_fluka.inp -c custom
One could also specify additional options to Monte-Carlo binary files. For example to add an user-defined particle source in Fluka one can use its -e option. If the flukadpm3_sobp file is not present in the PATH environmental variable, then its location needs to be known. This may be achieved by a mechanism of creating a link to an external file. Such links can be created by using -x switch, here we provide an example in which an external source is enabled by -e switch and two external files are linked (sobp.dat and flukadpm3_sobp):
generatemc.py -p 10000 -j 20 tests/res/sample_fluka.inp --mc_engine_options "[-e flukadpm3_sobp]" -x ./sobp.dat ./flukadpm3_sobp
When using -x option you may also set the absolute paths to the linked files.
Detailed Installation Guide¶
Installation guide is divided in two phases: checking the prerequisites and main package installation.
mcpartools works under Linux operating system.
If you are familiar with python and pip tool, simply type following command to install the package:
$ pip install mcpartools
If your are a less advanced user, read the rest of the page.
Installation guide is divided in two phases: prerequisites (mainly Python installation) and main package installation.
There are two groups of users: administrators and regular ones.
For regular users we assume that they can write files to their home directory, but not necessary elsewhere.
We assume that administrators can log in as root user, execute commands via sudo
or
have some other way to create files system-wide.
We expect that mcpartools will mostly be used by regular users on computing clusters. This is the reason why installation instruction is lengthy and detailed, explaining how to deal with lack of administrator rights.
Prerequisites - python interpreter¶
First we need to check if Python interpreter is installed. Try if one of following commands (printing Python version) works:
$ python --version
$ python3 --version
At the time of writing Python language interpreter has two popular versions: 2.x (Python 2) and 3.x (Python 3) families.
Command python
invokes either Python 2 or 3, while python3
can invoke only Python 3.
mcpartools supports most of the modern Python versions, mainly: 2.7, 3.2, 3.4, 3.5 and 3.6. Check if your interpreter version is supported.
If none of python
and python3
commands are present, then Python interpreter has to be installed.
We suggest to use the newest version available for your Linux distribution (from 3.x family).
User installation¶
In case Python is missing and you are regular user, the best would be contact somebody with administrator rights and ask to install Python interpreter in the system.
Installation of Python without administrator rights is however possible, but in case something goes wrong it will require expert knowledge.
As an user you will need to download Python interpreter source code (written in C language) and compile it. For that purpose you will need a C language compiler (i.e. gcc) and some other tools (i.e. make). These tools are usually installed by somebody with administrator rights. Python installer might not complain about missing SSL libraries (i.e. libssl-dev) and will compile successfully, but we recommend to install it (SSL libraries) before, to have easier installation of pip package manager in the next steps.
When installing as user we advice to unpack downloaded source code in $HOME/tmp directory and keep it there. It may be needed for upgrade or deinstallation purpose.
Let us install Python 2.7 into $HOME/usr/py27 directory. First let us create $HOME/tmp directory and step into it:
$ mkdir -p $HOME/tmp
$ cd $HOME/tmp
Now its time to download and unpack source code package. We show an example with 2.7.12 version, but newer one can be problably found on https://www.python.org/downloads/source/
$ wget https://www.python.org/ftp/python/2.7.12/Python-2.7.12.tgz
$ tar -zxf Python-2.7.12.tgz
$ cd Python-2.7.12
Finally let us start compilation process (it might take couple of minutes). This process might be interrupted by some error message. Do not hesitate to find a professional help to fix it:
$ ./configure --prefix=$HOME/usr/py27
$ make
$ make install
Python2.7 is now installed into $HOME/usr/py27 directory. In order to execute python interpreter, you need to provide full path to the executable file, i.e.:
$ $HOME/usr/py27/bin/python --version
In a similar way python3.x can be installed.
Administrator installation¶
The best way is to use your package manager.
apt-get install python3
(python 3) orapt-get install python
(python 2) for Debian and Ubuntudnf install python3
(python 3) ordnf install python
(python 2) for Fedorayum install python3
(python 3) oryum install python
(python 2) for CentOS and SLC
Single file distribution¶
mcpartools is shipped as a single file executable. It can be downloaded from https://github.com/DataMedSci/mcpartools/releases webpage using the web browser or via command line (here an example with 0.1.4 version is found, newer versions should also be available):
$ wget https://github.com/DataMedSci/mcpartools/releases/download/v0.1.4/generatemc.pyz -O generatemc
After downloading the file, make sure it has executable bits set:
$ chmod ugo+x generatemc
When new version if released, replace downloaded file with newer one.
As mcpartools doesn’t have any mechanism of automatic updates, we recommend to use installation using pip tool, described below. It makes easy upgrade and uninstallation procedure.
Prerequisites - pip tool¶
pip is a tool for installing and managing Python packages. It downloads the packages from central Internet repository and installs them in a similar way as apps are downloaded on your smartphone by Google Play or Apple Store.
Try the following commands (printing pip version):
$ pip --version
$ pip3 --version
In a similar way to python interpreter pip is a tool for Python 2 or 3, while pip3 works exclusively for Python 3. If none of these commands are present, then pip has to be installed.
User installation¶
Follow the instruction from here https://pip.pypa.io/en/stable/installing/, mainly - download installation script using your web browser, or by typing in the terminal:
$ wget https://bootstrap.pypa.io/get-pip.py
# openssl for python2
Now use your python interpreter to execute downloaded script. It will install pip in your home directory:
$ python get-pip.py --user
Try if pip command is available by typing:
$ $HOME/.local/bin/pip --version
If this method fails you can also try to use a ensurepip approach. It works with Python versions: 2.7 (starting from 2.7.9), 3.4 and newer. To install pip, simply type:
$ python -m ensurepip
Administrator installation¶
Follow the package installation for your system. On some systems instructions mentioned below have to be prefixed with sudo command.
apt-get install python3-pip
(python 3) orapt-get install python-pip
(python 2) for Debian and Ubuntudnf install python3-pip
(python 3) ordnf install python-pip
(python 2) for Fedorayum install python3-pip
(python 3) oryum install python-pip
(python 2) for CentOS and SLC
pip package installation¶
Now it is time to install mcpartools package. It consists of executable file called generatemc and bunch of necessary code files.
User installation¶
User installation will put the mcpartools under hidden directory $HOME/.local.
To install the package, type in the terminal:
$ pip install mcpartools --user
If pip command is missing on your system, replace pip with pip3 in abovementioned instruction.
To upgrade the mcpartools to newer version, simply type:
$ pip install --upgrade mcpartools --user
To completely remove mcpartools from your system, use following command:
$ pip uninstall mcpartools
In most of modern systems all executables found in $HOME/.local/bin directory (generatemc executable will be saved there) can be called like normal Linux commands (i.e. ls, cd). It means that after installation you should be able to simply type in terminal: generatemc to use this package
$ generatemc --help
If this is not the case, please prefix the command with $HOME/.local/bin and call it in the following way:
$ $HOME/.local/bin/generatemc --help
Administrator installation¶
Administrator installation is very simple, but requires to save some files in system-wide directories (i.e. /usr). On some systems commands mentioned below have to be prefixed with sudo command:
$ pip install mcpartools
To upgrade the mcpartools to newer version, simply type:
$ pip install --upgrade mcpartools
To completely remove mcpartools from your system, use following command:
$ pip uninstall mcpartools
Now generatemc script should be installed for all users and can be invoked by typing:
$ generatemc --help
Developer documentation¶
Contributing¶
Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.
You can contribute in many ways:
Types of Contributions¶
Report Bugs¶
Report bugs at https://github.com/DataMedSci/mcpartools/issues.
If you are reporting a bug, please include:
- Your operating system name and version.
- Any details about your local setup that might be helpful in troubleshooting.
- Detailed steps to reproduce the bug.
Fix Bugs or Implement Features¶
Look through the GitHub issues for bugs or features. Anything tagged with “bug” or “feature” is open to whoever wants to implement it.
Write Documentation¶
mcpartools could always use more documentation, whether as part of the official mcpartools docs, in docstrings, or even on the web in blog posts, articles, and such.
Submit Feedback¶
The best way to send feedback is to file an issue at https://github.com/DataMedSci/mcpartools/issues.
If you are proposing a feature:
- Explain in detail how it would work.
- Keep the scope as narrow as possible, to make it easier to implement.
- Remember that this is a volunteer-driven project, and that contributions are welcome :)
Get Started for GIT-aware developers¶
Ready to contribute? Here’s how to set up mcpartools for local development. We assume you are familiar with GIT source control system. If not you will other instruction at the end of this page.
Fork the mcpartools repo on GitHub.
Clone your fork locally:
$ git clone git@github.com:your_name_here/mcpartools.git
If you are not familiar with GIT, proceed to step 5, otherwise create a branch for local development:
$ cd mcpartools $ git checkout -b feature/issue_number-name_of_your_bugfix_or_feature
Now you can make your changes locally.
As the software is prepared to be shipped as pip package, some modifications
of PYTHONPATH variables are needed to run the code. Let us assume you are now in the same directory as setup.py
file.
The standard way to execute Python scripts WILL NOT WORK:
$ python mcpartools/generatemc.py --version
Traceback (most recent call last):
File "mcpartools/generatemc.py", line 5, in <module>
from mcpartools.generator import Generator
ImportError: No module named mcpartools.generator
To have the code working, two things are needed:
- installation of
versioneer
package (needed to set proper version number) - adjustment of PYTHONPATH variable.
First let us install versioneer
package and generate necessary files:
$ pip install versioneer
$ versioneer install
Now code can be run by typing:
$ PYTHONPATH=. python mcpartools/generatemc.py --version
0.1.3.post.dev2
Make local changes to fix the bug or to implement a feature.
When you’re done making changes, check that your changes comply with PEP8 code quality standars (flake8 tests) and test against other Python versions with tox:
$ flake8 mcpartools tests $ tox
To get flake8 and tox, just pip install them.
Commit your changes and push your branch to GitHub:
$ git add . $ git commit -m "Your detailed description of your changes."
Repeat points 4-6 until the work is done. Now its time to push the changes to remote repository:
$ git push origin feature/issue_number-name_of_your_bugfix_or_feature
Submit a pull request through the GitHub website to the master branch of
git@github.com:DataMedSci/mcpartools.git
repository.Check the status of automatic tests ran by Travis system.
You can find them on the pull request webpage https://travis-ci.org/DataMedSci/mcpartools/pull_requests. In case some of the tests fails, fix the problem. Then commit and push your changes (steps 5-8).
Pull Request Guidelines¶
Before you submit a pull request, check that it meets these guidelines:
- The pull request should include tests.
- If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.
- The pull request should work for Python 2.7, 3.2, 3.4, 3.5 and 3.6. Check https://travis-ci.org/DataMedSci/mcpartools/pull_requests and make sure that the tests pass for all supported Python versions.
Get Started for non-GIT developers¶
Fetch the code from remote GIT repository to your local directory:
$ git clone git@github.com:DataMedSci/mcpartools.git
Follow steps 4-6 from the instruction for GIT-aware developers. Install versioneer:
$ pip install versioneer $ versioneer install
To run code locally, prefix usual calls with PYTHONPATH=.
:
$ PYTHONPATH=. python mcpartools/generatemc.py --version
0.1.3.post.dev2
Make your changes and check that they comply with PEP8 code quality standards (flake8 tests) and test against other Python versions with tox:
$ flake8 mcpartools tests
$ tox
- Compress your working directory and send it to us by email (see authors), describing your changes.
Tips¶
To run full tests type:
$ tox
To run only a single test type:
$ PYTHONPATH=. python tests/test_file_to_run.py
Technical documentation¶
TODO
Credits¶
Development¶
- Leszek Grzanka - IFJ-PAN, Poland <leszek.grzanka@gmail.com>
- ant6
Contributors¶
None yet. Why not be the first?
Indices and tables