From 2e40544c986e60712442e019e2bcce7f6d25d1aa Mon Sep 17 00:00:00 2001
From: ralfulrich <ralf.ulrich@kit.edu>
Date: Wed, 5 May 2021 15:08:06 +0200
Subject: [PATCH] first draft on stack
---
documentation/howto_create_module.rst | 9 ++++---
documentation/index.rst | 1 +
documentation/particles.rst | 37 +++++++++++++++++++++------
3 files changed, 35 insertions(+), 12 deletions(-)
diff --git a/documentation/howto_create_module.rst b/documentation/howto_create_module.rst
index 3177cdb69..416abb537 100644
--- a/documentation/howto_create_module.rst
+++ b/documentation/howto_create_module.rst
@@ -1,21 +1,22 @@
Howto create new physics modules
================================
-There are different types of physics modules, which you can add to the CORSIKA~8 physics process
+There are different types of physics modules, which you can add to the CORSIKA 8 physics process
sequence. Modules can act on particles, secondaries or the entire stack. Modules can create new particles
or they can modify or delete particles. They can also produce output.
Types of different modules are explained in ::modules
-When creating new modules, we suggest to stick as close as possible to the default CORSIKA~8 coding guidelines
+When creating new modules, we suggest to stick as close as possible to the default CORSIKA 8 coding guidelines
and code structure. This makes code review and sharing with others not more complicated than needed.
-When your modules creates output, use the available CORSIKA~8 output machinery. This is not explained here.
+When your modules creates output, use the available CORSIKA 8 output machinery. This is not explained here. Also learn
+how to use units, and use the loggers from the very beginning. Furthermore, get aquinted with C++17.
Let's consider the case of an "InteractionProcess" which will remove the projectile particle and create
secondary particles on the stack instead. It also has a cross section in order to evaulate the probability
with respect to other InteractionProcesses. Create a header file "SimpleProcess.hpp", which is conceptually
-based to resemble (roughly) a Matthews-Heitler model:
+based to resemble (roughly) a Matthew-Heitler model:
.. code-block:: c++
diff --git a/documentation/index.rst b/documentation/index.rst
index c8cdd9672..cbcb393b5 100644
--- a/documentation/index.rst
+++ b/documentation/index.rst
@@ -9,6 +9,7 @@ Welcome to the CORSIKA 8 air shower simulation framework.
readme_link
output
particles
+ particle_stack
media
units
environment
diff --git a/documentation/particles.rst b/documentation/particles.rst
index 33f22f996..ace733680 100644
--- a/documentation/particles.rst
+++ b/documentation/particles.rst
@@ -1,12 +1,33 @@
-Particle Properties
-===================
+Particle Storage and Stack
+==========================
-.. toctree::
- particle_classes
+Particles in memory are stored in a Stack. The Stack handles the memory management and access to particle data
+properties. The stack can be extended with additional fields that then become part of the particle object.
-.. doxygengroup:: Particles
- :project: CORSIKA8
- :members:
+The standard Stack object in CORSIKA 8 is the NuclearStackExtension, further extended with internal
+fields like `geometry node` and `weight` or `history`. But the important part is the `NuclearStackExtension`.
+There are several ways to create particles:
+* novel particles on the stack:
+ * stack::addParticle(particle_data_type const&)
+ * stack::addParticle(nuclear_particle_data_type const&)
+ * stack::addParticle(particle_data_momentum_type const&)
+ * stack::addParticle(nuclear_particle_data_momentum_type const&)
+* secondary particles:
+ * stack::addSecondary(parent const&, particle_data_type const&)
+ * stack::addSecondary(parent const&, nuclear_particle_data_type const&)
+ * stack::addSecondary(parent const&, particle_data_momentum_type const&)
+ * stack::addSecondary(parent const&, nuclear_particle_data_momentum_type const&)
+ or directly:
+ * particle::addSecondary(particle_data_type const&)
+ * particle::addSecondary(nuclear_particle_data_type const&)
+ * particle::addSecondary(particle_data_momentum_type const&)
+ * particle::addSecondary(nuclear_particle_data_momentum_type const&)
+
+The content of these method parameters are:
+
+* particle_data_type: {PID [corsika::Code], kinetic energy [HEPEnergyType], direction [DirectionVector], position [Point], time[TimeType]}
+* particle_data_momentum_type: {PID [corsika::Code], momentum [MomentumVector], position [Point], time[TimeType]}
+* nuclear_particle_data_type: {PID [corsika::Code], kinetic energy [HEPEnergyType], direction [DirectionVector], position [Point], time[TimeType], A [unsigned int], Z [unsigned int]}
+* nuclear_particle_data_momentum_type: {PID [corsika::Code], momentum [MomentumVector], position [Point], time[TimeType], A [unsigned int], Z [unsigned int]}
-
--
GitLab