docs

corsika/framework/process/BaseProcess.hpp

@@ -16,6 +16,8 @@ namespace corsika {
 
   class TDerived; // fwd decl
 
+  class _BaseProcess {};
+
   /**
      @ingroup Processes
      @{
@@ -31,7 +33,6 @@ namespace corsika {
      ./Processes/AnalyticProcessors/ExecTime.h, see e.g. how this is done in
      ProcessSequence.hpp/make_sequence
    */
-  class _BaseProcess {};
 
   template <typename TDerived>
   struct BaseProcess : _BaseProcess {
@@ -54,7 +55,7 @@ namespace corsika {
   };
 
   /**
-   * ProcessTraits specialization
+     ProcessTraits specialization
    **/
   template <typename TProcess>
   struct is_process<

corsika/framework/process/ProcessSequence.hpp

@@ -60,6 +60,65 @@ namespace corsika {
    - ContinuousProcess
    - StackProcess
    - SecondariesProcess   
+   - BoundaryCrossingProcess
+
+   And all processes (including ProcessSequence and SwitchProcessSequence) are derived from BaseProcess. 
+   
+   Processes of any type (e.g. p1, p2, p3,...) can be assembled into a ProcessSequence using the `make_sequence` factory function.
+   
+   @code{.cpp}
+     auto sequence1 = make_sequence(p1, p2, p3);
+     auto sequence2 = make_sequence(p4, p5, p6, p7);
+     auto sequence3 = make_sequence(sequence1, sequemce2, p8, p9);
+   @endcode
+
+   Note, if the order of processes
+   matters, the order of occurence
+   in the ProcessSequence determines
+   the executiion order.
+   
+   SecondariesProcess alyways act on
+   new secondaries produced (i.e. in
+   InteractionProcess and
+   DecayProcess) in the scope of
+   their ProcessSequence. For
+   example if i1 and i2 are
+   InteractionProcesses and s1 is a
+   SecondariesProcess, then
+
+   @code{.cpp}
+     auto sequence = make_sequence(i1, make_sequence(i2, s1))
+   @endcode
+
+   will result in s1 acting only on
+   the particles produced by i2 and
+   not by i1. This can be very
+   useful, e.g. to fine tune thinning. 
+
+   A special type of ProcessSequence
+   is SwitchProcessSequence, which
+   has two branches and a functor
+   that can select between these two
+   branches.
+
+   @code{.cpp}
+     auto sequence = make_switch(sequence1, sequence2, selector);
+   @endcode
+
+   where the only requirement to
+   `selector` is that it
+   provides a `SwitchResult operator()(Particle const& particle) const` method. Thus,
+   based on the dynamic properties
+   of `particle` the functor
+   can make its decision. This is
+   clearly important for switching
+   between low-energy and
+   high-energy models, but not
+   limited to this. The selection
+   can even be done with a lambda
+   function.
+   
+   
 
    @ingroup Processes
    @{
@@ -67,27 +126,28 @@ namespace corsika {
 
   
   /**
-   *
-   *  Definition of a static process list/sequence
-   *
-   *  A compile time static list of processes. The compiler will
-   *  generate a new type based on template logic containing all the
-   *  elements provided by the user.
-   *
-   *  TProcess1 and TProcess2 must both be derived from BaseProcess,
-   *  and are both references if possible (lvalue), otherwise (rvalue)
-   *  they are just classes. This allows us to handle both, rvalue as
-   *  well as lvalue Processes in the ProcessSequence.
-   *
-   *  (The sequence, and the processes use the CRTP, curiously recurring template
-   *  pattern).
-   *
-   * Template parameters:
-   *  - 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
-   **/
+   
+     Definition of a static process list/sequence
+   
+     A compile time static list of processes. The compiler will
+     generate a new type based on template logic containing all the
+     elements provided by the user.
+   
+     TProcess1 and TProcess2 must both be derived from BaseProcess,
+     and are both references if possible (lvalue), otherwise (rvalue)
+     they are just classes. This allows us to handle both, rvalue as
+     well as lvalue Processes in the ProcessSequence.
+   
+     (The sequence, and the processes use the CRTP, curiously recurring template
+     pattern).
+   
+    Template parameters:
+     @tparam TProcess1 is of type BaseProcess, either a dedicatd process, or a ProcessSequence
+     @tparam TProcess2 is of type BaseProcess, either a dedicatd process, or a ProcessSequence
+     @tparam ProcessIndexOffset to count and index each ContinuousProcess in the entire process-chain
+      @tparam IndexOfProcess1
+      @tparam IndexOfProcess2 
+   */
 
   template <typename TProcess1, typename TProcess2 = NullModel,
             int ProcessIndexOffset = 0,
@@ -218,17 +278,21 @@ namespace corsika {
   };
 
   /**
+    @fn make_sequence
+
     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,
+     - BaseProcess
+     - ContinuousProcess and
+     - InteractionProcess/DecayProcess
+     - StackProcess
      - SecondariesProcess
+     - BoundaryCrossingProcess
+
     can be assembled into a ProcessSequence, all
     combinatorics are allowed.
 
@@ -236,11 +300,11 @@ namespace corsika {
     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
-   
-   **/
-
+    @tparam TProcesses parameter pack with objects of type BaseProcess
+    @tparam TProcess1 another 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>
   typename std::enable_if_t<
       is_process_v<typename std::decay_t<TProcess1>>,
@@ -252,13 +316,17 @@ namespace corsika {
   }
 
   /**
-   * Factory function to create ProcessSequence
-   *
-   * specialization for two input objects (no paramter pack in vB).
-   *
-   * \param vA needs to derive from BaseProcess or ProcessSequence
-   * \param vB needs to derive BaseProcess or ProcessSequence
-   **/
+    @fn make_sequence
+    
+    Factory function to create ProcessSequence
+   
+    specialization for two input objects (no paramter pack in vB).
+   
+    @tparam TProcess1 another BaseProcess
+    @tparam TProcess2 another BaseProcess
+    @param vA needs to derive from BaseProcess or ProcessSequence
+    @param vB needs to derive BaseProcess or ProcessSequence
+   */
   template <typename TProcess1, typename TProcess2>
   typename std::enable_if_t<is_process_v<typename std::decay_t<TProcess1>> &&
                                 is_process_v<typename std::decay_t<TProcess2>>,
@@ -268,13 +336,16 @@ namespace corsika {
   }
 
   /**
-   * Factory function to create ProcessSequence from a single BaseProcess
-   *
-   * also allow a single Process in ProcessSequence, accompany by
-   * `NullModel`
-   *
-   * \param vA needs to derive from BaseProcess or ProcessSequence
-   **/
+    @fn make_sequence
+
+    Factory function to create ProcessSequence from a single BaseProcess
+   
+    also allow a single Process in ProcessSequence, accompany by
+    `NullModel`
+   
+    @tparam TProcess1 another BaseProcess
+    @param vA needs to derive from BaseProcess or ProcessSequence
+   */
   template <typename TProcess>
   typename std::enable_if_t<is_process_v<typename std::decay_t<TProcess>>,
                             ProcessSequence<TProcess, NullModel>>
@@ -283,7 +354,10 @@ namespace corsika {
   }
 
   /**
-   * traits marker to identify objectas ProcessSequence
+    traits marker to identify objectas ProcessSequence
+
+    @tparam TProcess1 another BaseProcess
+    @tparam TProcess2 another BaseProcess
    **/
   template <typename TProcess1, typename TProcess2>
   struct is_process_sequence<ProcessSequence<TProcess1, TProcess2>> : std::true_type {

corsika/framework/process/SwitchProcessSequence.hpp

@@ -9,7 +9,7 @@
 #pragma once
 
 /**
- * \file SwitchProcessSequence.hpp
+  @file SwitchProcessSequence.hpp
  **/
 
 #include <corsika/framework/process/BaseProcess.hpp>
@@ -31,18 +31,22 @@
 namespace corsika {
 
   /**
+     @enum
      @ingroup Processes
-     @{
 
-   * enum for the process switch selection: identify if First or
-   * Second process branch should be used.
-   **/
-  enum class SwitchResult { First, /// Follow first branch in SwitchProcessSequence
-			    Second /// Follow second branch in
-				   /// SwitchProcessSequence
+     enum for the process switch selection: identify if First or Second
+     process branch should be used.
+     @var SwitchResult::First Follow first branch in SwitchProcessSequence
+     @var SwitchResult::Second Follow second branch in SwitchProcessSequence
+   */
+  enum class SwitchResult { First, 
+			    Second 
   };
   
   /**
+     @ingroup Processes
+     @{
+
      Class to switch between two process branches
 
      A compile-time static list of processes that uses an internal
@@ -65,12 +69,14 @@ namespace corsika {
      particle stack and not on indiviidual particles.
 
      Template parameters:
-      - TProcess1 is of type BaseProcess, either a dedicatd process, or a ProcessSequence
-      - TProcess2 is of type BaseProcess, either a dedicatd process, or a ProcessSequence
-      - IndexFirstProcess, IndexOfProcess1, IndexOfProcess2 are to count and index each
-  ContinuousProcess in the entire process-chain
-
-     See also class ProcessSequence
+     @tparam TProcess1 is of type BaseProcess, either a dedicatd process, or a ProcessSequence
+     @tparam TProcess2 is of type BaseProcess, either a dedicatd process, or a ProcessSequence
+     @tparam TSelect selector functor/function 
+     @tparam IndexFirstProcess to count and index each ContinuousProcess in the entire process-chain
+     @tparam IndexOfProcess1 index of TProcess1 (counting of ContinuousProcess)
+     @tparam IndexOfProcess2 index of TProcess2 (counting of ContinuousProcess)
+
+     See also class ProcessSequence.
   **/
 
   template <typename TProcess1, typename TProcess2, typename TSelect,

documentation/conf.py

@@ -37,9 +37,9 @@ copyright = u'2021, CORSIKA 8 Collaboration'
 author = u'CORSIKA 8 Collaboration'
 
 # The short X.Y version
-version = u''
+version = u'0.0.0'
 # The full version, including alpha/beta/rc tags
-release = u'0.0.1'
+release = u'prototype-0.1.0'
 
 extensions = [
     'sphinx.ext.todo',
@@ -85,39 +85,14 @@ 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_static_path = []
 # html_sidebars = {}
 
-
-# -- Options for HTMLHelp output ---------------------------------------------
-
-# Output file base name for HTML help builder.
 htmlhelp_basename = 'C8doc'
 
-
 # -- Options for LaTeX output ------------------------------------------------
 
 latex_elements = {
@@ -142,8 +117,8 @@ latex_elements = {
 # (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'),
+    (master_doc, 'C8-GUIDE.tex', u'CORSIKA 8 Documentation',
+     u'CORSIKA 8 Collaboration', 'manual'),
 ]
 
 
@@ -152,7 +127,7 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'proposal', u'PROPOSAL Documentation',
+    (master_doc, 'CORSIKA 8', u'CORSIKA 8 Documentation',
      [author], 1)
 ]
 
@@ -163,8 +138,8 @@ man_pages = [
 # (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.',
+    (master_doc, 'CORSIKA 8', u'CORSIKA 8 Documentation',
+     author, 'CORSIKA 8', 'The air shower simulation framework',
      'Miscellaneous'),
 ]