TimeStepper implementation for advancing Brownian walker particles. More...

#include <CD_BrownianWalkerStepper.H>

Inheritance diagram for Physics::BrownianWalker::BrownianWalkerStepper:

Collaboration diagram for Physics::BrownianWalker::BrownianWalkerStepper:

Public Member Functions
	BrownianWalkerStepper ()
	Default constructor. Parses all options from the BrownianWalker ParmParse block.

	BrownianWalkerStepper (const std::string &a_className)
	Constructor which sets the input-script prefix this stepper reads its options under.

	BrownianWalkerStepper (RefCountedPtr< ItoSolver > &a_solver, const std::string &a_className)
	Full constructor for a derived stepper.

	BrownianWalkerStepper (RefCountedPtr< ItoSolver > &a_solver)
	Full constructor. Delegates to the default constructor and stores the provided solver.

virtual	~BrownianWalkerStepper ()
	Destructor.

void	initialData () override
	Fill the solver with initial particles, make superparticles, and set flow fields.

void	allocate () override
	Allocate internal storage in the solver.

void	postInitialize () override
	Post-initialization hook. No operations are performed.

bool	loadBalanceThisRealm (const std::string &a_realm) const override
	Return whether the given realm should be load balanced by this stepper.

Vector< long int >	getCheckpointLoads (const std::string &a_realm, const int a_level) const override
	Return per-patch computational loads for checkpointing and plotting.

void	loadBalanceBoxes (Vector< Vector< int > > &a_procs, Vector< Vector< Box > > &a_boxes, const std::string &a_realm, const Vector< DisjointBoxLayout > &a_grids, const int a_lmin, const int a_finestLevel) override
	Load balance grid patches for the specified realm.

void	postCheckpointSetup () override
	Post-checkpoint setup. Remaps particles, makes superparticles, and restores advection and diffusion fields after a restart.

int	getNumberOfPlotVariables () const override
	Return the number of output variables contributed by this stepper.

Vector< std::string >	getPlotVariableNames () const override
	Return the names of the output variables contributed by this stepper.

void	writePlotData (LevelData< EBCellFAB > &a_output, int &a_icomp, const std::string &a_outputRealm, const int a_level) const override
	Write plot data into the output holder.

Real	computeDt () override
	Compute the next time step as m_cfl * ItoSolver::computeDt().

void	synchronizeSolverTimes (const int a_step, const Real a_time, const Real a_dt) override
	Update internal time/step counters and forward them to the solver.

void	printStepReport () override
	Print a step report showing the local and global particle counts.

void	postPlot () override
	Perform post-plot operations. Writes the particles if asked to.

void	plotParticles () const noexcept
	Write the solver's bulk particles to an H5Part file, one per plot step.

void	registerOperators () override
	Register the operators required by the solver.

void	registerRealms () override
	Register the realm(s) used in the simulation.

void	parseRuntimeOptions () override
	Parse runtime options from ParmParse. Re-reads verbosity, ppc, CFL, and load balancing flag.

bool	needToRegrid () override
	Always returns false; regridding is triggered externally by Driver.

void	preRegrid (const int a_lbase, const int a_oldFinestLevel) override
	Pre-regrid hook. Deposits particle counts onto the mesh and puts the solver in pre-regrid mode.

void	setupSolvers () override
	Instantiate the species and configure the solver with realm, phase, and AMR data.

Real	advance (const Real a_dt) override
	Advance the particle system by one Euler-Maruyama step.

void	regrid (const int a_lmin, const int a_oldFinestLevel, const int a_newFinestLevel) override
	Regrid the solver onto the new mesh and remake superparticles.

void	postRegrid () override
	Post-regrid hook. Clears temporary mesh storage and restores flow fields.

Public Member Functions inherited from TimeStepper
	TimeStepper ()
	Default constructor (does nothing)

virtual	~TimeStepper ()
	Default destructor (does nothing)

	TimeStepper (const TimeStepper &)=delete
	Disallow copy construction.

TimeStepper &	operator= (const TimeStepper &)=delete
	Disallow copy assignment.

	TimeStepper (TimeStepper &&)=default
	Allow move construction.

TimeStepper &	operator= (TimeStepper &&)=default
	Allow move assignment.

void	setAmr (const RefCountedPtr< AmrMesh > &a_amr)
	Set AmrMesh.

void	setComputationalGeometry (const RefCountedPtr< ComputationalGeometry > &a_computationalGeometry)
	Set the computational geometry.

virtual void	prePlot ()
	An option for calling special functions prior to plotting data. Called by Driver in the IMMEDIATELY before writing the plot file.

bool	keepGoing () const
	Query whether the time stepper wants to continue stepping.

Protected Types
enum	LoadBalancingMethod { Mesh , Particle }
	Supported load balancing strategies. More...

Protected Member Functions
void	setAdvectionDiffusion ()
	Set the velocity and diffusion fields on the mesh if the solver is mobile/diffusive.

void	setVelocity ()
	Compute and assign the solid-body rotation velocity field to the solver.

void	setDiffusion ()
	Set the mesh diffusion function on the solver.

void	makeSuperParticles ()
	Merge to ItoSolver.particles_per_cell, checking weight conservation if asked.

Real	computeTotalWeight ()
	Compute the global total weight of the bulk particles.

void	loadBalanceBoxesMesh (Vector< Vector< int > > &a_procs, Vector< Vector< Box > > &a_boxes, const std::string &a_realm, const Vector< DisjointBoxLayout > &a_grids, const int a_lmin, const int a_finestLevel)
	Load balance using particle counts estimated from mesh-deposited data.

void	loadBalanceBoxesParticles (Vector< Vector< int > > &a_procs, Vector< Vector< Box > > &a_boxes, const std::string &a_realm, const Vector< DisjointBoxLayout > &a_grids, const int a_lmin, const int a_finestLevel)
	Load balance by directly remapping particles to the new grids and counting them.

Protected Attributes
LoadBalancingMethod	m_whichLoadBalance
	Selected load balancing strategy.

std::string	m_realm
	Name of the realm on which the particles live.

phase::which_phase	m_phase
	Computational phase on which the particles live.

bool	m_loadBalance
	If true, the application performs particle-based load balancing at each regrid.

RefCountedPtr< ItoSolver >	m_solver
	The Ito solver used to advance the particle system.

RefCountedPtr< ItoSpecies >	m_species
	Species definition passed to the Ito solver.

EBAMRCellData	m_regridPPC
	Temporary storage for the number of particles per cell, used during load balancing.

Real	m_diffCo
	Spatially uniform diffusion coefficient for all particles.

Real	m_mobility
	Spatially uniform particle mobility.

Real	m_omega
	Angular velocity of the solid-body rotation advection field.

std::string	m_className
	Input-script prefix this stepper reads its options under.

bool	m_constantVelocity
	If true, the advective field is spatially constant rather than rotational.

RealVect	m_velocity
	The advective field used when m_constantVelocity is true.

bool	m_verifyConservation
	If true, verify that the superparticle merge conserves the total particle weight.

Real	m_cfl
	CFL-like scaling factor applied to the solver's intrinsic time step estimate.

Protected Attributes inherited from TimeStepper
int	m_verbosity
	Class verbosity.

int	m_timeStep
	Time step.

Real	m_time
	TIme.

Real	m_dt
	Previous time step size.

bool	m_keepGoing
	If false, Driver will stop the time loop after the current step.

RefCountedPtr< AmrMesh >	m_amr
	AmrMesh.

RefCountedPtr< ComputationalGeometry >	m_computationalGeometry
	Computational geometry.

Detailed Description

TimeStepper implementation for advancing Brownian walker particles.

This class drives a single ItoSolver using an Euler-Maruyama scheme:

\[ \mathbf{X}^{n+1} = \mathbf{X}^n + \mathbf{V}\,\Delta t + \sqrt{2D\,\Delta t}\,\mathbf{N}(0,1) \]

where \(\mathbf{V}\) is the advection velocity, \(D\) is the diffusion coefficient, and \(\mathbf{N}(0,1)\) is a standard Gaussian random vector.

The velocity field is a solid-body rotation with angular velocity \(\omega\), and both the mobility and diffusion coefficient are spatially uniform and set directly on each particle.

This module demonstrates two particle-based load balancing strategies:

Mesh-based: estimates the particle count on new grids from mesh-deposited data (faster).
Particle-based: directly remaps and counts particles on the new grids (more accurate).

Member Enumeration Documentation

◆ LoadBalancingMethod

enum Physics::BrownianWalker::BrownianWalkerStepper::LoadBalancingMethod

protected

Supported load balancing strategies.

Enumerator
Mesh	Estimate particle counts from mesh-deposited data (fast).
Particle	Count particles directly by remapping to the new grids (accurate).

Constructor & Destructor Documentation

◆ BrownianWalkerStepper() [1/3]

BrownianWalkerStepper::BrownianWalkerStepper ( const std::string & a_className )

Constructor which sets the input-script prefix this stepper reads its options under.

Every option of a derived stepper – the ones it inherits and the ones it adds – then lives under one prefix that matches the derived class, rather than the user having to know which of two prefixes a given option belongs to. Defaults to 'BrownianWalker' for this class.

Parameters

[in] a_className Input-script prefix.

◆ BrownianWalkerStepper() [2/3]

BrownianWalkerStepper::BrownianWalkerStepper	(	RefCountedPtr< ItoSolver > &	a_solver,
		const std::string &	a_className
	)

Full constructor for a derived stepper.

Parameters

[in]	a_solver	Ito solver to advance.
[in]	a_className	Input-script prefix.

◆ BrownianWalkerStepper() [3/3]

BrownianWalkerStepper::BrownianWalkerStepper ( RefCountedPtr< ItoSolver > & a_solver )

Full constructor. Delegates to the default constructor and stores the provided solver.

Parameters

[in] a_solver Ito solver to use for particle advancement.

Member Function Documentation

◆ advance()

Real BrownianWalkerStepper::advance ( const Real a_dt )

overridevirtual

Advance the particle system by one Euler-Maruyama step.

Performs: advection hop, diffusion hop, remap, EB absorption, superparticle merging, field update, and mesh deposition.

Parameters

[in] a_dt Time step size in seconds.

Returns: The time step actually used (equal to a_dt).

Implements TimeStepper.

◆ allocate()

void BrownianWalkerStepper::allocate ( )

overridevirtual

Allocate internal storage in the solver.

Implements TimeStepper.

◆ computeDt()

Real BrownianWalkerStepper::computeDt ( )

overridevirtual

Compute the next time step as m_cfl * ItoSolver::computeDt().

Returns: Time step size in seconds.

Implements TimeStepper.

◆ computeTotalWeight()

Real BrownianWalkerStepper::computeTotalWeight ( )

protected

Compute the global total weight of the bulk particles.

Folds the weight column over every leaf of the bulk container with ParticleLoops::reduce and MPI-reduces the result. Reads the container as-is, independent of whether it is organized by cell or by patch. Used by the conservation check.

Returns: Global (MPI-reduced) sum of all bulk particle weights.

◆ getCheckpointLoads()

Vector< long int > BrownianWalkerStepper::getCheckpointLoads	(	const std::string &	a_realm,
		const int	a_level
	)		const

overridevirtual

Return per-patch computational loads for checkpointing and plotting.

Uses the number of particles in each grid patch as the load metric.

Parameters

[in]	a_realm	Realm identifier.
[in]	a_level	AMR level.

Returns: Vector of particle counts, one entry per grid patch on a_level.

Reimplemented from TimeStepper.

◆ getNumberOfPlotVariables()

int BrownianWalkerStepper::getNumberOfPlotVariables ( ) const

overridevirtual

Return the number of output variables contributed by this stepper.

Returns: Number of plot variables (delegated to the solver).

Implements TimeStepper.

◆ getPlotVariableNames()

Vector< std::string > BrownianWalkerStepper::getPlotVariableNames ( ) const

overridevirtual

Return the names of the output variables contributed by this stepper.

Returns: Variable name list (delegated to the solver).

Implements TimeStepper.

◆ initialData()

void BrownianWalkerStepper::initialData ( )

overridevirtual

Fill the solver with initial particles, make superparticles, and set flow fields.

Implements TimeStepper.

◆ loadBalanceBoxes()

void BrownianWalkerStepper::loadBalanceBoxes	(	Vector< Vector< int > > &	a_procs,
		Vector< Vector< Box > > &	a_boxes,
		const std::string &	a_realm,
		const Vector< DisjointBoxLayout > &	a_grids,
		const int	a_lmin,
		const int	a_finestLevel
	)

overridevirtual

Load balance grid patches for the specified realm.

Dispatches to either loadBalanceBoxesMesh or loadBalanceBoxesParticles depending on m_whichLoadBalance.

Parameters

[out]	a_procs	MPI rank assigned to each grid patch.
[out]	a_boxes	Grid patches on each level.
[in]	a_realm	Realm identifier.
[in]	a_grids	Current grids before load balancing.
[in]	a_lmin	Coarsest level that changed.
[in]	a_finestLevel	Finest level after regridding.

Reimplemented from TimeStepper.

◆ loadBalanceBoxesMesh()

void BrownianWalkerStepper::loadBalanceBoxesMesh	(	Vector< Vector< int > > &	a_procs,
		Vector< Vector< Box > > &	a_boxes,
		const std::string &	a_realm,
		const Vector< DisjointBoxLayout > &	a_grids,
		const int	a_lmin,
		const int	a_finestLevel
	)

protected

Load balance using particle counts estimated from mesh-deposited data.

Uses the particle-per-cell data deposited during preRegrid to estimate the post-regrid particle distribution without remapping particles. Faster than loadBalanceBoxesParticles but may be less accurate after superparticle merging.

Parameters

[out]	a_procs	MPI rank assigned to each grid patch.
[out]	a_boxes	Grid patches on each level.
[in]	a_realm	Realm identifier.
[in]	a_grids	Current grids.
[in]	a_lmin	Coarsest level that changed.
[in]	a_finestLevel	Finest level after regridding.

◆ loadBalanceBoxesParticles()

void BrownianWalkerStepper::loadBalanceBoxesParticles	(	Vector< Vector< int > > &	a_procs,
		Vector< Vector< Box > > &	a_boxes,
		const std::string &	a_realm,
		const Vector< DisjointBoxLayout > &	a_grids,
		const int	a_lmin,
		const int	a_finestLevel
	)

protected

Load balance by directly remapping particles to the new grids and counting them.

More accurate than loadBalanceBoxesMesh, but requires remapping the particle data twice (once here and once in regrid), making it slower at large particle counts.

Parameters

[out]	a_procs	MPI rank assigned to each grid patch.
[out]	a_boxes	Grid patches on each level.
[in]	a_realm	Realm identifier.
[in]	a_grids	Current grids.
[in]	a_lmin	Coarsest level that changed.
[in]	a_finestLevel	Finest level after regridding.

◆ loadBalanceThisRealm()

bool BrownianWalkerStepper::loadBalanceThisRealm ( const std::string & a_realm ) const

overridevirtual

Return whether the given realm should be load balanced by this stepper.

Parameters

[in] a_realm Realm identifier to query.

Returns: True if a_realm matches m_realm and load balancing is enabled.

Reimplemented from TimeStepper.

◆ makeSuperParticles()

void BrownianWalkerStepper::makeSuperParticles ( )

protected

Merge to ItoSolver.particles_per_cell, checking weight conservation if asked.

If m_verifyConservation is set, the total particle weight is checked for conservation across the merge and the run is aborted if it is violated.

◆ needToRegrid()

bool BrownianWalkerStepper::needToRegrid ( )

overridevirtual

Always returns false; regridding is triggered externally by Driver.

Returns: False.

Reimplemented from TimeStepper.

◆ parseRuntimeOptions()

void BrownianWalkerStepper::parseRuntimeOptions ( )

overridevirtual

Parse runtime options from ParmParse. Re-reads verbosity, ppc, CFL, and load balancing flag.

Reimplemented from TimeStepper.

◆ plotParticles()

void BrownianWalkerStepper::plotParticles ( ) const

noexcept

Write the solver's bulk particles to an H5Part file, one per plot step.

Controlled by BrownianWalker.plot_particles. Files land in particles/<solver>/<solver>.step<step>.<dim>d.h5part, matching the layout ItoKMCGodunovStepper uses, so the same post-processing works on both.

◆ postCheckpointSetup()

void BrownianWalkerStepper::postCheckpointSetup ( )

overridevirtual

Post-checkpoint setup. Remaps particles, makes superparticles, and restores advection and diffusion fields after a restart.

Implements TimeStepper.

◆ postInitialize()

void BrownianWalkerStepper::postInitialize ( )

overridevirtual

Post-initialization hook. No operations are performed.

Implements TimeStepper.

◆ postPlot()

void BrownianWalkerStepper::postPlot ( )

overridevirtual

Perform post-plot operations. Writes the particles if asked to.

Reimplemented from TimeStepper.

◆ postRegrid()

void BrownianWalkerStepper::postRegrid ( )

overridevirtual

Post-regrid hook. Clears temporary mesh storage and restores flow fields.

Implements TimeStepper.

◆ preRegrid()

void BrownianWalkerStepper::preRegrid	(	const int	a_lbase,
		const int	a_oldFinestLevel
	)

overridevirtual

Pre-regrid hook. Deposits particle counts onto the mesh and puts the solver in pre-regrid mode.

Parameters

[in]	a_lbase	Coarsest level that will change.
[in]	a_oldFinestLevel	Finest level before regridding.

Implements TimeStepper.

◆ printStepReport()

void BrownianWalkerStepper::printStepReport ( )

overridevirtual

Print a step report showing the local and global particle counts.

Implements TimeStepper.

◆ registerOperators()

void BrownianWalkerStepper::registerOperators ( )

overridevirtual

Register the operators required by the solver.

Implements TimeStepper.

◆ registerRealms()

void BrownianWalkerStepper::registerRealms ( )

overridevirtual

Register the realm(s) used in the simulation.

Implements TimeStepper.

◆ regrid()

void BrownianWalkerStepper::regrid	(	const int	a_lmin,
		const int	a_oldFinestLevel,
		const int	a_newFinestLevel
	)

overridevirtual

Regrid the solver onto the new mesh and remake superparticles.

Parameters

[in]	a_lmin	Coarsest level that changed.
[in]	a_oldFinestLevel	Finest level before regridding.
[in]	a_newFinestLevel	Finest level after regridding.

Implements TimeStepper.

◆ setDiffusion()

void BrownianWalkerStepper::setDiffusion ( )

protected

Set the mesh diffusion function on the solver.

Sets the spatially uniform coefficient m_diffCo. The per-particle diffusion coefficients are assigned directly through ItoSolver::setParticleDiffusion, so this field does not move the walkers, but it is the field that is plotted as 'dco' and the field a grad(D) drift correction would differentiate.

◆ setupSolvers()

void BrownianWalkerStepper::setupSolvers ( )

overridevirtual

Instantiate the species and configure the solver with realm, phase, and AMR data.

Implements TimeStepper.

◆ synchronizeSolverTimes()

void BrownianWalkerStepper::synchronizeSolverTimes	(	const int	a_step,
		const Real	a_time,
		const Real	a_dt
	)

overridevirtual

Update internal time/step counters and forward them to the solver.

Parameters

[in]	a_step	Current time step number.
[in]	a_time	Current simulation time in seconds.
[in]	a_dt	Time step that was used.

Implements TimeStepper.

◆ writePlotData()

void BrownianWalkerStepper::writePlotData	(	LevelData< EBCellFAB > &	a_output,
		int &	a_icomp,
		const std::string &	a_outputRealm,
		const int	a_level
	)		const

overridevirtual

Write plot data into the output holder.

Parameters

[in,out]	a_output	Output data holder.
[in,out]	a_icomp	Starting component index in a_output; incremented on return.
[in]	a_outputRealm	Realm that owns a_output.
[in]	a_level	AMR level to write.

Implements TimeStepper.

Member Data Documentation

◆ m_className

std::string Physics::BrownianWalker::BrownianWalkerStepper::m_className

protected

Input-script prefix this stepper reads its options under.

'BrownianWalker' for this class; a derived stepper passes its own name so that every option it reads lives under one prefix.

◆ m_constantVelocity

bool Physics::BrownianWalker::BrownianWalkerStepper::m_constantVelocity

protected

If true, the advective field is spatially constant rather than rotational.

BrownianWalker.velocity_field. A constant field translates the whole population rigidly, which keeps the particle distribution uniform as it moves – useful when the point of the run is what some other operator does to that distribution rather than what the flow does to it.

◆ m_velocity

RealVect Physics::BrownianWalker::BrownianWalkerStepper::m_velocity

protected

The advective field used when m_constantVelocity is true.

BrownianWalker.constant_velocity.

◆ m_verifyConservation

bool Physics::BrownianWalker::BrownianWalkerStepper::m_verifyConservation

protected

If true, verify that the superparticle merge conserves the total particle weight.

When set, makeSuperParticles() sums the global (MPI-reduced) particle weight before and after the merge and calls MayDay::Abort if the two differ by more than a small relative tolerance. Off by default – it costs two global reductions per merge, so it is intended for regression testing rather than production runs.

The documentation for this class was generated from the following files:

Physics/BrownianWalker/CD_BrownianWalkerStepper.H
Physics/BrownianWalker/CD_BrownianWalkerStepper.cpp

Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ LoadBalancingMethod

Constructor & Destructor Documentation

◆ BrownianWalkerStepper() [1/3]

◆ BrownianWalkerStepper() [2/3]

◆ BrownianWalkerStepper() [3/3]

Member Function Documentation

◆ advance()

◆ allocate()

◆ computeDt()

◆ computeTotalWeight()

◆ getCheckpointLoads()

◆ getNumberOfPlotVariables()

◆ getPlotVariableNames()

◆ initialData()

◆ loadBalanceBoxes()

◆ loadBalanceBoxesMesh()

◆ loadBalanceBoxesParticles()

◆ loadBalanceThisRealm()

◆ makeSuperParticles()

◆ needToRegrid()

◆ parseRuntimeOptions()

◆ plotParticles()

◆ postCheckpointSetup()

◆ postInitialize()

◆ postPlot()

◆ postRegrid()

◆ preRegrid()

◆ printStepReport()

◆ registerOperators()

◆ registerRealms()

◆ regrid()

◆ setDiffusion()

◆ setupSolvers()

◆ synchronizeSolverTimes()

◆ writePlotData()

Member Data Documentation

◆ m_className

◆ m_constantVelocity

◆ m_velocity

◆ m_verifyConservation