PerElementParticleInitializer

Particle initializer that uniformly distributes a specified number of particles per element and calculates the corresponding particle weight based on the requested number density, particles per element, and the elements "volume".

Overview

Because the charge density in SALAMANDER is defined by Dirac delta functions and each computational particle represents some number of physical particles, computational particles are assigned a weight $var element = document.getElementById("moose-equation-e0edda6d-cc95-45a2-a818-287ec242b17e");katex.render("\\omega_i", element, {displayMode:false,throwOnError:false});$ . In cartesian geometry this weight represents the number of physical particles per [m $var element = document.getElementById("moose-equation-f6b2f855-e28c-42f9-aa62-2272b344044d");katex.render("^{3-d}", element, {displayMode:false,throwOnError:false});$ ] where $var element = document.getElementById("moose-equation-5fcb3920-f1fc-4d4e-bc80-3de3e12a43e7");katex.render("d", element, {displayMode:false,throwOnError:false});$ is the dimension of the problem.

warning

The weight calculation for particles has only been implemented for Cartesian domains and may not be valid for Non-Cartesian domains.

In this object the weight of the $var element = document.getElementById("moose-equation-48f5dadd-605c-44eb-88d1-5aa3e062d1f1");katex.render("j^\\text{th}", element, {displayMode:false,throwOnError:false});$ particle is given by

$var element = document.getElementById("moose-equation-b107561e-7754-4935-b49c-71cb5fb2ffb6");katex.render(" \\omega_j \\equiv \\frac{ N \\; V_j }{ \\text{ppe} },", element, {displayMode:true,throwOnError:false});$

where $var element = document.getElementById("moose-equation-8093e42c-58d7-4dd1-a7ea-87776cf8e7db");katex.render("N", element, {displayMode:false,throwOnError:false});$ is the requested number density, $var element = document.getElementById("moose-equation-11c7787a-05a1-428c-a408-b2496cdabdb4");katex.render("V_j", element, {displayMode:false,throwOnError:false});$ is the dimension dependent "volume" (length in 1D, area in 2D and volume in 3D) of the element the particle is being placed in and ppe is the requested number of particles per element.

Example Input Syntax

[UserObjects<<<{"href": "../../syntax/UserObjects/index.html"}>>>]
  [initializer]
    type = PerElementParticleInitializer<<<{"description": "Particle initializer that uniformly distributes a specified number of particles per element and calculates the corresponding particle weight based on the requested number density, particles per element, and the elements \"volume\".", "href": "PerElementParticleInitializer.html"}>>>
    mass<<<{"description": "The mass of the particles being placed in the mesh"}>>> = 1
    charge<<<{"description": "The charge of the particles being placed in the mesh"}>>> = 1
    number_density<<<{"description": "The number density of particles you want to represent"}>>> = ${charge_density}
    velocity_distributions<<<{"description": "The distribution names to be sampled when initializing the velocity of each particle"}>>> = 'zero zero zero'
  []
[]

Input Parameters

velocity_distributionsThe distribution names to be sampled when initializing the velocity of each particle
C++ Type:std::vector<DistributionName>
Controllable:No
Description:The distribution names to be sampled when initializing the velocity of each particle

Required Parameters

charge1The charge of the particles being placed in the mesh
Default:1
C++ Type:double
Unit:(no unit assumed)
Controllable:No
Description:The charge of the particles being placed in the mesh
mass1The mass of the particles being placed in the mesh
Default:1
C++ Type:double
Unit:(no unit assumed)
Controllable:No
Description:The mass of the particles being placed in the mesh
number_densityThe number density of particles you want to represent
C++ Type:double
Unit:(no unit assumed)
Controllable:No
Description:The number density of particles you want to represent
particles_per_elementThe number of computational particles that should be placed in each element
C++ Type:unsigned int
Controllable:No
Description:The number of computational particles that should be placed in each element
seed0An additional seed for the random number generators
Default:0
C++ Type:unsigned int
Controllable:No
Description:An additional seed for the random number generators
speciesThe type of particle that is being initialized
C++ Type:std::string
Controllable:No
Description:The type of particle that is being initialized

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: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, FINAL, CUSTOM
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

(test/tests/userobjects/particle_initializer/per_element/errors/errors.i)
(test/tests/userobjects/particle_initializer/per_element/elements/initializer_base.i)

Child Objects

(include/userobjects/BoundingBoxParticleInitializer.h)

References

No citations exist within this document.

(test/tests/userobjects/particle_initializer/per_element/elements/1d.i)

!include initializer_base.i

[Mesh]
  [gmg]
    type = GeneratedMeshGenerator
    dim = 1
    nx = 10
    xmax = 1
    elem_type = EDGE2
  []
  allow_renumbering = false
[]

[BCs]
  [potential_solution]
    type = DirichletBC
    variable = phi
    value = 0
    boundary = 'left right'
    preset = false
  []
[]

[Functions]
  [potential]
    type = ParsedFunction
    expression = 'x * (1 - x)'
  []
[]

(test/tests/userobjects/particle_initializer/per_element/errors/errors.i)

[Problem]
  solve = false
[]

[GlobalParams]
  particles_per_element = 10
[]

[Mesh]
  [gmg]
    type = GeneratedMeshGenerator
    dim = 1
  []
[]

[Distributions]
  [zero]
    type = Constant
    value = 0.0
  []
[]

[UserObjects]
  [initializer]
    type = PerElementParticleInitializer
    mass = 1
    charge = 1
    number_density = 2
    velocity_distributions = 'zero zero zero'
  []

  [stepper]
    type = TestSimpleStepper
  []

  [study]
    type = TestInitializedPICStudy
    initializer = initializer
    stepper = stepper
    always_cache_traces = true
    data_on_cache_traces = true
    execute_on=TIMESTEP_BEGIN
  []

  [potential_accumulator]
    type = ChargeDensityAccumulator
    study = study
    variable = phi
    extra_vector_tags = dump_value
  []

  [density_accumulator]
    type = ChargeDensityAccumulator
    study = study
    variable = n
  []
[]


[RayKernels]
  [null]
    type = NullRayKernel
  []
[]

[Executioner]
  type = Steady
[]

(test/tests/userobjects/particle_initializer/per_element/elements/initializer_base.i)

# the number of computational particles to be put in each element
particles_per_element = 10
# the analytic solution for the charge density
# set by cli args for each case since it is needed by all
# tests but changes based on the dimension of the problem
charge_density = 0

[GlobalParams]
  particles_per_element = ${particles_per_element}
[]

[Problem]
  extra_tag_vectors = dump_value
[]

[Variables]
  [phi]
  []

  [n]
  []
[]

[Kernels]
  [poissons]
    type = ADMatDiffusion
    diffusivity = 1
    variable = phi
  []

  [projection]
    type = ProjectionKernel
    variable = n
  []
[]


[AuxVariables]
  [dump_value]
  []
[]

[AuxKernels]
  [dump_value]
    type = TagVectorAux
    variable = dump_value
    vector_tag = dump_value
    v = phi
  []
[]

[Distributions]
  [zero]
    type = Constant
    value = 0.0
  []
[]

[UserObjects]
  [initializer]
    type = PerElementParticleInitializer
    mass = 1
    charge = 1
    number_density = ${charge_density}
    velocity_distributions = 'zero zero zero'
  []

  [stepper]
    type = TestSimpleStepper
  []

  [study]
    type = TestInitializedPICStudy
    initializer = initializer
    stepper = stepper
    always_cache_traces = true
    data_on_cache_traces = true
    execute_on=TIMESTEP_BEGIN
  []

  [potential_accumulator]
    type = ChargeDensityAccumulator
    study = study
    variable = phi
    extra_vector_tags = dump_value
  []

  [density_accumulator]
    type = ChargeDensityAccumulator
    study = study
    variable = n
  []
[]


[RayKernels]
  [null]
    type = NullRayKernel
  []
[]

[Functions]
  [charge_density]
    type = ParsedFunction
    expression = ${charge_density}
  []
[]


[Postprocessors]
  [potential_l2]
    type = ElementL2Error
    variable = phi
    function = potential
  []

  [density_l2]
    type = ElementL2Error
    variable = n
    function = charge_density
  []

  [particles_per_element]
    type = ConstantPostprocessor
    value = ${particles_per_element}
  []

  [h]
    type = AverageElementSize
  []
[]

[Executioner]
  type = Transient
  solve_type = NEWTON
  petsc_options_iname = '-pc_type -pc_factor_shift_type -pc_factor_shift_amount -pc_factor_mat_solver'
  petsc_options_value = 'lu NONZERO 1.e-9 superlu_dists'
  line_search = 'none'
  nl_max_its = 15
  l_max_its = 300
  scheme = 'bdf2'
  automatic_scaling = true
  compute_scaling_once = false
  dt = 1
  num_steps = 1
[]

[Outputs]
  exodus = true
  [csv]
    type = CSV
    execute_on = TIMESTEP_END
  []
  [rays]
    type = RayTracingExodus
    study = study
    output_data_names = 'charge weight mass'
    execute_on = TIMESTEP_END
  []
[]

(include/userobjects/BoundingBoxParticleInitializer.h)

// This file is part of SALAMANDER: Software for Advanced Large-scale Analysis of MAgnetic confinement for Numerical Design, Engineering & Research,
// A multiphysics application for modeling plasma facing components
// https://github.com/idaholab/salamander
// https://mooseframework.inl.gov/salamander
//
// SALAMANDER is powered by the MOOSE Framework
// https://www.mooseframework.inl.gov
//
// Licensed under LGPL 2.1, please see LICENSE for details
// https://www.gnu.org/licenses/lgpl-2.1.html
//
// Copyright 2025, Battelle Energy Alliance, LLC
// ALL RIGHTS RESERVED
//

#pragma once

#include "PerElementParticleInitializer.h"

class BoundingBoxParticleInitializer : public PerElementParticleInitializer
{
public:
  BoundingBoxParticleInitializer(const InputParameters & parameters);

  static InputParameters validParams();
  /**
   * Initialization that applies a bounding box to
   * PerElementParticleInitializer
   * if the bounding box encompasses the whole domain then these are the same
   */
  virtual std::vector<InitialParticleData> getParticleData() const override;

protected:
  /// The Point object constructed from the x1, y1, z1 components for the bottom left BB corner
  const Point _bottom_left;

  /// The Point object constructed from the x2, y2, z2 components for the bottom left BB corner
  const Point _top_right;
  /// Holds the coefficients for each of the planes which are required for checking if an element is contained within the bounding box
  const std::vector<std::vector<Real>> _planes;
};

Overview
Example Input Syntax
Input Parameters
Input Files
Child Objects
References