MFEMMatrixFreeAMS

Overview

Defines and builds an mfem::MatrixFreeAMS low-order refined (LOR) solver to use as a matrix-free preconditioner for a curl-curl problem of the form

var element = document.getElementById("moose-equation-2ea5aa87-02ba-49e1-86a5-a67a869acad8");katex.render("(\\alpha \\vec \\nabla \\times \\vec u, \\vec \\nabla \\times \\vec v)_\\Omega + (\\beta \\vec u, \\vec v)_\\Omega = (\\vec f, \\vec v)_\\Omega \\,\\,\\, \\forall \\vec v \\in V", element, {displayMode:true,throwOnError:false,macros:{"\\eqc":"\\,,","\\eqp":"\\,.","\\pd":"\\frac{\\partial #1}{\\partial #2}","\\pr":"\\left(#1\\right)","\\ddt":"\\frac{d #1}{d t}"}});

where $var element = document.getElementById("moose-equation-18f02fbd-b86a-4a88-a7e1-9e439b5360eb");katex.render("\\vec u, \\vec v \\in H(\\mathrm{curl})", element, {displayMode:false,throwOnError:false,macros:{"\\eqc":"\\,,","\\eqp":"\\,.","\\pd":"\\frac{\\partial #1}{\\partial #2}","\\pr":"\\left(#1\\right)","\\ddt":"\\frac{d #1}{d t}"}});$ and $var element = document.getElementById("moose-equation-a60e90eb-8cbb-43ca-b403-0b6e1b4b7fbe");katex.render("\\alpha", element, {displayMode:false,throwOnError:false,macros:{"\\eqc":"\\,,","\\eqp":"\\,.","\\pd":"\\frac{\\partial #1}{\\partial #2}","\\pr":"\\left(#1\\right)","\\ddt":"\\frac{d #1}{d t}"}});$ and $var element = document.getElementById("moose-equation-bbe676f8-f4f2-4041-aafe-7c7e279866de");katex.render("\\beta", element, {displayMode:false,throwOnError:false,macros:{"\\eqc":"\\,,","\\eqp":"\\,.","\\pd":"\\frac{\\partial #1}{\\partial #2}","\\pr":"\\left(#1\\right)","\\ddt":"\\frac{d #1}{d t}"}});$ are scalar coefficients.

The number of CG iterations to use for inner solves on the auxiliary spaces associated with the Nédélec interpolation operator $var element = document.getElementById("moose-equation-9e9b3f10-abda-478c-a30d-284bff776369");katex.render("\\Pi", element, {displayMode:false,throwOnError:false,macros:{"\\eqc":"\\,,","\\eqp":"\\,.","\\pd":"\\frac{\\partial #1}{\\partial #2}","\\pr":"\\left(#1\\right)","\\ddt":"\\frac{d #1}{d t}"}});$ and the gradient operator $var element = document.getElementById("moose-equation-6c070141-a70d-41a9-b336-4c421739c547");katex.render("G", element, {displayMode:false,throwOnError:false,macros:{"\\eqc":"\\,,","\\eqp":"\\,.","\\pd":"\\frac{\\partial #1}{\\partial #2}","\\pr":"\\left(#1\\right)","\\ddt":"\\frac{d #1}{d t}"}});$ can be controlled by the inner_pi_iterations and inner_g_iterations parameters, which default to 0 and 1, respectively. Increasing these may aid convergence when $var element = document.getElementById("moose-equation-b8e7ce86-78b6-43ff-aa88-303a17685a48");katex.render("\\alpha", element, {displayMode:false,throwOnError:false,macros:{"\\eqc":"\\,,","\\eqp":"\\,.","\\pd":"\\frac{\\partial #1}{\\partial #2}","\\pr":"\\left(#1\\right)","\\ddt":"\\frac{d #1}{d t}"}});$ and/or $var element = document.getElementById("moose-equation-73d2d969-b5d8-422d-8724-6850a0b818a1");katex.render("\\beta", element, {displayMode:false,throwOnError:false,macros:{"\\eqc":"\\,,","\\eqp":"\\,.","\\pd":"\\frac{\\partial #1}{\\partial #2}","\\pr":"\\left(#1\\right)","\\ddt":"\\frac{d #1}{d t}"}});$ are highly discontinuous.

The method used corresponds to a matrix-free version of Hypre's AMS preconditioner (with default cycle 1), as described in Hypre's AMS documentation.

Implementation details for the mfem::MatrixFreeAMS preconditioner, along with some performance comparisons against Hypre's AMS preconditioner for 2D problems, can be found in this paper.

Example Input File Syntax

[Preconditioner<<<{"href": "../../../syntax/Preconditioner/index.html"}>>>]
  [ams]
    type = MFEMHypreAMS<<<{"description": "Hypre auxiliary-space Maxwell solver and preconditioner for the iterative solution of MFEM equation systems.", "href": "MFEMHypreAMS.html"}>>>
    fespace<<<{"description": "H(curl) FESpace to use in HypreAMS setup."}>>> = HCurlFESpace
  []
  [matrix_free_ams]
    type = MFEMMatrixFreeAMS<<<{"description": "MFEM matrix-free auxiliary-space Maxwell preconditioner for the iterative solution of MFEM equation systems.", "href": "MFEMMatrixFreeAMS.html"}>>>
  []
[]

[Solvers<<<{"href": "../../../syntax/Solvers/index.html"}>>>]
  active<<<{"description": "If specified only the blocks named will be visited and made active"}>>> = gmres
  [gmres]
    type = MFEMHypreGMRES<<<{"description": "Hypre solver for the iterative solution of MFEM equation systems using the generalized minimal residual method.", "href": "MFEMHypreGMRES.html"}>>>
    preconditioner<<<{"description": "Optional choice of preconditioner to use."}>>> = ams
    l_tol<<<{"description": "Set the relative tolerance."}>>> = 1e-12
  []
  [cg]
    type = MFEMCGSolver<<<{"description": "MFEM native solver for the iterative solution of MFEM equation systems using the conjugate gradient method.", "href": "MFEMCGSolver.html"}>>>
    preconditioner<<<{"description": "Optional choice of preconditioner to use."}>>> = matrix_free_ams
    l_tol<<<{"description": "Set the relative tolerance."}>>> = 1e-12
  []
[]

Input Parameters

alpha_coefficient1.Name of scalar coefficient used in curl-curl component of target equation system. A functor is any of the following: a variable, an MFEM material property, a function, a postprocessor or a number.
Default:1.
C++ Type:MFEMScalarCoefficientName
Controllable:No
Description:Name of scalar coefficient used in curl-curl component of target equation system. A functor is any of the following: a variable, an MFEM material property, a function, a postprocessor or a number.
beta_coefficient1.Name of scalar coefficient used in mass component of target equation system. A functor is any of the following: a variable, an MFEM material property, a function, a postprocessor or a number.
Default:1.
C++ Type:MFEMScalarCoefficientName
Controllable:No
Description:Name of scalar coefficient used in mass component of target equation system. A functor is any of the following: a variable, an MFEM material property, a function, a postprocessor or a number.
inner_g_iterations1Number of CG iterations on auxiliary G space.
Default:1
C++ Type:unsigned int
Controllable:No
Description:Number of CG iterations on auxiliary G space.
inner_pi_iterations0Number of CG iterations on auxiliary Pi space.
Default:0
C++ Type:unsigned int
Controllable:No
Description:Number of CG iterations on auxiliary Pi space.
use_initial_guessFalseWhether to preserve the current MFEM solution vector as the initial guess for an iterative solver.
Default:False
C++ Type:bool
Controllable:No
Description:Whether to preserve the current MFEM solution vector as the initial guess for an iterative solver.

Optional Parameters

control_tagsAdds user-defined labels for accessing object parameters via control logic.
C++ Type:std::vector<std::string>
Controllable:No
Description:Adds user-defined labels for accessing object parameters via control logic.
enableTrueSet the enabled status of the MooseObject.
Default:True
C++ Type:bool
Controllable:No
Description:Set the enabled status of the MooseObject.

Advanced Parameters

Input Files

(test/tests/mfem/kernels/curlcurl.i)

(test/tests/mfem/kernels/curlcurl.i)

# Definite Maxwell problem solved with Nedelec elements of the first kind
# based on MFEM Example 3.

[Mesh]
  type = MFEMMesh
  file = ../mesh/small_fichera.mesh
[]

[Problem]
  type = MFEMProblem
[]

[FESpaces]
  inactive = "L2FESpace"
  [HCurlFESpace]
    type = MFEMVectorFESpace
    fec_type = ND
    fec_order = FIRST
  []
  [HDivFESpace]
    type = MFEMVectorFESpace
    fec_type = RT
    fec_order = CONSTANT
  []
  [L2FESpace]
    type = MFEMScalarFESpace
    fec_type = L2
    fec_order = CONSTANT
  []
[]

[Variables]
  [e_field]
    type = MFEMVariable
    fespace = HCurlFESpace
  []
[]

[AuxVariables]
  inactive = "joule_heating"
  [db_dt_field]
    type = MFEMVariable
    fespace = HDivFESpace
  []
  [joule_heating]
    type = MFEMVariable
    fespace = L2FESpace
  []
[]

[AuxKernels]
  inactive = "joule_Q_aux"
  [curl]
    type = MFEMCurlAux
    variable = db_dt_field
    source = e_field
    scale_factor = -1.0
    execute_on = TIMESTEP_END
  []
  [joule_Q_aux]
    type = MFEMInnerProductAux
    variable = joule_heating
    first_source_vec = e_field
    second_source_vec = e_field
    execute_on = TIMESTEP_END
  []
[]

[Functions]
  [exact_e_field]
    type = ParsedVectorFunction
    expression_x = 'sin(kappa * y)'
    expression_y = 'sin(kappa * z)'
    expression_z = 'sin(kappa * x)'

    symbol_names = kappa
    symbol_values = 3.1415926535
  []

  [forcing_field]
    type = ParsedVectorFunction
    expression_x = '(1. + kappa * kappa) * sin(kappa * y)'
    expression_y = '(1. + kappa * kappa) * sin(kappa * z)'
    expression_z = '(1. + kappa * kappa) * sin(kappa * x)'

    symbol_names = kappa
    symbol_values = 3.1415926535
  []
[]

[BCs]
  [tangential_E_bdr]
    type = MFEMVectorTangentialDirichletBC
    variable = e_field
    vector_coefficient = exact_e_field
  []
[]

[Kernels]
  [curlcurl]
    type = MFEMCurlCurlKernel
    variable = e_field
  []
  [mass]
    type = MFEMVectorFEMassKernel
    variable = e_field
  []
  [source]
    type = MFEMVectorFEDomainLFKernel
    variable = e_field
    vector_coefficient = forcing_field
  []
[]

[Preconditioner]
  [ams]
    type = MFEMHypreAMS
    fespace = HCurlFESpace
  []
  [matrix_free_ams]
    type = MFEMMatrixFreeAMS
  []
[]

[Solvers]
  active = gmres
  [gmres]
    type = MFEMHypreGMRES
    preconditioner = ams
    l_tol = 1e-12
  []
  [cg]
    type = MFEMCGSolver
    preconditioner = matrix_free_ams
    l_tol = 1e-12
  []
[]

[Executioner]
  type = MFEMSteady
  device = cpu
[]

[Outputs]
  [ParaViewDataCollection]
    type = MFEMParaViewDataCollection
    file_base = OutputData/CurlCurl
    vtk_format = ASCII
  []
[]

(test/tests/mfem/kernels/curlcurl.i)

# Definite Maxwell problem solved with Nedelec elements of the first kind
# based on MFEM Example 3.

[Mesh]
  type = MFEMMesh
  file = ../mesh/small_fichera.mesh
[]

[Problem]
  type = MFEMProblem
[]

[FESpaces]
  inactive = "L2FESpace"
  [HCurlFESpace]
    type = MFEMVectorFESpace
    fec_type = ND
    fec_order = FIRST
  []
  [HDivFESpace]
    type = MFEMVectorFESpace
    fec_type = RT
    fec_order = CONSTANT
  []
  [L2FESpace]
    type = MFEMScalarFESpace
    fec_type = L2
    fec_order = CONSTANT
  []
[]

[Variables]
  [e_field]
    type = MFEMVariable
    fespace = HCurlFESpace
  []
[]

[AuxVariables]
  inactive = "joule_heating"
  [db_dt_field]
    type = MFEMVariable
    fespace = HDivFESpace
  []
  [joule_heating]
    type = MFEMVariable
    fespace = L2FESpace
  []
[]

[AuxKernels]
  inactive = "joule_Q_aux"
  [curl]
    type = MFEMCurlAux
    variable = db_dt_field
    source = e_field
    scale_factor = -1.0
    execute_on = TIMESTEP_END
  []
  [joule_Q_aux]
    type = MFEMInnerProductAux
    variable = joule_heating
    first_source_vec = e_field
    second_source_vec = e_field
    execute_on = TIMESTEP_END
  []
[]

[Functions]
  [exact_e_field]
    type = ParsedVectorFunction
    expression_x = 'sin(kappa * y)'
    expression_y = 'sin(kappa * z)'
    expression_z = 'sin(kappa * x)'

    symbol_names = kappa
    symbol_values = 3.1415926535
  []

  [forcing_field]
    type = ParsedVectorFunction
    expression_x = '(1. + kappa * kappa) * sin(kappa * y)'
    expression_y = '(1. + kappa * kappa) * sin(kappa * z)'
    expression_z = '(1. + kappa * kappa) * sin(kappa * x)'

    symbol_names = kappa
    symbol_values = 3.1415926535
  []
[]

[BCs]
  [tangential_E_bdr]
    type = MFEMVectorTangentialDirichletBC
    variable = e_field
    vector_coefficient = exact_e_field
  []
[]

[Kernels]
  [curlcurl]
    type = MFEMCurlCurlKernel
    variable = e_field
  []
  [mass]
    type = MFEMVectorFEMassKernel
    variable = e_field
  []
  [source]
    type = MFEMVectorFEDomainLFKernel
    variable = e_field
    vector_coefficient = forcing_field
  []
[]

[Preconditioner]
  [ams]
    type = MFEMHypreAMS
    fespace = HCurlFESpace
  []
  [matrix_free_ams]
    type = MFEMMatrixFreeAMS
  []
[]

[Solvers]
  active = gmres
  [gmres]
    type = MFEMHypreGMRES
    preconditioner = ams
    l_tol = 1e-12
  []
  [cg]
    type = MFEMCGSolver
    preconditioner = matrix_free_ams
    l_tol = 1e-12
  []
[]

[Executioner]
  type = MFEMSteady
  device = cpu
[]

[Outputs]
  [ParaViewDataCollection]
    type = MFEMParaViewDataCollection
    file_base = OutputData/CurlCurl
    vtk_format = ASCII
  []
[]

Overview
Example Input File Syntax
Input Parameters
Input Files