Welcome to Kassiopeia’s documentation!

Documentation Contents

• Welcome to Kassiopeia's documentation!

General information

• Contact, Meeting and References
  • Contact
  • Regular Meeting
  • References and Citation
• License
• Authors

Getting Started

• Introduction
  • The Kasper framework
  • Extending Functionality
• Setup with container
  • Docker image
    • Docker/Podman/Apptainer(/Singularity)
    • Provided images
  • Running a docker container
    • Run on HPC infrastructure (Apptainer/Singularity)
    • Run locally (docker/podman)
    • File structure of the container
    • Listing and removing existing containers
    • Running applications directly
  • Setting up persistent storage
    • Using a persistent volume
    • Using an existing directory
  • Running graphical applications
    • Using kassiopeia_full
    • Using kassiopeia_minimal
  • Root access
  • Customizing Docker containers
  • Building the docker image
    • Minimal (bare Kassiopeia installation)
    • Full (for personal use)
  • Re-Building Kassiopeia with Docker
• Manual installation
  • Downloading the code
  • Software dependencies
    • Required software dependencies
    • Minimum requirements
      • Debian/Ubuntu
      • RedHat/Fedora
    • Required dependencies
    • Optional dependencies
    • External libraries
  • Compiling the code using CMake
  • Configuring optional dependencies
    • Build options
    • Kassiopeia module
    • KEMField module
    • KGeoBag module
    • Kommon module
    • Miscellaneous options
• Directory structure & environmental variables

Usage

• Running Kassiopeia
  • Verbosity levels
  • Output files
• Example configurations
  • The Dipole Trap Example
    • Trajectory Visualization
  • The Quadrupole Trap Example
    • Simulation Analysis
  • The Photomultiplier Tube Example
    • Visualization with ParaView
  • The Mesh Simulation Example
  • Other Examples
• Configuring your own simulation
  • General Statements
    • Variables
    • Including external files
    • Print statements
    • Conditional Expressions and Looping
    • Comments
  • Formula Expressions
  • Messaging System
    • Verbosity levels
    • Additional logging
  • Common Pitfalls and Problems
• KGeoBag (geometry) - <geometry>
  • Geometry section
    • Shapes and assemblies
    • Tagging system
    • Assembling elements
    • Transformations
    • Extensions
  • Basic Shapes in KGeoBag
    • Geometry visualization
    • Basic elements
      • Poly-loop
      • Poly-line
    • Surfaces
      • Flat surfaces
      • Rotated Surfaces
      • Shell Surfaces
      • Extruded Surfaces
      • Special Surfaces
    • Spaces
      • Extruded Spaces
      • Rotated Spaces
      • Special Spaces
  • Complex Shapes in KGeoBag
    • Surfaces
      • Pump Port Surface
      • Conic Section Pump Port Surface
      • Beam Surface
      • Rod Surface
      • Extruded Surfaces with holes
      • Rotated Surface
    • Spaces
      • Pump Port Space
      • Conic Section Pump Port Space
      • Beam Space
      • Rod Space
      • Extruded Space
      • Rotated Space
    • Shapes from imported files
      • STL File Surface
      • STL File Space
  • KGeoBag Visualization
  • Tools
    • Geometry viewers
      • Usage
      • Advanced visualization
    • Mesh viewers
      • Usage
• KEMField (fields) - <kemfield>
  • Fields
    • Electric fields
    • Magnetic fields
  • Visualization
    • Electrode Geometry
    • Field maps
  • Tools
    • Field calculation
    • Development
    • Usage
  • Manual
• Kassiopeia (particles) - <kassiopeia>
  • Conceptual overview
  • Generation & Termination
    • Generation
      • Choosing energy values
      • Value generator types
      • Special creator types
    • Termination
  • Propagation & Interactions
    • Propagation
      • Exact trajectory
      • Adiabatic trajectory
      • Electric and magnetic trajectories
      • Trajectory types
      • Examples
    • Interactions
      • Volume Interactions
      • Surface Interactions
  • Output
    • Writers
    • Output description
    • Output fields
  • Navigation
    • Surfaces navigation
    • Space navigation
    • Meshed space navigation
      • Commands
  • Simulation
  • Visualization
    • Using VTK
    • Using ROOT
    • Using Python
  • Tools

Further Information

• Understanding Simulation Output
  • Output configuration
    • Groups and fields
    • Output structure
  • ROOT output files
    • Data structure
    • Accessing simulation data
      • Using Kassiopeia
      • Using ROOT
      • Using Python
      • Using Python with KassiopeiaReader
      • Using Python with uproot / Pandas
    • Python notebook
    • Geometry visualization
  • VTK output files
    • Data structure
    • Accessing simulation data
      • Using ParaView
    • ASCII output files
• XML Bindings
  • Overview
  • Bindings graph
  • List of bindings
    • KRoot
      • KommonNamedRandomGenerator
      • KDummyRandom
      • KGInterface
      • KGGeometryPrinter
      • KSRoot
      • KEMRoot
      • KMessageTable
      • KROOTWindow
      • KApplicationRunner
      • KVTKWindow

This simulation package by the KATRIN collaboration allows to run highly customizable particle tracking simulations along with calculations of electric and magnetic fields. Kassiopeia is supported and intended to run on systems running either Linux or MacOS X.

Source Code: https://github.com/KATRIN-Experiment/Kassiopeia

Quick start: Try it out online in an interactive Binder session. Open a “VNC (Desktop)” tab and a terminal tab and run

Kassiopeia $KASPERSYS/config/Kassiopeia/Examples/DipoleTrapSimulation.xml

to run your first simulation! Note: A VTK error indicates that the “VNC (Desktop)” tab is not open yet.

Cite our paper :

D. Furse et al. (2017) New J. Phys. 19 053012: “Kassiopeia: A Modern, Extensible C++ Particle Tracking Package” (doi:10.1088/1367-2630/aa6950)

In addition to this user guide, Kassiopeia and its associated libraries have been documented extensively in several PhD theses. Many of these can be found under the list of KATRIN publications.

Docker images

All images: https://github.com/orgs/KATRIN-Experiment/packages

The kassiopeia/full image comes with a JupyterLab installation, can run on Kubernetes based JupyterHubs and is also used for the “try it out online” link above. For more information and a guide on how to set up Kassiopeia see chapter Setup via container.