Particle Diagnostics
====================

This page is generated from in-code XGC I/O metadata by ``utils/python/document_outputs.py``.

Particle, escaped-particle, and particle-consistency diagnostic outputs.

xgc.particle.*.bp
-----------------

.. list-table::
   :header-rows: 1
   :widths: 25 20 55

   * - Variable
     - Units
     - Description
   * - ``sp_name + "gid"``
     - Positive integer
     - Global ID of the markers in the sample.
   * - ``sp_name + "nphase"``
     - Positive integer
     - Number of particle phase variables.
   * - ``sp_name + "num_total"``
     - Positive integer
     - Number of markers in the sample.
   * - ``sp_name + "phase"``
     - [m, m, rad, m, dimensionless, dimensionless, J/T, dimensionless, m^-3, optional: m^-3]
     - Selected species particle phase array with columns [R, Z, phi, rho, w1, w2, mu, w0, g], where :math:`R`, :math:`Z`, and :math:`\phi` are the cylindrical coordinates of the particle, :math:`\rho` is the parallel gyroradius (proxy for :math:`v_{\parallel}`), :math:`w_1` is the delta-f weight, :math:`w_2` is a weight used in the weight evolution equation, :math:`\mu` is the magnetic moment, :math:`w_0` is the full-f weight (from importance sampling), and :math:`g` is the marker density. Particles are selected when their global particle ID is positive and divisible by diag_particle_mod. If PTL_G2 is enabled, an additional g2 marker-density column is appended.
   * - ``time``
     - s
     - Simulation time of step in seconds.
   * - ``timestep``
     - Positive integer
     - Simulation time step index.

xgc.escaped_ptls.*.bp
---------------------

.. list-table::
   :header-rows: 1
   :widths: 25 20 55

   * - Variable
     - Units
     - Description
   * - ``prefix + "dw"``
     - dimensionless
     - Decoded escaped-particle weight-change payload from the packed particle flag.
   * - ``prefix + "flag"``
     - integer flag
     - Decoded escaped-particle low-bit status flags for this species.
   * - ``prefix + "gid"``
     - index
     - Globally unique marker-particle IDs for escaped particles of this species.
   * - ``prefix + "maxgid"``
     - Non-negative integer
     - Largest globally unique marker-particle ID already assigned for this species when escaped particles are written.
   * - ``prefix + "nphase"``
     - Positive integer
     - Number of columns in the escaped-particle phase array.
   * - ``prefix + "num_total"``
     - Non-negative integer
     - Total number of escaped marker particles written for this species in this diagnostic step.
   * - ``prefix + "phase"``
     - [m, m, rad, m, dimensionless, dimensionless, J/T, dimensionless, m^-3, T m^2, T]
     - Escaped-particle phase array with columns [R, Z, phi, rho, w1, w2, mu, w0, g, psi, \|B\|], where :math:`R`, :math:`Z`, and :math:`\phi` are the cylindrical coordinates of the particle, :math:`\rho` is the parallel gyroradius (proxy for :math:`v_{\parallel}`), :math:`w_1` is the delta-f weight, :math:`w_2` is a weight used in the weight evolution equation, :math:`\mu` is the magnetic moment, :math:`g` is the marker density, :math:`\psi` is the poloidal magnetic flux, and :math:`\|B\|` is the magnetic-field magnitude.
   * - ``prefix + "step"``
     - Non-negative integer
     - Simulation time step at which each escaped particle was marked for output.
   * - ``time``
     - s
     - Simulation time of step in seconds.
   * - ``timestep``
     - Non-negative integer
     - Simulation time step of the escaped-particle diagnostic output.

particle_check*.bp
------------------

.. list-table::
   :header-rows: 1
   :widths: 25 20 55

   * - Variable
     - Units
     - Description
   * - ``refgid``
     - index
     - Reference globally unique particle IDs used by the global particle consistency check.
   * - ``refphase``
     - [m, m, rad, m, dimensionless, dimensionless, J/T, dimensionless, m^-3]
     - Reference particle phase array with columns [R, Z, phi, rho, w1, w2, mu, w0, g], where :math:`R`, :math:`Z`, and :math:`\phi` are the cylindrical coordinates of the particle, :math:`\rho` is the parallel gyroradius (proxy for :math:`v_{\parallel}`), :math:`w_1` is the delta-f weight, :math:`w_2` is a weight used in the weight evolution equation, :math:`\mu` is the magnetic moment, :math:`w_0` is the full-f weight (from importance sampling), and :math:`g` is the marker density. Used by the global particle consistency check.