Header lines¶

The header section can be preceded by any number of comment line starting with the # character.

The header lines are 5 lines containing the following information:

1. Number of intervals for x, y, z
2. Mesh coordinates for x direction
3. Mesh coordinates for y direction
4. Mesh coordinates for z direction
5. List of activated materials; use of this info requires the m parameter

These are optionally followed by a parameters line (line 6). This line begins with a ‘p’, and single character parameters, separated by spaces, follow. The currently supported parameters are (order does not matter):

• u: Enable uniform sampling.
• v: Enable voxel sampling.
• m: Enable source position rejection based on activated materials.
• e: Read in custom list of energy bin boundaries.
• d: Enable debug output to file source_debug. Dumps xxx,yyy,zzz,wgt every 10k particles.
• c: Treat bins for each voxel as cumulative.
• b: Flag indicating bias values are used; only valid with voxel sampling.
• r: Particles starting in a void are resampled (within the same voxel).
• a: Resample entire particle when a particle would start in void. Requires u and r to be enabled. Can give incorrect results due to playing an unfair game.

An example parameter line: p u d m e

If the parameters line is not present, the default is to set u, m, c as True. If ‘e’ parameter exists, line 7 lists custom energy group boundaries, space delimited. This line start with the integer number of groups. The default energy bins are a 42 group structure. All subsequent lines are for voxels.

Voxel lines¶

Two formats are supported, cumulative bins, or non-cumulative bins. In both cases, lines list bin values from low energy to high energy, delimited by spaces.

Note that the normalization for voxel and uniform sampling is different, and will result in differing gammas files. In general, for voxel sampling, normalization is based on the average source strength in photons/voxel/s; For uniform sampling, we want average source density in phtons/cm3/s.

If the R2S-ACT workflow is not being used to generate the gammas file, one should verify that the gammas files are being generated correctly. To do this, use a simple test problem to verify that you get the same average energy per source particle in all test cases, and that all uniform sampling test cases have a average weight of 1.0 per source particle. (See the summary table in MCNP output)

Note that correct normalization also depends on whether material rejection is being used.

In either case, the last bin can be followed by a bias value for the voxel. An arbitrary range of bias values can be used since the source routine does the necessary re-normalization for voxel sampling.

Other notes¶

Voxel sampling and energy sampling use a sampling technique referred to as ‘alias discrete’ or ‘alias’ sampling. This provides efficiency benefits over ‘direct discrete’ sampling of PDFs. Creation of the alias tables uses the algorithm described by Vose (1991).

r2s.mcnp.source_gamma_doc.gen_alias_table()¶

Subroutine generates an alias table

Parameters :	bins : list of floats (INOUT) PDF’s absolute probabilities aliases : list of integers (OUT) Filled with alias indices. probs_list : list of floats (OUT) List of probabilities for each bin/alias pair. len : int Number of bins in the alias table

Notes

The sum of the probabilities in bins must be 1.

We implement the alias table creation algorithm described by Vose (1991). For reference:

Vose:      Code:
p_j        bins(j)
large_l    ind_large(l)
small_s    ind_small(s)
prob_j     probs_list(j)
'bin' j    j
alias_j    aliases(j)

r2s.mcnp.source_gamma_doc.gen_erg_alias_table()¶

Create alias table for energy bins of a single voxel

Parameters :	len : int length of ergsList ergsList : list of floats ergsList values must total 1! myErgAliases : list of integers (OUT) The generated alias indices for the energy PDF myErgBinsProbabilities : list of floats (OUT) List of probabilities for each bin/alias pair.

r2s.mcnp.source_gamma_doc.gen_voxel_alias_table()¶

Generate alias table for voxels in the problem

Notes

The resulting alias table is stored in lists aliases and binsProbabilities.

tot_list does not have to be normalized prior to calling this subroutine

r2s.mcnp.source_gamma_doc.print_debug()¶

Subroutine stores debug info in an array, and write the array to a file after every 10000 particles.

r2s.mcnp.source_gamma_doc.read_custom_ergs()¶

Read line from gammas file to get a custom set of energy bins

r2s.mcnp.source_gamma_doc.read_header()¶

Read in first 5 lines of gammas file, as well as comment lines

Parameters :	myunit : int Unit number for an opened file (i.e. file ‘gammas’)

Notes

First 5 non-comment lines contain the x,y,z mesh intervals and the list of active materials

Also skips over any comment lines (beginning with # character) at start of file.

r2s.mcnp.source_gamma_doc.read_params()¶

Read in the parameters line, if there is one.

Parameters :	myunit : int Unit number for an opened file (i.e. file ‘gammas’)

Notes

Line should start with a ‘p’ and have single characters that are space delimited.

Set various parameters to 1 (true) if they exist.

r2s.mcnp.source_gamma_doc.sample_erg()¶

Sample the alias table of energy bins for the selected voxel.

Parameters :	myerg : float (OUT) Sampled energy is stored in this variable myvoxel : int Index of sampled voxel n_grp : int Number of energy groups n_vox : int Length of next two arrays probList : list of lists of floats List of bin probabilities for energy PDF, for each voxel aliasesList : list of lists of integers Alias indices for energy group, for each voxel

r2s.mcnp.source_gamma_doc.sample_hexahedra()¶

Uniformly samples within the extents of a hexahedral voxel

Notes

ii, jj, kk are presumed to have been already determined, and have values in the range [1, i_ints/j_ints/k_ints].

r2s.mcnp.source_gamma_doc.source()¶

Subroutine manages sampling of photons on mesh

Adapted from dummy source.F90 file.

Notes

if nsr=0, subroutine source must be furnished by the user. at entrance, a random set of uuu,vvv,www has been defined. the following variables must be defined within the subroutine: xxx,yyy,zzz,icl,jsu,erg,wgt,tme and possibly ipt,uuu,vvv,www. subroutine srcdx may also be needed.

r2s.mcnp.source_gamma_doc.source_setup()¶

Subroutine handles parsing of the ‘gammas’ file and related initializations

r2s.mcnp.source_gamma_doc.uniform_sample()¶

Uniformly sample photon position in the entire volume of the mesh tally.

r2s.mcnp.source_gamma_doc.voxel_sample()¶

Sample photon position from alias table of voxels.

Parameters (not currently implemented)¶

These features would be set in the r2s.cfg file. * ~~r: Particles starting in a void are resampled (within the same voxel).~~ * ~~a: Resample entire particle when a particle would start in void. Requires u and r to be enabled. Can give incorrect results due to playing an unfair game.~~

~~If the parameters line is not present, the default is to set u, m, c as True. If ‘e’ parameter exists, line 7 lists custom energy group boundaries, space delimited. This line start with the integer number of groups. ~~

~~Note that correct normalization also depends on whether material rejection is being used.~~

Other notes¶

Voxel sampling and energy sampling use a sampling technique referred to as ‘alias discrete’ or ‘alias’ sampling. This provides efficiency benefits over ‘direct discrete’ sampling of PDFs. Creation of the alias tables uses the algorithm described by Vose (1991).

The default energy bins are a 42 group structure.

An arbitrary range of bias values can be used since the source routine does the necessary re-normalization for voxel sampling.

r2s.mcnp.source_moab_doc.gen_alias_table()¶

Subroutine generates an alias table

Parameters :	bins : list of floats (INOUT) PDF’s absolute probabilities aliases : list of integers (OUT) Filled with alias indices. probs_list : list of floats (OUT) List of probabilities for each bin/alias pair. len : int Number of bins in the alias table

Notes

The sum of the probabilities in bins must be 1.

We implement the alias table creation algorithm described by Vose (1991). For reference:

Vose:      Code:
p_j        bins(j)
large_l    ind_large(l)
small_s    ind_small(s)
prob_j     probs_list(j)
'bin' j    j
alias_j    aliases(j)

r2s.mcnp.source_moab_doc.gen_erg_alias_table()¶

Create alias table for energy bins of a single voxel

Parameters :	len : int length of ergsList ergsList : list of floats ergsList values must total 1! myErgAliases : list of integers (OUT) The generated alias indices for the energy PDF myErgBinsProbabilities : list of floats (OUT) List of probabilities for each bin/alias pair.

r2s.mcnp.source_moab_doc.gen_voxel_alias_table()¶

Generate alias table for voxels in the problem

Notes

The resulting alias table is stored in lists aliases and binsProbabilities.

tot_list does not have to be normalized prior to calling this subroutine

r2s.mcnp.source_moab_doc.get_hex_vol()¶

Subroutine calculates volume of a hexahedron entity on a MOAB mesh

Parameters :	mymesh : iMesh_Instance Mesh object entity_handle : iBase_EntityHandle Entity set handle volume : float Stores the calculated volume

Notes

Current implementation assumes 8 vertext hex with square planar facets

r2s.mcnp.source_moab_doc.get_tet_vol()¶

Subroutine calculates volume of a tetrahedron entity on a MOAB mesh

Parameters :	mymesh : iMesh_Instance Mesh object tet_entity_handle : iBase_EntityHandle Entity set handle volume : float Stores the calculated volume

Notes

Algorithm is from Wikipedia article for Tetrahedrons. For points A, B, C, D:

vol = (1/6) * abs( (A-D) . ((B-D) x (C-D)) )

r2s.mcnp.source_moab_doc.print_debug()¶

Subroutine stores debug info in an array, and write the array to a file after every 10000 particles.

r2s.mcnp.source_moab_doc.read_moab()¶

Read in the moab mesh, getting the root set and voxel entities, and looking for bias and energy tags.

Parameters :	mymesh : iMesh_Instance Mesh instance which will be initialized and then read filename : character array Filename to read mesh data from. (.vtk or .h5m file) rpents : pointer to array of iBase_EntityHandle Pointer to an array that will be filled with iBase_REGION entity handles

r2s.mcnp.source_moab_doc.sample_box()¶

Uniformly samples within the extents of a hexahedral voxel

Notes

ii, jj, kk are presumed to have been already determined, and have values in the range [1, i_ints/j_ints/k_ints].

r2s.mcnp.source_moab_doc.sample_erg()¶

Sample the alias table of energy bins for the selected voxel.

Parameters :	myerg : float (OUT) Sampled energy is stored in this variable myvoxel : int Index of sampled voxel n_grp : int Number of energy groups n_vox : int Length of next two arrays probList : list of lists of floats List of bin probabilities for energy PDF, for each voxel aliasesList : list of lists of integers Alias indices for energy group, for each voxel

r2s.mcnp.source_moab_doc.sample_hexahedra()¶

This subroutine receives the eight vertices of a hexahedron and sets xxx, yyy, zzz, to values corresponding to a uniformly sampled point within the hexahedral voxel.

It is assumed that the hexahedron is a parallelepiped.

Parameters :	co - list of 12 real*8 values : The x y z coordinates of four points for a hexaahedron. These numbers are in xxx.. yyy.. zzz.. order.

Notes

The algorithm used is to sample distances along three edge vectors that originate at the first vertex of the hexahedron (MOAB canonical ordering) and add these three vectors to the first vertice’s coordinates.

r2s.mcnp.source_moab_doc.sample_region_entity()¶

This subroutine retrieves the vertices of the sampled voxel, and calls the appropriate sampling subroutine to get a sampled point.

Parameters :	mymesh : iMesh_Instance Mesh object entity_handle : iBase_EntityHandle Entity set handle

r2s.mcnp.source_moab_doc.sample_tetrahedra()¶

This subroutine receives the four vertices of a tetrahedron and sets xxx, yyy, zzz, to values corresponding to a uniformly sampled point within the tetrahedron.

Parameters :	co - list of 12 real*8 values : The x y z coordinates of four points for a tetrahedron. These numbers are in xxx.. yyy.. zzz.. order.

Notes

The algorithm used is that described by Rocchini & Cignoni (2001)

r2s.mcnp.source_moab_doc.source()¶

Subroutine manages sampling of photons on mesh

Adapted from dummy source.F90 file.

Notes

if nsr=0, subroutine source must be furnished by the user. at entrance, a random set of uuu,vvv,www has been defined. the following variables must be defined within the subroutine: xxx,yyy,zzz,icl,jsu,erg,wgt,tme and possibly ipt,uuu,vvv,www. subroutine srcdx may also be needed.

r2s.mcnp.source_moab_doc.source_setup()¶

Subroutine handles parsing of the ‘gammas’ file and related initializations

r2s.mcnp.source_moab_doc.voxel_sample()¶

Sample photon position from alias table of voxels.