PointInSignedFunctionCheckUO

PointInSignedFunctionCheckUO classifies a point against a surface defined implicitly as the zero level set of a signed function. Unlike the mesh-based PointInPolyhedronCheckUO, it needs no surface mesh: the classification comes directly from the sign of the function value at the query point. It implements the point-in-surface check interface, so it can be combined with mesh-based checkers inside a PointInUnionCheckUO.

Sign convention

By default a negative function value denotes the interior, matching the usual signed-distance-function convention (and the union signed distance used elsewhere in the shifted boundary method). If your level set is positive inside instead, set inside_is_negative = false and the sign is flipped internally.

Tolerance and the on-surface band

A point is labeled as follows, after normalizing so that negative denotes the interior:

phi < -tolerance -> INSIDE
|phi| <= tolerance -> ON
phi > tolerance -> OUTSIDE

Two consequences are worth noting:

tolerance affects containment. Because ON is treated as contained (spatialValue() returns 1 for it), the contained region is the true interior grown by a shell of half-width tolerance around the zero level set, rather than the exact sign region. This matches how the mesh backend treats on-surface points.
tolerance is measured in function value space, not distance. It equals a geometric distance only when the function is a normalized signed distance (|grad phi| = 1). For a general level set (for example x^2 + y^2 - 1, whose gradient magnitude varies) the geometric thickness of the on-surface band changes with position, so choose tolerance with the function's scaling in mind.

Usage

Set function to the signed level-set function. The result is available through the standard spatial user object interface and can be sampled by a SpatialUserObjectAux.

Classifies a point as inside, on, or outside a surface defined by the zero level set of a signed function.

Input Parameters

functionSigned level-set function; negative inside by default (see inside_is_negative).
C++ Type:FunctionName
Unit:(no unit assumed)
Controllable:No
Description:Signed level-set function; negative inside by default (see inside_is_negative).

Required Parameters

inside_is_negativeTrueWhether negative function values denote the interior. True matches the signed-distance convention; set false for a level set that is positive inside.
Default:True
C++ Type:bool
Controllable:No
Description:Whether negative function values denote the interior. True matches the signed-distance convention; set false for a level set that is positive inside.
tolerance1e-06Half-width, in function value space, of the on-surface band around the zero level set. Points within this band are labeled as on the surface.
Default:1e-06
C++ Type:Real
Unit:(no unit assumed)
Controllable:No
Description:Half-width, in function value space, of the on-surface band around the zero level set. Points within this band are labeled as on the surface.

Optional Parameters

allow_duplicate_execution_on_initialFalseIn the case where this UserObject is depended upon by an initial condition, allow it to be executed twice during the initial setup (once before the IC and again after mesh adaptivity (if applicable).
Default:False
C++ Type:bool
Controllable:No
Description:In the case where this UserObject is depended upon by an initial condition, allow it to be executed twice during the initial setup (once before the IC and again after mesh adaptivity (if applicable).
execute_onTIMESTEP_ENDThe 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.
Default:TIMESTEP_END
C++ Type:ExecFlagEnum
Options:XFEM_MARK, FORWARD, ADJOINT, HOMOGENEOUS_FORWARD, ADJOINT_TIMESTEP_BEGIN, ADJOINT_TIMESTEP_END, NONE, INITIAL, LINEAR, LINEAR_CONVERGENCE, NONLINEAR, NONLINEAR_CONVERGENCE, POSTCHECK, TIMESTEP_END, TIMESTEP_BEGIN, MULTIAPP_FIXED_POINT_END, MULTIAPP_FIXED_POINT_BEGIN, MULTIAPP_FIXED_POINT_CONVERGENCE, MULTISYSTEM_FIXED_POINT_ITERATION_END, FINAL, CUSTOM, TRANSFER
Controllable:No
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.
execution_order_group0Execution order groups are executed in increasing order (e.g., the lowest number is executed first). Note that negative group numbers may be used to execute groups before the default (0) group. Please refer to the user object documentation for ordering of user object execution within a group.
Default:0
C++ Type:int
Controllable:No
Description:Execution order groups are executed in increasing order (e.g., the lowest number is executed first). Note that negative group numbers may be used to execute groups before the default (0) group. Please refer to the user object documentation for ordering of user object execution within a group.
force_postauxFalseForces the UserObject to be executed in POSTAUX
Default:False
C++ Type:bool
Controllable:No
Description:Forces the UserObject to be executed in POSTAUX
force_preauxFalseForces the UserObject to be executed in PREAUX
Default:False
C++ Type:bool
Controllable:No
Description:Forces the UserObject to be executed in PREAUX
force_preicFalseForces the UserObject to be executed in PREIC during initial setup
Default:False
C++ Type:bool
Controllable:No
Description:Forces the UserObject to be executed in PREIC during initial setup

Execution Scheduling 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:Yes
Description:Set the enabled status of the MooseObject.
use_displaced_meshFalseWhether or not this object should use the displaced mesh for computation. Note that in the case this is true but no displacements are provided in the Mesh block the undisplaced mesh will still be used.
Default:False
C++ Type:bool
Controllable:No
Description:Whether or not this object should use the displaced mesh for computation. Note that in the case this is true but no displacements are provided in the Mesh block the undisplaced mesh will still be used.

Advanced Parameters

prop_getter_suffixAn optional suffix parameter that can be appended to any attempt to retrieve/get material properties. The suffix will be prepended with a '_' character.
C++ Type:MaterialPropertyName
Unit:(no unit assumed)
Controllable:No
Description:An optional suffix parameter that can be appended to any attempt to retrieve/get material properties. The suffix will be prepended with a '_' character.
use_interpolated_stateFalseFor the old and older state use projected material properties interpolated at the quadrature points. To set up projection use the ProjectedStatefulMaterialStorageAction.
Default:False
C++ Type:bool
Controllable:No
Description:For the old and older state use projected material properties interpolated at the quadrature points. To set up projection use the ProjectedStatefulMaterialStorageAction.

Material Property Retrieval Parameters

Input Files

(modules/shifted_boundary_method/test/tests/distance_calc/2D_signed_distance.i)
(test/tests/userobjects/point_in_union/union_nested.i)
(test/tests/userobjects/point_in_union/union_mesh_and_function.i)
(modules/shifted_boundary_method/test/tests/in_out_test/2D_lambda0p5.i)
(test/tests/userobjects/point_in_union/union_tristate.i)

(modules/shifted_boundary_method/test/tests/distance_calc/2D_signed_distance.i)

nx = 16
# Asymmetric immersed geometry: a non-circular closed curve. A circle is maximally
# symmetric (every diameter is a symmetry axis), so an element centroid can sit
# exactly on a symmetry axis and become equidistant to two surface segments. That
# KDTree nearest-segment tie is broken only by floating-point round-off, which
# differs across platforms and flips the gradient direction. Deforming the boundary
# with a radial modulation removes all symmetry, so every centroid has a unique
# nearest segment and the in-out sign / gradient stay reproducible across platforms.
R = 1.3
cx = 2.03
cy = 1.97
# Control the boundary asymmetry (radial modulation amplitudes).
a = 0.18
b = 0.10
n_seg = 64
[Problem]
  solve = false
[]

[Mesh]
  [shift_boundary_mesh]
    type = ParsedCurveGenerator
    x_formula = '${cx} + ${R} * (1 + ${a} * cos(t) + ${b} * sin(2*t)) * cos(t)'
    y_formula = '${cy} + ${R} * (1 + ${a} * cos(t) + ${b} * sin(2*t)) * sin(t)'
    section_bounding_t_values = '0 ${fparse 2*pi}'
    nums_segments = '${n_seg}'
    is_closed_loop = true
    save_with_name = 'shift_boundary_mesh'
  []

  [gen]
    type = CartesianMeshGenerator
    dim = 2
    dx = '4'
    dy = '4'
    ix = '${nx}'
    iy = '${nx}'
    subdomain_id = '1'
  []

  add_subdomain_ids = 2 # outside block
  add_sideset_names = 'SBMinterface'
  final_generator = 'gen'
[]

[UserObjects]
  [TreeBuilder]
    type = SBMSurfaceMeshBuilder
    surface_mesh = shift_boundary_mesh
  []
  [signed_distance_to_surface]
    type = ShortestDistanceToSurface
    surfaces = 'sign_dist_square'
    signed_distance = true
  []
  [distance_to_surface]
    type = ShortestDistanceToSurface
    surfaces = 'dist_square'
  []
  [InOutTest]
    type = PointInPolyhedronCheckUO
    builder = TreeBuilder
    # A user-selected axis-aligned ray avoids the PCA/SVD direction ambiguity of
    # an isotropic shape (circle), which is not reproducible across platforms.
    point_containment_method = user_selected_ray
    ray_direction = '1 0 0'
  []
  [SignedFunctionTest]
    type = PointInSignedFunctionCheckUO
    function = level_set
  []
[]

[Functions]
  [level_set]
    # Const level set that is > 0, so if we union with this, it does not change any behavior
    # (IN/OUT/ON still remain).
    type = ConstantFunction
    value = 1
  []
  [dist_square]
    type = UnsignedDistanceToSurfaceMesh
    builder = TreeBuilder
  []
  [sign_dist_square]
    type = SignedDistanceToSurfaceMesh
    builder = TreeBuilder
    in_out_test = InOutTest
  []
[]

[Variables]
  [u]
    initial_condition = 1
    block = 1
  []
[]

[AuxVariables]
  [signed_distance]
    order = CONSTANT
    family = MONOMIAL
  []
  [unsigned_distance]
    order = CONSTANT
    family = MONOMIAL
  []
  # Vector field capturing the signed-distance gradient direction. Sampling the
  # gradient at every element centroid exercises points both inside and outside
  # the circle, so the gold pins down the outward-pointing direction on both sides.
  [signed_distance_grad]
    order = CONSTANT
    family = MONOMIAL_VEC
  []
[]

[AuxKernels]
  [signed_dist]
    type = ElementCentroidToSurfaceDistanceAux
    distance_to_surface = signed_distance_to_surface
    variable = signed_distance
    execute_on = 'INITIAL timestep_begin'
  []
  [unsigned_dist]
    type = ElementCentroidToSurfaceDistanceAux
    distance_to_surface = distance_to_surface
    variable = unsigned_distance
    execute_on = 'INITIAL timestep_begin'
  []
  [signed_dist_grad]
    type = FunctorElementalGradientAux
    functor = sign_dist_square
    variable = signed_distance_grad
    execute_on = 'INITIAL timestep_begin'
  []
[]

[Executioner]
  type = Steady
[]

[Outputs]
  exodus = true
[]

(test/tests/userobjects/point_in_union/union_nested.i)

# Nested union test. A union is itself a provider of another union:
#   inner = union(funcA = x - 1, funcB = x - 2)
#   outer = union(inner, funcC = x - 2.5)
# Nodes are at x = 0, 1, 2, 3:
#   x = 0 : inner INSIDE                      -> outer INSIDE  (2)
#   x = 1 : inner INSIDE                      -> outer INSIDE  (2)
#   x = 2 : inner ON , C INSIDE (2 < 2.5)     -> outer INSIDE  (2)  (nested ON beaten by sibling INSIDE)
#   x = 3 : inner OUTSIDE, C OUTSIDE          -> outer OUTSIDE (0)
# Proves the documented nesting and that precedence flows through nested unions.

[Problem]
  solve = false
[]

[Mesh]
  [gen]
    type = CartesianMeshGenerator
    dim = 2
    dx = '3'
    dy = '1'
    ix = '3'
    iy = '1'
    subdomain_id = '1'
  []
[]

[Functions]
  [funcA]
    type = ParsedFunction
    expression = 'x - 1'
  []
  [funcB]
    type = ParsedFunction
    expression = 'x - 2'
  []
  [funcC]
    type = ParsedFunction
    expression = 'x - 2.5'
  []
[]

[AuxVariables]
  [sideness]
    family = LAGRANGE
    order = FIRST
  []
[]

[AuxKernels]
  [sideness]
    type = SurfaceSidenessTestAux
    variable = sideness
    user_object = outer
    execute_on = 'initial'
  []
[]

[UserObjects]
  [checkA]
    type = PointInSignedFunctionCheckUO
    function = funcA
  []
  [checkB]
    type = PointInSignedFunctionCheckUO
    function = funcB
  []
  [checkC]
    type = PointInSignedFunctionCheckUO
    function = funcC
  []
  [inner]
    type = PointInUnionCheckUO
    providers = 'checkA checkB'
  []
  [outer]
    type = PointInUnionCheckUO
    providers = 'inner checkC'
  []
[]

[Executioner]
  type = Steady
[]

[Outputs]
  exodus = true
[]

(test/tests/userobjects/point_in_union/union_mesh_and_function.i)

# Mixed-representation union. One geometry is a meshed closed surface (a circle
# handed to a BoundaryMeshBuilder and PointInPolyhedronCheckUO); the other is a
# signed level set (a circle signed-distance function checked by
# PointInSignedFunctionCheckUO). PointInUnionCheckUO reports a point contained when
# it is inside either. This exercises both checker types through one union.

[Problem]
  solve = false
[]

[Mesh]
  [circle1]
    type = ParsedCurveGenerator
    x_formula = '1.0 + 0.8 * cos(t)'
    y_formula = '2.0 + 0.8 * sin(t)'
    section_bounding_t_values = '0 ${fparse 2*pi}'
    nums_segments = '48'
    is_closed_loop = true
    save_with_name = 'circle1'
  []
  [gen]
    type = CartesianMeshGenerator
    dim = 2
    dx = '4'
    dy = '4'
    ix = '16'
    iy = '16'
    subdomain_id = '1'
  []
  final_generator = 'gen'
[]

[Functions]
  # Signed distance to a circle at (3, 2), radius 0.8 (negative inside).
  [circle2_sdf]
    type = ParsedFunction
    expression = 'sqrt((x - 3.0)^2 + (y - 2.0)^2) - 0.8'
  []
[]

[AuxVariables]
  [inside]
    family = MONOMIAL
    order = CONSTANT
  []
[]

[AuxKernels]
  [inside]
    type = SpatialUserObjectAux
    variable = inside
    user_object = union
    execute_on = 'initial'
  []
[]

[UserObjects]
  [builder1]
    type = BoundaryMeshBuilder
    surface_mesh = circle1
  []
  [check_mesh]
    type = PointInPolyhedronCheckUO
    builder = builder1
    point_containment_method = pca_ray
  []
  [check_func]
    type = PointInSignedFunctionCheckUO
    function = circle2_sdf
  []
  [union]
    type = PointInUnionCheckUO
    providers = 'check_mesh check_func'
  []
[]

[Executioner]
  type = Steady
[]

[Outputs]
  exodus = true
[]

(modules/shifted_boundary_method/test/tests/in_out_test/2D_lambda0p5.i)

nx = 16
lambda = 0.5
# Immersed ellipse geometry: distinct semi-axes make the boundary anisotropic so
# PCA has a well-separated minor axis, giving a reproducible auto ray direction.
# Off-grid center keeps the arc cutting elements at generic fractions with no
# node/quadrature point landing exactly on the surface.
a = 1.6
b = 1.0
cx = 2.03
cy = 1.97
n_seg = 48
[Problem]
  solve = false
[]

[Mesh]
  [shift_boundary_mesh]
    type = ParsedCurveGenerator
    x_formula = '${cx} + ${a} * cos(t)'
    y_formula = '${cy} + ${b} * sin(t)'
    section_bounding_t_values = '0 ${fparse 2*pi}'
    nums_segments = '${n_seg}'
    is_closed_loop = true
    save_with_name = 'shift_boundary_mesh'
  []

  [gen]
    type = CartesianMeshGenerator
    dim = 2
    dx = '4'
    dy = '4'
    ix = '${nx}'
    iy = '${nx}'
    subdomain_id = '1'
  []

  add_subdomain_ids = 2 # outside block
  add_sideset_names = 'SBMinterface'
  final_generator = 'gen'
[]

[Functions]
  [level_set]
    type = ParsedFunction
    expression = '((x - ${cx}) / ${a})^2 + ((y - ${cy}) / ${b})^2 - 1'
  []
[]

[UserObjects]
  [TreeBuilder]
    type = SBMSurfaceMeshBuilder
    check_watertightness = true
    surface_mesh = shift_boundary_mesh
  []

  [inout_test]
    type = PointInPolyhedronCheckUO
    builder = TreeBuilder
  []
  [signed_function_test]
    type = PointInSignedFunctionCheckUO
    function = level_set
  []
[]

[MeshModifiers]
  [IntercpetedESM]
    type = InterceptedElementModifier
    subdomain_id_inside = 1
    subdomain_id_outside = 2
    lambda = ${lambda}
    is_domain_inside_surface = true
    in_out_test = inout_test
    execute_on = 'INITIAL'
    execution_order_group = 0
  []
  [SBMinterface]
    type = SidesetAroundSubdomainUpdater
    inner_subdomains = 1
    outer_subdomains = 2
    update_sideset_name = 'SBMinterface'
    assign_outer_surface_sides = false
    execute_on = 'INITIAL'
    execution_order_group = 1
    block = '1 2' # need to override default block
  []
[]

[Variables]
  [u]
    initial_condition = 1
    block = 1
  []
[]

[Executioner]
  type = Steady
[]

[Outputs]
  exodus = true
[]

(test/tests/userobjects/point_in_union/union_tristate.i)

# Tri-state union test. Two signed half-space level sets are unioned; nodes along
# x deterministically realize each precedence case (INSIDE > ON > OUTSIDE):
#   funcA = x - 1  (inside where x < 1),  funcB = x - 2  (inside where x < 2)
# Nodes are at x = 0, 1, 2, 3:
#   x = 0 : A INSIDE , B INSIDE  -> INSIDE  (2)
#   x = 1 : A ON     , B INSIDE  -> INSIDE  (2)   (ON overridden by INSIDE)
#   x = 2 : A OUTSIDE, B ON      -> ON      (1)   (ON over OUTSIDE)
#   x = 3 : A OUTSIDE, B OUTSIDE -> OUTSIDE (0)
# SurfaceSidenessTestAux reports the raw tri-state (outside=0, on=1, inside=2), so
# the gold distinguishes ON from INSIDE (which spatialValue() would collapse).

[Problem]
  solve = false
[]

[Mesh]
  [gen]
    type = CartesianMeshGenerator
    dim = 2
    dx = '3'
    dy = '1'
    ix = '3'
    iy = '1'
    subdomain_id = '1'
  []
[]

[Functions]
  [funcA]
    type = ParsedFunction
    expression = 'x - 1'
  []
  [funcB]
    type = ParsedFunction
    expression = 'x - 2'
  []
[]

[AuxVariables]
  [sideness]
    family = LAGRANGE
    order = FIRST
  []
[]

[AuxKernels]
  [sideness]
    type = SurfaceSidenessTestAux
    variable = sideness
    user_object = union
    execute_on = 'initial'
  []
[]

[UserObjects]
  [checkA]
    type = PointInSignedFunctionCheckUO
    function = funcA
  []
  [checkB]
    type = PointInSignedFunctionCheckUO
    function = funcB
  []
  [union]
    type = PointInUnionCheckUO
    providers = 'checkA checkB'
  []
[]

[Executioner]
  type = Steady
[]

[Outputs]
  exodus = true
[]

Sign convention
Tolerance and the on - surface band
Usage
Input Parameters
Input Files