MCNP-GO: Python Tool for MCNP File Assembly

• MCNP-GO is a Python package that decomposes MCNP models into reusable objects, enabling precise assembly via geometric transformations and renumbering.
• It employs a modular design with core modules for parsing, renumbering, collision detection, material merging, and metadata tracking to ensure configuration management.
• The tool supports complex applications such as tomographic experiments by automating object insertion, collision handling, and traceability with embedded JSON metadata.

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 (Friou, 7 Jul 2025). 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 (Friou, 7 Jul 2025).

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 (Friou, 7 Jul 2025).

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 (Friou, 7 Jul 2025). 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 (Friou, 7 Jul 2025).

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 (Friou, 7 Jul 2025). 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 (Friou, 7 Jul 2025). 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 $$T_{\text{net(surf)}} = M_{\text{in}}^T \cdot T_{\text{old(surf)}} + T_{\text{in}}$$0 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 (Friou, 7 Jul 2025). 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.