Input file syntax

The input file for a Numbat simulation is a simple, block-structured text file based on the input files for a plain MOOSE input file.

Essential input

Details of the minimum input file requirements are given below.

Mesh

All simulations must feature a mesh. For the basic model with a rectangular mesh, the built-in NumbatBiasedMesh can be used to create a suitable mesh. This is a type of GeneratedMesh that provides the option to refine the mesh near one boundary. The size of the initial element can be specified, after which the elements are progressively coarser, see NumbatBiasedMesh for details. This can be extremely useful in simulations of density-driven convection, where it is necessary to have a finer mesh in the vicinity of the boundary where the fingers form in order to capture the process adequately. Away from this region, the fingers grow and merge, so that a coarser mesh is sufficient to simulate them. Having a biased mesh such as that produced by NumbatBiasedMesh can minimise the number of elements necessary, reducing the overall computational demands.

In 2D, the input block looks like:


[Mesh]
  type = NumbatBiasedMesh
  dim = 2
  ymax = 1.5
  nx = 100
  ny = 50
  refined_edge = top
  refined_resolution = 0.001
[]
(examples/inputfiles/2D.i)

In 3D, the Mesh block would look like:


[Mesh]
  type = NumbatBiasedMesh
  dim = 3
  zmax = 1.5
  nx = 20
  ny = 20
  nz = 500
  refined_edge = front
  refined_resolution = 0.001
[]
(examples/inputfiles/3D.i)
note

In contrast to the normal GeneratedMesh provided by MOOSE, NumbatBiasedMesh renames the boundaries of the three dimensional mesh so that the boundaries top and bottom are at the extrema of the z axis.

Variables

The number and type of variables required depends on the chosen formulation. For the dimensional formulation, two nonlinear variables must be provided, representing the fluid pressure and solute concentration.


[Variables]
  [./concentration]
    initial_condition = 0
    scaling = 1e6
  [../]
  [./pressure]
    initial_condition = 1e6
  [../]
[]
(examples/inputfiles/2D.i)

For the dimensionless streamfunction formulation, the nonlinear variables for a 2D simulations are solute concentration and streamfunction:


[Variables]
  [./concentration]
    order = FIRST
    family = LAGRANGE
  [../]
  [./streamfunction]
    order = FIRST
    family = LAGRANGE
    initial_condition = 0.0
  [../]
[]
(examples/inputfiles/2DSF.i)

In 3D, an additional streamfunction variable must also be added:


[Variables]
  [./concentration]
    order = FIRST
    family = LAGRANGE
    [./InitialCondition]
      type = NumbatPerturbationIC
      variable = concentration
      amplitude = 0.1
      seed = 1
    [../]
  [../]
  [./streamfunctionx]
    order = FIRST
    family = LAGRANGE
    initial_condition = 0.0
  [../]
  [./streamfunctiony]
    order = FIRST
    family = LAGRANGE
    initial_condition = 0.0
  [../]
[]
(examples/inputfiles/3DSF.i)

Materials

For the dimensional formulation, several material and fluid properties are required: porosity, permeability, fluid density and viscosity, and diffusivity. These can be added using the following Numbat materials:


[Materials]
  [./porosity]
    type = NumbatPorosity
    porosity = 0.3
    noise = noise
  [../]
  [./permeability]
    type = NumbatPermeability
    permeability = '1e-11 0 0 0 1e-11 0 0 0 1e-11'
  [../]
  [./diffusivity]
    type = NumbatDiffusivity
    diffusivity = 2e-9
  [../]
  [./density]
    type = NumbatDensity
    concentration = concentration
    zero_density = 995
    delta_density = 10.5
    saturated_concentration = 0.049306
  [../]
  [./viscosity]
    type = NumbatViscosity
    viscosity = 6e-4
  [../]
[]
(examples/inputfiles/2D.i)
note

No material properties are required in the dimensionless streamfunction formulation

Kernels

Four kernels are required for a dimensional model: NumbatTimeDerivative, NumbatDiffusion, NumbatConvection, and NumbatDarcy.


[Kernels]
  [./time]
    type = NumbatTimeDerivative
    variable = concentration
  [../]
  [./diffusion]
    type = NumbatDiffusion
    variable = concentration
  [../]
  [./convection]
    type = NumbatConvection
    variable = concentration
    pressure = pressure
  [../]
  [./darcy]
    type = NumbatDarcy
    variable = pressure
    concentration = concentration
  [../]
[]
(examples/inputfiles/2D.i)

For the dimensionless streamfunction formulation, four kernels are required for a 2D model: a NumbatDarcySF kernel, a NumbatDiffusionSF kernel, a NumbatConvectionSF kernel, and a TimeDerivative kernel.


[Kernels]
  [./Darcy]
    type = NumbatDarcySF
    variable = streamfunction
    concentration = concentration
  [../]
  [./Convection]
    type = NumbatConvectionSF
    variable = concentration
    streamfunction = streamfunction
  [../]
  [./Diffusion]
    type = NumbatDiffusionSF
    variable = concentration
  [../]
  [./TimeDerivative]
    type = TimeDerivative
    variable = concentration
  [../]
[]
(examples/inputfiles/2DSF.i)

For 3D models, an additional NumbatDarcySF kernel is required for the additional streamfunction variable. An example of the kernels block for a 3D isotropic model is


[Kernels]
  [./Darcy_x]
    type = NumbatDarcySF
    variable = streamfunctionx
    concentration = concentration
    component = x
  [../]
  [./Darcy_y]
    type = NumbatDarcySF
    variable = streamfunctiony
    concentration = concentration
    component = y
  [../]
  [./Convection]
    type = NumbatConvectionSF
    variable = concentration
    streamfunction = 'streamfunctionx streamfunctiony'
  [../]
  [./Diffusion]
    type = NumbatDiffusionSF
    variable = concentration
  [../]
  [./TimeDerivative]
    type = TimeDerivative
    variable = concentration
  [../]
[]
(examples/inputfiles/3DSF.i)

In the 3D case, it is important to note that the NumbatDarcySF kernel must specify the component that it applies to, and that the streamfunction keyword in the NumbatConvectionSF kernel must contain both streamfunction variables ordered by the x component then the y component.

note

For the streamfunction formulation, a TimeDerivative kernel is used, rather than a NumbatTimeDerivative kernel, as porosity has been scaled out of the problem.

Boundary conditions

Appropriate boundary conditions must be prescribed. Typically, these will be constant concentration at the top of the model domain, periodic boundary conditions on the lateral sides (to mimic an infinite model), and no-flow boundary conditions at the top and bottom surfaces.

In the 2D dimensional formulation, this can be achieved using the following input block:


[BCs]
  [./conctop]
    type = PresetBC
    variable = concentration
    boundary = top
    value = 0.049306
  [../]
  [./Periodic]
    [./x]
      variable = concentration
      auto_direction = x
    [../]
  [../]
[]
(examples/inputfiles/2D.i)

while in 3D


[BCs]
  [./conctop]
    type = PresetBC
    variable = concentration
    boundary = front
    value = 0.049306
  [../]
  [./Periodic]
    [./x]
      variable = concentration
      auto_direction = 'x y'
    [../]
  [../]
[]
(examples/inputfiles/3D.i)

In this case, the conctop boundary condition fixes the value of concentration at the top boundary, while the Periodic boundary condition enforces periodicity of concentration along the boundaries in the directions specified in the auto_direction parameter.

It is useful to note that a MOOSE GeneratedMesh provides descriptive names for the sides of the model (top, bottom, left, right) which can be referenced in the input file.

For the dimensionless streamfunction formulation, no-flow boundary conditions are prescribed on the top and bottom surfaces by holding the streamfunction variable constant (in this case 0).


[BCs]
  [./conctop]
    type = DirichletBC
    variable = concentration
    boundary = top
    value = 1.0
  [../]
  [./streamfuntop]
    type = DirichletBC
    variable = streamfunction
    boundary = top
    value = 0.0
  [../]
  [./streamfunbottom]
    type = DirichletBC
    variable = streamfunction
    boundary = bottom
    value = 0.0
  [../]
  [./Periodic]
    [./x]
      variable = 'concentration streamfunction'
      auto_direction = x
    [../]
  [../]
[]
(examples/inputfiles/2DSF.i)

Executioner

Each MOOSE simulation must use an Executioner, which provides parameters for the solve.


[Executioner]
  type = Transient
  l_max_its = 200
  end_time = 3e5
  solve_type = NEWTON
  petsc_options = -ksp_snes_ew
  petsc_options_iname = '-pc_type -sub_pc_type -ksp_atol'
  petsc_options_value = 'bjacobi ilu 1e-12'
  nl_abs_tol = 1e-10
  nl_max_its = 25
  dtmax = 2e3
  [./TimeStepper]
    type = IterationAdaptiveDT
    dt = 1
  [../]
[]
(examples/inputfiles/2D.i)

Executioners are a standard MOOSE feature that are well documented on the MOOSE, so no further detail is provided here.

Preconditioning

A default preconditioning block is used that provides all Jacobian entries to aid convergence.


[Preconditioning]
  [./smp]
    type = SMP
    full = true
  [../]
[]
(examples/inputfiles/2D.i)

This is a standard MOOSE feature that is documented on the MOOSE website, so no further detail is provided here.

Outputs

To provide ouptut from the simulation, an Outputs block must be specified. An example is


[Outputs]
  perf_graph = true
  [./exodus]
    type = Exodus
    file_base = 2Dddc
    execute_on = 'INITIAL TIMESTEP_END'
  [../]
  [./csvoutput]
    type = CSV
    file_base = 2Dddc
    execute_on = 'INITIAL TIMESTEP_END'
  [../]
[]
(examples/inputfiles/2D.i)

There are a large number of output options available in MOOSE, see the MOOSE website for further details.

Action system

To avoid having to enter several of these input file blocks each time, and ensuring that the correct parameters are provided to each object in the correct order, Numbat provides some powerful actions that automatically add most of the required objects.

The NumbatAction adds all of the nonlinear variables, kernels, aux variables, aux kernels and postprocessors typically required in a dimensional Numbat simulation.

This action is called in the input file simply as


[Numbat]
  [./Dimensional]
  [../]
[]
(tests/2D/2D_action.i)

The use of this action is exactly equivalent to the following input file syntax

[Variables]
  [./concentration]
    initial_condition = 0
  [../]
  [./pressure]
    initial_condition = 1e6
  [../]
[]

[AuxVariables]
  [./u]
    order = CONSTANT
    family = MONOMIAL
  [../]
  [./v]
    order = CONSTANT
    family = MONOMIAL
  [../]
[]

[Kernels]
  [./time]
    type = NumbatTimeDerivative
    variable = concentration
  [../]
  [./diffusion]
    type = NumbatDiffusion
    variable = concentration
  [../]
  [./convection]
    type = NumbatConvection
    variable = concentration
    pressure = pressure
  [../]
  [./darcy]
    type = NumbatDarcy
    variable = pressure
    concentration = concentration
  [../]
[]

[AuxKernels]
  [./uAux]
    type = NumbatDarcyVelocity
    pressure = pressure
    variable = u
    component = x
  [../]
  [./vAux]
    type = NumbatDarcyVelocity
    pressure = pressure
    variable = v
    component = y
  [../]
[]

[BCs]
  [./conctop]
    type = DirichletBC
    variable = concentration
    boundary = top
    value = 1.0
  [../]
  [./Periodic]
    [./x]
      variable = 'concentration pressure'
      auto_direction = x
    [../]
  [../]
[]

[Postprocessors]
  [./boundary_flux]
    type = NumbatSideFlux
    variable = concentration
    boundary = top
  [../]
  [./total_mass]
    type = NumbatTotalMass
    variable = concentration
  [../]
[]
(tests/2D/2D.i)

A specific value for the saturated boundary concentration can optionally be provided


[Numbat]
  [./Dimensional]
    boundary_concentration = 0.05
  [../]
[]
(tests/2D/2D_c0_action.i)

Similarly, the NumbatSFAction adds all of the nonlinear variables, kernels, aux variables, aux kernels and postprocessors typically required in a dimensionless Numbat simulation.

This action is called in the input file simply as


[Numbat]
  [./Dimensionless]
  [../]
[]
(tests/2D/2DSF_action.i)

The use of this action is exactly equivalent to the following input file syntax for a 2D simulation.

[Variables]
  [./concentration]
    order = FIRST
    family = LAGRANGE
    initial_condition = 0.0
  [../]
  [./streamfunction]
    order = FIRST
    family = LAGRANGE
    initial_condition = 0.0
  [../]
[]

[AuxVariables]
  [./u]
    order = CONSTANT
    family = MONOMIAL
  [../]
  [./v]
    order = CONSTANT
    family = MONOMIAL
  [../]
[]

[Kernels]
  [./Darcy]
    type = NumbatDarcySF
    variable = streamfunction
    concentration = concentration
  [../]
  [./Convection]
    type = NumbatConvectionSF
    variable = concentration
    streamfunction = streamfunction
  [../]
  [./Diffusion]
    type = NumbatDiffusionSF
    variable = concentration
  [../]
  [./TimeDerivative]
    type = TimeDerivative
    variable = concentration
  [../]
[]

[AuxKernels]
  [./uAux]
    type = NumbatDarcyVelocitySF
    variable = u
    component = x
    streamfunction = streamfunction
  [../]
  [./vAux]
    type = NumbatDarcyVelocitySF
    variable = v
    component = y
    streamfunction = streamfunction
  [../]
[]

[BCs]
  [./conctop]
    type = DirichletBC
    variable = concentration
    boundary = top
    value = 1.0
  [../]
  [./streamfuntop]
    type = DirichletBC
    variable = streamfunction
    boundary = top
    value = 0.0
  [../]
  [./streamfunbottom]
    type = DirichletBC
    variable = streamfunction
    boundary = bottom
    value = 0.0
  [../]
  [./Periodic]
    [./x]
      variable = 'concentration streamfunction'
      auto_direction = x
    [../]
  [../]
[]

[Postprocessors]
  [./boundary_flux]
    type = NumbatSideFluxSF
    variable = concentration
    boundary = top
  [../]
  [./total_mass]
    type = NumbatTotalMassSF
    variable = concentration
  [../]
[]
(tests/2D/2DSF.i)

The use of these actions is recommended for all users, as they reduce the possibility of input file errors.

Optional input

While the above required blocks will enable a Numbat simulation to run, there are a number of optional input blocks that will improve the simulations are increase the amount of results provided.

Mesh adaptivity

MOOSE features built-in mesh adaptivity that is extremely useful in Numbat simulations to reduce computational expense. This can be included using:


[Adaptivity]
  max_h_level = 1
  initial_marker = boxmarker
  initial_steps = 1
  marker = errormarker
  [./Indicators]
    [./gradjumpindicator]
      type = GradientJumpIndicator
      variable = concentration
    [../]
  [../]
  [./Markers]
    [./errormarker]
      type = ErrorToleranceMarker
      refine = 0.05
      indicator = gradjumpindicator
    [../]
    [./boxmarker]
      type = BoxMarker
      bottom_left = '0 0 -10'
      top_right = '500 500 0'
      inside = refine
      outside = dont_mark
    [../]
  [../]
[]
(examples/inputfiles/3DSF.i)

For details about mesh adaptivity, see the MOOSE website.

Initial condition

To seed the instability, a random perturbation to the initial concentration can be prescribed using the NumbatPerturbationIC initial condition.


[ICs]
  [./concentration]
    type = NumbatPerturbationIC
    variable = concentration
    amplitude = 0.1
    seed = 1
  [../]
[]
(examples/inputfiles/2DSF.i)

The NumbatPerturbationIC initial condition applies the diffusive concentration profile to the nodes for (scaled) time , (1) for , where is the error function.

A uniform random perturbation is then added to the diffusive concentration profile, where the amplitude of the perturbation is specified by the input file value amplitude.

Postprocessors

The flux over the top boundary or the total mass of solute in the model is of particular interest in many cases (especially convective mixing of CO). These can be calculated at each time step using the NumbatSideFlux and NumbatTotalMass Postprocessors.


[Postprocessors]
  [./boundaryfluxint]
    type = NumbatSideFlux
    variable = concentration
    boundary = top
  [../]
  [./mass]
    type = NumbatTotalMass
    variable = concentration
  [../]
[]
(examples/inputfiles/2D.i)

Versions of these Postprocessors for the dimensionless streamfunction formulation are also provided, see NumbatSideFluxSF and NumbatTotalMassSF for details.

Numbat also provides a simple Postprocessor to calculate the Rayleigh number for dimensional simulations, see NumbatRayleighNumber for details.

AuxKernels

The velocity components in the and directions (in 2D), and , , and directions in 3D can be calculated using the auxiliary system. These velocity components are calculated using the streamfunction(s), see the governing equations for details.

In the 2D case, two auxiliary variables, and , can be defined for the horizontal and vertical velocity components, respectively.

note

Importantly, these auxiliary variables must have monomial shape functions (these are referred to as elemental variables, as the value is constant over each mesh element). This restriction is due to fact that the gradient of variables is undefined for nodal auxiliary variables (for example, those using linear Lagrange shape functions).

An example of the input syntax for the 2D case is


[AuxVariables]
  [./u]
    order = CONSTANT
    family = MONOMIAL
  [../]
  [./w]
    order = CONSTANT
    family = MONOMIAL
  [../]
[]
(examples/inputfiles/2DSF.i)

For the 3D case, there is an additional horizontal velocity component (v), so the input syntax is


[AuxVariables]
  [./u]
    order = CONSTANT
    family = MONOMIAL
  [../]
  [./v]
    order = CONSTANT
    family = MONOMIAL
  [../]
  [./w]
    order = CONSTANT
    family = MONOMIAL
  [../]
[]
(examples/inputfiles/3DSF.i)

The velocity components are calculated by NumbatDarcyVelocity AuxKernels (or NumbatDarcyVelocitySF AuxKernels for the dimensionless streamfunction formulation). Each velocity component is computed by an AuxKernel.

For the 2D case, two AuxKernels are required:


[AuxKernels]
  [./uAux]
    type = NumbatDarcyVelocitySF
    variable = u
    component = x
    streamfunction = streamfunction
  [../]
  [./wAux]
    type = NumbatDarcyVelocitySF
    variable = w
    component = y
    streamfunction = streamfunction
  [../]
[]
(examples/inputfiles/2DSF.i)

while for 3D, three AuxKernels are necessary:


[AuxKernels]
  [./uAux]
    type = NumbatDarcyVelocitySF
    variable = u
    component = x
    streamfunction = 'streamfunctionx streamfunctiony'
  [../]
  [./vAux]
    type = NumbatDarcyVelocitySF
    variable = v
    component = y
    streamfunction = 'streamfunctionx streamfunctiony'
  [../]
  [./wAux]
    type = NumbatDarcyVelocitySF
    variable = w
    component = z
    streamfunction = 'streamfunctionx streamfunctiony'
  [../]
[]
(examples/inputfiles/3DSF.i)
note

For the 3D case, both streamfunction variables must be given, in the correct order (eg. then )