NekScalarValue

Description

The NekScalarValue class sends a scalar value between NekRS and MOOSE. This can be used to control NekRS simulations using MOOSE's Controls system or stochastically perturb NekRS simulations using the MOOSE stochastic tools module. Passing a number can also be used for much more general purposes (anywhere that a scalar value appears in NekRS's .udf or .oudf files).

Example Input File Syntax

Below is an example input file that defines two scalar transfers that we will use to control a NekRS boundary condition from MOOSE using the Controls system.

[Problem<<<{"href": "../../syntax/Problem/index.html"}>>>]
  type = NekRSProblem
  casename<<<{"description": "Case name for the NekRS input files; this is <case> in <case>.par, <case>.udf, <case>.oudf, and <case>.re2."}>>> = 'pyramid'
  n_usrwrk_slots<<<{"description": "If initialize_usrwrk is true, the number of slots that Cardinal will allocate in platform->app->bc->o_usrwrk. These entries can be used to hold fields related to coupling (which will be populated by Cardinal), or other custom usages, such as a distance-to-wall calculation"}>>> = 1

  [ScalarTransfers<<<{"href": "../../syntax/Problem/ScalarTransfers/index.html"}>>>]
    [scalar1]
      type = NekScalarValue<<<{"description": "Transfers a scalar value into NekRS"}>>>
      direction<<<{"description": "Direction in which to send data"}>>> = to_nek
      usrwrk_slot<<<{"description": "When 'direction = to_nek', the slot in the usrwrk array to write the incoming data"}>>> = 0
    []
    [scalar2]
      type = NekScalarValue<<<{"description": "Transfers a scalar value into NekRS"}>>>
      direction<<<{"description": "Direction in which to send data"}>>> = to_nek
      usrwrk_slot<<<{"description": "When 'direction = to_nek', the slot in the usrwrk array to write the incoming data"}>>> = 0
    []
  []
[]

We will control the value in each of these parameters using a RealFunctionControl, a MOOSE object that lets us define a scalar value using a function. Here, we will use a simple constant value function, which changes value partway through the simulation.

[Controls<<<{"href": "../../syntax/Controls/index.html"}>>>]
  [func_control]
    type = RealFunctionControl<<<{"description": "Sets the value of a 'Real' input parameters to the value of a provided function.", "href": "../controls/RealFunctionControl.html"}>>>
    parameter<<<{"description": "The input parameter(s) to control. Specify a single parameter name and all parameters in all objects matching the name will be updated"}>>> = 'Problem/ScalarTransfers/scalar1/value'
    function<<<{"description": "The function to use for controlling the specified parameter."}>>> = 'val'
    execute_on<<<{"description": "The list of flag(s) indicating when this object should be executed. For a description of each flag, see https://mooseframework.inl.gov/source/interfaces/SetupInterface.html."}>>> = 'timestep_begin'
  []
  [func_control2]
    type = RealFunctionControl<<<{"description": "Sets the value of a 'Real' input parameters to the value of a provided function.", "href": "../controls/RealFunctionControl.html"}>>>
    parameter<<<{"description": "The input parameter(s) to control. Specify a single parameter name and all parameters in all objects matching the name will be updated"}>>> = 'Problem/ScalarTransfers/scalar2/value'
    function<<<{"description": "The function to use for controlling the specified parameter."}>>> = 'val2'
    execute_on<<<{"description": "The list of flag(s) indicating when this object should be executed. For a description of each flag, see https://mooseframework.inl.gov/source/interfaces/SetupInterface.html."}>>> = 'timestep_begin'
  []
[]

[Functions<<<{"href": "../../syntax/Functions/index.html"}>>>]
  [val]
    type = ParsedFunction<<<{"description": "Function created by parsing a string", "href": "../functions/MooseParsedFunction.html"}>>>
    expression<<<{"description": "The user defined function."}>>> = 'if (t > 1, 200.0, 100.0)'
  []
  [val2]
    type = ParsedFunction<<<{"description": "Function created by parsing a string", "href": "../functions/MooseParsedFunction.html"}>>>
    expression<<<{"description": "The user defined function."}>>> = 'if (t > 1, 400.0, 300.0)'
  []
[]

When running the input file, you will then see a table like the following print:


--------------------------------------------------------------------------------------------------------
| Slot |  Data   |      How to Access (.oudf)      |               How to Access (.udf)                |
--------------------------------------------------------------------------------------------------------
|    0 | scalar1 | bc->usrwrk[0*bc->fieldOffset+0] | platform->app->bc->o_usrwrk[0*nrs->fieldOffset+0] |
|    0 | scalar2 | bc->usrwrk[0*bc->fieldOffset+1] | platform->app->bc->o_usrwrk[0*nrs->fieldOffset+1] |
--------------------------------------------------------------------------------------------------------

Suppose we want to use these two scalar values to set a Dirichlet temperature boundary condition in NekRS. We would simply follow the instructions for the .oudf, and do:

void udfDirichlet(bcData *bc)
{
  // note: when running with Cardinal, Cardinal will allocate the usrwrk
  // array. If running with NekRS standalone (e.g. nrsmpi), you need to
  // replace the usrwrk with some other value or allocate it youself from
  // the udf and populate it with values.
  if (bc->id == 5)
    bc->sScalar = bc->usrwrk[0 * bc->fieldOffset + 0]; // this is the value of scalar1
  else if (bc->id == 6)
    bc->sScalar = bc->usrwrk[0 * bc->fieldOffset + 1]; // this is the value of scalar2
}

void udfNeumann(bcData *bc)
{
  bc->fluxScalar = 0.0;
}

Input Parameters

directionDirection in which to send data
C++ Type:MooseEnum
Options:to_nek, from_nek
Controllable:No
Description:Direction in which to send data

Required Parameters

output_postprocessorName of the postprocessor to output the value sent into NekRS
C++ Type:PostprocessorName
Unit:(no unit assumed)
Controllable:No
Description:Name of the postprocessor to output the value sent into NekRS
scaling1Multiplier on the value passed into NekRS
Default:1
C++ Type:Real
Unit:(no unit assumed)
Controllable:No
Description:Multiplier on the value passed into NekRS
usrwrk_slotWhen 'direction = to_nek', the slot in the usrwrk array to write the incoming data
C++ Type:unsigned int
Controllable:No
Description:When 'direction = to_nek', the slot in the usrwrk array to write the incoming data
value0Scalar value to pass into NekRS
Default:0
C++ Type:Real
Unit:(no unit assumed)
Controllable:Yes
Description:Scalar value to pass into NekRS

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/nek_errors/usrwrk_transfers/scalar.i)
(test/tests/nek_stochastic/device/nek_multi.i)
(test/tests/nek_errors/usrwrk_transfers/nek.i)
(test/tests/nek_stochastic/shift/nek.i)
(test/tests/nek_errors/usrwrk_transfers/wrong_problem_s.i)
(test/tests/nek_stochastic/nek_multi.i)
(test/tests/nek_stochastic/quiet_init/nek_multi.i)
(tutorials/nek_stochastic/nek.i)
(test/tests/transfers/nek_scalar_value/nek.i)

(test/tests/transfers/nek_scalar_value/nek.i)

[Problem]
  type = NekRSProblem
  casename = 'pyramid'
  n_usrwrk_slots = 1

  [ScalarTransfers]
    [scalar1]
      type = NekScalarValue
      direction = to_nek
      usrwrk_slot = 0
    []
    [scalar2]
      type = NekScalarValue
      direction = to_nek
      usrwrk_slot = 0
    []
  []
[]

[Mesh]
  type = NekRSMesh
  volume = true
[]

[Executioner]
  type = Transient

  [TimeStepper]
    type = NekTimeStepper
  []
[]

[Controls]
  [func_control]
    type = RealFunctionControl
    parameter = 'Problem/ScalarTransfers/scalar1/value'
    function = 'val'
    execute_on = 'timestep_begin'
  []
  [func_control2]
    type = RealFunctionControl
    parameter = 'Problem/ScalarTransfers/scalar2/value'
    function = 'val2'
    execute_on = 'timestep_begin'
  []
[]

[Functions]
  [val]
    type = ParsedFunction
    expression = 'if (t > 1, 200.0, 100.0)'
  []
  [val2]
    type = ParsedFunction
    expression = 'if (t > 1, 400.0, 300.0)'
  []
[]

[Postprocessors]
  [avg_t_5]
    type = NekSideAverage
    field = temperature
    boundary = '5'
  []
  [avg_t_6]
    type = NekSideAverage
    field = temperature
    boundary = '6'
  []
[]

[Outputs]
  exodus = true
  csv = true
[]

(test/tests/transfers/nek_scalar_value/nek.i)

[Problem]
  type = NekRSProblem
  casename = 'pyramid'
  n_usrwrk_slots = 1

  [ScalarTransfers]
    [scalar1]
      type = NekScalarValue
      direction = to_nek
      usrwrk_slot = 0
    []
    [scalar2]
      type = NekScalarValue
      direction = to_nek
      usrwrk_slot = 0
    []
  []
[]

[Mesh]
  type = NekRSMesh
  volume = true
[]

[Executioner]
  type = Transient

  [TimeStepper]
    type = NekTimeStepper
  []
[]

[Controls]
  [func_control]
    type = RealFunctionControl
    parameter = 'Problem/ScalarTransfers/scalar1/value'
    function = 'val'
    execute_on = 'timestep_begin'
  []
  [func_control2]
    type = RealFunctionControl
    parameter = 'Problem/ScalarTransfers/scalar2/value'
    function = 'val2'
    execute_on = 'timestep_begin'
  []
[]

[Functions]
  [val]
    type = ParsedFunction
    expression = 'if (t > 1, 200.0, 100.0)'
  []
  [val2]
    type = ParsedFunction
    expression = 'if (t > 1, 400.0, 300.0)'
  []
[]

[Postprocessors]
  [avg_t_5]
    type = NekSideAverage
    field = temperature
    boundary = '5'
  []
  [avg_t_6]
    type = NekSideAverage
    field = temperature
    boundary = '6'
  []
[]

[Outputs]
  exodus = true
  csv = true
[]

(test/tests/transfers/nek_scalar_value/pyramid.oudf)

void udfDirichlet(bcData *bc)
{
  // note: when running with Cardinal, Cardinal will allocate the usrwrk
  // array. If running with NekRS standalone (e.g. nrsmpi), you need to
  // replace the usrwrk with some other value or allocate it youself from
  // the udf and populate it with values.
  if (bc->id == 5)
    bc->sScalar = bc->usrwrk[0 * bc->fieldOffset + 0]; // this is the value of scalar1
  else if (bc->id == 6)
    bc->sScalar = bc->usrwrk[0 * bc->fieldOffset + 1]; // this is the value of scalar2
}

void udfNeumann(bcData *bc)
{
  bc->fluxScalar = 0.0;
}

(test/tests/nek_errors/usrwrk_transfers/scalar.i)

[Mesh]
  type = NekRSMesh
  boundary = '6'
[]

[Problem]
  type = NekRSProblem
  casename = 'brick'
  n_usrwrk_slots = 5

  [ScalarTransfers]
    [scalar]
      type = NekScalarValue
      direction = to_nek
      usrwrk_slot = '3'
    []
  []

  [FieldTransfers]
    [flux]
      type = NekBoundaryFlux
      direction = to_nek
      usrwrk_slot = '3'
    []
    [flux2]
      type = NekBoundaryFlux
      direction = to_nek
      usrwrk_slot = '4'
    []
  []
[]

[Executioner]
  type = Transient

  [TimeStepper]
    type = NekTimeStepper
  []
[]

(test/tests/nek_stochastic/device/nek_multi.i)

[Mesh]
  type = NekRSMesh
  volume = true
[]

[Problem]
  type = NekRSProblem
  casename = 'pyramid'
  n_usrwrk_slots = 1

  [ScalarTransfers]
    [scalar1]
      type = NekScalarValue
      direction = to_nek
      usrwrk_slot = 0
      output_postprocessor = s1
    []
  []
[]

[Executioner]
  type = Transient

  [TimeStepper]
    type = NekTimeStepper
  []
[]

[Controls]
  [stochastic]
    type = SamplerReceiver
  []
[]

[Postprocessors]
  [s1]
    type = Receiver
  []

  # we use the stochastic value to set the boundary condition on temperature on sideset 1;
  # we are checking that the value of the temperature on sideset 1 indeed matches that value
  [max_on_side]
    type = NekSideExtremeValue
    field = temperature
    boundary = '1'
    value_type = max
  []
  [min_on_side]
    type = NekSideExtremeValue
    field = temperature
    boundary = '1'
    value_type = min
  []
[]

[Outputs]
  csv = true
[]

(test/tests/nek_errors/usrwrk_transfers/nek.i)

[Mesh]
  type = NekRSMesh
  boundary = '6'
[]

[Problem]
  type = NekRSProblem
  casename = 'brick'
  n_usrwrk_slots = 7

  [FieldTransfers]
    [flux]
      type = NekBoundaryFlux
      direction = to_nek
      usrwrk_slot = '1'
    []
    [source]
      type = NekBoundaryFlux
      direction = to_nek
      usrwrk_slot = '2'
    []
  []

  [ScalarTransfers]
    [scalar]
      type = NekScalarValue
      direction = to_nek
      usrwrk_slot = '3'
    []
  []
[]

[Executioner]
  type = Transient

  [TimeStepper]
    type = NekTimeStepper
  []
[]

(test/tests/nek_stochastic/shift/nek.i)

[Mesh]
  type = NekRSMesh
  volume = true
[]

[Problem]
  type = NekRSProblem
  casename = 'brick'
  n_usrwrk_slots = 3

  [ScalarTransfers]
    [s2]
      type = NekScalarValue
      direction = to_nek
      value = 2.5
      usrwrk_slot = 1
      output_postprocessor = s2
    []
    [s3]
      type = NekScalarValue
      direction = to_nek
      value = 3.5
      usrwrk_slot = 1
      output_postprocessor = s3
    []
  []

  [FieldTransfers]
    [scalar01]
      type = NekFieldVariable
      direction = from_nek
    []
    [scalar02]
      type = NekFieldVariable
      direction = from_nek
    []
    [scalar03]
      type = NekFieldVariable
      direction = from_nek
    []
  []
[]

[Executioner]
  type = Transient

  [TimeStepper]
    type = NekTimeStepper
  []
[]

[Postprocessors]
  [s2]
    type = Receiver
  []
  [s3]
    type = Receiver
  []

  [max_scalar1]
    type = NodalExtremeValue
    variable = scalar01
    value_type = max
  []
  [min_scalar1]
    type = NodalExtremeValue
    variable = scalar01
    value_type = min
  []
  [max_scalar2]
    type = NodalExtremeValue
    variable = scalar02
    value_type = max
  []
  [min_scalar2]
    type = NodalExtremeValue
    variable = scalar02
    value_type = min
  []
  [max_scalar3]
    type = NodalExtremeValue
    variable = scalar03
    value_type = max
  []
  [min_scalar3]
    type = NodalExtremeValue
    variable = scalar03
    value_type = min
  []
[]

[Outputs]
  csv = true
[]

(test/tests/nek_errors/usrwrk_transfers/wrong_problem_s.i)

[Mesh]
  [g]
    type = GeneratedMeshGenerator
    dim = 1
    nx = 5
  []
[]

[Problem]
  type = FEProblem
  solve = false

  [ScalarTransfers]
    [scalar]
      type = NekScalarValue
      direction = to_nek
      usrwrk_slot = '3'
    []
  []
[]

[Executioner]
  type = Transient
[]

(test/tests/nek_stochastic/nek_multi.i)

[Mesh]
  type = NekRSMesh
  volume = true
[]

[Problem]
  type = NekRSProblem
  casename = 'ethier'
  n_usrwrk_slots = 2

  [FieldTransfers]
    [scalar02]
      type = NekFieldVariable
      direction = from_nek
    []
  []

  [ScalarTransfers]
    [scalar1]
      type = NekScalarValue
      direction = to_nek
      usrwrk_slot = 0
      output_postprocessor = s1
    []
  []
[]

[Executioner]
  type = Transient

  [TimeStepper]
    type = NekTimeStepper
  []
[]

[Controls]
  [stochastic]
    type = SamplerReceiver
  []
[]

[Postprocessors]
  [s1]
    type = Receiver
  []

  # we use the stochastic value to set the scalar (in the .udf files). Here,
  # we are checking that the value of the scalar everywhere is equation to the 's1' postprocessor
  [max_scalar]
    type = ElementExtremeValue
    variable = scalar02
    value_type = max
  []
  [min_scalar]
    type = ElementExtremeValue
    variable = scalar02
    value_type = min
  []
[]

[Outputs]
  csv = true
[]

(test/tests/nek_stochastic/quiet_init/nek_multi.i)

[Mesh]
  type = NekRSMesh
  volume = true
[]

[Problem]
  type = NekRSProblem
  casename = 'ethier'
  n_usrwrk_slots = 2

  [ScalarTransfers]
    [scalar1]
      type = NekScalarValue
      direction = to_nek
      usrwrk_slot = 0
      output_postprocessor = s1
    []
  []

  [FieldTransfers]
    [scalar02]
      type = NekFieldVariable
      direction = from_nek
    []
  []
[]

[Executioner]
  type = Transient

  [TimeStepper]
    type = NekTimeStepper
  []
[]

[Controls]
  [stochastic]
    type = SamplerReceiver
  []
[]

[Postprocessors]
  [s1]
    type = Receiver
  []

  # we use the stochastic value to set the scalar (in the .udf files). Here,
  # we are checking that the value of the scalar everywhere is equation to the 's1' postprocessor
  [max_scalar]
    type = ElementExtremeValue
    variable = scalar02
    value_type = max
  []
  [min_scalar]
    type = ElementExtremeValue
    variable = scalar02
    value_type = min
  []
[]

[Outputs]
  csv = true
[]

(tutorials/nek_stochastic/nek.i)

[Mesh]
  type = NekRSMesh
  boundary = '5'
[]

[Problem]
  type = NekRSProblem
  casename = 'channel'
  n_usrwrk_slots = 2

  [FieldTransfers]
    [flux]
      type = NekBoundaryFlux
      direction = to_nek
      usrwrk_slot = 0
    []
    [temperature]
      type = NekFieldVariable
      field = temperature
      direction = from_nek
    []
  []

  [ScalarTransfers]
    [k]
      type = NekScalarValue
      direction = to_nek
      usrwrk_slot = 1
      output_postprocessor = k_from_stm
    []
  []
[]

[Executioner]
  type = Transient

  [TimeStepper]
    type = NekTimeStepper
  []
[]

[Postprocessors]
  [max_temp]
    type = NekVolumeExtremeValue
    field = temperature
  []
  [k_from_stm] # this will just print to the screen the value of k received
    type = Receiver
  []
  [expect_max_T]
    type = ParsedPostprocessor
    expression = '1000.0 / k_from_stm + 500.0'
    pp_names = k_from_stm
  []
[]

[Outputs]
  csv = true
  hide = 'flux_integral'
[]

[Controls]
  [stm]
    type = SamplerReceiver
  []
[]

(test/tests/transfers/nek_scalar_value/nek.i)

[Problem]
  type = NekRSProblem
  casename = 'pyramid'
  n_usrwrk_slots = 1

  [ScalarTransfers]
    [scalar1]
      type = NekScalarValue
      direction = to_nek
      usrwrk_slot = 0
    []
    [scalar2]
      type = NekScalarValue
      direction = to_nek
      usrwrk_slot = 0
    []
  []
[]

[Mesh]
  type = NekRSMesh
  volume = true
[]

[Executioner]
  type = Transient

  [TimeStepper]
    type = NekTimeStepper
  []
[]

[Controls]
  [func_control]
    type = RealFunctionControl
    parameter = 'Problem/ScalarTransfers/scalar1/value'
    function = 'val'
    execute_on = 'timestep_begin'
  []
  [func_control2]
    type = RealFunctionControl
    parameter = 'Problem/ScalarTransfers/scalar2/value'
    function = 'val2'
    execute_on = 'timestep_begin'
  []
[]

[Functions]
  [val]
    type = ParsedFunction
    expression = 'if (t > 1, 200.0, 100.0)'
  []
  [val2]
    type = ParsedFunction
    expression = 'if (t > 1, 400.0, 300.0)'
  []
[]

[Postprocessors]
  [avg_t_5]
    type = NekSideAverage
    field = temperature
    boundary = '5'
  []
  [avg_t_6]
    type = NekSideAverage
    field = temperature
    boundary = '6'
  []
[]

[Outputs]
  exodus = true
  csv = true
[]

Description
Example Input File Syntax
Input Parameters
Input Files