pyopensn.solver.CMFDAcceleration

class pyopensn.solver.CMFDAcceleration

Construct a CMFD accelerator for the power iteration k-eigenvalue solver.

Wrapper of opensn::CMFDAcceleration.

__init__(self: pyopensn.solver.CMFDAcceleration, **kwargs) → None

CMFD acceleration for the power iteration k-eigenvalue solver.

With CMFD, each power iteration performs a configured number of high-order WGS transport update iterations, then applies a bounded low-order scalar-flux correction. The defaults use one WGS update iteration, automatic current closure, fixed correction relaxation, and a transport-current balance gate before outer power iteration is allowed to converge.

Most users should tune only the common controls: coarse_mesh, current_closure, aggregation_size, group_aggregation_size, relaxation, update_wgs_max_its, update_wgs_abs_tol, and balance_residual_tolerance. Parameters marked “developer/debug” are exposed for investigations and regression testing, but normally should be left at their defaults.

Parameters:

• problem (pyopensn.solver.DiscreteOrdinatesProblem) – Existing DiscreteOrdinatesProblem instance.

• coarse_mesh (str, default="local_aggregation") –

  Common option. Coarse-mesh construction method. Valid choices are:

  • ’identity’ : one CMFD coarse cell per transport cell

  • ’local_aggregation’ : connected same-block fine cells aggregated locally

  • ’global_aggregation’ : connected same-block fine cells aggregated across MPI ranks

  "local_aggregation" is the conservative default. "global_aggregation" can reduce the coarse problem size on larger distributed meshes. Global aggregation is a logical CMFD coarse-space construction: it does not repartition the transport mesh or change fine-cell ownership. Each global coarse cell has one owning rank, while ranks owning member fine cells keep membership records for restriction and prolongation. Aggregates are connected by face adjacency, remain within one mesh block, and may be smaller than aggregation_size near boundaries or disconnected regions. "identity" is primarily for debugging and method comparisons.

• current_closure (str, default="auto") –

  Common option. CMFD face-current closure. Valid choices are:

  • ’auto’ : choose net, partial, or a blend from early coarse-balance behavior

  • ’net’ : match the signed transport current across each coarse face

  • ’partial’ : build face coupling from outgoing partial currents on both sides

  "auto" is recommended for production use. A fixed closure is useful when comparing methods, reproducing a benchmark setting, or diagnosing a case where automatic selection is not robust.

• aggregation_size (int, default=32) – Common option. Target number of fine cells per aggregated coarse cell for coarse_mesh="local_aggregation" or coarse_mesh="global_aggregation". Larger values reduce CMFD matrix size and setup/solve cost, but make the spatial correction less detailed. Smaller values increase the coarse-system cost but may improve robustness.

• group_aggregation_size (int, default=1) – Common option. Number of transport energy groups per CMFD coarse group, not the final number of coarse groups. A value of 1 preserves the full transport group structure in the low-order system. To target N total coarse groups, use (num_groups + N - 1) // N.

• relaxation (float, default=0.5) – Common option. Relaxation factor applied to the CMFD scalar-flux correction. This is the requested correction strength. The correction limiter may damp or skip an individual correction if the requested update would produce an invalid k-eigenvalue, non-finite flux, or excessive negative scalar flux.

• update_wgs_max_its (int, default=1) – Common option. Maximum WGS iterations used before each CMFD correction. The default performs one transport update iteration per power iteration; larger values make each transport update more accurate but more expensive.

• update_wgs_abs_tol (float, default=1.0e-12) – Common option. WGS absolute tolerance used before each CMFD correction. When update_wgs_max_its=1, this tolerance is normally not the stopping criterion because only one WGS iteration is allowed. It matters when more WGS iterations are allowed.

• balance_residual_tolerance (float, default=1.0e-6) – Common option. Restricted transport-current balance residual tolerance required before CMFD permits outer power-iteration convergence. This prevents false convergence when k_eff_change is small but the CMFD-restricted transport balance is still inconsistent. This is a consistency guard, not an estimate of the k-eigenvalue error. For large 3D cases it may need to be looser than the outer k_tol; choose it tight enough to prevent false convergence but not so tight that it forces unnecessary asymptotic balance iterations.

• l_abs_tol (float, default=1.0e-7) – Developer/debug. Absolute residual tolerance for each CMFD coarse linear solve. This affects the low-order linear solve, not the outer transport convergence.

• max_iters (int, default=100) – Developer/debug. Maximum iterations for each CMFD coarse linear solve. Increase only if the coarse KSP solve is reaching its iteration limit. CMFD skips a correction when any coarse linear solve fails to converge within this limit. If the log reports correction = skipped (coarse_linear_solve_not_converged), use a direct coarse solve for modest coarse systems, increase this limit for iterative solves, or provide stronger petsc_options.

• verbose (bool, default=False) – Developer/debug. If true, prints CMFD diagnostic and timing metrics. These are useful for regression tests and performance studies but can be noisy in production.

• petsc_options (str, default="") – Developer/debug. Additional PETSc options for the CMFD coarse solver. Used only for solver experiments, especially with coarse_solver_policy="petsc_options".

• pi_max_its (int, default=50) – Developer/debug. Maximum inner power iterations for the CMFD coarse k solve. Increase only if the coarse k solve is not converging enough to give useful corrections.

• pi_k_tol (float, default=1.0e-8) – Developer/debug. k-eigenvalue tolerance for CMFD coarse power iterations. This is separate from the outer PowerIterationKEigenSolver k tolerance.

• correction_max_attempts (int, default=10) – Developer/debug. Maximum CMFD correction damping attempts before skipping the correction for the current transport update. Each failed attempt halves the damping. If the log reports correction = skipped (negative_flux_guard), first reduce relaxation or use finer spatial/energy aggregation; changing this option is mainly for diagnostics.

• correction_min_damping (float, default=1.0e-4) – Developer/debug. Minimum CMFD correction damping factor considered during correction limiting. If no admissible correction is found above this damping, CMFD skips the correction for that transport update.

• negative_flux_tolerance (float, default=1.0e-6) – Developer/debug. Allowed scalar-flux undershoot for accepting a CMFD correction. Corrections producing scalar flux below this guard are damped or skipped. Raising this value can hide unstable corrections and should be accompanied by final-k and scalar-flux checks.

• inactive_iterations (int, default=0) – Developer/debug. Number of initial power iterations before applying CMFD corrections. Transport update controls are still used during these iterations.

• coarse_solver_policy (str, default="auto") –

  Developer/debug. Coarse solver policy. Valid choices are:

  • ’auto’ : PETSc preonly+LU below coarse_direct_solve_threshold global unknowns, GMRES+Jacobi otherwise

  • ’direct’ : PETSc preonly+LU

  • ’iterative’ : GMRES+Jacobi

  • ’petsc_options’ : allow petsc_options to override the PETSc KSP/PC setup

  CMFD corrections from unconverged coarse linear solves are always skipped. The skipped correction uses the unaccelerated transport update for that power iteration; after repeated skipped corrections, CMFD returns the raw transport k update so that power iteration can continue to move.

• coarse_direct_solve_threshold (int, default=20000) – Developer/debug. Maximum global CMFD unknown count for automatic direct coarse solves when coarse_solver_policy="auto". Larger values make "auto" use direct solves for larger coarse systems; choose values based on available host memory and acceptable factorization cost.