Merge branch 'master' into 113_test-reports

.gitlab-ci.yml

@@ -6,11 +6,12 @@ variables:
 before_script:
   - apt-get update --yes
   - apt-get install --yes cmake libboost-dev libeigen3-dev python3 gfortran
+  - apt-get install --yes doxygen graphviz
 
 build:
   stage: build
   tags:
-    - run1
+    - corsika
   script:
     - mkdir build
     - cd build
@@ -26,6 +27,27 @@ build:
       junit:
         - build/test_outputs/junit*.xml
 
+pages:
+  stage: build
+  tags:
+    - corsika
+  script:
+    - mkdir build
+    - cd build
+    - cmake ..
+    - make doxygen
+    - mkdir .public
+    - cp -r Documentation/Doxygen/html .public/
+    - mv .public ../public
+  artifacts:
+    paths:
+      - public
+  only:
+    - tags
+    - triggers
+    - schedules
+
+
 # code_quality:
 #   image: docker:stable
 #   variables:

CMakeLists.txt

@@ -74,3 +74,4 @@ add_subdirectory (Setup)
 add_subdirectory (Processes)
 add_subdirectory (Documentation)
 add_subdirectory (Main)
+add_subdirectory (Tools)

COLLABORATION_AGREEMENT.md

@@ -16,7 +16,7 @@ community and individuals in a best effort to deliver the best
 possible computing performance and physics output. 
 The MCnet guidelines developed by [www.montecarlonet.org](www.montecarlonet.org) 
 are copied in [MCNET_GUIDELINES](MCNET_GUIDELINES) -- they provide a very good 
-additional scope that contributors should read and follow. 
+additional scope that contributors should read and consider. 
 
 All possible
 liability and licensing question are only handled by the adopted
@@ -29,9 +29,9 @@ license GPLv3, as copied in full in the file
 short statement of the copyright and this license. Each binary or
 source code release of CORSIKA must contain the file LICENSE. The
 code, documentation and content in the folder [ThirdParty](ThirdParty)
-is not integral part of the CORSIKA project and can be based on or
-include other licenses, which must be compatible with GPLv3. Check the
-content of this folder for details. It depends on the configuration of
+is not integral part of the CORSIKA project and can be based on, or
+include, other licenses, which must be compatible with GPLv3. Check the
+content of this folder for details and additional license information. It depends on the configuration of
 the build system to what extend this code is used to build CORSIKA.
 
 ## Who is the "copyright holder"
@@ -65,39 +65,39 @@ If you want to contribute, you need to read
 improve them.
 
 
-## Definition and working mode of the CORSIKA Project panel
+## The CORSIKA Project panel
 The CORSIKA Project panel makes all decisions for the CORSIKA
 Project. It can also change the
 [COLLABORATION\_AGREEMENT](COLLABORATION\_AGREEMENT.md), the
-[the GUIDELINES](CONTRIBUTING.md) or any other structure or document relevant for the CORSIKA Project.
+[GUIDELINES](CONTRIBUTING.md) or any other structure or document relevant for the CORSIKA Project.
 
 The CORSIKA Project *panel* consists (October 2018) of
    
+  * Hans Dembinski (MPG)
   * Ralph Engel (KIT)
   * Dieter Heck (KIT)
   * Tanguy Pierog (KIT)
   * Maximilian Reininghaus (KIT)
-  * Markus Roth (KIT)
+  * Felix Riehn (LIP)
   * Ralf Ulrich (KIT)
-  * Michael Unger (KIT)
   * Darko Veberic (KIT)
   
 and can be contacted via corsika-project@lists.kit.edu.  The chair
 person of the CORSIKA Project is Ralf Ulrich (KIT). Members of the
-CORSIKA Project *panel* are *Maintainer* of the CORSIKA Project in
+CORSIKA Project *panel* can be *Maintainer* of the CORSIKA Project in
 gitlab at
 [https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika](https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika),
-and have special responsibilities for this reason. 
+and have special responsibilities also for this reason. 
 
-## Changing to a different license, for parts, or the complete project
+### Changing to a different license, for parts, or the complete project
 
-The CORSIKA Project panel can change the license for parts or the entire project. 
+The CORSIKA Project panel can change the license for parts or the entire project in general or for individual releases.
 
-## Planning and performing releases
+### Planning and performing releases
 
 The CORSIKA Project panel decides on releases of the software, and about the content of it. 
 
-## Changes to the Collaboration Agreement
+### Changes to the Collaboration Agreement
 
 The CORSIKA Project panel decides on changes to the Collaboration
 agreement.

CONTRIBUTING.md

@@ -2,23 +2,23 @@
 
 The CORSIKA Project very much welcomes contributions. Here we outlined
 how you can find the right place to contribute, and how to do that.
-Connect to http://gitlab.ikp.kit.edu and corsika-devel@lists.kit.edu
-or corsika-project@lists.kit.edu to get in touch with the project.
-The CORSIKA Project decides on the [GUIDELINES](CONTRIBUTING.md), and can
-change them.
+Connect to https://gitlab.ikp.kit.edu and corsika-devel@lists.kit.edu (self-register at https://www.lists.kit.edu/sympa/subscribe/corsika-devel)
+or write to corsika-project@lists.kit.edu to get in touch with the project.
+The CORSIKA Project decides on the [GUIDELINES](CONTRIBUTING.md) and can decide to
+change/improve them.
 
 # How to contribute
 
   - We organize all development via `Issues` that may be feature requests,
-    ideas, or bugs fix requests. 
+    ideas, discussions, or bugs fix requests. 
   - New issues can be created, or existing issues
-    picked up. 
+    picked up or contributed to. 
   - Issues are discussed in meetings or via  corsika-devel@lists.kit.edu  within the CORSIKA Project.
   - Issues are assigned to milestones. 
   - The work on issues is performed in `branches` that can be best
     created directly via the gitlab web interface. 
   - Proposed code to close one issue (located in a specific git
-    branch) is reviewed and eventually discussed, and finally merged
+    branch) is reviewed, discussed, and eventually merged
     into the master branch to close the issue.
 
 
@@ -31,7 +31,9 @@ formatting. We provide a script `do-clang-format.sh`, which can be
 very useful. But we urge everybody to integrate `clang-format` already
 on the level of your source code editor. See [the official
 page](https://clang.llvm.org/docs/ClangFormat.html) for information
-about `clang-format` and its editor integration. 
+about `clang-format` and its editor integration. At least: run
+`do-clang-format.sh` prior to any `git add` command. Code with
+improper formatting will not be accepted for merging. 
 
 The definition of source code format is written down in the file
 [.clang-format](.clang-format) and can be changed, if the CORSIKA
@@ -39,6 +41,7 @@ Project agrees on it. To see what is possible, check
 e.g. [link1](https://clangformat.com/) or
 [link2](https://zed0.co.uk/clang-format-configurator/).
 
+
 ## Naming conventions
 
 While `clang-format` does the structural formatting, we still need to agree on naming conventions:
@@ -47,8 +50,9 @@ While `clang-format` does the structural formatting, we still need to agree on n
   - Class member variables start with "f"
   - Any static variable has a "g" prefix. A static member variable starts with "fg"
   - Class member functions start with capital letters
-  - Any class getter begins with "Get", and setter with "Set"
+  - Any class getter begins with "Get", and setter with "Set". Logical getters start with "Is" or "Has".
   - enums should be "enum class", and start with a capital "E", enum entries start with "e"
+  - Function parameter names start with "v"
 
   - We use namespaces to avoid clashes and to structure code
     - *Everything* is part of the corsika namespace
@@ -62,12 +66,12 @@ While `clang-format` does the structural formatting, we still need to agree on n
       files.
     - Each header file uses an include protection that includes at
       least the namespace name, and header file name, thus, `#ifndef
-      __include_geometry_Point_h__` or `#ifnedf __geometry_Point_h__`,
+      __include_geometry_Point_h__` or `#ifndef __geometry_Point_h__`,
       or similar are acceptable.
     - Header files should always be included with `<..>`, thus,
       `#include <corsika/geometry/Point.h>` since the build system
       will always provide the correct include directives (and files
-      anyway cannot be found in file-system paths that typically do
+      anyway cannot be found in file-system paths, which generally do
       not follow the namespace naming conventions outlined
       here).
 
@@ -79,7 +83,7 @@ While `clang-format` does the structural formatting, we still need to agree on n
 ## Coding rules
 
   - Code may not introduce any compiler errors, or warnings
-  - All unit tests must succeed at all times
+  - All unit tests must succeed at all times. If tests fail, code is not merged.
   - We use C++17 concepts wherever useful and helpful
   - On any major error or malfunction we throw an exception. This is needed and required for complex physics and shower debugging.
   - We never catch exceptions for error handling, there might be very few special exceptions from this. We need to discuss such cases.
@@ -90,17 +94,23 @@ While `clang-format` does the structural formatting, we still need to agree on n
     exposed to outside users, there might be pointers for very special cases
     inside of classes.
   - When you contribute new code, or extend existing code, at the same time provide unit-tests for all functionality.
+  - When you contribute new physics algorithms, in addition you also need to provide a validation module
   - Code must be documented with `doxygen` commands
   
 
 ## Release versioning scheme
 
-Releases of CORSIKA are thought to be the baseline for larger scale testing, and full production. 
-The releases are numbered as x.y.z, starting with x=8 form the gitlab c++ version. X will only be incremented 
-for major design or physics changes. The y index is updated for new official releases that normally contain improved or enhanced physics 
-performance, and may also contain normal interface changes to accomodate improvements. The z index can be updated frequently for
-bug fixes or new features. Changes in z will not contain interface changes, thus, code will remain fully compatible.  
-Special releases of CORSIKA can also have a tag name from git, e.g. as in the "milestone1" release.
+Releases of CORSIKA are thought to be the baseline for larger scale
+testing, and full production.  The releases are numbered as x.y.z,
+starting with x=8 form the gitlab c++ version. X will only be
+incremented for major design or physics changes. The y index is
+updated for new official releases that normally contain improved or
+enhanced physics performance, and may also contain normal interface
+changes to accomodate improvements. The z index can be updated more
+frequently for bug fixes or new features. Changes in z will not
+contain (major) interface changes, thus, production code will remain
+fully compatible within changes of z.  Special releases of CORSIKA can
+also have a tag name from git, e.g. as in the "milestone1" release.
 
 
 # How to become scientific author of the CORSIKA Project
@@ -108,10 +118,10 @@ Special releases of CORSIKA can also have a tag name from git, e.g. as in the "m
 The CORSIKA Project decides on who becomes scientific author. The
 following conditions are clearly sufficient, but not all of them are
 required all the time:
-  - responsibility for a particular functionality or part
-  - follows these [GUIDELINES](GUIDELINES.md)
-  - agrees to the [COLLABORATION_AGREEMENT](COLLABORATION_AGREEMENT.md)
+  - responsibility for a particular functionality or software/management part 
+  - have read and follow these [GUIDELINES](CONTRIBUTING.md)
   - active in the CORSIKA Project, that means responsive to
-    discussions and problems in corsika-devel@list.kit.edu or on https//gitlab.ikp.kit.edu, of relevant *issues*,
+    discussions and problems in corsika-devel@list.kit.edu or on https//gitlab.ikp.kit.edu, of relevant *Issues*,
     or in (phone) meetings
+  - agreement to the [COLLABORATION_AGREEMENT](COLLABORATION_AGREEMENT.md) is strictly required
   - the members of the CORSIKA Project panel agree

Documentation/Examples/CMakeLists.txt

@@ -7,13 +7,13 @@ add_test(helix_example helix_example)
 add_executable (geometry_example geometry_example.cc)
 target_compile_options(geometry_example PRIVATE -g) # do not skip asserts
 target_link_libraries (geometry_example CORSIKAgeometry CORSIKAunits)
-#install (TARGETS geometry_example DESTINATION share/examples)
+install (TARGETS geometry_example DESTINATION share/examples)
 add_test(geometry_example geometry_example)
 
 add_executable (logger_example logger_example.cc)
 target_compile_options(logger_example PRIVATE -g) # do not skip asserts
 target_link_libraries (logger_example CORSIKAunits CORSIKAlogging)
-#install (TARGETS logger_example DESTINATION share/examples)
+install (TARGETS logger_example DESTINATION share/examples)
 add_test(logger_example logger_example)
 
 add_executable (stack_example stack_example.cc)
@@ -35,7 +35,7 @@ target_link_libraries (cascade_example SuperStupidStack CORSIKAunits CORSIKAlogg
   CORSIKAenvironment
   CORSIKAprocesssequence
   )
-#install (TARGETS cascade_example DESTINATION share/examples)
+install (TARGETS cascade_example DESTINATION share/examples)
 add_test(cascade_example cascade_example)
 
 add_executable (staticsequence_example staticsequence_example.cc)
@@ -45,5 +45,5 @@ target_link_libraries (staticsequence_example
   CORSIKAunits
   CORSIKAgeometry
   CORSIKAlogging)
-#install (TARGETS staticsequence_example DESTINATION share/examples)
+install (TARGETS staticsequence_example DESTINATION share/examples)
 add_test(staticsequence_example staticsequence_example)

README.md

@@ -3,7 +3,7 @@
 Documentation and reference guide for the CORSIKA8 software framework
 for air shower simulations. We aim that CORSIKA remains the most comprehensive
 framework for simulating particle cascades with stochastic and continuous processes. The purpose of CORSIKA is to 
-simulate any particle cascades in astroparticle physics or astrophysical context. A lot of emphasis is put on modularity, completeness, validation and correctness. To boost computational efficiency different techniques are
+simulate any particle cascades in astroparticle physics or astrophysical context. A lot of emphasis is put on modularity, flexibility, completeness, validation and correctness. To boost computational efficiency different techniques are
 provided, like thinning or cascade equations. 
 
 The software makes extensive use of static design patterns and
@@ -14,9 +14,9 @@ only specific model parameters can still be changed.
 CORSIKA8 is released under the GPL3 license. See [license file](https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika/blob/master/LICENSE) which is part of every release and the source code. 
 
 When you contribute to CORSIKA check the guidelines outlined here:
-[coding guidelines](https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika/blob/master/CONTRIBUTING.md). Code that fail the review by the CORSIKA author group must be improved before it can be merged in the official code base. After your code has been accepted and merged you become a contributor of the CORSIKA project and you should include yourself in the [AUTHORS](https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika/blob/master/AUTHORS) file. 
+[coding guidelines](https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika/blob/master/CONTRIBUTING.md). Code that fails the review by the CORSIKA author group must be improved before it can be merged in the official code base. After your code has been accepted and merged you become a contributor of the CORSIKA project and you should include yourself in the [AUTHORS](https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika/blob/master/AUTHORS) file. 
 
-You need to read and agree to the [collaboration agreement](https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika/blob/master/COLLABORATION_AGREEMENT.md). The agreement can be discussed, and eventually improved. 
+IMPORTANT: Before your contribute, you need to read and agree to the [collaboration agreement](https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika/blob/master/COLLABORATION_AGREEMENT.md). The agreement can be discussed, and eventually improved. 
 
 We also want to point you to the [MCnet guidelines](https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika/blob/master/MCNET_GUIDELINES), which are very useful also for us. 
 
@@ -27,11 +27,11 @@ Prerequisites: eigen3, boost, cmake, g++, git. On Ubuntu 18.04, just do:
 sudo apt-get install libeigen3-dev libboost-dev cmake g++ git
 ```
 
-Follow these steps to download and install CORSIKA8-milestone1
+Follow these steps to download and install CORSIKA8-milestone2
 ```
 git clone git@gitlab.ikp.kit.edu:AirShowerPhysics/corsika.git
 cd corsika
-git checkout milestone1
+git checkout milestone2
 mkdir ../corsika-build
 cd ../corsika-build
 cmake ../corsika -DCMAKE_INSTALL_PREFIX=../corsika-install
@@ -39,7 +39,19 @@ make -j8
 make install
 make test
 ```
-and if you want to see how the Heitler model works and is implemented, see `Framework/Cascade/testCascade.cc` for a starting point. 
+and if you want to see how the first simple hadron cascade develops, see `Documentation/Examples/cascade_example.cc` for a starting point. 
+
+Run the cascade_example with: 
+```
+cd ../corsika-install
+share/examples/cascade_example
+```
+
+Visualize output: 
+```
+bash share/tools/plot_tracks.sh tracks.dat 
+firefox tracks.dat.gif 
+```
 
 ### Generating doxygen documentation
 
@@ -51,3 +63,7 @@ Switch to the corsika build directory and do
 ```
 make doxygen
 ```
+browse with firefox:
+```
+firefox ../corsika-install/share/doc/html/index.html
+```

Tools/CMakeLists.txt

+set (TOOLS_FILES plot_tracks.sh)
+
+install (
+  FILES ${TOOLS_FILES} 
+  DESTINATION share/tools
+  )