A Comprehensive Guide to the PTRAC Card in MCNP(X)

A Guide to the MCNPX PTRAC Card for Particle Track Output

Introduction

In Monte Carlo radiation transport codes like MCNPX, understanding the detailed behavior of individual particles is crucial for debugging complex models, analyzing specific events, and visualizing particle paths. The PTRAC (Particle Track) card is a powerful and optional feature in MCNPX that enables users to record a detailed history of particle events based on highly customizable filters. Instead of relying solely on integrated tallies, PTRAC provides a discrete, event-by-event account of a particle's journey, offering unparalleled insight into the simulation's inner workings. This article explores the functionality, keywords, and practical application of the PTRAC card.

PTRAC Overview and Default Behavior

The primary function of the PTRAC card is to generate an output file (default name PTRAC) containing user-filtered particle events. If the card is used without any keywords, MCNPX will write all events for all particle histories to the PTRAC file. While this provides complete information, it almost invariably results in an extremely large file, making it impractical for all but the smallest simulations. Therefore, the judicious use of filtering keywords is essential to manage output size and focus on relevant data.

The PTRAC keywords are logically grouped into three categories:

1. Output-Control Keywords: Manage the file format, size, and I/O operations.

2. Event-Filter Keywords: Select which specific types of events to record for a particle's history.

3. History-Filter Keywords: Determine for which particle histories the events should be recorded.

These keywords can be entered on the PTRAC card in any order.

Output-Control Keywords

These keywords govern the physical characteristics of the output file.

• BUFFER: Controls the amount of memory allocated for storing filtered events before writing to disk. A small value increases I/O operations but reduces memory usage, while a large value minimizes I/O at the cost of higher memory requirements. (Default: BUFFER=100).

• FILE (FTLE): Specifies the file type.

  • FILE=BIN: Generates a binary file (Default).

  • FILE=ASC: Generates an ASCII file.

  • FILE=BOV/FILE=AOV: Used for writing to a named pipe on UNIX systems by overwriting an existing file.

• MAX: Sets the maximum number of events written to the PTRAC file. If MAX is set to a negative value, MCNPX will terminate once the absolute value of events has been written. (Default: MAX=10000).

• MEPH: Sets the maximum number of events recorded per history. (Default: write all events for a history).

• WRITE: Controls the level of detail for each recorded event.

  • WRITE=POS: Records only the particle's position (x, y, z) and associated cell and material numbers (Default).

  • WRITE=ALL: Records position, direction cosines (u, v, w), energy, weight, and time.

Event-Filter Keywords

These keywords filter events on a per-event basis. If a history meets the overall criteria, only the event types specified here are written to the file.

• EVENT: Specifies the type of events to record. Multiple mnemonics can be used.

  • SRC: Initial source events.

  • BNK: Bank events (secondary sources, e.g., photons from neutrons).

  • SUR: Surface crossing events.

  • COL: Collision events.

  • TER: Termination events.

  • CAP: Coincident capture events (Default: all events are written).

  • Note: EVENT=CAP uses a specialized, high-speed output format that differs significantly from the standard PTRAC data, recording only history number, capture time, and cell number.

• FILTER: Provides advanced filtering based on MCNPX internal variables. It uses mnemonics corresponding to variables in the PBLCOM common block (see Table 1). A filter can specify an exact value or a range.

  • Example: FILTER=2, ICL writes events occurring only in cell 2.

  • Example: FILTER=0,10,X writes events where the particle's x-coordinate is between 0 and 10 cm.

  • Example: FILTER=0.0,10.0,X 0,1,U 1.0,2,ERG combines filters for position, direction, and energy.

• TYPE: Filters events based on particle type (e.g., neutron, photon, electron) using the particle identifiers from Table 4-1. (Default: writes events for all particles).

Table 1: Selected Mnemonics for the FILTER Keyword

History-Filter Keywords

These keywords determine which entire particle histories are eligible to have their events written to the PTRAC file. If any track in a history meets the filter criteria, all filtered events for that entire history are recorded.

• NPS: Sets a range of history numbers to output. (Default: all histories).

• CELL: A list of cell numbers. If a particle enters any cell on the list, the entire history is recorded.

• SURFACE: A list of surface numbers. If a particle crosses any surface on the list, the entire history is recorded.

• TALLY & VALUE: A powerful pair of keywords that record histories based on their contribution to a specific tally.

  • TALLY lists the tally numbers, and VALUE specifies the cutoff value.

  • Example: TALLY=4 VALUE=2.0 writes events for any history that contributes 2.0 or more to the TFC bin of tally 4.

  • A negative tally number (e.g., TALLY=-4) uses a multiplier of the average tally value rather than an absolute cutoff.

Practical Example

Consider the following PTRAC card entry:

PTRAC FILTER=8,9,ERG EVENT=SUR NPS=1,50 TYPE=E CELL=3,4

This line applies a logical AND to all filter criteria. It will write to the PTRAC file only surface crossing events (EVENT=SUR) for electrons (TYPE=E) with energies between 8 and 9 MeV (FILTER=8,9,ERG) that were generated within the first 50 histories (NPS=1,50) and where the particle has entered either cell 3 or 4 (CELL=3,4). This highly specific filtering ensures the output file contains only the most relevant data.

Important Considerations

• The PTRAC card is not permitted in a continue-run input file.

• The PTRAC file includes heavy ion particles but does not record their individual identities (ZZZAAAs).

• When multiple keywords are used, all filter criteria must be satisfied for an event to be written.

Conclusion

The PTRAC card is an indispensable tool for advanced MCNPX users requiring detailed particle-level data. By effectively leveraging its three categories of keywords—output control, event filtering, and history filtering—users can efficiently generate manageable and highly targeted output files for debugging, analysis, and visualization, thereby extracting maximum value from their Monte Carlo simulations.