Field solver wrapper that implements the full binned self-field algorithm. More...

#include <BinnedFieldSolver.h>

Inheritance diagram for BinnedFieldSolver< T, Dim >:

Collaboration diagram for BinnedFieldSolver< T, Dim >:

Classes
struct	BinKinematics

struct	BinStatsRow
	Row entry for the level-3 bin statistics table. More...

Public Types
enum class	ScatterAttribute { ChargeQ }
	Which particle attribute to scatter from to build the mesh charge density `rho`. More...

enum class	ImageScatterMode { PrimaryAndImage , PrimaryOnly , ImageOnly }
	Controls which charges are scattered during rho preparation. More...

enum class	GatherAttribute { ElectricFieldE }
	Which particle attribute to gather the accumulated electric field into. More...

using	PartBunch_t = PartBunch< T, Dim >

using	ParticleCtr_t = typename PartBunch_t::ParticleContainer_t

using	AdaptBins_t = typename PartBunch_t::AdaptBins_t

using	BCHandler_t = BCHandler< Dim >

using	bin_index_type = typename AdaptBins_t::bin_index_type

using	size_type = typename AdaptBins_t::size_type

using	particle_position_type = typename PartBunch_t::Base::particle_position_type

Public Member Functions
	BinnedFieldSolver (std::string solver, Field_t< Dim > rho, VField_t< T, Dim > E, Field_t< Dim > *phi, std::shared_ptr< BCHandler_t > bcHandler, int tablePrintFrequency, bool adaptiveBinning)
	Construct a binned/legacy-compatible solver.

void	computeSelfFields (PartBunch_t &bunch)
	Compute space-charge self-fields for the given particle bunch.

void	setScatterAttribute (const ScatterAttribute attr)
	Set particle scatter attribute (extensible; default is `ChargeQ`).

void	setGatherAttribute (const GatherAttribute attr)
	Set particle gather attribute (extensible; default is `ElectricFieldE`).

void	setImageChargeConfiguration (bool enabled, double zPlane)
	Configure optional image-charge scatter pass.

bool	isImageChargeEnabled () const

double	getImageChargePlaneZ () const

void	setShiftedGreensConfiguration (bool enabled, double zPlane)
	Configure the shifted Green's function Dirichlet correction (alternative to image charges). Mutually exclusive with `setImageChargeConfiguration(true, ...)`. Requires the OPEN field solver; the solver-type check happens at runtime in `FieldSolver::runShiftedOpenSolver` when the correction pass fires.

bool	isShiftedGreensEnabled () const

double	getShiftedGreensPlaneZ () const

void	setZerofaceMaxSteps (int maxSteps)
	Set the maximum number of timesteps for which image charges are active (0 = unlimited).

int	getZerofaceMaxSteps () const

bool	isImageChargeActiveForStep (size_t step) const
	Check whether the explicit image-charge pass should run for a given timestep.

bool	isShiftedGreensActiveForStep (size_t step) const
	Check whether the shifted Green's function correction should run for a given timestep. Reuses the same step budget (`zerofaceMaxSteps_m`) as the image-charge path.

void	setZeroFacePlaneDumpFrequency (int frequency)
	Configure dump frequency for dirichlet-plane diagnostics (`0` disables dumps).

int	getZeroFacePlaneDumpFrequency () const

BinKinematics	computeGammaBinGlobal (PartBunch_t &bunch, std::shared_ptr< AdaptBins_t > bins, const bin_index_type binIndex, const size_type nPartGlobal) const
	Compute per-bin global mean momentum and gamma.

void	prepareRhoForBin (PartBunch_t &bunch, std::shared_ptr< AdaptBins_t > bins, const bin_index_type binIndex, const size_type nPartGlobal, const double gammaBin, ImageScatterMode mode=ImageScatterMode::PrimaryAndImage)
	Build mesh `rho` for a specific merged bin and apply all corrections.

void	accumulateFieldToTemp (const double gammaBin, const Vector_t< double, Dim > &pmean, std::shared_ptr< VField_t< T, Dim > > EtmpSP, std::shared_ptr< VField_t< T, Dim > > BtmpSP, double bFieldSign=1.0, int flipAxis=-1)
	Accumulate Lorentz-transformed electric/magnetic fields into temporaries.

void	dumpScalField (std::string what)

void	dumpScalField (std::string what)

void	dumpVectField (std::string what)

void	dumpVectField (std::string what)

Field_t< Dim > *	getRho ()

void	setRho (Field_t< Dim > *rho)

VField_t< T, Dim > *	getE () const

void	setE (VField_t< T, Dim > *E)

Field< T, Dim > *	getPhi () const

void	setPhi (Field< T, Dim > *phi)

std::shared_ptr< BCHandler_t >	getBCHandler () const

void	setBCHandler (std::shared_ptr< BCHandler_t > bcHandler)

T	getCouplingConstant () const
	Get the solver's coupling constant.

double	getCouplingConstant () const

void	initOpenSolver ()

void	initOpenSolver ()

void	initSolver () override

void	initSolver ()

void	setPotentialBCs ()
	Set boundary conditions for the electrostatic potential field.

void	setPotentialBCs ()

bool	hasValidBCHandler () const

void	runSolver () override

void	runSolver (bool force_skip_field_dump)
	Execute the field solver for the current simulation state.

void	runSolver (bool force_skip_field_dump)

void	resetCallCounter ()
	Reset the solver call counter to zero.

size_t	getCallCounter ()

void	runShiftedOpenSolver (const ippl::Vector< double, Dim > &shift)
	Run an Open-solver solve with a shifted free-space Green's function.

void	runShiftedOpenSolver (const ippl::Vector< double, 3 > &shift)

template<typename Solver >
void	initSolverWithParams (const ippl::ParameterList &sp)

void	initSolverWithParams (const ippl::ParameterList &sp)

void	initNullSolver ()

void	initNullSolver ()

void	initNullSolver ()

void	initFFTSolver ()

void	initFFTSolver ()

void	initCGSolver ()

void	initCGSolver ()

void	initP3MSolver ()

Static Public Member Functions
static void	setScalarField (Field_t< Dim > &field, double value)
	Set all scalar field entries, including ghosts, without IPPL expression templates.

static void	scaleAndShiftScalarField (Field_t< Dim > &field, double scale, double shift)
	Apply `field` = field * scale + shift on owned cells without expression templates.

static void	setVectorField (VField_t< T, Dim > &field, const Vector_t< T, Dim > &value)
	Set all vector field entries, including ghosts, without IPPL expression templates.

Private Member Functions
void	printBinStatsTable (const std::string &binningCmdName, const std::vector< BinStatsRow > &rows)
	Print the bin statistics table at level 3.

void	dumpDirichletPlaneDiagnosticsIfRequested (PartBunch_t &bunch, const std::string &solveTag)
	Dump and report potential values interpolated on the image-charge plane.

void	computeBinnedSelfFields (PartBunch_t &bunch)
	Compute self-fields using the binned algorithm.

void	computeLegacySelfFields (PartBunch_t &bunch)
	Compute self-fields using the legacy monolithic algorithm.

void	rebinAndPrepare (PartBunch_t &bunch, std::shared_ptr< AdaptBins_t > bins)
	Build and prepare adaptive bins for the current step.

void	buildFlippedZSlab (const VField_t< T, Dim > &src)
	Populate `flippedZSlab_m` with the z-axis globally-flipped version of `src`.

void	gatherFromTempToParticles (PartBunch_t &bunch, std::shared_ptr< VField_t< T, Dim > > EtmpSP, std::shared_ptr< VField_t< T, Dim > > BtmpSP)
	Gather the accumulated lab-frame fields from temporaries back to particles.

Private Attributes
ScatterAttribute	scatterAttribute_m

GatherAttribute	gatherAttribute_m

int	tablePrintFrequency_m = 0

bool	adaptiveBinning_m = true

int	zeroFacePlaneDumpFrequency_m = 0

int	zerofaceMaxSteps_m = 0

ImageChargeScatterController< T, Dim >	imageScatterController_m

bool	warnedPlaneDumpParallelUnsupported_m = false

bool	shiftedGreensEnabled_m = false

double	shiftedGreensPlaneZ_m = 0.0

std::shared_ptr< VField_t< T, Dim > >	flippedZSlabField_m

Field_t< Dim > *	rho_m

VField_t< T, Dim > *	E_m

Field_t< Dim > *	phi_m

std::shared_ptr< BCHandler_t >	bcHandler_m

size_t	call_counter_m
	Counts number of times the solver has been called.

Detailed Description

template<typename T, unsigned Dim>
class BinnedFieldSolver< T, Dim >

Field solver wrapper that implements the full binned self-field algorithm.

OPAL particle bunch: field container, solver, load balancer, and one or more beams.

Template Parameters

T	Particle numeric type (typically `double`).
Dim	Spatial dimensionality (currently only `Dim == 3` is supported).

Design overview:

The solver owns no particle data; it borrows a PartBunch by reference.
Runtime selection:
- If adaptive bins are available (bunch.hasBinning() / bunch.getBins()), the per-bin algorithm is executed.
- Otherwise, the legacy monolithic scatter/solve/gather path is used.
The solver currently supports only ChargeQ -> rho scattering and ElectricFieldE gathering, but gathers both E and B fields.
Physics details:
- See https://github.com/aliemen/HS24-masters-thesis for details.
- After bins are calculated, it solves electrostatics per bin in a quasi-static approximation.
- Fields per bin are then transformed to the lab frame and accumulated into the temporary fields, this also produces the magnetic field contributions.
- Finally, the accumulated fields are gathered back to the particles.
- This procedure approximates full Maxwell's equations for the self-fields.
- Without a bins object, it falls back to the legacy electrostatic approximation.

Template Parameters

T	Floating-point type for positions/fields (typically double).
Dim	Spatial dimension (3 for OPALX).

Definition at line 42 of file BinnedFieldSolver.h.

Class Documentation

◆ BinnedFieldSolver::BinKinematics

struct BinnedFieldSolver::BinKinematics

template<typename T, unsigned Dim>
struct BinnedFieldSolver< T, Dim >::BinKinematics

Definition at line 152 of file BinnedFieldSolver.h.

Collaboration diagram for BinnedFieldSolver< T, Dim >::BinKinematics:

Class Members
double	gammaBin = 1.0
Vector_t< double, Dim >	pmean = Vector_t<double, Dim>(0.0)

◆ BinnedFieldSolver::BinStatsRow

struct BinnedFieldSolver::BinStatsRow

template<typename T, unsigned Dim>
struct BinnedFieldSolver< T, Dim >::BinStatsRow

Row entry for the level-3 bin statistics table.

Definition at line 182 of file BinnedFieldSolver.h.

Collaboration diagram for BinnedFieldSolver< T, Dim >::BinStatsRow:

Class Members
long long	binNumber	Merged bin index (or `-1` for legacy mode).
double	gammaBin	Global average gamma for the (merged) bin.
unsigned long long	nParticles	Number of particles in the (merged) bin.

Member Typedef Documentation

◆ AdaptBins_t

template<typename T , unsigned Dim>

using BinnedFieldSolver< T, Dim >::AdaptBins_t = typename PartBunch_t::AdaptBins_t

Definition at line 48 of file BinnedFieldSolver.h.

◆ BCHandler_t

template<typename T , unsigned Dim>

using BinnedFieldSolver< T, Dim >::BCHandler_t = BCHandler<Dim>

Definition at line 49 of file BinnedFieldSolver.h.

◆ bin_index_type

template<typename T , unsigned Dim>

using BinnedFieldSolver< T, Dim >::bin_index_type = typename AdaptBins_t::bin_index_type

Definition at line 50 of file BinnedFieldSolver.h.

◆ PartBunch_t

template<typename T , unsigned Dim>

using BinnedFieldSolver< T, Dim >::PartBunch_t = PartBunch<T, Dim>

Definition at line 46 of file BinnedFieldSolver.h.

◆ particle_position_type

template<typename T , unsigned Dim>

using BinnedFieldSolver< T, Dim >::particle_position_type = typename PartBunch_t::Base::particle_position_type

Definition at line 53 of file BinnedFieldSolver.h.

◆ ParticleCtr_t

template<typename T , unsigned Dim>

using BinnedFieldSolver< T, Dim >::ParticleCtr_t = typename PartBunch_t::ParticleContainer_t

Definition at line 47 of file BinnedFieldSolver.h.

◆ size_type

template<typename T , unsigned Dim>

using BinnedFieldSolver< T, Dim >::size_type = typename AdaptBins_t::size_type

Definition at line 51 of file BinnedFieldSolver.h.

Member Enumeration Documentation

◆ GatherAttribute

template<typename T , unsigned Dim>

enum class BinnedFieldSolver::GatherAttribute

strong

Which particle attribute to gather the accumulated electric field into.

Currently only ElectricFieldE is implemented.

Enumerator
ElectricFieldE

Definition at line 76 of file BinnedFieldSolver.h.

◆ ImageScatterMode

template<typename T , unsigned Dim>

enum class BinnedFieldSolver::ImageScatterMode

strong

Controls which charges are scattered during rho preparation.

PrimaryAndImage scatters both (legacy combined behavior). PrimaryOnly scatters only the real bunch charges. ImageOnly scatters only the mirrored image charges.

Enumerator
PrimaryAndImage
PrimaryOnly
ImageOnly

Definition at line 69 of file BinnedFieldSolver.h.

◆ ScatterAttribute

template<typename T , unsigned Dim>

enum class BinnedFieldSolver::ScatterAttribute

strong

Which particle attribute to scatter from to build the mesh charge density rho.

Currently only ChargeQ is implemented.

Enumerator
ChargeQ

Definition at line 60 of file BinnedFieldSolver.h.

Constructor & Destructor Documentation

◆ BinnedFieldSolver()

template<typename T , unsigned Dim>

BinnedFieldSolver< T, Dim >::BinnedFieldSolver	(	std::string	solver,
		Field_t< Dim > *	rho,
		VField_t< T, Dim > *	E,
		Field_t< Dim > *	phi,
		std::shared_ptr< BCHandler_t >	bcHandler,
		int	tablePrintFrequency,
		bool	adaptiveBinning
	)

Construct a binned/legacy-compatible solver.

Parameters

solver	Concrete solver name (e.g. `FFT`, `OPEN`, `CG`, `NONE`).
rho	Pointer to the mesh charge-density field storage.
E	Pointer to the mesh electric-field storage (solver output).
phi	Pointer to the potential-field storage (solver internal use).
bcHandler	Shared pointer to the boundary-condition handler.
tablePrintFrequency	Global timestep frequency of printing the bin stats table to console in binned mode. If `0`, printing is disabled.
adaptiveBinning	If true, merge uniform bins adaptively after rebinning. If false, keep the uniform MAXBINS histogram.

Member Function Documentation

◆ accumulateFieldToTemp()

template<typename T , unsigned Dim>

void BinnedFieldSolver< T, Dim >::accumulateFieldToTemp	(	const double	gammaBin,
		const Vector_t< double, Dim > &	pmean,
		std::shared_ptr< VField_t< T, Dim > >	EtmpSP,
		std::shared_ptr< VField_t< T, Dim > >	BtmpSP,
		double	bFieldSign = `1.0`,
		int	flipAxis = `-1`
	)

Accumulate Lorentz-transformed electric/magnetic fields into temporaries.

The solver output field is interpreted as the bin-frame electric field ‘E’ withB' = 0, and transformed to the lab frame with: -E_lab = gammaBin * E' + (gammaBin - 1) * (E' · w) * w -B_lab = (gammaBin / c^2) * (v x E') wherev = c * pmean / gammaBinandw = v / |v|(orw = 0if|v| = 0`).

When flipAxis is a valid axis index (0..Dim-1), the solver output is read at an axis-flipped source index N-1-k (in that axis only) and the transverse E components are negated before the Lorentz transform, yielding the image-charge contribution produced by a shifted-Green's-function solve:

E_d -> -E_d for d != flipAxis
E_d -> +E_d for d == flipAxis (the component parallel to the flip). This is derived from phi_image(x) = -phi_shifted(R(x)) and E = -grad(phi). The zero-copy read from the flipped source index is the reason this is baked into accumulateFieldToTemp instead of an out-of-place kernel.

Currently single-rank only when flipAxis >= 0 (an axis-flip across MPI ranks would need extra communication). The caller is expected to guard against multi-rank use upstream.

Parameters

gammaBin	Global average gamma for the merged bin.
pmean	Global average normalized momentum for the merged bin.
EtmpSP	Temporary electric field buffer for accumulation.
BtmpSP	Temporary magnetic field buffer for accumulation.
bFieldSign	+1 for forward-moving charges, -1 for image charges.
flipAxis	Axis in which to flip the read index (use -1 for no flip).

◆ buildFlippedZSlab()

template<typename T , unsigned Dim>

void BinnedFieldSolver< T, Dim >::buildFlippedZSlab ( const VField_t< T, Dim > & src )

private

Populate flippedZSlab_m with the z-axis globally-flipped version of src.

Under PARFFTZ=true the global flip k -> N_z_global-1-k generally crosses MPI ranks. This helper does one pairwise-exchange pass over ippl::Comm: each rank packs the z-slabs of src that peers need, posts MPI_Isend/MPI_Irecv, and unpacks the received slabs into the correct local destination indices of flippedZSlab_m. After the call the lambda in accumulateFieldToTemp reads flippedZSlab_m(i, j, k) directly without any cross-rank access.

Parameters

src	Source vector field (typically `*(this->getE())` after the shifted-GF solve). Only the z axis is flipped; x and y stay local to the rank.

◆ computeBinnedSelfFields()

template<typename T , unsigned Dim>

void BinnedFieldSolver< T, Dim >::computeBinnedSelfFields ( PartBunch_t & bunch )

private

Compute self-fields using the binned algorithm.

Requires that the bunch has a valid bin structure and a temporary electric field buffer (bunch.getTempEField()).

Parameters

bunch Particle bunch for which to compute self-fields.

◆ computeGammaBinGlobal()

template<typename T , unsigned Dim>

BinKinematics BinnedFieldSolver< T, Dim >::computeGammaBinGlobal	(	PartBunch_t &	bunch,
		std::shared_ptr< AdaptBins_t >	bins,
		const bin_index_type	binIndex,
		const size_type	nPartGlobal
	)		const

Compute per-bin global mean momentum and gamma.

The function computes the global mean momentum vector pmean across all particles in the merged bin and derives: gammaBin = mean(sqrt(1 + dot(p_i, p_i))).

Parameters

bunch	Bunch providing particle data.
bins	Bins providing the merged-bin iteration policy and indexing.
binIndex	Bin index in the merged-bin space.
nPartGlobal	Global particle count for this merged bin.

Returns: Per-bin kinematics bundle (pmean, gammaBin).

◆ computeLegacySelfFields()

template<typename T , unsigned Dim>

void BinnedFieldSolver< T, Dim >::computeLegacySelfFields ( PartBunch_t & bunch )

private

Compute self-fields using the legacy monolithic algorithm.

This is a direct adaptation of the legacy implementation: scatter (all particles) -> solve once -> gather electric field directly to particles.

Parameters

bunch Particle bunch for which to compute self-fields.

◆ computeSelfFields()

template<typename T , unsigned Dim>

void BinnedFieldSolver< T, Dim >::computeSelfFields ( PartBunch_t & bunch )

Compute space-charge self-fields for the given particle bunch.

If the bunch provides adaptive binning (bunch.getBins()), the solver executes the per-bin algorithm: scatter rho corrections -> solve -> Lorentz scaling -> accumulate -> gather. Otherwise, it executes the legacy monolithic algorithm: scatter all particles -> solve once -> gather directly.

Parameters

bunch Particle bunch to update. Ownership remains with the caller.

Exceptions

OpalException If required internal data (particle container / temp E field) is missing, or if unsupported scatter/gather modes are selected.

Referenced by PartBunch< T, Dim >::computeSelfFields().

◆ dumpDirichletPlaneDiagnosticsIfRequested()

template<typename T , unsigned Dim>

void BinnedFieldSolver< T, Dim >::dumpDirichletPlaneDiagnosticsIfRequested	(	PartBunch_t &	bunch,
		const std::string &	solveTag
	)

private

Dump and report potential values interpolated on the image-charge plane.

If diagnostics are disabled or conditions are not met for the current step, this function returns without side effects.

Parameters

bunch	Particle bunch context for time/step and DataSink access.
solveTag	Label used in output file naming (`legacy`, `binned`, ...).

◆ dumpScalField() [1/2]

void FieldSolver< double, 3 >::dumpScalField ( std::string what )

inherited

Definition at line 148 of file FieldSolver.cpp.

References OpalData::getInputBasename(), OpalData::getInstance(), and Util::toUpper().

Here is the call graph for this function:

◆ dumpScalField() [2/2]

template<typename T , unsigned Dim>

void FieldSolver< T, Dim >::dumpScalField ( std::string what )

inherited

◆ dumpVectField() [1/2]

void FieldSolver< double, 3 >::dumpVectField ( std::string what )

inherited

Definition at line 55 of file FieldSolver.cpp.

References OpalData::getInputBasename(), OpalData::getInstance(), and Util::toUpper().

Here is the call graph for this function:

◆ dumpVectField() [2/2]

template<typename T , unsigned Dim>

void FieldSolver< T, Dim >::dumpVectField ( std::string what )

inherited

◆ gatherFromTempToParticles()

template<typename T , unsigned Dim>

void BinnedFieldSolver< T, Dim >::gatherFromTempToParticles	(	PartBunch_t &	bunch,
		std::shared_ptr< VField_t< T, Dim > >	EtmpSP,
		std::shared_ptr< VField_t< T, Dim > >	BtmpSP
	)

private

Gather the accumulated lab-frame fields from temporaries back to particles.

Parameters

bunch	Particle bunch to gather into.
EtmpSP	Temporary electric field buffer holding the accumulated lab-frame field.
BtmpSP	Temporary magnetic field buffer holding the accumulated lab-frame field.

◆ getBCHandler()

template<typename T , unsigned Dim>

std::shared_ptr< BCHandler_t > FieldSolver< T, Dim >::getBCHandler ( ) const

inlineinherited

Definition at line 50 of file FieldSolver.hpp.

References FieldSolver< T, Dim >::bcHandler_m.

◆ getCallCounter()

template<typename T , unsigned Dim>

size_t FieldSolver< T, Dim >::getCallCounter ( )

inlineinherited

Definition at line 103 of file FieldSolver.hpp.

References FieldSolver< T, Dim >::call_counter_m.

Referenced by ParallelTracker::execute().

◆ getCouplingConstant() [1/2]

double FieldSolver< double, 3 >::getCouplingConstant ( ) const

inherited

Todo:: Verify this before activating a new solver!

Definition at line 483 of file FieldSolver.cpp.

References Physics::epsilon_0, and Physics::pi.

◆ getCouplingConstant() [2/2]

template<typename T , unsigned Dim>

T FieldSolver< T, Dim >::getCouplingConstant ( ) const

inherited

Get the solver's coupling constant.

Returns the scalar coupling constant used by the field solver to scale interactions between particles and the field. This value is applied during ParBunch::computeSpaceCharge. Its physical meaning and units potentially depend on the specific solver type used.

Returns: The coupling constant of type T (usually double).

◆ getE()

template<typename T , unsigned Dim>

VField_t< T, Dim > * FieldSolver< T, Dim >::getE ( ) const

inlineinherited

Definition at line 44 of file FieldSolver.hpp.

References FieldSolver< T, Dim >::E_m.

◆ getImageChargePlaneZ()

template<typename T , unsigned Dim>

double BinnedFieldSolver< T, Dim >::getImageChargePlaneZ ( ) const

inline

Definition at line 126 of file BinnedFieldSolver.h.

References BinnedFieldSolver< T, Dim >::imageScatterController_m.

Referenced by PartBunch< T, Dim >::computeBoundsForFieldSolve().

◆ getPhi()

template<typename T , unsigned Dim>

Field< T, Dim > * FieldSolver< T, Dim >::getPhi ( ) const

inlineinherited

Definition at line 47 of file FieldSolver.hpp.

References FieldSolver< T, Dim >::phi_m.

◆ getRho()

template<typename T , unsigned Dim>

Field_t< Dim > * FieldSolver< T, Dim >::getRho ( )

inlineinherited

Definition at line 41 of file FieldSolver.hpp.

References FieldSolver< T, Dim >::rho_m.

◆ getShiftedGreensPlaneZ()

template<typename T , unsigned Dim>

double BinnedFieldSolver< T, Dim >::getShiftedGreensPlaneZ ( ) const

inline

Definition at line 134 of file BinnedFieldSolver.h.

References BinnedFieldSolver< T, Dim >::shiftedGreensPlaneZ_m.

◆ getZerofaceMaxSteps()

template<typename T , unsigned Dim>

int BinnedFieldSolver< T, Dim >::getZerofaceMaxSteps ( ) const

inline

Definition at line 139 of file BinnedFieldSolver.h.

References BinnedFieldSolver< T, Dim >::zerofaceMaxSteps_m.

◆ getZeroFacePlaneDumpFrequency()

template<typename T , unsigned Dim>

int BinnedFieldSolver< T, Dim >::getZeroFacePlaneDumpFrequency ( ) const

inline

Definition at line 150 of file BinnedFieldSolver.h.

References BinnedFieldSolver< T, Dim >::zeroFacePlaneDumpFrequency_m.

◆ hasValidBCHandler()

template<typename T , unsigned Dim>

bool FieldSolver< T, Dim >::hasValidBCHandler ( ) const

inlineinherited

Definition at line 84 of file FieldSolver.hpp.

References FieldSolver< T, Dim >::bcHandler_m.

◆ initCGSolver() [1/2]

void FieldSolver< double, 3 >::initCGSolver ( )

inherited

Todo:: should probably at some point be passed from the input file

Definition at line 308 of file FieldSolver.cpp.

◆ initCGSolver() [2/2]

template<typename T , unsigned Dim>

void FieldSolver< T, Dim >::initCGSolver ( )

inlineinherited

Definition at line 153 of file FieldSolver.hpp.

◆ initFFTSolver() [1/2]

void FieldSolver< double, 3 >::initFFTSolver ( )

inherited

Todo:: don't print phi_m to file if FFT and GRAD is selected!

Definition at line 286 of file FieldSolver.cpp.

References Dim.

◆ initFFTSolver() [2/2]

template<typename T , unsigned Dim>

void FieldSolver< T, Dim >::initFFTSolver ( )

inherited

◆ initNullSolver() [1/3]

void FieldSolver< double, 3 >::initNullSolver ( )

inherited

Definition at line 318 of file FieldSolver.cpp.

References Dim.

◆ initNullSolver() [2/3]

template<typename T , unsigned Dim>

void FieldSolver< T, Dim >::initNullSolver ( )

inherited

◆ initNullSolver() [3/3]

void FieldSolver< double, 3 >::initNullSolver ( )

inherited

◆ initOpenSolver() [1/2]

void FieldSolver< double, 3 >::initOpenSolver ( )

inherited

Definition at line 272 of file FieldSolver.cpp.

◆ initOpenSolver() [2/2]

template<typename T , unsigned Dim>

void FieldSolver< T, Dim >::initOpenSolver ( )

inherited

◆ initP3MSolver()

template<typename T , unsigned Dim>

void FieldSolver< T, Dim >::initP3MSolver ( )

inlineinherited

Definition at line 155 of file FieldSolver.hpp.

◆ initSolver() [1/2]

void FieldSolver< double, 3 >::initSolver ( )

inherited

Definition at line 330 of file FieldSolver.cpp.

◆ initSolver() [2/2]

template<typename T , unsigned Dim>

void FieldSolver< T, Dim >::initSolver ( )

overrideinherited

◆ initSolverWithParams() [1/2]

void FieldSolver< double, 3 >::initSolverWithParams ( const ippl::ParameterList & sp )

inherited

Todo:: for now, don't use the CG solver!

Definition at line 17 of file FieldSolver.cpp.

◆ initSolverWithParams() [2/2]

template<typename T , unsigned Dim>

template<typename Solver >

void FieldSolver< T, Dim >::initSolverWithParams ( const ippl::ParameterList & sp )

inherited

◆ isImageChargeActiveForStep()

template<typename T , unsigned Dim>

bool BinnedFieldSolver< T, Dim >::isImageChargeActiveForStep ( size_t step ) const

Check whether the explicit image-charge pass should run for a given timestep.

Referenced by PartBunch< T, Dim >::bunchUpdate(), and PartBunch< T, Dim >::computeBoundsForFieldSolve().

◆ isImageChargeEnabled()

template<typename T , unsigned Dim>

bool BinnedFieldSolver< T, Dim >::isImageChargeEnabled ( ) const

inline

Definition at line 125 of file BinnedFieldSolver.h.

References BinnedFieldSolver< T, Dim >::imageScatterController_m.

Referenced by ParallelTracker::markBackwardParticlesAtSourcePlane().

◆ isShiftedGreensActiveForStep()

template<typename T , unsigned Dim>

bool BinnedFieldSolver< T, Dim >::isShiftedGreensActiveForStep ( size_t step ) const

Check whether the shifted Green's function correction should run for a given timestep. Reuses the same step budget (zerofaceMaxSteps_m) as the image-charge path.

◆ isShiftedGreensEnabled()

template<typename T , unsigned Dim>

bool BinnedFieldSolver< T, Dim >::isShiftedGreensEnabled ( ) const

inline

Definition at line 133 of file BinnedFieldSolver.h.

References BinnedFieldSolver< T, Dim >::shiftedGreensEnabled_m.

◆ prepareRhoForBin()

template<typename T , unsigned Dim>

void BinnedFieldSolver< T, Dim >::prepareRhoForBin	(	PartBunch_t &	bunch,
		std::shared_ptr< AdaptBins_t >	bins,
		const bin_index_type	binIndex,
		const size_type	nPartGlobal,
		const double	gammaBin,
		ImageScatterMode	mode = `ImageScatterMode::PrimaryAndImage`
	)

Build mesh rho for a specific merged bin and apply all corrections.

Steps mirror the legacy ordering from the existing OPAL-X code paths and include:

dt scaling for charge scattering,
mesh normalization and background subtraction (non-OPEN),
Lorentz rest-frame scaling: rho /= gammaBin,
scaling by the solver coupling constant.

Parameters

bunch	Bunch providing geometry and charge data.
bins	Adaptive bins providing bin iteration and hash indexing.
binIndex	Merged bin index.
nPartGlobal	Global number of particles in that merged bin.
gammaBin	Global average gamma for that merged bin.

◆ printBinStatsTable()

template<typename T , unsigned Dim>

void BinnedFieldSolver< T, Dim >::printBinStatsTable	(	const std::string &	binningCmdName,
		const std::vector< BinStatsRow > &	rows
	)

private

Print the bin statistics table at level 3.

The output includes columns for bin index, particle count, and gammaBin. In binned mode, rows correspond to each merged bin. In legacy mode, a single row with binNumber = -1 is printed.

Parameters

tableName	Logical table name (used in the header).
nBinsOrZero	Number of bins (for header metadata). Use `0` for legacy mode.
rows	Table rows to print.

◆ rebinAndPrepare()

template<typename T , unsigned Dim>

void BinnedFieldSolver< T, Dim >::rebinAndPrepare	(	PartBunch_t &	bunch,
		std::shared_ptr< AdaptBins_t >	bins
	)

private

Build and prepare adaptive bins for the current step.

This performs a full rebin to the maximum bin count, sorts the particle container by bin, generates the adaptive histogram (merging), and restores bin configuration.

Parameters

bunch	Bunch whose bins are updated.
bins	Adaptive bin structure owned/managed by the bunch.

◆ resetCallCounter()

template<typename T , unsigned Dim>

void FieldSolver< T, Dim >::resetCallCounter ( )

inlineinherited

Reset the solver call counter to zero.

Sets the internal call counter (call_counter_m) back to 0 so that subsequent calls will be counted from a clean state.

Note: This function is necessary to exclude potential solver warm-up calls from being counted towards output or logging that depends on the number of solver executions.

Definition at line 101 of file FieldSolver.hpp.

References FieldSolver< T, Dim >::call_counter_m.

◆ runShiftedOpenSolver() [1/2]

void FieldSolver< double, 3 >::runShiftedOpenSolver ( const ippl::Vector< double, 3 > & shift )

inherited

Definition at line 446 of file FieldSolver.cpp.

◆ runShiftedOpenSolver() [2/2]

template<typename T , unsigned Dim>

void FieldSolver< T, Dim >::runShiftedOpenSolver ( const ippl::Vector< double, Dim > & shift )

inherited

Run an Open-solver solve with a shifted free-space Green's function.

Installs a translated Green's kernel \(G(r) = -1/(4\pi|r - \texttt{shift}|)\) on the underlying IPPL FFTOpenPoissonSolver via shiftedGreensFunction(shift), runs solve(), then restores the standard Green's function (greensFunction()) so subsequent solves in later bins are not affected.

The manual restore guards against two adjacent bins whose stretched mesh spacings happen to coincide: the mesh-change detector inside the IPPL solve() would then not recompute the kernel and the next primary solve would silently reuse the shifted one. With the current binning algorithm this collision is not supposed to happen, so the extra FFT per shifted pass is defensive and can be removed once the invariant is guaranteed by the binner.

Parameters

shift Per-axis translation of the Green's function in physical units.

Exceptions

OpalException if the configured solver is not "OPEN".

◆ runSolver() [1/3]

template<typename T , unsigned Dim>

void FieldSolver< T, Dim >::runSolver ( )

inlineoverrideinherited

Definition at line 86 of file FieldSolver.hpp.

References FieldSolver< T, Dim >::runSolver().

Referenced by FieldSolver< T, Dim >::runSolver().

Here is the call graph for this function:

◆ runSolver() [2/3]

void FieldSolver< double, 3 >::runSolver ( bool force_skip_field_dump )

inherited

Definition at line 362 of file FieldSolver.cpp.

References Dim.

◆ runSolver() [3/3]

template<typename T , unsigned Dim>

void FieldSolver< T, Dim >::runSolver ( bool force_skip_field_dump )

inherited

Execute the field solver for the current simulation state.

Performs a single solve cycle using the solver's current configuration, boundary conditions and particle/mesh data. The solver updates the internal field representations.

Parameters

force_skip_field_dump If true, suppress any field-dump output that would otherwise be produced by this call. If false, field output behavior follows the configured/normal schedule.

Note: This second implementation is necessary since the pure runSolver() routine is defined in the base class as not taking any arguments.

◆ scaleAndShiftScalarField()

template<typename T , unsigned Dim>

static void BinnedFieldSolver< T, Dim >::scaleAndShiftScalarField	(	Field_t< Dim > &	field,
		double	scale,
		double	shift
	)

static

Apply field = field * scale + shift on owned cells without expression templates.

◆ setBCHandler()

template<typename T , unsigned Dim>

void FieldSolver< T, Dim >::setBCHandler ( std::shared_ptr< BCHandler_t > bcHandler )

inlineinherited

Definition at line 51 of file FieldSolver.hpp.

References FieldSolver< T, Dim >::bcHandler_m, and FieldSolver< T, Dim >::setPotentialBCs().

Here is the call graph for this function:

◆ setE()

template<typename T , unsigned Dim>

void FieldSolver< T, Dim >::setE ( VField_t< T, Dim > * E )

inlineinherited

Definition at line 45 of file FieldSolver.hpp.

References FieldSolver< T, Dim >::E_m.

◆ setGatherAttribute()

template<typename T , unsigned Dim>

void BinnedFieldSolver< T, Dim >::setGatherAttribute ( const GatherAttribute attr )

Set particle gather attribute (extensible; default is ElectricFieldE).

Parameters

attr	Attribute to gather into.

◆ setImageChargeConfiguration()

template<typename T , unsigned Dim>

void BinnedFieldSolver< T, Dim >::setImageChargeConfiguration	(	bool	enabled,
		double	zPlane
	)

Configure optional image-charge scatter pass.

◆ setPhi()

template<typename T , unsigned Dim>

void FieldSolver< T, Dim >::setPhi ( Field< T, Dim > * phi )

inlineinherited

Definition at line 48 of file FieldSolver.hpp.

References FieldSolver< T, Dim >::phi_m.

◆ setPotentialBCs() [1/2]

void FieldSolver< double, 3 >::setPotentialBCs ( )

inherited

Definition at line 509 of file FieldSolver.cpp.

References Dim.

◆ setPotentialBCs() [2/2]

template<typename T , unsigned Dim>

void FieldSolver< T, Dim >::setPotentialBCs ( )

inherited

Set boundary conditions for the electrostatic potential field.

Converts the boundary-condition specification provided by the BC handler into the IPPL boundary-condition format for Field_t<Dim> and applies the resulting conditions to the internal potential field (phi_m) by calling its setFieldBC method.

Exceptions

OpalException if the BC handler is not set or invalid.

Referenced by FieldSolver< T, Dim >::FieldSolver(), and FieldSolver< T, Dim >::setBCHandler().

◆ setRho()

template<typename T , unsigned Dim>

void FieldSolver< T, Dim >::setRho ( Field_t< Dim > * rho )

inlineinherited

Definition at line 42 of file FieldSolver.hpp.

References FieldSolver< T, Dim >::rho_m.

◆ setScalarField()

template<typename T , unsigned Dim>

static void BinnedFieldSolver< T, Dim >::setScalarField	(	Field_t< Dim > &	field,
		double	value
	)

static

Set all scalar field entries, including ghosts, without IPPL expression templates.

◆ setScatterAttribute()

template<typename T , unsigned Dim>

void BinnedFieldSolver< T, Dim >::setScatterAttribute ( const ScatterAttribute attr )

Set particle scatter attribute (extensible; default is ChargeQ).

Parameters

attr	Attribute to scatter from.

◆ setShiftedGreensConfiguration()

template<typename T , unsigned Dim>

void BinnedFieldSolver< T, Dim >::setShiftedGreensConfiguration	(	bool	enabled,
		double	zPlane
	)

Configure the shifted Green's function Dirichlet correction (alternative to image charges). Mutually exclusive with setImageChargeConfiguration(true, ...). Requires the OPEN field solver; the solver-type check happens at runtime in FieldSolver::runShiftedOpenSolver when the correction pass fires.

◆ setVectorField()

template<typename T , unsigned Dim>

static void BinnedFieldSolver< T, Dim >::setVectorField	(	VField_t< T, Dim > &	field,
		const Vector_t< T, Dim > &	value
	)

static

Set all vector field entries, including ghosts, without IPPL expression templates.

◆ setZerofaceMaxSteps()

template<typename T , unsigned Dim>

void BinnedFieldSolver< T, Dim >::setZerofaceMaxSteps ( int maxSteps )

Set the maximum number of timesteps for which image charges are active (0 = unlimited).

◆ setZeroFacePlaneDumpFrequency()

template<typename T , unsigned Dim>

void BinnedFieldSolver< T, Dim >::setZeroFacePlaneDumpFrequency ( int frequency )

Configure dump frequency for dirichlet-plane diagnostics (0 disables dumps).

Member Data Documentation

◆ adaptiveBinning_m

template<typename T , unsigned Dim>

bool BinnedFieldSolver< T, Dim >::adaptiveBinning_m = true

private

Definition at line 161 of file BinnedFieldSolver.h.

◆ bcHandler_m

template<typename T , unsigned Dim>

std::shared_ptr<BCHandler_t> FieldSolver< T, Dim >::bcHandler_m

privateinherited

Definition at line 18 of file FieldSolver.hpp.

Referenced by FieldSolver< T, Dim >::getBCHandler(), FieldSolver< T, Dim >::hasValidBCHandler(), and FieldSolver< T, Dim >::setBCHandler().

◆ call_counter_m

template<typename T , unsigned Dim>

size_t FieldSolver< T, Dim >::call_counter_m

privateinherited

Counts number of times the solver has been called.

Definition at line 21 of file FieldSolver.hpp.

Referenced by FieldSolver< T, Dim >::getCallCounter(), and FieldSolver< T, Dim >::resetCallCounter().

◆ E_m

template<typename T , unsigned Dim>

VField_t<T, Dim>* FieldSolver< T, Dim >::E_m

privateinherited

Definition at line 14 of file FieldSolver.hpp.

Referenced by FieldSolver< T, Dim >::getE(), and FieldSolver< T, Dim >::setE().

◆ flippedZSlabField_m

template<typename T , unsigned Dim>

std::shared_ptr<VField_t<T, Dim> > BinnedFieldSolver< T, Dim >::flippedZSlabField_m

private

Definition at line 177 of file BinnedFieldSolver.h.

◆ gatherAttribute_m

template<typename T , unsigned Dim>

GatherAttribute BinnedFieldSolver< T, Dim >::gatherAttribute_m

private

Definition at line 159 of file BinnedFieldSolver.h.

◆ imageScatterController_m

template<typename T , unsigned Dim>

ImageChargeScatterController<T, Dim> BinnedFieldSolver< T, Dim >::imageScatterController_m

private

Definition at line 164 of file BinnedFieldSolver.h.

Referenced by BinnedFieldSolver< T, Dim >::getImageChargePlaneZ(), and BinnedFieldSolver< T, Dim >::isImageChargeEnabled().

◆ phi_m

template<typename T , unsigned Dim>

Field_t<Dim>* FieldSolver< T, Dim >::phi_m

privateinherited

Definition at line 15 of file FieldSolver.hpp.

Referenced by FieldSolver< T, Dim >::getPhi(), and FieldSolver< T, Dim >::setPhi().

◆ rho_m

template<typename T , unsigned Dim>

Field_t<Dim>* FieldSolver< T, Dim >::rho_m

privateinherited

Definition at line 13 of file FieldSolver.hpp.

Referenced by FieldSolver< T, Dim >::getRho(), and FieldSolver< T, Dim >::setRho().

◆ scatterAttribute_m

template<typename T , unsigned Dim>

ScatterAttribute BinnedFieldSolver< T, Dim >::scatterAttribute_m

private

Definition at line 158 of file BinnedFieldSolver.h.

◆ shiftedGreensEnabled_m

template<typename T , unsigned Dim>

bool BinnedFieldSolver< T, Dim >::shiftedGreensEnabled_m = false

private

Definition at line 169 of file BinnedFieldSolver.h.

Referenced by BinnedFieldSolver< T, Dim >::isShiftedGreensEnabled().

◆ shiftedGreensPlaneZ_m

template<typename T , unsigned Dim>

double BinnedFieldSolver< T, Dim >::shiftedGreensPlaneZ_m = 0.0

private

Definition at line 170 of file BinnedFieldSolver.h.

Referenced by BinnedFieldSolver< T, Dim >::getShiftedGreensPlaneZ().

◆ tablePrintFrequency_m

template<typename T , unsigned Dim>

int BinnedFieldSolver< T, Dim >::tablePrintFrequency_m = 0

private

Definition at line 160 of file BinnedFieldSolver.h.

◆ warnedPlaneDumpParallelUnsupported_m

template<typename T , unsigned Dim>

bool BinnedFieldSolver< T, Dim >::warnedPlaneDumpParallelUnsupported_m = false

private

Definition at line 165 of file BinnedFieldSolver.h.

◆ zerofaceMaxSteps_m

template<typename T , unsigned Dim>

int BinnedFieldSolver< T, Dim >::zerofaceMaxSteps_m = 0

private

Definition at line 163 of file BinnedFieldSolver.h.

Referenced by BinnedFieldSolver< T, Dim >::getZerofaceMaxSteps().

◆ zeroFacePlaneDumpFrequency_m

template<typename T , unsigned Dim>

int BinnedFieldSolver< T, Dim >::zeroFacePlaneDumpFrequency_m = 0

private

Definition at line 162 of file BinnedFieldSolver.h.

Referenced by BinnedFieldSolver< T, Dim >::getZeroFacePlaneDumpFrequency().

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

BinnedFieldSolver.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Class Documentation

◆ BinnedFieldSolver::BinKinematics

◆ BinnedFieldSolver::BinStatsRow

Member Typedef Documentation

◆ AdaptBins_t

◆ BCHandler_t

◆ bin_index_type

◆ PartBunch_t

◆ particle_position_type

◆ ParticleCtr_t

◆ size_type

Member Enumeration Documentation

◆ GatherAttribute

◆ ImageScatterMode

◆ ScatterAttribute

Constructor & Destructor Documentation

◆ BinnedFieldSolver()

Member Function Documentation

◆ accumulateFieldToTemp()

◆ buildFlippedZSlab()

◆ computeBinnedSelfFields()

◆ computeGammaBinGlobal()

◆ computeLegacySelfFields()

◆ computeSelfFields()

◆ dumpDirichletPlaneDiagnosticsIfRequested()

◆ dumpScalField() [1/2]

◆ dumpScalField() [2/2]

◆ dumpVectField() [1/2]

◆ dumpVectField() [2/2]

◆ gatherFromTempToParticles()

◆ getBCHandler()

◆ getCallCounter()

◆ getCouplingConstant() [1/2]

◆ getCouplingConstant() [2/2]

◆ getE()

◆ getImageChargePlaneZ()

◆ getPhi()

◆ getRho()

◆ getShiftedGreensPlaneZ()

◆ getZerofaceMaxSteps()

◆ getZeroFacePlaneDumpFrequency()

◆ hasValidBCHandler()

◆ initCGSolver() [1/2]

◆ initCGSolver() [2/2]

◆ initFFTSolver() [1/2]

◆ initFFTSolver() [2/2]

◆ initNullSolver() [1/3]

◆ initNullSolver() [2/3]

◆ initNullSolver() [3/3]

◆ initOpenSolver() [1/2]

◆ initOpenSolver() [2/2]

◆ initP3MSolver()

◆ initSolver() [1/2]

◆ initSolver() [2/2]

◆ initSolverWithParams() [1/2]

◆ initSolverWithParams() [2/2]

◆ isImageChargeActiveForStep()

◆ isImageChargeEnabled()

◆ isShiftedGreensActiveForStep()

◆ isShiftedGreensEnabled()

◆ prepareRhoForBin()

◆ printBinStatsTable()

◆ rebinAndPrepare()

◆ resetCallCounter()

◆ runShiftedOpenSolver() [1/2]

◆ runShiftedOpenSolver() [2/2]

◆ runSolver() [1/3]

◆ runSolver() [2/3]

◆ runSolver() [3/3]

◆ scaleAndShiftScalarField()

◆ setBCHandler()

◆ setE()

◆ setGatherAttribute()