ks_simulation

The final object to be declared within <kassiopeia> 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:

<ks_simulation
    name="quadrupole_trap_simulation"
    run="1"
    seed="51385"
    events="10"
    magnetic_field="field_electromagnet"
    electric_field="field_electrostatic"
    space="space_world"
    generator="generator_uniform"
    trajectory="trajectory_exact"
    space_navigator="nav_space"
    surface_navigator="nav_surface"
    writer="write_root"
/>

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 </kassiopeia> is placed to complete the simulation configuration. When this tag is encountered by the XML parser, it triggers the simulation to run.

XML element: <ks_simulation>
C++ type: KSSimulation
Attributes

Attribute

Type

Description

add_static_event_modifier

string

Refers to the name of one of: <ks_root_event_modifier>, <ksmod_event_report>.

add_static_run_modifier

string

Refers to the name of one of: <ks_root_run_modifier>.

add_static_step_modifier

string

Refers to the name of one of: <ks_root_step_modifier>, <ksmod_dynamic_enhancement>, <ksmod_split_on_turn>.

add_static_track_modifier

string

Refers to the name of one of: <ks_root_track_modifier>.

command

string

the name of a command that is executed at the start of the simulation.

Refers to the name of one of: <add_control>, <add_electric_field>, <add_magnetic_field>, <add_space_interaction>, <add_step_modifier>, <add_step_output>, <add_term>, <add_terminator>, <add_track_output>, <clear_density>, <clear_step_data>, <clear_step_point>, <clear_surface_interaction>, <clear_track_data>, <clear_track_point>, <clear_trajectory>, <ks_command_member>, <remove_control>, <remove_electric_field>, <remove_magnetic_field>, <remove_space_interaction>, <remove_step_modifier>, <remove_step_output>, <remove_term>, <remove_terminator>, <remove_track_output>, <set_density>, <set_step_data>, <set_step_point>, <set_surface_interaction>, <set_track_data>, <set_track_point>, <set_trajectory>.

electric_field

string

the name of the electric field used at the start of the simulation.

Refers to the name of one of: <constant_electric_field>, <electric_potentialmap>, <electric_quadrupole_field>, <electrostatic_field>, <induced_azimuthal_electric_field>, <linear_electric_field>, <ramped_electric_field>, <ramped_transitional_electric_field>.

events

unsigned int

generator

string

the name of the generator used at the start of the simulation.

Refers to the name of one of: <ks_root_generator>, <ksgen_generator_composite>, <ksgen_generator_file>, <ksgen_generator_simulation>.

magnetic_field

string

the name of the magnetic field used at the start of the simulation.

Refers to the name of one of: <constant_magnetic_field>, <electromagnet_field>, <field_electromagnet>, <magnetic_dipole_field>, <magnetic_fieldmap>, <magnetic_superposition_field>, <ramped_magnetic_field>.

name

string

run

unsigned int

seed

unsigned int

space

string

the name of the navigation space in which the simulation starts.

Refers to the name of one of: <ksgeo_space>.

space_interaction

string

the name of a space interaction active at the start of the simulation.

Refers to the name of one of: <ks_root_space_interaction>, <ksint_decay>, <ksint_scattering>, <ksint_spin_flip>, <ksint_spin_flip_pulse>, <ksint_spin_rotate_y_pulse>.

space_navigator

string

the name of the space navigator.

Refers to the name of one of: <ks_root_space_navigator>, <ksnav_meshed_space>, <ksnav_space>.

step_report_iteration

unsigned int

surface

string

the name of a navigation surface active at the start of the simulation.

Refers to the name of one of: <ksgeo_surface>.

surface_interaction

string

the name of a surface interaction active at the start of the simulation.

Refers to the name of one of: <kess_surface_interaction>, <ks_root_surface_interaction>, <ksint_surface_UCN>, <ksint_surface_diffuse>, <ksint_surface_multiplication>, <ksint_surface_specular>, <ksint_surface_spin_flip>.

surface_navigator

string

the name of the surface navigator.

Refers to the name of one of: <ks_root_surface_navigator>, <ksnav_surface>.

terminator

string

the name of a terminator active at the start of the simulation.

Refers to the name of one of: <ks_root_terminator>, <ksterm_death>, <ksterm_magnetron>, <ksterm_max_energy>, <ksterm_max_length>, <ksterm_max_long_energy>, <ksterm_max_r>, <ksterm_max_step_time>, <ksterm_max_steps>, <ksterm_max_time>, <ksterm_max_total_time>, <ksterm_max_z>, <ksterm_min_distance>, <ksterm_min_energy>, <ksterm_min_long_energy>, <ksterm_min_r>, <ksterm_min_z>, <ksterm_output>, <ksterm_secondaries>, <ksterm_stepsize>, <ksterm_trapped>, <ksterm_zh_radius>.

trajectory

string

the name of the trajectory used at the start of the simulation.

Refers to the name of one of: <ks_root_trajectory>, <kstraj_trajectory_adiabatic>, <kstraj_trajectory_adiabatic_spin>, <kstraj_trajectory_electric>, <kstraj_trajectory_exact>, <kstraj_trajectory_exact_spin>, <kstraj_trajectory_exact_trapped>, <kstraj_trajectory_linear>, <kstraj_trajectory_magnetic>.

writer

string

the name of the writer.

Refers to the name of one of: <ks_root_writer>, <kswrite_ascii>, <kswrite_root>, <kswrite_vtk>.

Used as:

More information

Explained in: Simulation

Appears in the documentation:

Used in example configurations: