kika.mctal

The mctal module provides functionality for processing MCNP tally output files.

Submodules

kika.mcnp.mctal

class kika.mcnp.mctal.Mctal(code_name: str | None = None, ver: str | None = None, probid: str | None = None, knod: int | None = None, nps: int | None = None, rnr: int | None = None, problem_id: str | None = None, ntal: int | None = None, npert: int | None = 0, tally_numbers: List[int] = None, tally: Dict[int, Tally] = None)

Bases: object

Container class for MCNP MCTAL file data.

Variables:

• code_name – Name of the MCNP code version

• ver – Version number of MCNP

• probid – Problem ID string

• knod – Code specific parameter

• nps – Number of particle histories

• rnr – Random number

• problem_id – Problem identification line

• ntal – Number of tallies

• npert – Number of perturbations

• tally_numbers – List of tally numbers

• tally – Dictionary mapping tally numbers to Tally objects

code_name: str | None = None

ver: str | None = None

probid: str | None = None

knod: int | None = None

nps: int | None = None

rnr: int | None = None

problem_id: str | None = None

ntal: int | None = None

npert: int | None = 0

tally_numbers: List[int] = None

tally: Dict[int, Tally] = None

class kika.mcnp.mctal.PerturbationCollection

Bases: dict

A collection class for perturbation data that provides a nice summary representation.

This class extends the standard dictionary with a custom __repr__ method to provide a formatted summary of the perturbation data.

to_dataframe()

Converts all perturbation data to a pandas DataFrame.

Returns:

DataFrame containing data from all perturbations

Return type:

pandas.DataFrame

class kika.mcnp.mctal.Tally(tally_id: int, name: str = '', n_cells_surfaces: int = 0, cell_surface_ids: List[int] = None, n_direct_bins: int = 1, n_user_bins: int = 0, _has_total_user_bin: bool = False, _has_cumulative_user_bin: bool = False, n_segment_bins: int = 0, _has_total_segment_bin: bool = False, _has_cumulative_segment_bin: bool = False, n_multiplier_bins: int = 0, _has_total_multiplier_bin: bool = False, _has_cumulative_multiplier_bin: bool = False, n_cosine_bins: int = 0, _has_total_cosine_bin: bool = False, _has_cumulative_cosine_bin: bool = False, n_energy_bins: int = 0, _has_total_energy_bin: bool = False, _has_cumulative_energy_bin: bool = False, energies: List[float] = None, n_time_bins: int = 0, _has_total_time_bin: bool = False, _has_cumulative_time_bin: bool = False, times: List[float] = None, total_energy_result: float | None = None, total_energy_error: float | None = None, results: List[float] = None, errors: List[float] = None, integral_result: float | None = None, integral_error: float | None = None, tfc_nps: List[int] = None, tfc_results: List[float] = None, tfc_errors: List[float] = None, tfc_fom: List[float] = None, perturbation: PerturbationCollection = None)

Bases: object

Container for MCNP tally data.

Variables:

• tally_id – Unique identifier for the tally

• name – Name/description of the tally

• n_cells_surfaces – Number of cells or surfaces where the tally is scored

• cell_surface_ids – List of cell or surface IDs

• n_direct_bins – Number of direct vs. total or flagged vs. unflagged bins

• n_user_bins – Number of user bins

• _has_total_user_bin – Whether user bins include a total bin (private)

• _has_cumulative_user_bin – Whether user bins are cumulative (private)

• n_segment_bins – Number of segment bins

• _has_total_segment_bin – Whether segment bins include a total bin (private)

• _has_cumulative_segment_bin – Whether segment bins are cumulative (private)

• n_multiplier_bins – Number of multiplier bins

• _has_total_multiplier_bin – Whether multiplier bins include a total bin (private)

• _has_cumulative_multiplier_bin – Whether multiplier bins are cumulative (private)

• n_cosine_bins – Number of cosine bins

• _has_total_cosine_bin – Whether cosine bins include a total bin (private)

• _has_cumulative_cosine_bin – Whether cosine bins are cumulative (private)

• n_energy_bins – Number of energy bins

• _has_total_energy_bin – Whether energy bins include a total bin (private)

• _has_cumulative_energy_bin – Whether energy bins are cumulative (private)

• energies – Energy bin boundaries

• n_time_bins – Number of time bins

• _has_total_time_bin – Whether time bins include a total bin (private)

• _has_cumulative_time_bin – Whether time bins are cumulative (private)

• times – Time bin boundaries

• total_energy_result – Result for the total energy bin (if present)

• total_energy_error – Error for the total energy bin (if present)

• results – Tally results for each bin (excluding totals)

• errors – Relative errors for each bin (excluding totals)

• integral_result – Integral result over all bins

• integral_error – Relative error of the integral result

• tfc_nps – Number of particles for TFC analysis

• tfc_results – Results at each TFC step

• tfc_errors – Errors at each TFC step

• tfc_fom – Figure of Merit at each TFC step

• perturbation – Perturbation data keyed by perturbation index

tally_id: int

name: str = ''

n_cells_surfaces: int = 0

cell_surface_ids: List[int] = None

n_direct_bins: int = 1

n_user_bins: int = 0

n_segment_bins: int = 0

n_multiplier_bins: int = 0

n_cosine_bins: int = 0

n_energy_bins: int = 0

energies: List[float] = None

n_time_bins: int = 0

times: List[float] = None

total_energy_result: float | None = None

total_energy_error: float | None = None

results: List[float] = None

errors: List[float] = None

integral_result: float | None = None

integral_error: float | None = None

tfc_nps: List[int] = None

tfc_results: List[float] = None

tfc_errors: List[float] = None

tfc_fom: List[float] = None

perturbation: PerturbationCollection = None

get_dimensions() → dict

Get all dimensions of the tally with their sizes.

Returns:

Dictionary with dimension names as keys and their sizes as values, in order: cell, user, segment, multiplier, cosine, energy, time

Return type:

dict

get_shaped_results() → ndarray

Reshape the flat results array into a multidimensional array.

Returns:

Multidimensional array of results

Return type:

numpy.ndarray

get_shaped_errors() → ndarray

Reshape the flat errors array into a multidimensional array.

Returns:

Multidimensional array of errors

Return type:

numpy.ndarray

to_xarray()

Convert tally data to an xarray Dataset with labeled dimensions.

Returns:

Dataset containing tally results and errors with labeled dimensions

Return type:

xarray.Dataset

Note:

This method does not include energy-integrated data. Use get_integral_energy_data() to access energy-integrated results.

get_slice(**kwargs) → Tuple[ndarray, ndarray]

Extract a slice of results and errors by specifying dimension values.

Parameters:

kwargs (dict) – Dimension name and value pairs. For dimensions with explicit coordinates (like energy or time), use the coordinate value. For dimensions without explicit values, use the index.

Returns:

Tuple of (results, errors) arrays for the specified slice

Return type:

tuple(numpy.ndarray, numpy.ndarray)

Example:

# Select by actual energy value (MeV) tally.get_slice(energy=1.0)

# Select by segment index tally.get_slice(segment=1)

# Combine multiple dimensions tally.get_slice(energy=1.0, segment=1)

to_dataframe()

Converts tally data to a pandas DataFrame.

For simple tallies with only energy dependence, creates a DataFrame with ‘Energy’, ‘Result’, and ‘Error’ columns. For multidimensional tallies, creates a flattened DataFrame with columns for each dimension.

Returns:

DataFrame containing the tally data

Return type:

pandas.DataFrame

Note:

This method does not include energy-integrated data. Use get_integral_energy_dataframe() to access energy-integrated results.

get_integral_energy_data()

Get the results integrated over all energy bins.

For multidimensional tallies, returns shaped arrays for all dimensions except energy.

Returns:

Dictionary with ‘Result’ and ‘Error’ keys containing the energy-integrated data. For multidimensional tallies, these will be numpy arrays.

Return type:

dict or None

get_integral_energy_dataframe()

Get the energy-integrated results as a DataFrame.

For multidimensional tallies, includes all dimensions except energy.

Returns:

DataFrame containing the energy-integrated data

Return type:

pandas.DataFrame

plot_tfc_data(figsize=(15, 5), show_error_bars=True)

Creates and displays plots showing TFC convergence data.

This method creates a figure with three subplots showing the TFC convergence data: results vs NPS (with optional error bars), relative errors vs NPS, and figure of merit vs NPS. The figure is displayed immediately.

Parameters:

• figsize (tuple) – Figure size in inches as (width, height)

• show_error_bars (bool) – Whether to display error bars on the results plot

Raises:

ValueError – If no TFC data is available for plotting

Returns:

None

class kika.mcnp.mctal.TallyPert(tally_id: int, name: str = '', n_cells_surfaces: int = 0, cell_surface_ids: List[int] = None, n_direct_bins: int = 1, n_user_bins: int = 0, _has_total_user_bin: bool = False, _has_cumulative_user_bin: bool = False, n_segment_bins: int = 0, _has_total_segment_bin: bool = False, _has_cumulative_segment_bin: bool = False, n_multiplier_bins: int = 0, _has_total_multiplier_bin: bool = False, _has_cumulative_multiplier_bin: bool = False, n_cosine_bins: int = 0, _has_total_cosine_bin: bool = False, _has_cumulative_cosine_bin: bool = False, n_energy_bins: int = 0, _has_total_energy_bin: bool = False, _has_cumulative_energy_bin: bool = False, energies: List[float] = None, n_time_bins: int = 0, _has_total_time_bin: bool = False, _has_cumulative_time_bin: bool = False, times: List[float] = None, total_energy_result: float | None = None, total_energy_error: float | None = None, results: List[float] = None, errors: List[float] = None, integral_result: float | None = None, integral_error: float | None = None, tfc_nps: List[int] = None, tfc_results: List[float] = None, tfc_errors: List[float] = None, tfc_fom: List[float] = None, perturbation: PerturbationCollection = None, perturbation_number: int = None)

Bases: Tally

Container for perturbed tally data, inheriting from Tally.

Ivar:

Inherits all attributes from Tally class

Variables:

perturbation_number – The perturbation index number

perturbation_number: int = None

kika.mcnp.parse_mctal

kika.mcnp.parse_mctal.read_mctal(filename)

Read and parse an MCNP MCTAL file.

Parameters:

filename (str) – Path to the MCTAL file

Returns:

An Mctal object containing the parsed data

Return type:

Mctal

Raises:

ValueError – If the file format is invalid or parsing fails

kika.mcnp.parse_mctal.parse_tally(tally_id, file_obj, start_pos, tfc=True, pert=True)

Parse a single tally section from an MCTAL file.

Parameters:

• tally_id (int) – ID number of the tally to parse

• file_obj (file) – Open file object positioned at tally start

• start_pos (int) – File position where tally section starts

• tfc (bool) – Whether to parse TFC data

• pert (bool) – Whether to parse perturbation data

Returns:

A Tally object containing the parsed data

Return type:

Tally

Raises:

ValueError – If tally format is invalid or parsing fails

kika.mcnp.parse_mctal.separate_total_energy_bins(values, n_energy_bins, has_total_energy_bin)

Separate the total energy bin values from the regular results array.

In MCNP MCTAL files with multiple dimensions, energy is the rightmost dimension and varies fastest. For tallies with total energy bins, every nth value (where n = n_energy_bins) is a total bin value.

Parameters:

• values (list) – The flat array of values (results or errors)

• n_energy_bins (int) – Number of energy bins including total bins

• has_total_energy_bin (bool) – Whether the tally has total energy bins

Returns:

(regular_values, total_values) - values with totals removed, and the extracted totals

Return type:

tuple