Merge pull request #228 from smpark7/eigenvalue-executioner

Update action and tests for the Eigenvalue executioner

doc/content/getting_started/eigenvalue.md

@@ -19,11 +19,34 @@ respectively.
        style=width:35%;text-align:center;margin-left:auto;margin-right:auto;
 
 For multiplication factor ($k$) eigenvalue calculations, Moltres relies on the
-`InversePowerMethod` or `NonlinearEigen` executioners from MOOSE. These executioners solve the
+`Eigenvalue` executioner from MOOSE. These executioners solve the
 neutron diffusion equations set up as an eigenvalue problem to find $k$ and the neutron flux
 distribution, which occur as the absolute minimum eigenvalue $1/k$ and the corresponding
-eigenvector of the system. The mathematical background and documentation for these executioners can
-be found [here](https://mooseframework.inl.gov/source/executioners/InversePowerMethod.html). This
-tutorial uses the `InversePowerMethod` executioner which applies the inverse power method.
+eigenvector of the system.
 
+The MOOSE Action system allows us to streamline and simplify creating input files for Moltres
+simulations. You will have encountered the `PrecursorAction` object in Tutorial 2a for setting up
+input parameters for delayed neutron precursors. `PrecursorAction` automatically sets up the
+required Variables, Kernels, BCs, etc. governing precursor production, decay, and drift. Otherwise,
+users will need to fill in every input object for six or eight precursor groups, which would
+undoubtedly result in a very long input file prone to typos and user error. Similarly, we created
+NtAction for neutron group fluxes since many reactor simulations involve more than two neutron
+energy groups.
 
+Both `nts.i` and `nts-action.i` set up the same eigenvalue problem for a 2-D axisymmetric MSRE
+model. The model parameters are as follows:
+
+- Two neutron energy groups
+- Six delayed neutron precursor groups
+- Vacuum boundary conditions along the top, bottom and outer boundaries of the axisymmetric
+  cylinder
+- Uniform temperature of 900K
+- Uniform salt flow upwards along the fuel channels at 18.085cm/s
+- No salt looping (precursors that flow out of the core without decaying are considered lost)
+
+
+Both input files produce the same neutron flux and precursor distributions. You may compare them to
+identify the objects that NtAction automatically initializes, and appreciate how much cleaner
+`nts-action.i` looks compared to `nts.i`.
+
+Results and discussion to come at a later date.

doc/content/getting_started/input_syntax.md

@@ -179,6 +179,21 @@ extension). To generate a mesh for use with Moltres, a typical bash command is
 dimension of the mesh, the argument following `-o` is the name of the output
 `.msh` file, and the last argument is the input `.geo` file.
 
+## Problem Block id=problem
+
+The `Problem` block is used to indicate the type of problem we are solving. MOOSE automatically
+identifies which problem class is suitable for your simulation type (e.g., `FEProblem` or
+`EigenProblem`). However, for this particular input file, we want to set the `bx_norm` parameter
+for determining the eigenvalue estimate during each iteration of the eigensolver. Therefore, this
+input file requires us to indicate the problem type and the `bx_norm` parameter.
+
+```
+[Problem]
+  type = EigenProblem
+  bx_norm = bnorm
+[]
+```
+
 ## Variables Block id=variables
 
 The `Variables` block is used to indicate the primary solution variables, or
@@ -195,12 +210,10 @@ kernel and BC term must be associated with one primary variable from the
   [group1]
     order = FIRST
     family = LAGRANGE
-    initial_condition = 1
   []
   [group2]
     order = FIRST
     family = LAGRANGE
-    initial_condition = 1
   []
 []
 ```
@@ -314,7 +327,7 @@ Kernels can be optionally restricted to specific subdomains within the model by
 that is solved may differ in different mesh regions. The equations that are modeled
 are represented below, followed by the input required to construct these equations.
 In the `group1` and `group2` neutron flux equations below and in the input that
-follows, notice that the fission kernel (`CoupledFissionEigenKernel`)
+follows, notice that the fission kernel (`CoupledFissionKernel`)
 is only included in the fuel region ('0'), and is not included in the moderator region ('1')
 since there is no fuel in the moderator region. Also, the `DelayedNeutronSource`
 kernel, which contributes neutrons from the precursor group equations, is only
@@ -328,10 +341,14 @@ included as part of the `group1` or fast group equation.
   + \underbrace{\Sigma_g^r \phi_g}_{SigmaR}
   - \underbrace{\nabla \cdot D_g \nabla \phi_g}_{GroupDiffusion}
   - \underbrace{\sum_{g \ne g'}^G \Sigma_{g'\rightarrow g}^s \phi_{g'}}_{InScatter}
-  - \underbrace{\chi_g^p \sum_{g' = 1}^G (1 - \beta) \nu \Sigma_{f,g'} \phi_{g'}}_{\substack{CoupledFissionKernel\\ \textrm{'Fuel' region only}}}
+  - \underbrace{\chi_g^p \sum_{g' = 1}^G (1 - \beta) \frac{\nu \Sigma_{f,g'}}{k} \phi_{g'}}_{\substack{CoupledFissionKernel\\ \textrm{'Fuel' region only}}}
   - \underbrace{\chi_g^d \sum_i^I \lambda_i C_i}_{\substack{DelayedNeutronSource\\ \textrm{'Fuel' region only} \\ \textrm{Not in group2 Eqn}}}
   = 0
 
+The `extra_vector_tags = eigen` parameter indicates all kernels to be scaled by the $1/k$
+eigenvalue in this eigenvalue problem. This parameter is omitted for non-eigenvalue problems
+discussed in the other tutorial problems.
+
 ```
 [Kernels]
   #---------------------------------------------------------------------
@@ -353,10 +370,11 @@ included as part of the `group1` or fast group equation.
     group_number = 1
   []
   [fission_source_group1]
-    type = CoupledFissionEigenKernel
+    type = CoupledFissionKernel
     variable = group1
     group_number = 1
     block = '0'
+    extra_vector_tags = 'eigen'
   []
   [delayed_group1]
     type = DelayedNeutronSource
@@ -379,10 +397,11 @@ included as part of the `group1` or fast group equation.
     group_number = 2
   []
   [fission_source_group2]
-    type = CoupledFissionEigenKernel
+    type = CoupledFissionKernel
     variable = group2
     group_number = 2
     block = '0'
+    extra_vector_tags = 'eigen'
   []
   [inscatter_group2]
     type = InScatter
@@ -479,37 +498,19 @@ basic instructions.
 
 ```
 [Executioner]
-  type = InversePowerMethod
-  max_power_iterations = 50
-
-  normalization = 'powernorm'
-  normal_factor = 8e6
-
-  xdiff = 'group1diff'
-  bx_norm = 'bnorm'
-  k0 = 1.
-  l_max_its = 100
-  eig_check_tol = 1e-7
+  type = Eigenvalue
+  initial_eigenvalue = 1
+  solve_type = 'PJFNK'
+  petsc_options = '-snes_converged_reason -ksp_converged_reason -snes_linesearch_monitor'
+  petsc_options_iname = '-pc_type -pc_hypre_type'
+  petsc_options_value = 'hypre boomeramg'
 
   automatic_scaling = true
   compute_scaling_once = false
   resid_vs_jac_scaling_param = 0.1
-  off_diagonals_in_auto_scaling = false
-
-  solve_type = 'NEWTON'
-  petsc_options = '-snes_converged_reason -ksp_converged_reason -snes_linesearch_monitor'
-  petsc_options_iname = '-pc_type -pc_factor_shift_type'
-  petsc_options_value = 'lu       NONZERO'
 
   line_search = none
 []
-
-[Preconditioning]
-  [./SMP]
-    type = SMP
-    full = true
-  [../]
-[]
 ```
 
 ## Postprocessors Block id=postprocessors
@@ -518,17 +519,23 @@ A `PostProcessor` computes a single scalar value during the simulations.
 General postprocessor documentation can be found
 [here](https://www.mooseframework.org/syntax/Postprocessors/index.html). 
 
-The `bnorm`, `tot_fissions`, and `powernorm` parameters calculate the total number of fission
-neutrons, fission interactions, and fission heat, respectively. The `bnorm` parameter is required
-by the `InversePowerMethod` executioner as a normalization term for inverse power iterations. The
-other two may be used to normalize the flux solution at the end of the calculation through the
-`normalization` and `normal_factor` parameters in the `Executioner` block. The `group1diff`
-postprocessor is also required by the `InversePowerMethod` executioner for Chebyshev acceleration.
-The rest of the postprocessors calculate the integral sum or maximum values of the `group1` and
-`group2` flux variables.
+`k_eff` retrieves the real part of the computed eigenvalue which is taken to be the $k$
+multiplication factor. The `bnorm`, `tot_fissions`, and `powernorm` postprocessor objects calculate
+the total number of fission neutrons, fission interactions, and fission heat, respectively. The
+`bnorm` parameter is required by the `Eigenvalue` executioner as an estimate for $k$ in each
+iteration. The other two may be used to normalize the flux solution at the end of
+the calculation through the `normalization` and `normal_factor` parameters in the `Executioner`
+block. The rest of the postprocessors calculate the integral sum, diff, or maximum values
+of the `group1` and `group2` flux variables.
 
 ```
 [Postprocessors]
+  [k_eff]
+    type = VectorPostprocessorComponent
+    index = 0
+    vectorpostprocessor = k_vpp
+    vector_name = eigen_values_real
+  []
   [bnorm]
     type = ElmIntegTotFissNtsPostprocessor
     execute_on = linear
@@ -601,8 +608,9 @@ values during the simulation, which may be desired when running test runs.
 
 ## Debug Block id=debug
 
-This simply tells Moltres to print the variable residual norms during the
-non-linear solve.
+This parameter tells Moltres to print the variable residual norms during the
+non-linear solve. Residual information is useful for debugging convergence issues by identifying
+which variable is exhibiting slow or no convergence behavior.
 
 ```
 [Debug]

include/actions/NtAction.h

@@ -36,4 +36,36 @@ class NtAction : public VariableNotAMooseObjectAction
 
   /// number of energy groups
   unsigned int _num_groups;
+
+  /**
+  * Adds non-source neutronics kernel
+  *
+  * @param op The zero-based index for the precursor group the kernel acts on
+  * @param var_name The name of the variable the kernel acts on
+  * @param kernel_type The kernel type to be added
+  * @param all_var_names Vector of the names of all group flux variables
+  */
+  void addNtKernel(const unsigned & op,
+                   const std::string & var_name,
+                   const std::string & kernel_type,
+                   const std::vector<VariableName> & all_var_names);
+
+  /**
+  * Adds CoupledFissionKernel kernel
+  *
+  * @param op The zero-based index for the precursor group the kernel acts on
+  * @param var_name The name of the variable the kernel acts on
+  * @param all_var_names Vector of the names of all group flux variables
+  */
+  void addCoupledFissionKernel(const unsigned & op,
+                               const std::string & var_name,
+                               const std::vector<VariableName> & all_var_names);
+
+  /**
+  * Adds DelayedNeutronSource kernel
+  *
+  * @param op The zero-based index for the precursor group the kernel acts on
+  * @param var_name The name of the variable the kernel acts on
+  */
+  void addDelayedNeutronSource(const unsigned & op, const std::string & var_name);
 };