MCPL converters for MCNP
- Quick and dirty way to get ssw2mcpl and mcpl2ssw
The MCNP–MCPL interface currently supports MCNPX, MCNP5 and MCNP6 and exploits the existing MCNP capability to stop and subsequently restart simulations at a user-defined set of surfaces through the Surface Source
Write/Read (SSW/SSR) functionality, based on intermediate files. We refer to such files as “SSW files”, although different names are occasionally used (e.g. “RSSA files”). The MCNP-MCPL interface is thus implemented as two standalone commandline converters:
mcpl2ssw. A detailed description of the commands, as well as references to the relevant MCNP manuals in which it is described how to enable the SSW functionality in a given MCNP input deck, is given in the MCPL paper (section 3.2) and the present page will merely provide a few typical usage examples.
At the bottom of the page is also included a quick and dirty recipe for how the
mcpl2ssw commands can be obtained without first downloading and installing the MCPL distribution. Note that users of the ESS dgcode framework already have access to the commands, and it is planned to provide McStas and McXtrace users with them as well
(cf. this issue).
A few exampes and instructions of how to use
mcpl2ssw are provided in the following.
Converting an SSW file to MCPL
Simply providing the
ssw2mcpl command with the name of an existing SSW file and the desired name of the MCPL file to be created, is enough to trigger the conversion:
ssw2mcpl sswfile.w newfile.mcpl
ssw_open_file: Opened file "sswfile.w": ssw_open_file: File layout detected : MCNPX ssw_open_file: Code ID fields : "mcnpx" / "2.7.0" ssw_open_file: Title field : "Example to write mcpl from mcnp5,mcnp6 and mcnpx" ssw_open_file: Source statistics (histories): 1000 ssw_open_file: Particles in file : 2000 ssw_open_file: Number of surfaces : 2 ssw_open_file: Histories at surfaces : 1000 MCPL: Attempting to compress file newfile.mcpl with gzip MCPL: Succesfully compressed file into newfile.mcpl.gz Created newfile.mcpl.gz
However, it is possible to add more than the minimal amount of information into the output file. First of all, the
-d flag can be used to enable double-precision rather than single-precision storage of floating point numbers. Next, the
-s flag will cause the MCNP surface ID’s to be embedded in the MCPL userflags fields, and finally specifying
-c <path_to_input_deck> will cause the MCNP input deck used to generate the SSW file in question to be embedded into the MCPL header (can later be retrieved with
mcpltool -bmcnp_input_deck newfile.mcpl). In particular, it is highly recommended to embed the input_deck with
-c for later reference, and the
-s might be essential if the file is intended to be converted back for usage in an MCNP simulation with compatible surface ID’s. Thus, enabling as much information as possible in the MCPL file would happen with:
ssw2mcpl -d -s -c input_deck sswfile.w newfile.mcpl
Inspecting the resulting newfile.mcpl with
mcpltool might give an output like this (admittedly the SSW file was not from a very interesting simulation):
Opened MCPL file newfile.mcpl.gz: Basic info Format : MCPL-3 No. of particles : 2000 Header storage : 1077 bytes Data storage : 144000 bytes Custom meta data Source : "MCNPX" Number of comments : 3 -> comment 0 : "SSW file from MCNPX converted with ssw2mcpl (from MCPL release v1.1.0)" -> comment 1 : "SSW metadata: [kods='mcnpx', vers='2.7.0', title='Example to write mcpl from mcnp5,mcnp6 and mcnpx']" -> comment 2 : "The userflags in this file are the surface IDs found in the SSW file" Number of blobs : 1 -> 747 bytes of data with key "mcnp_input_deck" Particle data format User flags : yes Polarisation info : no Fixed part. type : no Fixed part. weight : no FP precision : double Endianness : little Storage : 72 bytes/particle index pdgcode ekin[MeV] x[cm] y[cm] z[cm] ux uy uz time[ms] weight userflags 0 2112 250 1050 0 0 1 0 0 5.7379e-05 1 0x00000004 1 2112 250 1500 0 0 1 0 0 8.1853e-05 1 0x00000005 2 2112 250 1050 0 0 1 0 0 5.7379e-05 1 0x00000004 3 2112 250 1500 0 0 1 0 0 8.1853e-05 1 0x00000005 4 2112 250 1050 0 0 1 0 0 5.7379e-05 1 0x00000004 5 2112 250 1500 0 0 1 0 0 8.1853e-05 1 0x00000005 6 2112 250 1050 0 0 1 0 0 5.7379e-05 1 0x00000004 7 2112 250 1500 0 0 1 0 0 8.1853e-05 1 0x00000005 8 2112 250 1050 0 0 1 0 0 5.7379e-05 1 0x00000004 9 2112 250 1500 0 0 1 0 0 8.1853e-05 1 0x00000005
Converting an MCPL file to SSW
Usage of the
mcpl2ssw command to convert an MCPL file into the SSW format is slightly more involved than the reverse conversion: in addition to an input MCPL file, the user must also supply a reference
SSW file in a format suitable for the MCNP setup in which the
resulting SSW file is subsequently intended to be used as input. This added complexity is necessary since different MCNP flavours have different SSW format, but also because the SSW file actually contains details about the simulation geometry used in a particular setup. It doesn’t matter how many particles are stored in the reference SSW file, it can in principle be very small. Additionally,
mcpl2ssw needs to assign MCNP surface ID’s to all particles. This can be set globally with the
-s flag, or else
mcpl2ssw will try to use the contents of the MCPL userflags field as the surface ID’s.
Assuming refsswfile.w is an SSW file in a format compatible with the target setup, the MCPL file myfile.mcpl.gz can be converted into a compatible SSW file, newfile.w, with the following command:
mcpl2ssw myfile.mcpl.gz refsswfile.w newfile.w
Opened MCPL file produced with "MCNPX" (contains 2000 particles) Opening reference SSW file: ssw_open_file: Opened file "refsswfile.w": ssw_open_file: File layout detected : MCNP6 ssw_open_file: Code ID fields : "mcnp" / "6" ssw_open_file: Title field : "Example to write mcpl from mcnp5,mcnp6 and mcnpx" ssw_open_file: Source statistics (histories): 1000 ssw_open_file: Particles in file : 2000 ssw_open_file: Number of surfaces : 2 ssw_open_file: Histories at surfaces : 1000 Creating (or overwriting) output SSW file. Initiating particle conversion loop. Ending particle conversion loop. Created newfile.w with 2000 particles (nrss) and 2000 histories (np1).
Note that here refsswfile.w is associated with MCNP6 while myfile.mcpl.gz was created with ssw2mcpl from an MCNPX file, but of course MCPL files from non-MCNP simulations can be used as well - assuming the surface ID’s can be specified globally or in the userflags field. The reason the above example worked was that myfile.mcpl.gz had been created from with the
-s flag to
ssw2mcpl (the user should of course make sure that the surface ID’s in the two setups were compatible).
Here is another example, in which the MCPL file originates in a Geant4 simulation, and the surface ID is set globally to 4 (again, it is the users responsibility that this makes sense):
mcpl2ssw -s4 g4output.mcpl refsswfile.w newfile.w
Opened MCPL file produced with "G4MCPLWriter [G4MCPLWriter]" (contains 1006 particles) Opening reference SSW file: ssw_open_file: Opened file "refsswfile.w": ssw_open_file: File layout detected : MCNP6 ssw_open_file: Code ID fields : "mcnp" / "6" ssw_open_file: Title field : "Example to write mcpl from mcnp5,mcnp6 and mcnpx" ssw_open_file: Source statistics (histories): 1000 ssw_open_file: Particles in file : 2000 ssw_open_file: Number of surfaces : 2 ssw_open_file: Histories at surfaces : 1000 Creating (or overwriting) output SSW file. Initiating particle conversion loop. Ending particle conversion loop. Created newfile.w with 1006 particles (nrss) and 1006 histories (np1).
Get full usage instructions
Full usage instructions are obtainable with the
Usage: ssw2mcpl [options] input.ssw [output.mcpl] Converts the Monte Carlo particles in the input.ssw file (MCNP Surface Source Write format) to MCPL format and stores in the designated output file (defaults to "output.mcpl"). Options: -h, --help : Show this usage information. -d, --double : Enable double-precision storage of floating point values. -s, --surf : Store SSW surface IDs in the MCPL userflags. -n, --nogzip : Do not attempt to gzip output file. -c FILE : Embed entire configuration FILE (the input deck) used to produce input.ssw in the MCPL header.
Usage: mcpl2ssw [options] <input.mcpl> <reference.ssw> [output.ssw] Converts the Monte Carlo particles in the input MCPL file to SSW format (MCNP Surface Source Write) and stores the result in the designated output file (defaults to "output.ssw"). In order to do so and get the details of the SSW format correct, the user must also provide a reference SSW file from the same approximate setup (MCNP version, input deck...) where the new SSW file is to be used. The reference SSW file can of course be very small, as only the file header is important (the new file essentially gets a copy of the header found in the reference file, except for certain fields related to number of particles whose values are changed). Finally, one must pay attention to the Surface ID assigned to the particles in the resulting SSW file: Either the user specifies a global one with -s<ID>, or it is assumed that the MCPL userflags field in the input file is actually intended to become the Surface ID. Note that not all MCPL files have userflag fields and that valid Surface IDs are integers in the range 1-999999. Options: -h, --help : Show this usage information. -s<ID> : All particles in the SSW file will get this surface ID. -l<LIMIT> : Limit the number of particles transferred to the SSW file (defaults to 2147483647, the maximal SSW capacity).
Quick and dirty way to get ssw2mcpl and mcpl2ssw
Rather than downloading and building the full MCPL distribution, it is possible to get hold
mcpl2ssw commands simply by downloading and saving
the two single-file (“fat”) versions of the code with via these links: ssw2mcpl_app_fat.c and mcpl2ssw_app_fat.c.
Next, go to a terminal and compile them with two commands (exchange “gcc” with the name of your compiler - e.g. “clang” on OSX):
gcc -std=c99 ssw2mcpl_app_fat.c -lm -o ssw2mcpl gcc -std=c99 mcpl2ssw_app_fat.c -lm -o mcpl2ssw
And you are ready to run! For instance:
./ssw2mcpl <my-ssw-file> <my-mcpl-file>
Or get full usage instructions with:
./ssw2mcpl --help ./mcpl2ssw --help