Coupled operators¶

These functions expose Morana’s independently callable finite-volume assembly surface. Start with extract_cross_section_data(snapshot), then pass the complete layered data and the same snapshot to the loss, fission, and right-hand-side assemblers. Each function can also capture a mutable configuration, but an explicit snapshot keeps several assembly calls on one stable problem definition. Assemblers return fresh mutable SciPy sparse matrices or NumPy vectors; extracted compact data are immutable snapshots. Read direct finite-volume operator assembly for data flow, layout, and ownership conventions and the finite-volume theory for the assembled equations.

operators ¶

Finite-volume operator assembly helpers.

CrossSectionData `dataclass` ¶

CrossSectionData(layers: tuple[CrossSectionLayerData, ...])

Store compact cross sections for all axial material layers.

Parameters:

Name	Type	Description	Default
`layers`	`tuple[CrossSectionLayerData, ...]`	Bottom-to-top iterable of compact layer data using a common group count.	required

Attributes:

Name	Type	Description
`layers`	`tuple[CrossSectionLayerData, ...]`	Bottom-to-top tuple of compact cross-section layers.
`groups`	`int`	Shared positive number of energy groups.
`n_axial_layers`	`int`	Number of stored axial layers.

Raises:

Type	Description
`TypeError`	If `layers` is not iterable or contains values other than `CrossSectionLayerData`.
`ValueError`	If no layer is supplied, the layers contain no active cells, or the supplied layers do not use a common group count.

Notes

This container preserves slice-local active-cell numbering. Global node-major packing is created only by the assembly helpers. Layers and their CrossSectionLayerData entries are immutable checked input snapshots for one assembly scope.

groups `property` ¶

groups: int

Return the number of energy groups.

n_axial_layers `property` ¶

n_axial_layers: int

Return the number of axial material layers.

layer ¶

layer(axial_index: int) -> CrossSectionLayerData

Return cross-section data for one axial layer.

Parameters:

Name	Type	Description	Default
`axial_index`	`int`	Zero-based axial-layer index.	required

Returns:

Type	Description
`CrossSectionLayerData`	Compact data for the selected layer.

Raises:

Type	Description
`TypeError`	If `axial_index` is not an integer.
`IndexError`	If `axial_index` does not select a stored layer.

CrossSectionLayerData `dataclass` ¶

CrossSectionLayerData(
    axial_index: int,
    diffusion: ndarray,
    sigma_a: ndarray,
    sigma_s: ndarray,
    multiplicity_matrix: ndarray,
    fission_transfer: ndarray,
    material_by_active_id: Mapping[int, str],
)

Store compact group-indexed cross sections for one axial layer.

Parameters:

Name	Type	Description	Default
`axial_index`	`int`	Zero-based axial-layer index.	required
`diffusion`	`ndarray`	Diffusion coefficients shaped `(groups, active_cells)`.	required
`sigma_a`	`ndarray`	Absorption cross sections shaped `(groups, active_cells)`.	required
`fission_transfer`	`ndarray`	Fission-neutron transfer cross sections shaped `(groups, groups, active_cells)` and event-oriented as `fission_transfer[g_from, g_to, active_id]`.	required
`sigma_s`	`ndarray`	Complete ordinary scattering-event matrices shaped `(groups, groups, active_cells)` and indexed from-group, to-group.	required
`multiplicity_matrix`	`ndarray`	Resolved scattering-neutron emission multiplicities shaped `(groups, groups, active_cells)` and indexed from-group, to-group.	required
`material_by_active_id`	`Mapping[int, str]`	Compact active-ID-to-material mapping for this layer.	required

Attributes:

Name	Type	Description
`axial_index`	`int`	Zero-based axial-layer index associated with every stored array.
`diffusion, sigma_a, sigma_s, multiplicity_matrix, fission_transfer`		Owned read-only arrays using the documented group-major conventions.
`sigma_r`	`ndarray`	Fresh read-only conventional removal array shaped `(groups, active_cells)`.
`scattering_coupling`	`ndarray`	Fresh read-only signed scattering-neutron coupling shaped `(groups, groups, active_cells)`.
`fission_production`	`ndarray`	Fresh read-only incident-group fission-neutron production shaped `(groups, active_cells)` and derived by summing the outgoing-group axis of `fission_transfer`.
`material_by_active_id`	`Mapping[int, str]`	Copied slice-local compact material provenance with contiguous IDs.

Raises:

Type	Description
`TypeError`	If `axial_index` is not an integer, `material_by_active_id` is not a mapping, its IDs are not integers, or its material names are not strings.
`ValueError`	If no energy group is supplied, array shapes, finite nonnegative values, or compact material IDs are invalid.

Notes

sigma_r and scattering_coupling are derived from ordinary event data and resolved multiplicities. Array values are copied so later changes to constructor inputs cannot change an assembled operator. The stored arrays and copied material_by_active_id mapping are immutable. Construct a replacement value when changing compact cross-section data.

active_cells `property` ¶

active_cells: int

Return the number of active cells.

fission_production `property` ¶

fission_production: ndarray

Return fresh read-only fission-neutron production by incident group.

groups `property` ¶

groups: int

Return the number of energy groups.

scattering_coupling `property` ¶

scattering_coupling: ndarray

Return fresh read-only signed scattering-neutron coupling.

sigma_r `property` ¶

sigma_r: ndarray

Return fresh read-only conventional absorption-plus-outscatter removal.

assemble_boundary_rhs ¶

assemble_boundary_rhs(
    configuration: (
        ProblemConfiguration | ProblemConfigurationSnapshot
    ),
    cross_sections: CrossSectionData,
) -> np.ndarray

Assemble prescribed-flux and incoming-current boundary sources.

Parameters:

Name	Type	Description	Default
`configuration`	`ProblemConfiguration \| ProblemConfigurationSnapshot`	Mutable problem configuration or immutable snapshot with complete exposed-face boundary coverage. A mutable configuration is captured at entry.	required
`cross_sections`	`CrossSectionData`	Complete layered compact data corresponding to `configuration`.	required

Returns:

Type	Description
`ndarray`	Fresh mutable node-major, group-fastest global boundary-source vector. It contains only additive prescribed-flux and imposed-current boundary terms, integrated over their selected exposed faces.

Raises:

Type	Description
`TypeError`	If `configuration` is neither `ProblemConfiguration` nor `ProblemConfigurationSnapshot`, or `cross_sections` is not a `CrossSectionData`.
`ValueError`	If compact data are incomplete or do not match the configuration; exposed faces lack complete, group-compatible boundary coverage; or integrated boundary entries are nonfinite or negative.

Notes

A fixed source is not required. Homogeneous conditions produce no additive entry; their response remains in assemble_loss_matrix().

assemble_fission_matrix ¶

assemble_fission_matrix(
    configuration: (
        ProblemConfiguration | ProblemConfigurationSnapshot
    ),
    cross_sections: CrossSectionData,
) -> csr_matrix

Assemble global volume-integrated fission emission.

Parameters:

Name	Type	Description	Default
`configuration`	`ProblemConfiguration \| ProblemConfigurationSnapshot`	Mutable problem configuration or immutable snapshot owning the material layout. A mutable configuration is captured at entry.	required
`cross_sections`	`CrossSectionData`	Complete layered compact data corresponding to `configuration`.	required

Returns:

Type	Description
`csr_matrix`	Fresh mutable node-major, group-fastest fission-emission matrix. For cell `n`, it maps source group `g_from` to destination group `g_to` with `fission_transfer[g_from, g_to, n] * volume[n]`.

Raises:

Type	Description
`TypeError`	If `configuration` is neither `ProblemConfiguration` nor `ProblemConfigurationSnapshot`, or `cross_sections` is not a `CrossSectionData`.
`ValueError`	If compact data are not complete or do not match the configuration layout, or volume-integrated fission entries are nonfinite or negative.

Notes

This independent assembly operation does not require a fixed source or boundary coverage. It returns fission emission only; the solver forms the fixed-source operator as loss minus this matrix. Its column sums are checked against the volume-integrated incident-group production functional, which verifies transfer orientation and volume integration for either public fission representation.

assemble_loss_matrix ¶

assemble_loss_matrix(
    configuration: (
        ProblemConfiguration | ProblemConfigurationSnapshot
    ),
    cross_sections: CrossSectionData,
) -> csr_matrix

Assemble diffusion loss, removal, and scattering coupling.

Parameters:

Name	Type	Description	Default
`configuration`	`ProblemConfiguration \| ProblemConfigurationSnapshot`	Mutable problem configuration or immutable snapshot with complete exposed-face boundary coverage. A mutable configuration is captured at entry.	required
`cross_sections`	`CrossSectionData`	Compact data extracted from the same configuration.	required

Returns:

Type	Description
`csr_matrix`	Fresh mutable node-major, group-fastest global loss matrix. It combines removal, scattering coupling, radial/axial leakage, and resolved boundary response.

Raises:

Type	Description
`TypeError`	If `configuration` is neither `ProblemConfiguration` nor `ProblemConfigurationSnapshot`, or `cross_sections` is not a `CrossSectionData`.
`ValueError`	If compact data are not complete or do not match the configuration, diffusion coefficients are invalid, exposed faces lack complete group-compatible boundary coverage, or assembled entries fail their finite/sign checks.

Notes

In the packed system, diagonal loss entries are positive and transfer or neighbor couplings are nonpositive. Inhomogeneous boundary data add both a response contribution here and a separate contribution from assemble_boundary_rhs(). No volumetric source is required.

assemble_source_rhs ¶

assemble_source_rhs(
    configuration: (
        ProblemConfiguration | ProblemConfigurationSnapshot
    ),
    cross_sections: CrossSectionData,
) -> np.ndarray

Assemble the volume-integrated volumetric source right-hand side.

Parameters:

Name	Type	Description	Default
`configuration`	`ProblemConfiguration \| ProblemConfigurationSnapshot`	Mutable problem configuration or immutable snapshot. Boundary coverage is not required by this independent assembly operation. A mutable configuration is captured at entry.	required
`cross_sections`	`CrossSectionData`	Complete layered compact data corresponding to `configuration`.	required

Returns:

Type	Description
`ndarray`	Fresh mutable node-major, group-fastest global source vector. Each volumetric source value is multiplied by its selected cell volume. If no volumetric source is configured, the vector is zero.

Raises:

Type	Description
`TypeError`	If `configuration` is neither `ProblemConfiguration` nor `ProblemConfigurationSnapshot`, or `cross_sections` is not a `CrossSectionData`.
`ValueError`	If compact data are incomplete or do not match the configuration layout; a cell source has the wrong layer count; or evaluated source values have an invalid shape, are nonfinite, negative, or overflow after volume integration.

Notes

Boundary coverage is not required. This function assembles only the volumetric fixed-source term; add assemble_boundary_rhs() separately when an inhomogeneous resolved boundary is present.

extract_cross_section_data ¶

extract_cross_section_data(
    configuration: (
        ProblemConfiguration | ProblemConfigurationSnapshot
    ),
) -> CrossSectionData

Extract compact group-indexed data for every axial material layer.

Parameters:

Name	Type	Description	Default
`configuration`	`ProblemConfiguration \| ProblemConfigurationSnapshot`	Mutable problem configuration or immutable snapshot containing cross sections for every active material. Boundary coverage and a source are not required. A mutable configuration is captured at entry.	required

Returns:

Type	Description
`CrossSectionData`	Owned compact arrays in bottom-to-top, slice-local active-ID order. Complete ordinary `sigma_s` and resolved multiplicity arrays; removal and coupling are derived, and nonfissionable positions receive zero fission-transfer blocks. Fissionable positions retain the canonical event-oriented transfer data regardless of whether their material supplied separable or general transfer input.

Raises:

Type	Description
`TypeError`	If `configuration` is neither `ProblemConfiguration` nor `ProblemConfigurationSnapshot`.
`ValueError`	If no material-mesh cell is active, active materials are missing or lack cross sections, or active materials use inconsistent energy-group counts.

Notes

Extraction is independent of source and boundary data. The returned object is suitable for public assembly with the same selected snapshot. Pass a snapshot explicitly when several operator calls must use one stable problem definition.

Coupled operators¶

operators ¶

CrossSectionData dataclass ¶

groups property ¶

n_axial_layers property ¶

layer ¶

CrossSectionLayerData dataclass ¶

active_cells property ¶

fission_production property ¶

groups property ¶

scattering_coupling property ¶

sigma_r property ¶

assemble_boundary_rhs ¶

assemble_fission_matrix ¶

assemble_loss_matrix ¶

assemble_source_rhs ¶

extract_cross_section_data ¶

CrossSectionData `dataclass` ¶

groups `property` ¶

n_axial_layers `property` ¶

CrossSectionLayerData `dataclass` ¶

active_cells `property` ¶

fission_production `property` ¶

groups `property` ¶

scattering_coupling `property` ¶

sigma_r `property` ¶