Package: proposal
###############################################################################
#                                                                             #
#            _____  _____   ____  _____   ____   _____         _              #
#           |  __ \|  __ \ / __ \|  __ \ / __ \ / ____|  /\   | |             #
#           | |__) | |__) | |  | | |__) | |  | | (___   /  \  | |             #
#           |  ___/|  _  /| |  | |  ___/| |  | |\___ \ / /\ \ | |             #
#           | |    | | \ \| |__| | |    | |__| |____) / ____ \| |____         #
#           |_|    |_|  \_\\____/|_|     \____/|_____/_/    \_\______|        #
#                                                                             #
#                            _   _    ___   ___                               #
#                           | | | |  / _ \ (   )                              #
#                           | |_| | |  __/  | |                               #
#                           | ._,_|  \___|   \_)                              #
#                           | |                                               #
#                           |_|                                               #
#                                                                             #
###############################################################################PROPOSALPROPOSAL (Propagator with optimal precision and optimized speed for all
leptons) is presented as a public tool for propagating leptons and gamma rays
through media.
Up-to-date cross sections for ionization, bremsstrahlung, photonuclear
interactions, electron pair production, Landau–Pomeranchuk–Migdal and
Ter-Mikaelian effects, muon and tau decay, as well as Molière scattering are
implemented for different parametrizations.
The full Paper can be foundhere.
Recent improvements are documentedhere.PROPOSAL is developed and tested on macOS, Linux and Windows:
Continuous integration is set up on GitHub actions testing PROPOSAL on gcc, clang and Visual Studio.PROPOSAL is now a C++14 library using pybind11 Python bindings!RequirementsCMake 3.9 or higher (to build the tests CMake 3.10 is required)C++14 compatible compiler (for gcc: version 5 and later; for clang: version 3.4 and later)Furthermore, you either need the package managerconanwhich will provide all dependencies that are necessary for PROPOSAL or you need to provide these dependencies by your own. For more information, seehere.InstallationIf you are only interested in using PROPOSAL as a python library, the easiest way to install it should be usingpip install proposalAdvanced install and compiling instructions, especially if you want to use PROPOSAL as a C++ library, are found ininstall.UsageUsage in PythonIf you want to learn how to use PROPOSAL in Python, we recommend to look at the jupyter notebooks provided in theexamplesfolder.
A good starting point is thePropagatorjupyter notebook.For a short demonstration, look at the following snippet:
It will create data you can use to show the distribution of muon ranges and the number of interactions in ice.importproposalasppmu_def=pp.particle.MuMinusDef()prop=pp.Propagator(particle_def=mu_def,path_to_config_file="path/to/config.json")init_state=pp.particle.ParticleState()init_state.energy=1e9# initial energy in MeVinit_state.position=pp.Cartesian3D(0,0,0)init_state.direction=pp.Cartesian3D(0,0,1)mu_length=[]foriinrange(1000):track=prop.propagate(init_state)mu_length.append(track.track_propagated_distances()[-1]/100)Note that you need to provide a path to a valid configuration file.
The parameters of the given configuration file are describedhere.For a detailed explanation on how this snippet works, look at thePropagatorjupyter notebook!Usage as a C++ libraryPROPOSAL is built as a library, which means you can include this project in your own
C++ project by including the header files. The following snippet uses theconfigurationto propagate muons and
stores the muon ranges.
The parameters of the configuration file are describedhere.#include"PROPOSAL/PROPOSAL.h"usingnamespacePROPOSAL;intmain(){automu_def=MuMinusDef();Propagatorprop(mu_def,"path/to/config.json");Cartesian3Dposition(0,0,0);Cartesian3Ddirection(0,0,1);autoenergy=1e8;// MeVautoinit_state=ParticleState(position,direction,energy,0.,0.);std::vector<double>ranges;for(inti=0;i<10;i++){autotrack=prop.Propagate(init_state,50000);// distance to propagate in cmranges.push_back(track.back().propagated_distance);}// ... Do stuff with ranges, e.g. plot histogram}To see an example on how to run this script with PROPOSAL using CMake, seehere.IssuesWhen you encounter any errors or misunderstandings, you can always create an issue here on GitHub.
Furthermore, you may always contact us with your questions viaJean-Marco Alameddine,Jan Soedingrekso,Alexander Sandrock.LicenseThis software may be modified and distributed under the terms of
a modified LGPL License. See the LICENSE for details of the LGPL License.Modifications of the LGPLLicense:The user shall acknowledge the use of PROPOSAL by citing the following reference:J.H. Koehne et al.
Comput.Phys.Commun. 184 (2013) 2070-2090
DOI: 10.1016/j.cpc.2013.04.001The user should report any bugs/errors or improvements to the current maintainer of PROPOSAL.How to cite PROPOSAL?If you use PROPOSAL, please cite the PROPOSAL paper@article{koehne2013proposal,title={PROPOSAL: A tool for propagation of charged leptons},author={Koehne, Jan-Hendrik andFrantzen, Katharina andSchmitz, Martin andFuchs, Tomasz andRhode, Wolfgang andChirkin, Dmitry andTjus, J Becker},journal={Computer Physics Communications},volume={184},number={9},pages={2070--2090},year={2013},doi={10.1016/j.cpc.2013.04.001}}and our zenodo entry of the version you use@misc{dunsch_2020_1484180,author={Alameddine, Jean-Marco andDunsch, Mario andBollmann, Lars andFuchs, Tomasz andGutjahr, Pascal andKoehne, Jan-Hendrik andKopper, Claudio andKrings, Kai andKuo, Chung-Yun andMenne, Thorben andNoethe, Maximilian andOlivas, Alex andRhode, Wolfgang andSackel, Maximilian andSandrock, Alexander andSchneider, Austin andSoedingrekso, Jan andvan Santen, Jacob},title={tudo-astroparticlephysics/PROPOSAL: Zenodo},month=mar,year=2020,doi={10.5281/zenodo.1484180},url={https://doi.org/10.5281/zenodo.1484180}}and if you want to cite the latest improvements@article{dunsch_2018_proposal_improvements,title={Recent Improvements for the Lepton Propagator PROPOSAL},author={Dunsch, Mario andSoedingrekso, Jan andSandrock, Alexander andMeier, Max andMenne, Thorben andRhode, Wolfgang},journal={Computer Physics Communications},volume={242},pages={132--144},year={2019},eprint={1809.07740},eprinttype={arXiv},eprintclass={hep-ph},doi={10.1016/j.cpc.2019.03.021}}Developers and MaintainersJan Soedingrekso,Alexander Sandrock,Jean-Marco AlameddineFormer Developers and MaintainersJan-Hendrik Koehne,Tomasz Fuchs,Mario Dunsch,Maximilian SackelAcknowledgmentThis work was created as part of the projectC3of theSFB876.