5.30. [ User Defined Interaction ], [ User Defined Particle ] section

This section is for utilizing user-defined interactions or particles.

  • See /phits/utility/UserDefinedModel/readme-en.pdf for details.

  • Currently, when using User Defined Interaction for electrons, positrons, and photons, it is necessary to use EGS5, negs=1,2.

  • The range of user-defined particle kf-code values that can be set is \(900000 \le \mathrm{kf} \le 999999\) or \(-99999999 \le \mathrm{kf} \le -900000\).

There are three types of files in the /phits/src/ folder.

  1. udm_int_<NAME>.f90 A source file that defines a module with information on user-defined interactions, such as cross sections. The <NAME> part of the filename can be specified by the user. The udm_int_sample.f90 file is already included in the /phits/src/ folder as a sample. In this sample source, electrons or positrons with energies over 100 MeV interact with material of atomic number \(Z\) at a cross section of \(Z\times 10^{-6}\) barn, emitting one user-defined particle.

  2. udm_part_<NAME>.f90 A source file that defines a module with information on user-defined particles, such as mass, lifetime, and branching ratios. The <NAME> part of the filename can be specified by the user. The udm_part_sample.f90 file is already included in the /phits/src/ folder as a sample. This sample source defines a user-defined particle that decays into an electron neutrino. Its mass and lifetime can be specified in the input file.

  3. udm_manager.f90 A source file that specifies the module to be used.

An example input for [ User Defined Interaction ] is as follows.

Listing 5.30.1 [ User Defined Interaction ] section example (1)
[ User Defined Interaction ]
$ Name           Bias    Parameters
my_interaction   1.0e+5  900000

This input example is an input file to run udm_int_sample.f90. The first and second arguments input the Name of the module to be used and the bias value, respectively. For instance, my_interaction corresponds to the string assigned to the Name variable in the udm_int_sample module defined in udm_int_sample.f90. The occurrence frequency of processes with small cross sections can be increased by setting the bias value greater than one. In such cases, the weight of the generated particle is automatically adjusted, so average final results are not dependent on the bias value. For the third argument, zero or more parameter values can be input. The number and meaning of the parameters to be used depend on the source file. In the case of the udm_int_sample module, the first parameter value represents the kf-code value of the user-defined particle being generated.

An example input for [ User Defined Particle ] is as follows.

Listing 5.30.2 [ User Defined Particle ] section example (1)
[ User Defined Particle ]
$ Name       kfcode   Parameters
my_particle  900000   1.0 1e-8

This input example is an input file to run udm_part_sample.f90. The first and second arguments input the Name of the module to be used and the kf-code value of the particle handled in this file, respectively. For instance, my_particle corresponds to the string assigned to the Name variable in the udm_part_sample module defined in udm_part_sample.f90. For the third argument, you can input zero or more parameter values. The number and significance of the parameters to be used depend on the source file. In the case of the udm_part_sample module, the first and second parameter values represent the user-defined particle’s mass, in MeV, and lifetime, in seconds. The udm_part_<NAME>.f90 file can be used not only to define user-specific particles but also to modify properties of existing particles, such as lifetime and branching ratios.

5.30.1. Application examples of user-defined code

5.30.1.1. Example 1: Muon Pair Production Induced by Positrons

\(e^+e^-_{\rm atomic}\to\mu^+\mu^-\)

User code: udm_int_ee2mumu.f90

Usage:

Listing 5.30.3 [ User Defined Interaction ] section example (2)
[ User Defined Interaction ]
$ Name     Bias      Parameters
ee2mumu    1.0e+5

5.30.1.2. Example 2: Neutrino reaction

By loading neutrino databases, a wider range of neutrino reactions can be generated. An example database can be downloaded from the following URL:

https://rcwww.kek.jp/research/shield/sakaki/phits/temp.html

User code: udm_int_neutrino.f90

Usage:

Listing 5.30.4 [ User Defined Interaction ] section example (3)
[ User Defined Interaction ]
$ Name     Bias   Parameters
neutrino   1      <Absolute or relative path to the database folder>

5.30.1.3. Example 3: Apply Energy Cutoff Only to Specified Regions and Particles

User code: udm_int_kill.f90

Usage:

If a particle corresponding to kf-code <kf> in region number <reg> is not transported when its energy is less than <emin>, write these three values repeatedly in the Parameters section. The value of Bias is ignored.

Listing 5.30.5 [ User Defined Interaction ] section example (4)
[ User Defined Interaction ]
$ Name    Bias   Parameters
kill      1      <kf1> <reg1> <emin1>   <kf2> <reg2> <emin2>  ...

Input-1:

Do not transport electrons, kf=11, in region 101 if their energy is below 500 MeV, and do not transport neutrons, kf=2112, in region 102 if their energy is below 100 MeV. If kf=0, the condition applies to all particles.

Listing 5.30.6 [ User Defined Interaction ] section example (5)
[ User Defined Interaction ]
$ Name   Bias   Parameters
kill     1      11 101 500   2112 102 100

Input-2:

Prepare a data file in which each line contains information in the format <kf> <reg> <emin>. Specify the relative or absolute path of that file in the Parameters section.

Listing 5.30.7 [ User Defined Interaction ] section example (6)
[ User Defined Interaction ]
$ Name   Bias   Parameters
kill     1      emin.txt

Example of emin.txt:

Listing 5.30.8 Example of emin.txt
#   kf  reg  emin
    11  101   100
   -11  101   100
  2212  102    50
     0  103    30