surface postprocessors

[ragusa]

Surface Post-Processor (SPP) Specification

Goal

The Surface Post-Processor (SPP) computes face-based, current-like quantities derived from the angular flux on a user-defined set of surfaces. Surfaces are selected by a surface filter that may reference boundary IDs (external domain perimeter), named/user-defined face sets (including internal surfaces), and optionally MPI rank-interface faces. In addition, the user may provide an optional list of logical volumes to further restrict which faces are included; this logical-volume filter is applied as an additional AND constraint on top of the surface selection. The SPP uses the built-in directional factor $\Omega\cdot n$ (not user-configurable) and supports angular integration modes for net, outgoing, or incoming contributions. By default, results are summed over all energy groups, with options to return per-group results or user-defined group-set (macro-group) collapsed results. Internal or MPI-interface surface post-processing is only valid if angular flux storage was enabled in the simulation.

• Provide a consistent, extensible mechanism to compute boundary leakage and surface currents from angular flux.
• Clearly separate surface-based post-processing from volumetric scalar-flux post-processing.
• Support both simple boundary-ID based use cases and advanced user-defined internal surface sets.
• Allow optional restriction of surface tallies to faces adjacent to user-specified logical volumes.

---

Scope

In scope

• Angular-flux-based surface QoIs on selected faces.
• Surface selection via boundary IDs and user-defined surface/face sets.
• Optional logical-volume restriction on top of surface selection.
• Angular integration modes: net, outgoing, incoming.
• Energy aggregation modes: all-groups (default), per-group, group-sets.
• Global reductions over the selected faces.

Out of scope (v1)

• User-defined multipliers beyond the built-in $\Omega\cdot n$.
• Per-neighbor-rank or per-partition-island reporting for MPI interfaces.

---

Definitions

Let:

• $f$ be a face, $g\in{1,\dots,G}$ an energy group.
• $A_f$ the face area.
• $n_f$ outward normal (well-defined for boundary faces; for internal faces, orientation must be specified or implied by the face-set definition).
• $\psi_{i,g}(\Omega)$ the angular flux at DoF $i$ on face $f$, group $g$.
• $DOF(f)$ the set of DoFs associated with face $f$.
• $S$ the selected set of faces after filtering.

Built-in directional factor (not user-configurable):
$$
(\Omega \cdot n_f)
$$

Per-face angularly integrated quantities:

• Net current
  $$
  j_{f,g}^{net} = \int_{4\pi} (\Omega\cdot n_f),\sum_{i \in DOF(f)} \psi_{i,g}(\Omega),d\Omega
  $$
• Outgoing current
  $$
  j_{f,g}^{+} = \int_{\Omega\cdot n_f>0} (\Omega\cdot n_f),\sum_{i \in DOF(f)} \psi_{i,g}(\Omega),d\Omega
  $$
• Incoming current
  $$
  j_{f,g}^{-} = \int_{\Omega\cdot n_f<0} (\Omega\cdot n_f),\sum_{i \in DOF(f)} \psi_{i,g}(\Omega),d\Omega
  $$

---

Surface filter specification

User inputs

A surface filter must be able to select faces by one of:

1. boundary_ids (external perimeter faces)
2. surface_sets (named/user-defined face sets; may include internal faces)
3. mpi_interface (optional; union of rank-interface faces)

Optional additional restriction:

• logical_volumes (optional list of logical volume names)

Inclusion rule

A face $f$ is included if:

1. It belongs to the chosen surface_filter.type category and matches the user-provided IDs/names,
   AND
2. If logical_volumes is provided, $f$ must be adjacent to at least one cell that belongs to at least one of the listed logical volumes.

Recommended predicate:

• Let $L$ be the optional set/list of logical volumes.
• Let $AdjCells(f)$ be the set of cells adjacent to face $f$ (1 cell for boundary faces, 2 for internal).

Then:
$$
f \in S \iff
(\text{matches surface filter})
\ \land
\bigl(L\ \text{unspecified} \ \lor\ \exists c \in AdjCells(f): c \in L \bigr)
$$

Notes:

• boundary_ids should map to mesh/BC-provided face tags.
• surface_sets must allow user-defined internal surfaces.
• mpi_interface, if enabled in v1, should represent the union of all faces whose adjacent cells are owned by different MPI ranks.
• The logical-volume filter is intended to let users restrict a boundary-ID or surface-set SPP to a sub-region of the domain without introducing material-based filtering on faces.

---

Angular-flux requirement rules

• Boundary-ID SPP: requires angular flux if computing any current-like quantity (default assumption).
• Internal surface-set SPP: requires store_angular_flux = true (or equivalent).
• MPI-interface SPP (if supported): requires store_angular_flux = true.

SPP must reject or clearly error if an internal/MPI-interface SPP is requested without angular flux storage.

---

Angular integration modes

SPP must support:

• net (default TBD)
• outgoing ($\Omega\cdot n&gt;0$)
• incoming ($\Omega\cdot n&lt;0$)

No additional user-defined angular multipliers in v1.

---

Energy handling

Default

• energy.mode = all_groups
  Return results summed over all groups.

Supported modes

1. all_groups
   $$
   Q = \sum_{g=1}^G Q_g
   $$
2. per_group
   Return $Q_g$ for all $g$.
3. group_sets
   User provides named group sets $\mathcal{G}k$:
   $$
   Q_k = \sum{g\in \mathcal{G}_k} Q_g
   $$

---

Spatial reductions (outputs)

For each group $g$, and chosen angular mode $m \in {net, +, -}$:

• Surface integral
  $$
  Q_{g}^{int} = \sum_{f\in S} j_{f,g}^{m},A_f
  $$
• Surface average
  $$
  Q_{g}^{avg} =
  \frac{\sum_{f\in S} j_{f,g}^{m},A_f}{\sum_{f\in S} A_f}
  $$
• Min / Max (face-wise)
  $$
  Q_{g}^{min} = \min_{f\in S} j_{f,g}^{m}, \quad
  Q_{g}^{max} = \max_{f\in S} j_{f,g}^{m}
  $$

---

Orientation / normals

• For boundary faces, outward normals are defined by the mesh.
• For internal face sets, the SPP must define or require a consistent normal convention. Options:
  • normal orientation is stored with the face set, or
  • a documented deterministic rule is used (e.g., local cell ordering), and the choice is documented.

---

Output shape rules

The final output dimensions are determined by:

• selected reductions × angular mode × energy mode

Examples:

• surface_integral + outgoing + all_groups → single scalar
• surface_average + net + per_group → length $G$ vector
• max + incoming + group_sets → length $K$ vector