NUBEAM Monte Carlo particle lists and lost-particle output

TRANSP/NUBEAM Technical Documentation

Purpose: Description of NUBEAM Monte Carlo particle-state files, particle phase-space reconstruction, species identification, output configuration, and lost-particle diagnostics.

1. Introduction

NUBEAM generates and tracks Monte Carlo (MC) particles to simulate the behavior of energetic ions produced by neutral beam injection (NBI) and fusion reactions.

NUBEAM provides particle-state files containing information about individual fast ions, including their positions, velocities, pitch coordinates, statistical weights, and species identification.

These files can be used for:

• Reconstruction of fast-ion distribution functions.

• Restarting NUBEAM calculations.

• Debugging particle orbit calculations.

• Analysis of particle phase-space evolution.

• Post-processing of fast-ion distributions.

NUBEAM also provides lost-particle diagnostics containing information about particles lost during orbit tracking.

This document describes the structure, generation, and interpretation of these outputs.

2. NUBEAM particle-state files

NUBEAM stores particle information in arrays with dimensions:

(minb, mibs)

where:

• minb — Monte Carlo particle storage dimension.

• mibs — Number of particle species.

Only the particle information required for restarting or debugging NUBEAM is stored.

2.1 Primary Monte Carlo Particle Properties

nbienay(minb,mibs)

Energy fraction of the original injected beam ion:

• 1 — Full injection energy.

• 2 — Half injection energy.

• 3 — One-third injection energy.

einjay(minb,mibs)

Original ion injection energy in the laboratory frame.

pmechay(minb,mibs)

Particle mechanical momentum.

pphiay(minb,mibs)

Particle canonical momentum.

pinjay(minb,mibs)

Injected power associated with Monte Carlo particle deposition, excluding shine-through power.

vay(minb,mibs)

Particle velocity magnitude.

xmuay(minb,mibs)

Particle magnetic moment, represented by:

v_perp² / B

2.2 Additional Stored Particle Properties

njavay(minb,mibs)

Orbit-averaged zone index.

cxpray(minb,mibs)

Charge-exchange frequency control parameter.

fppray(minb,mibs)

Fokker–Planck collision frequency control parameter.

goosay(minb,mibs)

Goose factor associated with the Monte Carlo particle.

nbndex(minb,mibs)

Particle storage indexing array.

nbscay(minb,mibs)

Beam source index.

rmjionay(minb,mibs)

Particle guiding-center major radius, R, from the previous step.

xzionay(minb,mibs)

Particle guiding-center vertical position, Z, from the previous step.

tdepay(minb,mibs)

Particle deposition time.

tfluxay(minb,mibs)

Magnetic flux-surface coordinate (Wb).

thay(minb,mibs)

Poloidal angle coordinate.

wghtay(minb,mibs)

Monte Carlo particle statistical weight.

xiay(minb,mibs)

Xi coordinate.

xistay(minb,mibs)

Deposited XIFLR or previous orbit-averaged ion Xi.

xksidy(minb,mibs)

Parallel velocity fraction:

V_parallel / V

xzbmay(minb,mibs)

Heavy-ion charge state.

3. Reconstructing particle phase space

3.1 Minimum Required Variables

The following five variables provide the minimum stored information needed to reconstruct particle positions, velocity magnitude, pitch, and statistical weights.

The parallel velocity is calculated as:

V_parallel = vay × xksidy

The perpendicular velocity magnitude is:

V_perp = vay × sqrt(1 − xksidy²)

For a particle of mass m, the kinetic energy is:

E = 0.5 × m × vay²

These quantities can be used to construct weighted fast-ion distributions in position, energy, and pitch coordinates.

For example:

f(R, Z, E, V_parallel/V)

Important: If multiple particle-state files exist for the requested time slice, all relevant files must be read to reconstruct the complete particle population.

3.2 Identifying Active Particles

Two special conditions must be considered when processing particle arrays.

Zero particle weight

wghtay = 0

This indicates that the particle was killed or is no longer tracked.

Such particles should generally be excluded when constructing the active fast-ion distribution.

Unused particle storage

rmjionay = 0 AND xzionay = 0

When both coordinates are zero, the particle storage slot has not yet been used.

These conditions distinguish active particles from inactive or uninitialized storage entries.

4. Identifying beam ions and fusion products

NUBEAM particle-state files may contain both neutral-beam-generated fast ions and fusion products.

Particle origin is determined using the array:

nlfprod(:)

This variable is stored in:

<RUNID>_debug_nbi_fld_state.cdf

Interpretation:

This information allows beam-ion and fusion-product populations to be separated during post-processing.

5. Particle species, mass, and charge

Particle species information is available from the plasma-state file:

<RUNID>_ps_ts1_state.cdf

5.1 Species Charge and Mass

The relevant variables are:

qatom_ALL

Atomic charge information for plasma species.

The atomic charge number is obtained as:

Z(j) = qatom_ALL(j) / ps_xe

m_ALL

Species mass in kilograms.

The species mass in proton-mass units is:

A(j) = m_ALL(j) / ps_mp

Constants:

ps_mp = 1.6726 × 10⁻²⁷ kg

Proton mass.

ps_xe = 1.6022 × 10⁻¹⁹ C

Elementary charge.

5.2 Species Mapping

To identify the plasma-state species corresponding to NUBEAM beam ions and fusion products, read the following mapping arrays:

snbi_to_all

sfus_to_all

These arrays are stored in the plasma-state file.

For example:

snbi_to_all = 5

sfus_to_all = 6, 7

The corresponding particle-file species indices are:

These mappings allow the appropriate mass and charge to be assigned to each particle species.

6. Generating NUBEAM particle-state files

NUBEAM particle-state files can be generated at selected simulation times using the namelist parameter:

FI_OUTTIM

For example:

FI_OUTTIM = 1.0, 2.0

This requests fast-ion working-state archives at simulation times 1.0 and 2.0 seconds.

The resulting archives are named:

<RUNID>_FI_TAR.GZ1

<RUNID>_FI_TAR.GZ2

...

These archives contain:

• NUBEAM state files.

• Monte Carlo particle lists.

• Internal fast-ion working-state information.

• Data required for debugging and post-processing.

6.1 Extracting Particle-State Archives

Use the NUBEAM utility:

fi_gzn_unpack <RUNID>_FI_TAR.GZ1

For example:

fi_gzn_unpack 123456A01_FI_TAR.GZ1

After extraction, the particle-state files are available for analysis.

Relevant particle-state files include:

*_nbi_ptcl_state_*.cdf

*_debug_nbi_ptcl_state_*.cdf

6.2 Particle-State File Creation Timing

The two particle-state file types correspond to different stages of the NUBEAM calculation.

Beginning of the NUBEAM call

*_debug_nbi_ptcl_state_*.cdf

This file contains particle-state information saved at the beginning of the NUBEAM call.

End of the NUBEAM call

*_nbi_ptcl_state_*.cdf

This file contains particle-state information saved at the end of the NUBEAM call.

This distinction is important when comparing particle populations before and after a NUBEAM time step.

7. Output timing and time averaging

7.1 OUTTIM

The namelist parameter OUTTIM specifies the times at which AC-file output is requested.

Example:

OUTTIM = 1.0, 2.0

Requirements:

• Values must be specified in ascending order.

• Up to 200 output times may be specified.

• All output times must lie within the simulation interval.

TINIT ≤ OUTTIM ≤ FTIME

The default value:

OUTTIM = 1.0D34

suppresses intermediate AC-file output.

7.2 FI_OUTTIM

The namelist parameter FI_OUTTIM specifies the times at which fast-ion working-state archives are generated.

Example:

FI_OUTTIM = 1.0, 2.0

Requirements:

• Values must be specified in ascending order.

• Up to 200 output times may be specified.

• All requested times must lie within the simulation interval.

TINIT ≤ FI_OUTTIM ≤ FTIME

7.3 Time Averaging of AC-File Quantities

When the namelist includes an averaging selection such as:

SELAVG = 'FBM ...'

the corresponding AC-file quantities are time-averaged over the interval specified by:

AVGTIM

Example:

AVGTIM = 0.02 sec

dtbeam = 0.001 sec

In this example, the averaging interval spans approximately 20 NUBEAM time steps.

7.4 Particle Lists Are Not Time-Averaged

The following files contain particle-state snapshots:

*_nbi_ptcl_state_*.cdf

*_debug_nbi_ptcl_state_*.cdf

These particle lists are not time-averaged.

The averaging applied to selected AC-file quantities through AVGTIM does not apply to the particle-state files.

This distinction is important when comparing reconstructed particle distributions with time-averaged AC-file diagnostics.

8. NUBEAM lost-particle output

NUBEAM provides lost-particle diagnostics that record information about Monte Carlo particles lost during orbit tracking.

These diagnostics can be used to investigate:

• Fast-ion confinement.

• Prompt particle losses.

• Finite Larmor radius losses.

• Collisional and anomalous transport losses.

• Magnetic ripple losses.

• Spatial and energy distributions of lost particles.

8.1 Required Namelist Configuration

To generate lost-particle output at selected times, define both:

OUTTIM = 1.0, 2.0

FI_OUTTIM = 1.0, 2.0

OUTTIM specifies diagnostic output times.

FI_OUTTIM requests archives containing the fast-ion working states.

8.2 NLBOUT_GATHER Option

The parameter NLBOUT_GATHER controls the time interval over which lost-particle information is collected.

Default:

NLBOUT_GATHER = .TRUE.

Case 1: NLBOUT_GATHER = .TRUE.

Lost-particle information is collected over multiple NUBEAM time steps within approximately:

OUTTIM − AVGTIM ≤ t ≤ OUTTIM

Data is stored for each time step within the collection interval.

This option provides a larger sample of lost particles and is useful for improving loss statistics.

Case 2: NLBOUT_GATHER = .FALSE.

Lost-particle information is collected over a single NUBEAM time interval:

tbm1 < OUTTIM < tbm2

In practice, the diagnostic contains losses from the last NUBEAM time step associated with the requested output time.

8.3 Lost-Particle Output Variables

8.4 Identifying Prompt Losses

The variable goose_lost can be used to identify prompt losses.

The criterion is:

goose_lost < 1.00001

Particles satisfying this condition are classified as prompt losses.

9. Lost-particle mechanisms

NUBEAM collects particle losses encountered during orbit tracking.

The included loss mechanisms are described below.

9.1 Geometric Orbit Losses

Particles are lost when their orbits cross prescribed coordinate limits or leave the fast-ion confinement region.

9.2 Finite Larmor Radius (FLR) Losses

Particles are lost when their Larmor radius becomes greater than or equal to the distance to the limiter.

9.3 Coulomb-Related Losses

Losses associated with collisional particle evolution, including cases where the finite Larmor radius reaches the limiter boundary.

9.4 Anomalous Diffusion Losses

Losses caused by anomalous fast-ion diffusion.

9.5 Ripple Losses

Losses associated with magnetic-field ripple.

9.6 Trapped-Orbit Losses

Particles are lost when their orbits become trapped outside the plasma confinement region.

The lost-particle diagnostics therefore include both prompt and nonprompt losses.

10. Improving lost-particle statistics

The statistical quality of lost-particle diagnostics depends on the number of Monte Carlo particles deposited and tracked.

To obtain more reliable prompt-loss statistics, increase the number of deposited Monte Carlo particles.

The number of particles deposited per time step is determined by:

max(1, min(nptcls, delt/tau_sl * frac_dep_lim * nptcls))

The parameter frac_dep_lim controls the deposition fraction.

Default:

frac_dep_lim = 1.5

Increasing the number of deposited particles can improve the statistical representation of prompt losses, particularly when the number of lost particles is small.

10.1 Boundary Parameter

The parameter:

XBMBND

specifies the Xi value at the bloated boundary.

Default:

XBMBND = 1.3

11. Recommended post-processing procedure

The following procedure can be used to reconstruct fast-ion distributions and analyze lost particles.

Step 1. Configure the output times

Set the namelist parameters:

OUTTIM = time1, time2, ...

FI_OUTTIM = time1, time2, ...

Specify the requested times in ascending order.

Step 2. Run TRANSP/NUBEAM

Confirm that the requested fast-ion archives have been generated.

Step 3. Extract the fast-ion archives

Use:

fi_gzn_unpack <RUNID>_FI_TAR.GZ1

Repeat for other archives as necessary.

Step 4. Read the particle-state arrays

Load the required particle properties:

rmjionay

xzionay

vay

xksidy

wghtay

Read all relevant particle files if multiple files exist.

Step 5. Identify active particles

Exclude unused particle storage slots and particles with zero statistical weight when constructing active-particle distributions.

Step 6. Determine particle species

Use the following arrays:

nlfprod

snbi_to_all

sfus_to_all

qatom_ALL

m_ALL

These variables allow beam ions and fusion products to be identified and assigned the appropriate masses and charges.

Step 7. Reconstruct the particle distribution

Calculate particle energies and velocity components.

Accumulate particles into the desired phase-space bins using their Monte Carlo statistical weights.

Step 8. Analyze lost particles

Use the lost-particle variables to determine:

• Particle loss locations.

• Energies at loss.

• Pitch coordinates at loss.

• Loss times.

• Particle statistical weights.

• Prompt-loss classification.

Step 9. Verify the collection interval

Read:

NSTEP_GTIME_lost

GTIME1_LOST

GTIME2_LOST

These variables identify the number of NUBEAM time steps and the time interval represented by the lost-particle diagnostic.

12. Summary

NUBEAM provides two complementary types of Monte Carlo particle information.

12.1 Particle-State Files

Particle-state files contain information about individual fast ions at selected stages of the NUBEAM calculation.

These files support:

• Reconstruction of fast-ion phase-space distributions.

• Restarting NUBEAM calculations.

• Debugging particle behavior.

• Analysis of fast-ion population evolution.

The minimum variables needed to reconstruct particle positions, velocity magnitude, pitch, and statistical weights are:

rmjionay, xzionay, vay, xksidy, wghtay

Particle-state files are not time-averaged.

12.2 Lost-Particle Diagnostics

Lost-particle diagnostics contain information about particles lost during orbit tracking.

The stored information includes:

• Particle loss time.

• Position at loss.

• Energy at loss.

• Pitch coordinate.

• Statistical weight.

• Particle species.

• Goose factor.

The diagnostics include prompt, finite Larmor radius, Coulomb-related, anomalous diffusion, ripple, and geometric orbit losses.

The parameter NLBOUT_GATHER controls whether lost particles are collected over multiple time steps or a single NUBEAM time interval.

12.3 Comparison of Particle-State and Lost-Particle Outputs

Together, NUBEAM particle-state files and lost-particle diagnostics provide the information needed for detailed analysis of fast-ion phase-space distributions, particle confinement, and loss mechanisms in TRANSP/NUBEAM.

Document based on the supplied NUBEAM variable descriptions and namelist information. Variable definitions and output behavior have not been independently verified against the current NUBEAM source code.