Welcome to Kassiopeia’s documentation!

Documentation Contents

• Introduction
  • The Kasper framework
  • Extending Functionality
• References, Citation and Contact
  • External references
  • Developer contact
• Getting Started
  • Downloading the code
  • Supported operating systems and hardware requirements
  • Docker image
  • Required software dependencies
    • Minimum requirements
    • Required dependencies
    • Optional dependencies
    • External libraries
  • Compiling the code using CMake
    • Environment variables
  • Directory structure and environmental variables
    • Executing Kassiopeia
  • Configuring optional dependencies
    • Build options
      • Kassiopeia module
      • KEMField module
      • KGeoBag module
      • Kommon module
      • Miscellaneous options
• Examples and Tests
  • 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
  • Overview and Units
  • XML Parsing and Features
    • General Statements
      • Variables
      • Including external files
      • Print statements
      • Conditional Expressions and Looping
      • Comments
    • Formula Expressions
    • Messaging System
      • Verbosity levels
      • Additional logging
  • Geometry
    • Shapes and assemblies
    • Tagging system
    • Assembling elements
    • Transformations
    • Extensions
  • KEMField
    • Fields
      • Electric
      • Magnetic
  • Kassiopeia
    • Generation
      • Choosing energy values
      • Value generator types
      • Special creator types
    • Termination
    • 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
    • Navigation and Commands
    • Simulation
    • Visualization
      • VTK visualization
      • ROOT visualization
    • Common Pitfalls and Problems
• Basic KGeoBag Shapes
  • Geometry visualization
  • Basic elements
    • Poly-loop
    • Poly-line
  • Surfaces
    • Flat surfaces
      • Flattened circle surface
      • Flattened poly-loop surface
    • Rotated Surfaces
      • Rotated line segment surface
      • Rotated arc segment surface
      • Rotated poly-line surface
      • Rotated circle surface
      • Rotated poly loop surface
    • Shell Surfaces
      • Shell line segment surface
      • Shell arc segment surface
      • Shell poly-line surface
      • Shell circle surface
      • Shell poly-loop surface
    • Extruded Surfaces
      • Extruded poly-line surface
      • Extruded circle surface
      • Extruded poly-loop surface
    • Special Surfaces
      • Disk surface
      • Annulus surface
      • Cylinder surface
      • Cone Surface
      • Cut Cone Surface
      • Torus Surface
      • Cut Torus Surface
  • Spaces
    • Extruded Spaces
      • Extruded Circle Space
      • Extruded Poly-Loop Space
    • Rotated Spaces
      • Rotated Line Segment
      • Rotated Arc Segment
      • Rotated Poly-Line Space
      • Rotated Circle Space
      • Rotated Poly-Loop Space
    • Special Spaces
      • Cylinder Space
      • Cone Space
      • Cut Cone Space
      • Torus Space
      • Cylinder Tube Space
      • Cut Cone Tube Space
      • Box Space
• Complex KGeoBag Shapes
  • Surfaces
    • Pump Port Surface
    • Conic Section Pump Port Surface
    • Beam Surface
      • Multi-cut surfaces
    • 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
• 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
• Additional Simulation Tools
  • Geometry viewers
    • Usage
    • Advanced visualization
  • Mesh viewers
    • Usage
  • Field calculation
    • Usage
  • Simulation tools
• Visualization Techniques
  • KGeoBag visualization
    • Geometry visualization
      • Using Python
  • Kassiopieia visualization
    • Track visualization
      • Using VTK
    • Using ROOT
      • Using Python
  • KEMField visualization
    • Electrode Geometry
    • Field maps
• XML Bindings
  • Overview
  • Bindings graph
  • List of bindings
    • KRoot
      • KommonNamedRandomGenerator
      • KDummyRandom
      • KGInterface
      • KGGeometryPrinter
      • KSRoot
      • KEMRoot
      • KMessageTable
      • KROOTWindow
      • KApplicationRunner
      • KVTKWindow
• License
• Authors

This simulation package by the KATRIN collaboration allows to run highly customizable particle tracking simulations along with calculations of electric and magnetic fields.

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)

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.

More information