Core Modules

ww_data

Main interface module for WWINP file manipulation. Provides the WWData class for high-level operations on weight window data.

class WWData(header, mesh, values)[source]

Bases: object

Main interface for WWINP file manipulation.

High-level interface for manipulating weight window data from WWINP files.

Parameters:

header (Header) – Weight window file header information
mesh (Mesh) – Mesh geometry and binning information
values (WeightWindowValues) – Weight window values container

header: Header

mesh: Mesh

values: WeightWindowValues

copy()[source]

Create a deep copy of the WWData object.

Returns:

A new WWData instance with copied data

Return type:

WWData

Example:

>>> import wwinpy
>>> ww = wwinpy.from_file("path/to/wwinp_file")
>>> ww_copy = ww.copy()

multiply(factor=1.2, particle_types=-1)[source]

Multiply weight window values by a specified factor.

Parameters:

factor (float) – Multiplication factor to apply
particle_types (Union[int, List[int]]) – Particle type(s) to process. Use -1 for all types

Return type:

None

Returns:

None

Example:

>>> import wwinpy
>>> ww = wwinpy.from_file("path/to/wwinp_file")
>>> ww.multiply(1.2)  # Apply to all particle types
>>> ww.multiply(1.2, particle_types=0)  # Apply only to particle type 0

soften(power=0.6, particle_types=-1)[source]

Adjust weight window values by applying a power transformation.

Parameters:

power (float) – Exponent to apply to values (< 1 softens, > 1 hardens)
particle_types (Union[int, List[int]]) – Particle type(s) to process. Use -1 for all types

Return type:

None

Returns:

None

Example:

>>> import wwinpy
>>> ww = wwinpy.from_file("path/to/wwinp_file")
>>> ww.soften(0.6)  # Apply to all particle types
>>> ww.soften(0.6, particle_types=0)  # Apply only to particle type 0

apply_ratio_threshold(threshold=10.0, particle_types=-1, verbose=False)[source]

Apply a ratio threshold to weight window values.

Parameters:

threshold (float) – Maximum allowed ratio between neighboring cells
particle_types (Union[int, List[int]]) – Particle type(s) to process. Use -1 for all types
verbose (bool) – If True, prints detailed information

Return type:

None

Returns:

None

Example:

>>> import wwinpy
>>> ww = wwinpy.from_file("path/to/wwinp_file")
>>> ww.apply_ratio_threshold(10.0)  # Apply to all particle types
>>> ww.apply_ratio_threshold(threshold=10.0, particle_types=0)  # Apply only to particle type 0
>>> ww.apply_ratio_threshold(threshold=10.0, particle_types=[0, 1])

query_ww(**kwargs)[source]

Query weight window values based on specified criteria.

Parameters:

kwargs (dict) – Query parameters for filtering weight windows Valid keys: particle_type, time, energy, x, y, z

Returns:

Object containing queried values and metadata

Return type:

QueryResult

Example:

>>> import wwinpy
>>> ww = wwinpy.from_file("path/to/wwinp_file")
>>> result = wwinp.query_ww(
...     particle_type=0,
...     energy=(1.0, 10.0),
...     x=(0, 10),
...     y=0,
...     z=(0, 10)
... )

write_file(filename)[source]

Write the WWINP data to a file in FORTRAN-compatible format.

Parameters:: filename (str) – Path where the output file will be written
Return type:: None
Returns:: None

__init__(header, mesh, values)

Parameters:

header (Header)
mesh (Mesh)
values (WeightWindowValues)

Return type:

None

header

This module contains the Header class for Window Weight (WW) file handling.

class Header(if_, iv, ni, nr, probid='', nt=<factory>, ne=<factory>, nfx=None, nfy=None, nfz=None, x0=None, y0=None, z0=None, ncx=None, ncy=None, ncz=None, nwg=None, x1=None, y1=None, z1=None, x2=None, y2=None, z2=None)[source]

Bases: object

A class representing the header information for a Window Weight (WW) file.

This class stores and manages various parameters that define the geometric mesh and particle properties for radiation transport calculations.

Parameters:

if (int) – File type indicator (currently only 1 is supported)
iv (int) – Time-dependent windows flag (1=no, 2=yes)
ni (int) – Number of particle types
nr (int) – Mesh type indicator (10=rectangular, 16=cylindrical/spherical)
probid (str, optional) – Problem identification string
nt (List[int]) – Number of time bins per particle type
ne (List[int]) – Number of energy bins per particle type
nfx (float, optional) – Total number of fine mesh bins in x/r direction
nfy (float, optional) – Total number of fine mesh bins in y/z/theta direction
nfz (float, optional) – Total number of fine mesh bins in z/theta/phi direction
x0 (float, optional) – Origin x-coordinate or radial reference point
y0 (float, optional) – Origin y-coordinate or axial reference point
z0 (float, optional) – Origin z-coordinate or angular reference point
ncx (float, optional) – Number of coarse mesh bins in x/r direction
ncy (float, optional) – Number of coarse mesh bins in y/z/theta direction
ncz (float, optional) – Number of coarse mesh bins in z/theta/phi direction
nwg (float, optional) – Geometry type (1=cartesian, 2=cylindrical, 3=spherical)
x1 (float, optional) – X-component of first reference vector
y1 (float, optional) – Y-component of first reference vector
z1 (float, optional) – Z-component of first reference vector
x2 (float, optional) – X-component of second reference vector
y2 (float, optional) – Y-component of second reference vector
z2 (float, optional) – Z-component of second reference vector
if_ (int)

if_: int

iv: int

ni: int

nr: int

probid: str = ''

nt: List[int]

ne: List[int]

nfx: Optional[float] = None

nfy: Optional[float] = None

nfz: Optional[float] = None

x0: Optional[float] = None

y0: Optional[float] = None

z0: Optional[float] = None

ncx: Optional[float] = None

ncy: Optional[float] = None

ncz: Optional[float] = None

nwg: Optional[float] = None

x1: Optional[float] = None

y1: Optional[float] = None

z1: Optional[float] = None

x2: Optional[float] = None

y2: Optional[float] = None

z2: Optional[float] = None

property has_time_dependency: bool

Check if the window weights have time dependency.

Returns:: True if window weights are time-dependent (iv=2), False otherwise
Return type:: bool

property type_of_mesh: str | None

Get the type of mesh geometry being used.

Returns:: String indicating mesh type (‘cartesian’, ‘cylindrical’, ‘spherical’), ‘unknown’ for invalid values, or None if nwg is not set
Return type:: Optional[str]

property number_of_time_bins: List[int]

Get the list of time bins for each particle type.

Returns:: List containing the number of time bins for each particle type
Return type:: List[int]

property number_of_energy_bins: List[int]

Get the list of energy bins for each particle type.

Returns:: List containing the number of energy bins for each particle type
Return type:: List[int]

property number_of_particle_types: int

Get the total number of particle types.

Returns:: Number of particle types defined in the window weights
Return type:: int

__init__(if_, iv, ni, nr, probid='', nt=<factory>, ne=<factory>, nfx=None, nfy=None, nfz=None, x0=None, y0=None, z0=None, ncx=None, ncy=None, ncz=None, nwg=None, x1=None, y1=None, z1=None, x2=None, y2=None, z2=None)

Parameters:

if_ (int)
iv (int)
ni (int)
nr (int)
probid (str)
nt (List[int])
ne (List[int])
nfx (Optional[float])
nfy (Optional[float])
nfz (Optional[float])
x0 (Optional[float])
y0 (Optional[float])
z0 (Optional[float])
ncx (Optional[float])
ncy (Optional[float])
ncz (Optional[float])
nwg (Optional[float])
x1 (Optional[float])
y1 (Optional[float])
z1 (Optional[float])
x2 (Optional[float])
y2 (Optional[float])
z2 (Optional[float])

Return type:

None

mesh

This module provides the Mesh class for handling geometric, time, and energy meshes in Monte Carlo simulations. The module implements data structures for managing multi-dimensional mesh configurations and their properties.

class Mesh(header, geometry, time_mesh=<factory>, energy_mesh=<factory>)[source]

Bases: object

A class that encapsulates geometry, time, and energy mesh data for Monte Carlo simulations.

This class serves as a container for all mesh-related data, including geometric meshes (both coarse and fine), time meshes, and energy meshes. It provides properties to access different aspects of the mesh configuration.

Parameters:

header (Header) – Configuration header containing mesh specifications
geometry (GeometryData) – Geometric data containing mesh coordinates and properties
time_mesh (dict[int, np.ndarray]) – Dictionary mapping particle types to time mesh arrays
energy_mesh (dict[int, np.ndarray]) – Dictionary mapping particle types to energy mesh arrays

header: Header

geometry: GeometryData

time_mesh: dict[int, ndarray]

energy_mesh: dict[int, ndarray]

property coarse_geometry_mesh: Dict[str, ndarray]

Get the coarse geometry mesh coordinates.

Returns:: Dictionary containing coarse mesh coordinates for each dimension
Return type:: Dict[str, np.ndarray]

property fine_geometry_mesh: Dict[str, ndarray]

Get the fine geometry mesh coordinates.

Returns:: Dictionary containing fine mesh coordinates for each dimension
Return type:: Dict[str, np.ndarray]

property geometry_indices: ndarray

Get the 3D array of geometry indices.

Returns:: 3D array of geometry indices
Return type:: np.ndarray

property type_of_geometry_mesh: str | None

Get the type of geometry mesh (cartesian, cylindrical, or spherical).

Returns:: String indicating the geometry mesh type, or None if not defined
Return type:: Optional[str]

__init__(header, geometry, time_mesh=<factory>, energy_mesh=<factory>)

Parameters:

header (Header)
geometry (GeometryData)
time_mesh (dict[int, ndarray])
energy_mesh (dict[int, ndarray])

Return type:

None

weight_windows

Weight window operations module. Handles storage and manipulation of weight window values through the WeightWindowValues class.

class WeightWindowValues(header, mesh, ww_values=<factory>)[source]

Bases: object

Weight window values container class.

Internal container class for managing weight window values and operations.

Parameters:

header (Header) – WWINP file header information
mesh (Mesh) – Mesh geometry and binning information
ww_values (Dict[int, np.ndarray]) – Dictionary mapping particle types to weight window arrays

header: Header

mesh: Mesh

ww_values: Dict[int, ndarray]

multiply(factor=1.2, particle_types=-1)[source]

Multiply weight window values by a factor.

Parameters:

factor (float) – Multiplication factor to apply
particle_types (Union[int, List[int]]) – Particle type(s) to process. Use -1 for all types, or specify individual types as an integer or list of integers

Raises:

ValueError – If an invalid particle type is specified

Return type:

None

soften(power=0.6, particle_types=-1)[source]

Modify weight window boundaries by raising values to a power.

Parameters:

power (float) – Exponent to apply to values (< 1 softens, > 1 hardens)
particle_types (Union[int, List[int]]) – Particle type(s) to process. Use -1 for all types, or specify individual types as an integer or list of integers

Raises:

ValueError – If an invalid particle type is specified

Return type:

None

apply_ratio_threshold(threshold=10.0, particle_types=-1, verbose=False)[source]

Apply a ratio threshold to identify and modify extreme weight window differences bewteen neighbor cells.

Parameters:

threshold (float) – Maximum allowed ratio between neighboring cells
particle_types (Union[int, List[int]]) – Particle type(s) to process. Use -1 for all types, or specify individual types as an integer or list of integers
verbose (bool) – If True, prints detailed detailed detailed information about modifications

Return type:

None

Returns:

None

Raises:

ValueError – If an invalid particle type is specified

When verbose=True, the following information is printed: - Time and energy bin information - Modified voxel positions and values - Summary statistics of changes

query_ww(particle_type=None, time=None, energy=None, x=None, y=None, z=None)[source]

Query weight window values based on specified criteria.

Parameters:

particle_type (Optional[int]) – Specific particle type to query (None for all types)
time (Optional[Union[float, Tuple[float, float]]]) – Time value or (min, max) range for time-dependent data
energy (Optional[Union[float, Tuple[float, float]]]) – Energy value or (min, max) range in MeV
x (Optional[Union[float, Tuple[float, float]]]) – X coordinate value or (min, max) range in geometry units
y (Optional[Union[float, Tuple[float, float]]]) – Y coordinate value or (min, max) range in geometry units
z (Optional[Union[float, Tuple[int, int]]]) – Z coordinate value or (min, max) range in geometry units

Returns:

Object containing queried values and metadata

Return type:

QueryResult

Raises:

ValueError – If an invalid particle type is specified

Example:

>>> ww = wwinpy.from_file(path/to/wwinp)
>>> result = ww.query_ww(
...     particle_type=0,
...     energy=(1.0, 10.0),
...     x=(0, 10),
...     y=(0, 10),
...     z=(0, 10)
... ).to_dataframe()

__init__(header, mesh, ww_values=<factory>)

Parameters:

header (Header)
mesh (Mesh)
ww_values (Dict[int, ndarray])

Return type:

None

parser

WWINP file parser module.

This module provides functionality for reading and parsing MCNP weight window input (WWINP) files. Contains optimized parsing functions for handling large data files efficiently.

from_file(file_path, verbose=False)[source]

Parse a WWINP file and create a WWData object.

Parameters:

file_path (str) – Path to the WWINP file to parse
verbose (bool) – If True, print detailed parsing information

Returns:

Parsed WWINP data object

Return type:

WWData

Raises:

WWINPFormatError – If the file format is invalid
WWINPParsingError – If there are errors during parsing

Utility Modules

geometry

This module handles geometric data structures and operations for Cartesian, Cylindrical, and Spherical coordinate systems. Provides classes for managing geometry axes and mesh generation in various coordinate systems.

class GeometryAxis(origin, q=<factory>, p=<factory>, s=<factory>)[source]

Bases: object

A class representing a geometric axis with coarse and fine mesh information.

Parameters:

origin (float) – The starting coordinate of the axis
q (np.ndarray) – Array of fine mesh ratios for each segment
p (np.ndarray) – Array of coarse mesh coordinates
s (np.ndarray) – Array of number of fine meshes per segment

origin: float

q: ndarray

p: ndarray

s: ndarray

add_segment(q, p, s)[source]

Add a new coarse mesh segment to the axis.

Parameters:

q (float) – Fine mesh ratio for the segment
p (float) – Coarse mesh coordinate endpoint
s (float) – Number of fine meshes in the segment

__init__(origin, q=<factory>, p=<factory>, s=<factory>)

Parameters:

origin (float)
q (ndarray)
p (ndarray)
s (ndarray)

Return type:

None

class GeometryData(header, x_axis=None, y_axis=None, z_axis=None, r_axis=None, theta_axis=None, phi_axis=None)[source]

Bases: object

A class managing geometric mesh data for different coordinate systems.

Parameters:

header (Header) – Configuration header containing mesh type and dimensions
x_axis (Optional[GeometryAxis]) – X-axis data for Cartesian coordinates
y_axis (Optional[GeometryAxis]) – Y-axis data for Cartesian coordinates
z_axis (Optional[GeometryAxis]) – Z-axis data for Cartesian/Cylindrical coordinates
r_axis (Optional[GeometryAxis]) – Radial axis data for Cylindrical/Spherical coordinates
theta_axis (Optional[GeometryAxis]) – Angular axis data for Cylindrical/Spherical coordinates
phi_axis (Optional[GeometryAxis]) – Azimuthal axis data for Spherical coordinates

header: Header

x_axis: Optional[GeometryAxis] = None

y_axis: Optional[GeometryAxis] = None

z_axis: Optional[GeometryAxis] = None

r_axis: Optional[GeometryAxis] = None

theta_axis: Optional[GeometryAxis] = None

phi_axis: Optional[GeometryAxis] = None

property coarse_mesh: Dict[str, ndarray]

Get the coarse mesh for the current geometry type.

Returns:: Dictionary containing mesh coordinates for each dimension
Return type:: Dict[str, np.ndarray]
Raises:: ValueError – If required axes for the geometry type are not defined

property fine_mesh: Dict[str, ndarray]

Get the fine mesh for the current geometry type.

Returns:: Dictionary containing mesh coordinates for each dimension
Return type:: Dict[str, np.ndarray]
Raises:: ValueError – If required axes for the geometry type are not defined

property indices: ndarray

Generate a 3D array of geometry indices.

Creates indices based on the dimensions (nfx, nfy, nfz) defined in the header. The index at position (x,y,z) is calculated as z*(nfx*nfy) + y*nfx + x.

Returns:: 3D array of geometry indices
Return type:: np.ndarray

__init__(header, x_axis=None, y_axis=None, z_axis=None, r_axis=None, theta_axis=None, phi_axis=None)

Parameters:

header (Header)
x_axis (Optional[GeometryAxis])
y_axis (Optional[GeometryAxis])
z_axis (Optional[GeometryAxis])
r_axis (Optional[GeometryAxis])
theta_axis (Optional[GeometryAxis])
phi_axis (Optional[GeometryAxis])

Return type:

None

query

Query module for weight window data retrieval. Provides the QueryResult class for structured access to weight window query results.

class QueryResult(header, particle_types, ww_values, energy_intervals, time_intervals, x_intervals, y_intervals, z_intervals)[source]

Bases: object

Store the results of a weight window query.

Parameters:

header (Header) – Weight window file header information
particle_types (List[int]) – List of particle type identifiers
ww_values (List[np.ndarray]) – List of weight window values arrays, one per particle type
energy_intervals (List[Tuple[np.ndarray, np.ndarray]]) – List of energy interval pairs (starts, ends) for each particle type
time_intervals (List[Tuple[np.ndarray, np.ndarray]]) – List of time interval pairs (starts, ends) for each particle type
x_intervals (Tuple[np.ndarray, np.ndarray]) – Spatial interval pairs (starts, ends) for x-direction
y_intervals (Tuple[np.ndarray, np.ndarray]) – Spatial interval pairs (starts, ends) for y-direction
z_intervals (Tuple[np.ndarray, np.ndarray]) – Spatial interval pairs (starts, ends) for z-direction

header: Header

particle_types: List[int]

ww_values: List[ndarray]

energy_intervals: List[Tuple[ndarray, ndarray]]

time_intervals: List[Tuple[ndarray, ndarray]]

x_intervals: Tuple[ndarray, ndarray]

y_intervals: Tuple[ndarray, ndarray]

z_intervals: Tuple[ndarray, ndarray]

to_dataframe()[source]

Convert query results to a pandas DataFrame.

Returns:: DataFrame containing weight window data with particle type, spatial, energy, and time information
Return type:: pd.DataFrame

__init__(header, particle_types, ww_values, energy_intervals, time_intervals, x_intervals, y_intervals, z_intervals)

Parameters:

header (Header)
particle_types (List[int])
ww_values (List[ndarray])
energy_intervals (List[Tuple[ndarray, ndarray]])
time_intervals (List[Tuple[ndarray, ndarray]])
x_intervals (Tuple[ndarray, ndarray])
y_intervals (Tuple[ndarray, ndarray])
z_intervals (Tuple[ndarray, ndarray])

Return type:

None

ratios

Module providing optimized ratio calculations for weight window meshes.

Uses Numba-accelerated functions for efficient ratio calculations between neighboring cells.

calculate_max_ratio_array(array)[source]

Parameters:: array (ndarray)
Return type:: ndarray

calculate_ratios_stats(array)[source]

Calculate direction-invariant average and maximum ratio between neighbors, counting each pair only once (forward neighbors only). Ratio is defined as max(center, neighbor) / min(center, neighbor), so it is always >= 1 and does not depend on whether the data is ascending or descending.

Parameters:: array (ndarray) – 3D array of values, shape [nz, ny, nx].
Return type:: tuple[float, float]
Returns:: (average_ratio, max_ratio).

utils

Utility functions for WWINP file processing.

Provides helper functions for data verification and grid operations.

verify_and_correct(ni, nt, ne, iv, verbose=False)[source]

Verify and correct weight window input parameters.

Parameters:

ni (int) – Number of particle types
nt (Optional[List[int]]) – Time groups per particle type (None if iv != 2)
ne (List[int]) – Energy groups per particle type
iv (int) – Time dependency flag (2 for time-dependent)
verbose (bool) – Enable detailed output

Returns:

Tuple of (corrected ni, corrected nt, corrected ne)

Return type:

Tuple[int, Optional[List[int]], List[int]]

Raises:

ValueError – If input parameters are inconsistent

get_closest_energy_indices(energy_grid, energy_value, atol=1e-09)[source]

Find energy indices bounding a value in an energy grid.

Parameters:

energy_grid (np.ndarray) – Sorted energy grid points array
energy_value (float) – Target energy value
atol (float, optional) – Absolute tolerance for float comparison

Returns:

Array of one or two indices. Two indices only when value exactly matches a grid point

Return type:

np.ndarray

get_range_energy_indices(grid, range_tuple, atol=1e-09)[source]

Find energy indices for a range of values in an energy grid.

Parameters:

grid (np.ndarray) – Sorted energy grid points array
range_tuple (Tuple[float, float]) – (min, max) energy range values
atol (float)

Returns:

Array of indices covering the range

Return type:

np.ndarray

Raises:

ValueError – If grid is empty or range is invalid

get_energy_intervals_from_indices(bins, indices)[source]

Get energy interval boundaries for given indices.

Parameters:

bins (np.ndarray) – Energy grid boundaries array
indices (np.ndarray) – Array of indices from get_closest_energy_indices

Returns:

Tuple of (starts, ends) arrays for energy intervals

Return type:

Tuple[np.ndarray, np.ndarray]

get_closest_indices(grid, value, atol=1e-09)[source]

Find indices bounding a value in a grid.

Parameters:

grid (np.ndarray) – Sorted grid points array
value (float) – Target value
atol (float, optional) – Absolute tolerance for float comparison

Returns:

Array of two bounding indices

Return type:

np.ndarray

get_range_indices(grid, range_tuple)[source]

Find grid indices within a range.

Parameters:

grid (np.ndarray) – Sorted grid points array
range_tuple (Tuple[float, float]) – (min, max) range values

Returns:

Array of indices within range

Return type:

np.ndarray

Raises:

ValueError – If range_tuple[0] > range_tuple[1]

get_bin_intervals_from_indices(bins, indices)[source]

Get bin interval boundaries for given indices.

Parameters:

bins (np.ndarray) – Array of bin boundaries
indices (np.ndarray) – Array of [start, end] indices

Returns:

Tuple of (bin_starts, bin_ends) arrays

Return type:

Tuple[np.ndarray, np.ndarray]

Raises:

ValueError – If bins is None/empty or indices invalid

plotter

class WWPlotter(wwinp)[source]

Bases: object

Parameters:: wwinp (WWData)

__init__(wwinp)[source]

Initialize the plotter with WWData.

Parameters:: wwinp (WWData) – The weight window data to visualize

plot_3d(particle_type, time_idx=0)[source]

Create an interactive 3D visualization with energy slider.

Parameters:

particle_type (int) – Particle type to visualize
time_idx (int) – Time index for time-dependent data

Return type:

None

plot_slices(particle_type, time_idx=0)[source]

Create an interactive visualization with orthogonal slices.

Parameters:

particle_type (int) – Particle type to visualize
time_idx (int) – Time index for time-dependent data

Return type:

None

plot_volume(particle_type, time_idx=0)[source]

Create a volume rendering visualization.

Parameters:

particle_type (int) – Particle type to visualize
time_idx (int) – Time index for time-dependent data

Return type:

None

exceptions

Custom exceptions for WWINP file handling.

Defines specific exception types for format and parsing errors.

exception WWINPFormatError[source]

Bases: Exception

Exception raised for WWINP file format errors.

Raises:: When the WWINP file structure is invalid

exception WWINPParsingError[source]

Bases: Exception

Exception raised for WWINP parsing errors.

Raises:: When the WWINP file content cannot be parsed