---
title: 'MCNP-GO: Python Tool for MCNP File Assembly'
url: https://www.emergentmind.com/topics/mcnp-go
type: topic
---

# MCNP-GO: Python Tool for MCNP File Assembly

Searching arXiv for the specified paper and closely related context.
MCNP-GO is a Python package for manipulating and assembling MCNP input files by treating each component as an independent object described by a valid MCNP file and combining such objects into a single cohesive file [2507.05659]. It is presented as a systems engineering approach to MCNP model construction, particularly for applications in which precise modeling and positioning of equipment are crucial. The package is intended to address the management of large databases of MCNP input files, with explicit emphasis on reliability, traceability, configuration management, collision handling, and material consistency, while remaining usable for practitioners with minimal Python knowledge.

## 1. Definition, scope, and modeling philosophy

MCNP-GO is organized around the idea that an MCNP model can be decomposed into reusable, independently valid object files and later reassembled programmatically. In that formulation, a room, detector, sample, CCD, or other subsystem is represented by its own MCNP deck, and assembly is performed by loading these decks as objects, transforming them geometrically, renumbering their identifiers, and merging them into one final input file [2507.05659].

This object-based perspective is coupled to a systems engineering orientation. The package is explicitly described as addressing the challenges of managing large databases of MCNP input files and ensuring reliability and traceability through configuration management systems. A common misconception is to regard MCNP-GO as a general-purpose geometry editor. The paper instead defines it more narrowly and more concretely: it manipulates existing MCNP decks, assembles them, tracks operations performed on them, and preserves provenance through headers and metadata rather than replacing MCNP’s native constructive solid geometry formalism.

The intended use case is not limited to small examples. The abstract and worked example center on applications where equipment positioning matters operationally, culminating in a tomographic experiment assembled from multiple pre-existing MCNP objects. This suggests that MCNP-GO is most naturally situated between model libraries and experiment-specific assembly scripts rather than as a standalone monolithic preprocessor.

## 2. Internal organization and data model

The software is centered on an `MCNPFile` object implemented as the class `go`, with six core functional modules: Parser & Object Manager, Renumbering Module, Transformation Module, Collision & Assembly Module, Material Manager, and Traceability & Metadata Module [2507.05659].

| Module | Function |
|---|---|
| Parser & Object Manager | Reads an MCNP deck, splits it into card-blocks, builds internal representations |
| Renumbering Module | Reassigns unique IDs to cells, surfaces, and transformations |
| Transformation Module | Applies affine transforms via MCNP transform cards |
| Collision & Assembly Module | Inserts objects and manages collisions |
| Material Manager | Merges material cards and reuses identical compositions |
| Traceability & Metadata Module | Logs inserted files and stores embedded JSON metadata |

The Parser & Object Manager reads an existing MCNP deck and splits it into card-blocks corresponding to cells, surfaces, transforms, materials, data cards, and footer. It then builds internal representations of each card type using dictionaries and lists. This decomposition is structurally important because later operations—such as extraction, renumbering, transformation, and reassembly—act on typed subsets of the input rather than on an undifferentiated text file.

The Renumbering Module reassigns unique IDs to cells, surfaces, and transformations to avoid conflicts during merges. The paper highlights a specific MCNP constraint enforced by the module: no `TRCL` on IDs greater than `999`. This is complemented by a dedicated `ResolveTRCL()` method, which renumbers cells and surfaces so that no transform references an ID above that threshold.

The Traceability & Metadata Module maintains a recursive header log of every inserted file, its filepath, and the transforms applied to it, including Euler angles, matrices, and translation vectors. It also supports an embedded JSON section after the MCNP data block for user metadata such as groups of cell, surface, and transform IDs or point-detector positions. In effect, the package treats provenance and annotation as part of the model artifact rather than as external documentation.

## 3. Geometric transformation, renumbering, and assembly semantics

Geometric manipulation in MCNP-GO is handled through MCNP transform cards. The Transformation Module applies affine transforms—translations and rotations—to surfaces or cells and exposes convenience methods `TrRotX`, `TrRotY`, `TrRotZ`, `TrRotU`, as well as a generic `Transform(card-list)` interface [2507.05659]. The update rules are given explicitly.

For surface transform cards, the net transform is

$$
M_{\text{net(surf)}} = M_{\text{old(surf)}} \cdot M_{\text{in}}
$$

$$
T_{\text{net(surf)}} = M_{\text{in}}^T \cdot T_{\text{old(surf)}} + T_{\text{in}}
$$

For cell (`TRCL`/`fill`) cards, the net transform is

$$
M_{\text{net(cell)}} = M_{\text{in}}^T \cdot M_{\text{old(cell)}} \cdot M_{\text{in}}
$$

$$
T_{\text{net(cell)}} = M_{\text{in}}^T \cdot T_{\text{old(cell)}} - M_{\text{net(cell)}}^T \cdot T_{\text{in}} + T_{\text{in}}
$$

where \( M \) and \( T \) are rotation matrices and translation vectors. The worked example also presents the surface-update relation in the equivalent notation

$$
M_{\rm new} = M_{\rm old}\,M_{\rm in}, \quad
T_{\rm new} = M_{\rm in}^T\,T_{\rm old} + T_{\rm in}.
$$

Assembly is performed in two distinct modes. `Insert` uses a bounding-surface copy strategy, adding the inserted object’s bounding surface to the host’s gas and graveyard cells. `InsertCells` uses the MCNP exclusion operator `#`, removing the inserted cells from the host’s gas cell. During insertion, renumbering and material merging are automatic. Collisions are detected by checking overlapping bounding surfaces or Boolean exclusion [2507.05659].

Material reconciliation is not left implicit. The Material Manager merges material cards by reusing existing material numbers when compositions are identical in library, nuclide fractions, and `mp`, `mx`, and `mt` flags; otherwise, new materials are appended and renumbered if needed. A common misunderstanding is that insertion merely concatenates geometry. In MCNP-GO, insertion also carries semantics for collision handling, identifier management, and material equivalence.

## 4. Python API and canonical workflow

All functionality is exposed through the top-level class `go` in `mcnpgo/mcnpgo.py` [2507.05659]. The constructor `go(filepath: str)` loads and parses an existing `.mcnp` file. The principal methods are:

- `Renum(cell: int=1, surf: int=100, trans: int=1000) -> None`
- `Extract(cells: Iterable[int]) -> go`
- `Insert(other: go, location: str = "auto") -> None`
- `InsertCells(other: go) -> None`
- `ResolveTRCL() -> None`
- `Transform(card: List[Union[int,float,str]]) -> None`
- `TrRotX(trans: List[float], angle: float) -> None`
- `TrRotY(trans: List[float], angle: float) -> None`
- `TrRotZ(trans: List[float], angle: float) -> None`
- `TrRotU(trans: List[float], angle: float, axis: List[float]) -> None`
- `GetTr() -> List[Dict]`
- `FindTrCard(tr_id: int) -> Dict`
- `GetGroup(name: str, key: str) -> List[Union[int,str]]`
- `AddMCNPCard(card: List[str]) -> None`
- `WriteMCNPFile(filepath: str) -> None`

The minimal workflow in the paper proceeds by importing pre-existing MCNP files as independent objects, renumbering cells, surfaces, and transforms for readability and uniqueness, applying geometric transforms, assembling the objects, resolving any `TRCL` issues, and writing the final deck. A representative sequence is: instantiate `room = go("room.mcnp")`, `detector = go("detector.mcnp")`, and `sample = go("lattice_sample.mcnp")`; call `room.Renum(cell=1, surf=100, trans=2000)` and `detector.Renum(cell=1000, surf=2000, trans=3000)`; apply `detector.TrRotZ(trans=[0,400,0], angle=5.0)`; then perform `room.Insert(detector, location="inside")`, `sample.TrRotX(trans=[0,300,0], angle=0.0)`, `room.Insert(sample, location="inside")`, and `room.ResolveTRCL()`.

The API also exposes metadata-aware queries. `GetGroup(name, key)` retrieves entries from the embedded JSON metadata, including fields such as `"cell"`, `"surf"`, `"trans"`, `"position"`, and `"comment"`. `FindTrCard(tr_id)` returns a transform-card dictionary with keys `"id"`, `"rot"`, and `"trans"`. The worked example uses these methods to reconstruct the final position of a detector component from its original stored position and its accumulated transform card. This makes metadata operational rather than merely descriptive.

## 5. Tomographic experiment example

The paper demonstrates MCNP-GO by constructing a tomographic setup in four steps [2507.05659]. The first step places a CCD inside a detector bench by loading `ccd = go("ccd.mcnp")`, applying `detector.TrRotX(trans=[60,50,0], angle=0.0)`, and calling `detector.Insert(ccd, location="inside")`.

The second step tilts the detector bench by \(1^\circ\) about \(Y\) and shifts it by \((0,400,0)\) using `detector.TrRotY(trans=[0,400,0], angle=1.0)`, after which the detector is inserted into the room with `room.Insert(detector, location="inside")`.

The third step loops over object rotation angles `angles = [0, 30, 45, 90]`. A lattice object `lat = go("lat_ex5.mcnp")` is deep-copied together with the room model, then transformed with `lat_cpy.TrRotZ(trans=[0,300,0], angle=θ)`, inserted into the copied room, passed through `ResolveTRCL()`, and written out as `tomograph_{θ}.mcnp`. The paper’s resulting-deck excerpt for \(\theta = 45^\circ\) lists the original file `./room.mcnp`, inserted files `./detector.mcnp`, `./ccd.mcnp`, and `./lat_ex5.mcnp`, along with transform descriptors such as `Y1°`, `Z=45°`, translation vectors, and a matrix entry in the header.

The excerpted assembled deck further contains a concrete wall cell, a gas cell with bounding-surface additions for the `lat_ex5` envelope, a graveyard cell excluding that envelope, surface cards, transform cards, material cards, data cards, and a JSON metadata block of groups and transforms. The example is significant because it demonstrates not merely file concatenation but parameterized experiment generation: a single scripted workflow emits a family of MCNP decks corresponding to multiple tomographic angles.

## 6. Installation, traceability practice, and extension points

The package requires Python `>= 3.7`, is tested on `3.8` and `3.9`, and depends on `numpy >= 1.16` and the built-in `json` module [2507.05659]. Installation can proceed by cloning the repository with `git clone https://github.com/afriou/mcnpgo.git`, changing into the directory and running `pip install .`, or simply copying the `mcnpgo` folder into `PYTHONPATH`. The implementation has no compiled extensions and is described as pure Python.

The paper recommends version-controlling the object database with Git or SVN so that the header trace can identify exactly which commit or file was used. It also recommends enforcing the rule that the gas cell is the second-last cell and the graveyard is the last cell in every object deck so that `Insert()` works without manual edits. For automated tallies, point-detector or source positions can be stored in the JSON footer.

For very large or high-fidelity CAD-converted geometries, the paper advises splitting void regions into multiple gas cells rather than relying on a giant single cell, and it suggests writing a custom `InsertVoid` algorithm, with `GEOUNED_void` named as a reference point. Proposed extension paths include alternative collision-detection strategies such as `MontePy neighbor-search`, support for vertical MCNP format or multi-universe `fill` constructs, and a higher-level GUI or DSL capable of emitting the Python assembly script automatically from CAD or CSV references.

These recommendations clarify the package’s operational boundaries. MCNP-GO already supports renumbering, extraction, transformation, assembly, material merging, recursive provenance logging, and JSON metadata embedding; proposed additions concern broader geometry classes, alternative collision logic, and higher-level front ends rather than changes to the core object-assembly model.

Source: https://www.emergentmind.com/topics/mcnp-go