diff --git a/Documentation/gh-pages/source/conf.py b/Documentation/gh-pages/source/conf.py index 69570985..156da15c 100644 --- a/Documentation/gh-pages/source/conf.py +++ b/Documentation/gh-pages/source/conf.py @@ -63,7 +63,15 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. -exclude_patterns = [] + +# Exclude link file +exclude_patterns = ['links.rst'] + +# make rst_epilog a variable, so you can add other epilog parts to it +rst_epilog ="" +# Read link all targets from file +with open('links.rst') as f: + rst_epilog += f.read() highlight_language = '' diff --git a/Documentation/gh-pages/source/configuring_simulation.rst b/Documentation/gh-pages/source/configuring_simulation.rst index 699a61e8..7aa1ed35 100644 --- a/Documentation/gh-pages/source/configuring_simulation.rst +++ b/Documentation/gh-pages/source/configuring_simulation.rst @@ -1,19 +1,8 @@ Configuring Your Own Simulation -******************************* - - - -.. contents:: On this page - :local: - :depth: 2 - - +================================ .. _configuration-label: -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 (see :ref:`KGeoBag `) which describes the system geometry and its extensions, the ```` section (see :ref:`KEMField `) which defines the electromagnetic field elements, and the ```` @@ -46,7 +35,7 @@ simulation file can thus be broken down into something which looks like the foll - The XML based interface of *Kassiopeia* allows for a very flexible way in which to modify and configure particle @@ -55,571 +44,24 @@ using MKS_ and their derived units. The exception to this rule is energy, which It should be noted that XML elements are parsed in order, and elements which are referenced by other elements must be declared before their first use. -XML Parsing and Features -======================== - -The document language used for describing a Kassiopeia simulation configuration is based on standard XML_, but has been -augmented with several additional features to aid in complicated or repetitive tasks. For a full description of this -language and its features, see [1]. - -The general XML syntax is: - -.. code-block:: xml - - - - - -where ```` defines an `element` that corresponds to an object of *Kassiopeia* or one of the other modules. Each -element can have an unlimited number of `attrbutes`, each with its own `value`. Attributes are passed on to the -corresponding object during initialization. XML allows nesting of elements, and therefore some elements can have child -elements with the same syntax. - -All elements must end with a closing statement, like `` ... ``. For elements without children, the -syntax can be shortened to the single statement ````. - -General Statements ------------------- - -Variables -~~~~~~~~~ - -A local variable may be defined with a particular value (integer,floating point type, string, etc.) with the following -syntax: - -.. code-block:: xml - - - -and may be reference by any other subsequent (using a local variable before it is defined is not allowed) element in the -document through the use of the square brackets ``[...]`` in the following manner: - -.. code-block:: xml - - - -Note that all variables are defined as strings, but can be interpreted as other types (such as numbers, lists, etc.) -by during initialization of the element. The details depend on the element's implementation. - -Normal variables are defined only for the scope of the current file. Global variables, on the other hand, persist across -any subsequently included files. These may be specified through: - -.. code-block:: xml - - - -Both local and global variables my be undefined (removed from the parser's scope) in the following manner: - -.. code-block:: xml - - - - -It is also possible to reassign a variable (changing their value) with the syntax: - -.. code-block:: xml - - - - -Occasionally the user may wish to specify a variable which can be modified from the command line as an argument passed -to *Kassiopeia*. These variables are called `external variables` and they behave in the same way as global variables, -except that their first definition sets their value and other definitions are ignored. Hence, if an external variable -is defined in multiple included files, only the first occurence matters. If the variable is defined on the command line, -its definition precedes any of the included files. - -To define an external variable called ``my_random_seed`` the syntax is: - -.. code-block:: xml - - - -This particular example is useful for running large batches of similar simulations. For example, to simulate many -independent tracks the user might want to run the same simulation repeatedly, but use a different random seed when -starting the simulation. The value of ``my_random_seed`` can be changed from its default value of 123 from the command -line call to *Kassiopeia* in the following manner: - -.. code-block:: bash - - Kassiopeia ./my_simulation.xml -r my_random_seed=456 - -or with the alternate syntax: - -.. code-block:: bash - - Kassiopeia ./my_simulation.xml --my_random_seed=456 - -Note that this applies to other applications that belong to *Kassiopeia* or the other modules as well. - -Including external files -~~~~~~~~~~~~~~~~~~~~~~~~ - -Including external XML files is also supported through a relatively simple syntax. This is helpful when a simulation is -too complex to be managed by a single file. A separate XML file can be included using the following: - -.. code-block:: xml - - - -This include expression may also be configured dynamically through the use of a variable, for example: - -.. code-block:: xml - - - - -could be modified to include an entirely different file by passing another file name argument to *Kassiopeia* using:: - - Kassiopeia ./my_simulation.xml -r my_file_name=my_other_file.xml - -This feature is particularly useful and enables the user to swap in an entirely different configuration for some portion -of the simulation by passing a single command line variable. - -Lastly, it is possible to mark an included file as optional so that no error will be thrown if the files does not exist. -This is sometimes useful when a file with variable definitions should be included before the main configuration. The -syntax in this case is: - -.. code-block:: xml - - - -Print statements -~~~~~~~~~~~~~~~~ - -The XML initializer allows to print the current value of a variable, or any sort of text message. The message will be -shown during XML initialization, and it is useful for debugging and checking correct initialization. The syntax is: - -.. code-block:: xml - - - - -where the message content is set to the current value of the variable through the ``[...]`` syntax. - -To show a general informative message without a variable name, use the syntax: - -.. code-block:: xml - - - -Both examples together will yield the output:: - - [INITIALIZATION NORMAL MESSAGE] value of is <42> - [INITIALIZATION NORMAL MESSAGE] This is a test message. - -Instead of showing normal messages, it is also possible to show a warning or an error message. An error message will -terminate the prgogram, so it is most useful in combination with the conditional expressions described below: - -.. code-block:: xml - - - - -Finally, an assertion statement can be used that checks if a condition is true, and shows an error otherwise. See below -for an explanation of conditional expressions. The syntax for the assert statement is: - -.. code-block:: xml - - - - -Conditional Expressions and Looping -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In addition to mathematical expressions, simple boolean conditions can be specified. These are often helpful for -swapping or toggling on/off different features, but also for setting several variables depending on the value of a "meta -variable". An example showing the inclusion/exclusion of a brief section of XML is shown below: - -.. code-block:: xml - - - - - - - -Note that this uses the formula syntax ``{...}`` in the condition. The operator ``eq`` checks for equality between the -two variables. Other allowed operators are listed in the table below. To combine multiple conditions into one -expression, use brackets like ``([var1] eq [var2]) && ([var3] eq [var4])``. - -+------------------------------------------------------------------------------------------------+ -| Conditional operators | -+-------------+-------------+-------------------+------------------------------------------------+ -| XML syntax | C++ operator| Operator | Description | -+=============+=============+===================+================================================+ -| ``! A`` | ``!`` | Logical "not" | False if statement A is true. | -+-------------+-------------+-------------------+------------------------------------------------+ -| ``A && B`` | ``&&`` | Logical "and" | True if both statements A and B are true. | -+-------------+-------------+-------------------+------------------------------------------------+ -| ``A || B`` | ``||`` | Logical "or" | True if one of the statements A and B is true. | -+-------------+-------------+-------------------+------------------------------------------------+ -| ``A eq B`` | ``==`` | Equal-to | True if both values A and B are equal. | -+-------------+-------------+-------------------+------------------------------------------------+ -| ``A ne B`` | ``!=`` | Not-equal | True if both values A and B are not equal. | -+-------------+-------------+-------------------+------------------------------------------------+ -| ``A gt B`` | ``<`` | Greater-than | True if value A is greater than value B. | -+-------------+-------------+-------------------+------------------------------------------------+ -| ``A lt B`` | ``>`` | Less-than | True if value A is less than value B. | -+-------------+-------------+-------------------+------------------------------------------------+ -| ``A ge B`` | ``>=`` | Greater-or-equal | True if value A is greater or equal to value B.| -+-------------+-------------+-------------------+------------------------------------------------+ -| ``A le B`` | ``<=`` | Less-or-equal | True if value A is less or equal to value B. | -+-------------+-------------+-------------------+------------------------------------------------+ -| ``A mod B`` | ``%`` | Modulo | Return remainder of value A divided by value B.| -+-------------+-------------+-------------------+------------------------------------------------+ - -It is also possible to check directly if a variable has been set to a "true" value (i.e. not 0, false, or an empty -string.) The syntax in this case is: - -.. code-block:: xml - - - - - - -The conditional expression does not support if-else blocks, so in order to define an alternate conditional branch one -has to add another if-statement in the XML file. - -Another feature which is indispensable when assembling complicated or repetitive geometries is the the ability to insert -multiple copies of an XML fragment with slight modifications. This is called looping and is somewhat similar to the way -a for-loop works in C++ or Python. However, it is a purely static construct intended that is only evaluated during XML -initialization to reduce the amount of code needed to describe a geometry (or other XML feature.) - -An example of its use can be found in the ``DipoleTrapMeshedSpaceSimulation.xml`` example. The example of the loop -syntax for the placement of several copies of a surface with the name ``intermediate_z_surface`` is given below: - -.. code-block:: xml - - - - - - - -In this case, the loop variable ``[i]`` is used to define the name of the copy and its displacement. - -Loops and conditional expressions may also be nested when needed. - -Comments -~~~~~~~~ - -It is wise to include comments in the XML files to explain certain structures or their behavior. Comment blocks are -included by the syntax: - -.. code-block:: xml - - - -As shown above, a comment can span multiple lines. Any text between ```` is ignored by the XML initializer, -including any XML elements. This makes it possible to quickly comment out parts of the file, e.g. for debugging. - - -Formula Expressions -------------------- - -The ability to calculate in-line formulas is another useful feature. The underlying implementation of the formula -processor relies on two external libraries. First, formulas are interpreted with the TinyExpr_ parser. This is a very -fast implementation that works for most simple expressions. If parsing fails, the formula is interpreted by the ROOT -TFormula_ class, which is slower but more versatile. To the user, the switching between both parsers is completely -transparent and no extra steps have to be taken. - -In order to active the formula mode, the relevant expression must be enclosed in curly braces ``{...}``. Variables may -also be used within a formula, and all variable replacements will be done before the formula parsing (meaning that -the current value of the variable will be used in the formula.) An example of the formula syntax is given in the -following variable definition: - -.. code-block:: xml - - - - - -This example results in the variable ``length`` taking the value of 3.3. - -Note that this example uses a standard function ``sqrt(x)`` that is supported by TinyExpr_. In general, any formulas -using advanced TMath_ functions or other complex syntax will use the TFormula_ parser. Simple TMath_ functions like -``TMath::Sqrt(x)`` or ``TMath::Sin(x)`` are mapped to their equivalent standard function (``sqrt(x)``, ``sin(x)``) that is -natively understood by TinyExpr_. The standard functions (and mathematical constants) are listed in the table below. - -+---------------------------------------------------------------------------------------------------------+ -| Standard functions and constants | -+-------------+---------------+--------------------------+------------------------------------------------+ -| XML syntax | C++ function | ROOT equivalent | Description | -+=============+===============+==========================+================================================+ -| ``abs(x)`` | ``fabs(x)`` | ``TMath::Abs()`` | Compute absolute value. | -+-------------+---------------+--------------------------+------------------------------------------------+ -| ``acos(x)`` | ``acos(x)`` | ``TMath::ACos(x)`` | Compute arc cosine. | -+-------------+---------------+--------------------------+------------------------------------------------+ -| ``asin(x)`` | ``asin(x)`` | ``TMath::ASin(x)`` | Compute arc sine. | -+-------------+---------------+--------------------------+------------------------------------------------+ -| ``atan(x)`` | ``atan(x)`` | ``TMath::ATan(x)`` | Compute arc tangent. | -+-------------+---------------+--------------------------+------------------------------------------------+ -| ``atan2(x)``| ``atan2(x)`` | ``TMath::ATan2(x)`` | Compute arc tangent with two parameters. | -+-------------+---------------+--------------------------+------------------------------------------------+ -| ``ceil(x)`` | ``ceil(x)`` | ``TMath::Ceil(x)`` | Round up value. | -+-------------+---------------+--------------------------+------------------------------------------------+ -| ``cos(x)`` | ``cos(x)`` | ``TMath::Cos(x)`` | Compute cosine. | -+-------------+---------------+--------------------------+------------------------------------------------+ -| ``cosh(x)`` | ``cosh(x)`` | ``TMath::CosH(x)`` | Compute hyperbolic cosine. | -+-------------+---------------+--------------------------+------------------------------------------------+ -| ``exp(x)`` | ``exp(x)`` | ``TMath::Exp(x)`` | Compute exponential function. | -+-------------+---------------+--------------------------+------------------------------------------------+ -| ``fac(x)`` | | ``TMath::Factorial(x)`` | Compute factorial. | -+-------------+---------------+--------------------------+------------------------------------------------+ -| ``floor(x)``| ``floor(x)`` | ``TMath::Floor(x)`` | Round down value. | -+-------------+---------------+--------------------------+------------------------------------------------+ -| ``ln(x)`` | ``log(x)`` | ``TMath::Log(x)`` | Compute natural logarithm. | -+-------------+---------------+--------------------------+------------------------------------------------+ -| ``log(x)`` | ``log10(x)`` | | Compute common logarithm. | -+-------------+---------------+--------------------------+------------------------------------------------+ -| ``log10(x)``| ``log10(x)`` | ``TMath::Log10(x)`` | Compute common logarithm. | -+-------------+---------------+--------------------------+------------------------------------------------+ -| ``ncr(n,r)``| | ``TMath::Binomial(n,r)`` | Compute combinations of `n` over `r`. | -+-------------+---------------+--------------------------+------------------------------------------------+ -| ``npr(n,r)``| | | Compute permuations of `n` over `r`. | -+-------------+---------------+--------------------------+------------------------------------------------+ -| ``pow(x)`` | ``pow(x)`` | ``TMath::Pow(x)`` | Raise to power. | -+-------------+---------------+--------------------------+------------------------------------------------+ -| ``sin(x)`` | ``sin(x)`` | ``TMath::Sin(x)`` | Compute sine. | -+-------------+---------------+--------------------------+------------------------------------------------+ -| ``sinh(x)`` | ``sinh(x)`` | ``TMath::SinH(x)`` | Compute hyperbolic sine. | -+-------------+---------------+--------------------------+------------------------------------------------+ -| ``sqrt(x)`` | ``sqrt(x)`` | ``TMath::Sqrt(x)`` | Compute square root. | -+-------------+---------------+--------------------------+------------------------------------------------+ -| ``tan(x)`` | ``tan(x)`` | ``TMath::Tan(x)`` | Compute tangent. | -+-------------+---------------+--------------------------+------------------------------------------------+ -| ``tanh(x)`` | ``tanh(x)`` | ``TMath::TanH(x)`` | Compute hyperbolic tangent. | -+-------------+---------------+--------------------------+------------------------------------------------+ -| ``e`` | | ``TMath::Pi()`` | Fundamental constant. | -+-------------+---------------+--------------------------+------------------------------------------------+ -| ``pi`` | ``M_PI`` | ``TMath::E()`` | Fundamental constant. | -+-------------+---------------+--------------------------+------------------------------------------------+ - - -Messaging System ----------------- - -*Kassiopeia* provides a very granular means of reporting and logging simulation details of interest. This feature is -particularly useful when modifying the code and debugging specific features. For example, at the top of the file -``QuadrupoleTrapSimulation.xml`` you can find section describing the verbosity of each simulation element and the -location of the logging file (as defined by the variable ``log_path`` and the ```` element): - -.. code-block:: xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -For the verbosity settings, you can independently set the verbosity that you see in the terminal and the verbosity that -is put into log files. Furthermore, you can do that for each different part of *Kassiopeia* and the other modules. For -example, if you want a lot of detail on what's happening in the navigation routines, you can increase the verbosity for -only that part of *Kassiopeia*, without being flooded with messages from everything else. The different sources are -define by the ``key`` attribute of the ```` element, and explained in the table below. - -+--------------------------------------------------------------------------------------------------------------------------+ -| Message sources | -+-----------------------+-------------+-----------------------------------+------------------------------------------------+ -| Key | Module | Location | Description | -+=======================+=============+===================================+================================================+ -| ``k_file`` | Kommon | File | File handling | -+-----------------------+-------------+-----------------------------------+------------------------------------------------+ -| ``k_initialization`` | Kommon | Initialization | XML initialization and processing | -+-----------------------+-------------+-----------------------------------+------------------------------------------------+ -| ``k_utility`` | Kommon | Utility | Utility functions | -+-----------------------+-------------+-----------------------------------+------------------------------------------------+ -| ``kem_bindings`` | KEMField | Bindings | XML bindings | -+-----------------------+-------------+-----------------------------------+------------------------------------------------+ -| ``kem_core`` | KEMField | Core | Core functionality | -+-----------------------+-------------+-----------------------------------+------------------------------------------------+ -| ``kg_bindings`` | KGeoBag | Bindings | XML bindings | -+-----------------------+-------------+-----------------------------------+------------------------------------------------+ -| ``kg_core`` | KGeoBag | Core | Core functionality | -+-----------------------+-------------+-----------------------------------+------------------------------------------------+ -| ``kg_axial_mesh`` | KGeoBag | Extensions/AxialMesh | Axially symmetric meshing | -+-----------------------+-------------+-----------------------------------+------------------------------------------------+ -| ``kg_drmesh`` | KGeoBag | Extensions/DiscreteRotationalMesh | Rotationally discrete meshing | -+-----------------------+-------------+-----------------------------------+------------------------------------------------+ -| ``kg_mesh`` | KGeoBag | Extensions/Mesh | Asymmetric meshing | -+-----------------------+-------------+-----------------------------------+------------------------------------------------+ -| ``kg_metrics`` | KGeoBag | Extensions/Metrics | Metrics calculation (volumes & areas) | -+-----------------------+-------------+-----------------------------------+------------------------------------------------+ -| ``kg_random`` | KGeoBag | Extensions/Random | Random generator functions | -+-----------------------+-------------+-----------------------------------+------------------------------------------------+ -| ``kg_math`` | KGeoBag | Math | Mathematical functions | -+-----------------------+-------------+-----------------------------------+------------------------------------------------+ -| ``kg_shape`` | KGeoBag | Shapes | Geometric shapes | -+-----------------------+-------------+-----------------------------------+------------------------------------------------+ -| ``kg_vis`` | KGeoBag | Visualization | Visualization (VTK_, ROOT_) | -+-----------------------+-------------+-----------------------------------+------------------------------------------------+ -| ``ks_bindings`` | Kassiopeia | Bindings | XML bindings | -+-----------------------+-------------+-----------------------------------+------------------------------------------------+ -| ``ks_field`` | Kassiopeia | Fields | Field calculation | -+-----------------------+-------------+-----------------------------------+------------------------------------------------+ -| ``ks_generator`` | Kassiopeia | Generators | Particle generation | -+-----------------------+-------------+-----------------------------------+------------------------------------------------+ -| ``ks_geometry`` | Kassiopeia | Geometry | Geometry handling | -+-----------------------+-------------+-----------------------------------+------------------------------------------------+ -| ``ks_interaction`` | Kassiopeia | Interactions | Particle interactions | -+-----------------------+-------------+-----------------------------------+------------------------------------------------+ -| ``ks_math`` | Kassiopeia | Math | Mathematical functions | -+-----------------------+-------------+-----------------------------------+------------------------------------------------+ -| ``ks_modifier`` | Kassiopeia | Modifiers | Trajectory modifiers | -+-----------------------+-------------+-----------------------------------+------------------------------------------------+ -| ``ks_navigator`` | Kassiopeia | Navigators | Particle navigation | -+-----------------------+-------------+-----------------------------------+------------------------------------------------+ -| ``ks_object`` | Kassiopeia | Objects | Dynamic command interface | -+-----------------------+-------------+-----------------------------------+------------------------------------------------+ -| ``ks_operator`` | Kassiopeia | Operators | Core functionality, particle state | -+-----------------------+-------------+-----------------------------------+------------------------------------------------+ -| ``ks_reader`` | Kassiopeia | Readers | File reading | -+-----------------------+-------------+-----------------------------------+------------------------------------------------+ -| ``ks_main`` | Kassiopeia | Simulation | Simulation execution | -+-----------------------+-------------+-----------------------------------+------------------------------------------------+ -| ``ks_run`` | Kassiopeia | Simulation | Simulation progress, "run" level | -+-----------------------+-------------+-----------------------------------+------------------------------------------------+ -| ``ks_event`` | Kassiopeia | Simulation | Simulation progress, "event" level | -+-----------------------+-------------+-----------------------------------+------------------------------------------------+ -| ``ks_track`` | Kassiopeia | Simulation | Simulation progress, "track" level | -+-----------------------+-------------+-----------------------------------+------------------------------------------------+ -| ``ks_step`` | Kassiopeia | Simulation | Simulation progress, "step" level | -+-----------------------+-------------+-----------------------------------+------------------------------------------------+ -| ``ks_terminator`` | Kassiopeia | Terminators | Particle termination | -+-----------------------+-------------+-----------------------------------+------------------------------------------------+ -| ``ks_trajectory`` | Kassiopeia | Trajectories | Trajectory calculation | -+-----------------------+-------------+-----------------------------------+------------------------------------------------+ -| ``ks_utility`` | Kassiopeia | Utility | Utility functions | -+-----------------------+-------------+-----------------------------------+------------------------------------------------+ -| ``ks_vis`` | Kassiopeia | Visualization | Visualization (VTK_, ROOT_) | -+-----------------------+-------------+-----------------------------------+------------------------------------------------+ -| ``ks_writer`` | Kassiopeia | Writers | File writing | -+-----------------------+-------------+-----------------------------------+------------------------------------------------+ - -The different parts of the code are explained further below, along with XML configuration examples. - -Verbosity levels -~~~~~~~~~~~~~~~~ - -There are five possible verbosity levels, they are ``debug``, ``info``, ``normal``, ``warning`` and ``error``. Of these, -``error`` is the least verbose, only reporting on fatal errors that terminate the simulation. The ``normal`` mode will -include a relatively small set of details in addition to any warnings (this is the default), while ``debug`` will -provide an extremely extensive description of the state of the simulation as it progresses. - -Note that the ``debug`` setting is a special case: Since there is so much additional information provided by this -setting, it substantially slows down the speed of the simulation even when the messages are not printed or saved to the -log file. In order to avoid unnecessarily slowing down *Kassiopeia*, the debug output is completely disabled unless it -is explicitly enabled in the build by enabling the CMake option ``Kassiopeia_ENABLE_DEBUG`` during configuration (and -the corresponding options for other modules.) - -As mentioned earlier, the verbosity level can also be changed by the command line arguments ``-v`` and ``-q``, which -raise or lower the verbosity level. However, this only works for sources that have not been configured explicitely -in the ```` section. - -Additional logging -~~~~~~~~~~~~~~~~~~ - -The description above applies to the *KMessage* interface, which is configured through XML files. In addition, some code -uses the independent *KLogger* interface. If *Kassiopeia* was compiled with Log4CXX_ enabled at build time, the KLogger -interface can be configured through its own configuration file, which is located at: - - ``$KASPERSYS/config/Kommon/log4cxx.properties`` - -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. - .. note:: - In *Kassiopeia*, *KEMField* and *KGeoBag*, most messages use the *KMessage* interface. - - -Common Pitfalls and Problems ----------------------------- - -The XML parser does have some ability to recognize simple errors in a configuration file and will generally report the -location of an element which it is not able to process. - -Some errors which might occur if a file is improperly configured are: - -- Multiple objects which share the same name at the same scope. -- Misspelled element types. -- Missing closing brackets. -- Undefined variables. -- Undeclared (but used) elements. - -In the case of more than one copy of the same object with the name ````, the XML parser will fail with with an error -along the lines of:: - - [INITIALIZATION ERROR MESSAGE] Multiple instances of object with name . - -In the case where an element's type name is misspelled the parser will fail with an unreconized element error, or -display a warning that the element is ignored. For example if we misspelled ``ksterm_max_z`` as ``kterm_max_z`` we would -recieve the following warning:: - - [INITIALIZATION WARNING MESSAGE] nothing registered for element in element - -If there is a mis-matched bracket the intialization will usually fail with an unrecongnized character error, such as:: - - [INITIALIZATION ERROR MESSAGE] element encountered an error > - -If a variable "[X]" is used without being previously defined, and undefined error will be reported as follows:: - - [INITIALIZATION ERROR MESSAGE] variable is not defined - -If there is an attempt to retrieve/reference and element which has not been declared the the simulation will fail with -the message:: - - [INITIALIZATION WARNING MESSAGE] No suitable Object called in Toolbox - -Depening on where the element is referenced, the error may look different. For example:: + To test your configuration, you can use the given visualization techniques for each *Kassiopeia* section, which are described in detail in the following chapters. - [KSOBJECT ERROR MESSAGE] component could not build command named (invalid child component) -.. _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/ +.. toctree:: + :maxdepth: 1 + :hidden: -.. rubric:: Footnotes + Chapter overview -[1] Daniel Lawrence Furse. Techniques for direct neutrino mass measurement utilizing tritium [beta]-decay. PhD thesis, Massachusetts Institute of Technology, 2015. +.. toctree:: + :maxdepth: 1 + :caption: Chapter contents -[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. + configuring_simulation_statements + configuring_simulation_expressions + configuring_simulation_messagingsystem + configuring_simulation_pitfalls -[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/configuring_simulation_expressions.rst b/Documentation/gh-pages/source/configuring_simulation_expressions.rst new file mode 100644 index 00000000..2712ec82 --- /dev/null +++ b/Documentation/gh-pages/source/configuring_simulation_expressions.rst @@ -0,0 +1,81 @@ + +Formula Expressions +==================== + +The ability to calculate in-line formulas is another useful feature. The underlying implementation of the formula +processor relies on two external libraries. First, formulas are interpreted with the TinyExpr_ parser. This is a very +fast implementation that works for most simple expressions. If parsing fails, the formula is interpreted by the ROOT +TFormula_ class, which is slower but more versatile. To the user, the switching between both parsers is completely +transparent and no extra steps have to be taken. + +In order to active the formula mode, the relevant expression must be enclosed in curly braces ``{...}``. Variables may +also be used within a formula, and all variable replacements will be done before the formula parsing (meaning that +the current value of the variable will be used in the formula.) An example of the formula syntax is given in the +following variable definition: + +.. code-block:: xml + + + + + +This example results in the variable ``length`` taking the value of 3.3. + +Note that this example uses a standard function ``sqrt(x)`` that is supported by TinyExpr_. In general, any formulas +using advanced TMath_ functions or other complex syntax will use the TFormula_ parser. Simple TMath_ functions like +``TMath::Sqrt(x)`` or ``TMath::Sin(x)`` are mapped to their equivalent standard function (``sqrt(x)``, ``sin(x)``) that is +natively understood by TinyExpr_. The standard functions (and mathematical constants) are listed in the table below. + ++---------------------------------------------------------------------------------------------------------+ +| Standard functions and constants | ++-------------+---------------+--------------------------+------------------------------------------------+ +| XML syntax | C++ function | ROOT equivalent | Description | ++=============+===============+==========================+================================================+ +| ``abs(x)`` | ``fabs(x)`` | ``TMath::Abs()`` | Compute absolute value. | ++-------------+---------------+--------------------------+------------------------------------------------+ +| ``acos(x)`` | ``acos(x)`` | ``TMath::ACos(x)`` | Compute arc cosine. | ++-------------+---------------+--------------------------+------------------------------------------------+ +| ``asin(x)`` | ``asin(x)`` | ``TMath::ASin(x)`` | Compute arc sine. | ++-------------+---------------+--------------------------+------------------------------------------------+ +| ``atan(x)`` | ``atan(x)`` | ``TMath::ATan(x)`` | Compute arc tangent. | ++-------------+---------------+--------------------------+------------------------------------------------+ +| ``atan2(x)``| ``atan2(x)`` | ``TMath::ATan2(x)`` | Compute arc tangent with two parameters. | ++-------------+---------------+--------------------------+------------------------------------------------+ +| ``ceil(x)`` | ``ceil(x)`` | ``TMath::Ceil(x)`` | Round up value. | ++-------------+---------------+--------------------------+------------------------------------------------+ +| ``cos(x)`` | ``cos(x)`` | ``TMath::Cos(x)`` | Compute cosine. | ++-------------+---------------+--------------------------+------------------------------------------------+ +| ``cosh(x)`` | ``cosh(x)`` | ``TMath::CosH(x)`` | Compute hyperbolic cosine. | ++-------------+---------------+--------------------------+------------------------------------------------+ +| ``exp(x)`` | ``exp(x)`` | ``TMath::Exp(x)`` | Compute exponential function. | ++-------------+---------------+--------------------------+------------------------------------------------+ +| ``fac(x)`` | | ``TMath::Factorial(x)`` | Compute factorial. | ++-------------+---------------+--------------------------+------------------------------------------------+ +| ``floor(x)``| ``floor(x)`` | ``TMath::Floor(x)`` | Round down value. | ++-------------+---------------+--------------------------+------------------------------------------------+ +| ``ln(x)`` | ``log(x)`` | ``TMath::Log(x)`` | Compute natural logarithm. | ++-------------+---------------+--------------------------+------------------------------------------------+ +| ``log(x)`` | ``log10(x)`` | | Compute common logarithm. | ++-------------+---------------+--------------------------+------------------------------------------------+ +| ``log10(x)``| ``log10(x)`` | ``TMath::Log10(x)`` | Compute common logarithm. | ++-------------+---------------+--------------------------+------------------------------------------------+ +| ``ncr(n,r)``| | ``TMath::Binomial(n,r)`` | Compute combinations of `n` over `r`. | ++-------------+---------------+--------------------------+------------------------------------------------+ +| ``npr(n,r)``| | | Compute permuations of `n` over `r`. | ++-------------+---------------+--------------------------+------------------------------------------------+ +| ``pow(x)`` | ``pow(x)`` | ``TMath::Pow(x)`` | Raise to power. | ++-------------+---------------+--------------------------+------------------------------------------------+ +| ``sin(x)`` | ``sin(x)`` | ``TMath::Sin(x)`` | Compute sine. | ++-------------+---------------+--------------------------+------------------------------------------------+ +| ``sinh(x)`` | ``sinh(x)`` | ``TMath::SinH(x)`` | Compute hyperbolic sine. | ++-------------+---------------+--------------------------+------------------------------------------------+ +| ``sqrt(x)`` | ``sqrt(x)`` | ``TMath::Sqrt(x)`` | Compute square root. | ++-------------+---------------+--------------------------+------------------------------------------------+ +| ``tan(x)`` | ``tan(x)`` | ``TMath::Tan(x)`` | Compute tangent. | ++-------------+---------------+--------------------------+------------------------------------------------+ +| ``tanh(x)`` | ``tanh(x)`` | ``TMath::TanH(x)`` | Compute hyperbolic tangent. | ++-------------+---------------+--------------------------+------------------------------------------------+ +| ``e`` | | ``TMath::Pi()`` | Fundamental constant. | ++-------------+---------------+--------------------------+------------------------------------------------+ +| ``pi`` | ``M_PI`` | ``TMath::E()`` | Fundamental constant. | ++-------------+---------------+--------------------------+------------------------------------------------+ diff --git a/Documentation/gh-pages/source/configuring_simulation_messagingsystem.rst b/Documentation/gh-pages/source/configuring_simulation_messagingsystem.rst new file mode 100644 index 00000000..abef55d4 --- /dev/null +++ b/Documentation/gh-pages/source/configuring_simulation_messagingsystem.rst @@ -0,0 +1,164 @@ + +Messaging System +================= + +*Kassiopeia* provides a very granular means of reporting and logging simulation details of interest. This feature is +particularly useful when modifying the code and debugging specific features. For example, at the top of the file +``QuadrupoleTrapSimulation.xml`` you can find section describing the verbosity of each simulation element and the +location of the logging file (as defined by the variable ``log_path`` and the ```` element): + +.. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +For the verbosity settings, you can independently set the verbosity that you see in the terminal and the verbosity that +is put into log files. Furthermore, you can do that for each different part of *Kassiopeia* and the other modules. For +example, if you want a lot of detail on what's happening in the navigation routines, you can increase the verbosity for +only that part of *Kassiopeia*, without being flooded with messages from everything else. The different sources are +define by the ``key`` attribute of the ```` element, and explained in the table below. + ++--------------------------------------------------------------------------------------------------------------------------+ +| Message sources | ++-----------------------+-------------+-----------------------------------+------------------------------------------------+ +| Key | Module | Location | Description | ++=======================+=============+===================================+================================================+ +| ``k_file`` | Kommon | File | File handling | ++-----------------------+-------------+-----------------------------------+------------------------------------------------+ +| ``k_initialization`` | Kommon | Initialization | XML initialization and processing | ++-----------------------+-------------+-----------------------------------+------------------------------------------------+ +| ``k_utility`` | Kommon | Utility | Utility functions | ++-----------------------+-------------+-----------------------------------+------------------------------------------------+ +| ``kem_bindings`` | KEMField | Bindings | XML bindings | ++-----------------------+-------------+-----------------------------------+------------------------------------------------+ +| ``kem_core`` | KEMField | Core | Core functionality | ++-----------------------+-------------+-----------------------------------+------------------------------------------------+ +| ``kg_bindings`` | KGeoBag | Bindings | XML bindings | ++-----------------------+-------------+-----------------------------------+------------------------------------------------+ +| ``kg_core`` | KGeoBag | Core | Core functionality | ++-----------------------+-------------+-----------------------------------+------------------------------------------------+ +| ``kg_axial_mesh`` | KGeoBag | Extensions/AxialMesh | Axially symmetric meshing | ++-----------------------+-------------+-----------------------------------+------------------------------------------------+ +| ``kg_drmesh`` | KGeoBag | Extensions/DiscreteRotationalMesh | Rotationally discrete meshing | ++-----------------------+-------------+-----------------------------------+------------------------------------------------+ +| ``kg_mesh`` | KGeoBag | Extensions/Mesh | Asymmetric meshing | ++-----------------------+-------------+-----------------------------------+------------------------------------------------+ +| ``kg_metrics`` | KGeoBag | Extensions/Metrics | Metrics calculation (volumes & areas) | ++-----------------------+-------------+-----------------------------------+------------------------------------------------+ +| ``kg_random`` | KGeoBag | Extensions/Random | Random generator functions | ++-----------------------+-------------+-----------------------------------+------------------------------------------------+ +| ``kg_math`` | KGeoBag | Math | Mathematical functions | ++-----------------------+-------------+-----------------------------------+------------------------------------------------+ +| ``kg_shape`` | KGeoBag | Shapes | Geometric shapes | ++-----------------------+-------------+-----------------------------------+------------------------------------------------+ +| ``kg_vis`` | KGeoBag | Visualization | Visualization (VTK_, ROOT_) | ++-----------------------+-------------+-----------------------------------+------------------------------------------------+ +| ``ks_bindings`` | Kassiopeia | Bindings | XML bindings | ++-----------------------+-------------+-----------------------------------+------------------------------------------------+ +| ``ks_field`` | Kassiopeia | Fields | Field calculation | ++-----------------------+-------------+-----------------------------------+------------------------------------------------+ +| ``ks_generator`` | Kassiopeia | Generators | Particle generation | ++-----------------------+-------------+-----------------------------------+------------------------------------------------+ +| ``ks_geometry`` | Kassiopeia | Geometry | Geometry handling | ++-----------------------+-------------+-----------------------------------+------------------------------------------------+ +| ``ks_interaction`` | Kassiopeia | Interactions | Particle interactions | ++-----------------------+-------------+-----------------------------------+------------------------------------------------+ +| ``ks_math`` | Kassiopeia | Math | Mathematical functions | ++-----------------------+-------------+-----------------------------------+------------------------------------------------+ +| ``ks_modifier`` | Kassiopeia | Modifiers | Trajectory modifiers | ++-----------------------+-------------+-----------------------------------+------------------------------------------------+ +| ``ks_navigator`` | Kassiopeia | Navigators | Particle navigation | ++-----------------------+-------------+-----------------------------------+------------------------------------------------+ +| ``ks_object`` | Kassiopeia | Objects | Dynamic command interface | ++-----------------------+-------------+-----------------------------------+------------------------------------------------+ +| ``ks_operator`` | Kassiopeia | Operators | Core functionality, particle state | ++-----------------------+-------------+-----------------------------------+------------------------------------------------+ +| ``ks_reader`` | Kassiopeia | Readers | File reading | ++-----------------------+-------------+-----------------------------------+------------------------------------------------+ +| ``ks_main`` | Kassiopeia | Simulation | Simulation execution | ++-----------------------+-------------+-----------------------------------+------------------------------------------------+ +| ``ks_run`` | Kassiopeia | Simulation | Simulation progress, "run" level | ++-----------------------+-------------+-----------------------------------+------------------------------------------------+ +| ``ks_event`` | Kassiopeia | Simulation | Simulation progress, "event" level | ++-----------------------+-------------+-----------------------------------+------------------------------------------------+ +| ``ks_track`` | Kassiopeia | Simulation | Simulation progress, "track" level | ++-----------------------+-------------+-----------------------------------+------------------------------------------------+ +| ``ks_step`` | Kassiopeia | Simulation | Simulation progress, "step" level | ++-----------------------+-------------+-----------------------------------+------------------------------------------------+ +| ``ks_terminator`` | Kassiopeia | Terminators | Particle termination | ++-----------------------+-------------+-----------------------------------+------------------------------------------------+ +| ``ks_trajectory`` | Kassiopeia | Trajectories | Trajectory calculation | ++-----------------------+-------------+-----------------------------------+------------------------------------------------+ +| ``ks_utility`` | Kassiopeia | Utility | Utility functions | ++-----------------------+-------------+-----------------------------------+------------------------------------------------+ +| ``ks_vis`` | Kassiopeia | Visualization | Visualization (VTK_, ROOT_) | ++-----------------------+-------------+-----------------------------------+------------------------------------------------+ +| ``ks_writer`` | Kassiopeia | Writers | File writing | ++-----------------------+-------------+-----------------------------------+------------------------------------------------+ + +The different parts of the code are explained further below, along with XML configuration examples. + +Verbosity levels +~~~~~~~~~~~~~~~~ + +There are five possible verbosity levels, they are ``debug``, ``info``, ``normal``, ``warning`` and ``error``. Of these, +``error`` is the least verbose, only reporting on fatal errors that terminate the simulation. The ``normal`` mode will +include a relatively small set of details in addition to any warnings (this is the default), while ``debug`` will +provide an extremely extensive description of the state of the simulation as it progresses. + +Note that the ``debug`` setting is a special case: Since there is so much additional information provided by this +setting, it substantially slows down the speed of the simulation even when the messages are not printed or saved to the +log file. In order to avoid unnecessarily slowing down *Kassiopeia*, the debug output is completely disabled unless it +is explicitly enabled in the build by enabling the CMake option ``Kassiopeia_ENABLE_DEBUG`` during configuration (and +the corresponding options for other modules.) + +As mentioned earlier, the verbosity level can also be changed by the command line arguments ``-v`` and ``-q``, which +raise or lower the verbosity level. However, this only works for sources that have not been configured explicitely +in the ```` section. + +Additional logging +~~~~~~~~~~~~~~~~~~ + +The description above applies to the *KMessage* interface, which is configured through XML files. In addition, some code +uses the independent *KLogger* interface. If *Kassiopeia* was compiled with Log4CXX_ enabled at build time, the KLogger +interface can be configured through its own configuration file, which is located at: + + ``$KASPERSYS/config/Kommon/log4cxx.properties`` + +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. + +.. note:: + + In *Kassiopeia*, *KEMField* and *KGeoBag*, most messages use the *KMessage* interface. + + diff --git a/Documentation/gh-pages/source/configuring_simulation_pitfalls.rst b/Documentation/gh-pages/source/configuring_simulation_pitfalls.rst new file mode 100644 index 00000000..c0e1da15 --- /dev/null +++ b/Documentation/gh-pages/source/configuring_simulation_pitfalls.rst @@ -0,0 +1,43 @@ + + +Common Pitfalls and Problems +============================ + +The XML parser does have some ability to recognize simple errors in a configuration file and will generally report the +location of an element which it is not able to process. + +Some errors which might occur if a file is improperly configured are: + +- Multiple objects which share the same name at the same scope. +- Misspelled element types. +- Missing closing brackets. +- Undefined variables. +- Undeclared (but used) elements. + +In the case of more than one copy of the same object with the name ````, the XML parser will fail with with an error +along the lines of:: + + [INITIALIZATION ERROR MESSAGE] Multiple instances of object with name . + +In the case where an element's type name is misspelled the parser will fail with an unreconized element error, or +display a warning that the element is ignored. For example if we misspelled ``ksterm_max_z`` as ``kterm_max_z`` we would +recieve the following warning:: + + [INITIALIZATION WARNING MESSAGE] nothing registered for element in element + +If there is a mis-matched bracket the intialization will usually fail with an unrecongnized character error, such as:: + + [INITIALIZATION ERROR MESSAGE] element encountered an error > + +If a variable "[X]" is used without being previously defined, and undefined error will be reported as follows:: + + [INITIALIZATION ERROR MESSAGE] variable is not defined + +If there is an attempt to retrieve/reference and element which has not been declared the the simulation will fail with +the message:: + + [INITIALIZATION WARNING MESSAGE] No suitable Object called in Toolbox + +Depening on where the element is referenced, the error may look different. For example:: + + [KSOBJECT ERROR MESSAGE] component could not build command named (invalid child component) diff --git a/Documentation/gh-pages/source/configuring_simulation_statements.rst b/Documentation/gh-pages/source/configuring_simulation_statements.rst new file mode 100644 index 00000000..0cd8fbbb --- /dev/null +++ b/Documentation/gh-pages/source/configuring_simulation_statements.rst @@ -0,0 +1,267 @@ +General Statements +=================== + +The document language used for describing a Kassiopeia simulation configuration is based on standard XML_, but has been +augmented with several additional features to aid in complicated or repetitive tasks. For a full description of this +language and its features, see [1]. + +The general XML syntax is: + +.. code-block:: xml + + + + + +where ```` defines an `element` that corresponds to an object of *Kassiopeia* or one of the other modules. Each +element can have an unlimited number of `attrbutes`, each with its own `value`. Attributes are passed on to the +corresponding object during initialization. XML allows nesting of elements, and therefore some elements can have child +elements with the same syntax. + +All elements must end with a closing statement, like `` ... ``. For elements without children, the +syntax can be shortened to the single statement ````. + + +Variables +~~~~~~~~~ + +A local variable may be defined with a particular value (integer,floating point type, string, etc.) with the following +syntax: + +.. code-block:: xml + + + +and may be reference by any other subsequent (using a local variable before it is defined is not allowed) element in the +document through the use of the square brackets ``[...]`` in the following manner: + +.. code-block:: xml + + + +Note that all variables are defined as strings, but can be interpreted as other types (such as numbers, lists, etc.) +by during initialization of the element. The details depend on the element's implementation. + +Normal variables are defined only for the scope of the current file. Global variables, on the other hand, persist across +any subsequently included files. These may be specified through: + +.. code-block:: xml + + + +Both local and global variables my be undefined (removed from the parser's scope) in the following manner: + +.. code-block:: xml + + + + +It is also possible to reassign a variable (changing their value) with the syntax: + +.. code-block:: xml + + + + +Occasionally the user may wish to specify a variable which can be modified from the command line as an argument passed +to *Kassiopeia*. These variables are called `external variables` and they behave in the same way as global variables, +except that their first definition sets their value and other definitions are ignored. Hence, if an external variable +is defined in multiple included files, only the first occurence matters. If the variable is defined on the command line, +its definition precedes any of the included files. + +To define an external variable called ``my_random_seed`` the syntax is: + +.. code-block:: xml + + + +This particular example is useful for running large batches of similar simulations. For example, to simulate many +independent tracks the user might want to run the same simulation repeatedly, but use a different random seed when +starting the simulation. The value of ``my_random_seed`` can be changed from its default value of 123 from the command +line call to *Kassiopeia* in the following manner: + +.. code-block:: bash + + Kassiopeia ./my_simulation.xml -r my_random_seed=456 + +or with the alternate syntax: + +.. code-block:: bash + + Kassiopeia ./my_simulation.xml --my_random_seed=456 + +Note that this applies to other applications that belong to *Kassiopeia* or the other modules as well. + +Including external files +~~~~~~~~~~~~~~~~~~~~~~~~ + +Including external XML files is also supported through a relatively simple syntax. This is helpful when a simulation is +too complex to be managed by a single file. A separate XML file can be included using the following: + +.. code-block:: xml + + + +This include expression may also be configured dynamically through the use of a variable, for example: + +.. code-block:: xml + + + + +could be modified to include an entirely different file by passing another file name argument to *Kassiopeia* using:: + + Kassiopeia ./my_simulation.xml -r my_file_name=my_other_file.xml + +This feature is particularly useful and enables the user to swap in an entirely different configuration for some portion +of the simulation by passing a single command line variable. + +Lastly, it is possible to mark an included file as optional so that no error will be thrown if the files does not exist. +This is sometimes useful when a file with variable definitions should be included before the main configuration. The +syntax in this case is: + +.. code-block:: xml + + + +Print statements +~~~~~~~~~~~~~~~~ + +The XML initializer allows to print the current value of a variable, or any sort of text message. The message will be +shown during XML initialization, and it is useful for debugging and checking correct initialization. The syntax is: + +.. code-block:: xml + + + + +where the message content is set to the current value of the variable through the ``[...]`` syntax. + +To show a general informative message without a variable name, use the syntax: + +.. code-block:: xml + + + +Both examples together will yield the output:: + + [INITIALIZATION NORMAL MESSAGE] value of is <42> + [INITIALIZATION NORMAL MESSAGE] This is a test message. + +Instead of showing normal messages, it is also possible to show a warning or an error message. An error message will +terminate the prgogram, so it is most useful in combination with the conditional expressions described below: + +.. code-block:: xml + + + + +Finally, an assertion statement can be used that checks if a condition is true, and shows an error otherwise. See below +for an explanation of conditional expressions. The syntax for the assert statement is: + +.. code-block:: xml + + + + +Conditional Expressions and Looping +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In addition to mathematical expressions, simple boolean conditions can be specified. These are often helpful for +swapping or toggling on/off different features, but also for setting several variables depending on the value of a "meta +variable". An example showing the inclusion/exclusion of a brief section of XML is shown below: + +.. code-block:: xml + + + + + + + +Note that this uses the formula syntax ``{...}`` in the condition. The operator ``eq`` checks for equality between the +two variables. Other allowed operators are listed in the table below. To combine multiple conditions into one +expression, use brackets like ``([var1] eq [var2]) && ([var3] eq [var4])``. + ++------------------------------------------------------------------------------------------------+ +| Conditional operators | ++-------------+-------------+-------------------+------------------------------------------------+ +| XML syntax | C++ operator| Operator | Description | ++=============+=============+===================+================================================+ +| ``! A`` | ``!`` | Logical "not" | False if statement A is true. | ++-------------+-------------+-------------------+------------------------------------------------+ +| ``A && B`` | ``&&`` | Logical "and" | True if both statements A and B are true. | ++-------------+-------------+-------------------+------------------------------------------------+ +| ``A || B`` | ``||`` | Logical "or" | True if one of the statements A and B is true. | ++-------------+-------------+-------------------+------------------------------------------------+ +| ``A eq B`` | ``==`` | Equal-to | True if both values A and B are equal. | ++-------------+-------------+-------------------+------------------------------------------------+ +| ``A ne B`` | ``!=`` | Not-equal | True if both values A and B are not equal. | ++-------------+-------------+-------------------+------------------------------------------------+ +| ``A gt B`` | ``<`` | Greater-than | True if value A is greater than value B. | ++-------------+-------------+-------------------+------------------------------------------------+ +| ``A lt B`` | ``>`` | Less-than | True if value A is less than value B. | ++-------------+-------------+-------------------+------------------------------------------------+ +| ``A ge B`` | ``>=`` | Greater-or-equal | True if value A is greater or equal to value B.| ++-------------+-------------+-------------------+------------------------------------------------+ +| ``A le B`` | ``<=`` | Less-or-equal | True if value A is less or equal to value B. | ++-------------+-------------+-------------------+------------------------------------------------+ +| ``A mod B`` | ``%`` | Modulo | Return remainder of value A divided by value B.| ++-------------+-------------+-------------------+------------------------------------------------+ + +It is also possible to check directly if a variable has been set to a "true" value (i.e. not 0, false, or an empty +string.) The syntax in this case is: + +.. code-block:: xml + + + + + + +The conditional expression does not support if-else blocks, so in order to define an alternate conditional branch one +has to add another if-statement in the XML file. + +Another feature which is indispensable when assembling complicated or repetitive geometries is the the ability to insert +multiple copies of an XML fragment with slight modifications. This is called looping and is somewhat similar to the way +a for-loop works in C++ or Python. However, it is a purely static construct intended that is only evaluated during XML +initialization to reduce the amount of code needed to describe a geometry (or other XML feature.) + +An example of its use can be found in the ``DipoleTrapMeshedSpaceSimulation.xml`` example. The example of the loop +syntax for the placement of several copies of a surface with the name ``intermediate_z_surface`` is given below: + +.. code-block:: xml + + + + + + + +In this case, the loop variable ``[i]`` is used to define the name of the copy and its displacement. + +Loops and conditional expressions may also be nested when needed. + +Comments +~~~~~~~~ + +It is wise to include comments in the XML files to explain certain structures or their behavior. Comment blocks are +included by the syntax: + +.. code-block:: xml + + + +As shown above, a comment can span multiple lines. Any text between ```` is ignored by the XML initializer, +including any XML elements. This makes it possible to quickly comment out parts of the file, e.g. for debugging. + + + +.. 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/contact.rst b/Documentation/gh-pages/source/contact.rst index d41b6da3..9c9778f9 100644 --- a/Documentation/gh-pages/source/contact.rst +++ b/Documentation/gh-pages/source/contact.rst @@ -48,6 +48,3 @@ In addition to this user guide, *Kassiopeia* and its associated libraries have b PhD theses. Many of these can be found under the list of KATRIN publications_. - -.. _publications: https://www.katrin.kit.edu/375.php -.. _`our paper`: https://iopscience.iop.org/article/10.1088/1367-2630/aa6950 \ No newline at end of file diff --git a/Documentation/gh-pages/source/element_kassiopeia.rst b/Documentation/gh-pages/source/element_kassiopeia.rst index 5f8ea1e9..ca1a7851 100644 --- a/Documentation/gh-pages/source/element_kassiopeia.rst +++ b/Documentation/gh-pages/source/element_kassiopeia.rst @@ -1,11 +1,7 @@ .. _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: @@ -18,1273 +14,25 @@ tags of the form: 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 - - - - - +outlined in this chapter. +.. toctree:: + :maxdepth: 1 + :hidden: + Chapter overview -.. _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/ +.. toctree:: + :maxdepth: 1 + :caption: Chapter contents -.. rubric:: Footnotes + kassiopeia_structure + kassiopeia_generation + kassiopeia_propagation + kassiopeia_output + kassiopeia_navigation + kassiopeia_simulation + kassiopeia_visualization -[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 index c2e28d54..3758c96f 100644 --- a/Documentation/gh-pages/source/element_kemfield.rst +++ b/Documentation/gh-pages/source/element_kemfield.rst @@ -1,14 +1,10 @@ .. _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 `_. +Detailed explanations on installation and implementation are available in the manual displayed at the end of this chapter. The field elements all live within the *KEMField* element and must be placed with start and end tags of the form: @@ -23,167 +19,19 @@ Note that in some configuration files, you may find the "legacy style" setup whe 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/ +.. toctree:: + :maxdepth: 1 + :hidden: + Chapter overview +.. toctree:: + :maxdepth: 1 + :caption: Chapter contents -.. rubric:: Footnotes + kemfield_fields + kemfield_visualization + kemfield_manual -[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 index 85ed1701..473ba9c3 100644 --- a/Documentation/gh-pages/source/element_kgeobag.rst +++ b/Documentation/gh-pages/source/element_kgeobag.rst @@ -1,26 +1,15 @@ - - -KGeoBag (geometry) - -***************************** - .. _KGeoBag: -.. contents:: On this page - :local: - :depth: 2 - - - -Geometry section -================= +KGeoBag (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`). +A full a description of all of the shape objects (surfaces and spaces) which maybe constructed in *KGeoBag* can be found in this chapter. +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 @@ -34,353 +23,25 @@ Every relevant to the geometry description is processed by *KGeoBag* and must ap -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. +.. note:: -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 + 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. - - -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 -=============== +.. toctree:: + :maxdepth: 1 + :hidden: -See the following two chapters for an overview over simple and more advanced shapes: + Chapter overview .. toctree:: :maxdepth: 1 + :caption: Chapter contents - + kgeobag_geometry kgeobag_simple_shapes kgeobag_complex_shapes + kgeobag_visualization -.. _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 413190d8..747b8ce5 100644 --- a/Documentation/gh-pages/source/examples.rst +++ b/Documentation/gh-pages/source/examples.rst @@ -196,13 +196,4 @@ also distributed with Kassiopeia, and are described in the following table. +-----------------------------------------+---------------------------------------------------------------+ - - -.. _VTK: http://www.vtk.org/ -.. _Paraview: http://www.paraview.org/ -.. _TBrowser: https://root.cern.ch/doc/master/classTBrowser.html -.. _PyROOT: https://root.cern/manual/python/ -.. _uproot: https://pypi.org/project/uproot/ -.. _STL: https://en.wikipedia.org/wiki/STL_%28file_format%29 - .. [*] D. Furse *et al.* (2017) New J. Phys. **19** 053012, `doi:10.1088/1367-2630/aa6950 `_ diff --git a/Documentation/gh-pages/source/index.rst b/Documentation/gh-pages/source/index.rst index 14a06ba8..78337b06 100644 --- a/Documentation/gh-pages/source/index.rst +++ b/Documentation/gh-pages/source/index.rst @@ -129,10 +129,3 @@ For more information and a guide on how to set up `Kassiopeia` see chapter :ref: - -.. _`Try it out online`: https://mybinder.org/v2/gh/KATRIN-Experiment/KassiopeiaBinder/HEAD -.. _`the KATRIN collaboration`: https://katrin.kit.edu -.. _`our paper`: https://iopscience.iop.org/article/10.1088/1367-2630/aa6950 -.. _publications: https://www.katrin.kit.edu/375.php - - diff --git a/Documentation/gh-pages/source/introduction.rst b/Documentation/gh-pages/source/introduction.rst index a414f102..aedd1956 100644 --- a/Documentation/gh-pages/source/introduction.rst +++ b/Documentation/gh-pages/source/introduction.rst @@ -45,5 +45,3 @@ Furthermore, the object oriented approach of *Kassiopeia* provides a clear path certain specific features in their own novel applications. Code contributions that extend *Kassiopeia's* functionality can be submitted through GitHub and are always welcome. - -.. _KATRIN: https://www.katrin.kit.edu \ No newline at end of file diff --git a/Documentation/gh-pages/source/kassiopeia_generation.rst b/Documentation/gh-pages/source/kassiopeia_generation.rst new file mode 100644 index 00000000..21609ae1 --- /dev/null +++ b/Documentation/gh-pages/source/kassiopeia_generation.rst @@ -0,0 +1,235 @@ +Generation & Termination +========================= + +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. + + diff --git a/Documentation/gh-pages/source/kassiopeia_navigation.rst b/Documentation/gh-pages/source/kassiopeia_navigation.rst new file mode 100644 index 00000000..7a239272 --- /dev/null +++ b/Documentation/gh-pages/source/kassiopeia_navigation.rst @@ -0,0 +1,120 @@ +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. + +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. + + + diff --git a/Documentation/gh-pages/source/kassiopeia_output.rst b/Documentation/gh-pages/source/kassiopeia_output.rst new file mode 100644 index 00000000..df3a110d --- /dev/null +++ b/Documentation/gh-pages/source/kassiopeia_output.rst @@ -0,0 +1,478 @@ +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`` | ++--------------------+-------------------------------------+------------------+ + diff --git a/Documentation/gh-pages/source/kassiopeia_propagation.rst b/Documentation/gh-pages/source/kassiopeia_propagation.rst new file mode 100644 index 00000000..0e871786 --- /dev/null +++ b/Documentation/gh-pages/source/kassiopeia_propagation.rst @@ -0,0 +1,280 @@ +Propagation & Interactions +=========================== + +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. diff --git a/Documentation/gh-pages/source/kassiopeia_simulation.rst b/Documentation/gh-pages/source/kassiopeia_simulation.rst new file mode 100644 index 00000000..cd20964d --- /dev/null +++ b/Documentation/gh-pages/source/kassiopeia_simulation.rst @@ -0,0 +1,39 @@ +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. + diff --git a/Documentation/gh-pages/source/kassiopeia_structure.rst b/Documentation/gh-pages/source/kassiopeia_structure.rst new file mode 100644 index 00000000..06928982 --- /dev/null +++ b/Documentation/gh-pages/source/kassiopeia_structure.rst @@ -0,0 +1,24 @@ +Conceptual overview +==================== + +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 \ No newline at end of file diff --git a/Documentation/gh-pages/source/kassiopeia_visualization.rst b/Documentation/gh-pages/source/kassiopeia_visualization.rst new file mode 100644 index 00000000..10b69980 --- /dev/null +++ b/Documentation/gh-pages/source/kassiopeia_visualization.rst @@ -0,0 +1,132 @@ + +.. _kassiopeia-visualization: + +Visualization +============== + +The *Kassiopieia* module provides a set of stand-alone visualization tools that are described under :ref:`tools-label`. +The user may also specify visualization elements in the configuration file, which may be combined with the viewers +provided by *KGeoBag*. In fact this is often needed, if one wants to see e.g. the simulated trajectories within +the simulation geometry. + + +Using VTK +~~~~~~~~~ + +Below is an example that combines the VTK_ geometry painter of *KGeoBag* with a visualization of the simulated tracks +(``vtk_track_painter``) and the track terminator positions (``vtk_track_terminator_painter``). + +.. note:: + + In order to use visualizations of simulation data, a ROOT_ output file has to exist. + + +.. code-block:: xml + + + + + + + +The options ``enable_display`` and ``enable_write`` of the ```` element specify if a viewer window should be +shown, and if an output file should be written. The output files can be viewed e.g. in the ParaView_ software. There +also exists a ```` element that is intended to visualize configured generators in the simulation. +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. + +.. note:: + + The visualization window must be placed outside of the ````...```` environment tags. + +Using ROOT +~~~~~~~~~~~~ + +A similar 2D visualization can be achieved using the ROOT_ visualization elements. +In constrast to VTK_, which displays three-dimensional geometry, the ROOT_ visualization is limited to two dimensions. +The example below will present a view of the 3D geometry projected onto the Z-X plane. + +.. code-block:: xml + + + + + + + + +It is possible to combine multiple such views into a single window by using the ```` elements with +corresponding parameters. The projection mode has to be adjusted for the individual geometry painters. Another element, +````, can visualize the convergence radius and source points of the zonal harmonic +approximation that can be used for electric and magnetic field solving. + +Using Python +~~~~~~~~~~~~ + +The track painters export VTK_ output files that can be visualized in Python with the PyVista_ module, as shown in :ref:`kgeobag-visualization`. + diff --git a/Documentation/gh-pages/source/kemfield_fields.rst b/Documentation/gh-pages/source/kemfield_fields.rst new file mode 100644 index 00000000..0a00527a --- /dev/null +++ b/Documentation/gh-pages/source/kemfield_fields.rst @@ -0,0 +1,149 @@ +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 +**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_solver``). 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]. + + + + +.. 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/kemfield_manual.rst b/Documentation/gh-pages/source/kemfield_manual.rst new file mode 100644 index 00000000..d268cd37 --- /dev/null +++ b/Documentation/gh-pages/source/kemfield_manual.rst @@ -0,0 +1,12 @@ + +Manual +--------------- + +The KEMField manual is desplayed below and is alternatively available for download :download:`here <../../../KEMField/Documentation/manual/manual.pdf>`. +It can also be found in the `Github repository `_. + + +.. pdf-include:: ./PDFs/manual.pdf + :width: 100% + :height: 800px + diff --git a/Documentation/gh-pages/source/kemfield_visualization.rst b/Documentation/gh-pages/source/kemfield_visualization.rst new file mode 100644 index 00000000..78da48fa --- /dev/null +++ b/Documentation/gh-pages/source/kemfield_visualization.rst @@ -0,0 +1,98 @@ + +.. _kemfield-visualization: + +Visualization +--------------- + +The *KEMField* modules provides a special visualization that is only available for electrostatic geometries. In contrast +to the geometry viewers from *KGeoBag*, the *KEMField* viewer also includes extra information about the mesh elements, +the applied electric potentials, and the calculated charge densities. It is therefore extremely valuable for the design +of such geometries. + +Electrode Geometry +~~~~~~~~~~~~~~~~~~~~~ + +The viewer is instantiated with the XML element ```` under the ```` or ```` +tag. For example, expanding the ``DipoleTrapSimulation.xml`` file: + +.. code-block:: xml + + + + + + + + +The options ``save`` and ``view`` specify if an output file should be written to the given filename, and if a viewer +window should be shown. The options ``preprocessing`` and ``postprocessing`` indicate if the visualization is to be +performed before or after calculating the charge densities (if both are true, the visualization is performed twice). + +Field maps +~~~~~~~~~~ + +Although not primarily a visualization feature, the option to compute electric and magnetic field maps with *KEMField* +can also be used to provide input for the ParaView_ software that can be combined with other visualization output files. +Field maps can be calculated in 2D or 3D mode, and both variants can readily be used in ParaView. + +The example below will generate a 2D map of the magnetic and electric field: + +.. code-block:: xml + + + + + + + +The output files will only be generated once and the computation is skipped if a file under the same name exists. To +force an update, either delete the file or set ``force_update`` to true. The parameters ``center``, ``length`` and +``spacing`` define the bounds and dimensions of the map. (In this example, a 2D map will be created because one of +the dimensions is equal to zero.) To speed up the computation, it is possible to exclude the magnetic field gradient +(``compute_gradient``) or electric field (``compute_field``), or to make use of existing symmetries in either dimension. +Note that the symmetry is not checked against the actual geometry, so it's a responsibility of the user to set this up +correctly. diff --git a/Documentation/gh-pages/source/kgeobag_complex_shapes.rst b/Documentation/gh-pages/source/kgeobag_complex_shapes.rst index 225d7f7e..0249ba57 100644 --- a/Documentation/gh-pages/source/kgeobag_complex_shapes.rst +++ b/Documentation/gh-pages/source/kgeobag_complex_shapes.rst @@ -451,24 +451,3 @@ An XML example is as follows: - - -.. _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_geometry.rst b/Documentation/gh-pages/source/kgeobag_geometry.rst new file mode 100644 index 00000000..38c2251d --- /dev/null +++ b/Documentation/gh-pages/source/kgeobag_geometry.rst @@ -0,0 +1,319 @@ + +Geometry section +================= + + +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:`kgeobag-visualization`. 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`. + diff --git a/Documentation/gh-pages/source/kgeobag_simple_shapes.rst b/Documentation/gh-pages/source/kgeobag_simple_shapes.rst index 529fe6ef..eb3dbd71 100644 --- a/Documentation/gh-pages/source/kgeobag_simple_shapes.rst +++ b/Documentation/gh-pages/source/kgeobag_simple_shapes.rst @@ -1052,23 +1052,3 @@ The parameters are: - 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/kgeobag_visualization.rst b/Documentation/gh-pages/source/kgeobag_visualization.rst new file mode 100644 index 00000000..19e59bfc --- /dev/null +++ b/Documentation/gh-pages/source/kgeobag_visualization.rst @@ -0,0 +1,79 @@ +.. _kgeobag-visualization: + +KGeoBag Visualization +===================== + +The *KGeoBag* module provides a set of stand-alone visualization tools that are described under :ref:`tools-label`. These +are suited to display the simulation geometry and other geometric elements, such as the mesh used for field calculation +and/or navigation. + +In addition, the geometry visualization can also be defined in the configuration file. In this case, output files +may be produced before or after performing the simulation, and a visualization window can be shown as well. Note that +the visualization window blocks the application until it is closed, so it is not advised to use this feature in a +scripted environment. The examples in this section are based on the ``DipoleTrapSimulation.xml`` file, which may be extended accordingly to test the features explained here and in the following chapters. +The commandline option ``-b`` (or ``-batch``) will prevent any visualization windows to appear regardless of the setting in the configuration file, e.g.: + +.. code-block:: bash + + Kassiopeia -b DipoleTrapSimulation.xml + + +The *KGeoBag* module provides painter classes for the geometry which are covered below in the *Kassiopeia* section. +In addition, the mesh geometry can be viewed as well: + +.. code-block:: xml + + + + + +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** + + +It is possible to draw a geometry visualization in Python. This is especially useful if you run your analysis in Python as well (see :ref:`output-label` for examples.) + +The PyVista_ Python package makes it easy to operate on the VTK_ output files that are produced by *KGeoBag* and the +other *Kasper* modules. (Note that this method only works if VTK_ was enabled at build time.) In the XML snippets above, +the different VTK painters will produce output files if the ``enable_write`` attribute is set. These files contain the +3D geometry in the `vtp` format and can be read in Python. In order to get a 2D view of the geometry, one also needs to +create a slice that transforms the 3D surfaces into 2D lines. + +.. code-block:: python + + import pyvista as pv + import matplotlib as mpl + import matplotlib.pyplot as plt + + # Open geometry file + dataset = pv.read('geometry_painter.vtp') + + # Produce a slice along the x-z axis + mesh = dataset.slice(normal=[0,1,0]) + + # Draw lines in each slice cell + plt.figure() + xlim, ylim = (0,0), (0,0) + for ind in range(mesh.n_cells): + x, y, z = mesh.cell_points(ind).T + + if mesh.cell_type(ind) == 3: # VTK_LINE + line = mpl.lines.Line2D(z, x, lw=2, c='k') + plt.gca().add_artist(line) + xlim = (min(xlim[0],z.min()), max(xlim[1],z.max())) + ylim = (min(ylim[0],x.min()), max(ylim[1],x.max())) + plt.xlim(xlim) + plt.ylim(ylim) + + diff --git a/Documentation/gh-pages/source/links.rst b/Documentation/gh-pages/source/links.rst new file mode 100644 index 00000000..75901c0a --- /dev/null +++ b/Documentation/gh-pages/source/links.rst @@ -0,0 +1,60 @@ +.. This file contains the links and replacements used in the documentation + +.. _publications: https://www.katrin.kit.edu/375.php +.. _`our paper`: https://iopscience.iop.org/article/10.1088/1367-2630/aa6950 +.. _`Try it out online`: https://mybinder.org/v2/gh/KATRIN-Experiment/KassiopeiaBinder/HEAD +.. _`the KATRIN collaboration`: https://katrin.kit.edu +.. _`our paper`: https://iopscience.iop.org/article/10.1088/1367-2630/aa6950 +.. _publications: https://www.katrin.kit.edu/375.php +.. _KATRIN: https://www.katrin.kit.edu +.. _TBrowser: https://root.cern.ch/doc/master/classTBrowser.html +.. _PyROOT: https://root.cern/manual/python/ +.. _uproot: https://pypi.org/project/uproot/ +.. _STL: https://en.wikipedia.org/wiki/STL_%28file_format%29 +.. _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/ +.. _PyVista: https://www.pyvista.org/ +.. _NumPy: https://numpy.org/ +.. _Pandas: https://pandas.pydata.org/ +.. _CMake: https://www.cmake.org/ +.. _GCC: https://gcc.gnu.org/ +.. _Clang: https://clang.llvm.org/ +.. _HDF5: https://support.hdfgroup.org/HDF5/ +.. _LibXml2: https://www.xmlsoft.org/ +.. _PCL: https://www.pointclouds.org/ +.. _PETSc: https://mcs.anl.gov/petsc/ +.. _DoxyGen: https://www.doxygen.nl/ +.. _GSL: https://www.gnu.org/software/gsl/ +.. _Boost: http://www.boost.org/ +.. _TBB: https://www.threadingbuildingblocks.org/ +.. _OpenMPI: https://www.open-mpi.org/ +.. _MPICH: http://www.mpich.org/ +.. _FFTW: http://www.fftw.org/ +.. _CUDA: https://developer.nvidia.com/cuda-toolkit +.. _OpenCL: https://www.khronos.org/opencl/ +.. _ZLIB: http://www.zlib.net/ +.. _miniz: https://code.google.com/archive/p/miniz/ +.. _Docker: https://www.docker.com/ +.. _GoogleTest: https://github.com/google/googletest/ +.. _gperftools: https://github.com/gperftools/gperftools/ + +.. |gccVersion| replace:: 6.1 +.. |clangVersion| replace:: 3.4 +.. |CMakeVersion| replace:: 3.14 +.. |BoostVersion| replace:: 1.65 +.. |ROOTVersion| replace:: 6.24 +.. |FFTWVersion| replace:: 3.3.4 +.. |VTKVersion| replace:: 7.0 + + + diff --git a/Documentation/gh-pages/source/output.rst b/Documentation/gh-pages/source/output.rst index 09b6e10c..f923eda7 100644 --- a/Documentation/gh-pages/source/output.rst +++ b/Documentation/gh-pages/source/output.rst @@ -777,10 +777,3 @@ However, because the storage is rather inefficient it should not be used for lar the order of several Gigabytes can be easily produced by a typical Monte-Carlo simulation! -.. _Paraview: http://www.paraview.org/ -.. _ROOT: https://root.cern.ch/ -.. _VTK: http://www.vtk.org/ -.. _NumPy: https://numpy.org/ -.. _Pandas: https://pandas.pydata.org/ -.. _uproot: https://pypi.org/project/uproot/ -.. _Gnuplot: http://www.gnuplot.info/ diff --git a/Documentation/gh-pages/source/runningKassiopeia.rst b/Documentation/gh-pages/source/runningKassiopeia.rst index c653ec00..5c4708e1 100644 --- a/Documentation/gh-pages/source/runningKassiopeia.rst +++ b/Documentation/gh-pages/source/runningKassiopeia.rst @@ -51,11 +51,5 @@ just once in the terminal. To immediately exit the simulation (without cleaning the key combination ``Crtl-C`` again, which leads to program termination. -.. _VTK: http://www.vtk.org/ -.. _Paraview: http://www.paraview.org/ -.. _TBrowser: https://root.cern.ch/doc/master/classTBrowser.html -.. _PyROOT: https://root.cern/manual/python/ -.. _uproot: https://pypi.org/project/uproot/ -.. _STL: https://en.wikipedia.org/wiki/STL_%28file_format%29 .. [*] D. Furse *et al.* (2017) New J. Phys. **19** 053012, `doi:10.1088/1367-2630/aa6950 `_ diff --git a/Documentation/gh-pages/source/setup_manual.rst b/Documentation/gh-pages/source/setup_manual.rst index c6781941..b61169da 100644 --- a/Documentation/gh-pages/source/setup_manual.rst +++ b/Documentation/gh-pages/source/setup_manual.rst @@ -422,36 +422,3 @@ The ``COMPILER_TUNE_OPTIONS`` flag activates the compiler options: Since this produces code compiled for the current CPU, this option should not be used on a computing cluster or other architectures where compiled code is shared between different machines. Be aware that this option is largely untested. - -.. _CMake: https://www.cmake.org/ -.. _GCC: https://gcc.gnu.org/ -.. _Clang: https://clang.llvm.org/ -.. _HDF5: https://support.hdfgroup.org/HDF5/ -.. _LibXml2: https://www.xmlsoft.org/ -.. _PCL: https://www.pointclouds.org/ -.. _PETSc: https://mcs.anl.gov/petsc/ -.. _DoxyGen: https://www.doxygen.nl/ -.. _GSL: https://www.gnu.org/software/gsl/ -.. _ROOT: https://root.cern.ch/ -.. _Boost: http://www.boost.org/ -.. _Log4CXX: https://logging.apache.org/log4cxx/latest_stable/ -.. _TBB: https://www.threadingbuildingblocks.org/ -.. _VTK: http://www.vtk.org/ -.. _OpenMPI: https://www.open-mpi.org/ -.. _MPICH: http://www.mpich.org/ -.. _FFTW: http://www.fftw.org/ -.. _CUDA: https://developer.nvidia.com/cuda-toolkit -.. _OpenCL: https://www.khronos.org/opencl/ -.. _ZLIB: http://www.zlib.net/ -.. _miniz: https://code.google.com/archive/p/miniz/ -.. _Docker: https://www.docker.com/ -.. _GoogleTest: https://github.com/google/googletest/ -.. _gperftools: https://github.com/gperftools/gperftools/ -.. |gccVersion| replace:: 6.1 -.. |clangVersion| replace:: 3.4 -.. |CMakeVersion| replace:: 3.14 -.. |BoostVersion| replace:: 1.65 -.. |ROOTVersion| replace:: 6.24 -.. |FFTWVersion| replace:: 3.3.4 -.. |VTKVersion| replace:: 7.0 - diff --git a/Documentation/gh-pages/source/tools.rst b/Documentation/gh-pages/source/tools.rst index 9a148e21..1c4f7556 100644 --- a/Documentation/gh-pages/source/tools.rst +++ b/Documentation/gh-pages/source/tools.rst @@ -159,5 +159,3 @@ Finally, some helper tools are provided with *Kassiopeia* that can be used toget All listed programs will show a brief usage summary if called without arguments. -.. _ROOT: https://root.cern.ch/ -.. _VTK: http://www.vtk.org/ diff --git a/Documentation/gh-pages/source/visualization.rst b/Documentation/gh-pages/source/visualization.rst deleted file mode 100644 index d3bae103..00000000 --- a/Documentation/gh-pages/source/visualization.rst +++ /dev/null @@ -1,301 +0,0 @@ -.. _visualization-label: - -Visualization Techniques -************************ - -The *Kasper* software provides some visualization techniques that can help with the design and optimization of a -simulation, and with interpreting its results. In general, there are options for 2D visualization using the ROOT_ -software and for 3D visualization using the VTK_ toolkit. The VTK output files can also be viewed and combined with -external software such as ParaView_. - -The examples in this section are based on the ``DipoleTrapSimulation.xml`` file, which may be extended accordingly to -test the features explained here. - -.. contents:: On this page - :local: - :depth: 2 - -KGeoBag visualization -===================== - -The *KGeoBag* module provides a set of stand-alone visualization tools that are described under :ref:`tools-label`. These -are suited to display the simulation geometry and other geometric elements, such as the mesh used for field calculation -and/or navigation. - -In addition, the geometry visualization can also be defined in the configuration file. In this case, output files -may be produced before or after performing the simulation, and a visualization window can be shown as well. Note that -the visualization window blocks the application until it is closed, so it is not advised to use this feature in a -scripted environment. The commandline option ``-b`` (or ``-batch``) will prevent any visualization windows to appear -regardless of the setting in the configuration file, e.g.: - -.. code-block:: bash - - Kassiopeia -b DipoleTrapSimulation.xml - -Geometry visualization ----------------------- - -The *KGeoBag* module provides painter classes for the geometry which are covered below in the *Kassiopeia* section. -In addition, the mesh geometry can be viewed as well: - -.. code-block:: xml - - - - - -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 -~~~~~~~~~~~~ - -It is possible to draw a geometry visualization in Python. This is especially useful if you run your analysis in Python as well (see :ref:`output-label` for examples.) - -The PyVista_ Python package makes it easy to operate on the VTK_ output files that are produced by *KGeoBag* and the other *Kasper* modules. (Note that this method only works if VTK_ was enabled at build time.) In the XML snippets above, the different VTK painters will produce output files if the ``enable_write`` attribute is set. These files contain the 3D geometry in the `vtp` format and can be read in Python. In order to get a 2D view of the geometry, one also needs to create a slice that transforms the 3D surfaces into 2D lines. - -.. code-block:: python - - import pyvista as pv - import matplotlib as mpl - import matplotlib.pyplot as plt - - # Open geometry file - dataset = pv.read('geometry_painter.vtp') - - # Produce a slice along the x-z axis - mesh = dataset.slice(normal=[0,1,0]) - - # Draw lines in each slice cell - plt.figure() - xlim, ylim = (0,0), (0,0) - for ind in range(mesh.n_cells): - x, y, z = mesh.cell_points(ind).T - - if mesh.cell_type(ind) == 3: # VTK_LINE - line = mpl.lines.Line2D(z, x, lw=2, c='k') - plt.gca().add_artist(line) - xlim = (min(xlim[0],z.min()), max(xlim[1],z.max())) - ylim = (min(ylim[0],x.min()), max(ylim[1],x.max())) - plt.xlim(xlim) - plt.ylim(ylim) - - -Kassiopieia visualization -========================= - -The *Kassiopieia* module provides a set of stand-alone visualization tools that are described under :ref:`tools-label`. -The user may also specify visualization elements in the configuration file, which may be combined with the viewers -provided by *KGeoBag*. In fact this is often needed, if one wants to see e.g. the simulated trajectories within -the simulation geometry. - -Track visualization -------------------- - -Using VTK -~~~~~~~~~ - -Below is an example that combines the VTK_ geometry painter of *KGeoBag* with a visualization of the simulated tracks -(``vtk_track_painter``) and the track terminator positions (``vtk_track_terminator_painter``). Note that in order -to use visualizations of simulation data, a ROOT_ output file has to exist. - -.. code-block:: xml - - - - - - - -The options ``enable_display`` and ``enable_write`` of the ```` element specify if a viewer window should be -shown, and if an output file should be written. The output files can be viewed e.g. in the ParaView_ software. There -also exists a ```` element that is intended to visualize configured generators in the simulation. - -Using ROOT ----------- - -A similar 2D visualization can be achieved using the ROOT_ visualization elements. The example below will present a view -of the 3D geometry projected onto the Z-X plane. - -.. code-block:: xml - - - - - - - - -It is possible to combine multiple such views into a single window by using the ```` elements with -corresponding parameters. The projection mode has to be adjusted for the individual geometry painters. Another element, -````, can visualize the convergence radius and source points of the zonal harmonic -approximation that can be used for electric and magnetic field solving. - -Using Python -~~~~~~~~~~~~ - -The track painters export VTK_ output files that can be visualized in Python with the PyVista_ module, as shown above. - - -KEMField visualization -====================== - -The *KEMField* modules provides a special visualization that is only available for electrostatic geometries. In contrast -to the geometry viewers from *KGeoBag*, the *KEMField* viewer also includes extra information about the mesh elements, -the applied electric potentials, and the calculated charge densities. It is therefore extremely valuable for the design -of such geometries. - -Electrode Geometry ------------------- - -The viewer is instantiated with the XML element ```` under the ```` or ```` -tag. For example, expanding the ``DipoleTrapSimulation.xml`` file: - -.. code-block:: xml - - - - - - - - -The options ``save`` and ``view`` specify if an output file should be written to the given filename, and if a viewer -window should be shown. The options ``preprocessing`` and ``postprocessing`` indicate if the visualization is to be -performed before or after calculating the charge densities (if both are true, the visualization is performed twice). - -Field maps ----------- - -Although not primarily a visualization feature, the option to compute electric and magnetic field maps with *KEMField* -can also be used to provide input for the ParaView_ software that can be combined with other visualization output files. -Field maps can be calculated in 2D or 3D mode, and both variants can readily be used in ParaView. - -The example below will generate a 2D map of the magnetic and electric field: - -.. code-block:: xml - - - - - - - -The output files will only be generated once and the computation is skipped if a file under the same name exists. To -force an update, either delete the file or set ``force_update`` to true. The parameters ``center``, ``length`` and -``spacing`` define the bounds and dimensions of the map. (In this example, a 2D map will be created because one of -the dimensions is equal to zero.) To speed up the computation, it is possible to exclude the magnetic field gradient -(``compute_gradient``) or electric field (``compute_field``), or to make use of existing symmetries in either dimension. -Note that the symmetry is not checked against the actual geometry, so it's a responsibility of the user to set this up -correctly. - -.. _ROOT: https://root.cern.ch/ -.. _VTK: http://www.vtk.org/ -.. _ParaView: https://www.paraview.org/ -.. _PyVista: https://www.pyvista.org/