.. _[t-wwg]:

[ T-WWG ] section
==================================================

This tally gives parameters used for the **[Weight Window]** section.
The tally serves as a Weight Window Generator (WWG) to automatically obtain effective settings of **[Weight Window]** for a user-defined virtual space.
When using this function, a test calculation using an input file including the **[t-wwg]** tally must be performed.
Long calculations can then be performed using the **[Weight Window]** section generated from this test calculation.
In the case of **mesh=reg**, you have to give the volume of each cell in the **[volume]** section.
When you perform the restart calculation or use the sumtally function with an input file including **[t-wwg]**, set **axis** other than **wwg** and **ireschk=1** in the **[parameters]** section.

This tally scores the fluence of particles in each history :math:`j`, particle :math:`k`, energy mesh :math:`l`, and geometrical mesh :math:`m`, denoted as :math:`\Phi_{jklm}`.
Then, at the end of each batch, it determines the lower limit of their weight window, :math:`W_{klm,\rm low}`, as written below:

.. math::
   :label: eq-wlow

   W_{klm,\rm low}
    =
    C_{kl}
    \left[
     \left( \Sigma_j \Phi_{jklm} \right)_{k,l,x{\rm \%ile}}
     + \Sigma_j \Phi_{jklm}
    \right],

where :math:`\left( \Sigma_j \Phi_{jklm} \right)_{k,l,x{\rm \%ile}}` is the :math:`x`-percentile value of :math:`\Sigma_j\Phi_{jklm}` for particle :math:`k` and energy mesh :math:`l` among all geometrical mesh :math:`m`.
The value of :math:`x` can be determined by an input parameter named **pedestal** whose default value is 0.1 that indicates 10 percentiles.
The basic idea of this equation is to make :math:`W_{klm,\rm low}` proportional to :math:`\Sigma_j\Phi_{jklm}`, but the introduction of the **pedestal** term, :math:`\left( \Sigma_j \Phi_{jklm} \right)_{k,l,x{\rm \%ile}}`, is required to avoid extremely low :math:`W_{klm,\rm low}` that could cause excessive particle splitting.

:math:`C_{kl}` in Eq. :eq:`eq-wlow` is the normalization constant which depends on an input parameter named **normww** as written below:

.. math::
   :label: eq-ckl

   C_{kl}
    =
    \begin{cases}
     \frac{W_{\rm max}}{
     \left( \Sigma_j \Phi_{jklm} \right)_{m,{\rm max}}
     }
     &
     {\rm for \, normww=0}
     \\
     \frac{W_{\rm max}}{
     \left( \Sigma_j \Phi_{jklm} \right)_{lm,{\rm max}}
     }
     &
     {\rm for \, normww=1}
     \\
     \frac{W_{\rm max}}{
     \left( \Sigma_j \Phi_{jklm} \right)_{klm,{\rm max}}
     }
     &
     {\rm for \, normww=2}
     \\
     \frac{W_{\rm max}}{
     \left( \Sigma_j \Phi_{jklm} \right)_{m,{\rm max}}
     }
     \frac{ \left( \Sigma_{jm} \Phi_{jklm} \right) }
     {\left( \Sigma_{jm} \Phi_{jklm} \right)_{l,{\rm min}}}
     &
     {\rm for \, normww=-1}
     \\
     \frac{W_{\rm max}}{
     \left( \Sigma_j \Phi_{jklm} \right)_{m,{\rm max}}
     }
     \frac{ \left( \Sigma_{jm} \Phi_{jklm} \right) }
     {\left( \Sigma_{jm} \Phi_{jklm} \right)_{kl,{\rm min}}}
     &
     {\rm for \, normww=-2}
    \end{cases}

Here, the subscripts :math:`m, \max`, :math:`lm, \max`, and :math:`klm, \max` denote the maximum values over the respective indices, while :math:`l, \min` and :math:`lm, \min` denote the minimum values over the corresponding indices.
For example, :math:`\left( \sum_j \Phi_{jklm} \right)_{lm, \mathrm{max}}` represents the maximum value of :math:`\left( \sum_j \Phi_{jklm} \right)` over all energy groups l and spatial meshes m, and thus takes different values for each particle k.
When **normww** is 0, 1, or 2, normalization is performed based on the maximum fluence at the mesh points of m, lm, and klm, respectively.
On the other hand, when **normww** is -1 or -2, a correction term is added based on the energy group (for -1) or particle-energy group (for -2) that gives the minimum value of the sum over m, i.e., the total fluence over the entire spatial domain.
As a result, biases in the total fluence among energy groups (for -1) or among particle-energy groups (for -2) are corrected, yielding weight window values that lead to a more balanced spatial distribution of Monte Carlo particles.
Thus, if you want to focus on high-energy neutron transport, you can narrow the energy-mesh width of high-energy neutrons and set **normww=1**, so that :math:`W_{klm,\rm low}` for that high-energy group will be smaller overall.

The fundamental concept of **[t-wwg]** is to generate a **[weight window]** section that can distribute MC fluence as uniformly as possible to all locations within the regions defined in **[t-wwg]**.
On the other hand, if you want to evaluate the dose in a certain region of interest (ROI) with high accuracy in a short time, you can generate a **[weight window]** that can navigate particles to the ROI by combining the history counter and the maximum biasing factor, :math:`B_{\rm max}`, defined by the **chwei** parameter.
For activating this algorithm, you must define the **[counter]** section to increase a counter value when a particle enters the ROI and specify the **chwei(i)** parameter in **[t-wwg]**, where :math:`i` is the counter number defined in **[counter]**.
Then, this tally determines the biasing factor for each mesh, :math:`B_{klm}`, as written below:

.. math::
   :label: eq-bklm

   B_{klm}
    =
    \frac{\Sigma_j H_{ij} \varphi_{jklm}}
    {\left( \Sigma_j H_{ij} \varphi_{jklm} \right)_{k,l,{\rm max}} }
    \left[ B_{\rm max} -1 \right]
    +1.

where :math:`H_{ij}` is the :math:`i`-th history-counter value of history :math:`j`, and :math:`\varphi_{jklm}` is the MC fluence for the condition.
The strategy behind this equation is to maximize the biasing factor up to :math:`B_{\rm max}=` **chwei(i)** at the geometrical mesh :math:`m` that gives the maximum value of :math:`\Sigma_j H_{ij} \varphi_{jklm}`, that is the location where the MC particles pass through most frequently before or after arriving at the ROI, while minimizing the factor to 1 where :math:`\Sigma_j H_{ij} \varphi_{jklm}=0`.
The lower limit of the weight window, :math:`W_{klm,\rm low}`, is calculated by replacing :math:`\Sigma_j \varphi_{jklm}` with :math:`\Sigma_j \Phi_{jklm}/B_{klm}` in Eqs. :eq:`eq-wlow` and :eq:`eq-ckl`.
Please see the literature [#wwg-paper]_ and the lecture notes [#wwg-note]_ for more details.

The **[t-wwg]** parameters are formatted as follows.

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

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

   * - value
     - explanation
   * - **reg, xyz, tet**
     - Mesh type.
       Only **reg**, **xyz**, and **tet** can be set.
       A mesh type subsection is required below this option.

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

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

   * - value
     - explanation
   * -  | **1** (optional)
     -  | 1: [ :math:`1/\mathrm{cm}^2/\mathrm{source}` ]

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

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

   * - value
     - explanation
   * - **eng, reg, tet, t**
     - x axis value of output data.
   * - **xy, yz, xz**
     - 2-dimensional.
       They are the same as **[t-track]**.
   * - **wwg**
     - To obtain the **[Weight Window]** section, set **axis=wwg**.
       To perform restart calculation, set two or more **axis** parameters, and then set the first **axis** to **reg**, **eng**, or **t**.


Only **reg**, **xyz**, and **tet** can be set as **mesh** in this tally, because the parameters in **[Weight Window]** are defined only for these mesh types.
Note that the surfaces of **xyz** mesh should be slightly shifted from surfaces of cells.
Please be especially careful if you are using parameters to link geometry boundary and **xyz** mesh ranges.
After version 3.34, if the maximum and minimum xyz mesh values for **[weight window]** and **[t-wwg]** are defined as integers, the minimum value is shifted by :math:`-1*` **deltxyz** and the maximum value by :math:`+2*` **deltxyz** from the integer, see :ref:`faq-e-lostparticle`.
**mesh=tet** can be used only for geometry containing tetrahedral-mesh geometry.
The weight window factors for each constituent tetrahedron element for the tetrahedral-mesh geometry can be obtained.
In short, **axis** should be set to **wwg** to obtain the parameters for **[Weight Window]**.
Although **eng**, **reg**, **tet**, **xy**, **yz**, **xz**, and **t** can also be set, their results are not related with **[Weight Window]**.
Note that restart calculation cannot be performed when **axis=xy**, **yz**, or **xz** are selected because the ``_err`` file is not created by this tally.

.. include:: ./commontally/file.rst
.. include:: ./commontally/resfile.rst
.. include:: ./commontally/factor.rst
.. include:: ./commontally/title.rst
.. include:: ./commontally/angel.rst
.. rst-class:: no-caption-number

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

   * - value
     - explanation
   * - **0** (default), **1, 2, 3**
     - When **mesh=reg** and **axis=xy,yz,xz**, region border (1), material name (2), and region name (3) are plotted using this option.
       A **xyz** mesh section must be added below this option.

.. include:: ./commontally/resol.rst
.. include:: ./commontally/width.rst
.. rst-class:: no-caption-number

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

   * - value
     - explanation
   * - (optional)
     - This option defines the volume for each region for **reg** mesh.
       Volume definitions are required below this option.
       Values defined in **[volume]** are used in the case of no definition.
       If special description such as using ``(  )`` is used to specify a region in **reg=**, its internally defined region number is output in input echo when this volume subsection is not defined.

.. include:: ./commontally/epsout.rst
.. include:: ./commontally/ph5out.rst
.. include:: ./commontally/trcl.rst
.. include:: ./commontally/gslat.rst
.. include:: ./commontally/stdcut.rst
.. rst-class:: no-caption-number

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

   * - value
     - explanation
   * - (optional, D=0.1)
     - Percentile value, :math:`x` in Eq. :eq:`eq-wlow`, divided by 100 for calculating the pedestal of :math:`W_{klm,{\rm low}}`.

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

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

   * - value
     - explanation
   * - (optional, D=-2)
     - Normalization option, see Eq. :eq:`eq-ckl`.
       **0**: No adjustment.
       :math:`\pm 1`: Adjust :math:`C_{kl}` so that the MC fluences in each energy group are equivalent.
       :math:`\pm 2`: Adjust :math:`C_{kl}` so that the MC fluences in each particle and energy group are equivalent.

When **normww** is set to a positive value, the overall weight window values become lower, so the weight of each particle is controlled primarily by particle splitting.
Conversely, if **normww** is set to a negative value, the overall weight window values become higher, leading to more frequent Russian roulette.
For calculation conditions with large variance per history, such as the case of sources with a wide energy distribution, a negative value will give better statistics per unit computational time, since the calculation time per history will be shorter.
This is the reason why **normww=-2** is selected as the default value.
However, care should be taken to define particle type and energy mesh in the case of **normww=-2**, as most particles are killed by Russian roulette if there is even one group with extremely low particle fluence in each particle and energy group.
For the **part** parameter, it is recommended to set **all** or **neutron photon** in the case of neutron and photon only transport calculations.
Regarding the energy groups, it is recommended to set the number of energy bins just a few, or less, with a slightly narrower group width for the energy bands that contribute the most to the tally.
If you are not sure which setting is optimal, we encourage you to use **part=all** and **ne=1**.
In that case, the calculation results will not depend on **normww**.

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

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

   * - value
     - explanation
   * - (optional, D=0.99)
     - Normalization constant corresponding to the maximum value of :math:`W_{klm,{\rm low}}`, see Eq. :eq:`eq-ckl`.

.. include:: ./commontally/ctmin.rst
.. include:: ./commontally/ctmax.rst
.. include:: ./commontally/chmin.rst
.. include:: ./commontally/chmax.rst
.. rst-class:: no-caption-number

.. list-table:: **chwei(i)**
   :header-rows: 0

   * - value
     - explanation
   * - (optional, D=0)
     - Magnitude of particle-navigation capability in the generated **[weight windows]** using the i-th history counter, that is :math:`B_{\rm max}` in Eq. :eq:`eq-bklm`.
       Only one of these parameters can be defined per **[t-wwg]**, even if their counter IDs are different.
       The restart calculation or use of the sumtally function is now allowed when this parameter is defined.

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

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

   * - value
     - explanation
   * - (optional, D=all)
     - The plane, **xy**, **yz**, or **xz**, for calculating the maximum value of :math:`\left( \Sigma_j H_{ij} \varphi_{jklm} \right)_{k,l,{\rm max}}` in Eq. :eq:`eq-bklm`.
       The default value is **all**, which indicates that the maximum value is calculated from all geometrical meshes.
       When using particle-navigation function for duct streaming calculations, specifying a plane perpendicular to the duct will reduce the computation time.
       This parameter is valid only when **mesh=xyz** and **chwei** is defined.

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

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

   * - value
     - explanation
   * - (optional, D=0)
     - Threshold energy [MeV] for the low-energy unbiasing method.
       Below this energy, the lower limit of the weight window is multiplied by **elowthre**.
       If it is set to 0, the low-energy unbiasing method is not used.
       Note that the number of energy bins, **ne**, must be set to 1 when using this method.

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

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

   * - value
     - explanation
   * - (optional, D=5.0)
     - The multiplying factor for the lower limit of the weight window for energies below **elowthre**.


An example output of this tally is as follows.

.. code-block:: text
   :caption: Example output of **[t-wwg]**

   [ Weight Window ]
        mesh =  reg

   set:  c71[0.0]  c72[c71+2.13496E-08]  c73[1.25478E-04]
   set:  c74[0.0]  c75[c74+9.29569E-09]  c76[2.08987E-04]

       part = neutron
        eng =  2
             1.00000E-03   1.00000E+03

       reg          ww1                    ww2
       1   (8.94092E-05+c71)/c73  (2.08987E-04+c74)/c76
       2   (1.25478E-04+c71)/c73  (1.26817E-04+c74)/c76
       3   (8.53835E-05+c71)/c73  (5.78131E-05+c74)/c76

In this sample, the **[Weight Window]** parameters for neutrons with two energy bins are output.
In principle, it is not necessary to change these parameters, but **c71** or **c74** should be specified when adding a constant value for each Weight Window.

.. [#wwg-paper] Sato et al. Nucl. Instr. and Meth. B, 2024; 557: 165535.
.. [#wwg-note] ``phits/lecture/advanced/weightB`` and ``phits/lecture/advanced/shielding``