diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000000000000000000000000000000000000..3d49cee1b4ca6476c66fd1c0159f2866f681b0df
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,204 @@
+CORSIKA 8 Framework for Particle Cascades in Astroparticle Physics
+===================================================================
+
+The purpose of CORSIKA is to 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 aim is that
+CORSIKA remains the most comprehensive framework for simulating
+particle cascades with stochastic and continuous processes.
+
+The software makes extensive use of static design patterns and
+compiler optimization. Thus, the most fundamental configuration
+decision of the user must be performed at compile time. At run time
+model parameters can still be changed.
+
+CORSIKA 8 is by default released under the GPLv3 license. See `license
+file <https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika/blob/master/LICENSE>`_
+which is part of every release and the source code.
+
+If you use, or want to refer to, CORSIKA 8 please cite `"Towards a Next
+Generation of CORSIKA: A Framework for the Simulation of Particle
+Cascades in Astroparticle Physics", Comput.Softw.Big Sci. 3 (2019)
+2 <https://doi.org/10.1007/s41781-018-0013-0>`_. We kindly ask (and
+require) any relevant improvement or addition to be offered or
+contributed to the main CORSIKA 8 repository for the benefit of the
+whole community.
+
+When you plan to contribute to CORSIKA 8 check the guidelines outlined here:
+`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 8
+project (code author).
+
+IMPORTANT: Before you 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.
+
+
+Get in contact
+--------------
+ * Connect to https://gitlab.ikp.kit.edu register yourself and join the "Air Shower Physics" group. Write to me (ralf.ulrich@kit.edu) only in case there are problems with that.
+ * Connect to corsika-devel@lists.kit.edu (self-register at
+ https://www.lists.kit.edu/sympa/subscribe/corsika-devel) to get in
+ touch with the project.
+
+ * Register on the corsika slack channel.
+
+
+Installation
+------------
+
+CORSIKA 8 is tested regularly at least on gcc7.3.0 and clang-8.0.0.
+
+Prerequisites
+~~~~~~~~~~~~~
+
+You will also need:
+
+- Python 3 (supported versions are Python >= 3.6), with pip
+- conan (via pip)
+- cmake
+- git
+- g++, gfortran, binutils, make
+
+On a bare Ubuntu 20.04, just add:
+::
+
+ sudo apt-get install python3 python3-pip cmake g++ gfortran git doxygen graphviz
+
+
+On a bare CentOS 7 install python3, pip3 (pip from python3) and cmake3. Any of the devtools 7, 8, 9 should work (at least).
+Also initialize devtools, before building CORSIKA 8:
+::
+
+ source /opt/rh/devtoolset-9/enable
+
+
+CORSIKA 8 uses the `conan <https://conan.io/>`_ package manager to
+manage our dependencies. If you do not have Conan installed, it can be
+installed with:
+::
+
+ pip install --user conan
+
+
+Compiling
+~~~~~~~~~
+
+Once Conan is installed, follow these steps to download and install CORSIKA 8:
+::
+
+ git clone --recursive git@gitlab.ikp.kit.edu:AirShowerPhysics/corsika.git
+ mkdir corsika-build
+ cd corsika-build
+ cmake ../corsika -DCMAKE_INSTALL_PREFIX=../corsika-install
+ make -j8
+ make install
+
+
+Installation (using docker containers)
+--------------------------------------
+
+There are docker containers prepared that bring all the environment and packages you need to run CORSIKA. See `docker hub <https://hub.docker.com/repository/docker/corsika/devel>`_ for a complete overview.
+
+Prerequisites
+~~~~~~~~~~~~~
+
+You only need docker, e.g. on Ubuntu: :code:`sudo apt-get install docker` and of course root access.
+
+Compiling
+---------
+
+Follow these steps to download and install CORSIKA 8, master development version
+::
+
+ git clone --recursive https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika.git
+ sudo docker run -v $PWD:/corsika -it corsika/devel:clang-8 /bin/bash
+ mkdir build
+ cd build
+ cmake ../corsika -DCMAKE_INSTALL_PREFIX=../corsika-install
+ make -j8
+ make install
+
+Runing Unit Tests
+-----------------
+
+Note, before you run *any* executbale you must also define the
+:code:`CORSIKA_DATA` environment variable to point to the location where you
+cloned corsika :code:`modules/data`, thus typically
+::
+
+ export CORSIKA_DATA=$PWD/../corsika/modules/data
+
+To run the Unit Tests, just type :code:`ctest` in your build area.
+
+
+Running examples
+----------------
+
+To see how a relatively simple hadron cascade develops,
+see :code:`examples/cascade_example.cpp` for a starting point.
+
+To run the cascade_example, or any other CORSIKA 8 application, you
+must first compile it wrt. to the CORSIKA 8 header-only framework. This
+can be done best by copying
+e.g. :code:`corsika-install/share/corsika/examples/` to your working place
+(e.g. :code:`corsika-work`).
+
+Next, you need to define the environment variable :code:`corsika_DIR` to point to, either,
+your build, or your install area. Thus, e.g.
+::
+
+ export corsika_DIR=<dir where you installed CORSIKA 8 to, or where you buld it">
+
+Then compile your example/application with
+::
+
+ cd corsika-work
+ cmake .
+ make
+ bin/cascade_example
+
+Visualize output (needs gnuplot installed):
+::
+
+ bash $corsika_DIR/share/corsika/tools/plot_tracks.sh tracks.dat
+ firefox tracks.dat.gif
+
+(note, if you use the corsika_DIR to point to the build area: the script :code:`plot_tracks.sh` is
+not copied to the build area, it is only part of the source tree at :code:`tools/plot_tracks.sh`)
+
+Or also consider the :code:`vertical_EAS` example in the same directory,
+which can be configured with command line options.
+Run :code:`bin/vertical_EAS` to get basic help.
+
+
+Generating doxygen documentation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To generate the documentation, you need doxygen and graphviz. If you work with
+the docker corsika/devel containers this is already included.
+Otherwise, e.g. on Ubuntu 18.04, do:
+::
+
+ sudo apt-get install doxygen graphviz
+
+Switch to the corsika build directory and do
+::
+
+ make doxygen
+ make install
+
+open with firefox:
+::
+
+ firefox ../corsika-install/share/corsika/doc/html/index.html
diff --git a/corsika/detail/framework/process/InteractionProcess.hpp b/corsika/detail/framework/process/InteractionProcess.hpp
new file mode 100644
index 0000000000000000000000000000000000000000..ed67fed3df2c7a8cbe9054ac08d83f5c6d5411e0
--- /dev/null
+++ b/corsika/detail/framework/process/InteractionProcess.hpp
@@ -0,0 +1,78 @@
+#pragma once
+
+namespace corsika {
+
+ namespace detail {
+
+ /**
+ Helper traits class (partial) for static compile time checking.
+
+ Note, this is a poor replacement for C++20 concepts... they are
+ eagerly awaited!
+
+ It defines the default body of a generic test function returning
+ std::false_type.
+
+ In addition it defines the pattern for class-method matching with a
+ return type TReturn and function arguments TArgs... . Right now
+ both method signatures, "const" and "not const", are matched.
+ */
+ template <typename TReturn, typename... TArgs>
+ struct has_method_signature {
+
+ template <class T>
+ static std::true_type testSignature(TReturn (T::*)(TArgs&&...));
+
+ template <class T>
+ static std::true_type testSignature(TReturn (T::*)(TArgs&&...) const);
+
+ template <class T>
+ static std::false_type test(...);
+ };
+
+ } // namespace detail
+
+ template <class TProcess, typename TReturn, typename... TArgs>
+ struct has_method_doInteract : public detail::has_method_signature<TReturn, TArgs...> {
+
+ using detail::has_method_signature<TReturn, TArgs...>::testSignature;
+
+ template <class T>
+ static decltype(testSignature(&T::template doInteraction<TArgs...>)) test(
+ std::nullptr_t);
+
+ template <class T>
+ static decltype(testSignature(&T::doInteraction)) test(std::nullptr_t);
+
+ public:
+ using type = decltype(test<std::decay_t<TProcess>>(nullptr));
+ static const bool value = type::value;
+ };
+
+ template <class TProcess, typename TReturn, typename... TArgs>
+ bool constexpr has_method_doInteract_v =
+ has_method_doInteract<TProcess, TReturn, TArgs...>::value;
+
+ template <class TProcess, typename TReturn, typename... TArgs>
+ struct has_method_getInteractionLength
+ : public detail::has_method_signature<TReturn, TArgs...> {
+
+ using detail::has_method_signature<TReturn, TArgs...>::testSignature;
+
+ template <class T>
+ static decltype(testSignature(&T::template getInteractionLength<TArgs...>)) test(
+ std::nullptr_t);
+
+ template <class T>
+ static decltype(testSignature(&T::getInteractionLength)) test(std::nullptr_t);
+
+ public:
+ using type = decltype(test<std::decay_t<TProcess>>(nullptr));
+ static const bool value = type::value;
+ };
+
+ template <class TProcess, typename TReturn, typename... TArgs>
+ bool constexpr has_method_getInteractionLength_v =
+ has_method_getInteractionLength<TProcess, TReturn, TArgs...>::value;
+
+} // namespace corsika
diff --git a/corsika/detail/framework/process/ProcessSequence.inl b/corsika/detail/framework/process/ProcessSequence.inl
index b93331d05079962f5e710ac8de952935eb289517..d1ba0a0ce4723fb64aa554912eaa1456d88f9dd8 100644
--- a/corsika/detail/framework/process/ProcessSequence.inl
+++ b/corsika/detail/framework/process/ProcessSequence.inl
@@ -181,7 +181,7 @@ namespace corsika {
[[maybe_unused]] InverseGrammageType lambda_inv_select,
[[maybe_unused]] InverseGrammageType lambda_inv_sum) {
- // TODO: add check for lambda_inv_select>lambda_inv_tot
+ // TODO: add check for lambda_inv_select > lambda_inv_tot
if constexpr (t1ProcSeq) {
// if A is a process sequence --> check inside
@@ -195,7 +195,14 @@ namespace corsika {
lambda_inv_sum += A_.getInverseInteractionLength(view.parent());
// check if we should execute THIS process and then EXIT
if (lambda_inv_select <= lambda_inv_sum) {
- A_.doInteraction(view);
+
+ // interface checking on TProcess1
+ static_assert(has_method_doInteract_v<TProcess1, void, TSecondaryView&>,
+ "TDerived has no method with correct signature \"void "
+ "doInteraction(TSecondaryView&)\" required for "
+ "InteractionProcess<TDerived>. ");
+
+ A_.template doInteraction(view);
return ProcessReturn::Interacted;
}
} // end branch A
@@ -210,6 +217,13 @@ namespace corsika {
// soon as SecondaryView::parent() is migrated!
// check if we should execute THIS process and then EXIT
if (lambda_inv_select <= lambda_inv_sum) {
+
+ // interface checking on TProcess1
+ static_assert(has_method_doInteract_v<TProcess2, void, TSecondaryView&>,
+ "TDerived has no method with correct signature \"void "
+ "doInteraction(TSecondaryView&)\" required for "
+ "InteractionProcess<TDerived>. ");
+
B_.doInteraction(view);
return ProcessReturn::Interacted;
}
diff --git a/corsika/detail/modules/TrackWriter.inl b/corsika/detail/modules/TrackWriter.inl
index 6d4ef2c737decc093430821d0b8663867f93723b..ebd52339e72eddde23f1f50dc66e709712165963 100644
--- a/corsika/detail/modules/TrackWriter.inl
+++ b/corsika/detail/modules/TrackWriter.inl
@@ -31,7 +31,7 @@ namespace corsika {
}
template <typename TParticle, typename TTrack>
- inline ProcessReturn TrackWriter::doContinuous(const TParticle& vP, const TTrack& vT,
+ inline ProcessReturn TrackWriter::doContinuous(TParticle const& vP, TTrack const& vT,
bool const) {
auto const start = vT.getPosition(0).getCoordinates();
auto const delta = vT.getPosition(1).getCoordinates() - start;
@@ -54,7 +54,7 @@ namespace corsika {
}
template <typename TParticle, typename TTrack>
- inline LengthType TrackWriter::getMaxStepLength(const TParticle&, const TTrack&) {
+ inline LengthType TrackWriter::getMaxStepLength(TParticle const&, TTrack const&) {
return meter * std::numeric_limits<double>::infinity();
}
diff --git a/corsika/framework/core/Cascade.hpp b/corsika/framework/core/Cascade.hpp
index 64c4c065e01fd6bf08bf394605c04285a914c09a..4b2b1b99093e8f28e84201f8ac9409376f765eeb 100644
--- a/corsika/framework/core/Cascade.hpp
+++ b/corsika/framework/core/Cascade.hpp
@@ -90,8 +90,9 @@ namespace corsika {
, sequence_(pl)
, stack_(stack) {
CORSIKA_LOG_INFO(c8_ascii_);
+ CORSIKA_LOG_INFO("Tracking algorithm: {} (version {})", TTracking::getName(), TTracking::getVersion());
if constexpr (TStackView::has_event) {
- CORSIKA_LOG_INFO(" - With full cascade HISTORY.");
+ CORSIKA_LOG_INFO("Stack - with full cascade HISTORY.");
}
}
//! \}
diff --git a/corsika/framework/core/Logging.hpp b/corsika/framework/core/Logging.hpp
index 2daea27c596be86c039f31f7a0b608e28d47ff4e..67f059c2fe6d1dc5d4b228e551f4ebbbcd1acf9e 100644
--- a/corsika/framework/core/Logging.hpp
+++ b/corsika/framework/core/Logging.hpp
@@ -7,7 +7,7 @@
*/
/**
- * @File Logging.hpp
+ * @file Logging.hpp
*
* CORSIKA8 logging utilities.
*
diff --git a/corsika/framework/core/ParticleProperties.hpp b/corsika/framework/core/ParticleProperties.hpp
index e133d68679c27bc597050a46d84c5bba2bfed70e..51f2b4a785121b5f814c9ed6ea28766997e48d8a 100644
--- a/corsika/framework/core/ParticleProperties.hpp
+++ b/corsika/framework/core/ParticleProperties.hpp
@@ -10,11 +10,6 @@
@file ParticleProperties.hpp
Interface to particle properties
-
- The properties of all particles are saved in static and flat
- arrays. There is a enum corsika::Code to identify each
- particles, and each individual particles has its own static class,
- which can be used to retrieve its physical properties.
*/
#pragma once
@@ -29,21 +24,46 @@
#include <corsika/framework/core/PhysicalUnits.hpp>
+
+namespace corsika {
+
/**
- * \file ParticleProperties.hpp
- *
- * The properties of all elementary particles are accessible here. The data
- * are taken from the Pythia ParticleData.xml file.
- *
+ @defgroup Particles Particle Properties
+
+ The properties of all particles are saved in static and flat
+ arrays. There is a enum corsika::Code to identify each
+ particles, and each individual particles has its own static class,
+ which can be used to retrieve its physical properties.
+
+ The properties of all elementary particles are accessible here. The data
+ are taken from the Pythia ParticleData.xml file.
+
+ Particle data can be accessed via global function in namespace corsika, or via
+ static classes for each particle type. These classes all have the interface (example for
+ the class corsika::Electron):
+
+ @code{.cpp}
+ static constexpr Code code{Code::Electron};
+ static constexpr Code anti_code{Code::Positron};
+ static constexpr HEPMassType mass{corsika::get_mass(code)};
+ static constexpr ElectricChargeType charge{corsika::get_charge(code)};
+ static constexpr int charge_number{corsika::get_charge_number(code)};
+ static constexpr std::string_view name{corsika::get_name(code)};
+ static constexpr bool is_nucleus{corsika::is_nucleus(code)};
+ @endcode
+
+ The names, relations and properties of all particles known to CORSIKA 8 are listed below.
+
+ @addtogroup Particles
+ @{
*/
-namespace corsika {
- /**
- * @enum Code
- * The Code enum is the actual place to define CORSIKA 8 particle codes.
- */
+ /** The Code enum is the actual place to define CORSIKA 8 particle codes. */
enum class Code : int16_t;
+
+ /** Specifically for PDG ids */
enum class PDGCode : int32_t;
+
using CodeIntType = std::underlying_type<Code>::type;
using PDGCodeType = std::underlying_type<PDGCode>::type;
@@ -92,6 +112,9 @@ namespace corsika {
//! the output stream operator for human-readable particle codes
std::ostream& operator<<(std::ostream&, corsika::Code);
+
+ /** @}*/
+
} // namespace corsika
// data arrays, etc., as generated automatically
@@ -101,3 +124,4 @@ namespace corsika {
// constants in namespaces-like static classes, generated automatically
#include <corsika/framework/core/GeneratedParticleClasses.inc>
+
diff --git a/corsika/framework/process/BaseProcess.hpp b/corsika/framework/process/BaseProcess.hpp
index b8c96a54faa504a84c79272ce23f67534b6950b8..77ccc2d10d1e2c1e51756f5a1f68fb0511e0bd2b 100644
--- a/corsika/framework/process/BaseProcess.hpp
+++ b/corsika/framework/process/BaseProcess.hpp
@@ -17,11 +17,14 @@ namespace corsika {
class TDerived; // fwd decl
/**
+ @ingroup Processes
+ @{
+
Each process in C8 must derive from BaseProcess
The structural base type of a process object in a
ProcessSequence. Both, the ProcessSequence and all its elements
- are of type BaseProcess<T>
+ are of type BaseProcess
\todo rename BaseProcess into just Process
\todo rename _BaseProcess, or find better alternative in FIXME
@@ -67,4 +70,6 @@ namespace corsika {
static unsigned int constexpr count = N + 1;
};
+ //! @}
+
} // namespace corsika
diff --git a/corsika/framework/process/BoundaryCrossingProcess.hpp b/corsika/framework/process/BoundaryCrossingProcess.hpp
index 1e9a4bdee4eb3de6de009e7a1274bddb3e967d2a..2ea1c1c186d308ce7f31f82c3aad18ef4c516c8b 100644
--- a/corsika/framework/process/BoundaryCrossingProcess.hpp
+++ b/corsika/framework/process/BoundaryCrossingProcess.hpp
@@ -15,15 +15,11 @@
namespace corsika {
- /*
- struct passepartout {
- template <typename T>
- operator T&();
-
- template <typename T>
- operator T &&();
- };*/
-
+ /** @ingroup Processes
+ @{
+ */
+
+
template <typename TDerived>
class BoundaryCrossingProcess : public BaseProcess<TDerived> {
@@ -42,4 +38,6 @@ namespace corsika {
typename TParticle::node_type const& to);
};
+ //! @}
+
} // namespace corsika
diff --git a/corsika/framework/process/ContinuousProcess.hpp b/corsika/framework/process/ContinuousProcess.hpp
index 51d73d332fbe00ea3c5845608a0c582f224d5b4c..23321bfe6e73e3d642b1fc174a7f54cddd625ea5 100644
--- a/corsika/framework/process/ContinuousProcess.hpp
+++ b/corsika/framework/process/ContinuousProcess.hpp
@@ -16,6 +16,9 @@
namespace corsika {
/**
+ @ingroup Processes
+ @{
+
Processes with continuous effects along a particle Trajectory
The structural base type of a process object in a
@@ -67,4 +70,6 @@ namespace corsika {
enum { count = N + 1 };
};
+ /** @} */
+
} // namespace corsika
diff --git a/corsika/framework/process/ContinuousProcessIndex.hpp b/corsika/framework/process/ContinuousProcessIndex.hpp
index 9d6e84d0f39baaa9a1e0ad7dbf369aba6a967fb3..e74f0844b369a9003f46167a937165f5a5c4a231 100644
--- a/corsika/framework/process/ContinuousProcessIndex.hpp
+++ b/corsika/framework/process/ContinuousProcessIndex.hpp
@@ -11,9 +11,11 @@
namespace corsika {
/**
- * To index individual processes (continuous processes) inside a
- * ProcessSequence.
- *
+ @ingroup Processes
+
+ To index individual processes (continuous processes) inside a
+ ProcessSequence.
+
**/
class ContinuousProcessIndex {
diff --git a/corsika/framework/process/ContinuousProcessStepLength.hpp b/corsika/framework/process/ContinuousProcessStepLength.hpp
index 32b921857aaf6762c584ac5bf68b6885c019e038..201e20783d8551c0fe2de42b487eeaa242ec2488 100644
--- a/corsika/framework/process/ContinuousProcessStepLength.hpp
+++ b/corsika/framework/process/ContinuousProcessStepLength.hpp
@@ -14,9 +14,11 @@
namespace corsika {
/**
- * To store step length in LengthType and unique index in ProcessSequence of shortest
- * step ContinuousProcess.
- *
+ @ingroup Processes
+
+ To store step length in LengthType and unique index in ProcessSequence of shortest
+ step ContinuousProcess.
+
**/
class ContinuousProcessStepLength {
diff --git a/corsika/framework/process/DecayProcess.hpp b/corsika/framework/process/DecayProcess.hpp
index 64298dc3442176149f6cd7747219f7d2a9bac482..198cafe059388a67696fb4eeb08e3c6cdd5db3ca 100644
--- a/corsika/framework/process/DecayProcess.hpp
+++ b/corsika/framework/process/DecayProcess.hpp
@@ -14,6 +14,9 @@
namespace corsika {
/**
+ @ingroup Processes
+ @{
+
Process decribing the decay of particles
The structural base type of a process object in a
@@ -41,4 +44,6 @@ namespace corsika {
}
};
+ /** @} */
+
} // namespace corsika
diff --git a/corsika/framework/process/InteractionCounter.hpp b/corsika/framework/process/InteractionCounter.hpp
index 143fa430e79fea07937c67117646e79919f61f06..2659873824bbb22e4cd096a615b1fafac293daf1 100644
--- a/corsika/framework/process/InteractionCounter.hpp
+++ b/corsika/framework/process/InteractionCounter.hpp
@@ -14,6 +14,9 @@
namespace corsika {
/*!
+ @ingroup Processes
+ @{
+
* Wrapper around an InteractionProcess that fills histograms of the number
* of calls to DoInteraction() binned in projectile energy (both in
* lab and center-of-mass frame) and species
@@ -33,11 +36,15 @@ namespace corsika {
InteractionHistogram const& getHistogram() const;
+ void blob(int) {}
+
private:
TCountedProcess& process_;
InteractionHistogram histogram_;
};
+ //! @}
+
} // namespace corsika
#include <corsika/detail/framework/process/InteractionCounter.inl>
diff --git a/corsika/framework/process/InteractionHistogram.hpp b/corsika/framework/process/InteractionHistogram.hpp
index ab0fee8fd299a36d3f150db1e8d0f1213a615315..2138eb1541c03a482a4a5b48be49466cf6ff0614 100644
--- a/corsika/framework/process/InteractionHistogram.hpp
+++ b/corsika/framework/process/InteractionHistogram.hpp
@@ -23,6 +23,10 @@
namespace corsika {
+ /** @ingroup Processes
+ @{
+ */
+
class InteractionHistogram {
static double constexpr lower_edge_cms = 1e3, upper_edge_cms = 1e17; // eV sqrt s
static double constexpr lower_edge_lab = 1e3, upper_edge_lab = 1e21; // eV lab
@@ -47,6 +51,8 @@ namespace corsika {
InteractionHistogram operator+(InteractionHistogram other) const;
};
+ /** @} */
+
} // namespace corsika
#include <corsika/detail/framework/process/InteractionHistogram.inl> // for implementation
diff --git a/corsika/framework/process/InteractionProcess.hpp b/corsika/framework/process/InteractionProcess.hpp
index f80480926c74b5f908e3fe7b4c85643a30cfeadd..1cbddf005b62e8016737d7073ce1e226deba15d0 100644
--- a/corsika/framework/process/InteractionProcess.hpp
+++ b/corsika/framework/process/InteractionProcess.hpp
@@ -11,34 +11,62 @@
#include <corsika/framework/process/BaseProcess.hpp>
#include <corsika/framework/core/PhysicalUnits.hpp>
+#include <corsika/detail/framework/process/InteractionProcess.hpp> // for extra traits, method/interface checking
+
namespace corsika {
/**
+ @ingroup Processes
+ @{
+
Process describing the interaction of particles
- The structural base type of a process object in a
- ProcessSequence. Both, the ProcessSequence and all its elements
- are of type InteractionProcess<T>
+ The structural base type for any interaction process in a
+ ProcessSequence.
+
+ Create a new InteractionProcess, e.g. for XYModel, via
+ \code
+ class XYModel : public InteractionProcess<XYModel> {};
+ \endcode
+
+ and provide the two necessary interface methods
+ \code
+ template <typename TSecondaryView>
+ void doInteraction(TSecondaryView&);
+
+ template <typename TParticle>
+ GrammageType getInteractionLength(TParticle const&)
+ \endcode
+
+ Where, of course, SecondaryView and Particle are the valid
+ classes to access particles on the Stack. Those two methods do
+ not need to be templated, they could use the types
+ e.g. corsika::setup::Stack::particle_type -- but by the cost of
+ loosing all flexibility otherwise provided.
+ (For your potential interest, InteractionProcess is based on the
+ CRTP C++ design pattern)
*/
template <typename TDerived>
class InteractionProcess : public BaseProcess<TDerived> {
+
public:
using BaseProcess<TDerived>::ref;
- /// here starts the interface-definition part
- // -> enforce TDerived to implement DoInteraction...
- template <typename TParticle>
- void doInteraction(TParticle&);
-
- template <typename TParticle>
- GrammageType getInteractionLength(TParticle const&);
-
template <typename TParticle>
InverseGrammageType getInverseInteractionLength(TParticle const& particle) {
+
+ // interface checking on TProcess1
+ static_assert(has_method_getInteractionLength_v<TDerived, GrammageType, TParticle const&>,
+ "TDerived has no method with correct signature \"GrammageType "
+ "getInteractionLength(TParticle const&)\" required for "
+ "InteractionProcess<TDerived>. ");
+
return 1. / ref().getInteractionLength(particle);
}
};
+ /** @} */
+
} // namespace corsika
diff --git a/corsika/framework/process/NullModel.hpp b/corsika/framework/process/NullModel.hpp
index 0e4746f31a924f4bf597f93eada980696d493efb..c7fb1f344562aec901c17ed37f97c1d69d42bce4 100644
--- a/corsika/framework/process/NullModel.hpp
+++ b/corsika/framework/process/NullModel.hpp
@@ -13,7 +13,10 @@
namespace corsika {
/**
- * Process that does nothing
+ @ingroup Processes
+ @{
+
+ Process that does nothing
*/
class NullModel : public BaseProcess<NullModel> {
@@ -23,4 +26,6 @@ namespace corsika {
~NullModel() = default;
};
+ //! @}
+
} // namespace corsika
diff --git a/corsika/framework/process/ProcessReturn.hpp b/corsika/framework/process/ProcessReturn.hpp
index eef7058d09c171df53686fb4850a77d9e92c91c5..a7d522195d84ffa5a41dbd0637327cdf2345f3e9 100644
--- a/corsika/framework/process/ProcessReturn.hpp
+++ b/corsika/framework/process/ProcessReturn.hpp
@@ -15,6 +15,9 @@
namespace corsika {
/**
+ @ingroup
+ @{
+
since in a process sequence many status updates can accumulate
for a single particle, this enum should define only bit-flags
that can be accumulated easily with "|="
@@ -59,4 +62,6 @@ namespace corsika {
return static_cast<int>(a & ProcessReturn::Interacted);
}
+ //! @}
+
} // namespace corsika
diff --git a/corsika/framework/process/ProcessSequence.hpp b/corsika/framework/process/ProcessSequence.hpp
index 30c270bcbf30acaf0c8a539aada621eb0618886e..79d5dc53e93d86f39fc9b9ab9a2799039fbc7ad1 100644
--- a/corsika/framework/process/ProcessSequence.hpp
+++ b/corsika/framework/process/ProcessSequence.hpp
@@ -9,7 +9,7 @@
#pragma once
/**
- * \file ProcessSequence.hpp
+ * @file ProcessSequence.hpp
*/
#include <corsika/framework/process/BaseProcess.hpp>
@@ -28,6 +28,7 @@
namespace corsika {
+ // traits class to statically count processes in the sequence
template <typename TProcess, int N>
struct count_continuous<TProcess, N,
typename std::enable_if_t<is_process_sequence_v<TProcess>>> {
@@ -35,6 +36,7 @@ namespace corsika {
N + std::decay_t<TProcess>::getNumberOfProcesses();
};
+ // traits class to statically count processes in the sequence
template <typename TProcess, int N>
struct count_processes<TProcess, N,
typename std::enable_if_t<is_process_v<TProcess> &&
@@ -43,6 +45,27 @@ namespace corsika {
N + std::decay_t<TProcess>::getNumberOfProcesses();
};
+
+/**
+ @defgroup Processes Physics Processes and Modules
+
+ Physics processes in CORSIKA 8 are clustered in ProcessSequence and SwitchProcessSequence containers.
+ The former is a mere (ordered) collection, while the latter has the option to switch between two
+ alternative ProcessSequences.
+
+ Depending on the type of data to act on and on the allowed actions of processes there are several
+ interface options:
+ - InteractionProcess
+ - DecayProcess
+ - ContinuousProcess
+ - StackProcess
+ - SecondariesProcess
+
+ @ingroup Processes
+ @{
+ */
+
+
/**
*
* Definition of a static process list/sequence
@@ -63,7 +86,7 @@ namespace corsika {
* - TProcess1 is of type BaseProcess, either a dedicatd process, or a ProcessSequence
* - TProcess2 is of type BaseProcess, either a dedicatd process, or a ProcessSequence
* - ProcessIndexOffset, IndexOfProcess1, IndexOfProcess2 are to count and index each
- *ContinuousProcess in the entire process-chain
+ * ContinuousProcess in the entire process-chain
**/
template <typename TProcess1, typename TProcess2 = NullModel,
@@ -195,27 +218,27 @@ namespace corsika {
};
/**
- * Factory function to create ProcessSequence
- *
- * to construct ProcessSequences in a flexible and dynamic way the
- * `sequence` factory functions are provided
- *
- * Any objects of type
- * - BaseProcess,
- * - ContinuousProcess, and
- * - Interaction/DecayProcess,
- * - StackProcess,
- * - SecondariesProcess
- * can be assembled into a ProcessSequence, all
- * combinatorics are allowed.
-
- * The sequence function checks that all its arguments are all of
- * types derived from BaseProcess. Also the ProcessSequence itself
- * is derived from type BaseProcess
- *
- * \param vA needs to derive from BaseProcess or ProcessSequence
- * \param vB paramter-pack, needs to derive BaseProcess or ProcessSequence
- *
+ Factory function to create a ProcessSequence
+
+ to construct ProcessSequences in a flexible and dynamic way the
+ `sequence` factory functions are provided
+
+ Any objects of type
+ - BaseProcess,
+ - ContinuousProcess, and
+ - InteractionProcess/DecayProcess,
+ - StackProcess,
+ - SecondariesProcess
+ can be assembled into a ProcessSequence, all
+ combinatorics are allowed.
+
+ The sequence function checks that all its arguments are all of
+ types derived from BaseProcess. Also the ProcessSequence itself
+ is derived from type BaseProcess
+
+ \param vA needs to derive from BaseProcess or ProcessSequence
+ \param vB paramter-pack, needs to derive BaseProcess or ProcessSequence
+
**/
template <typename... TProcesses, typename TProcess1>
@@ -270,6 +293,8 @@ namespace corsika {
is_process_sequence() {}
};
+ /** @} */
+
} // namespace corsika
#include <corsika/detail/framework/process/ProcessSequence.inl>
diff --git a/corsika/framework/process/SecondariesProcess.hpp b/corsika/framework/process/SecondariesProcess.hpp
index daa45cc396f817e623ef107c9fdffd24099b8cbe..2146ba5a03862d79145757ae5dfb006930fd7480 100644
--- a/corsika/framework/process/SecondariesProcess.hpp
+++ b/corsika/framework/process/SecondariesProcess.hpp
@@ -14,12 +14,13 @@
namespace corsika {
/**
+ @ingroup Processes
+ @{
Process that modifies a list of secondaries of other processes
The structural base type of a process object in a
ProcessSequence. Both, the ProcessSequence and all its elements
are of type SecondariesProcess<T>
-
*/
template <typename TDerived>
@@ -31,4 +32,6 @@ namespace corsika {
void doSecondaries(TSecondaries&);
};
+ //! @}
+
} // namespace corsika
diff --git a/corsika/framework/process/StackProcess.hpp b/corsika/framework/process/StackProcess.hpp
index 7bf23c82c4b5e5a380e64ee8a3eb8632c0d2be2b..d1a748cd0d47781000e9bfae126e3a98d339cfe3 100644
--- a/corsika/framework/process/StackProcess.hpp
+++ b/corsika/framework/process/StackProcess.hpp
@@ -14,6 +14,9 @@
namespace corsika {
/**
+ @ingroup Processes
+ @{
+
Process to act on the entire particle stack
The structural base type of a process object in a
@@ -51,4 +54,6 @@ namespace corsika {
//! @}
};
+ //! @}
+
} // namespace corsika
diff --git a/corsika/framework/process/SwitchProcessSequence.hpp b/corsika/framework/process/SwitchProcessSequence.hpp
index 22da0facc5c5df27f38e03fadf02db014138cd60..275df81d4c13fc6e3fa2960c65653f06132f07a0 100644
--- a/corsika/framework/process/SwitchProcessSequence.hpp
+++ b/corsika/framework/process/SwitchProcessSequence.hpp
@@ -31,11 +31,17 @@
namespace corsika {
/**
+ @ingroup Processes
+ @{
+
* enum for the process switch selection: identify if First or
* Second process branch should be used.
**/
- enum class SwitchResult { First, Second };
-
+ enum class SwitchResult { First, /// Follow first branch in SwitchProcessSequence
+ Second /// Follow second branch in
+ /// SwitchProcessSequence
+ };
+
/**
Class to switch between two process branches
@@ -64,7 +70,7 @@ namespace corsika {
- IndexFirstProcess, IndexOfProcess1, IndexOfProcess2 are to count and index each
ContinuousProcess in the entire process-chain
- See also class \sa ProcessSequence
+ See also class ProcessSequence
**/
template <typename TProcess1, typename TProcess2, typename TSelect,
@@ -120,7 +126,7 @@ namespace corsika {
*
* \param in_A process branch A
* \param in_A process branch B
- * \param sel functor to swtich between branch A and B
+ * \param sel functor to switch between branch A and B
**/
SwitchProcessSequence(TProcess1 in_A, TProcess2 in_B, TSelect sel)
: select_(sel)
@@ -185,14 +191,13 @@ namespace corsika {
};
/**
- *
* the functin `make_select(proc1,proc1,selector)` assembles many
* BaseProcesses, and ProcessSequences into a SwitchProcessSequence,
- * all combinatorics must be allowed, this is why we define a macro
- * to define all combinations here:
- *
+ * all combinatorics are allowed.
*
- * Both, Processes1 and Processes2, must derive from BaseProcesses
+ * \param vA needs to derive from BaseProcess or ProcessSequence
+ * \param vB needs to derive from BaseProcess or ProcessSequence
+ * \param selector must provide `SwitchResult operator()(const Particle&) const`
**/
template <typename TProcess1, typename TProcess2, typename TSelect>
@@ -203,6 +208,8 @@ namespace corsika {
return SwitchProcessSequence<TProcess1, TProcess2, TSelect>(vA, vB, selector);
}
+ //! @}
+
} // namespace corsika
#include <corsika/detail/framework/process/SwitchProcessSequence.inl>
diff --git a/corsika/media/MediumProperties.hpp b/corsika/media/MediumProperties.hpp
index 76434f1f710e3799b5fc74e25ad83334015ac834..ec1348c023666997978e8e5312ff7002178c39c2 100644
--- a/corsika/media/MediumProperties.hpp
+++ b/corsika/media/MediumProperties.hpp
@@ -11,12 +11,55 @@
namespace corsika {
/**
- * Medium types are useful most importantly for effective models
- * like energy losses. a particular medium (mixture of components)
- * may have specif properties not reflected by its mixture of
- * components.
- **/
+ @defgroup MediaProperties Media Properties
+
+ Medium types are useful most importantly for effective models
+ like energy losses. a particular medium (mixture of components)
+ may have specif properties not reflected by its mixture of
+ components.
+
+ The data provided here is automatically parsed from the file
+ properties8.dat from NIST.
+
+ The data of each known medium can be access via the global functions in namespace corsika,
+ or via a static class object with the following interface (here at the example of the class HydrogenGas):
+
+ @code{.cpp}
+ static constexpr Medium medium() { return Medium::HydrogenGas; }
+
+ static std::string const getName() { return data_.getName(); }
+ static std::string const getPrettyName() { return data_.getPrettyName(); }
+ static double getWeight() { return data_.getWeight (); }
+ static int weight_significant_figure() { return data_.weight_significant_figure (); }
+ static int weight_error_last_digit() { return data_.weight_error_last_digit(); }
+ static double Z_over_A() { return data_.Z_over_A(); }
+ static double getSternheimerDensity() { return data_.getSternheimerDensity(); }
+ static double getCorrectedDensity() { return data_.getCorrectedDensity(); }
+ static State getState() { return data_.getState(); }
+ static MediumType getType() { return data_.getType(); }
+ static std::string const getSymbol() { return data_.getSymbol(); }
+ static double getIeff() { return data_.getIeff(); }
+ static double getCbar() { return data_.getCbar(); }
+ static double getX0() { return data_.getX0(); }
+ static double getX1() { return data_.getX1(); }
+ static double getAA() { return data_.getAA(); }
+ static double getSK() { return data_.getSK(); }
+ static double getDlt0() { return data_.getDlt0(); }
+
+ inline static const MediumData data_ { "hydrogen_gas", "hydrogen gas (H%2#)", 1.008,
+ 3, 7, 0.99212,
+ 8.3748e-05, 8.3755e-05, State::DiatomicGas,
+ MediumType::Element, "H", 19.2, 9.5835, 1.8639, 3.2718, 0.14092, 5.7273, 0.0 };
+ @endcode
+
+ The numeric data known to CORSIKA 8 (and obtained from NIST) can be browsed below.
+
+ @ingroup MediaProperties
+ @{
+ */
+
+ //! General type of medium
enum class MediumType {
Unknown,
Element,
@@ -28,15 +71,16 @@ namespace corsika {
BiologicalDosimetry
};
+ //! Physical state of medium
enum class State { Unknown, Solid, Liquid, Gas, DiatomicGas };
enum class Medium : int16_t;
+
using MediumIntType = std::underlying_type<Medium>::type;
- /** \todo documentation needs update ...
- * \struct MediumData
+ /**
*
- * Simple object to group together a number of properties
+ * Simple object to group together the properties of a medium.
*
**/
struct MediumData {
@@ -59,25 +103,31 @@ namespace corsika {
double sk_;
double dlt0_;
- std::string getName() const { return name_; }
- std::string getPrettyName() const { return pretty_name_; }
- double getWeight() const { return weight_; }
- const int& weight_significant_figure() const { return weight_significant_figure_; }
- const int& weight_error_last_digit() const { return weight_error_last_digit_; }
- const double& Z_over_A() const { return Z_over_A_; }
- double getSternheimerDensity() const { return sternheimer_density_; }
- double getCorrectedDensity() const { return corrected_density_; }
- State getState() const { return state_; }
- MediumType getType() const { return type_; }
- std::string getSymbol() const { return symbol_; }
- double getIeff() const { return Ieff_; }
- double getCbar() const { return Cbar_; }
- double getX0() const { return x0_; }
- double getX1() const { return x1_; }
- double getAA() const { return aa_; }
- double getSK() const { return sk_; }
- double getDlt0() const { return dlt0_; }
+ //! @name MediumDataInterface Interface methods
+ //! Interface functions for MediumData
+ //! @{
+ std::string getName() const { return name_; } /// returns name
+ std::string getPrettyName() const { return pretty_name_; } /// returns pretty name
+ double getWeight() const { return weight_; } /// return weight
+ const int& weight_significant_figure() const { return weight_significant_figure_; } /// return significnat figures of weight
+ const int& weight_error_last_digit() const { return weight_error_last_digit_; } /// return error of weight
+ const double& Z_over_A() const { return Z_over_A_; } /// Z_over_A_
+ double getSternheimerDensity() const { return sternheimer_density_; } /// Sternheimer density
+ double getCorrectedDensity() const { return corrected_density_; } /// corrected density
+ State getState() const { return state_; } /// state
+ MediumType getType() const { return type_; } /// type
+ std::string getSymbol() const { return symbol_; } /// symbol
+ double getIeff() const { return Ieff_; } /// Ieff
+ double getCbar() const { return Cbar_; } /// Cbar
+ double getX0() const { return x0_; } /// X0
+ double getX1() const { return x1_; } /// X1
+ double getAA() const { return aa_; } /// AA
+ double getSK() const { return sk_; } /// Sk
+ double getDlt0() const { return dlt0_; } /// Delta0
+ //! @}
};
+
+ //! @}
} // namespace corsika
@@ -85,8 +135,19 @@ namespace corsika {
namespace corsika {
+ /**
+ @file MediaProperties.hpp
+
+ @ingroup MediaProperties
+ @{
+
+ Returns MediumData object for medium identifed by enum Medium.
+ */
+
constexpr MediumData const& mediumData(Medium const m) {
return corsika::detail::medium_data[static_cast<MediumIntType>(m)];
}
+ //! @}
+
} // namespace corsika
diff --git a/corsika/modules/qgsjetII/qgsjet-II-04.hpp b/corsika/modules/qgsjetII/qgsjet-II-04.hpp
index f95d011ae1c1a7784a40aef7012eb2d05e32a6cf..9d3b884fb71a5f0e15801f994021a325bdbaba49 100644
--- a/corsika/modules/qgsjetII/qgsjet-II-04.hpp
+++ b/corsika/modules/qgsjetII/qgsjet-II-04.hpp
@@ -60,40 +60,32 @@ void qgaini_(
const char* datdir); // Note: there is a length limiation 132 from fortran-qgsjet here
/**
- @function qgini_
-
additional initialization procedure per event
- @parameter e0n - interaction energy (per hadron/nucleon),
- @parameter icp0 - hadron type (+-1 - pi+-, +-2 - p(p~), +-3 - n(n~), +-4 - K+-, +-5 -
+ @param e0n - interaction energy (per hadron/nucleon),
+ @param icp0 - hadron type (+-1 - pi+-, +-2 - p(p~), +-3 - n(n~), +-4 - K+-, +-5 -
K_l/s),
- @parameter iap - projectile mass number (1 - for a hadron),
- @parameter iat - target mass number
+ @param iap - projectile mass number (1 - for a hadron),
+ @param iat - target mass number
*/
void qgini_(const double& e0n, const int& icp0, const int& iap, const int& iat);
/**
- @function qgconf_
-
generate one event configuration
*/
void qgconf_();
/**
- @function qgsect_
-
hadron-nucleus (hadron-nucleus) particle production cross section
- @parameter e0n lab. energy per projectile nucleon (hadron)
- @parameter icz hadron class (1 - pion, 2 - nucleon, 3 - kaon)
- @parameter iap projectile mass number (1=<iap<=iapmax),
- @parameter iat target mass number (1=<iat<=iapmax)
+ @param e0n lab. energy per projectile nucleon (hadron)
+ @param icz hadron class (1 - pion, 2 - nucleon, 3 - kaon)
+ @param iap projectile mass number (1=<iap<=iapmax),
+ @param iat target mass number (1=<iat<=iapmax)
*/
double qgsect_(const double& e0n, const int& icz, const int& iap0, const int& iat0);
/**
- @function qgran
-
link to random number generation
*/
double qgran_(int&);
diff --git a/corsika/modules/tracking/TrackingLeapFrogCurved.hpp b/corsika/modules/tracking/TrackingLeapFrogCurved.hpp
index 5eb28160818abf42f7a4a743165515f2254d89dc..d341559e7368a0fd940c30ad18bbe5a43e152662 100644
--- a/corsika/modules/tracking/TrackingLeapFrogCurved.hpp
+++ b/corsika/modules/tracking/TrackingLeapFrogCurved.hpp
@@ -30,7 +30,6 @@ namespace corsika {
/**
* \file TrackingLeapFrogCurved.hpp
- * \function LeapFrogStep
*
* Performs one leap-frog step consistent of two halve-steps with steplength/2
* The step is caluculated analytically precisely to reach to the next volume
@@ -54,8 +53,7 @@ namespace corsika {
using Intersect<Tracking>::nextIntersect;
public:
- Tracking()
- : straightTracking_{tracking_line::Tracking()} {}
+ Tracking() : straightTracking_{tracking_line::Tracking()} {}
template <typename TParticle>
auto getTrack(TParticle const& particle);
@@ -73,6 +71,9 @@ namespace corsika {
template <typename TParticle>
static Intersections intersect(TParticle const& particle, Plane const& plane);
+ static std::string getName() { return "LeapFrog-curved"; }
+ static std::string getVersion() { return "1.0.0"; }
+
protected:
/**
* Use internally stored class tracking_line::Tracking to
diff --git a/corsika/modules/tracking/TrackingLeapFrogStraight.hpp b/corsika/modules/tracking/TrackingLeapFrogStraight.hpp
index f54e355ba3ca568e75caff18be305bf665f73557..a57c68eb580656284556b0d11b7a4d6089e43234 100644
--- a/corsika/modules/tracking/TrackingLeapFrogStraight.hpp
+++ b/corsika/modules/tracking/TrackingLeapFrogStraight.hpp
@@ -60,6 +60,9 @@ namespace corsika {
template <typename Particle>
auto getTrack(Particle& particle);
+
+ static std::string getName() { return "LeapFrogStraight"; }
+ static std::string getVersion() { return "1.0.0"; }
protected:
double firstFraction_;
diff --git a/corsika/modules/tracking/TrackingStraight.hpp b/corsika/modules/tracking/TrackingStraight.hpp
index 4b498bfa522d5856b2251435a437c7ec42681687..2ca9dce6dd5605fcc827be83584db96602e5391f 100644
--- a/corsika/modules/tracking/TrackingStraight.hpp
+++ b/corsika/modules/tracking/TrackingStraight.hpp
@@ -51,7 +51,10 @@ namespace corsika::tracking_line {
//! find intersection of Plane with Track
template <typename TParticle>
static Intersections intersect(TParticle const& particle, Plane const& plane);
- };
+
+ static std::string getName() { return "Tracking-Straight"; }
+ static std::string getVersion() { return "1.0.0"; }
+};
} // namespace corsika::tracking_line
diff --git a/corsika/modules/urqmd/UrQMD.hpp b/corsika/modules/urqmd/UrQMD.hpp
index 52439d7234a287718c06a471859e8e35b31fe8fd..9d4a0c7d2251372cd5b084d9972d5a8bf3b079b3 100644
--- a/corsika/modules/urqmd/UrQMD.hpp
+++ b/corsika/modules/urqmd/UrQMD.hpp
@@ -35,6 +35,8 @@ namespace corsika::urqmd {
bool canInteract(Code) const;
+ void blob(int) {}
+
private:
static CrossSectionType getCrossSection(Code, Code, HEPEnergyType, int);
diff --git a/documentation/CMakeLists.txt b/documentation/CMakeLists.txt
index e62d3c71db4fb27081f910d7623a53eadf85c7bf..5e727190a8bb493e5b5a4f679226970303b084a1 100644
--- a/documentation/CMakeLists.txt
+++ b/documentation/CMakeLists.txt
@@ -1,5 +1,6 @@
find_package (Doxygen OPTIONAL_COMPONENTS dot mscgen dia)
-
+find_package (Sphinx)
+
if (DOXYGEN_FOUND)
if (NOT DOXYGEN_DOT_EXECUTABLE)
message (FATAL_ERROR "Found doxygen but not 'dot' command, please install graphviz or set DOXYGEN_DOT_EXECUTABLE")
@@ -10,23 +11,43 @@ if (DOXYGEN_FOUND)
set (DOXYGEN_GENERATE_HTML YES)
set (DOXYGEN_GENERATE_MAN YES)
configure_file (${DOXYGEN_IN} ${DOXYGEN_OUT} @ONLY)
- message ("Start doxygen with \"make doxygen\"")
+ message ("Start doxygen with \"make docs\"")
# note the option ALL which allows to build the docs together with the application
- add_custom_target (doxygen # ALL
+ add_custom_target (docs # ALL
COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_OUT}
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
COMMENT "Generating API documentation with Doxygen"
VERBATIM
)
- add_custom_command (TARGET doxygen POST_BUILD
+ add_custom_command (TARGET docs POST_BUILD
COMMAND cd ${CMAKE_CURRENT_BINARY_DIR}/latex; pdflatex refman.tex
)
install (DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html DESTINATION share/doc OPTIONAL)
install (FILES ${CMAKE_CURRENT_BINARY_DIR}/latex/refman.pdf DESTINATION share/doc OPTIONAL)
-
+
+ if (SPHINX_FOUND)
+
+ set (SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR})
+ set (SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/docs/sphinx)
+
+ add_custom_command (TARGET docs POST_BUILD
+ COMMAND ${SPHINX_EXECUTABLE} -b html
+ # Tell Breathe where to find the Doxygen output
+ -Dbreathe_projects.CORSIKA8=${CMAKE_CURRENT_BINARY_DIR}/xml/
+ ${SPHINX_SOURCE} ${SPHINX_BUILD}
+ WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+ COMMENT "Generating documentation with Sphinx"
+ )
+
+ else (SPHINX_FOUND)
+
+ message ("Sphinx not found;")
+
+ endif (SPHINX_FOUND)
+
else (DOXYGEN_FOUND)
message ("Doxygen need to be installed to generate the doxygen documentation")
diff --git a/documentation/Doxyfile.in b/documentation/Doxyfile.in
index 1378999e9fd140e792d576fdceefce4556bff5e4..ded50d6a5ee5068ce65aa1a15338654f98f3ec72 100644
--- a/documentation/Doxyfile.in
+++ b/documentation/Doxyfile.in
@@ -7,12 +7,12 @@ GENERATE_LATEX = YES
GENERATE_XML = YES
OUTPUT_DIRECTORY = @CMAKE_CURRENT_BINARY_DIR@/
-INPUT = @PROJECT_SOURCE_DIR@/corsika @PROJECT_SOURCE_DIR@/src
+INPUT = @PROJECT_SOURCE_DIR@/corsika @PROJECT_SOURCE_DIR@/src @CMAKE_BINARY_DIR@/corsika
EXCLUDE_PATTERNS = *.inl
FULL_PATH_NAMES = YES
STRIP_FROM_PATH = @PROJECT_SOURCE_DIR@
-FILE_PATTERNS = *.cpp *.hpp *.dox *.md
+FILE_PATTERNS = *.cpp *.hpp *.dox *.md *.inc
EXTENSION_MAPPING = inc=C++
RECURSIVE = YES
@@ -34,13 +34,16 @@ GENERATE_LEGEND = YES
USE_MATHJAX = YES
MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols
-#JAVADOC_BANNER = YES
+#JAVADOC_BANNER = YES
JAVADOC_AUTOBRIEF = YES
-REPEAT_BRIEF = YES
+REPEAT_BRIEF = YES
ABBREVIATE_BRIEF = YES
-MULTILINE_CPP_IS_BRIEF = YES
-MARKDOWN_SUPPORT = YES
-BUILTIN_STL_SUPPORT = YES
-CLANG_ASSISTED_PARSING = YES
+MULTILINE_CPP_IS_BRIEF = YES
+MARKDOWN_SUPPORT = YES
+BUILTIN_STL_SUPPORT = YES
+
+#CLANG_ASSISTED_PARSING = YES
+#CLANG_DATABASE_PATH = @CMAKE_CURRENT_BINARY_DIR@/
+#CLANG_OPTIONS = "-std=c++17"
SEARCHENGINE = YES
diff --git a/documentation/api.rst b/documentation/api.rst
new file mode 100644
index 0000000000000000000000000000000000000000..f8436257b4f5bfb33b642b0a7ac4bd452774634c
--- /dev/null
+++ b/documentation/api.rst
@@ -0,0 +1,11 @@
+Full API
+========
+
+Consider using Doxygen directly for a full API reference....
+
+..
+ .. doxygenindex::
+ :project: CORSIKA8
+ :path: c8
+ :outline:
+ :no-link:
diff --git a/documentation/conf.py b/documentation/conf.py
index 4693c2bface440831cbfa98257c9d57fc9c4fa91..61d0846303b392c07519a034ca58d3c77314ffab 100644
--- a/documentation/conf.py
+++ b/documentation/conf.py
@@ -1,6 +1,158 @@
-#...
-extensions = [ "breathe" ]
-#...
+import sys
+
+# sys.path.append( "/software/bDreathe-4.14.2/" )
+
+# -- Project information -----------------------------------------------------
+
+project = u'CORSIKA8'
+copyright = u'2021, CORSIKA 8 Collaboration'
+author = u'CORSIKA 8 Collaboration'
+
+# The short X.Y version
+version = u''
+# The full version, including alpha/beta/rc tags
+release = u'0.0.1'
+
+extensions = [
+ 'sphinx.ext.todo',
+ 'breathe',
+ 'sphinx.ext.mathjax',
+ 'sphinx.ext.autodoc',
+ 'sphinx.ext.extlinks',
+ 'sphinx.ext.autosummary',
+ 'sphinx.ext.napoleon',
+ 'recommonmark'
+]
+
+#breathe_projects = { "CORSIKA8": "/work/corsika/corsika/build/documentation/xml/" }
+breathe_default_project = "CORSIKA8"
+
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path .
+exclude_patterns = []
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further. For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself. Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'PROPOSALdoc'
+
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {
+ # The paper size ('letterpaper' or 'a4paper').
+ #
+ # 'papersize': 'letterpaper',
+
+ # The font size ('10pt', '11pt' or '12pt').
+ #
+ # 'pointsize': '10pt',
+
+ # Additional stuff for the LaTeX preamble.
+ #
+ # 'preamble': '',
+
+ # Latex figure (float) alignment
+ #
+ # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+# author, documentclass [howto, manual, or own class]).
+latex_documents = [
+ (master_doc, 'PROPOSAL.tex', u'PROPOSAL Documentation',
+ u'tudo-astroparticlephysics', 'manual'),
+]
+
+
+# -- Options for manual page output ------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+ (master_doc, 'proposal', u'PROPOSAL Documentation',
+ [author], 1)
+]
+
+
+# -- Options for Texinfo output ----------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+# dir menu entry, description, category)
+texinfo_documents = [
+ (master_doc, 'PROPOSAL', u'PROPOSAL Documentation',
+ author, 'PROPOSAL', 'One line description of project.',
+ 'Miscellaneous'),
+]
+
+
+# -- Extension configuration -------------------------------------------------
+
+napoleon_google_docstring = True
+napoleon_include_init_with_doc = True
+napoleon_use_keyword = True
+napoleon_use_param = True
+napoleon_use_rtype = False
+napoleon_use_admonition_for_examples = True
+# autodoc_docstring_signature=False
+
+
+
+
-# Breathe Configuration
-breathe_default_project = "CORSIKA 8"
diff --git a/documentation/index.rst b/documentation/index.rst
index 9ce3208119454075d818fa50ef5d4d02941efdb8..4f712f1076dc8141a7c47d4463421daf28046865 100644
--- a/documentation/index.rst
+++ b/documentation/index.rst
@@ -1,7 +1,20 @@
-…
+CORSIKA 8
+*********
-Docs
-====
+Welcome to the CORSIKA 8 air shower simulation framework.
+
+.. toctree::
+ :maxdepth: 2
+
+ readme_link
+ modules
+ particles
+ media
+ api
+
+
+..
+ .. doxygenclass:: corsika::Stack
+ :project: CORSIKA8
+ :members:
-.. doxygenstruct:: corsika
- :members:
diff --git a/documentation/media.rst b/documentation/media.rst
new file mode 100644
index 0000000000000000000000000000000000000000..484a9afa2389e962cf71d9723f8313771a7d9a1c
--- /dev/null
+++ b/documentation/media.rst
@@ -0,0 +1,9 @@
+Media Properties
+===================
+
+.. toctree::
+ media_classes
+
+.. doxygengroup:: MediaProperties
+ :project: CORSIKA8
+ :members:
diff --git a/documentation/media_classes.rst b/documentation/media_classes.rst
new file mode 100644
index 0000000000000000000000000000000000000000..0cd1607cc38d3d2ea8e5357e6bb6244e713e262f
--- /dev/null
+++ b/documentation/media_classes.rst
@@ -0,0 +1,7 @@
+Media Classes
+=============
+
+.. doxygengroup:: MediaPropertiesClasses
+ :project: CORSIKA8
+ :members:
+
diff --git a/documentation/modules.rst b/documentation/modules.rst
new file mode 100644
index 0000000000000000000000000000000000000000..bcb292faadf034b78507d07eedbebde8071525c5
--- /dev/null
+++ b/documentation/modules.rst
@@ -0,0 +1,9 @@
+Physics modules and processes
+=============================
+
+.. doxygengroup:: Processes
+ :project: CORSIKA8
+ :members:
+
+
+
diff --git a/documentation/particle_classes.rst b/documentation/particle_classes.rst
new file mode 100644
index 0000000000000000000000000000000000000000..63e184dc5017929e78d16bedeaa69476c2af76f3
--- /dev/null
+++ b/documentation/particle_classes.rst
@@ -0,0 +1,7 @@
+Particle Classes
+================
+
+.. doxygengroup:: ParticleClasses
+ :project: CORSIKA8
+ :members:
+
diff --git a/documentation/particles.rst b/documentation/particles.rst
new file mode 100644
index 0000000000000000000000000000000000000000..33f22f996ceebbd735665fc2d8d088e7e0b7dc7b
--- /dev/null
+++ b/documentation/particles.rst
@@ -0,0 +1,12 @@
+Particle Properties
+===================
+
+.. toctree::
+ particle_classes
+
+.. doxygengroup:: Particles
+ :project: CORSIKA8
+ :members:
+
+
+
diff --git a/documentation/readme_link.rst b/documentation/readme_link.rst
new file mode 100644
index 0000000000000000000000000000000000000000..72a33558153fb57def85612b021ec596ef2a51b9
--- /dev/null
+++ b/documentation/readme_link.rst
@@ -0,0 +1 @@
+.. include:: ../README.rst
diff --git a/examples/vertical_EAS.cpp b/examples/vertical_EAS.cpp
index 9f816ce19975a7be024ec08bfd4a8f82308e894f..e49030fe3fbff7e5a7ed277036a0707a81d2f359 100644
--- a/examples/vertical_EAS.cpp
+++ b/examples/vertical_EAS.cpp
@@ -104,7 +104,7 @@ int main(int argc, char** argv) {
CORSIKA_LOG_INFO("vertical_EAS");
if (argc < 5) {
- std::cerr << "usage: vertical_EAS <A> <Z> <energy/GeV> [seed] \n"
+ std::cerr << "usage: vertical_EAS <A> <Z> <energy/GeV> <Nevt> [seed] \n"
" if A=0, Z is interpreted as PDG code \n"
" if no seed is given, a random seed is chosen \n"
<< std::endl;
diff --git a/src/framework/core/pdxml_reader.py b/src/framework/core/pdxml_reader.py
index 2520cdfe4adb3f75bf316043425ca47e3e3742d7..31ea1d6a4ebbfb8f1f11422ee8dc21d5ca68ddc6 100755
--- a/src/framework/core/pdxml_reader.py
+++ b/src/framework/core/pdxml_reader.py
@@ -275,7 +275,8 @@ def gen_conversion_PDG_ngc(particle_db):
# return string with enum of all internal particle codes
#
def gen_internal_enum(particle_db):
- string = ("enum class Code : CodeIntType {\n"
+ string = ("//! @cond EXCLUDE_DOXY\n"
+ "enum class Code : CodeIntType {\n"
" FirstParticle = 1, // if you want to loop over particles, you want to start with \"1\" \n") # identifier for eventual loops...
@@ -284,7 +285,7 @@ def gen_internal_enum(particle_db):
string += " {key:s} = {code:d},\n".format(key = k, code = last_ngc_id)
string += (" LastParticle = {:d},\n" # identifier for eventual loops...
- "}};").format(last_ngc_id + 1)
+ "}}; //! @endcond").format(last_ngc_id + 1)
if last_ngc_id > 0x7fff: # does not fit into int16_t
raise Exception("Integer overflow in internal particle code definition prevented!")
@@ -297,13 +298,14 @@ def gen_internal_enum(particle_db):
# return string with enum of all PDG particle codes
#
def gen_pdg_enum(particle_db):
- string = "enum class PDGCode : PDGCodeType {\n"
+ string = ("//! @cond EXCLUDE_DOXY\n"
+ "enum class PDGCode : PDGCodeType {\n")
for cId in particle_db:
pdgCode = particle_db[cId]['pdg']
string += " {key:s} = {code:d},\n".format(key = cId, code = pdgCode)
- string += " };\n"
+ string += " }; //! @endcond \n"
return string
@@ -407,7 +409,9 @@ def gen_properties(particle_db):
#
def gen_classes(particle_db):
- string = "// list of C++ classes to access particle properties"
+ string = ("// list of C++ classes to access particle properties\n"
+ "/** @defgroup ParticleClasses \n"
+ " @{ */\n")
for cname in particle_db:
if cname == "Nucleus":
@@ -449,6 +453,8 @@ def gen_classes(particle_db):
string += " static constexpr CodeIntType TypeIndex = static_cast<CodeIntType>(code);\n"
string += "};\n"
+ string += " //! @}\n";
+
return string
@@ -459,7 +465,11 @@ def inc_start():
string = ('// generated by pdxml_reader.py\n'
'// MANUAL EDITS ON OWN RISK. THEY WILL BE OVERWRITTEN. \n'
'\n'
- 'namespace corsika {\n')
+ 'namespace corsika {\n'
+ '/** @ingroup Particles \n'
+ ' @{ \n'
+ ' */ \n'
+ )
return string
@@ -467,7 +477,8 @@ def inc_start():
#
#
def detail_start():
- string = ('namespace particle::detail {\n\n')
+ string = ('/** @cond EXCLUDE_DOXY */\n'
+ ' namespace particle::detail {\n\n')
return string
@@ -475,14 +486,14 @@ def detail_start():
#
#
def detail_end():
- string = "\n}//end namespace particle::detail\n"
+ string = "\n}//end namespace particle::detail\n /** @endcond */"
return string
###############################################################
#
#
def inc_end():
- string = "} // end namespace corsika"
+ string = "/** @} */\n} // end namespace corsika"
return string
diff --git a/src/media/readProperties.py b/src/media/readProperties.py
index 44eb3f839b068d7d26ca457f5d327cabec6b9591..13fdc4c628f6a114d0e531b2435aebdd8f4a1e27 100755
--- a/src/media/readProperties.py
+++ b/src/media/readProperties.py
@@ -219,6 +219,7 @@ def read_data(filename):
def gen_code(media_db):
string = """
+ /** @cond EXCLUDE_DOXY */
// enum for all media
enum class Medium : MediumIntType {
Unkown,
@@ -231,7 +232,7 @@ def gen_code(media_db):
imedium += 1
string += " {} = {} ,\n".format("First", 0)
string += " {} = {} ,\n".format("Last", imedium-1)
- string += " };\n\n"
+ string += " };/** @endcond */\n\n"
return string
@@ -242,11 +243,11 @@ def gen_code(media_db):
def gen_classes(media_db):
string = """
- // list of C++ classes to access media properties"
-
-// typedef std::map<std::string, double> Properties;
-// typedef std::array<Properties, static_cast<MediumIntType>(Medium::Last)+1> Constituents; this is wrong> num_elements
+ /** @defgroup MediaPropertiesClasses
+ list of C++ classes to access media properties
+ @{
+ */
"""
for entry in media_db:
@@ -278,10 +279,13 @@ def gen_classes(media_db):
class_string = """
/**
- * \class {cname}
+ * @class {cname}
*
* Media properties from properties8.dat file from NIST:
- * - Sternheimer index {stern_index}, label {stern_label}
+ * - Sternheimer index: {stern_index}, label: {stern_label}, name: {name}, nice_name: {nice_name}, symbol: {symbol}
+ * - weight: {weight}, weight_significant_figure: {weight_significant_figure}, weight_error_last_digit: {weight_error_last_digit}
+ * - Z_over_A: {Z_over_A}, sternheimhers_density: {sternheimer_density}, corrected_density: {corrected_density},
+ * - State::{state}, MediumType::{type}, Ieff={Ieff}, Cbar={Cbar}, X0={x0}, x1={x1}, aa={aa}, sk={sk}, dlt0={dlt0}
**/
class {cname} {{
@@ -342,32 +346,10 @@ def gen_classes(media_db):
properties=properties);
- # static std::string const name() {{ return "{name}"; }}
- # static std::string const pretty_name() {{ return "{nice_name}"; }}
- # static constexpr double weight() {{ return {weight} ; }}
- # static constexpr int weight_significant_figure() {{ return {weight_significant_figure} ; }}
- # static constexpr int weight_error_last_digit() {{ return {weight_error_last_digit}; }}
- # static constexpr double Z_over_A() {{ return {Z_over_A}; }}
- # static constexpr double sternheimer_density() {{ return {sternheimer_density}; }}
- # static constexpr double corrected_density() {{ return {corrected_density}; }}
- # static constexpr State state() {{ return State::{state}; }}
- # static constexpr MediumType type() {{ return MediumType::{type}; }}
- # static std::string const symbol() {{ return "{symbol}"; }}
-
- # static constexpr double Ieff() {{ return {Ieff}; }}
- # static constexpr double Cbar() {{ return {Cbar}; }}
- # static constexpr double x0() {{ return {x0}; }}
- # static constexpr double x1() {{ return {x1}; }}
- # static constexpr double aa() {{ return {aa}; }}
- # static constexpr double sk() {{ return {sk}; }}
- # static constexpr double dlt0() {{ return {dlt0}; }}
-
-
string += class_string
-
-# private:\n"
-# static constexpr CodeIntType TypeIndex = static_cast<CodeIntType const>(Type);\n"
+ string += " /** @} */"
+
return string
###############################################################
@@ -419,7 +401,9 @@ def inc_start():
#pragma once
namespace corsika {
-
+ /** @ingroup MediaProperties
+ @{
+ */
"""
return string
@@ -428,7 +412,8 @@ namespace corsika {
#
#
def detail_start():
- string = ('namespace detail {\n\n')
+ string = (' /** @} */ \n'
+ 'namespace detail {\n\n')
return string
diff --git a/tests/framework/testCascade.cpp b/tests/framework/testCascade.cpp
index 633f30f47328970be8374552ecbb86411aaa6936..b860e9955d3c3122c4295cdaa6f32875f9aa6021 100644
--- a/tests/framework/testCascade.cpp
+++ b/tests/framework/testCascade.cpp
@@ -77,6 +77,8 @@ public:
// trajectory: just go ahead forever
particle.getNode()); // next volume node
}
+ static std::string getName() { return "DummyTracking"; }
+ static std::string getVersion() { return "1.0.0"; }
};
class ProcessSplit : public InteractionProcess<ProcessSplit> {
@@ -90,7 +92,7 @@ public:
}
template <typename TView>
- ProcessReturn doInteraction(TView& view) {
+ void doInteraction(TView& view) {
calls_++;
auto vP = view.getProjectile();
const HEPEnergyType E = vP.getEnergy();
@@ -98,7 +100,6 @@ public:
vP.getPosition(), vP.getTime()));
vP.addSecondary(std::make_tuple(vP.getPID(), E / 2, vP.getMomentum(),
vP.getPosition(), vP.getTime()));
- return ProcessReturn::Interacted;
}
int getCalls() const { return calls_; }