Implements the sampling method for reading particle phase space from ASCII files. More...

#include <FromFile.h>

Inheritance diagram for FromFile:

Collaboration diagram for FromFile:

Public Types
using	size_type = ippl::detail::size_type

Public Member Functions
	FromFile (std::shared_ptr< ParticleContainer_t > pc, std::shared_ptr< FieldContainer_t > fc, Distribution_t *opalDist)
	Constructor for FromFile.

	FromFile (std::shared_ptr< ParticleContainer_t > pc, std::shared_ptr< FieldContainer_t > fc, const std::string &filename)
	Convenience constructor that takes the filename directly.

void	generateParticles (size_t &numberOfParticles, Vector_t< double, 3 > nr) override
	Generates particles by reading from file.

void	emitParticles (double t, double dt) override
	Time-stepped emission hook for one-shot delayed file-based injection.

void	setEmissionOffsets (ippl::Vector< double, 3 > R0, ippl::Vector< double, 3 > P0, double t0, const std::string &emissionModel="NONE")

void	setInitialPolarization (const ippl::Vector< double, 3 > &pol)

void	fillPolarization (size_t startIdx, size_t count)

Vector_t< double, 3 >	getEmissionR0 () const

virtual bool	isEmissionDone (double t) const
	Whether this sampler has finished all emission (no more particles will be created).

virtual double	getGlobalTimeShift () const
	Optional tracker time shift needed before the first emitted particles are born.

virtual bool	hasInitialReferenceMomentum () const
	Optional initial reference momentum in the source-local frame.

virtual Vector_t< double, 3 >	getInitialReferenceMomentum () const

virtual double	getEmissionTimeStep () const
	Optional OPAL-like tracker time step while this sampler is still emitting.

virtual void	testNumEmitParticles (size_t, double)

virtual void	testEmitParticles (size_t, double)

virtual void	initDomainDecomp (double)

virtual void	setWithDomainDecomp (bool)

size_t	computeLocalEmitCount (size_t totalToSample) const
	Computes the number of particles this rank should emit so that the global total equals totalToSample and no rank exceeds its capacity (space left).

Protected Attributes
std::shared_ptr< ParticleContainer_t >	pc_m

std::shared_ptr< FieldContainer_t >	fc_m

Distribution_t *	opalDist_m = nullptr

std::string	samplingMethod_m

Vector_t< double, 3 >	R0_m = 0.0
	Emission source offset: position R0, momentum P0, start time t0 (applied in sample step).

Vector_t< double, 3 >	P0_m = 0.0

double	t0_m = 0.0

std::string	emissionModel_m = "NONE"

Vector_t< double, 3 >	initialPol_m = 0.0

bool	hasEmittedOnce_m = false
	For one-shot emitters (e.g. Gaussian at delayed t0): guard to avoid double sampling.

Private Member Functions
void	readFile (const std::string &filename)
	Reads and parses the particle file. Format must be: N (particle count), then header line (column names), then data lines. Comments ('#') and blank lines are skipped. Throws if format is invalid.

std::vector< size_t >	parseHeader (const std::string &headerLine)
	Parses the header line to get column indices. Header must contain all of x, y, z, px, py, pz (or aliases). Throws if any are missing.

std::string	normalizeColumnName (const std::string &name)
	Normalizes column name for comparison (case-insensitive, whitespace handling).

Private Attributes
std::string	filename_m
	File path to read particle data from.

std::vector< std::vector< double > >	particleData_m
	Stored particle data: each element is a 6D phase space vector [x, y, z, px, py, pz].

size_t	numParticles_m
	Number of particles in the file.

std::vector< size_t >	columnIndices_m
	Column indices mapping: [x_idx, y_idx, z_idx, px_idx, py_idx, pz_idx].

Detailed Description

Implements the sampling method for reading particle phase space from ASCII files.

The file must follow this structure (no variations allowed):

Line 1: number of particles (single integer N).
Line 2: column names (space-separated), e.g. "x px y py z pz".
Remaining lines: one data row per particle (6+ columns). Blank lines and lines starting with '#' are skipped. There must be exactly N data lines. If the file does not follow this structure, an error is thrown.

Definition at line 31 of file FromFile.h.

Member Typedef Documentation

◆ size_type

using FromFile::size_type = ippl::detail::size_type

Definition at line 33 of file FromFile.h.

Constructor & Destructor Documentation

◆ FromFile() [1/2]

FromFile::FromFile	(	std::shared_ptr< ParticleContainer_t >	pc,
		std::shared_ptr< FieldContainer_t >	fc,
		Distribution_t *	opalDist
	)

Constructor for FromFile.

Parameters

pc	Shared pointer to ParticleContainer.
fc	Shared pointer to FieldContainer.
opalDist	Borrowed Distribution.

Definition at line 15 of file FromFile.cpp.

References filename_m, Distribution::getFilename(), OpalData::getInputFn(), OpalData::getInstance(), and readFile().

Here is the call graph for this function:

◆ FromFile() [2/2]

FromFile::FromFile	(	std::shared_ptr< ParticleContainer_t >	pc,
		std::shared_ptr< FieldContainer_t >	fc,
		const std::string &	filename
	)

Convenience constructor that takes the filename directly.

This is primarily intended for unit tests, where constructing a full OPALX Distribution object is unnecessary. It behaves like the main constructor but skips querying the Distribution for the filename.

Definition at line 46 of file FromFile.cpp.

References filename_m, and readFile().

Here is the call graph for this function:

Member Function Documentation

◆ computeLocalEmitCount()

size_t SamplingBase::computeLocalEmitCount ( size_t totalToSample ) const

inherited

Computes the number of particles this rank should emit so that the global total equals totalToSample and no rank exceeds its capacity (space left).

Parameters

totalToSample Global number of particles to emit this timestep.

Returns: Local number of particles this rank should create/emit.

Definition at line 6 of file SamplingBase.cpp.

References SamplingBase::pc_m.

Referenced by FlatTop::countEnteringParticlesPerRank(), generateParticles(), Gaussian::generateParticles(), and MultiVariateGaussian::generateParticles().

◆ emitParticles()

void FromFile::emitParticles	(	double	t,
		double	dt
	)

overridevirtual

Time-stepped emission hook for one-shot delayed file-based injection.

When a source using FROMFILE has t0 > 0 and a positive NPARTDIST, the sampler will read and inject particles once when [t, t+dt] crosses t0. Initial sampling at t0 == 0 is handled via generateParticles.

Reimplemented from SamplingBase.

Definition at line 350 of file FromFile.cpp.

References generateParticles(), Distribution::getNumParticles(), SamplingBase::hasEmittedOnce_m, numParticles_m, SamplingBase::opalDist_m, SamplingBase::pc_m, and SamplingBase::t0_m.

Here is the call graph for this function:

◆ fillPolarization()

void SamplingBase::fillPolarization	(	size_t	startIdx,
		size_t	count
	)

inlineinherited

Fill the Pol particle attribute with initialPol_m on the half-open range [startIdx, startIdx + count). No-op when the container does not store spin. Must be called after the particles have been created and before they are pushed downstream.

Definition at line 63 of file SamplingBase.hpp.

References SamplingBase::initialPol_m, and SamplingBase::pc_m.

Referenced by FlatTop::emitParticles(), generateParticles(), Gaussian::generateParticles(), and MultiVariateGaussian::generateParticles().

◆ generateParticles()

void FromFile::generateParticles	(	size_t &	numberOfParticles,
		Vector_t< double, 3 >	nr
	)

overridevirtual

Generates particles by reading from file.

Parameters

numberOfParticles	Number of particles to generate (may be overridden by file).
nr	Number of grid points per direction (not used here).

Reimplemented from SamplingBase.

Definition at line 234 of file FromFile.cpp.

References SamplingBase::computeLocalEmitCount(), SamplingBase::emissionModel_m, filename_m, SamplingBase::fillPolarization(), SamplingBase::hasEmittedOnce_m, numParticles_m, SamplingBase::P0_m, particleData_m, SamplingBase::pc_m, SamplingBase::R0_m, and SamplingBase::t0_m.

Referenced by emitParticles(), TEST_F(), TEST_F(), and TEST_F().

Here is the call graph for this function:

◆ getEmissionR0()

Vector_t< double, 3 > SamplingBase::getEmissionR0 ( ) const

inlineinherited

Definition at line 78 of file SamplingBase.hpp.

References SamplingBase::R0_m.

◆ getEmissionTimeStep()

virtual double SamplingBase::getEmissionTimeStep ( ) const

inlinevirtualinherited

Optional OPAL-like tracker time step while this sampler is still emitting.

Reimplemented in EmittedFromFile, and OpalFlatTop.

Definition at line 102 of file SamplingBase.hpp.

◆ getGlobalTimeShift()

virtual double SamplingBase::getGlobalTimeShift ( ) const

inlinevirtualinherited

Optional tracker time shift needed before the first emitted particles are born.

Reimplemented in EmittedFromFile, and OpalFlatTop.

Definition at line 92 of file SamplingBase.hpp.

◆ getInitialReferenceMomentum()

virtual Vector_t< double, 3 > SamplingBase::getInitialReferenceMomentum ( ) const

inlinevirtualinherited

Reimplemented in EmittedFromFile, and OpalFlatTop.

Definition at line 97 of file SamplingBase.hpp.

◆ hasInitialReferenceMomentum()

virtual bool SamplingBase::hasInitialReferenceMomentum ( ) const

inlinevirtualinherited

Optional initial reference momentum in the source-local frame.

Reimplemented in EmittedFromFile, and OpalFlatTop.

Definition at line 95 of file SamplingBase.hpp.

◆ initDomainDecomp()

virtual void SamplingBase::initDomainDecomp ( double )

inlinevirtualinherited

Reimplemented in FlatTop, and OpalFlatTop.

Definition at line 110 of file SamplingBase.hpp.

◆ isEmissionDone()

virtual bool SamplingBase::isEmissionDone ( double t ) const

inlinevirtualinherited

Whether this sampler has finished all emission (no more particles will be created).

Parameters

t	Current simulation time (s).

Reimplemented in FlatTop, EmittedFromFile, and OpalFlatTop.

Definition at line 86 of file SamplingBase.hpp.

References SamplingBase::hasEmittedOnce_m.

◆ normalizeColumnName()

std::string FromFile::normalizeColumnName ( const std::string & name )

private

Normalizes column name for comparison (case-insensitive, whitespace handling).

Parameters

name	Column name to normalize.

Returns: Normalized column name.

Definition at line 214 of file FromFile.cpp.

Referenced by parseHeader().

◆ parseHeader()

std::vector< size_t > FromFile::parseHeader ( const std::string & headerLine )

private

Parses the header line to get column indices. Header must contain all of x, y, z, px, py, pz (or aliases). Throws if any are missing.

Parameters

headerLine The header line string.

Returns: Vector of column indices: [x_idx, y_idx, z_idx, px_idx, py_idx, pz_idx]

Definition at line 169 of file FromFile.cpp.

References normalizeColumnName().

Referenced by readFile().

Here is the call graph for this function:

◆ readFile()

void FromFile::readFile ( const std::string & filename )

private

Reads and parses the particle file. Format must be: N (particle count), then header line (column names), then data lines. Comments ('#') and blank lines are skipped. Throws if format is invalid.

Parameters

filename Path to the file to read.

Definition at line 60 of file FromFile.cpp.

References columnIndices_m, numParticles_m, parseHeader(), and particleData_m.

Referenced by FromFile(), and FromFile().

Here is the call graph for this function:

◆ setEmissionOffsets()

void SamplingBase::setEmissionOffsets	(	ippl::Vector< double, 3 >	R0,
		ippl::Vector< double, 3 >	P0,
		double	t0,
		const std::string &	emissionModel = `"NONE"`
	)

inlineinherited

Definition at line 48 of file SamplingBase.hpp.

References SamplingBase::emissionModel_m, SamplingBase::P0_m, SamplingBase::R0_m, and SamplingBase::t0_m.

Referenced by TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), and TEST_F().

◆ setInitialPolarization()

void SamplingBase::setInitialPolarization ( const ippl::Vector< double, 3 > & pol )

inlineinherited

Definition at line 57 of file SamplingBase.hpp.

References SamplingBase::initialPol_m.

◆ setWithDomainDecomp()

virtual void SamplingBase::setWithDomainDecomp ( bool )

inlinevirtualinherited

Reimplemented in FlatTop, and OpalFlatTop.

Definition at line 112 of file SamplingBase.hpp.

◆ testEmitParticles()

virtual void SamplingBase::testEmitParticles	(	size_t	,
		double
	)

inlinevirtualinherited

Definition at line 108 of file SamplingBase.hpp.

◆ testNumEmitParticles()

virtual void SamplingBase::testNumEmitParticles	(	size_t	,
		double
	)

inlinevirtualinherited

Definition at line 105 of file SamplingBase.hpp.

Member Data Documentation

◆ columnIndices_m

std::vector<size_t> FromFile::columnIndices_m

private

Column indices mapping: [x_idx, y_idx, z_idx, px_idx, py_idx, pz_idx].

Definition at line 106 of file FromFile.h.

Referenced by readFile().

◆ emissionModel_m

std::string SamplingBase::emissionModel_m = "NONE"

protectedinherited

Definition at line 25 of file SamplingBase.hpp.

Referenced by OpalFlatTop::generateLocalParticles(), EmittedFromFile::generateParticles(), generateParticles(), Gaussian::generateParticles(), MultiVariateGaussian::generateParticles(), FlatTop::generateUniformDisk(), OpalFlatTop::getInitialReferenceMomentum(), and SamplingBase::setEmissionOffsets().

◆ fc_m

std::shared_ptr<FieldContainer_t> SamplingBase::fc_m

protectedinherited

Definition at line 18 of file SamplingBase.hpp.

Referenced by FlatTop::initDomainDecomp(), OpalFlatTop::initDomainDecomp(), FlatTop::setParameters(), and OpalFlatTop::setParameters().

◆ filename_m

std::string FromFile::filename_m

private

File path to read particle data from.

Definition at line 97 of file FromFile.h.

Referenced by FromFile(), FromFile(), and generateParticles().

◆ hasEmittedOnce_m

bool SamplingBase::hasEmittedOnce_m = false

protectedinherited

For one-shot emitters (e.g. Gaussian at delayed t0): guard to avoid double sampling.

Definition at line 33 of file SamplingBase.hpp.

Referenced by emitParticles(), Gaussian::emitParticles(), MultiVariateGaussian::emitParticles(), generateParticles(), Gaussian::generateParticles(), MultiVariateGaussian::generateParticles(), and SamplingBase::isEmissionDone().

◆ initialPol_m

Vector_t<double, 3> SamplingBase::initialPol_m = 0.0

protectedinherited

Initial polarization vector P applied to every particle this sampler creates. Rest-frame Pauli expectations along lab-frame axes; |Pol| in [0, 1]. Ignored when the container does not have a spin attribute (hasSpin() == false).

Definition at line 30 of file SamplingBase.hpp.

Referenced by SamplingBase::fillPolarization(), and SamplingBase::setInitialPolarization().

◆ numParticles_m

size_t FromFile::numParticles_m

private

Number of particles in the file.

Definition at line 103 of file FromFile.h.

Referenced by emitParticles(), generateParticles(), and readFile().

◆ opalDist_m

Distribution_t* SamplingBase::opalDist_m = nullptr

protectedinherited

Definition at line 19 of file SamplingBase.hpp.

Referenced by EmittedFromFile::buildInventory(), emitParticles(), Gaussian::emitParticles(), MultiVariateGaussian::emitParticles(), EmittedFromFile::generateParticles(), MultiVariateGaussian::MultiVariateGaussian(), and FlatTop::setParameters().

◆ P0_m

Vector_t<double, 3> SamplingBase::P0_m = 0.0

protectedinherited

Definition at line 23 of file SamplingBase.hpp.

Referenced by EmittedFromFile::buildInventory(), EmittedFromFile::generateLocalParticles(), OpalFlatTop::generateLocalParticles(), generateParticles(), Gaussian::generateParticles(), MultiVariateGaussian::generateParticles(), FlatTop::generateUniformDisk(), OpalFlatTop::getInitialReferenceMomentum(), and SamplingBase::setEmissionOffsets().

◆ particleData_m

std::vector<std::vector<double> > FromFile::particleData_m

private

Stored particle data: each element is a 6D phase space vector [x, y, z, px, py, pz].

Definition at line 100 of file FromFile.h.

Referenced by generateParticles(), and readFile().

◆ pc_m

std::shared_ptr<ParticleContainer_t> SamplingBase::pc_m

protectedinherited

◆ R0_m

Vector_t<double, 3> SamplingBase::R0_m = 0.0

protectedinherited

Emission source offset: position R0, momentum P0, start time t0 (applied in sample step).

Definition at line 22 of file SamplingBase.hpp.

Referenced by EmittedFromFile::generateLocalParticles(), OpalFlatTop::generateLocalParticles(), generateParticles(), Gaussian::generateParticles(), MultiVariateGaussian::generateParticles(), FlatTop::generateUniformDisk(), SamplingBase::getEmissionR0(), and SamplingBase::setEmissionOffsets().

◆ samplingMethod_m

std::string SamplingBase::samplingMethod_m

protectedinherited

Definition at line 20 of file SamplingBase.hpp.

◆ t0_m

double SamplingBase::t0_m = 0.0

protectedinherited

Definition at line 24 of file SamplingBase.hpp.

Referenced by EmittedFromFile::buildInventory(), FlatTop::emitParticles(), emitParticles(), Gaussian::emitParticles(), MultiVariateGaussian::emitParticles(), generateParticles(), Gaussian::generateParticles(), MultiVariateGaussian::generateParticles(), EmittedFromFile::getGlobalTimeShift(), OpalFlatTop::getGlobalTimeShift(), FlatTop::isEmissionDone(), SamplingBase::setEmissionOffsets(), and OpalFlatTop::toBirthTime().

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

Public Types

Public Member Functions

Protected Attributes

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ size_type

Constructor & Destructor Documentation

◆ FromFile() [1/2]

◆ FromFile() [2/2]

Member Function Documentation

◆ computeLocalEmitCount()

◆ emitParticles()

◆ fillPolarization()

◆ generateParticles()

◆ getEmissionR0()

◆ getEmissionTimeStep()

◆ getGlobalTimeShift()

◆ getInitialReferenceMomentum()

◆ hasInitialReferenceMomentum()

◆ initDomainDecomp()

◆ isEmissionDone()

◆ normalizeColumnName()

◆ parseHeader()

◆ readFile()

◆ setEmissionOffsets()

◆ setInitialPolarization()

◆ setWithDomainDecomp()

◆ testEmitParticles()

◆ testNumEmitParticles()

Member Data Documentation

◆ columnIndices_m

◆ emissionModel_m

◆ fc_m

◆ filename_m

◆ hasEmittedOnce_m

◆ initialPol_m

◆ numParticles_m

◆ opalDist_m

◆ P0_m

◆ particleData_m

◆ pc_m

◆ R0_m

◆ samplingMethod_m

◆ t0_m