.. _[t-product]:

[ T-Product ] section
==================================================

This tally gives particles and nuclei produced by nuclear reactions, decays, and fission, and also tallies source particles.
It differs from **[t-yield]** in that the energy and time distributions of produced particles and nuclei can be obtained in **[t-product]**.
No residual nuclei calculated by nuclear data libraries are scored.
Note that nuclei produced by neutrons with energies below **dmax(2)** are scored by setting **e-mode>=1**.

.. rst-class:: no-caption-number

.. list-table:: **mesh**
   :header-rows: 0

   * - value
     - explanation
   * - **reg, r-z, xyz, tet**
     - Mesh type.
       A mesh type subsection is required below this option.

.. rst-class:: no-caption-number

.. list-table:: **part**
   :header-rows: 0

   * - value
     - explanation
   * - **all** (default), particle name
     - Produced particle.

.. include:: ./commontally/material.rst
.. rst-class:: no-caption-number

.. list-table:: **mother**
   :header-rows: 0

   * - value
     - explanation
   * - (optional)
     - Specify mother nuclei.
   * - **all**
     - **all** is the default, same as no definition.
   * - number of mother nuclei
     - When setting the number of mother nuclei, define the mothers in the next line.
       The number of **mother** can be set as a negative value, in which case the specified mothers are not included for scoring.
       When **output=atomic**, **mother** cannot be specified.
   * - (next line)
     - **208Pb Pb**
       Nucleus if specified using mass.
       Without mass, all nuclei are isotopes of Pb.
       To specify multiple mother groups, use multiple **[t-product]** tallies.


When specifying **mother** , use the format described in :numref:`sec-part-spec` .

.. include:: ./commontally/e-type.rst
.. rst-class:: no-caption-number

.. list-table:: **e-unit**
   :header-rows: 0

   * - value
     - explanation
   * - **MeV** (default), **keV**, **eV**, **nm**, **A0**, **keV/um**
     - Unit of energy mesh.
       **nm** specifies wavelength in nanometers, **A0** specifies wavelength in angstroms. For massive particles, the de Broglie wavelength is used.
       When using **nm** or **A0**, unit must be 1, 2, 11, 12, 21, 22, 31, or 32.
       **keV/um** converts the energy axis to LET (equivalent to eng2let=1).

.. rst-class:: no-caption-number

.. list-table:: **eng2let**
   :header-rows: 0

   * - value
     - explanation
   * - (optional)
     - **0**, default: do not convert energy defined by **e-type** to LET.
       **1**: convert energy to LET, keV/um.
       Set **eng2let=1** and **axis=let** when you want to output the results as a function of LET.

.. include:: ./commontally/t-type.rst
.. include:: ./commontally/a-type.rst

Isomeric nuclei are supported as valid inputs for the **part** parameter.
Isomers can be specified by placing **m**, **n**, or **g** at the end of isotope names such as ``Na-24m``, first isomer, ``In-116m``, first isomer, ``In-116n``, second isomer, or ``In-116g``, ground state.
To score isomers, do not forget to set **igamma=3** in the **[parameters]** section.
Even if **igamma=3**, **part=Na-24** means that the sum of the Na-24 ground state and Na-24m isomer is scored.

.. rst-class:: no-caption-number

.. list-table:: **unit**
   :header-rows: 0

   * - value
     - explanation
   * - **1, 2, 3, 4, 5, 6**
     - 1: [1/source]
       2: [1/cm^3/source]
       3: [1/MeV/source]
       4: [1/cm^3/MeV/source]
       5: [1/Lethargy/source]
       6: [1/cm^3/Lethargy/source]
   * - **11, 12, 13, 14, 15, 16**
     - 11: [1/nsec/source]
       12: [1/cm^3/nsec/source]
       13: [1/MeV/nsec/source]
       14: [1/cm^3/MeV/nsec/source]
       15: [1/Lethargy/nsec/source]
       16: [1/cm^3/Lethargy/nsec/source]
   * - **21, 22, 23, 24, 25, 26**
     - 21: [1/sr/source]
       22: [1/cm^3/sr/source]
       23: [1/MeV/sr/source]
       24: [1/cm^3/MeV/sr/source]
       25: [1/Lethargy/sr/source]
       26: [1/cm^3/Lethargy/sr/source]
   * - **31, 32, 33, 34, 35, 36**
     - 31: [1/nsec/sr/source]
       32: [1/cm^3/nsec/sr/source]
       33: [1/MeV/nsec/sr/source]
       34: [1/cm^3/MeV/nsec/sr/source]
       35: [1/Lethargy/nsec/sr/source]
       36: [1/cm^3/Lethargy/nsec/sr/source]

.. rst-class:: no-caption-number

.. list-table:: **axis**
   :header-rows: 0

   * - value
     - explanation
   * - **eng, let, reg, x, y, z, r**
     - x axis value of output data.
   * - **tet**
     - x axis value of output data, only active with **mesh=tet**.
   * - **cos, the**
     - Angle, cosine, **theta** in degree, mesh.
   * - **xy, yz, xz, rz**
     - 2-dimensional.
   * - **t**
     - Time axis.

.. include:: ./commontally/samepage.rst
.. include:: ./commontally/file.rst
.. include:: ./commontally/resfile.rst

Lethargy in **unit=5, 6, 15, 16, 25, 26, 35, 36** is the natural logarithmic unit of energy defined by :math:`\ln(E_{\rm ref}/E)` using a reference energy :math:`E_{\rm ref}` and the particle energy :math:`E`.
Setting these units enables obtaining results in units of Lethargy, which are given as Lethargy widths, :math:`\ln(E_{\rm high}/E_{\rm low})`, for each energy bin in the energy mesh subsection.
Here :math:`E_{\rm high}` and :math:`E_{\rm low}` are the maximum and minimum values of the energy bins, respectively.

In **unit=21-26** or **31-36**, **sr** denotes steradians as the solid angle unit.

.. rst-class:: no-caption-number

.. list-table:: **output**
   :header-rows: 0

   * - value
     - explanation
   * - **source**
     - Source particles defined in **[source]** section.
   * - **nuclear** (default)
     - Particles from nuclear reaction, including elastic.
   * - **nonela**
     - Particles from nonelastic collision.
   * - **elastic**
     - Particles from elastic collision.
   * - **decay**
     - Particles from decay.
       Particles generated from RI source are not included.
   * - **fission**
     - Particles from fission.
       Particles generated from fission neutron source are not included.
   * - **atomic**
     - Particles from atomic interaction.

.. rst-class:: no-caption-number

.. list-table:: **primary**
   :header-rows: 0

   * - value
     - explanation
   * - **1** (optional), **0**
     - 1: both primary and secondary particles at the end of reactions are tallied.
       0: only secondary particles are tallied.
       This parameter is valid for **output=nuclear, elastic, atomic**.
       Otherwise, it is treated as 0.

.. include:: ./commontally/factor.rst
.. include:: ./commontally/title.rst
.. include:: ./commontally/angel.rst
.. include:: ./commontally/sangel.rst
.. include:: ./commontally/2d-type.rst
.. include:: ./commontally/gshow.rst
.. include:: ./commontally/rshow.rst
.. include:: ./commontally/x-txt.rst
.. include:: ./commontally/y-txt.rst
.. include:: ./commontally/z-txt.rst
.. include:: ./commontally/resol.rst
.. include:: ./commontally/width.rst

In the case of **output=decay** or **output=source**, the **primary** parameter is invalid because no primary particle exists.
No particles are excluded from tally by **primary**.
In the case of **output=nonela** or **output=fission**, the primary particle can survive, but the **primary** parameter is invalid because primary and secondary particles are indistinguishable.
No particles are excluded from tally by **primary**.
In the case of **output=atomic** with **primary=1**, the primary particle is scored at every atomic reaction in track structure mode.
Please ensure that this operation aligns with your intent.
**output=nuclear** is the sum of **nonela** and **elastic**.
**primary** only affects **elastic**, whereas **nonela** is not affected.

.. include:: ./commontally/volume.rst
.. include:: ./commontally/iechrl.rst
.. include:: ./commontally/volmat.rst
.. include:: ./commontally/epsout.rst
.. include:: ./commontally/bmpout.rst
.. include:: ./commontally/vtkout.rst
.. include:: ./commontally/vtkfmt.rst
.. include:: ./commontally/foamout.rst
.. include:: ./commontally/maxangel.rst
.. include:: ./commontally/ctmin.rst
.. include:: ./commontally/ctmax.rst
.. include:: ./commontally/chmin.rst
.. include:: ./commontally/chmax.rst
.. include:: ./commontally/trcl.rst
.. rst-class:: no-caption-number

.. list-table:: **dump**
   :header-rows: 0

   * - value
     - explanation
   * - Number of data
     - For **mesh=reg**, the information is dumped on the file.
       If **dump** is negative, data are written by ascii, if positive, by binary.
   * - (next line)
     - Data sequence.
       Define the data sequence.
       The history information, **nocas** and **nobch**, is necessary to use **idmpmode=1**.

.. rst-class:: no-caption-number

.. list-table:: **letmat**
   :header-rows: 0

   * - value
     - explanation
   * - (optional)
     - Effective only when **eng2let=1**.
       Material id for LET, :math:`dE/dx`.
       If not defined, a real material is assumed.
       If a material not used in the geometry is selected, its material density must be defined in **[material]**.
       To calculate LET in water, define water with 1 g/cm^3 in **[material]**.
       When **letmat<0** is set, PHITS automatically calculates :math:`dE/dx` for water with 1 g/cm^3 for electrons and positrons.
       Please see ``ParticleTherapy`` in the recommendation setting for more details.

.. include:: ./commontally/gslat.rst
.. include:: ./commontally/stdcut.rst

When **coll** or reaction events belonging to **coll** are specified in **[counter]**, the counter value changes before the particle information is tallied.
Therefore, to tally the information at the moment the reaction event occurs, specify the counter value after the change.

In the **[t-product]** tally, the dump option can only be used.
If the dump option is set, the meshes of **e-type** and **t-type** have only the meaning of the maximum and minimum values.
When using this **dump** parameter, **axis** and **file** are restricted to one axis and one file, and **unit** is always 1.
The dumped data are written onto a file named ``***_dmp``, where ``***`` indicates the file name specified by **file=***.
The normal output of the tally is written on ``***``.
From this file, information on the total normalization factor can be obtained; doing so requires setting one mesh each for **e-type**, **a-type**, and **t-type**.
Note that constraints based on the history counter, **chmin** and **chmax**, do not work with the dump function because the particle information is output to the dump file immediately after particle generation.
The history information, **nocas** and **nobch**, is necessary to use **idmpmode=1** for continuous calculation using the dump file; in addition, both the dump file with ``_dmp`` and the normal output file specified by **file=** are required to use **idmpmode=1**.
The option **dumpall** is not compatible with this dump tally option when shared memory parallelization is active.

**[t-product]** can tally source particles, and the function can be used to modify the dump file.
Dump files can be read and information written to a new dump file through modifications made by setting the **dump** parameter and **output=source** in this tally section and **icntl=6** in the **[parameters]** section.