Unlocking Advanced Simulations: A Comprehensive Guide to User-Defined Subroutines in MCNP/MCNPX

Unlocking Advanced Simulations: A Comprehensive Guide to User-Defined Subroutines in MCNP/MCNPX

Author: Partoyar Academy Research Team
Publication Date: October 26, 2023
Category: Advanced Monte Carlo Methods, Nuclear Engineering

Abstract

While the standard capabilities of MCNP and MCNPX are powerful enough for a vast range of problems, their true potential is unlocked through user-defined subroutines. These Fortran-based hooks allow experienced users to tailor the code to highly specific and complex scenarios that are impossible to model with standard input decks alone. This article provides a comprehensive overview of the complete ecosystem of user-expandable subroutines, detailing their functions, applications, and practical implementation guidelines. By mastering these tools, researchers and engineers can push the boundaries of their simulation projects, from custom source geometries to sophisticated variance-reduction techniques and bespoke tallies.

1. Introduction: Beyond the Standard Input Deck

MCNP (Monte Carlo N-Particle) and its extended version, MCNP(X), are the gold standards in particle transport simulation. Users typically define their problems—geometry, materials, source, and tallies—via a text-based input file. However, what happens when you need a source that isn't a simple point or disk? Or when you need to calculate a dose response function that isn't in the library? This is where user-defined subroutines come into play.

These subroutines are essentially "plug-in" points within the MCNP code where the user can inject custom Fortran logic. They provide direct access to particle data during the simulation lifecycle, enabling unparalleled control over the calculation process. This guide serves as a definitive reference for these powerful features.

2. The Complete Taxonomy of User Subroutines

We can categorize the subroutines based on their point of intervention in the particle's history.

2.1. Tallies and Scoring: Customizing What You Measure

• TALLYX (Custom Tallies): This is the most flexible tally subroutine. It allows you to define a scoring function from scratch.

  • Syntax: SUBROUTINE TALLYX(n, x, k, result)

  • Application: Ideal for creating complex, energy-dependent responses or combining multiple physical quantities in a single tally. For example, scoring a detector signal that depends non-linearly on energy and particle type.

• USERD (Custom Dose Calculation): Specifically designed for radiological protection studies.

  • Syntax: SUBROUTINE USERD(erg, fl, dose)

  • Application: Implementing fluence-to-dose conversion coefficients from publications like ICRP reports that are not natively available in MCNP.

2.2. Particle Source: Defining the Origin

• SOURCE (Custom Source Definition): The primary subroutine for defining a complex source geometry and energy spectrum.

  • Syntax: SUBROUTINE SOURCE(erg, x, y, z, u, v, w, time, iwt, nc, nr)

  • Application: Modeling anisotropic sources, spatially distributed sources (e.g., a source on a spherical surface or along a line), or complex energy distributions (e.g., a spectrum from a file).

• SRCDX (Advanced Source): An extended version of SOURCE offering more parameters and control, typically used for even more sophisticated source definitions.

2.3. Variance Reduction: Boosting Computational Efficiency

• USERWEI (Custom Weight Window): Dynamically alters the weight of particles during their travel to optimize the figure of merit (minimize variance for a given computation time).

  • Syntax: SUBROUTINE USERWEI(x, y, z, u, v, w, erg, wt, ipt, newwt)

  • Application: Increasing particle weight in regions of importance (e.g., deep inside a shield) and decreasing it in less important regions, dramatically improving the efficiency of deep-penetration problems.

• WWDX (Advanced Weight Management): Provides finer control over the weight-window generator.

2.4. Particle Tracking: Intervening During Transport

• USRTRK (Custom Particle Tracking): Called during the tracking of a particle. Allows the user to apply conditions or log data at every step.

  • Application: "Tagging" particles that originate from a specific region, applying special physics in a user-defined zone, or creating a custom particle history log.

• TRACKX (Advanced Tracking Control): Offers lower-level access to the tracking algorithm.

2.5. Materials and Cross-Sections: Defining the Interaction Environment

• USERMAT (Custom Material Properties): Allows the definition of material properties beyond the standard library.

• MICROX (Custom Microscopic Cross-Sections): The most advanced hook, enabling the user to provide a complete set of microscopic cross-sections for a nuclide, bypassing the MCNP library entirely. Essential for simulating hypothetical materials or testing new nuclear data.

2.6. Geometry: Creating Complex Surfaces

• USRSFC (Custom Geometric Surfaces): Allows the definition of algebraic or algorithmic surfaces not natively supported by MCNP's surface cards (e.g., a torus with an elliptical cross-section).

2.7. Output and Control

• USROUT/OTPUTX (Custom Output): Controls the formatting and content of the output file.

• USRTIM (Time-Dependent Calculations): For simulations where the system evolves over time.

• USRCUT (Custom Cutoff Conditions): Defines custom rules for terminating particle histories based on energy, weight, or other parameters.

• USERERG (Custom Energy Grouping): Defines a custom energy bin structure for tallies.

3. The Foundation: Essential COMMON Blocks

To access simulation data within your subroutines, MCNP uses Fortran COMMON blocks. These are shared memory spaces where the code stores critical variables.

Example: To get the current particle's energy inside TALLYX, you would declare and use the TRACK common block:

COMMON /TRACK/ erg, xpos, ypos, zpos, u, v, w, wt
REAL erg, xpos, ypos, zpos
! ... then use 'erg' in your calculation.

4. Practical Examples: From Theory to Practice

Example 1: Creating an Annular Neutron Source with SOURCE
This subroutine samples particle starting positions uniformly on an annulus (ring) between radii R1 and R2.

SUBROUTINE SOURCE(erg, x, y, z, u, v, w, time, iwt, nc, nr)
IMPLICIT NONE
REAL erg, x, y, z, u, v, w, time, iwt
INTEGER nc, nr
REAL r1, r2, theta, rad, pi
pi = 3.14159265359
CALL RANDOM_NUMBER(r1)
CALL RANDOM_NUMBER(r2)

! Sample radius^2 uniformly between R1^2 and R2^2
rad = SQRT( (0.5**2) + r1 * ( (2.0**2) - (0.5**2) ) )
theta = 2 * pi * r2

! Set position on the annulus in the Z=0 plane
x = rad * COS(theta)
y = rad * SIN(theta)
z = 0.0

! Set energy to a fission spectrum (mean ~2 MeV)
erg = -LOG(r1) * 2.0
iwt = 1.0 ! Particle weight

RETURN
END

Example 2: Implementing a Spatial Weight Window with USERWEI
This routine increases particle weight by a factor of 3 when they enter a sensitive detector region (a sphere of radius 10 cm centered at (0,0,50)), encouraging more particles to contribute to the tally in this crucial area.

SUBROUTINE USERWEI(x, y, z, u, v, w, erg, wt, ipt, newwt)
IMPLICIT NONE
REAL x, y, z, u, v, w, erg, wt, newwt
INTEGER ipt
REAL dist_to_center

dist_to_center = SQRT(x**2 + y**2 + (z-50.0)**2)

IF (dist_to_center < 10.0) THEN
    newwt = wt / 3.0 ! Russian Roulette will kill low-weight particles, survivors have higher weight.
ELSE
    newwt = wt * 1.0 ! Keep weight unchanged elsewhere.
ENDIF

RETURN
END

5. Best Practices for Development and Debugging

1. Start Simple: Begin with a "hello world" subroutine, like a SOURCE that simply writes particle coordinates to a file, to verify your compilation chain works.

2. Use IMPLICIT NONE: This Fortran directive is non-optional. It forces you to declare all variables, preventing subtle bugs from typos.

3. Debug with File I/O: Since you cannot use a debugger easily with MCNP, use OPEN, WRITE, and CLOSE statements to log variable values to an external file. Remember to remove these statements in production runs as they are very slow.

4. Compile Correctly: Compile your subroutine and link it with the MCNP executable.

   bash

   mcnpx inp=my_model.i subroutine.f

5. Validate Incrementally: Test your custom subroutine with a very simple model (e.g., a homogenous sphere) and a small number of particles (nps=1000) before scaling up to your full, complex geometry.

6. Conclusion

User-defined subroutines transform MCNP/MCNPX from a powerful but fixed tool into a customizable simulation platform. They empower users to tackle frontier problems in reactor design, radiation shielding, detector development, and medical physics. While there is a learning curve associated with their use, the investment pays substantial dividends in the form of solved problems that would otherwise be intractable.

At Partoyar Academy, we encourage our advanced students to experiment with these subroutines in guided projects, building the expertise necessary to become true Monte Carlo experts.

Further Reading:

• *MCNP User's Manual, Volume 2: User-Defined Features*

• *LA-UR-02-XXXX (The MCNPX Manual)*

• Briesmeister, J. F. (Ed.). (2000). MCNP—A General Monte Carlo N-Particle Transport Code.

For hands-on workshops and advanced courses on MCNP and reactor physics, visit the Partoyar Academy learning portal.