diff --git a/Documentation/gh-pages/source/KEMField_manual_link.rst b/Documentation/gh-pages/source/KEMField_manual_link.rst deleted file mode 100644 index 10d1a84f5..000000000 --- a/Documentation/gh-pages/source/KEMField_manual_link.rst +++ /dev/null @@ -1,14 +0,0 @@ -KEMField -********** - - -**KEMField** is a toolkit that allows users to solve electrostatic and magnetostatic fields from user-defined inputs. -Detailed explanations on installation and implementation are available in the manual displayed below. -Alternatively the manual is available for download :download:`here <../../../KEMField/Documentation/manual/manual.pdf>` -and can also be found in the `Github repository `_. - - -.. pdf-include:: ./PDFs/manual.pdf - :width: 100% - :height: 800px - diff --git a/Documentation/gh-pages/source/configuring_simulation.rst b/Documentation/gh-pages/source/configuring_simulation.rst index 44933dbc7..699a61e8e 100644 --- a/Documentation/gh-pages/source/configuring_simulation.rst +++ b/Documentation/gh-pages/source/configuring_simulation.rst @@ -1,5 +1,7 @@ Configuring Your Own Simulation -******************************** +******************************* + + .. contents:: On this page :local: @@ -13,9 +15,9 @@ Overview and Units ================== The configuration of *Kassiopeia* is done in three main sections, plus an optional fourth. These are the ```` -section which describes global message verbosity, the ```` section which describes the system geometry and its -extensions, the ```` section which defines the electromagnetic field elements, and the ```` -section which contains the elements needed for the particle tracking simulation. The optional fourth section relates to +section which describes global message verbosity, the ```` section (see :ref:`KGeoBag `) which describes the system geometry and its +extensions, the ```` section (see :ref:`KEMField `) which defines the electromagnetic field elements, and the ```` +section (see :ref:`Kassiopeia element `) which contains the elements needed for the particle tracking simulation. The optional fourth section relates to the specification of a VTK_ or ROOT_ window for the visualization of aspects of a completed simulation. A complete simulation file can thus be broken down into something which looks like the following: @@ -554,1767 +556,9 @@ interface can be configured through its own configuration file, which is located It allows flexible logging configuration of different parts of the code, including changing the verbosity level, redirecting output to a log file, or customizing the message format. -In *Kassiopeia*, *KEMField* and *KGeoBag*, most messages use the *KMessage* interface. - - -Geometry -======== - -The geometry section of the configuration file is the first piece needed in order to assemble a simulation. At its first -and most basic level it is responsible for defining all the different shapes that will be used, and placing them with -respect to one another in order to construct the arrangement (often called `assembly`) that is needed. - -For a full a description of all of the shape objects (surfaces and spaces) which maybe constructed in *KGeoBag* see -:ref:`basic-kgeobag-label` and :ref:`complex-kgeobag-label`. The abstract base classes which serve as the interface -between *KGeoBag* and *Kassiopeia* are ``KSSpace``, ``KSSurface``, and ``KSSide`` (see :gh-code:`Kassiopeia/Operators`). - -The geometry section is also responsible for adding "extended" information to the defined geometry elements. These -extensions can be properties such as colors for visualization, or boundary conditions and meshing details for the -electromagnetic simulations. - -Every relevant to the geometry description is processed by *KGeoBag* and must appear between the start and end brackets: - -.. code-block:: xml - - - - - -It should be noted, that the full description of the geometry need not lie within the same pair of ```` and -```` brackets. This facilitates the description of separate geometry pieces in different files, which may -then be included and used in the final assembly. - -Shapes and assemblies ---------------------- - -To understand the basics of *KGeoBag*, let us look at a simple example. A typical simulation geometry may look like -the image below, where multiple spaces (B-D) and surfaces (a-b) are assembled and placed in a "world" space A: - -.. image:: _images/geometry_picture.png - :width: 250pt - -Internally, *KGeoBag* manages its geometric elements and their relations as a stree structure: - -.. image:: _images/geometry_tree.png - :width: 250pt - -Now, to understand how this works in practice, we'll look at one of the example files provided with *Kassiopeia*. Of -the example files provided, the ``DipoleTrapSimulation.xml`` has the simplest geometry. It will be explained in detail -below, in order to walk you through a typical geometry configuration. - -The geometry section starts off with a description of each shapes involved: - -.. code-block:: xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -The individual shapes are defined by elements of the common structure: - -.. code-block:: xml - - - - -where each element is given a name, which it can be referenced with, and additional parameters dependeing on the shape. -For example, the disk surface is defined by only two parameters `r` and `z`, while other shapes differ. - -Tagging system --------------- - -The tagging system is used to group different elements together, for example by distinguishng between magnet and -electrode shapes. These tags will be used later to retrieve elements and pass them to the *KEMField* module. The -general syntax is: - -.. code-block:: xml - - - - - -and tags can be freely combined or re-used. - -Assembling elements -------------------- - -The defined shapes are then placed into an assembly of the experiment geometry. Geometric objects are placed by -referencing each shape by its given (and *unique*) name and placing it inside a space. This can be combined with -specifying a transformation (relative to the assembly origin) defining the location and orientation of each object. The -available transformation types are displacements (defined by a 3-vector), and rotations (defined by an axis-angle -pair, or a series of Euler angles using the *Z-Y'-Z''* convention): - -.. code-block:: xml - - - - - - - - - - - - - - - - - - - - - - - - -Here the individual named shapes that were defined earlier are referenced, using the general syntax: - -.. code-block:: xml - - - - - -and spaces can be freely nested, which is one of the key features of *KGeoBag*. Note the difference between the first -space, which does not refer to any shape and just holds the child elements, and the second space which refers to the -shape named ``my_space`` through the `node` attribute. The ``my_assembly`` space can be though of as a "virtual space", -without any reference to a real geometric object. - -Finally in the ``DipoleTrapSimulation.xml`` file, the full assembly is placed within the world volume: - -.. code-block:: xml - - - - - -The world volume is a crucial part of any geometry, since it defines the outermost "root" space in which all other -elements must be placed. Note that in this case, the space named ``dipole_trap_assembly`` is referenced through the -`tree` attribute (and not `node`, as you might expect.) This is due to the fact that the assembly is a "virtual" space -that just holds its child elements, but does not refer to an actual object. Make sure to keep this in mind for your -own geometry configurations! - -Transformations ---------------- - -It should be noted that transformations applied to an assembly are collectively applied to all of the geometric elements -within the assembly. For example, placing the dipole trap assembly within the world volume as: - -.. code-block:: xml - - - - - - - -would rotate the whole assembly by 90 degrees about the z-axis, and then displace it by 1 meter along the z-axis. - -Assemblies may be nested within each other, and the coordinate transformations which are associated with the placement -of each assembly will be appropriately applied to all of the elements they contain. This makes it very intuitive to -create complex geometries with multiple displacements and rotations, because it resembles the behavior of real-world -objects (i.e. turning an assemble object by some amount will also turn all parts inside by the same amount, relative -to the outside coordinate system.) - -Especially for rotations, it should be noted that it makes a difference if they are applied in the assembly before or -after placing child elements. Consider the following example: - -.. code-block:: xml - - - - - - - - - - - - - - -In this case, the ``placed_disk`` in in the first assembly will be tilted relative to the world volume, while the -disk in the second assembly will not! This can be verified easily with one of the geometry viewers, which are explained -in section :ref:`visualization-label`. The reason for this behavior is that in the second case, the rotation was -applied before placing the surface inside the assembly, and so it is not propagated to the shape. This is on purpose, -because it allows to transform the origin and orientation of the reference system before assembling elements. - -It is best to think of the ```` elements as commands that are executed during XML initialization, while -the geometry is assembled. It should be clear then that the two example assemblies yield different results. - -Extensions ----------- - -In order to give physical properties to the geometry elements that have been constructed and placed, they must be -associated with extensions. The currently available extensions are *meshing* (axially or rotationally symmetric, or -non-symmetric), *visualization* properties, electrostatic *boundary conditions* (Dirichlet or Neumann surfaces), and -magnetostatic properties of *solenoids and coils* (current density and number of windings.) - -A simple extension example is specifying the color and opacity of a shape for its display in a VTK_ visualization window -as follows: - -.. code-block:: xml - - - -This example tells the visualization that any shape given the tag ``magnet_tag`` should be colored with an RGBA color -value of (0,255,127,127), where all values are given in the range 0..255 and the fourth value defines the shape's -opacity. If you have VTK enabled you may wish to experiment with the changes introduced by modifying these parameters. -When using the ROOT_ visualization, the appearance settings will be ignored. - -In the line above, you also find an example of referencing tags throught the ``@tag_name`` syntax. Generally the -placed shapes can be referenced through a XPath_-like syntax that defines the location in the geometry tree, starting -at the "root" volume (which is typically called `world`.) This usually works with all `spaces` and `surfaces` -attributes of the XML elements. - -The tagging feature is very useful for applying properties to many different elements at once. To do this, each element -which is to receive the same extension must share the same tag. There is no limit to the number of tags an geometric -element may be given. For example, given the dipole trap geometry as specified, one may associate an axially symmetric -mesh with all elements that share the tag ``electrode_tag`` with the line: - -.. code-block:: xml - - - -This specifies that any geometric shape with the tag ``electrode_tag`` that is found within the ``world/dipole_trap`` -space should be giving an axial mesh extension (i.e. it will be divided into a collection of axially symmetric objects -like cones, cylinders, etc.) This axial mesh will be later used by the field solving routines in *KEMField*. However, a -tag is not strictly necessary to apply an extension. For example, if we wished to generate an axial mesh for everything -within the world volume we would write: - -.. code-block:: xml - - - -or, if we wished to single out the ``ring_surface`` shape by specifying its full path we would write: - -.. code-block:: xml - - - -Meshing is critical for any problem with involves electrostatic fields. The type of mesh depends on the symmetry of the -geometry. For completely axially-symmetric geometries, the ``axial_mesh`` is recommended so that the zonal harmonics -field computation method may be used. For completely non-symmetric (3D) geometries, the mesh type would be specified as -follows: - -.. code-block:: xml - - - -Because of the very shape-specific nature of the deterministic meshing which is provided by *KGeoBag*, parameters -(``mesh_count`` and ``mesh_power``) describing how the mesh is to be constructed are given when specifying the shapes -themselves. That being said, the mesh associated with a specific shape will not be constructed unless the extension -statement is present. - -It is possible to define multiple meshes side by side, e.g. if the simulation can be configured axially-symmetric or -non-symmetric. In this case, both meshes will be available for *KEMField* calculations regardless of the symmetry -setting. Note that the axial mesh cannot handle any non-symmetric elements, and these will be simply ignored. - -Another important extension for field calculations is the specification of boundary conditions. For example, when -solving the Laplace boundary value problem via *KEMField*, one may specify that a particular surface exhibit Dirichlet -boundary conditions where a particular voltage is applied to the surface through the use of the following extension: - -.. code-block:: xml - - - -Where ``value="-10"`` signifies that this surface has a potential of -10 volts. This is the standard case for defining -(metallic) electrode surfaces in a simulation, and a typical scenario for the boundary-element method (BEM). It is also -possible to define Neumann boundary conditions, which are typically used for insulating materials. - -Similar to the electrode setup, one can define a magnet system that provides a magnetostatic field for the simulation. -For example, one may specify a solenoid electromagnet with the appropriate parameters: - -.. code-block:: xml - - - -which references a space named ``upstream_solenoid`` with a total current of 22.3047 amps times 20000 turns. The -electric current and the number of turns can also be specified separately for added clarity: - -.. code-block:: xml - - - -The cylinder tube space is one of the supported shapes for electromagnets and describes a solenoid geometry. Other -supported shapes are the cylinder surface, describing a simple coil, and the rod space, describing a single wire. - -For further demonstrations of the possible geometry extensions please see the provided example XML files located -at :gh-code:`KGeoBag/Source/XML/Examples`. - - -KEMField -======== - -The field elements all live within the *KEMField* element and must be placed with start and end tags of the form: - -.. code-block:: xml - - - - - -Note that in some configuration files, you may find the "legacy style" setup where the field elements are defined under -the *Kassiopeia* element (see below). Although both variants are supported, it is recommended to follow the one -described here. - -Fields ------- - -Once the simulation geometry has been specified, the user may describe the types of electric and magnetic fields they -wish associate with each geometric object. The field package *KEMField* takes care of solving the boundary value problem -and computing the fields for electrostatic problems. It also handles the magnetic field computation from static current -distributions. - -Fast field calculation methods are available for axially symmetric (zonal harmonics) and three dimensional problems -(fast multipole method). The abstract base classes responsible for electric and magnetic fields in *Kassiopeia* are -:kassiopeia:`KSElectricField` and :kassiopeia:`KSMagneticField` respectively, which interface with the corresponding -implementations in *KEMField*. - -For example, in the ``DipoleTrapSimulation.xml`` example the electric and magnetic fields are axially symmetric and can -be computed using the zonal harmonics expansion. - -Electric -~~~~~~~~ - -To specify the electric field, the geometric surfaces which are electrically active must be listed in the ``surfaces`` -element. It is important that the surfaces which are specified have a mesh extension and a boundary type extension. If -either of these extensions are missing from the specified surface, they will not be included in the electrostatics -problem. A boundary element mesh is needed to solve the Laplace equation using the boundary element method. Each element -of the mesh inherits its parent surface's boundary condition type. - -Both a method to solve the Laplace boundary value problem (a ``bem_solver``), and a method by which to compute the -fields from the resulting charge densities must be given (a ``field_sovler``). In the following example we use a -``robin_hood_bem_solver`` and a ``zonal_harmonic_field_solver``: - -.. code-block:: xml - - - - - - -It is also important that geometric elements be meshed appropriately with respect to symmetry. In the case that the user -wishes to use zonal harmonic field calculation routines, an ``axial_mesh`` must be used. If a normal (3D) mesh is used, -zonal harmonics cannot function. Different mesh/symmetry types cannot be combined within the same electric field solving -element. The symmetry of the electric field model is set by the ``symmetry`` attribute. - -The zonal-harmonic solver offers many parameters to fine-tune the applied approximation. The example above lists mostly -default values. The most important parameter is probably the distance of the "source points", which provide the basis -for the approximation. The example above defines a spacing of 1 mm along the z-axis. - -In the three-dimensional mesh case, either an integrating field solver, or a fast multipole field solver may be used. -The integrating field solver may be specified through inclusion of the element: - -.. code-block:: xml - - - -within the the ``electrostatic_field`` element (replacing the ``zonal_harmonic_field_solver`` in the example above). -As the integrating field solver is quite simple, it does not require additional parameters. - -The fast multipole field solver on the other hand is somewhat more complex and requires a relatively large set of -additional parameters to be specified in order to configure its use according to the user's desired level of accuracy -and computational effort. - -For a complete list and description of the XML bindings available for the electric field solving routines, navigate to -the directory ``$KASPERSYS/config/KEMField/Complete``. The file ``ElectricFields.xml`` has examples of the binding for -initializing electric field problems (see :gh-code:`KEMField/Source/XML/Complete/ElectricFields.xml`.) - -Magnetic -~~~~~~~~ - -The specification of the magnetic field solving routines is considerably simpler since there is no need to solve a -boundary value problem before hand. There are essentially two choices for solving magnetic fields from static current -distributions: The zonal harmonics method for use with axially symmetric current sources, and the integrating magnetic -field solver which can be used on geometries with more arbitrary distributions of current. Unlike electric fields, -magnetic fields can contain components with both axially symmetric and non-axially symmetric elements within the same -region with no adverse effects. - -The following example uses the zonal harmonics method to compute the magnetic field: - -.. code-block:: xml - - - - - -Note that although the zonal harmonics solver allows a faster calculation of the electromagnetic fields, but requires -some initialization time to compute the source points. Depending on the simulation, the overall computation time could -be lower when using the integrating solver instead. - -Also, please note that only three *KGeoBag* shapes can be used to create electromagnets: cylinder surface, cylinder tube -space, and rod space. For details, see the above section `Extensions`. If other shapes are added to the electromagnet -field elemenet, they will not be recognized as magnet geometries. When using rod spaces, the resulting magnet element -will be a "line current" that does not allow any zonal harmonic approximation and is always solved directly. - -A complete list and set of examples of the XML bindings for magnetic fields can be found in the file -``$KASPERSYS/config/KEMField/Complete/MagneticFields.xml`` (see :gh-code:`KEMField/Source/XML/Complete/MagneticFields.xml`.) - -Further documentation on the exact methods and parameters used in *KEMField* can be found in [2] and [3]. - - -Kassiopeia -========== - -The remaining elements for the simulation all live within the *Kassiopeia* element and must be placed with start and end -tags of the form: - -.. code-block:: xml - - - - - -The elements which must be described within the *Kassiopeia* namespace include the specification of the particle -generation, termination, propagation, interactions, navigation, output, and simulation. The different parts will be -outlined below. - -To understand the basics of *Kassiopeia*, it is important to note that the simulation is organized into four levels: -run, event, track, and step. At the `step` level, the actual calculation of the particle trajectory takes place. When -a new particle is generated, a `track` is initiated that holds all steps belonging to that particle. The track ends -upon termination. The generation of a particle by a user-defined generator is associated with an `event`, which again -holds all corresponding tracks. Because a particle can create secondaries and tracks can be split, one event can hold -more than one track; all belonging to one generation event. Finally, all events from a single simulation are grouped -into a `run`. - -The overall relation between these levels is shown below. In this example, the run consists of three events and six -tracks. In the second event, an interaction occurs which leads to a secondary track. In the third event, the track -is split at the third step. - -.. image:: _images/run_event_track_step.png - :width: 400pt - -With this in mind, one can understand the workflow of the simulation shown below. Each step in the work flow is -associated with runs, events, tracks, and steps, and with certain modules of the simulation such as generation, -navigation, propagation etc. which will be explained futher below. +.. note:: -.. image:: _images/sim_flow.png - :width: 400pt - -Generation ----------- - -The intial state of particle's to be tracked is set up using the generator mechanism. The abstract base class of all -particle generators is :kassiopeia:`KSGenerator` and many different implementations exist. When generating a particle, -there are five important initial parameters: - -- `PID`: What is the particle type? For particle ID values, see the PDG_ numbering scheme. The PID can also be specified - by a common name, such as ``e-`` for PID 11 (an electron.) -- `Energy`: What is the initial energy of the particle? The energy is usually specified in Electronvolts (eV). -- `Position`: What is the initial position of the particle? -- `Direction`: In what direction is the particle traveling? -- `Time`: How is the production of particles distributed in time during the simulation? - -Each of the dynamic components (energy, position, direction, time) can be draw from a selected probability distribution. -In some scenarios a dedicated particle generator may be need which produces with a very specific and well defined -particle state as the result of some physical process (e.g. electron shake-off in Radon decay). However, as is often the -case, the user may wish to modify each dynamic component in a specific way in order to see what effect this has on the -rest of the simulation. - -To draw each dynamic component from an independent distribution a composite generator is used. This type of generator -combines a set of user selected distributions to produce the initial energy, position, direction, and time parameters. -The following composite generator example is taken from the ``DipoleTrapSimulation.xml`` file: - -.. code-block:: xml - - - - - - - - - - - - - - - - - - - - -In this example of the composite generator, the initial kinetic energy of the electron is fixed to 1 eV and its position -is drawn uniformly within a cylindrical volume, defined by the parameters ``(r,phi,z)``.Its initial starting time is -fixed to zero, while its initial momentum direction is fixed along the z-axis by specifiying the corresponding angles -``(phi,theta)`` in a spherical distribution. Here the particle type is specified by the PID 11. The available particles -and their PIDs are defined at the end of the file :gh-code:`Kassiopeia/Operators/Source/KSParticleFactory.cxx`. - -Choosing energy values -~~~~~~~~~~~~~~~~~~~~~~ - -All of the fixed values used in this composite generator may be replaced by probability distributions. The available -probability distributions depend on the quantity they are intended to generate, but include uniform, gaussian, pareto, -cosine, etc. The available distributions can be found in :gh-code:`Kassiopeia/Generators`. Also available is the ability -to generate values at fixed intervals throughout a limited range. For example this can be done for energy as follows: - -.. code-block:: xml - - - - - -which would generate 3 particles with energies equally spaced between 1 and 10 eV. Alternatively, as specific list of -values can also be used: - -.. code-block:: xml - - - - - -Keep in mind that if a ``list`` of ``set`` is used within a composite generator, the number of particles -produced in one generation event will be equal to multiplicative combination of all possible particle states. -For example, the following generator specification: - -.. code-block:: xml - - - - - - - - - - - - - - - - - - - -results in a total of 100 particles being generated per event (as a combination of possible energies and momentum -direction theta coordinate). To see other generator examples please see the included example XML files. - -The table below lists the available value distributions that can be used with one of the initial parameters. Note -that the XML element name can also be adapted, so instead of ``value_gauss`` for an energy distribution one would use: - -.. code-block:: xml - - - - - -Value generator types -~~~~~~~~~~~~~~~~~~~~~ - -The position and direction generators usually support multiple value distributions; e.g. radius (``r_gauss``), -azimuthal angle (``phi_gauss``) and z-position (``z_gauss``) for the composite cylindrical position generator. - -+--------------------------------------------------------------------------------------------------------------------+ -| Generator value distributions | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Name | XML Element | Description (main parameters) | -+====================+=====================================+=========================================================+ -| Fixed | ``value_fix`` | Fixed value | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| List | ``value_list`` | Fixed set of inidivual values | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Set | ``value_set`` | Fixed set of values in range (start, stop, increment) | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Uniform | ``value_uniform`` | Uniform distribution (min, max) | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Boltzmann | ``value_boltzmann`` | Boltzmann energy distribution (mass, `kT`) | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Gauss | ``value_gauss`` | Gaussian distribution (mean, sigma, min, max) | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Generalized Gauss | ``value_generalized_gauss`` | Skewed Gaussian distrib. (mean, sigma, min, max, skew) | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Pareto | ``value_pareto`` | Pareto distribution (slope, cutoff, offset, min, max) | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Cylindrical Radius | ``value_radius_cylindrical`` | Cylindrical radial distribution (min, max) | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Spherical Radius | ``value_radius_spherical`` | Spherical radial distribution (min, max) | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Fractional Radius | ``value_radius_fraction`` | Radial distribution with ``r_max = 1`` | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Cosine Angle | ``value_angle_cosine`` | Cosine angular distribution (min, max) | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Spherical Angle | ``value_angle_spherical`` | Spherical angular distribution (min, max) | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Z-Frustrum | ``value_z_frustrum`` | Random z-value inside frustrum (z1, r1, z2, r2) | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Formula | ``value_formula`` | ROOT Formula (``TF1``) given as string | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Histogram | ``value_histogram`` | ROOT Histogram (``TH1``) read from file | -+--------------------+-------------------------------------+---------------------------------------------------------+ - -Special creator types -~~~~~~~~~~~~~~~~~~~~~ - -In addition, a number of specialized generators exists. For example, the position or energy of the generated particle -can be defined in more a sophisticated way in case a particle is generated from nuclear decays (Tritium, Krypton, Radon) -or starts from a surface. - -+--------------------------------------------------------------------------------------------------------------------+ -| Energy generators (incomplete list) | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Name | XML Element | Description | -+====================+=====================================+=========================================================+ -| Beta Decay | ``energy_beta_decay`` | Energy from (tritium) beta decay | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Beta Recoil | ``energy_beta_recoil`` | Recoil energy from beta decay | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Krypton | ``energy_krypton_event`` | Energy from krypton decay (conversion/Auger) | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Lead | ``energy_lead_event`` | Energy from lead decay (conversion/Auger) | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Radon | ``energy_radon_event`` | Energy from radon decay (conversion/Auger/ShakeOff) | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Rydberg | ``energy_rydberg`` | Energy from Rydberg ionization | -+--------------------+-------------------------------------+---------------------------------------------------------+ - -+--------------------------------------------------------------------------------------------------------------------+ -| Position generators (incomplete list) | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Name | XML Element | Description | -+====================+=====================================+=========================================================+ -| Cylindrical | ``position_cylindrical_composite`` | Cylindrical position ``(r, phi, z)`` | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Rectangular | ``position_rectangular_composite`` | Rectangular position ``(x, y, z)`` | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Spherical | ``position_spherical_composite`` | Spherical position ``(r, phi, theta)`` | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Flux Tube | ``position_flux_tube`` | Cylindrical position; radius defined by flux tube | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Surface | ``position_surface_random`` | Random position on surface (not all types supported) | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Mesh Surface | ``position_mesh_surface_random`` | Random position on surface; needs surface mesh! | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Space | ``position_space_random`` | Random position in space (not all types supported) | -+--------------------+-------------------------------------+---------------------------------------------------------+ - -Termination ------------ - -The converse to particle generation is termination. The abstract base class of all particle terminators is -:kassiopeia:`KSTerminator`. Terminators are used to stop particle tracks in situations where further simulation of the -particle is of no further interest. Terminators typically operate on very simple conditional logic. For example, a -particle track may be terminated if the particle's kinetic energy drops below some set value, if it intersects a -particular surface, or simply after a given number of steps has been reached. - -An example of a terminator which stops particle tracks which exceed the number of allowed steps is given as follows: - -.. code-block:: xml - - - -A pair of terminators which will terminate a particle that exceeds an allowed range for the z-coordinate is given in the -following example: - -.. code-block:: xml - - - - -There are a wide variety of terminators currently avaiable that can be found in :gh-code:`Kassiopeia/Terminators`. The -user is encouraged to peruse the XML example files as well as the source code to determine what (if any) type of -pre-existing terminator might be useful for their purpose. As will be explained later, one may enable/disable specific -terminators dynamically during the simulation. This allows a very flexible configuration of particle termination. - -Propagation ------------ - -The propagation section is used to describe the physical process which is associated with the movement of a particle, -and also the means by which the equations of motion are solved. The equations of motions are solved numerically with -various control methods for the time step used during integration of a specific particle trajectory. The abstract base -class of all particle trajectories is :kassiopeia:`KSTrajectory`. - -There are essential five different equations of motion (trajectories) available for particle tracking in *Kassiopeia*. -These are, exact, adiabatic, electric, magnetic, and linear. These are implemented in :gh-code:`Kassiopeia/Trajectories` -and some specialized classes exist for spin particles. - -Exact trajectory -~~~~~~~~~~~~~~~~ - -The first trajectory type is the so-called *exact* method, which solves the Lorentz equation for charged particles -exactly without any approximations. It is visualized below: - -.. image:: _images/exact_step.png - :width: 150pt - -Adiabatic trajectory -~~~~~~~~~~~~~~~~~~~~ - -The second method is the adiabatic method, which is useful for solving charged particle motion in the presence of -smoothly varying magnetic fields. In this case, only the motion of the "guiding center" (a point on the magnetic field -line) is computed, which allows certain approximations. One may then reconcstruct the cyclotron motion of the particle -around the field line, however this is entirely optional. This method is visualized below: - -.. image:: _images/adiabatic_step.png - :width: 150pt - -Electric and magnetic trajectories -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The next two types, electric and magnetic (not shown here), are used for tracking the field lines of static electric and -magnetic fields respectively. Finally, the linear trajectory calculates a linear motion that is independent of any -external fields. - -The definition of a trajectory for the simulation is usually combined with additional parameters that define the -behavior of the simulation: - -- The `integrator` is responsible for solving the differential equation (ODE) in order to perform the tracking. - Integrators are based off the class :kassiopeia:`KSMathIntegrator`. -- An `interpolator` allows to speed up the ODE solving, by interpolating the particle's parameters over a single step. - Typically, the ODE solver performs evaluations of the particle state in between the initial and final position, - which is time-consuming. Interpolators are based off the class :kassiopeia:`KSMathIntegrator`. -- Additional `terms` extend the differential equation of the base trajectory. For example in case of the adiabatic - trajectory, one may add terms for gyration or drift that are otherwise not included in the appoximation. The ODE terms - are based off the class :kassiopeia:`KSMathDifferentiator`. -- Additional `controls` can modify the step size. Options exist for a static setting (e.g. a step size of 1 mm) - or dynamic adjustment (e.g. a step size derived from the local magnetic field.) Step controls are based off the class - :kassiopeia:`KSMathControl`. Multiple controls can be combined, in which case the smallest possible step is taken. - -Trajectory types -~~~~~~~~~~~~~~~~ - -The tables below lists the available integrators, interpolators, and terms: - -+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Trajectory integrators | -+--------------------+----------------------------+----------------------+----------------------+----------------------+------------------------------------------------+ -| Name | XML Element | Solution Order | Function evaluations | Error estimate | Description | -+====================+============================+======================+======================+======================+================================================+ -| RKF54 | ``integrator_rk54`` | 5 | 6 | Yes | 5th/4th-order Runge-Kutta | -+--------------------+----------------------------+----------------------+----------------------+----------------------+------------------------------------------------+ -| RKDP54 | ``integrator_rkdp54`` | 5 | 7 | Yes | 5th-order Runge-Kutta, 4th-order dense output | -+--------------------+----------------------------+----------------------+----------------------+----------------------+------------------------------------------------+ -| RK65 | ``integrator_rk65`` | 6 | 8 | Yes | 6th/5th-order Runge-Kutta | -+--------------------+----------------------------+----------------------+----------------------+----------------------+------------------------------------------------+ -| RKF8 | ``integrator_rk8`` | 8 | 13 | No | 8th-order Runge-Kutta | -+--------------------+----------------------------+----------------------+----------------------+----------------------+------------------------------------------------+ -| RK86 | ``integrator_rk86`` | 8 | 12 | Yes | 8th/6th-order Runge-Kutta | -+--------------------+----------------------------+----------------------+----------------------+----------------------+------------------------------------------------+ -| RK87 | ``integrator_rk87`` | 8 | 13 | Yes | 8th/7th-order Runge-Kutta | -+--------------------+----------------------------+----------------------+----------------------+----------------------+------------------------------------------------+ -| RKDP853 | ``integrator_rkdp853`` | 8 | 16 | Yes | 8th-order Runge-Kutta, 7th-order dense output | -+--------------------+----------------------------+----------------------+----------------------+----------------------+------------------------------------------------+ -| Sym4 | ``integrator_sym4`` | 4 | 4 | No | 4th-order Symplectic; only for exact tracking | -+--------------------+----------------------------+----------------------+----------------------+----------------------+------------------------------------------------+ - -+-----------------------------------------------------------------------------------------------------------+ -| Trajectory interpolators | -+--------------------+-------------------------------------+------------------------------------------------+ -| Name | XML Element | Description | -+====================+=====================================+================================================+ -| Fast | ``interpolator_fast`` | Fast linear interpolation | -+--------------------+-------------------------------------+------------------------------------------------+ -| Hermite | ``interpolator_hermite`` | Hermite polynomial interpolation | -+--------------------+-------------------------------------+------------------------------------------------+ -| Cont. Runge-Kutta | ``kstraj_interpolator_crk`` | Continuous Runge-Kutta (needs dense output) | -+--------------------+-------------------------------------+------------------------------------------------+ - -+--------------------------------------------------------------------------------------------------------------------+ -| Trajectory terms | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Name | XML Element | Description | -+====================+=====================================+=========================================================+ -| Propagation | ``term_propagation`` | Basic particle propagation | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Constant Force | ``term_constant_force_propagation`` | Propagation by constant force | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Synchrotron | ``term_synchrotron`` | Energy loss from synchrotron radiation | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Drift | ``term_drift`` | Electromagnetic field drifts, adiabatic only | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Gyration | ``term_gyration`` | Gyration around guiding center; adiabatic only | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Gravity | ``term_gravity`` | Gravity pull; exact only | -+--------------------+-------------------------------------+---------------------------------------------------------+ - -+--------------------------------------------------------------------------------------------------------------------+ -| Trajectory controls | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Name | XML Element | Description | -+====================+=====================================+=========================================================+ -| Length | ``control_length`` | Fixed length | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Time | ``control_time`` | Fixed time | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| B-Field Gradient | ``control_B_change`` | Length scaled by relative B-field gradient | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Cyclotron | ``control_cyclotron`` | Length scaled to length of a full cyclotron turn | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Energy | ``control_energy`` | Length adjusted to limit total energy violation | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Magnetic Moment | ``control_magnetic_moment`` | Length adjusted to limit adiabaticity violation | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Momentum Error | ``control_momentum_numerical_error``| Length adjusted to limit momentum error | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Position Error | ``control_position_numerical_error``| Length adjusted to limit position error | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Spin M-Dot | ``control_m_dot`` | Length scaled by $\dot{M}$ (spin tracking only) | -+--------------------+-------------------------------------+---------------------------------------------------------+ -| Spin Precession | ``control_spin_precession`` | Length scaled by precession freq. (spin tracking only) | -+--------------------+-------------------------------------+---------------------------------------------------------+ - -Examples -~~~~~~~~ - -The exact tracking method can be used where accuracy is of the utmost importance, but requires a large number of steps -in order propagate a particle for a long time or distance. An example of its use is given below: - -.. code-block:: xml - - - - - - - - - - -In the above example, the integrator type specified ``integrator_rkdp853`` is an 8-th order Runge-Kutta integrator with -a 7-th order dense output interpolant (specified by ``interpolator_crk``). The step size control is accomplished through -the combination of three different methods. Two of them, ``control_length`` and ``control_time``, place a fixed limit on -the step size, while the third ``control_position_error`` dynamically attempts to limit the local numerical error on the -particle's position. In this case no additional terms besides basic propagation are defined, since the exact trajectory -does not make any approximations. - -All of the trajectories take an optional parameter ``attempt_limit`` which limits the number of tries an integration -step will be re-attempted if a step size control determines that the step has failed. The default number of maximum -number of attempts is 32. If a trajectory makes no progress after the maximum number of allowed attempts, the track will -be terminated with a ``trajectory_fail`` flag. - -An example of the adiabatic trajectory with some additional options is specified in the following: - -.. code-block:: xml - - - - - - - - - - - - -In this example, both the motion of the particle's guiding center drift (``term_drift``) and the particle's local -gyration (``term_gyration``) itself are included in the equations of motion. If the second term is not present, the -adiabatic tracjectory only computes the movement of the guiding center. It is important to note that the adiabatic -trajectory cannot be used if there is no magnetic field present. Similar to the example above, the step size is -defined by a combination of two controls. - -The last three trajectory types can be specfified as follows: - -.. code-block:: xml - - - - - - - - - - - - - - - - - - - - - -The electric and magnetic field line trajectories are useful for visualization purposes, and during the design stages of -an experiment or simulation. Note that in the above examples we have used a faster but less accurate Runge-Kutta -integrator ``integrator_rkdp54``. The property ``direction`` in ``term_propagation`` can be used to specify the -direction in which field lines are tracked (positive-to-negative or north-to-south). The linear trajectory takes no -parameters besides a fixed step length,. - -In all of the trajectories (exact, adiabatic, electric, magnetic) the parameters ``piecewise_tolerance`` and -``max_segments`` are optional. They dictate how a particles trajectory (in between steps) should be approximated by -piecewise linear segments when determining surface and volume intersections. These parameters are only used when the -``ksnav_meshed_space`` navigator is in use, and determine how accurately intersections are found. The default -``ksnav_space`` navigator ignores these parameters, since it uses a faster but less accurate approximation by linearly -interpolating a particle's intermediate state and position. See below for details on navigation. - -The adiabatic trajectory also takes the additional parameters ``use_true_position`` and ``cyclotron_fraction`` when the -``mesh_spaced_navigator`` is in use. The parameter ``use_true_position`` determines whether the particle or its guiding -center position is used for the purpose of finding intersections. If the particle's true position is used, then the -parameter ``cyclotron_fraction`` dictates the number of linear segments the semi-helical path is broken into. - -Interactions ------------- - -In between generation and termination, discrete stochastic interactions involving the particle of interest may be -applied during tracking. These interactions are divided according to whether they are active in a volume, or on a -surface. In both cases, the behavior ties with the *KGeoBag* module that provides the geometric information. - -Volume Interactions -~~~~~~~~~~~~~~~~~~~ - -Volume interactions typically involve scattering off of a gas. The abstract base class of all volume interactions is -:kassiopeia:`KSSpaceInteraction`. Simple situations where the scattering interactions is treated approximately by a -constant density and cross section can be constructed as follows: - -.. code-block:: xml - - - - - - -In this example the density is computed according to the ideal gas law from the temperature (Kelvin) and pressure -(Pascal) and the cross section is treated as a constant (independent of particle energy). Other forms of interaction -are available in :gh-code:`Kassiopeia/Interactions`. For more complicated interactions (e.g. involving differential or -energy dependent cross sections) the user may need to devise their own interaction class. Volume interactions must -always be associated with a particular volume when describing the simulation structure. - -Surface Interactions -~~~~~~~~~~~~~~~~~~~~ - -Surface interactions are much more limited in their scope and only occur when the track of a particle passes through a -surface. The abstract base class of all surface interactions is :kassiopeia:`KSSurfaceInteraction`. - -For example, to cause a particle to be reflected diffusely (Lambertian) from a surface the user can specify an -interaction of the following type: - -.. code-block:: xml - - - -Similarly, one may use the following code to employ fully specular reflection: - -.. code-block:: xml - - - -In order for this interaction to operate on any particles it must be associated with a surface in the simulation command -structure. - -Output ------- - -The data which is saved as output from the simulation requires two pieces: a file writer and a description of the data -to be saved. The abstract base class of all file writers is :kassiopeia:`KSWriter`. - -Writers -~~~~~~~ - -The file writer is responsible for buffering and writing the desired information to disk. The default writer is based on -ROOT_, and stores the output in a ``TTree`` structure: - -.. code-block:: xml - - - -If *Kassiopeia* is linked against VTK_, an additional writer will be made available which can save track and step -information to a ``.vtp`` (VTK polydata) file. This data is useful for visualalization in external tools such as -Paraview_. This write may be created using the following statement: - -.. code-block:: xml - - - -Note that in principle both data formats are equivalent, but their underlying structure differs. In most cases it is -best to write output file in both formats, and delete any files that are no longer needed. - -To write output in plaintext ASCII format that can be easily viewed and read into other software such as Gnuplot_, -one may use the following statement: - -.. code-block:: xml - - - -This is not recommended for large-scale simulations because the output file will quickly approach a size that will be -extremely difficult to handle. - -Output description -~~~~~~~~~~~~~~~~~~ - -The user may tailor the data written to disk to keep precisely the quantities of interest and no more. To do this a -description of the data components to be kept at the track and step level must be given. An example of this (taken from -the ``QuadrupoleTrapSimulation.xml`` example) is shown below: - -.. code-block:: xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Let us break this down a bit. First of all, the output can be separated into three groups that each define an output -segment that will be written to the file: - -- `component_step_world` is the base definition for output at the step level. It contains standard parameters of the - particle such as its energy, position, or step index. -- `component_step_cell` defines additional output fields that are of interest in a specific region of the simulation. - How this feature can be used will be explained below. Generally, one can define as many output groups as necessary - to write output only where it is relevant to the simulation. -- `component_track_world` is the base definition for output at the track level. While the step output is written - continuously while the particle trajectory is being computed, the track output is only written once after a track - has been terminated. As such, the track output contains initial and final parameters of the particle (again, for - example, its energy or position) and are derived from the first and last step of the track. There is also an output - field ``z_length_integral`` that stores the integrated length of all tracks performed in the simulation. - -For output fields that are not directly available at the step (``parent="step"``) or track level, a mapping has to be -defined first. This is done by the lines: - -.. code-block:: xml - - - -and so on. The ``field="final_particle"`` points to the final particle state after a step has been performed, i.e. this -output is written after the completion of each step. Similary, at the track level there are output fields that point -to the initial and final parameters of a track, i.e. the state at particle generation and termination. - -The standard output fields for the particle are defined at the end of the file -:gh-code:`Kassiopeia/Operators/Source/KSParticle.cxx` while the step and track output fields can be found in -:gh-code:`Kassiopeia/Operators/Source/KSStep.cxx` and :gh-code:`Kassiopeia/Operators/Source/KSTrack.cxx`, respectively. -Other specialized output fields are also available for some propagation or interaction terms. - -Output fields -~~~~~~~~~~~~~ - -Many different output fields can be used and combined in the output configuration. The table below gives an -overview of the different fields and their types. - -+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Output fields | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Name | XML Element | Value Type | Base class | Description (main parameters) | -+====================+=====================================+==================+============================+==========================================================+ -| Index Number | ``index_number`` | ``long`` | ``KSParticle`` | Unique index number of the current step | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Parent Run ID | ``parent_run_id`` | ``int`` | ``KSParticle`` | Run ID of the parent step/track/event | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Parent Event ID | ``parent_event_id`` | ``int`` | ``KSParticle`` | Event ID of the parent step/track/event | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Parent Track ID | ``parent_track_id`` | ``int`` | ``KSParticle`` | Track ID of the parent step/track | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Parent Step ID | ``parent_step_id`` | ``int`` | ``KSParticle`` | Step ID of the parent step | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Particle ID | ``pid`` | ``long long`` | ``KSParticle`` | Assigned particle ID (PDG code) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Particle String ID | ``string_id`` | ``string`` | ``KSParticle`` | Assigned particle ID (human-readable) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Particle Mass | ``mass`` | ``double`` | ``KSParticle`` | Mass of the particle (in kg) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Particle Charge | ``charge`` | ``double`` | ``KSParticle`` | Charge of the particle (in C) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Particle Spin | ``total_spin`` | ``double`` | ``KSParticle`` | Spin magnitude of the particle (in hbar) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Gyromagnetic Ratio | ``gyromagnetic_ratio`` | ``double`` | ``KSParticle`` | Gyromagnetic ratio of the particle (in rad/sT) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Main Quantum No. | ``n`` | ``int`` | ``KSParticle`` | Main quantum number | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Second Quatum No. | ``l`` | ``int`` | ``KSParticle`` | Secondary quantum number | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Time | ``time`` | ``double`` | ``KSParticle`` | Time in the simulation (in s) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Wallclock Time | ``clock_time`` | ``double`` | ``KSParticle`` | Wallclock time (system time) at the current step | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Step Length | ``length`` | ``double`` | ``KSParticle`` | Length of the current step (in m) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Position Vector | ``position`` | ``KThreeVector`` | ``KSParticle`` | Position at the current step (in m) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Momentum Vector | ``momentum`` | ``KThreeVector`` | ``KSParticle`` | Momentum at the current step (in kg*m/s) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Velocity Vector | ``velocity`` | ``double`` | ``KSParticle`` | Velocity at the current step (in m/s) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Spin Vector | ``spin`` | ``KThreeVector`` | ``KSParticle`` | Spin at the current step (in hbar) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Index Number | ``spin0`` | ``double`` | ``KSParticle`` | | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Aligned Spin | ``aligned_spin`` | ``double`` | ``KSParticle`` | | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Spin Angle | ``spin_angle`` | ``double`` | ``KSParticle`` | | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Speed | ``speed`` | ``double`` | ``KSParticle`` | Total speed at the current step (in m/s) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Lorentz Factor | ``lorentz_factor`` | ``double`` | ``KSParticle`` | Lorentz factor at the current step | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Kinetic Energy | ``kinetic_energy`` | ``double`` | ``KSParticle`` | Kinetic energy at the current step (in J) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Kinetic Energy | ``kinetic_energy_ev`` | ``double`` | ``KSParticle`` | Kinetic energy at the current step (in eV) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Polar Angle | ``polar_angle_to_z`` | ``double`` | ``KSParticle`` | Polar angle relative to z-axis (in deg) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Azimuthal Angle | ``azimuthal_angle_to_x`` | ``double`` | ``KSParticle`` | Azimuthal angle relative to x-axis (in deg) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Magnetic Field | ``magnetic_field`` | ``KThreeVector`` | ``KSParticle`` | Magnetic field at the current step (in T) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Electric Field | ``electric_field`` | ``KThreeVector`` | ``KSParticle`` | Electric field at the current step (in V/m) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Magnetic Gradient | ``magnetic_gradient`` | ``KThreeMatrix`` | ``KSParticle`` | Magnetic gradient at the current step (in T/m) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Electric Potential | ``electric_potential`` | ``double`` | ``KSParticle`` | Electric potential at the current step (in V) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Long. Momentum | ``long_momentum`` | ``double`` | ``KSParticle`` | Longitudinal momentum at the current step (in kg*m/s) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Trans. Momentum | ``trans_momentum`` | ``double`` | ``KSParticle`` | Transversal momentum at the current step (in kg*m/s) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Long. Velocity | ``long_velocity`` | ``double`` | ``KSParticle`` | Longitudinal velocity at the current step (in m/s) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Trans. Velocity | ``trans_velocity`` | ``double`` | ``KSParticle`` | Transversal velocity at the current step (in m/s) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Polar Angle to B | ``polar_angle_to_b`` | ``double`` | ``KSParticle`` | Polar (pitch) angle relative to magnetic field (in deg) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Cyclotron Freq. | ``cyclotron_frequency`` | ``double`` | ``KSParticle`` | Cyclotron frequency at the current step (in Hz) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Magnetic Moment | ``orbital_magnetic_moment`` | ``double`` | ``KSParticle`` | Orbital magnetic moment at the current step (in A*m^2) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| GC Position Vector | ``guiding_center_position`` | ``KThreeVector`` | ``KSParticle`` | Guiding center position at the current step (in m) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Current Space | ``current_space_name`` | ``string`` | ``KSParticle`` | Name of the nearest space (see ``geo_space``) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Current Surface | ``current_surface_name`` | ``string`` | ``KSParticle`` | Name of the nearest surface (see ``geo_surface``) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Current Side | ``current_side_name`` | ``string`` | ``KSParticle`` | Name of the nearest side (see ``geo_side``) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| GC Velocity | ``gc_velocity`` | ``double`` | ``KSTrajTermDrift`` | Guiding center velocity (in m/s) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| GC Long. Force | ``longitudinal_force`` | ``double`` | ``KSTrajTermDrift`` | Longitudinal force added by drift terms (in N) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| GC Trans. Force | ``transverse_force`` | ``double`` | ``KSTrajTermDrift`` | Transversal force added by drift terms (in N) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Gy. Phase Velocity | ``phase_velocity`` | ``double`` | ``KSTrajTermGyration`` | Phase velocity of gyration around g.c. (in rad/s) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Synchrotron Force | ``total_force`` | ``double`` | ``KSTrajTermSynchrotron`` | Total force added by synchrotron radiation (in N) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Min. Distance | ``min_distance`` | ``double`` | ``KSTermMinDistance`` | Distance to the nearest surface (in m) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Interaction Count | ``step_number_of_interactions`` | ``int`` | ``KSIntCalculator`` | Number of interactions at current step | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Energy loss | ``step_energy_loss`` | ``double`` | ``KSIntCalculator`` | Energy loss at current step (in eV) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Angular Change | ``step_angular_change`` | ``double`` | ``KSIntCalculator`` | Angular change at current step (in deg) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Interaction Count | ``step_number_of_decays`` | ``int`` | ``KSIntDecayCalculator`` | Number of interactions at current step | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Energy loss | ``step_energy_loss`` | ``double`` | ``KSIntDecayCalculator`` | Energy loss at current step (in eV) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Enhancement Factor | ``enhancement_factor`` | ``double`` | ``KSModDynamicEnhancement``| Step modifier enhancement factor | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Run ID | ``run_id`` | ``int`` | ``KSRun`` | Run ID of current run | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Run Count | ``run_count`` | ``int`` | ``KSRun`` | Total number of runs | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Total Events | ``total_events`` | ``unsigned int`` | ``KSRun`` | Total number of events in run | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Total Tracks | ``total_tracks`` | ``unsigned int`` | ``KSRun`` | Total number of tracks in run | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Total Steps | ``total_steps`` | ``unsigned int`` | ``KSRun`` | Total number of steps in run | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Cont. Time | ``continuous_time`` | ``double`` | ``KSRun`` | Total time of all events/tracks/steps in run | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Cont. Length | ``continuous_length`` | ``double`` | ``KSRun`` | Total length of all events/tracks/steps in run | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Energy Change | ``continuous_energy_change`` | ``double`` | ``KSRun`` | Total energy change during run | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Momentum Change | ``continuous_momentum_change`` | ``double`` | ``KSRun`` | Total momentum change during run | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Secondaries Count | ``discrete_secondaries`` | ``unsigned int`` | ``KSRun`` | Number of secondaries created during run | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Energy Change | ``discrete_energy_change`` | ``double`` | ``KSRun`` | Total energy change during run | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Momentum Change | ``discrete_momentum_change`` | ``double`` | ``KSRun`` | Total momentum change during run | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Number of Turns | ``number_of_turns`` | ``unsigned int`` | ``KSRun`` | Number of particle turns/reflections during run | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Event ID | ``event_id`` | ``int`` | ``KSEvent`` | Event ID of current event | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Event Count | ``event_count`` | ``int`` | ``KSEvent`` | Total number of events | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Parent Run ID | ``parent_run_id`` | ``int`` | ``KSEvent`` | Run ID of parent run | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Total Tracks | ``total_tracks`` | ``unsigned int`` | ``KSEvent`` | Total number of tracks in event | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Total Steps | ``total_steps`` | ``unsigned int`` | ``KSEvent`` | Total number of steps in event | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Cont. Time | ``continuous_time`` | ``double`` | ``KSEvent`` | Total time of all tracks/steps in event | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Cont. Length | ``continuous_length`` | ``double`` | ``KSEvent`` | Total length of all tracks/steps in event | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Energy Change | ``continuous_energy_change`` | ``double`` | ``KSEvent`` | Total energy change during event | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Momentum Change | ``continuous_momentum_change`` | ``double`` | ``KSEvent`` | Total momentum change during event | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Secondaries Count | ``discrete_secondaries`` | ``unsigned int`` | ``KSEvent`` | Number of secondaries created during event | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Energy Change | ``discrete_energy_change`` | ``double`` | ``KSEvent`` | Total energy change during event | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Momentum Change | ``discrete_momentum_change`` | ``double`` | ``KSEvent`` | Total momentum change during event | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Number of Turns | ``number_of_turns`` | ``unsigned int`` | ``KSEvent`` | Number of particle turns/reflections during event | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Generator Name | ``generator_name`` | ``string`` | ``KSEvent`` | Name of the generator starting this event | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Generator Flag | ``generator_flag`` | ``bool`` | ``KSEvent`` | Additional flag of the used generator | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Primary Count | ``generator_primaries`` | ``unsigned int`` | ``KSEvent`` | Number of generated particles | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Generator Energy | ``generator_energy`` | ``double`` | ``KSEvent`` | Total energy of the generated particles (in eV) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Generator Time | ``generator_min_time`` | ``double`` | ``KSEvent`` | Minimum time of the generated particles (in s) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Generator Time | ``generator_max_time`` | ``double`` | ``KSEvent`` | Maximum time of the generated particles (in s) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Generator Position | ``generator_location`` | ``KThreeVector`` | ``KSEvent`` | Center position of the generated particles (in m) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Generator Radius | ``generator_radius`` | ``double`` | ``KSEvent`` | Maximum radius of the generated particles (in m) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Track ID | ``event_id`` | ``int`` | ``KSTrack`` | Track ID of current track | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Track Count | ``event_count`` | ``int`` | ``KSTrack`` | Total number of tracks | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Parent Event ID | ``parent_event_id`` | ``int`` | ``KSTrack`` | Event ID of parent track | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Total Steps | ``total_steps`` | ``unsigned int`` | ``KSTrack`` | Total number of steps in track | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Cont. Time | ``continuous_time`` | ``double`` | ``KSTrack`` | Total time of all steps in track | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Cont. Length | ``continuous_length`` | ``double`` | ``KSTrack`` | Total length of all steps in track | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Energy Change | ``continuous_energy_change`` | ``double`` | ``KSTrack`` | Total energy change during track | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Momentum Change | ``continuous_momentum_change`` | ``double`` | ``KSTrack`` | Total momentum change during track | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Secondaries Count | ``discrete_secondaries`` | ``unsigned int`` | ``KSTrack`` | Number of secondaries created during track | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Energy Change | ``discrete_energy_change`` | ``double`` | ``KSTrack`` | Total energy change during track | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Momentum Change | ``discrete_momentum_change`` | ``double`` | ``KSTrack`` | Total momentum change during track | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Number of Turns | ``number_of_turns`` | ``unsigned int`` | ``KSTrack`` | Number of particle turns/reflections during track | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Creator Name | ``creator_name`` | ``string`` | ``KSTrack`` | Name of the creator starting this track | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Terminator Name | ``terminator_name`` | ``string`` | ``KSTrack`` | Name of the terminator ending this track | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Initial Particle | ``initial_particle`` | ``KSParticle`` | ``KSTrack`` | Pointer to initial particle at begin of the track | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Final particle | ``final_particle`` | ``KSParticle`` | ``KSTrack`` | Pointer to final particle at end of the track | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Step ID | ``step_id`` | ``int`` | ``KSStep`` | Step ID of current step | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Step Count | ``step_count`` | ``int`` | ``KSStep`` | Total number of steps | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Parent Track ID | ``parent_track_id`` | ``int`` | ``KSStep`` | Track ID of parent track | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Cont. Time | ``continuous_time`` | ``double`` | ``KSStep`` | Total time of current step | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Cont. Length | ``continuous_length`` | ``double`` | ``KSStep`` | Total length of current step | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Energy Change | ``continuous_energy_change`` | ``double`` | ``KSStep`` | Total energy change during step | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Momentum Change | ``continuous_momentum_change`` | ``double`` | ``KSStep`` | Total momentum change during step | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Secondaries Count | ``discrete_secondaries`` | ``unsigned int`` | ``KSStep`` | Number of secondaries created during step | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Energy Change | ``discrete_energy_change`` | ``double`` | ``KSStep`` | Total energy change during step | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Momentum Change | ``discrete_momentum_change`` | ``double`` | ``KSStep`` | Total momentum change during step | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Number of Turns | ``number_of_turns`` | ``unsigned int`` | ``KSStep`` | Number of particle turns/reflections during step | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Modifier Name | ``modifier_name`` | ``string`` | ``KSStep`` | Name of the step modifier at this step | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Modifier Flag | ``modifier_flag`` | ``bool`` | ``KSStep`` | Additional flag for the used terminator | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Terminator Name | ``terminator_name`` | ``string`` | ``KSStep`` | Name of the terminator ending this step | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Terminator Flag | ``terminator_flag`` | ``bool`` | ``KSStep`` | Additional flag for the used terminator | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Trajectory Name | ``trajectory_name`` | ``string`` | ``KSStep`` | Name of the trajectory at this step | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Trajectory Center | ``trajectory_center`` | ``KThreeVector`` | ``KSStep`` | Position of the trajectory bounding sphere (in m) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Trajectory Radius | ``trajectory_radius`` | ``double`` | ``KSStep`` | Radius of the trajectory bounding sphere (in m) | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Trajectory Step | ``trajectory_step`` | ``double`` | ``KSStep`` | Time of the particle propagation | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Interaction Name | ``space_interaction_name`` | ``string`` | ``KSStep`` | Space name of the interaction at this step | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Interaction Flag | ``space_interaction_flag`` | ``bool`` | ``KSStep`` | Additional flag for the space interaction | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Interaction Step | ``space_interaction_step`` | ``double`` | ``KSStep`` | Time of the space interaction | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Navigation Name | ``space_navigation_name`` | ``string`` | ``KSStep`` | Space name of the navigation at this step | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Navigation Flag | ``space_navigation_flag`` | ``bool`` | ``KSStep`` | Additional flag for the space navigation | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Navigation Step | ``space_navigation_step`` | ``double`` | ``KSStep`` | Time of the space navigation | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Interaction Name | ``surface_interaction_name`` | ``string`` | ``KSStep`` | Surface name of the interaction at this step | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Interaction Flag | ``surface_interaction_flag`` | ``bool`` | ``KSStep`` | Additional flag for the surface interaction | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Navigation Name | ``surface_navigation_name`` | ``string`` | ``KSStep`` | Surface name of the navigation at this step | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Navigation Flag | ``surface_navigation_flag`` | ``bool`` | ``KSStep`` | Additional flag for the surface navigation | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Initial Particle | ``initial_particle`` | ``KSParticle`` | ``KSStep`` | Pointer to initial particle at begin of the step | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Finale Particle | ``final_particle`` | ``KSParticle`` | ``KSStep`` | Pointer to initial particle at begin of the step | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Intermed. Particle | ``interaction_particle`` | ``KSParticle`` | ``KSStep`` | Pointer to initial particle before interaction | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Intermed. Particle | ``navigation_particle`` | ``KSParticle`` | ``KSStep`` | Pointer to initial particle before navigation | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Intermed. Particle | ``terminator_particle`` | ``KSParticle`` | ``KSStep`` | Pointer to initial particle before termination | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ -| Intermed. Particle | ``trajectory_particle`` | ``KSParticle`` | ``KSStep`` | Pointer to initial particle before propagation | -+--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ - -Vector and matrix type can be accessed by their components in the written output data. For example, when the ``position`` -element is used, the corresponding fields in the output data can be found under the names ``position_x``, ``position_y``, -and ``position_z`. For matrix types, the rows are treated as 3-vectors themselves. Hence, the first element in a matrix -field named ``gradient`` can be found under ``gradient_x_x``, and so on. - -The following suffixes are available for the vector and matrix types. - -+-----------------------------------------------------------------------------+ -| Output field suffixes | -+--------------------+-------------------------------------+------------------+ -| Name | XML Element Suffix | Base Type | -+====================+=====================================+==================+ -| X Component | ``x`` | ``KThreeVector`` | -+--------------------+-------------------------------------+------------------+ -| Y Component | ``y`` | ``KThreeVector`` | -+--------------------+-------------------------------------+------------------+ -| Z Component | ``z`` | ``KThreeVector`` | -+--------------------+-------------------------------------+------------------+ -| Vector Magnitude | ``magnitude`` | ``KThreeVector`` | -+--------------------+-------------------------------------+------------------+ -| Squared Magnitude | ``magnitude_squared`` | ``KThreeVector`` | -+--------------------+-------------------------------------+------------------+ -| Radial Component | ``perp`` | ``KThreeVector`` | -+--------------------+-------------------------------------+------------------+ -| Squared Radial | ``perp_squared`` | ``KThreeVector`` | -+--------------------+-------------------------------------+------------------+ -| Polar Angle | ``polar_angle`` | ``KThreeVector`` | -+--------------------+-------------------------------------+------------------+ -| Azimuthal Angle | ``azimuthal_angle`` | ``KThreeVector`` | -+--------------------+-------------------------------------+------------------+ -| Determinant | ``determinant`` | ``KThreeMatrix`` | -+--------------------+-------------------------------------+------------------+ -| Trace | ``trace`` | ``KThreeMatrix`` | -+--------------------+-------------------------------------+------------------+ - -Navigation ----------- - -Surfaces navigation -~~~~~~~~~~~~~~~~~~~ - -The navigation of a particle is split into two components, surface navigation and space navigation. Surface navigation -is very simple and only takes place when a particle has intersected an active surface. The surface navigator determines -whether the state of the particle is modified on the surface and whether it is reflected or transmitted. It can be made -available for use with the declaration: - -.. code-block:: xml - - - -As this navigator is very simple, it does not take many additional parameters. The parameters ``transmission_split`` and -``reflection_split`` determine whether or not a track is split in two (for the purposes of output/saving data) upon -transmission through or reflection off a geometric surface. - -Space navigation -~~~~~~~~~~~~~~~~ - -The space navigator is more complex since it is responsible for determine the location of the particle and any possible -intersections it may have with real of virtual boundaries. It is also responsible for ensuring that the current -simulation state matches the configuration specified by the user. The spaces that the navigator considers may be real -objects (such as a vacuum chamber wall) or virtual (which only modify the state of the simulation, e.g. exchanging a -trajectory method). The latter case allows to dynamically reconfigure the simulation over a track. - -For space navigation there are two options. The first is the default ``ksnav_space`` navigator which can be specified as -below: - -.. code-block:: xml - - - -As this navigator is also very simple, it does not take many additional parameters. The parameters ``enter_split`` and -``exit_split`` determine whether or not a track is split in two upon entrance or exit of a geometric space. - -Meshed space navigation -~~~~~~~~~~~~~~~~~~~~~~~ - -A more complex behavior is achieved by the ``ksnav_meshed_space`` navigator, which is intended to be used in highly -detailed three-dimensional geometries where it has better performance over the default navigator. An example of this is -shown in the ``PhotoMultplierTube.xml`` file. Its configuration is more complicated as it performs the navigations on -the meshed boundaries of spaces and surfaces. It requires the construction of an octree spatial partition (which may be -cached for later re-use). The user must specify the depth of the octree (``max_octree_depth``) and the number of -elements allowed in a octree node before a subdivision is required (``n_allowed_elements``). In addition, the root of -the geometry tree must also be specified with the parameter ``root_space``, which is typically the world volume: - -.. code-block:: xml - - - -Though they are not shown here (they default to false), the exit and entrance split parameters may also be set for the -``ksnav_meshed_space`` navigator. Because the ``ksnav_meshed_space`` navigator requires a boundary mesh in order to -operate, all geometric objects (spaces, sufaces) which have navigation commands attached to them must also have a mesh -extension in the geometry specification. Furthermore, since ``ksnav_meshed_space`` requires access to the root space -``space_world`` and all of the navigation commands associated with the shapes it contains, it must be declared after the -definition of the simulation command structure element ``ksgeo_space`` (see below). - -The mesh navigator can also be used together with geometry from exernal files, as shown in the ``MeshSimulation.xml`` -example. - -Navigation and Commands ------------------------ - -For dyanmic configuration, *Kassiopeia* allows certain commands to be used during the calculation of a particle -trajectory. The commands are associated with particular surfaces and spaces and are what effectively governs the state -of the simulation as a particle is tracked. They are declared through the specification of a ``ksgeo_space``. A very -simple example of the declaration of the command structure can be seen in the DipoleTrapSimulation.xml as shown below: - -.. code-block:: xml - - - - - - - - - - - - - - - - - - -Note that in some configuration files, you may find alternative declarations such as: - -.. code-block:: xml - - - - -which are eequivalent to the commands shown above. - -Again, let us break down this example: - -- First we create a ``ksgeo_space`` navigation space using the ``world`` volume (a geometric object holding all other - elements.) Inside of this world volume we declare a series of command which will be executed any time a particle - enters or is initialized within the world volume. -- The first two commands add and remove specific terminators, while the next two declare what sort of output should be - written to disk while the particle is inside the world volume. -- Following that, there are commands which are attached to specific surfaces which are present in the geometry, and - handled by the navigator. For example in the first block, attaching the terminator ``term_upstream_target`` ensures - that a particle impinging on the surface ``surface_upstream_target`` will be terminated immediately. -- The last surface does not have any associated commands, but will still be considered for navigation. For example, - if ``transmission_split`` was set in the navigator, the track will be split if the particle crosses the surface. - -Commands can used to change the active field calculation method, swap trajectory types, or add/remove termsna and -interactions, define terminators, etc. Various spaces and their associated commands can be nested within each other -allowing for a very flexible and dynamic simulation configuration. For best results, it is important that the -structure of the ``geo_space`` and ``geo_surface`` elements follows the structure of the *KGeoBag* geometry tree, i.e. -nesting of the navigation elements should follow the same order as the underlying geometry. - -Simulation ----------- - -The final object to be declared within ```` is the simulation element. This describes the simulation object -:kassiopeia:`KSSimulation`, which is then executed by :kassiopeia:`KSRoot`. The simulation element specifies the global -and initial properties of the simulation as a whole. For example in the ``QuadrupoleTrapSimulation.xml`` example, the -simulation element is declared as follows: - -.. code-block:: xml - - - -The ``run`` is simply a user provided identifier. The ``seed`` is the value provided to the global (singleton) random -number generator. Simulations with the same configuration and same seed should provide identical results. If the user is -interested in running *Kassiopeia* on many machines in order to achieve high throughput particle tracking (Monte Carlo), -care must be taken to ensure that the ``seed`` value is different for each run of the simulation. - -The parameter ``events`` determines the total number of times that the generator is run (however this is not necessarily -the number of particles that will be tracked, e.g. if lists or sets are used in the generator of if secondary particles -are created). The remaining parameters ``magnetic_field``, ``space``, ``generator``, etc. all specify the default -objects to be used for the initial state of the simulation; where commands specified within ``ksgeo_space`` may -modify the actual objects used during the course of a simulation. - -Following the declaration of ``ks_simulation``, the closing tag ```` is placed to complete the simulation -configuration. When this tag is encountered by the XML parser, it triggers the simulation to run. - - -Visualization -------------- - -VTK visualization -~~~~~~~~~~~~~~~~~ - -If *Kassiopeia* has been linked against VTK_ or ROOT_, a simple visualization of the simulation can be made available. -By adding the `vtk_window` element at the end of the configuration file, we activate a VTK window that will open when -the simulation is complete. This element may hold a ``vtk_geometry_painter`` and a ```vtk_track_painter`` to draw the -geometry and tracks, respectively. An example of this type of visualization from the ``QuadrupoleTrapSimulation.xml`` -file is a follows: - -.. code-block:: xml - - - - - - -Note that the visualization window must be placed outside of the ````...```` -environment tags. - -ROOT visualization -~~~~~~~~~~~~~~~~~~ - -Similarly, a visualization window can be activated that uses the ROOT software. In constrast to VTK, which displays -three-dimensional geometry, the ROOT visualization is limited to two dimensions. A simple example that may be added -to the ``QuadrupoleTrapSimulation.xml`` file is as follows: - -.. code-block:: xml - - - - - + In *Kassiopeia*, *KEMField* and *KGeoBag*, most messages use the *KMessage* interface. Common Pitfalls and Problems diff --git a/Documentation/gh-pages/source/element_kassiopeia.rst b/Documentation/gh-pages/source/element_kassiopeia.rst new file mode 100644 index 000000000..5f8ea1e99 --- /dev/null +++ b/Documentation/gh-pages/source/element_kassiopeia.rst @@ -0,0 +1,1290 @@ +.. _Kassiopeia-element: + +Kassiopeia (particles) - +==================== + +.. contents:: On this page + :local: + :depth: 2 + +The remaining elements for the simulation all live within the *Kassiopeia* element and must be placed with start and end +tags of the form: + +.. code-block:: xml + + + + + +The elements which must be described within the *Kassiopeia* namespace include the specification of the particle +generation, termination, propagation, interactions, navigation, output, and simulation. The different parts will be +outlined below. + +To understand the basics of *Kassiopeia*, it is important to note that the simulation is organized into four levels: +run, event, track, and step. At the `step` level, the actual calculation of the particle trajectory takes place. When +a new particle is generated, a `track` is initiated that holds all steps belonging to that particle. The track ends +upon termination. The generation of a particle by a user-defined generator is associated with an `event`, which again +holds all corresponding tracks. Because a particle can create secondaries and tracks can be split, one event can hold +more than one track; all belonging to one generation event. Finally, all events from a single simulation are grouped +into a `run`. + +The overall relation between these levels is shown below. In this example, the run consists of three events and six +tracks. In the second event, an interaction occurs which leads to a secondary track. In the third event, the track +is split at the third step. + +.. image:: _images/run_event_track_step.png + :width: 400pt + +With this in mind, one can understand the workflow of the simulation shown below. Each step in the work flow is +associated with runs, events, tracks, and steps, and with certain modules of the simulation such as generation, +navigation, propagation etc. which will be explained futher below. + +.. image:: _images/sim_flow.png + :width: 400pt + +Generation +---------- + +The intial state of particle's to be tracked is set up using the generator mechanism. The abstract base class of all +particle generators is **KSGenerator** and many different implementations exist. When generating a particle, +there are five important initial parameters: + +- `PID`: What is the particle type? For particle ID values, see the PDG_ numbering scheme. The PID can also be specified + by a common name, such as ``e-`` for PID 11 (an electron.) +- `Energy`: What is the initial energy of the particle? The energy is usually specified in Electronvolts (eV). +- `Position`: What is the initial position of the particle? +- `Direction`: In what direction is the particle traveling? +- `Time`: How is the production of particles distributed in time during the simulation? + +Each of the dynamic components (energy, position, direction, time) can be draw from a selected probability distribution. +In some scenarios a dedicated particle generator may be need which produces with a very specific and well defined +particle state as the result of some physical process (e.g. electron shake-off in Radon decay). However, as is often the +case, the user may wish to modify each dynamic component in a specific way in order to see what effect this has on the +rest of the simulation. + +To draw each dynamic component from an independent distribution a composite generator is used. This type of generator +combines a set of user selected distributions to produce the initial energy, position, direction, and time parameters. +The following composite generator example is taken from the ``DipoleTrapSimulation.xml`` file: + +.. code-block:: xml + + + + + + + + + + + + + + + + + + + + +In this example of the composite generator, the initial kinetic energy of the electron is fixed to 1 eV and its position +is drawn uniformly within a cylindrical volume, defined by the parameters ``(r,phi,z)``.Its initial starting time is +fixed to zero, while its initial momentum direction is fixed along the z-axis by specifiying the corresponding angles +``(phi,theta)`` in a spherical distribution. Here the particle type is specified by the PID 11. The available particles +and their PIDs are defined at the end of the file :gh-code:`Kassiopeia/Operators/Source/KSParticleFactory.cxx`. + +Choosing energy values +~~~~~~~~~~~~~~~~~~~~~~ + +All of the fixed values used in this composite generator may be replaced by probability distributions. The available +probability distributions depend on the quantity they are intended to generate, but include uniform, gaussian, pareto, +cosine, etc. The available distributions can be found in :gh-code:`Kassiopeia/Generators`. Also available is the ability +to generate values at fixed intervals throughout a limited range. For example this can be done for energy as follows: + +.. code-block:: xml + + + + + +which would generate 3 particles with energies equally spaced between 1 and 10 eV. Alternatively, as specific list of +values can also be used: + +.. code-block:: xml + + + + + +Keep in mind that if a ``list`` of ``set`` is used within a composite generator, the number of particles +produced in one generation event will be equal to multiplicative combination of all possible particle states. +For example, the following generator specification: + +.. code-block:: xml + + + + + + + + + + + + + + + + + + + +results in a total of 100 particles being generated per event (as a combination of possible energies and momentum +direction theta coordinate). To see other generator examples please see the included example XML files. + +The table below lists the available value distributions that can be used with one of the initial parameters. Note +that the XML element name can also be adapted, so instead of ``value_gauss`` for an energy distribution one would use: + +.. code-block:: xml + + + + + +Value generator types +~~~~~~~~~~~~~~~~~~~~~ + +The position and direction generators usually support multiple value distributions; e.g. radius (``r_gauss``), +azimuthal angle (``phi_gauss``) and z-position (``z_gauss``) for the composite cylindrical position generator. + ++--------------------------------------------------------------------------------------------------------------------+ +| Generator value distributions | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Name | XML Element | Description (main parameters) | ++====================+=====================================+=========================================================+ +| Fixed | ``value_fix`` | Fixed value | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| List | ``value_list`` | Fixed set of inidivual values | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Set | ``value_set`` | Fixed set of values in range (start, stop, increment) | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Uniform | ``value_uniform`` | Uniform distribution (min, max) | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Boltzmann | ``value_boltzmann`` | Boltzmann energy distribution (mass, `kT`) | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Gauss | ``value_gauss`` | Gaussian distribution (mean, sigma, min, max) | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Generalized Gauss | ``value_generalized_gauss`` | Skewed Gaussian distrib. (mean, sigma, min, max, skew) | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Pareto | ``value_pareto`` | Pareto distribution (slope, cutoff, offset, min, max) | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Cylindrical Radius | ``value_radius_cylindrical`` | Cylindrical radial distribution (min, max) | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Spherical Radius | ``value_radius_spherical`` | Spherical radial distribution (min, max) | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Fractional Radius | ``value_radius_fraction`` | Radial distribution with ``r_max = 1`` | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Cosine Angle | ``value_angle_cosine`` | Cosine angular distribution (min, max) | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Spherical Angle | ``value_angle_spherical`` | Spherical angular distribution (min, max) | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Z-Frustrum | ``value_z_frustrum`` | Random z-value inside frustrum (z1, r1, z2, r2) | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Formula | ``value_formula`` | ROOT Formula (``TF1``) given as string | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Histogram | ``value_histogram`` | ROOT Histogram (``TH1``) read from file | ++--------------------+-------------------------------------+---------------------------------------------------------+ + +Special creator types +~~~~~~~~~~~~~~~~~~~~~ + +In addition, a number of specialized generators exists. For example, the position or energy of the generated particle +can be defined in more a sophisticated way in case a particle is generated from nuclear decays (Tritium, Krypton, Radon) +or starts from a surface. + ++--------------------------------------------------------------------------------------------------------------------+ +| Energy generators (incomplete list) | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Name | XML Element | Description | ++====================+=====================================+=========================================================+ +| Beta Decay | ``energy_beta_decay`` | Energy from (tritium) beta decay | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Beta Recoil | ``energy_beta_recoil`` | Recoil energy from beta decay | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Krypton | ``energy_krypton_event`` | Energy from krypton decay (conversion/Auger) | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Lead | ``energy_lead_event`` | Energy from lead decay (conversion/Auger) | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Radon | ``energy_radon_event`` | Energy from radon decay (conversion/Auger/ShakeOff) | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Rydberg | ``energy_rydberg`` | Energy from Rydberg ionization | ++--------------------+-------------------------------------+---------------------------------------------------------+ + ++--------------------------------------------------------------------------------------------------------------------+ +| Position generators (incomplete list) | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Name | XML Element | Description | ++====================+=====================================+=========================================================+ +| Cylindrical | ``position_cylindrical_composite`` | Cylindrical position ``(r, phi, z)`` | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Rectangular | ``position_rectangular_composite`` | Rectangular position ``(x, y, z)`` | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Spherical | ``position_spherical_composite`` | Spherical position ``(r, phi, theta)`` | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Flux Tube | ``position_flux_tube`` | Cylindrical position; radius defined by flux tube | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Surface | ``position_surface_random`` | Random position on surface (not all types supported) | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Mesh Surface | ``position_mesh_surface_random`` | Random position on surface; needs surface mesh! | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Space | ``position_space_random`` | Random position in space (not all types supported) | ++--------------------+-------------------------------------+---------------------------------------------------------+ + +Termination +----------- + +The converse to particle generation is termination. The abstract base class of all particle terminators is +**KSTerminator**. Terminators are used to stop particle tracks in situations where further simulation of the +particle is of no further interest. Terminators typically operate on very simple conditional logic. For example, a +particle track may be terminated if the particle's kinetic energy drops below some set value, if it intersects a +particular surface, or simply after a given number of steps has been reached. + +An example of a terminator which stops particle tracks which exceed the number of allowed steps is given as follows: + +.. code-block:: xml + + + +A pair of terminators which will terminate a particle that exceeds an allowed range for the z-coordinate is given in the +following example: + +.. code-block:: xml + + + + +There are a wide variety of terminators currently avaiable that can be found in :gh-code:`Kassiopeia/Terminators`. The +user is encouraged to peruse the XML example files as well as the source code to determine what (if any) type of +pre-existing terminator might be useful for their purpose. As will be explained later, one may enable/disable specific +terminators dynamically during the simulation. This allows a very flexible configuration of particle termination. + +Propagation +----------- + +The propagation section is used to describe the physical process which is associated with the movement of a particle, +and also the means by which the equations of motion are solved. The equations of motions are solved numerically with +various control methods for the time step used during integration of a specific particle trajectory. The abstract base +class of all particle trajectories is **KSTrajectory**. + +There are essential five different equations of motion (trajectories) available for particle tracking in *Kassiopeia*. +These are, exact, adiabatic, electric, magnetic, and linear. These are implemented in :gh-code:`Kassiopeia/Trajectories` +and some specialized classes exist for spin particles. + +Exact trajectory +~~~~~~~~~~~~~~~~ + +The first trajectory type is the so-called *exact* method, which solves the Lorentz equation for charged particles +exactly without any approximations. It is visualized below: + +.. image:: _images/exact_step.png + :width: 150pt + +Adiabatic trajectory +~~~~~~~~~~~~~~~~~~~~ + +The second method is the adiabatic method, which is useful for solving charged particle motion in the presence of +smoothly varying magnetic fields. In this case, only the motion of the "guiding center" (a point on the magnetic field +line) is computed, which allows certain approximations. One may then reconcstruct the cyclotron motion of the particle +around the field line, however this is entirely optional. This method is visualized below: + +.. image:: _images/adiabatic_step.png + :width: 150pt + +Electric and magnetic trajectories +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The next two types, electric and magnetic (not shown here), are used for tracking the field lines of static electric and +magnetic fields respectively. Finally, the linear trajectory calculates a linear motion that is independent of any +external fields. + +The definition of a trajectory for the simulation is usually combined with additional parameters that define the +behavior of the simulation: + +- The `integrator` is responsible for solving the differential equation (ODE) in order to perform the tracking. + Integrators are based off the class **KSMathIntegrator**. +- An `interpolator` allows to speed up the ODE solving, by interpolating the particle's parameters over a single step. + Typically, the ODE solver performs evaluations of the particle state in between the initial and final position, + which is time-consuming. Interpolators are based off the class **KSMathIntegrator**. +- Additional `terms` extend the differential equation of the base trajectory. For example in case of the adiabatic + trajectory, one may add terms for gyration or drift that are otherwise not included in the appoximation. The ODE terms + are based off the class **KSMathDifferentiator**. +- Additional `controls` can modify the step size. Options exist for a static setting (e.g. a step size of 1 mm) + or dynamic adjustment (e.g. a step size derived from the local magnetic field.) Step controls are based off the class + **KSMathControl**. Multiple controls can be combined, in which case the smallest possible step is taken. + +Trajectory types +~~~~~~~~~~~~~~~~ + +The tables below lists the available integrators, interpolators, and terms: + ++-----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Trajectory integrators | ++--------------------+----------------------------+----------------------+----------------------+----------------------+------------------------------------------------+ +| Name | XML Element | Solution Order | Function evaluations | Error estimate | Description | ++====================+============================+======================+======================+======================+================================================+ +| RKF54 | ``integrator_rk54`` | 5 | 6 | Yes | 5th/4th-order Runge-Kutta | ++--------------------+----------------------------+----------------------+----------------------+----------------------+------------------------------------------------+ +| RKDP54 | ``integrator_rkdp54`` | 5 | 7 | Yes | 5th-order Runge-Kutta, 4th-order dense output | ++--------------------+----------------------------+----------------------+----------------------+----------------------+------------------------------------------------+ +| RK65 | ``integrator_rk65`` | 6 | 8 | Yes | 6th/5th-order Runge-Kutta | ++--------------------+----------------------------+----------------------+----------------------+----------------------+------------------------------------------------+ +| RKF8 | ``integrator_rk8`` | 8 | 13 | No | 8th-order Runge-Kutta | ++--------------------+----------------------------+----------------------+----------------------+----------------------+------------------------------------------------+ +| RK86 | ``integrator_rk86`` | 8 | 12 | Yes | 8th/6th-order Runge-Kutta | ++--------------------+----------------------------+----------------------+----------------------+----------------------+------------------------------------------------+ +| RK87 | ``integrator_rk87`` | 8 | 13 | Yes | 8th/7th-order Runge-Kutta | ++--------------------+----------------------------+----------------------+----------------------+----------------------+------------------------------------------------+ +| RKDP853 | ``integrator_rkdp853`` | 8 | 16 | Yes | 8th-order Runge-Kutta, 7th-order dense output | ++--------------------+----------------------------+----------------------+----------------------+----------------------+------------------------------------------------+ +| Sym4 | ``integrator_sym4`` | 4 | 4 | No | 4th-order Symplectic; only for exact tracking | ++--------------------+----------------------------+----------------------+----------------------+----------------------+------------------------------------------------+ + ++-----------------------------------------------------------------------------------------------------------+ +| Trajectory interpolators | ++--------------------+-------------------------------------+------------------------------------------------+ +| Name | XML Element | Description | ++====================+=====================================+================================================+ +| Fast | ``interpolator_fast`` | Fast linear interpolation | ++--------------------+-------------------------------------+------------------------------------------------+ +| Hermite | ``interpolator_hermite`` | Hermite polynomial interpolation | ++--------------------+-------------------------------------+------------------------------------------------+ +| Cont. Runge-Kutta | ``kstraj_interpolator_crk`` | Continuous Runge-Kutta (needs dense output) | ++--------------------+-------------------------------------+------------------------------------------------+ + ++--------------------------------------------------------------------------------------------------------------------+ +| Trajectory terms | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Name | XML Element | Description | ++====================+=====================================+=========================================================+ +| Propagation | ``term_propagation`` | Basic particle propagation | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Constant Force | ``term_constant_force_propagation`` | Propagation by constant force | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Synchrotron | ``term_synchrotron`` | Energy loss from synchrotron radiation | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Drift | ``term_drift`` | Electromagnetic field drifts, adiabatic only | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Gyration | ``term_gyration`` | Gyration around guiding center; adiabatic only | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Gravity | ``term_gravity`` | Gravity pull; exact only | ++--------------------+-------------------------------------+---------------------------------------------------------+ + ++--------------------------------------------------------------------------------------------------------------------+ +| Trajectory controls | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Name | XML Element | Description | ++====================+=====================================+=========================================================+ +| Length | ``control_length`` | Fixed length | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Time | ``control_time`` | Fixed time | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| B-Field Gradient | ``control_B_change`` | Length scaled by relative B-field gradient | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Cyclotron | ``control_cyclotron`` | Length scaled to length of a full cyclotron turn | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Energy | ``control_energy`` | Length adjusted to limit total energy violation | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Magnetic Moment | ``control_magnetic_moment`` | Length adjusted to limit adiabaticity violation | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Momentum Error | ``control_momentum_numerical_error``| Length adjusted to limit momentum error | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Position Error | ``control_position_numerical_error``| Length adjusted to limit position error | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Spin M-Dot | ``control_m_dot`` | Length scaled by $\dot{M}$ (spin tracking only) | ++--------------------+-------------------------------------+---------------------------------------------------------+ +| Spin Precession | ``control_spin_precession`` | Length scaled by precession freq. (spin tracking only) | ++--------------------+-------------------------------------+---------------------------------------------------------+ + +Examples +~~~~~~~~ + +The exact tracking method can be used where accuracy is of the utmost importance, but requires a large number of steps +in order propagate a particle for a long time or distance. An example of its use is given below: + +.. code-block:: xml + + + + + + + + + + +In the above example, the integrator type specified ``integrator_rkdp853`` is an 8-th order Runge-Kutta integrator with +a 7-th order dense output interpolant (specified by ``interpolator_crk``). The step size control is accomplished through +the combination of three different methods. Two of them, ``control_length`` and ``control_time``, place a fixed limit on +the step size, while the third ``control_position_error`` dynamically attempts to limit the local numerical error on the +particle's position. In this case no additional terms besides basic propagation are defined, since the exact trajectory +does not make any approximations. + +All of the trajectories take an optional parameter ``attempt_limit`` which limits the number of tries an integration +step will be re-attempted if a step size control determines that the step has failed. The default number of maximum +number of attempts is 32. If a trajectory makes no progress after the maximum number of allowed attempts, the track will +be terminated with a ``trajectory_fail`` flag. + +An example of the adiabatic trajectory with some additional options is specified in the following: + +.. code-block:: xml + + + + + + + + + + + + +In this example, both the motion of the particle's guiding center drift (``term_drift``) and the particle's local +gyration (``term_gyration``) itself are included in the equations of motion. If the second term is not present, the +adiabatic tracjectory only computes the movement of the guiding center. It is important to note that the adiabatic +trajectory cannot be used if there is no magnetic field present. Similar to the example above, the step size is +defined by a combination of two controls. + +The last three trajectory types can be specfified as follows: + +.. code-block:: xml + + + + + + + + + + + + + + + + + + + + + +The electric and magnetic field line trajectories are useful for visualization purposes, and during the design stages of +an experiment or simulation. Note that in the above examples we have used a faster but less accurate Runge-Kutta +integrator ``integrator_rkdp54``. The property ``direction`` in ``term_propagation`` can be used to specify the +direction in which field lines are tracked (positive-to-negative or north-to-south). The linear trajectory takes no +parameters besides a fixed step length,. + +In all of the trajectories (exact, adiabatic, electric, magnetic) the parameters ``piecewise_tolerance`` and +``max_segments`` are optional. They dictate how a particles trajectory (in between steps) should be approximated by +piecewise linear segments when determining surface and volume intersections. These parameters are only used when the +``ksnav_meshed_space`` navigator is in use, and determine how accurately intersections are found. The default +``ksnav_space`` navigator ignores these parameters, since it uses a faster but less accurate approximation by linearly +interpolating a particle's intermediate state and position. See below for details on navigation. + +The adiabatic trajectory also takes the additional parameters ``use_true_position`` and ``cyclotron_fraction`` when the +``mesh_spaced_navigator`` is in use. The parameter ``use_true_position`` determines whether the particle or its guiding +center position is used for the purpose of finding intersections. If the particle's true position is used, then the +parameter ``cyclotron_fraction`` dictates the number of linear segments the semi-helical path is broken into. + +Interactions +------------ + +In between generation and termination, discrete stochastic interactions involving the particle of interest may be +applied during tracking. These interactions are divided according to whether they are active in a volume, or on a +surface. In both cases, the behavior ties with the *KGeoBag* module that provides the geometric information. + +Volume Interactions +~~~~~~~~~~~~~~~~~~~ + +Volume interactions typically involve scattering off of a gas. The abstract base class of all volume interactions is +**KSSpaceInteraction**. Simple situations where the scattering interactions is treated approximately by a +constant density and cross section can be constructed as follows: + +.. code-block:: xml + + + + + + +In this example the density is computed according to the ideal gas law from the temperature (Kelvin) and pressure +(Pascal) and the cross section is treated as a constant (independent of particle energy). Other forms of interaction +are available in :gh-code:`Kassiopeia/Interactions`. For more complicated interactions (e.g. involving differential or +energy dependent cross sections) the user may need to devise their own interaction class. Volume interactions must +always be associated with a particular volume when describing the simulation structure. + +Surface Interactions +~~~~~~~~~~~~~~~~~~~~ + +Surface interactions are much more limited in their scope and only occur when the track of a particle passes through a +surface. The abstract base class of all surface interactions is **KSSurfaceInteraction**. + +For example, to cause a particle to be reflected diffusely (Lambertian) from a surface the user can specify an +interaction of the following type: + +.. code-block:: xml + + + +Similarly, one may use the following code to employ fully specular reflection: + +.. code-block:: xml + + + +In order for this interaction to operate on any particles it must be associated with a surface in the simulation command +structure. + +Output +------ + +The data which is saved as output from the simulation requires two pieces: a file writer and a description of the data +to be saved. The abstract base class of all file writers is **KSWriter**. + +Writers +~~~~~~~ + +The file writer is responsible for buffering and writing the desired information to disk. The default writer is based on +ROOT_, and stores the output in a ``TTree`` structure: + +.. code-block:: xml + + + +If *Kassiopeia* is linked against VTK_, an additional writer will be made available which can save track and step +information to a ``.vtp`` (VTK polydata) file. This data is useful for visualalization in external tools such as +Paraview_. This write may be created using the following statement: + +.. code-block:: xml + + + +Note that in principle both data formats are equivalent, but their underlying structure differs. In most cases it is +best to write output file in both formats, and delete any files that are no longer needed. + +To write output in plaintext ASCII format that can be easily viewed and read into other software such as Gnuplot_, +one may use the following statement: + +.. code-block:: xml + + + +This is not recommended for large-scale simulations because the output file will quickly approach a size that will be +extremely difficult to handle. + +Output description +~~~~~~~~~~~~~~~~~~ + +The user may tailor the data written to disk to keep precisely the quantities of interest and no more. To do this a +description of the data components to be kept at the track and step level must be given. An example of this (taken from +the ``QuadrupoleTrapSimulation.xml`` example) is shown below: + +.. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Let us break this down a bit. First of all, the output can be separated into three groups that each define an output +segment that will be written to the file: + +- `component_step_world` is the base definition for output at the step level. It contains standard parameters of the + particle such as its energy, position, or step index. +- `component_step_cell` defines additional output fields that are of interest in a specific region of the simulation. + How this feature can be used will be explained below. Generally, one can define as many output groups as necessary + to write output only where it is relevant to the simulation. +- `component_track_world` is the base definition for output at the track level. While the step output is written + continuously while the particle trajectory is being computed, the track output is only written once after a track + has been terminated. As such, the track output contains initial and final parameters of the particle (again, for + example, its energy or position) and are derived from the first and last step of the track. There is also an output + field ``z_length_integral`` that stores the integrated length of all tracks performed in the simulation. + +For output fields that are not directly available at the step (``parent="step"``) or track level, a mapping has to be +defined first. This is done by the lines: + +.. code-block:: xml + + + +and so on. The ``field="final_particle"`` points to the final particle state after a step has been performed, i.e. this +output is written after the completion of each step. Similary, at the track level there are output fields that point +to the initial and final parameters of a track, i.e. the state at particle generation and termination. + +The standard output fields for the particle are defined at the end of the file +:gh-code:`Kassiopeia/Operators/Source/KSParticle.cxx` while the step and track output fields can be found in +:gh-code:`Kassiopeia/Operators/Source/KSStep.cxx` and :gh-code:`Kassiopeia/Operators/Source/KSTrack.cxx`, respectively. +Other specialized output fields are also available for some propagation or interaction terms. + +Output fields +~~~~~~~~~~~~~ + +Many different output fields can be used and combined in the output configuration. The table below gives an +overview of the different fields and their types. + ++---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Output fields | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Name | XML Element | Value Type | Base class | Description (main parameters) | ++====================+=====================================+==================+============================+==========================================================+ +| Index Number | ``index_number`` | ``long`` | ``KSParticle`` | Unique index number of the current step | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Parent Run ID | ``parent_run_id`` | ``int`` | ``KSParticle`` | Run ID of the parent step/track/event | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Parent Event ID | ``parent_event_id`` | ``int`` | ``KSParticle`` | Event ID of the parent step/track/event | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Parent Track ID | ``parent_track_id`` | ``int`` | ``KSParticle`` | Track ID of the parent step/track | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Parent Step ID | ``parent_step_id`` | ``int`` | ``KSParticle`` | Step ID of the parent step | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Particle ID | ``pid`` | ``long long`` | ``KSParticle`` | Assigned particle ID (PDG code) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Particle String ID | ``string_id`` | ``string`` | ``KSParticle`` | Assigned particle ID (human-readable) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Particle Mass | ``mass`` | ``double`` | ``KSParticle`` | Mass of the particle (in kg) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Particle Charge | ``charge`` | ``double`` | ``KSParticle`` | Charge of the particle (in C) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Particle Spin | ``total_spin`` | ``double`` | ``KSParticle`` | Spin magnitude of the particle (in hbar) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Gyromagnetic Ratio | ``gyromagnetic_ratio`` | ``double`` | ``KSParticle`` | Gyromagnetic ratio of the particle (in rad/sT) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Main Quantum No. | ``n`` | ``int`` | ``KSParticle`` | Main quantum number | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Second Quatum No. | ``l`` | ``int`` | ``KSParticle`` | Secondary quantum number | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Time | ``time`` | ``double`` | ``KSParticle`` | Time in the simulation (in s) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Wallclock Time | ``clock_time`` | ``double`` | ``KSParticle`` | Wallclock time (system time) at the current step | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Step Length | ``length`` | ``double`` | ``KSParticle`` | Length of the current step (in m) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Position Vector | ``position`` | ``KThreeVector`` | ``KSParticle`` | Position at the current step (in m) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Momentum Vector | ``momentum`` | ``KThreeVector`` | ``KSParticle`` | Momentum at the current step (in kg*m/s) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Velocity Vector | ``velocity`` | ``double`` | ``KSParticle`` | Velocity at the current step (in m/s) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Spin Vector | ``spin`` | ``KThreeVector`` | ``KSParticle`` | Spin at the current step (in hbar) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Index Number | ``spin0`` | ``double`` | ``KSParticle`` | | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Aligned Spin | ``aligned_spin`` | ``double`` | ``KSParticle`` | | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Spin Angle | ``spin_angle`` | ``double`` | ``KSParticle`` | | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Speed | ``speed`` | ``double`` | ``KSParticle`` | Total speed at the current step (in m/s) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Lorentz Factor | ``lorentz_factor`` | ``double`` | ``KSParticle`` | Lorentz factor at the current step | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Kinetic Energy | ``kinetic_energy`` | ``double`` | ``KSParticle`` | Kinetic energy at the current step (in J) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Kinetic Energy | ``kinetic_energy_ev`` | ``double`` | ``KSParticle`` | Kinetic energy at the current step (in eV) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Polar Angle | ``polar_angle_to_z`` | ``double`` | ``KSParticle`` | Polar angle relative to z-axis (in deg) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Azimuthal Angle | ``azimuthal_angle_to_x`` | ``double`` | ``KSParticle`` | Azimuthal angle relative to x-axis (in deg) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Magnetic Field | ``magnetic_field`` | ``KThreeVector`` | ``KSParticle`` | Magnetic field at the current step (in T) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Electric Field | ``electric_field`` | ``KThreeVector`` | ``KSParticle`` | Electric field at the current step (in V/m) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Magnetic Gradient | ``magnetic_gradient`` | ``KThreeMatrix`` | ``KSParticle`` | Magnetic gradient at the current step (in T/m) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Electric Potential | ``electric_potential`` | ``double`` | ``KSParticle`` | Electric potential at the current step (in V) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Long. Momentum | ``long_momentum`` | ``double`` | ``KSParticle`` | Longitudinal momentum at the current step (in kg*m/s) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Trans. Momentum | ``trans_momentum`` | ``double`` | ``KSParticle`` | Transversal momentum at the current step (in kg*m/s) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Long. Velocity | ``long_velocity`` | ``double`` | ``KSParticle`` | Longitudinal velocity at the current step (in m/s) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Trans. Velocity | ``trans_velocity`` | ``double`` | ``KSParticle`` | Transversal velocity at the current step (in m/s) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Polar Angle to B | ``polar_angle_to_b`` | ``double`` | ``KSParticle`` | Polar (pitch) angle relative to magnetic field (in deg) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Cyclotron Freq. | ``cyclotron_frequency`` | ``double`` | ``KSParticle`` | Cyclotron frequency at the current step (in Hz) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Magnetic Moment | ``orbital_magnetic_moment`` | ``double`` | ``KSParticle`` | Orbital magnetic moment at the current step (in A*m^2) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| GC Position Vector | ``guiding_center_position`` | ``KThreeVector`` | ``KSParticle`` | Guiding center position at the current step (in m) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Current Space | ``current_space_name`` | ``string`` | ``KSParticle`` | Name of the nearest space (see ``geo_space``) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Current Surface | ``current_surface_name`` | ``string`` | ``KSParticle`` | Name of the nearest surface (see ``geo_surface``) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Current Side | ``current_side_name`` | ``string`` | ``KSParticle`` | Name of the nearest side (see ``geo_side``) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| GC Velocity | ``gc_velocity`` | ``double`` | ``KSTrajTermDrift`` | Guiding center velocity (in m/s) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| GC Long. Force | ``longitudinal_force`` | ``double`` | ``KSTrajTermDrift`` | Longitudinal force added by drift terms (in N) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| GC Trans. Force | ``transverse_force`` | ``double`` | ``KSTrajTermDrift`` | Transversal force added by drift terms (in N) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Gy. Phase Velocity | ``phase_velocity`` | ``double`` | ``KSTrajTermGyration`` | Phase velocity of gyration around g.c. (in rad/s) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Synchrotron Force | ``total_force`` | ``double`` | ``KSTrajTermSynchrotron`` | Total force added by synchrotron radiation (in N) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Min. Distance | ``min_distance`` | ``double`` | ``KSTermMinDistance`` | Distance to the nearest surface (in m) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Interaction Count | ``step_number_of_interactions`` | ``int`` | ``KSIntCalculator`` | Number of interactions at current step | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Energy loss | ``step_energy_loss`` | ``double`` | ``KSIntCalculator`` | Energy loss at current step (in eV) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Angular Change | ``step_angular_change`` | ``double`` | ``KSIntCalculator`` | Angular change at current step (in deg) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Interaction Count | ``step_number_of_decays`` | ``int`` | ``KSIntDecayCalculator`` | Number of interactions at current step | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Energy loss | ``step_energy_loss`` | ``double`` | ``KSIntDecayCalculator`` | Energy loss at current step (in eV) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Enhancement Factor | ``enhancement_factor`` | ``double`` | ``KSModDynamicEnhancement``| Step modifier enhancement factor | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Run ID | ``run_id`` | ``int`` | ``KSRun`` | Run ID of current run | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Run Count | ``run_count`` | ``int`` | ``KSRun`` | Total number of runs | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Total Events | ``total_events`` | ``unsigned int`` | ``KSRun`` | Total number of events in run | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Total Tracks | ``total_tracks`` | ``unsigned int`` | ``KSRun`` | Total number of tracks in run | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Total Steps | ``total_steps`` | ``unsigned int`` | ``KSRun`` | Total number of steps in run | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Cont. Time | ``continuous_time`` | ``double`` | ``KSRun`` | Total time of all events/tracks/steps in run | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Cont. Length | ``continuous_length`` | ``double`` | ``KSRun`` | Total length of all events/tracks/steps in run | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Energy Change | ``continuous_energy_change`` | ``double`` | ``KSRun`` | Total energy change during run | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Momentum Change | ``continuous_momentum_change`` | ``double`` | ``KSRun`` | Total momentum change during run | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Secondaries Count | ``discrete_secondaries`` | ``unsigned int`` | ``KSRun`` | Number of secondaries created during run | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Energy Change | ``discrete_energy_change`` | ``double`` | ``KSRun`` | Total energy change during run | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Momentum Change | ``discrete_momentum_change`` | ``double`` | ``KSRun`` | Total momentum change during run | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Number of Turns | ``number_of_turns`` | ``unsigned int`` | ``KSRun`` | Number of particle turns/reflections during run | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Event ID | ``event_id`` | ``int`` | ``KSEvent`` | Event ID of current event | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Event Count | ``event_count`` | ``int`` | ``KSEvent`` | Total number of events | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Parent Run ID | ``parent_run_id`` | ``int`` | ``KSEvent`` | Run ID of parent run | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Total Tracks | ``total_tracks`` | ``unsigned int`` | ``KSEvent`` | Total number of tracks in event | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Total Steps | ``total_steps`` | ``unsigned int`` | ``KSEvent`` | Total number of steps in event | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Cont. Time | ``continuous_time`` | ``double`` | ``KSEvent`` | Total time of all tracks/steps in event | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Cont. Length | ``continuous_length`` | ``double`` | ``KSEvent`` | Total length of all tracks/steps in event | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Energy Change | ``continuous_energy_change`` | ``double`` | ``KSEvent`` | Total energy change during event | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Momentum Change | ``continuous_momentum_change`` | ``double`` | ``KSEvent`` | Total momentum change during event | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Secondaries Count | ``discrete_secondaries`` | ``unsigned int`` | ``KSEvent`` | Number of secondaries created during event | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Energy Change | ``discrete_energy_change`` | ``double`` | ``KSEvent`` | Total energy change during event | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Momentum Change | ``discrete_momentum_change`` | ``double`` | ``KSEvent`` | Total momentum change during event | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Number of Turns | ``number_of_turns`` | ``unsigned int`` | ``KSEvent`` | Number of particle turns/reflections during event | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Generator Name | ``generator_name`` | ``string`` | ``KSEvent`` | Name of the generator starting this event | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Generator Flag | ``generator_flag`` | ``bool`` | ``KSEvent`` | Additional flag of the used generator | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Primary Count | ``generator_primaries`` | ``unsigned int`` | ``KSEvent`` | Number of generated particles | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Generator Energy | ``generator_energy`` | ``double`` | ``KSEvent`` | Total energy of the generated particles (in eV) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Generator Time | ``generator_min_time`` | ``double`` | ``KSEvent`` | Minimum time of the generated particles (in s) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Generator Time | ``generator_max_time`` | ``double`` | ``KSEvent`` | Maximum time of the generated particles (in s) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Generator Position | ``generator_location`` | ``KThreeVector`` | ``KSEvent`` | Center position of the generated particles (in m) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Generator Radius | ``generator_radius`` | ``double`` | ``KSEvent`` | Maximum radius of the generated particles (in m) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Track ID | ``event_id`` | ``int`` | ``KSTrack`` | Track ID of current track | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Track Count | ``event_count`` | ``int`` | ``KSTrack`` | Total number of tracks | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Parent Event ID | ``parent_event_id`` | ``int`` | ``KSTrack`` | Event ID of parent track | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Total Steps | ``total_steps`` | ``unsigned int`` | ``KSTrack`` | Total number of steps in track | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Cont. Time | ``continuous_time`` | ``double`` | ``KSTrack`` | Total time of all steps in track | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Cont. Length | ``continuous_length`` | ``double`` | ``KSTrack`` | Total length of all steps in track | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Energy Change | ``continuous_energy_change`` | ``double`` | ``KSTrack`` | Total energy change during track | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Momentum Change | ``continuous_momentum_change`` | ``double`` | ``KSTrack`` | Total momentum change during track | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Secondaries Count | ``discrete_secondaries`` | ``unsigned int`` | ``KSTrack`` | Number of secondaries created during track | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Energy Change | ``discrete_energy_change`` | ``double`` | ``KSTrack`` | Total energy change during track | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Momentum Change | ``discrete_momentum_change`` | ``double`` | ``KSTrack`` | Total momentum change during track | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Number of Turns | ``number_of_turns`` | ``unsigned int`` | ``KSTrack`` | Number of particle turns/reflections during track | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Creator Name | ``creator_name`` | ``string`` | ``KSTrack`` | Name of the creator starting this track | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Terminator Name | ``terminator_name`` | ``string`` | ``KSTrack`` | Name of the terminator ending this track | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Initial Particle | ``initial_particle`` | ``KSParticle`` | ``KSTrack`` | Pointer to initial particle at begin of the track | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Final particle | ``final_particle`` | ``KSParticle`` | ``KSTrack`` | Pointer to final particle at end of the track | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Step ID | ``step_id`` | ``int`` | ``KSStep`` | Step ID of current step | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Step Count | ``step_count`` | ``int`` | ``KSStep`` | Total number of steps | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Parent Track ID | ``parent_track_id`` | ``int`` | ``KSStep`` | Track ID of parent track | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Cont. Time | ``continuous_time`` | ``double`` | ``KSStep`` | Total time of current step | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Cont. Length | ``continuous_length`` | ``double`` | ``KSStep`` | Total length of current step | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Energy Change | ``continuous_energy_change`` | ``double`` | ``KSStep`` | Total energy change during step | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Momentum Change | ``continuous_momentum_change`` | ``double`` | ``KSStep`` | Total momentum change during step | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Secondaries Count | ``discrete_secondaries`` | ``unsigned int`` | ``KSStep`` | Number of secondaries created during step | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Energy Change | ``discrete_energy_change`` | ``double`` | ``KSStep`` | Total energy change during step | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Momentum Change | ``discrete_momentum_change`` | ``double`` | ``KSStep`` | Total momentum change during step | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Number of Turns | ``number_of_turns`` | ``unsigned int`` | ``KSStep`` | Number of particle turns/reflections during step | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Modifier Name | ``modifier_name`` | ``string`` | ``KSStep`` | Name of the step modifier at this step | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Modifier Flag | ``modifier_flag`` | ``bool`` | ``KSStep`` | Additional flag for the used terminator | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Terminator Name | ``terminator_name`` | ``string`` | ``KSStep`` | Name of the terminator ending this step | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Terminator Flag | ``terminator_flag`` | ``bool`` | ``KSStep`` | Additional flag for the used terminator | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Trajectory Name | ``trajectory_name`` | ``string`` | ``KSStep`` | Name of the trajectory at this step | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Trajectory Center | ``trajectory_center`` | ``KThreeVector`` | ``KSStep`` | Position of the trajectory bounding sphere (in m) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Trajectory Radius | ``trajectory_radius`` | ``double`` | ``KSStep`` | Radius of the trajectory bounding sphere (in m) | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Trajectory Step | ``trajectory_step`` | ``double`` | ``KSStep`` | Time of the particle propagation | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Interaction Name | ``space_interaction_name`` | ``string`` | ``KSStep`` | Space name of the interaction at this step | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Interaction Flag | ``space_interaction_flag`` | ``bool`` | ``KSStep`` | Additional flag for the space interaction | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Interaction Step | ``space_interaction_step`` | ``double`` | ``KSStep`` | Time of the space interaction | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Navigation Name | ``space_navigation_name`` | ``string`` | ``KSStep`` | Space name of the navigation at this step | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Navigation Flag | ``space_navigation_flag`` | ``bool`` | ``KSStep`` | Additional flag for the space navigation | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Navigation Step | ``space_navigation_step`` | ``double`` | ``KSStep`` | Time of the space navigation | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Interaction Name | ``surface_interaction_name`` | ``string`` | ``KSStep`` | Surface name of the interaction at this step | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Interaction Flag | ``surface_interaction_flag`` | ``bool`` | ``KSStep`` | Additional flag for the surface interaction | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Navigation Name | ``surface_navigation_name`` | ``string`` | ``KSStep`` | Surface name of the navigation at this step | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Navigation Flag | ``surface_navigation_flag`` | ``bool`` | ``KSStep`` | Additional flag for the surface navigation | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Initial Particle | ``initial_particle`` | ``KSParticle`` | ``KSStep`` | Pointer to initial particle at begin of the step | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Finale Particle | ``final_particle`` | ``KSParticle`` | ``KSStep`` | Pointer to initial particle at begin of the step | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Intermed. Particle | ``interaction_particle`` | ``KSParticle`` | ``KSStep`` | Pointer to initial particle before interaction | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Intermed. Particle | ``navigation_particle`` | ``KSParticle`` | ``KSStep`` | Pointer to initial particle before navigation | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Intermed. Particle | ``terminator_particle`` | ``KSParticle`` | ``KSStep`` | Pointer to initial particle before termination | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ +| Intermed. Particle | ``trajectory_particle`` | ``KSParticle`` | ``KSStep`` | Pointer to initial particle before propagation | ++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+ + +Vector and matrix type can be accessed by their components in the written output data. For example, when the ``position`` +element is used, the corresponding fields in the output data can be found under the names ``position_x``, ``position_y``, +and ``position_z`. For matrix types, the rows are treated as 3-vectors themselves. Hence, the first element in a matrix +field named ``gradient`` can be found under ``gradient_x_x``, and so on. + +The following suffixes are available for the vector and matrix types. + ++-----------------------------------------------------------------------------+ +| Output field suffixes | ++--------------------+-------------------------------------+------------------+ +| Name | XML Element Suffix | Base Type | ++====================+=====================================+==================+ +| X Component | ``x`` | ``KThreeVector`` | ++--------------------+-------------------------------------+------------------+ +| Y Component | ``y`` | ``KThreeVector`` | ++--------------------+-------------------------------------+------------------+ +| Z Component | ``z`` | ``KThreeVector`` | ++--------------------+-------------------------------------+------------------+ +| Vector Magnitude | ``magnitude`` | ``KThreeVector`` | ++--------------------+-------------------------------------+------------------+ +| Squared Magnitude | ``magnitude_squared`` | ``KThreeVector`` | ++--------------------+-------------------------------------+------------------+ +| Radial Component | ``perp`` | ``KThreeVector`` | ++--------------------+-------------------------------------+------------------+ +| Squared Radial | ``perp_squared`` | ``KThreeVector`` | ++--------------------+-------------------------------------+------------------+ +| Polar Angle | ``polar_angle`` | ``KThreeVector`` | ++--------------------+-------------------------------------+------------------+ +| Azimuthal Angle | ``azimuthal_angle`` | ``KThreeVector`` | ++--------------------+-------------------------------------+------------------+ +| Determinant | ``determinant`` | ``KThreeMatrix`` | ++--------------------+-------------------------------------+------------------+ +| Trace | ``trace`` | ``KThreeMatrix`` | ++--------------------+-------------------------------------+------------------+ + +Navigation +---------- + +Surfaces navigation +~~~~~~~~~~~~~~~~~~~ + +The navigation of a particle is split into two components, surface navigation and space navigation. Surface navigation +is very simple and only takes place when a particle has intersected an active surface. The surface navigator determines +whether the state of the particle is modified on the surface and whether it is reflected or transmitted. It can be made +available for use with the declaration: + +.. code-block:: xml + + + +As this navigator is very simple, it does not take many additional parameters. The parameters ``transmission_split`` and +``reflection_split`` determine whether or not a track is split in two (for the purposes of output/saving data) upon +transmission through or reflection off a geometric surface. + +Space navigation +~~~~~~~~~~~~~~~~ + +The space navigator is more complex since it is responsible for determine the location of the particle and any possible +intersections it may have with real of virtual boundaries. It is also responsible for ensuring that the current +simulation state matches the configuration specified by the user. The spaces that the navigator considers may be real +objects (such as a vacuum chamber wall) or virtual (which only modify the state of the simulation, e.g. exchanging a +trajectory method). The latter case allows to dynamically reconfigure the simulation over a track. + +For space navigation there are two options. The first is the default ``ksnav_space`` navigator which can be specified as +below: + +.. code-block:: xml + + + +As this navigator is also very simple, it does not take many additional parameters. The parameters ``enter_split`` and +``exit_split`` determine whether or not a track is split in two upon entrance or exit of a geometric space. + +Meshed space navigation +~~~~~~~~~~~~~~~~~~~~~~~ + +A more complex behavior is achieved by the ``ksnav_meshed_space`` navigator, which is intended to be used in highly +detailed three-dimensional geometries where it has better performance over the default navigator. An example of this is +shown in the ``PhotoMultplierTube.xml`` file. Its configuration is more complicated as it performs the navigations on +the meshed boundaries of spaces and surfaces. It requires the construction of an octree spatial partition (which may be +cached for later re-use). The user must specify the depth of the octree (``max_octree_depth``) and the number of +elements allowed in a octree node before a subdivision is required (``n_allowed_elements``). In addition, the root of +the geometry tree must also be specified with the parameter ``root_space``, which is typically the world volume: + +.. code-block:: xml + + + +Though they are not shown here (they default to false), the exit and entrance split parameters may also be set for the +``ksnav_meshed_space`` navigator. Because the ``ksnav_meshed_space`` navigator requires a boundary mesh in order to +operate, all geometric objects (spaces, sufaces) which have navigation commands attached to them must also have a mesh +extension in the geometry specification. Furthermore, since ``ksnav_meshed_space`` requires access to the root space +``space_world`` and all of the navigation commands associated with the shapes it contains, it must be declared after the +definition of the simulation command structure element ``ksgeo_space`` (see below). + +The mesh navigator can also be used together with geometry from exernal files, as shown in the ``MeshSimulation.xml`` +example. + +Navigation and Commands +----------------------- + +For dyanmic configuration, *Kassiopeia* allows certain commands to be used during the calculation of a particle +trajectory. The commands are associated with particular surfaces and spaces and are what effectively governs the state +of the simulation as a particle is tracked. They are declared through the specification of a ``ksgeo_space``. A very +simple example of the declaration of the command structure can be seen in the DipoleTrapSimulation.xml as shown below: + +.. code-block:: xml + + + + + + + + + + + + + + + + + + +Note that in some configuration files, you may find alternative declarations such as: + +.. code-block:: xml + + + + +which are eequivalent to the commands shown above. + +Again, let us break down this example: + +- First we create a ``ksgeo_space`` navigation space using the ``world`` volume (a geometric object holding all other + elements.) Inside of this world volume we declare a series of command which will be executed any time a particle + enters or is initialized within the world volume. +- The first two commands add and remove specific terminators, while the next two declare what sort of output should be + written to disk while the particle is inside the world volume. +- Following that, there are commands which are attached to specific surfaces which are present in the geometry, and + handled by the navigator. For example in the first block, attaching the terminator ``term_upstream_target`` ensures + that a particle impinging on the surface ``surface_upstream_target`` will be terminated immediately. +- The last surface does not have any associated commands, but will still be considered for navigation. For example, + if ``transmission_split`` was set in the navigator, the track will be split if the particle crosses the surface. + +Commands can used to change the active field calculation method, swap trajectory types, or add/remove termsna and +interactions, define terminators, etc. Various spaces and their associated commands can be nested within each other +allowing for a very flexible and dynamic simulation configuration. For best results, it is important that the +structure of the ``geo_space`` and ``geo_surface`` elements follows the structure of the *KGeoBag* geometry tree, i.e. +nesting of the navigation elements should follow the same order as the underlying geometry. + +Simulation +---------- + +The final object to be declared within ```` is the simulation element. This describes the simulation object +**KSSimulation**, which is then executed by **KSRoot**. The simulation element specifies the global +and initial properties of the simulation as a whole. For example in the ``QuadrupoleTrapSimulation.xml`` example, the +simulation element is declared as follows: + +.. code-block:: xml + + + +The ``run`` is simply a user provided identifier. The ``seed`` is the value provided to the global (singleton) random +number generator. Simulations with the same configuration and same seed should provide identical results. If the user is +interested in running *Kassiopeia* on many machines in order to achieve high throughput particle tracking (Monte Carlo), +care must be taken to ensure that the ``seed`` value is different for each run of the simulation. + +The parameter ``events`` determines the total number of times that the generator is run (however this is not necessarily +the number of particles that will be tracked, e.g. if lists or sets are used in the generator of if secondary particles +are created). The remaining parameters ``magnetic_field``, ``space``, ``generator``, etc. all specify the default +objects to be used for the initial state of the simulation; where commands specified within ``ksgeo_space`` may +modify the actual objects used during the course of a simulation. + +Following the declaration of ``ks_simulation``, the closing tag ```` is placed to complete the simulation +configuration. When this tag is encountered by the XML parser, it triggers the simulation to run. + + +Visualization +------------- + +VTK visualization +~~~~~~~~~~~~~~~~~ + +If *Kassiopeia* has been linked against VTK_ or ROOT_, a simple visualization of the simulation can be made available. +By adding the `vtk_window` element at the end of the configuration file, we activate a VTK window that will open when +the simulation is complete. This element may hold a ``vtk_geometry_painter`` and a ```vtk_track_painter`` to draw the +geometry and tracks, respectively. An example of this type of visualization from the ``QuadrupoleTrapSimulation.xml`` +file is a follows: + +.. code-block:: xml + + + + + + +Note that the visualization window must be placed outside of the ````...```` +environment tags. + +ROOT visualization +~~~~~~~~~~~~~~~~~~ + +Similarly, a visualization window can be activated that uses the ROOT software. In constrast to VTK, which displays +three-dimensional geometry, the ROOT visualization is limited to two dimensions. A simple example that may be added +to the ``QuadrupoleTrapSimulation.xml`` file is as follows: + +.. code-block:: xml + + + + + + + + +.. _TFormula: http://root.cern.ch/root/htmldoc/TFormula.html +.. _TMath: http://root.cern.ch/root/htmldoc/TMath.html +.. _PDG: http://pdg.lbl.gov/mc_particle_id_contents.html +.. _Paraview: http://www.paraview.org/ +.. _ROOT: https://root.cern.ch/ +.. _VTK: http://www.vtk.org/ +.. _MKS: https://scienceworld.wolfram.com/physics/MKS.html +.. _XML: https://www.w3.org/TR/xml11/ +.. _Xpath: https://www.w3.org/TR/xpath-10/ +.. _TinyExpr: https://github.com/codeplea/tinyexpr/ +.. _Log4CXX: https://logging.apache.org/log4cxx/ +.. _Gnuplot: http://www.gnuplot.info/ + +.. rubric:: Footnotes + +[1] Daniel Lawrence Furse. Techniques for direct neutrino mass measurement utilizing tritium [beta]-decay. PhD thesis, Massachusetts Institute of Technology, 2015. + +[2] Thomas Corona. Methodology and application of high performance electrostatic field simulation in the KATRIN experiment. PhD thesis, University of North Carolina, Chapel Hill, 2014. + +[3] John P. Barrett. A Spatially Resolved Study of the KATRIN Main Spectrometer Using a Novel Fast Multipole Method. PhD thesis, Massachusetts Institute of Technology, 2016. diff --git a/Documentation/gh-pages/source/element_kemfield.rst b/Documentation/gh-pages/source/element_kemfield.rst new file mode 100644 index 000000000..c2e28d541 --- /dev/null +++ b/Documentation/gh-pages/source/element_kemfield.rst @@ -0,0 +1,189 @@ +.. _KEMField: + +KEMField (fields) - +=========================== + + + +**KEMField** is a toolkit that allows users to solve electrostatic and magnetostatic fields from user-defined inputs. +Detailed explanations on installation and implementation are available in the manual displayed at the bottom of this chapter. +Alternatively the manual is available for download :download:`here <../../../KEMField/Documentation/manual/manual.pdf>` +and can also be found in the `Github repository `_. + + +The field elements all live within the *KEMField* element and must be placed with start and end tags of the form: + +.. code-block:: xml + + + + + +Note that in some configuration files, you may find the "legacy style" setup where the field elements are defined under +the *Kassiopeia* element (see below). Although both variants are supported, it is recommended to follow the one +described here. + +Once the simulation geometry has been specified, the user may describe the types of electric and magnetic fields they +wish associate with each geometric object. The field package *KEMField* takes care of solving the boundary value problem +and computing the fields for electrostatic problems. It also handles the magnetic field computation from static current +distributions. + +Fast field calculation methods are available for axially symmetric (zonal harmonics) and three dimensional problems +(fast multipole method). The abstract base classes responsible for electric and magnetic fields in *Kassiopeia* are +**KSElectricField** and **KSMagneticField** respectively, which interface with the corresponding +implementations in *KEMField*. + +For example, in the ``DipoleTrapSimulation.xml`` example the electric and magnetic fields are axially symmetric and can +be computed using the zonal harmonics expansion. + +Electric fields +----------- + +To specify the electric field, the geometric surfaces which are electrically active must be listed in the ``surfaces`` +element. It is important that the surfaces which are specified have a mesh extension and a boundary type extension. If +either of these extensions are missing from the specified surface, they will not be included in the electrostatics +problem. A boundary element mesh is needed to solve the Laplace equation using the boundary element method. Each element +of the mesh inherits its parent surface's boundary condition type. + +Both a method to solve the Laplace boundary value problem (a ``bem_solver``), and a method by which to compute the +fields from the resulting charge densities must be given (a ``field_sovler``). In the following example we use a +``robin_hood_bem_solver`` and a ``zonal_harmonic_field_solver``: + +.. code-block:: xml + + + + + + +It is also important that geometric elements be meshed appropriately with respect to symmetry. In the case that the user +wishes to use zonal harmonic field calculation routines, an ``axial_mesh`` must be used. If a normal (3D) mesh is used, +zonal harmonics cannot function. Different mesh/symmetry types cannot be combined within the same electric field solving +element. The symmetry of the electric field model is set by the ``symmetry`` attribute. + +The zonal-harmonic solver offers many parameters to fine-tune the applied approximation. The example above lists mostly +default values. The most important parameter is probably the distance of the "source points", which provide the basis +for the approximation. The example above defines a spacing of 1 mm along the z-axis. + +In the three-dimensional mesh case, either an integrating field solver, or a fast multipole field solver may be used. +The integrating field solver may be specified through inclusion of the element: + +.. code-block:: xml + + + +within the the ``electrostatic_field`` element (replacing the ``zonal_harmonic_field_solver`` in the example above). +As the integrating field solver is quite simple, it does not require additional parameters. + +The fast multipole field solver on the other hand is somewhat more complex and requires a relatively large set of +additional parameters to be specified in order to configure its use according to the user's desired level of accuracy +and computational effort. + +For a complete list and description of the XML bindings available for the electric field solving routines, navigate to +the directory ``$KASPERSYS/config/KEMField/Complete``. The file ``ElectricFields.xml`` has examples of the binding for +initializing electric field problems (see :gh-code:`KEMField/Source/XML/Complete/ElectricFields.xml`.) + +Magnetic fields +---------- + +The specification of the magnetic field solving routines is considerably simpler since there is no need to solve a +boundary value problem before hand. There are essentially two choices for solving magnetic fields from static current +distributions: The zonal harmonics method for use with axially symmetric current sources, and the integrating magnetic +field solver which can be used on geometries with more arbitrary distributions of current. Unlike electric fields, +magnetic fields can contain components with both axially symmetric and non-axially symmetric elements within the same +region with no adverse effects. + +The following example uses the zonal harmonics method to compute the magnetic field: + +.. code-block:: xml + + + + + +Note that although the zonal harmonics solver allows a faster calculation of the electromagnetic fields, but requires +some initialization time to compute the source points. Depending on the simulation, the overall computation time could +be lower when using the integrating solver instead. + +Also, please note that only three *KGeoBag* shapes can be used to create electromagnets: cylinder surface, cylinder tube +space, and rod space. For details, see the above section `Extensions`. If other shapes are added to the electromagnet +field elemenet, they will not be recognized as magnet geometries. When using rod spaces, the resulting magnet element +will be a "line current" that does not allow any zonal harmonic approximation and is always solved directly. + +A complete list and set of examples of the XML bindings for magnetic fields can be found in the file +``$KASPERSYS/config/KEMField/Complete/MagneticFields.xml`` (see :gh-code:`KEMField/Source/XML/Complete/MagneticFields.xml`.) + +Further documentation on the exact methods and parameters used in *KEMField* can be found in [2] and [3]. + + +.. pdf-include:: ./PDFs/manual.pdf + :width: 100% + :height: 800px + + + +.. _TFormula: http://root.cern.ch/root/htmldoc/TFormula.html +.. _TMath: http://root.cern.ch/root/htmldoc/TMath.html +.. _PDG: http://pdg.lbl.gov/mc_particle_id_contents.html +.. _Paraview: http://www.paraview.org/ +.. _ROOT: https://root.cern.ch/ +.. _VTK: http://www.vtk.org/ +.. _MKS: https://scienceworld.wolfram.com/physics/MKS.html +.. _XML: https://www.w3.org/TR/xml11/ +.. _Xpath: https://www.w3.org/TR/xpath-10/ +.. _TinyExpr: https://github.com/codeplea/tinyexpr/ +.. _Log4CXX: https://logging.apache.org/log4cxx/ + + + +.. rubric:: Footnotes + +[1] Daniel Lawrence Furse. Techniques for direct neutrino mass measurement utilizing tritium [beta]-decay. PhD thesis, Massachusetts Institute of Technology, 2015. + +[2] Thomas Corona. Methodology and application of high performance electrostatic field simulation in the KATRIN experiment. PhD thesis, University of North Carolina, Chapel Hill, 2014. + +[3] John P. Barrett. A Spatially Resolved Study of the KATRIN Main Spectrometer Using a Novel Fast Multipole Method. PhD thesis, Massachusetts Institute of Technology, 2016. diff --git a/Documentation/gh-pages/source/element_kgeobag.rst b/Documentation/gh-pages/source/element_kgeobag.rst new file mode 100644 index 000000000..85ed1701a --- /dev/null +++ b/Documentation/gh-pages/source/element_kgeobag.rst @@ -0,0 +1,386 @@ + + +KGeoBag (geometry) - +***************************** + +.. _KGeoBag: + +.. contents:: On this page + :local: + :depth: 2 + + + +Geometry section +================= + +The geometry section of the configuration file is the first piece needed in order to assemble a simulation. At its first +and most basic level it is responsible for defining all the different shapes that will be used, and placing them with +respect to one another in order to construct the arrangement (often called `assembly`) that is needed. + +For a full a description of all of the shape objects (surfaces and spaces) which maybe constructed in *KGeoBag* see +:ref:`basic-kgeobag-label` and :ref:`complex-kgeobag-label`. The abstract base classes which serve as the interface +between *KGeoBag* and *Kassiopeia* are ``KSSpace``, ``KSSurface``, and ``KSSide`` (see :gh-code:`Kassiopeia/Operators`). + +The geometry section is also responsible for adding "extended" information to the defined geometry elements. These +extensions can be properties such as colors for visualization, or boundary conditions and meshing details for the +electromagnetic simulations. + +Every relevant to the geometry description is processed by *KGeoBag* and must appear between the start and end brackets: + +.. code-block:: xml + + + + + +It should be noted, that the full description of the geometry need not lie within the same pair of ```` and +```` brackets. This facilitates the description of separate geometry pieces in different files, which may +then be included and used in the final assembly. + +Shapes and assemblies +--------------------- + +To understand the basics of *KGeoBag*, let us look at a simple example. A typical simulation geometry may look like +the image below, where multiple spaces (B-D) and surfaces (a-b) are assembled and placed in a "world" space A: + +.. image:: _images/geometry_picture.png + :width: 250pt + +Internally, *KGeoBag* manages its geometric elements and their relations as a stree structure: + +.. image:: _images/geometry_tree.png + :width: 250pt + +Now, to understand how this works in practice, we'll look at one of the example files provided with *Kassiopeia*. Of +the example files provided, the ``DipoleTrapSimulation.xml`` has the simplest geometry. It will be explained in detail +below, in order to walk you through a typical geometry configuration. + +The geometry section starts off with a description of each shapes involved: + +.. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +The individual shapes are defined by elements of the common structure: + +.. code-block:: xml + + + + +where each element is given a name, which it can be referenced with, and additional parameters dependeing on the shape. +For example, the disk surface is defined by only two parameters `r` and `z`, while other shapes differ. + +Tagging system +-------------- + +The tagging system is used to group different elements together, for example by distinguishng between magnet and +electrode shapes. These tags will be used later to retrieve elements and pass them to the *KEMField* module. The +general syntax is: + +.. code-block:: xml + + + + + +and tags can be freely combined or re-used. + +Assembling elements +------------------- + +The defined shapes are then placed into an assembly of the experiment geometry. Geometric objects are placed by +referencing each shape by its given (and *unique*) name and placing it inside a space. This can be combined with +specifying a transformation (relative to the assembly origin) defining the location and orientation of each object. The +available transformation types are displacements (defined by a 3-vector), and rotations (defined by an axis-angle +pair, or a series of Euler angles using the *Z-Y'-Z''* convention): + +.. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + +Here the individual named shapes that were defined earlier are referenced, using the general syntax: + +.. code-block:: xml + + + + + +and spaces can be freely nested, which is one of the key features of *KGeoBag*. Note the difference between the first +space, which does not refer to any shape and just holds the child elements, and the second space which refers to the +shape named ``my_space`` through the `node` attribute. The ``my_assembly`` space can be though of as a "virtual space", +without any reference to a real geometric object. + +Finally in the ``DipoleTrapSimulation.xml`` file, the full assembly is placed within the world volume: + +.. code-block:: xml + + + + + +The world volume is a crucial part of any geometry, since it defines the outermost "root" space in which all other +elements must be placed. Note that in this case, the space named ``dipole_trap_assembly`` is referenced through the +`tree` attribute (and not `node`, as you might expect.) This is due to the fact that the assembly is a "virtual" space +that just holds its child elements, but does not refer to an actual object. Make sure to keep this in mind for your +own geometry configurations! + +Transformations +--------------- + +It should be noted that transformations applied to an assembly are collectively applied to all of the geometric elements +within the assembly. For example, placing the dipole trap assembly within the world volume as: + +.. code-block:: xml + + + + + + + +would rotate the whole assembly by 90 degrees about the z-axis, and then displace it by 1 meter along the z-axis. + +Assemblies may be nested within each other, and the coordinate transformations which are associated with the placement +of each assembly will be appropriately applied to all of the elements they contain. This makes it very intuitive to +create complex geometries with multiple displacements and rotations, because it resembles the behavior of real-world +objects (i.e. turning an assemble object by some amount will also turn all parts inside by the same amount, relative +to the outside coordinate system.) + +Especially for rotations, it should be noted that it makes a difference if they are applied in the assembly before or +after placing child elements. Consider the following example: + +.. code-block:: xml + + + + + + + + + + + + + + +In this case, the ``placed_disk`` in in the first assembly will be tilted relative to the world volume, while the +disk in the second assembly will not! This can be verified easily with one of the geometry viewers, which are explained +in section :ref:`visualization-label`. The reason for this behavior is that in the second case, the rotation was +applied before placing the surface inside the assembly, and so it is not propagated to the shape. This is on purpose, +because it allows to transform the origin and orientation of the reference system before assembling elements. + +It is best to think of the ```` elements as commands that are executed during XML initialization, while +the geometry is assembled. It should be clear then that the two example assemblies yield different results. + +Extensions +----------- + +In order to give physical properties to the geometry elements that have been constructed and placed, they must be +associated with extensions. The currently available extensions are *meshing* (axially or rotationally symmetric, or +non-symmetric), *visualization* properties, electrostatic *boundary conditions* (Dirichlet or Neumann surfaces), and +magnetostatic properties of *solenoids and coils* (current density and number of windings.) + +A simple extension example is specifying the color and opacity of a shape for its display in a VTK_ visualization window +as follows: + +.. code-block:: xml + + + +This example tells the visualization that any shape given the tag ``magnet_tag`` should be colored with an RGBA color +value of (0,255,127,127), where all values are given in the range 0..255 and the fourth value defines the shape's +opacity. If you have VTK enabled you may wish to experiment with the changes introduced by modifying these parameters. +When using the ROOT_ visualization, the appearance settings will be ignored. + +In the line above, you also find an example of referencing tags throught the ``@tag_name`` syntax. Generally the +placed shapes can be referenced through a XPath_-like syntax that defines the location in the geometry tree, starting +at the "root" volume (which is typically called `world`.) This usually works with all `spaces` and `surfaces` +attributes of the XML elements. + +The tagging feature is very useful for applying properties to many different elements at once. To do this, each element +which is to receive the same extension must share the same tag. There is no limit to the number of tags an geometric +element may be given. For example, given the dipole trap geometry as specified, one may associate an axially symmetric +mesh with all elements that share the tag ``electrode_tag`` with the line: + +.. code-block:: xml + + + +This specifies that any geometric shape with the tag ``electrode_tag`` that is found within the ``world/dipole_trap`` +space should be giving an axial mesh extension (i.e. it will be divided into a collection of axially symmetric objects +like cones, cylinders, etc.) This axial mesh will be later used by the field solving routines in *KEMField*. However, a +tag is not strictly necessary to apply an extension. For example, if we wished to generate an axial mesh for everything +within the world volume we would write: + +.. code-block:: xml + + + +or, if we wished to single out the ``ring_surface`` shape by specifying its full path we would write: + +.. code-block:: xml + + + +Meshing is critical for any problem with involves electrostatic fields. The type of mesh depends on the symmetry of the +geometry. For completely axially-symmetric geometries, the ``axial_mesh`` is recommended so that the zonal harmonics +field computation method may be used. For completely non-symmetric (3D) geometries, the mesh type would be specified as +follows: + +.. code-block:: xml + + + +Because of the very shape-specific nature of the deterministic meshing which is provided by *KGeoBag*, parameters +(``mesh_count`` and ``mesh_power``) describing how the mesh is to be constructed are given when specifying the shapes +themselves. That being said, the mesh associated with a specific shape will not be constructed unless the extension +statement is present. + +It is possible to define multiple meshes side by side, e.g. if the simulation can be configured axially-symmetric or +non-symmetric. In this case, both meshes will be available for *KEMField* calculations regardless of the symmetry +setting. Note that the axial mesh cannot handle any non-symmetric elements, and these will be simply ignored. + +Another important extension for field calculations is the specification of boundary conditions. For example, when +solving the Laplace boundary value problem via *KEMField*, one may specify that a particular surface exhibit Dirichlet +boundary conditions where a particular voltage is applied to the surface through the use of the following extension: + +.. code-block:: xml + + + +Where ``value="-10"`` signifies that this surface has a potential of -10 volts. This is the standard case for defining +(metallic) electrode surfaces in a simulation, and a typical scenario for the boundary-element method (BEM). It is also +possible to define Neumann boundary conditions, which are typically used for insulating materials. + +Similar to the electrode setup, one can define a magnet system that provides a magnetostatic field for the simulation. +For example, one may specify a solenoid electromagnet with the appropriate parameters: + +.. code-block:: xml + + + +which references a space named ``upstream_solenoid`` with a total current of 22.3047 amps times 20000 turns. The +electric current and the number of turns can also be specified separately for added clarity: + +.. code-block:: xml + + + +The cylinder tube space is one of the supported shapes for electromagnets and describes a solenoid geometry. Other +supported shapes are the cylinder surface, describing a simple coil, and the rod space, describing a single wire. + +For further demonstrations of the possible geometry extensions please see the provided example XML files located +at :gh-code:`KGeoBag/Source/XML/Examples`. + +KGeoBag shapes +=============== + +See the following two chapters for an overview over simple and more advanced shapes: + +.. toctree:: + :maxdepth: 1 + + + kgeobag_simple_shapes + kgeobag_complex_shapes + + +.. _TFormula: http://root.cern.ch/root/htmldoc/TFormula.html +.. _TMath: http://root.cern.ch/root/htmldoc/TMath.html +.. _PDG: http://pdg.lbl.gov/mc_particle_id_contents.html +.. _Paraview: http://www.paraview.org/ +.. _ROOT: https://root.cern.ch/ +.. _VTK: http://www.vtk.org/ +.. _MKS: https://scienceworld.wolfram.com/physics/MKS.html +.. _XML: https://www.w3.org/TR/xml11/ +.. _Xpath: https://www.w3.org/TR/xpath-10/ +.. _TinyExpr: https://github.com/codeplea/tinyexpr/ +.. _Log4CXX: https://logging.apache.org/log4cxx/ + +.. rubric:: Footnotes + +[1] Daniel Lawrence Furse. Techniques for direct neutrino mass measurement utilizing tritium [beta]-decay. PhD thesis, Massachusetts Institute of Technology, 2015. + +[2] Thomas Corona. Methodology and application of high performance electrostatic field simulation in the KATRIN experiment. PhD thesis, University of North Carolina, Chapel Hill, 2014. + +[3] John P. Barrett. A Spatially Resolved Study of the KATRIN Main Spectrometer Using a Novel Fast Multipole Method. PhD thesis, Massachusetts Institute of Technology, 2016. diff --git a/Documentation/gh-pages/source/examples.rst b/Documentation/gh-pages/source/examples.rst index ef28b8b39..413190d8c 100644 --- a/Documentation/gh-pages/source/examples.rst +++ b/Documentation/gh-pages/source/examples.rst @@ -1,7 +1,13 @@ Example configurations ====================== -Next in this section, we will investigate a number of pre-configured example files that are shipped with *Kassiopeia*. +.. contents:: On this page + :local: + :depth: 2 + + + +Next, we will investigate a number of pre-configured example files that are shipped with *Kassiopeia*. These files serve as a working example of various features of the simulation, but also as a reference for your own configurations. Please take some time to investigate these example files. diff --git a/Documentation/gh-pages/source/index.rst b/Documentation/gh-pages/source/index.rst index b95f50237..14a06ba8d 100644 --- a/Documentation/gh-pages/source/index.rst +++ b/Documentation/gh-pages/source/index.rst @@ -36,7 +36,12 @@ Welcome to Kassiopeia's documentation! ************************************** .. dropdown:: **Documentation Contents** - + + .. toctree:: + :maxdepth: 4 + + Welcome to Kassiopeia's documentation! + .. toctree:: :maxdepth: 4 :caption: General information @@ -63,24 +68,25 @@ Welcome to Kassiopeia's documentation! Running Kassiopeia Example configurations Configuring your own simulation + KGeoBag (geometry) - + KEMField (fields) - + Kassiopeia (particles) - .. toctree:: :maxdepth: 4 :caption: Further Information - Basic KGeoBag Shapes - Complex KGeoBag Shapes Understanding Simulation Output Additional Simulation Tools Visualization Techniques XML Bindings - KEMField + This simulation package by `the KATRIN collaboration`_ allows to run highly customizable particle tracking simulations -along with calculations of electric and magnetic fields. +along with calculations of electric and magnetic fields. *Kassiopeia* is supported and intended to run on systems running either Linux or MacOS X. diff --git a/Documentation/gh-pages/source/introduction.rst b/Documentation/gh-pages/source/introduction.rst index f4abf06dd..a414f1022 100644 --- a/Documentation/gh-pages/source/introduction.rst +++ b/Documentation/gh-pages/source/introduction.rst @@ -46,16 +46,4 @@ certain specific features in their own novel applications. Code contributions th can be submitted through GitHub and are always welcome. - - - -Supported operating systems and hardware requirements -===================================================== - -*Kassiopeia* is supported and intended to run on systems running either Linux or MacOS X. Currently, it has been -compiled and tested to run on fresh installations of the Linux distributions Fedora 31 and Ubuntu 20.04 LTS. It is also -expected to compile and run on other Linux distributions, however this has not been tested, and the steps needed to -compile *Kassiopeia* may deviate from what is outlined here. - - .. _KATRIN: https://www.katrin.kit.edu \ No newline at end of file diff --git a/Documentation/gh-pages/source/kgeobag_complex.rst b/Documentation/gh-pages/source/kgeobag_complex_shapes.rst similarity index 92% rename from Documentation/gh-pages/source/kgeobag_complex.rst rename to Documentation/gh-pages/source/kgeobag_complex_shapes.rst index 15710e370..225d7f7e4 100644 --- a/Documentation/gh-pages/source/kgeobag_complex.rst +++ b/Documentation/gh-pages/source/kgeobag_complex_shapes.rst @@ -1,453 +1,474 @@ -.. _complex-kgeobag-label: - -Complex Shapes in KGeoBag -************************* - -This section describes the more complicated shapes available in *KGeoBag*. Since as of yet, *KGeoBag* lacks the ability -to perform boolean operations on solids (constructive solid geometry), shapes which cannot be represented as an assembly -of basic shapes must be explicitly defined in C++. However, to augment the basic shapes, *KGeoBag* provides some -additional complex shapes that are commonly encountered in experimental structures such as vacuum chambers, etc. - -Some of the examples in this section make use of the the more advanced features of the XML parser, including loops, -conditional statements, and equation evaluation. - -.. contents:: On this page - :local: - :depth: 2 - -Surfaces -======== - -Pump Port Surface ------------------ - -The shape creates a tube-like surface with circular or rectangular pump ports (e.g. for vacuum chambers). The -coordinates (x,y,z) are the end points of the ports. The ports can only be created in radial direction. - -.. image:: _images/kgeobag_port_housing_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: No. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - -Conic Section Pump Port Surface -------------------------------- - -This shape is a cut cone surface with circular ports. The ports can be created either orthogonal to the surface or -parallel to the cone axis (paraxial). The coordinates (x,y,z) are the end points of the port. - -.. image:: _images/kgeobag_conic_section_port_housing_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: No. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - - - - - - -Beam Surface ------------- - -A beam creates a pipe which connects two polygons at each end. The polygons must have the same number of vertices but -may lie in planes which are not parallel to each other. For the description of the parameters involved see the images -below. - -.. image:: _images/beam_description.png - :width: 250pt - -In the following example, the variable ``[poly]`` dictates the the number of vertexes in each polygon at the ends of the -beam. - -.. image:: _images/kgeobag_beam_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: No. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - - - - - - -Multi-cut surfaces -~~~~~~~~~~~~~~~~~~ - -The beam shape can also be used to create more complex objects, such as a cut cone with two more cuts at both ends. - -.. image:: _images/kgeobag_multicut_surface_model.png - :width: 400pt - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - - - - - - - - - -Rod Surface ------------ - -The rod element can be used to create a rod like structure along a series of linear segments in three dimensional space. -The rod has a circular cross section which is approximated by a polygon (governed by the ``axial_mesh_count`` -parameter). This shape is defined by a radius (thickness of the rod) and a piecewise linear path specified by a by a -list of in-order vertexes. - -.. image:: _images/kgeobag_rod_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: No. - -The following XML example creates a helix shaped rod surface, as follows: - -.. code-block:: xml - - - - - - - - - - - - - -Extruded Surfaces with holes ----------------------------- - -With this element it is possible to create an extruded surface (from a poly-loop like curve) with arbitrary holes in it. -The commands ```` and ```` define whether the extruded path will produce an outer or an inner -surface. Therefore, they define if there will be a hole in the surface and its shape. - -.. image:: _images/kgeobag_extruded_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: No. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - - - - -Rotated Surface ---------------- - -This shape is very similar to rotated poly-line surface in :ref:`basic-kgeobag-label` but with other variables. The -coordinates in use in this shape are cylindrical. (z,r) - -.. image:: _images/kgeobag_rotated_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: No. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - - - - -Spaces -====== - -These elements generate volume (filled) objects. The for the following geometries is not supported at the moment. For -the definition of the variables see the corresponding surfaces above. - -Pump Port Space ---------------- - -For visualization, see the above pump port surface. - -- Works with GeometryViewer: No. -- Works with MeshViewer: No. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - -Conic Section Pump Port Space ------------------------------ - -For visualization, see the above conic section pump port surface. - -- Works with GeometryViewer: No. -- Works with MeshViewer: No. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - - - - - - -Beam Space ----------- - -For visualization, see the beam surface above. - -- Works with GeometryViewer: No. -- Works with MeshViewer: No. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - - - - - - -Rod Space ---------- - -For visualization, see the above rod surface. - -- Works with GeometryViewer: No. -- Works with MeshViewer: No. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - - - -Extruded Space --------------- - -For visualization see the above extruded space. - -- Works with GeometryViewer: No. -- Works with MeshViewer: No. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - - - - -Rotated Space -------------- - -For visualization see the above rotated surface. - -- Works with GeometryViewer: No. -- Works with MeshViewer: No. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - - - - -Shapes from imported files -========================== - -As an alternative to defining geometries via the XML file format, one may also use geometric objects from external -files. The only available file format is STL, which is supported by the majority of current 3D design software. The -STL file contains a set of triangles, which are treated as a fully meshed geometry in *KGeoBag*. As such, the geometry -is usable with *KEMField* (for electric field calculation) and *Kassiopeia* (for particle navigation.) - - -STL File Surface ----------------- - -.. image:: _images/kgeobag_teapot_mesh.png - :width: 400pt - -- Works with GeometryViewer: Yes. -- Works with MeshViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - - - -Note that because the geometry is defined by an external file, the possible modifications in the *KGeoBag* framework -are limited. Besides the translations/rotations that can be applied to any object, one may also scale the external -geometry or increase its number of mesh elements. If the triangles in the file are sufficienctly ordered, then one -can use the ``selector`` attribute to specify indices of the triangles to be used in *KGeoBag*. In the case of the -``Utah_teapot.stl`` example file, this allows to split the lid from the pot's body. - -STL File Space --------------- - -For visualization see the above STL file surface. - -- Works with GeometryViewer: Yes. -- Works with MeshViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - + +.. _complex-kgeobag-label: + +Complex Shapes in KGeoBag +========================= + +This section describes the more complicated shapes available in *KGeoBag*. Since as of yet, *KGeoBag* lacks the ability +to perform boolean operations on solids (constructive solid geometry), shapes which cannot be represented as an assembly +of basic shapes must be explicitly defined in C++. However, to augment the basic shapes, *KGeoBag* provides some +additional complex shapes that are commonly encountered in experimental structures such as vacuum chambers, etc. + +Some of the examples in this section make use of the the more advanced features of the XML parser, including loops, +conditional statements, and equation evaluation. + +Surfaces +---------- + +Pump Port Surface +~~~~~~~~~~~~~~~~~~ + +The shape creates a tube-like surface with circular or rectangular pump ports (e.g. for vacuum chambers). The +coordinates (x,y,z) are the end points of the ports. The ports can only be created in radial direction. + +.. image:: _images/kgeobag_port_housing_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: No. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + +Conic Section Pump Port Surface +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This shape is a cut cone surface with circular ports. The ports can be created either orthogonal to the surface or +parallel to the cone axis (paraxial). The coordinates (x,y,z) are the end points of the port. + +.. image:: _images/kgeobag_conic_section_port_housing_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: No. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + + + + + + +Beam Surface +~~~~~~~~~~~~~~ + +A beam creates a pipe which connects two polygons at each end. The polygons must have the same number of vertices but +may lie in planes which are not parallel to each other. For the description of the parameters involved see the images +below. + +.. image:: _images/beam_description.png + :width: 250pt + +In the following example, the variable ``[poly]`` dictates the the number of vertexes in each polygon at the ends of the +beam. + +.. image:: _images/kgeobag_beam_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: No. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + + + + + + +Multi-cut surfaces +""""""""""""""""""" + +The beam shape can also be used to create more complex objects, such as a cut cone with two more cuts at both ends. + +.. image:: _images/kgeobag_multicut_surface_model.png + :width: 400pt + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + + + + + + + + + +Rod Surface +~~~~~~~~~~~~~ + +The rod element can be used to create a rod like structure along a series of linear segments in three dimensional space. +The rod has a circular cross section which is approximated by a polygon (governed by the ``axial_mesh_count`` +parameter). This shape is defined by a radius (thickness of the rod) and a piecewise linear path specified by a by a +list of in-order vertexes. + +.. image:: _images/kgeobag_rod_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: No. + +The following XML example creates a helix shaped rod surface, as follows: + +.. code-block:: xml + + + + + + + + + + + + + +Extruded Surfaces with holes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +With this element it is possible to create an extruded surface (from a poly-loop like curve) with arbitrary holes in it. +The commands ```` and ```` define whether the extruded path will produce an outer or an inner +surface. Therefore, they define if there will be a hole in the surface and its shape. + +.. image:: _images/kgeobag_extruded_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: No. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + + + + +Rotated Surface +~~~~~~~~~~~~~~~~~~~~ + +This shape is very similar to rotated poly-line surface in :ref:`basic-kgeobag-label` but with other variables. The +coordinates in use in this shape are cylindrical. (z,r) + +.. image:: _images/kgeobag_rotated_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: No. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + + + + +Spaces +-------- + +These elements generate volume (filled) objects. The for the following geometries is not supported at the moment. For +the definition of the variables see the corresponding surfaces above. + +Pump Port Space +~~~~~~~~~~~~~~~~~~ + +For visualization, see the above pump port surface. + +- Works with GeometryViewer: No. +- Works with MeshViewer: No. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + +Conic Section Pump Port Space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For visualization, see the above conic section pump port surface. + +- Works with GeometryViewer: No. +- Works with MeshViewer: No. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + + + + + + +Beam Space +~~~~~~~~~~~~~ + +For visualization, see the beam surface above. + +- Works with GeometryViewer: No. +- Works with MeshViewer: No. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + + + + + + +Rod Space +~~~~~~~~~~ + +For visualization, see the above rod surface. + +- Works with GeometryViewer: No. +- Works with MeshViewer: No. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + + + +Extruded Space +~~~~~~~~~~~~~~~~~~ + +For visualization see the above extruded space. + +- Works with GeometryViewer: No. +- Works with MeshViewer: No. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + + + + +Rotated Space +~~~~~~~~~~~~~~~~ + +For visualization see the above rotated surface. + +- Works with GeometryViewer: No. +- Works with MeshViewer: No. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + + + + +Shapes from imported files +----------------------------- + +As an alternative to defining geometries via the XML file format, one may also use geometric objects from external +files. The only available file format is STL, which is supported by the majority of current 3D design software. The +STL file contains a set of triangles, which are treated as a fully meshed geometry in *KGeoBag*. As such, the geometry +is usable with *KEMField* (for electric field calculation) and *Kassiopeia* (for particle navigation.) + + +STL File Surface +~~~~~~~~~~~~~~~~~~~ + +.. image:: _images/kgeobag_teapot_mesh.png + :width: 400pt + +- Works with GeometryViewer: Yes. +- Works with MeshViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + + + +Note that because the geometry is defined by an external file, the possible modifications in the *KGeoBag* framework +are limited. Besides the translations/rotations that can be applied to any object, one may also scale the external +geometry or increase its number of mesh elements. If the triangles in the file are sufficienctly ordered, then one +can use the ``selector`` attribute to specify indices of the triangles to be used in *KGeoBag*. In the case of the +``Utah_teapot.stl`` example file, this allows to split the lid from the pot's body. + +STL File Space +~~~~~~~~~~~~~~~~~~ + +For visualization see the above STL file surface. + +- Works with GeometryViewer: Yes. +- Works with MeshViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + +.. _TFormula: http://root.cern.ch/root/htmldoc/TFormula.html +.. _TMath: http://root.cern.ch/root/htmldoc/TMath.html +.. _PDG: http://pdg.lbl.gov/mc_particle_id_contents.html +.. _Paraview: http://www.paraview.org/ +.. _ROOT: https://root.cern.ch/ +.. _VTK: http://www.vtk.org/ +.. _MKS: https://scienceworld.wolfram.com/physics/MKS.html +.. _XML: https://www.w3.org/TR/xml11/ +.. _Xpath: https://www.w3.org/TR/xpath-10/ +.. _TinyExpr: https://github.com/codeplea/tinyexpr/ +.. _Log4CXX: https://logging.apache.org/log4cxx/ + +.. rubric:: Footnotes + +[1] Daniel Lawrence Furse. Techniques for direct neutrino mass measurement utilizing tritium [beta]-decay. PhD thesis, Massachusetts Institute of Technology, 2015. + +[2] Thomas Corona. Methodology and application of high performance electrostatic field simulation in the KATRIN experiment. PhD thesis, University of North Carolina, Chapel Hill, 2014. + +[3] John P. Barrett. A Spatially Resolved Study of the KATRIN Main Spectrometer Using a Novel Fast Multipole Method. PhD thesis, Massachusetts Institute of Technology, 2016. diff --git a/Documentation/gh-pages/source/kgeobag_basic.rst b/Documentation/gh-pages/source/kgeobag_simple_shapes.rst similarity index 92% rename from Documentation/gh-pages/source/kgeobag_basic.rst rename to Documentation/gh-pages/source/kgeobag_simple_shapes.rst index 5cb54d2ac..529fe6ef3 100644 --- a/Documentation/gh-pages/source/kgeobag_basic.rst +++ b/Documentation/gh-pages/source/kgeobag_simple_shapes.rst @@ -1,1059 +1,1074 @@ -.. _basic-kgeobag-label: - -Basic Shapes in KGeoBag -*********************** - -This section is a description of the basic spaces and surfaces which can be constructed using *KGeoBag*. All of the -following shapes can be displayed by the executables ``MeshViewer`` and ``GeometryViewer`` (see :ref:`visualization-label`). -These executables are built and installed along with *KGeoBag* when it is linked against VTK_. - -.. contents:: On this page - :local: - :depth: 2 - -Geometry visualization -====================== - -In order to view a geometry you can execute ``GeometryViewer`` from the directory ``$KASPERSYS/install/bin`` with the -path to your geometry file (.xml) and the name of the geometry element you want to display as the arguments: - -.. code-block:: bash - - ./GeometryViewer ../config/TheBag/Examples/ExampleShapes.xml example_rotated_surface - -An example of the geometry view is shown below: - -.. image:: _images/geometryviewer.png - :width: 400pt - -To visualized the mesh of a geometric element execute MeshViewer in ``$KASPERSYS/install/bin`` with the path to your -geometry file (.xml) and the name of the geometry element you want to display: - -.. code-block:: bash - - ./MeshViewer <../config/TheBag/Examples/ExampleShapes.xml> - -There is also an ``AxialMeshViewer`` available, which displays the axial mesh (if defined) in the same way. The -geometric element can be a specific element or several elements collected into a group. To display a single element use -its name, to show a tagged group the argument is written as ``@tag_group``. An example of the mesh viewer being used on -a rod surface is shown below: - -.. image:: _images/meshviewer.png - :width: 400pt - -The ``GeometryViewer`` and ``MeshViewer`` will also produce a VTK poly-data file (.vtp) which can then be open in the -external application Paraview_ for more advanced visualization. - -The parameters specifying the method by which a geometric element is meshed must be given in the geometry file when the -shape is described. If no mesh is desired for some object, the mesh parameters may be ignored and the defaults will be -used. The commands above may also be tried with one of the *Kassiopeia* simulation examples. - -The mesh parameters vary for each object, but essentially describe two properties (for each meshable dimension). These -are the ``mesh_count`` and the ``mesh_power``. If the ``mesh_power`` is set equal to 1.0, then the ``mesh_count`` simply -specifies the number of equally sized segments that a shape will be chopped into, along a particular dimension. If the -``mesh_power`` is greater than 1.0, then the density of segments will increase towards the edges of the shape while -keeping the number of elements the same. The ``mesh_power`` property is useful for tailoring the accuracy of mesh -descriptions for Laplace boundary value problems, where quantities such as charge density may vary considerably near the -sharp edges of an object. Therefore, this parameter is mainly used for electrode meshes. - -The following sections provide examples and brief descriptions of some basic shapes available for use in *KGeoBag*. - -Basic elements -============== - -The following elements (poly-loop and poly-line) are internal descriptors. They can't be used by themselves outside a -geometry element. This section serves as a brief explanation for the structure of these shapes. - -Poly-loop ---------- - -A poly-loop is a closed sequence consisting of several lines and/or arcs that form a polygonal shape. The aequence -starts with ```` and ends with ```` or ````, and multiple ```` or ```` elements can be put in between. An example of a poly-loop element is as follows: - -.. code-block:: xml - - - - - - - - -which creates a line from (0,0) to (0.4,-0.1) followed by an arc to (-0.1,0.4), and then the loop is closed by a line -back to the starting point. Note that poly-loop and poly-line are two-dimensional objects that operate in (x,y) -coordinates. Any line that is created by a ```` command goes from the end-point of the previous line to the -specified coordinate. The directive ```` or ```` connects the first and last points with -the specified segment type. - -The arc elements are described with the boolean parameters ``right`` and ``short``, as shown here: - -.. image:: _images/short_true_false.png - -where ``right="true"`` means that the circle segment will be drawn clockwise, and vice versa. ``short="true"`` means -that the arc will be the shorter one of the two possiblities. - -Poly-line ---------- - -This element is desribed using the same procedure as in poly-loop. However, the first and last points are not -necessarily connected. An XML example is below: - -.. code-block:: xml - - - - - - - - - -In this case, the sequence progresses through five (x,y) points but does not connect back to the starting point. Hence, -it does not form a closed loop like the poly-loop element does, and does not need a ```` command. Otherwise, -the parameters for poly-line are the same as for poly-loop. - -Surfaces -======== - -Flat surfaces -------------- - -Flattened circle surface -~~~~~~~~~~~~~~~~~~~~~~~~ - -A flattened circle surface is just a surface with circular shape, where (x,y,z) are the coordinates for the center of -the circle and r is the radius: - -.. image:: _images/kgeobag_flattened_circle_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - -Flattened poly-loop surface -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -A flattened poly loop surface is a surface consisting of several lines, arcs or both, creating a polygon of your desired -shape. The first line and the last line are connected automatically. By using the features of the poly-loop outlined -above, this provides a very flexible method of designing surface elements. - -.. image:: _images/kgeobag_flattened_poly_loop_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - -Rotated Surfaces ----------------- - -All rotated surfaces are constructed from lines, arcs, poly-lines, or poly-loops which are then rotated around the local -x-axis. - -Rotated line segment surface -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This type generates the surface of revolution formed by a line that is rotated around the x-axis. - -.. image:: _images/kgeobag_rotated_line_segment_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - -Rotated arc segment surface -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This type generates the surface of revolution formed by an arc that is rotated around the x-axis. - -.. image:: _images/kgeobag_rotated_arc_segment_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - -Rotated poly-line surface -~~~~~~~~~~~~~~~~~~~~~~~~~ - -This type generates the surface of revolution created by rotating a poly-line around the local x-axis. - -.. image:: _images/kgeobag_rotated_poly_line_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - -Rotated circle surface -~~~~~~~~~~~~~~~~~~~~~~ - -This type generates the surface of revolution created by rotating a circle around the local x-axis. This shape is -essentially or torus, or a section of a torus. - -.. image:: _images/kgeobag_rotated_circle_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - -Rotated poly loop surface -~~~~~~~~~~~~~~~~~~~~~~~~~ - -This type generates the surface of revolution created by rotating a poly-loop around the local x-axis. - -.. image:: _images/kgeobag_rotated_poly_loop_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - - - - - -Shell Surfaces --------------- - -All shell surfaces are lines, arcs or surfaces that are rotated around the x-axis between a given start angle -(angle_start) and stop angle (angle_stop). - -Shell line segment surface -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This produces an angularly limited portion of a surface of revolution from a line that is rotated around the local -x-axis. - -.. image:: _images/kgeobag_shell_line_segment_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - -Shell arc segment surface -~~~~~~~~~~~~~~~~~~~~~~~~~ - -This produces an angularly limited portion of a surface of revolution from an arc that is rotated around the local -x-axis. - -.. image:: _images/kgeobag_shell_arc_segment_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - -Shell poly-line surface -~~~~~~~~~~~~~~~~~~~~~~~ - -This produces an angularly limited portion of a surface of revolution from a poly-line that is rotated around the local -x-axis. - -.. image:: _images/kgeobag_shell_poly_line_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - -Shell circle surface -~~~~~~~~~~~~~~~~~~~~ - -This produces an angularly limited portion of a surface of revolution from a circle that is rotated around the local -x-axis. - -.. image:: _images/kgeobag_shell_circle_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - -Shell poly-loop surface -~~~~~~~~~~~~~~~~~~~~~~~ - -This produces an angularly limited portion of a surface of revolution from a poly-loop that is rotated around the local -x-axis. - -.. image:: _images/kgeobag_shell_poly_loop_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - - - - - -Extruded Surfaces ------------------ - -Extruded surfaces are surfaces that are extruded along the direction of the local z-axis from a minimum z-position -(zmin) to a maximum z-position (zmax). - -Extruded poly-line surface -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This generates a surface by extruding a poly-line. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - -Extruded circle surface -~~~~~~~~~~~~~~~~~~~~~~~ - -This generates the surfaced produced by extruding a circle (this is the same as a cylinder). - -.. image:: _images/kgeobag_extruded_circle_space_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - -Extruded poly-loop surface -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This generates a surface by extruding a poly-loop. - -.. image:: _images/kgeobag_extruded_poly_loop_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - - - - - -Special Surfaces ----------------- - -These surfaces are just specific cases of the more general surface types already listed. However, since their use is -extremely common, they have been made available as unique, special types. For many simple simulations, it is possible -to design the geometry entirely using these elements. - -Disk surface -~~~~~~~~~~~~ - -This produces a disk centered on the local z-axis. - -.. image:: _images/kgeobag_disk_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - -The parameters are: - -- z: z-position in meters -- r: radius in meters -- radial_mesh_count: radial mesh parameter (default is 1) -- radial_mesh_power: radial meshing power (default is 1.) -- axial_mesh_count: axial mesh parameter (default is 16) - -Annulus surface -~~~~~~~~~~~~~~~ - -This produces an annulus centered on the z axis. - -.. image:: _images/kgeobag_annulus_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - -The parameters are: - -- z: z-position in meters -- r1: the first of the radii in meters -- r2: the second radius in meters -- radial_mesh_count: radial mesh parameter (default is 1) -- radial_mesh_power: radial meshing power (default is 1.) -- axial_mesh_count: axial mesh parameter (default is 16) - -Cylinder surface -~~~~~~~~~~~~~~~~ - -Generates a cylinder centered on the z axis. - -.. image:: _images/kgeobag_cylinder_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - -The parameters are: - -- z1: the first z position in meters -- z2: the second z position in meters -- r: radius in meters -- longitudinal_mesh_count: longitudinal mesh parameter (default is 1) -- longitudinal_mesh_power: longitudinal meshing power (default is 1.) -- axial_mesh_count: axial mesh parameter (default is 16) - -Cone Surface -~~~~~~~~~~~~ - -Generates a cone centered on the z axis. - -.. image:: _images/kgeobag_cone_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - -The parameters are: - -- za: apex z position in meters -- zb: base z position in meters -- rb: base radius in meters -- longitudinal_mesh_count: longitudinal mesh parameter (default is 1) -- longitudinal_mesh_power: longitudinal meshing power (default is 1.) -- axial_mesh_count: axial mesh parameter (default is 16) - -Cut Cone Surface -~~~~~~~~~~~~~~~~ - -Produces a truncated cone centered on the local z-axis. - -.. image:: _images/kgeobag_cut_cone_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - -The parameters are: - -- z1: the first z coordinates in meters -- r1: the first r coordinates in meters -- z2: the second z coordinate in meters -- r2: the second r coordinate in meters -- longitudinal_mesh_count: longitudinal mesh parameter (default is 1) -- longitudinal_mesh_power: longitudinal meshing power (default is 1.) -- axial_mesh_count: axial mesh parameter (default is 16) - -Torus Surface -~~~~~~~~~~~~~ - -Generates a torus centered on the local z axis. - -.. image:: _images/kgeobag_torus_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - -The parameters are: - -- z: z coordinate of the center in meters -- r: r coordinate of the center in meters -- radius: the toroidal radius in meters -- toroidal_mesh_count: toroidal mesh parameter (default is 64) -- axial_mesh_count: axial mesh parameter (default is 64) - -Cut Torus Surface -~~~~~~~~~~~~~~~~~ - -Produces an angularly limited toroidal section centered on the z axis. - -.. image:: _images/kgeobag_cut_torus_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - -The parameters are: - -- z1: the first z coordinate in meters -- r1: the first r coordinate in meters -- z2: the second z coordinate in meters -- r2: the second r coordinate in meters -- radius: the toroidal radius in meters -- right: is the arc on the right side of the directed line connecting point 1 to point 2? -- short: does the arc subtend less than pi radians? -- toroidal_mesh_count: toroidal mesh parameter (default is 64) -- axial_mesh_count: axial mesh parameter (default is 64) - - -Spaces -====== - -Spaces are considered distinct from surfaces as they are (water-tight) volumes. The cannot be open or have holes which -puncture their boundaries. In the *Kassiopeia* interface, spaces are treated very differently than surfaces and have -different features on purposes. - -Extruded Spaces ---------------- - -Extruded spaces are from in a manner similar to extruded surfaces, the only difference being that they also provide -planar caps to fully enclose a central volume. - -Extruded Circle Space -~~~~~~~~~~~~~~~~~~~~~ - -Generates a volume by extruding a cycle (cynlinder). - -.. image:: _images/kgeobag_extruded_circle_space_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - -Extruded Poly-Loop Space -~~~~~~~~~~~~~~~~~~~~~~~~ - -Generates a volume by extruding a poly-loop. - -.. image:: _images/kgeobag_extruded_poly_loop_space_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - - - - - -Rotated Spaces --------------- - -Rotated Line Segment -~~~~~~~~~~~~~~~~~~~~ - -Generates a volume enclosed by a surface of revolution produced from rotating a line segement. - -.. image:: _images/kgeobag_rotated_line_segment_space_model.png - :width: 400pt - -- Works with GeometryViewer: Yes. -- Works with MeshViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - -Rotated Arc Segment -~~~~~~~~~~~~~~~~~~~ - -Generates a volume enclosed by a surface of revolution produced from rotating an arc segment. - -.. image:: _images/kgeobag_rotated_arc_segment_space_model.png - :width: 400pt - -- Works with GeometryViewer: Yes. -- Works with MeshViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - -Rotated Poly-Line Space -~~~~~~~~~~~~~~~~~~~~~~~ - -Generates a volume enclosed by a surface of revolution produced from rotating a poly-line. - -.. image:: _images/kgeobag_rotated_poly_line_space_model.png - :width: 400pt - -- Works with GeometryViewer: Yes. -- Works with MeshViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - -Rotated Circle Space -~~~~~~~~~~~~~~~~~~~~ - -Generates a volume by rotating a circle (torus). - -.. image:: _images/kgeobag_rotated_circle_space_model.png - :width: 400pt - -- Works with GeometryViewer: Yes. -- Works with MeshViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - -Rotated Poly-Loop Space -~~~~~~~~~~~~~~~~~~~~~~~ - -Generates a volume enclosed by a surface of revolution produced from rotating a poly-loop - -.. image:: _images/kgeobag_rotated_poly_loop_space_model.png - :width: 400pt - -- Works with GeometryViewer: No. -- Works with MeshViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - - - - - -Special Spaces --------------- - -These spaces are just specific cases of the more general space types already listed. They have been made separately -available because of their common use. As with the special surfaces, these elements may be used to design a simple -simulation geometry. - -Cylinder Space -~~~~~~~~~~~~~~ - -Produces a cylinder space centered on the local z axis. - -.. image:: _images/kgeobag_cylinder_space_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - -The parameters are: - - z1: the first z coordinate in meters - - z2: the second z coordinate in meters - - r: the radius in meters - - longitudinal_mesh_count: longitudinal mesh parameter (default is 1) - - longitudinal_mesh_power: longitudinal meshing power (default is 1.) - - radial_mesh_count: radial mesh parameter (default is 1) - - radial_mesh_power: radial meshing power (default is 1.) - - axial_mesh_count: axial mesh parameter (default is 16) - -Cone Space -~~~~~~~~~~ - -Generates a conical space centered on the local z axis. - -.. image:: _images/kgeobag_cone_space_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - -The parameters are: - -- za: apex z position in meters -- zb: base z position in meters -- rb: base radius in meters -- longitudinal_mesh_count: longitudinal mesh parameter (default is 1) -- longitudinal_mesh_power: longitudinal meshing power (default is 1.) -- radial_mesh_count: radial mesh parameter (default is 1) -- radial_mesh_power: radial meshing power (default is 1.) -- axial_mesh_count: axial mesh parameter (default is 16) - -Cut Cone Space -~~~~~~~~~~~~~~ - -Produces a cut cone volume (frustrum). - -.. image:: _images/kgeobag_cut_cone_space_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - -The parameters are: - -- z1: the first z coordinate in meters -- r1: the first r coordinate in meters -- z2: the second z coordinate in meters -- r2: the second r coordinate in meters -- longitudinal_mesh_count: longitudinal mesh parameter (default is 1) -- longitudinal_mesh_power: longitudinal meshing power (default is 1.) -- radial_mesh_count: radial mesh parameter (default is 1) -- radial_mesh_power: radial meshing power (default is 1.) -- axial_mesh_count: axial mesh parameter (default is 16) - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -Torus Space -~~~~~~~~~~~ - -Produces a torus centered on the local z axis. - -.. image:: _images/kgeobag_torus_space_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - -The parameters are: - -- z: z coordinate of the center in meters -- r: r coordinate of the center in meters -- radius: the toroidal radius in meters -- toroidal_mesh_count: toroidal mesh parameter (default is 64) -- axial_mesh_count: axial mesh parameter (default is 64) - -Cylinder Tube Space -~~~~~~~~~~~~~~~~~~~ - -Creates a tube, (a hollow cylinder with finite wall thickness). - -.. image:: _images/kgeobag_cylinder_tube_space_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - -The parameters are: - -- z1: the first z position in meters -- z2: the second z position in meters -- r1: the first radius in meters -- r2: the second radius in meters -- longitudinal_mesh_count: longitudinal mesh parameter (default is 1) -- longitudinal_mesh_power: longitudinal meshing power (default is 1.) -- radial_mesh_count: radial mesh parameter (default is 1) -- radial_mesh_power: radial meshing power (default is 1.) -- axial_mesh_count: axial mesh parameter (default is 16) - -Cut Cone Tube Space -~~~~~~~~~~~~~~~~~~~ - -Generates a tubular frustrum (a cut cone with central axially symmetric void). - -.. image:: _images/kgeobag_cut_cone_tube_space_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - -The parameters are: - -- z1: the first side's z position in meters -- z2: the second side's z position in meters -- r11: one of the side's first radius in meters -- r12: the other side's first radius in meters -- r21: one of the side's second radius in meters -- r22: the other side' second radius in meters -- longitudinal_mesh_count: longitudinal mesh parameter (default is 1) -- longitudinal_mesh_power: longitudinal meshing power (default is 1.) -- radial_mesh_count: radial mesh parameter (default is 1) -- radial_mesh_power: radial meshing power (default is 1.) -- axial_mesh_count: axial mesh parameter (default is 16) - -Box Space -~~~~~~~~~ - -Produces an axis aligned rectangular prism. - -.. image:: _images/kgeobag_box_space_model.png - :width: 400pt - -- Works with MeshViewer: No. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - -The parameters are: - -- xa: one of the x extrema in meters -- xb: the other x extremum in meters -- x_mesh_count: x mesh count -- x_mesh_power: x mesh power -- ya: one of the y extrema in meters -- yb: the other y extremum in meters -- y_mesh_count: y mesh count -- y_mesh_power: y mesh power -- za: one of the z extrema in meters -- zb: the other z extremum in meters -- z_mesh_count: z mesh count -- z_mesh_power: z mesh power - -.. _Paraview: http://www.paraview.org -.. _VTK: http://www.vtk.org + +.. _basic-kgeobag-label: + +Basic Shapes in KGeoBag +========================== + +This section is a description of the basic spaces and surfaces which can be constructed using *KGeoBag*. All of the +following shapes can be displayed by the executables ``MeshViewer`` and ``GeometryViewer`` (see :ref:`visualization-label`). +These executables are built and installed along with *KGeoBag* when it is linked against VTK_. + + +Geometry visualization +----------------------- + +In order to view a geometry you can execute ``GeometryViewer`` from the directory ``$KASPERSYS/install/bin`` with the +path to your geometry file (.xml) and the name of the geometry element you want to display as the arguments: + +.. code-block:: bash + + ./GeometryViewer ../config/TheBag/Examples/ExampleShapes.xml example_rotated_surface + +An example of the geometry view is shown below: + +.. image:: _images/geometryviewer.png + :width: 400pt + +To visualized the mesh of a geometric element execute MeshViewer in ``$KASPERSYS/install/bin`` with the path to your +geometry file (.xml) and the name of the geometry element you want to display: + +.. code-block:: bash + + ./MeshViewer <../config/TheBag/Examples/ExampleShapes.xml> + +There is also an ``AxialMeshViewer`` available, which displays the axial mesh (if defined) in the same way. The +geometric element can be a specific element or several elements collected into a group. To display a single element use +its name, to show a tagged group the argument is written as ``@tag_group``. An example of the mesh viewer being used on +a rod surface is shown below: + +.. image:: _images/meshviewer.png + :width: 400pt + +The ``GeometryViewer`` and ``MeshViewer`` will also produce a VTK poly-data file (.vtp) which can then be open in the +external application Paraview_ for more advanced visualization. + +The parameters specifying the method by which a geometric element is meshed must be given in the geometry file when the +shape is described. If no mesh is desired for some object, the mesh parameters may be ignored and the defaults will be +used. The commands above may also be tried with one of the *Kassiopeia* simulation examples. + +The mesh parameters vary for each object, but essentially describe two properties (for each meshable dimension). These +are the ``mesh_count`` and the ``mesh_power``. If the ``mesh_power`` is set equal to 1.0, then the ``mesh_count`` simply +specifies the number of equally sized segments that a shape will be chopped into, along a particular dimension. If the +``mesh_power`` is greater than 1.0, then the density of segments will increase towards the edges of the shape while +keeping the number of elements the same. The ``mesh_power`` property is useful for tailoring the accuracy of mesh +descriptions for Laplace boundary value problems, where quantities such as charge density may vary considerably near the +sharp edges of an object. Therefore, this parameter is mainly used for electrode meshes. + +The following sections provide examples and brief descriptions of some basic shapes available for use in *KGeoBag*. + +Basic elements +-------------- + +The following elements (poly-loop and poly-line) are internal descriptors. They can't be used by themselves outside a +geometry element. This section serves as a brief explanation for the structure of these shapes. + +Poly-loop +~~~~~~~~~~ + +A poly-loop is a closed sequence consisting of several lines and/or arcs that form a polygonal shape. The aequence +starts with ```` and ends with ```` or ````, and multiple ```` or ```` elements can be put in between. An example of a poly-loop element is as follows: + +.. code-block:: xml + + + + + + + + +which creates a line from (0,0) to (0.4,-0.1) followed by an arc to (-0.1,0.4), and then the loop is closed by a line +back to the starting point. Note that poly-loop and poly-line are two-dimensional objects that operate in (x,y) +coordinates. Any line that is created by a ```` command goes from the end-point of the previous line to the +specified coordinate. The directive ```` or ```` connects the first and last points with +the specified segment type. + +The arc elements are described with the boolean parameters ``right`` and ``short``, as shown here: + +.. image:: _images/short_true_false.png + +where ``right="true"`` means that the circle segment will be drawn clockwise, and vice versa. ``short="true"`` means +that the arc will be the shorter one of the two possiblities. + +Poly-line +~~~~~~~~~~ + +This element is desribed using the same procedure as in poly-loop. However, the first and last points are not +necessarily connected. An XML example is below: + +.. code-block:: xml + + + + + + + + + +In this case, the sequence progresses through five (x,y) points but does not connect back to the starting point. Hence, +it does not form a closed loop like the poly-loop element does, and does not need a ```` command. Otherwise, +the parameters for poly-line are the same as for poly-loop. + +Surfaces +----------- + +Flat surfaces +~~~~~~~~~~~~~~ + +Flattened circle surface +""""""""""""""""""""""""""" + +A flattened circle surface is just a surface with circular shape, where (x,y,z) are the coordinates for the center of +the circle and r is the radius: + +.. image:: _images/kgeobag_flattened_circle_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + +Flattened poly-loop surface +""""""""""""""""""""""""""""" + +A flattened poly loop surface is a surface consisting of several lines, arcs or both, creating a polygon of your desired +shape. The first line and the last line are connected automatically. By using the features of the poly-loop outlined +above, this provides a very flexible method of designing surface elements. + +.. image:: _images/kgeobag_flattened_poly_loop_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + +Rotated Surfaces +~~~~~~~~~~~~~~~~~~ + +All rotated surfaces are constructed from lines, arcs, poly-lines, or poly-loops which are then rotated around the local +x-axis. + +Rotated line segment surface +""""""""""""""""""""""""""""""" + +This type generates the surface of revolution formed by a line that is rotated around the x-axis. + +.. image:: _images/kgeobag_rotated_line_segment_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + +Rotated arc segment surface +""""""""""""""""""""""""""""" + +This type generates the surface of revolution formed by an arc that is rotated around the x-axis. + +.. image:: _images/kgeobag_rotated_arc_segment_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + +Rotated poly-line surface +""""""""""""""""""""""""""" + +This type generates the surface of revolution created by rotating a poly-line around the local x-axis. + +.. image:: _images/kgeobag_rotated_poly_line_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + +Rotated circle surface +""""""""""""""""""""""" + +This type generates the surface of revolution created by rotating a circle around the local x-axis. This shape is +essentially or torus, or a section of a torus. + +.. image:: _images/kgeobag_rotated_circle_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + +Rotated poly loop surface +""""""""""""""""""""""""""" + +This type generates the surface of revolution created by rotating a poly-loop around the local x-axis. + +.. image:: _images/kgeobag_rotated_poly_loop_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + + + + + +Shell Surfaces +~~~~~~~~~~~~~~~~~ + +All shell surfaces are lines, arcs or surfaces that are rotated around the x-axis between a given start angle +(angle_start) and stop angle (angle_stop). + +Shell line segment surface +""""""""""""""""""""""""""" + +This produces an angularly limited portion of a surface of revolution from a line that is rotated around the local +x-axis. + +.. image:: _images/kgeobag_shell_line_segment_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + +Shell arc segment surface +""""""""""""""""""""""""""" + +This produces an angularly limited portion of a surface of revolution from an arc that is rotated around the local +x-axis. + +.. image:: _images/kgeobag_shell_arc_segment_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + +Shell poly-line surface +""""""""""""""""""""""""" + +This produces an angularly limited portion of a surface of revolution from a poly-line that is rotated around the local +x-axis. + +.. image:: _images/kgeobag_shell_poly_line_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + +Shell circle surface +""""""""""""""""""""" + +This produces an angularly limited portion of a surface of revolution from a circle that is rotated around the local +x-axis. + +.. image:: _images/kgeobag_shell_circle_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + +Shell poly-loop surface +""""""""""""""""""""""""" + +This produces an angularly limited portion of a surface of revolution from a poly-loop that is rotated around the local +x-axis. + +.. image:: _images/kgeobag_shell_poly_loop_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + + + + + +Extruded Surfaces +~~~~~~~~~~~~~~~~~~~ + +Extruded surfaces are surfaces that are extruded along the direction of the local z-axis from a minimum z-position +(zmin) to a maximum z-position (zmax). + +Extruded poly-line surface +""""""""""""""""""""""""""" + +This generates a surface by extruding a poly-line. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + +Extruded circle surface +""""""""""""""""""""""""" + +This generates the surfaced produced by extruding a circle (this is the same as a cylinder). + +.. image:: _images/kgeobag_extruded_circle_space_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + +Extruded poly-loop surface +""""""""""""""""""""""""""" + +This generates a surface by extruding a poly-loop. + +.. image:: _images/kgeobag_extruded_poly_loop_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + + + + + +Special Surfaces +~~~~~~~~~~~~~~~~~ + +These surfaces are just specific cases of the more general surface types already listed. However, since their use is +extremely common, they have been made available as unique, special types. For many simple simulations, it is possible +to design the geometry entirely using these elements. + +Disk surface +""""""""""""" + +This produces a disk centered on the local z-axis. + +.. image:: _images/kgeobag_disk_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + +The parameters are: + +- z: z-position in meters +- r: radius in meters +- radial_mesh_count: radial mesh parameter (default is 1) +- radial_mesh_power: radial meshing power (default is 1.) +- axial_mesh_count: axial mesh parameter (default is 16) + +Annulus surface +""""""""""""""""" +This produces an annulus centered on the z axis. + +.. image:: _images/kgeobag_annulus_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + +The parameters are: + +- z: z-position in meters +- r1: the first of the radii in meters +- r2: the second radius in meters +- radial_mesh_count: radial mesh parameter (default is 1) +- radial_mesh_power: radial meshing power (default is 1.) +- axial_mesh_count: axial mesh parameter (default is 16) + +Cylinder surface +""""""""""""""""" + +Generates a cylinder centered on the z axis. + +.. image:: _images/kgeobag_cylinder_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + +The parameters are: + +- z1: the first z position in meters +- z2: the second z position in meters +- r: radius in meters +- longitudinal_mesh_count: longitudinal mesh parameter (default is 1) +- longitudinal_mesh_power: longitudinal meshing power (default is 1.) +- axial_mesh_count: axial mesh parameter (default is 16) + +Cone Surface +""""""""""""""" + +Generates a cone centered on the z axis. + +.. image:: _images/kgeobag_cone_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + +The parameters are: + +- za: apex z position in meters +- zb: base z position in meters +- rb: base radius in meters +- longitudinal_mesh_count: longitudinal mesh parameter (default is 1) +- longitudinal_mesh_power: longitudinal meshing power (default is 1.) +- axial_mesh_count: axial mesh parameter (default is 16) + +Cut Cone Surface +""""""""""""""""" + +Produces a truncated cone centered on the local z-axis. + +.. image:: _images/kgeobag_cut_cone_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + +The parameters are: + +- z1: the first z coordinates in meters +- r1: the first r coordinates in meters +- z2: the second z coordinate in meters +- r2: the second r coordinate in meters +- longitudinal_mesh_count: longitudinal mesh parameter (default is 1) +- longitudinal_mesh_power: longitudinal meshing power (default is 1.) +- axial_mesh_count: axial mesh parameter (default is 16) + +Torus Surface +""""""""""""""" + +Generates a torus centered on the local z axis. + +.. image:: _images/kgeobag_torus_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + +The parameters are: + +- z: z coordinate of the center in meters +- r: r coordinate of the center in meters +- radius: the toroidal radius in meters +- toroidal_mesh_count: toroidal mesh parameter (default is 64) +- axial_mesh_count: axial mesh parameter (default is 64) + +Cut Torus Surface +""""""""""""""""""" + +Produces an angularly limited toroidal section centered on the z axis. + +.. image:: _images/kgeobag_cut_torus_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + +The parameters are: + +- z1: the first z coordinate in meters +- r1: the first r coordinate in meters +- z2: the second z coordinate in meters +- r2: the second r coordinate in meters +- radius: the toroidal radius in meters +- right: is the arc on the right side of the directed line connecting point 1 to point 2? +- short: does the arc subtend less than pi radians? +- toroidal_mesh_count: toroidal mesh parameter (default is 64) +- axial_mesh_count: axial mesh parameter (default is 64) + + +Spaces +-------- + +Spaces are considered distinct from surfaces as they are (water-tight) volumes. The cannot be open or have holes which +puncture their boundaries. In the *Kassiopeia* interface, spaces are treated very differently than surfaces and have +different features on purposes. + +Extruded Spaces +~~~~~~~~~~~~~~~~ + +Extruded spaces are from in a manner similar to extruded surfaces, the only difference being that they also provide +planar caps to fully enclose a central volume. + +Extruded Circle Space +""""""""""""""""""""""""" + +Generates a volume by extruding a cycle (cynlinder). + +.. image:: _images/kgeobag_extruded_circle_space_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + +Extruded Poly-Loop Space +""""""""""""""""""""""""""" + +Generates a volume by extruding a poly-loop. + +.. image:: _images/kgeobag_extruded_poly_loop_space_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + + + + + +Rotated Spaces +~~~~~~~~~~~~~~~~ + +Rotated Line Segment +""""""""""""""""""""" + +Generates a volume enclosed by a surface of revolution produced from rotating a line segement. + +.. image:: _images/kgeobag_rotated_line_segment_space_model.png + :width: 400pt + +- Works with GeometryViewer: Yes. +- Works with MeshViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + +Rotated Arc Segment +""""""""""""""""""""" + +Generates a volume enclosed by a surface of revolution produced from rotating an arc segment. + +.. image:: _images/kgeobag_rotated_arc_segment_space_model.png + :width: 400pt + +- Works with GeometryViewer: Yes. +- Works with MeshViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + +Rotated Poly-Line Space +""""""""""""""""""""""""" + +Generates a volume enclosed by a surface of revolution produced from rotating a poly-line. + +.. image:: _images/kgeobag_rotated_poly_line_space_model.png + :width: 400pt + +- Works with GeometryViewer: Yes. +- Works with MeshViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + +Rotated Circle Space +""""""""""""""""""""" + +Generates a volume by rotating a circle (torus). + +.. image:: _images/kgeobag_rotated_circle_space_model.png + :width: 400pt + +- Works with GeometryViewer: Yes. +- Works with MeshViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + +Rotated Poly-Loop Space +""""""""""""""""""""""""" + +Generates a volume enclosed by a surface of revolution produced from rotating a poly-loop + +.. image:: _images/kgeobag_rotated_poly_loop_space_model.png + :width: 400pt + +- Works with GeometryViewer: No. +- Works with MeshViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + + + + + +Special Spaces +~~~~~~~~~~~~~~~~ + +These spaces are just specific cases of the more general space types already listed. They have been made separately +available because of their common use. As with the special surfaces, these elements may be used to design a simple +simulation geometry. + +Cylinder Space +""""""""""""""" + +Produces a cylinder space centered on the local z axis. + +.. image:: _images/kgeobag_cylinder_space_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + +The parameters are: + - z1: the first z coordinate in meters + - z2: the second z coordinate in meters + - r: the radius in meters + - longitudinal_mesh_count: longitudinal mesh parameter (default is 1) + - longitudinal_mesh_power: longitudinal meshing power (default is 1.) + - radial_mesh_count: radial mesh parameter (default is 1) + - radial_mesh_power: radial meshing power (default is 1.) + - axial_mesh_count: axial mesh parameter (default is 16) + +Cone Space +""""""""""""" + +Generates a conical space centered on the local z axis. + +.. image:: _images/kgeobag_cone_space_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + +The parameters are: + +- za: apex z position in meters +- zb: base z position in meters +- rb: base radius in meters +- longitudinal_mesh_count: longitudinal mesh parameter (default is 1) +- longitudinal_mesh_power: longitudinal meshing power (default is 1.) +- radial_mesh_count: radial mesh parameter (default is 1) +- radial_mesh_power: radial meshing power (default is 1.) +- axial_mesh_count: axial mesh parameter (default is 16) + +Cut Cone Space +""""""""""""""" + +Produces a cut cone volume (frustrum). + +.. image:: _images/kgeobag_cut_cone_space_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + +The parameters are: + +- z1: the first z coordinate in meters +- r1: the first r coordinate in meters +- z2: the second z coordinate in meters +- r2: the second r coordinate in meters +- longitudinal_mesh_count: longitudinal mesh parameter (default is 1) +- longitudinal_mesh_power: longitudinal meshing power (default is 1.) +- radial_mesh_count: radial mesh parameter (default is 1) +- radial_mesh_power: radial meshing power (default is 1.) +- axial_mesh_count: axial mesh parameter (default is 16) + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +Torus Space +""""""""""""" + +Produces a torus centered on the local z axis. + +.. image:: _images/kgeobag_torus_space_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + +The parameters are: + +- z: z coordinate of the center in meters +- r: r coordinate of the center in meters +- radius: the toroidal radius in meters +- toroidal_mesh_count: toroidal mesh parameter (default is 64) +- axial_mesh_count: axial mesh parameter (default is 64) + +Cylinder Tube Space +""""""""""""""""""""" + +Creates a tube, (a hollow cylinder with finite wall thickness). + +.. image:: _images/kgeobag_cylinder_tube_space_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + +The parameters are: + +- z1: the first z position in meters +- z2: the second z position in meters +- r1: the first radius in meters +- r2: the second radius in meters +- longitudinal_mesh_count: longitudinal mesh parameter (default is 1) +- longitudinal_mesh_power: longitudinal meshing power (default is 1.) +- radial_mesh_count: radial mesh parameter (default is 1) +- radial_mesh_power: radial meshing power (default is 1.) +- axial_mesh_count: axial mesh parameter (default is 16) + +Cut Cone Tube Space +""""""""""""""""""""" + +Generates a tubular frustrum (a cut cone with central axially symmetric void). + +.. image:: _images/kgeobag_cut_cone_tube_space_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + +The parameters are: + +- z1: the first side's z position in meters +- z2: the second side's z position in meters +- r11: one of the side's first radius in meters +- r12: the other side's first radius in meters +- r21: one of the side's second radius in meters +- r22: the other side' second radius in meters +- longitudinal_mesh_count: longitudinal mesh parameter (default is 1) +- longitudinal_mesh_power: longitudinal meshing power (default is 1.) +- radial_mesh_count: radial mesh parameter (default is 1) +- radial_mesh_power: radial meshing power (default is 1.) +- axial_mesh_count: axial mesh parameter (default is 16) + +Box Space +""""""""""""" + +Produces an axis aligned rectangular prism. + +.. image:: _images/kgeobag_box_space_model.png + :width: 400pt + +- Works with MeshViewer: No. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + +The parameters are: + +- xa: one of the x extrema in meters +- xb: the other x extremum in meters +- x_mesh_count: x mesh count +- x_mesh_power: x mesh power +- ya: one of the y extrema in meters +- yb: the other y extremum in meters +- y_mesh_count: y mesh count +- y_mesh_power: y mesh power +- za: one of the z extrema in meters +- zb: the other z extremum in meters +- z_mesh_count: z mesh count +- z_mesh_power: z mesh power + + +.. _TFormula: http://root.cern.ch/root/htmldoc/TFormula.html +.. _TMath: http://root.cern.ch/root/htmldoc/TMath.html +.. _PDG: http://pdg.lbl.gov/mc_particle_id_contents.html +.. _Paraview: http://www.paraview.org/ +.. _ROOT: https://root.cern.ch/ +.. _VTK: http://www.vtk.org/ +.. _MKS: https://scienceworld.wolfram.com/physics/MKS.html +.. _XML: https://www.w3.org/TR/xml11/ +.. _Xpath: https://www.w3.org/TR/xpath-10/ +.. _TinyExpr: https://github.com/codeplea/tinyexpr/ +.. _Log4CXX: https://logging.apache.org/log4cxx/ + +.. rubric:: Footnotes + +[1] Daniel Lawrence Furse. Techniques for direct neutrino mass measurement utilizing tritium [beta]-decay. PhD thesis, Massachusetts Institute of Technology, 2015. + +[2] Thomas Corona. Methodology and application of high performance electrostatic field simulation in the KATRIN experiment. PhD thesis, University of North Carolina, Chapel Hill, 2014. + +[3] John P. Barrett. A Spatially Resolved Study of the KATRIN Main Spectrometer Using a Novel Fast Multipole Method. PhD thesis, Massachusetts Institute of Technology, 2016. diff --git a/Documentation/gh-pages/source/output.rst b/Documentation/gh-pages/source/output.rst index c2cd2c5a0..09b6e10c1 100644 --- a/Documentation/gh-pages/source/output.rst +++ b/Documentation/gh-pages/source/output.rst @@ -18,7 +18,7 @@ track and step level. In addition, if *Kassiopeia* was compiled with VTK_ suppor format may be written. These files are mainly intended for visualization, e.g. with the ParaView_ software. It is also possible to write simulation data as plaintext ASCII files, however this is not recommened for large simulations. -As explained in :ref:`configuration-label`, the output format is configured by the available writers. Writers use the +As explained in :ref:`Configuring Your Own Simulation `, the output format is configured by the available writers. Writers use the description of the output format in the XML configuration file, which specifies the output fields that will be written to file. Different output descriptions may be used for different writers. diff --git a/Documentation/gh-pages/source/setup_container.rst b/Documentation/gh-pages/source/setup_container.rst index 398772b43..a88794e5d 100644 --- a/Documentation/gh-pages/source/setup_container.rst +++ b/Documentation/gh-pages/source/setup_container.rst @@ -333,7 +333,7 @@ Root access Note that in nearly any case, there should be no need for actual root access to an active container. Use the information from section -|Customizing_docker_containers|_ instead. If you are developing with +:ref:`customizing-docker-containers` instead. If you are developing with Docker, there may be reasons to install software lateron anyways, in which case you can get a root shell by running the container with the additional option ``--name myKassiopeia`` and then executing: diff --git a/Documentation/gh-pages/source/visualization.rst b/Documentation/gh-pages/source/visualization.rst index c059b3233..d3bae1036 100644 --- a/Documentation/gh-pages/source/visualization.rst +++ b/Documentation/gh-pages/source/visualization.rst @@ -53,7 +53,7 @@ In addition, the mesh geometry can be viewed as well: /> -The axial mesh painter needs a defined mesh (```` XML element, see :ref:`configuration-label`). An +The axial mesh painter needs a defined mesh (```` XML element, see :ref:`Configuring Your Own Simulation `). An ```` exists as well, to be used with an asymmetric mesh (defined via ````.) Using Python