Module: particleSimulation

The ParticleSimulation module provides algorithms, data structures, input/output and data transformation methods required for actual charged particle trajectory simulations.

Data Structures / Simulation Objects

class InterpolatedField

Three dimensional rectangular and regular field, capable of containing multiple spatially resolved scalar and 3d vector fields and allowing spatial interpolation of the field values

Public Functions

explicit InterpolatedField(const std::string &hdf5Filename)

Constructor from a HDF5 file with a grid data set. The grid data can have varying grid point distances in the spatial directions and can have multiple data fields of scalar or 3d vector data

Parameters:

hdf5Filename – The filename of the HDF5 file to read

double getScalar(std::size_t ix, std::size_t iy, std::size_t iz, std::size_t fieldIndex) const

Get an uninterpolated scalar from the grid raw data.

Parameters:

  • ix – Data point index in x direction

  • iy – Data point index in y direction

  • iz – Data point index in z direction

  • fieldIndex – The index of the data field to return a data point from

double getInterpolatedScalar(double x, double y, double z, std::size_t fieldIndex) const

Gets an interpolated scalar for an arbitrary spatial position

Parameters:

  • x – Position of the probed data point in x direction

  • y – Position of the probed data point in y direction

  • z – Position of the probed data point in z direction

  • fieldIndex – The index of the data field to return an interpolated data point for

Core::Vector getVector(std::size_t ix, std::size_t iy, std::size_t iz, std::size_t fieldIndex) const

Get an uninterpolated vector from the grid raw data.

Parameters:

  • ix – Data point index in x direction

  • iy – Data point index in y direction

  • iz – Data point index in z direction

  • fieldIndex – The index of the data field to return a 3d vector data point from

Core::Vector getInterpolatedVector(double x, double y, double z, std::size_t fieldIndex) const

Gets an interpolated vector for an arbitrary spatial position

Parameters:

  • x – Position of the probed data point in x direction

  • y – Position of the probed data point in y direction

  • z – Position of the probed data point in z direction

  • fieldIndex – The index of the data field to return an interpolated 3d vector data point from

std::vector<std::vector<double>> getGrid() const

Gets the spatial grid (set of three vectors of spatial positions of the data points in the spatial dimensions)

std::array<double, 6> getBounds() const

Gets the outer spatial bounds of the data field

std::array<std::size_t, 3> findLowerBoundIndices(double x, double y, double z) const

Finds the highest indices which have spatial positions which are lower than the given position (lower corner neighbor of a given position)

Parameters:

  • x – X component of the probed position

  • y – Y component of the probed position

  • z – Z component of the probed position

class SampledWaveform

Sampled waveform (for example for SWIFT simulations) Sampled waveforms are simple one dimensional vectors with voltage values, one sampled value per timestep. Sampled waveforms are provided as simple CSV files, one value per line.

Public Functions

explicit SampledWaveform(std::string filename)

Constructor: Creates a sampled waveform from a given file

Parameters:

filename – the name of the file to read

bool good() const

Checks if the input file was read correctly and waveform data is ready

Returns:

true if the data was read correctly

std::size_t size() const

Returns the size of the waveform vector

Returns:

the number of elements in the waveform vector

double getValue(std::size_t index) const

Gets a value from the waveform data

Parameters:

index – an numeric index in the data vector of the waveform

Returns:

Voltage value of the timestep specified by the index

double getValueLooped(std::size_t index) const

Gets a value from the waveform data in a looped way: If the index is larger than the size of the waveform vector, the index is wrapped around Example: Index 12 in a 10 element waveform gets index 1 (not 2 because of zero indexing)

Parameters:

index – an numeric index in the data vector of the waveform

Returns:

Voltage value of the timestep specified by the index

double operator[](std::size_t index) const

Sampled waveforms can be used like arrays

Parameters:

index – an numeric index in the data vector of the sampled waveform

Returns:

Voltage value specified by index

double getInterpolatedValue(double phase) const

Gets linearly interpolated waveform values

Parameters:

phase – The waveform phase to get an interpolated value for (phase is considered not to be in radians, thus the phase values have to be between [0 .. 1])

Returns:

The linearly interpolated value for the given phase

class SimionPotentialArray

Public Functions

SimionPotentialArray(std::string filename, double spatialScale = 0.001)

Default constructor: Reads a SIMION PA file. The geometric scale is 0.001 since the usual length unit in SIMION PA files is mm.

Parameters:

  • filename – The filename of the SIMION PA file to read

  • spatialScale – A geometric scale factor to scale the potential array (default = 0.001 which is the conversion factor from mm, the length unit of SIMION, to m)

SimionPotentialArray(std::string filename, double spatialScale, double potentialScale)
SimionPotentialArray(std::string filename, Core::Vector position, double spatialScale, double potentialScale)
SimionPotentialArray(const SimionPotentialArray&) = delete
void setCornerPosition(Core::Vector newCornerPosition)
double getPotential(index_t ix, index_t iy, index_t iz) const
double getInterpolatedPotential(double xPt, double yPt, double zPt) const
Core::Vector getField(double xPt, double yPt, double zPt) const
bool isElectrode(double xPt, double yPt, double zPt) const
bool isInside(double xPt, double yPt, double zPt) const
std::array<double, 6> getBounds() const
std::array<index_t, 3> getNumberOfGridPoints() const
std::string getHeaderString() const
void printState() const

Particle Start Zones

Particles / Ions are started from particle start zones. ParticleSimulation::ParticleStartZone is the abstract super class of all particle start zones. All particle start zones can generate random start positions in the start zone with the :cpp:any:’getRandomParticlePosition’ method. A random set of particles in the particle start zone can be generated with the getRandomParticlesInStartZone method.

Currently, there are two instantiable particle start zones, a box with faces parallel to the main axes ParticleSimulation::BoxStartZone, and a cylindrical start zone which can be rotated and shifted ParticleSimulation::CylinderStartZone.

class ParticleStartZone

Abstract particle start zone class

Subclassed by ParticleSimulation::BoxStartZone, ParticleSimulation::CylinderStartZone, ParticleSimulation::SphereStartZone

Public Functions

virtual ~ParticleStartZone() = default
virtual Core::Vector getRandomParticlePosition() = 0
std::vector<std::unique_ptr<Core::Particle>> getRandomParticlesInStartZone(std::size_t numIons, double charge, double timeOfBirthRange = 0.0)

Generates a set of random ions in the ion start zone

Parameters:

  • numIons – number of ions

  • charge – charge of the generated ions

  • timeOfBirthRange – ions are generated with times of birth uniformly distributed in this range

Returns:

vector of random ions in cylindrical start zone

class BoxStartZone : public ParticleSimulation::ParticleStartZone

A box start zone with faces parallel to the axes of the coordinate system

Public Functions

explicit BoxStartZone(Core::Vector size, Core::Vector centerPosition = {0.0, 0.0, 0.0})

Constructs a box start zone

Parameters:

  • size – Size of the box in x,y,z, direction

  • centerPosition – Position of the box center

virtual Core::Vector getRandomParticlePosition() override

Gets a random position in the box particle start zone.

class CylinderStartZone : public ParticleSimulation::ParticleStartZone

Cylindrical particle start zone which can be rotated and translated in space.

Public Functions

CylinderStartZone(double radius, double length, Core::Vector normalVector = {0.0, 0.0, 0.0}, Core::Vector baseVector = {0.0, 0.0, 0.0})

Constructs a cylinder start zone

Parameters:

  • radius – Radius of the cylinder

  • length – length of the cylinder

  • normalVector – Normal vector of the bottom face of the cylinder

  • baseVector – Center position of the bottom face of the cylinder

virtual Core::Vector getRandomParticlePosition() override

Returns a new random particle position in the cylindrical start zone

Utilities

PSim_util.hpp / .cpp bundles a set of utility functions in the ParticleSimulation::util namespace:

namespace util

Functions

std::vector<std::unique_ptr<Core::Particle>> prepareIonsOnCylinderWalls(unsigned int nIons, double charge, double radius, double length)

Creates a hollow cylinder with ions / charged particles on the cylinder wall. Cylinder axis is the z axis

Parameters:

  • nIons – number of particles to create

  • charge – charge of particles to create

  • radius – radius of the cylinder (in xy direction)

  • length – length of the cylinder (in z direction)

Returns:

particles on the cylinder wall

std::vector<std::tuple<double, double, Core::Vector>> probeForces(std::vector<Core::Particle> &ions, Plane plane, int nU, int nV, double minU, double minV, double maxU, double maxV, double slicePos)

Probes electrical force induced by a group of charged particles on a spatial plane (U V W are the spatial coordinates in the sampled plane)

Parameters:

  • ions – cloud of charged particles which induce electric force by their charge

  • plane – a plane orientation

  • nU – number of sampled points in U direction of the plane

  • nV – number of sampled points in V direction of the plane

  • minU – lower bound of the plane in U direction

  • minV – lower bound of the plane in V direction

  • maxU – upper bound of the plane in U direction

  • maxV – upper bound of the plane in V direction

  • slicePos – position of the plane in W direction

Returns:

a vector with the U and V coordinates and the local electrical forces

std::vector<Core::Vector> getRandomPositionsInBox(unsigned int nPositions, Core::Vector corner, Core::Vector boxSize)

Produces random positions in a box

Parameters:

  • nPositions – number of positions

  • corner – lower corner of the box (xLow,yLow,zLow corner)

  • boxSize – size of the box in x,y,z direction

Returns:

random sampled positions in the speciefied box

std::vector<Core::Vector> getPositionsOnGrid(Core::Vector corner, Core::Vector boxSize, unsigned int nPerDirection)

Gets randomly sampled ions in a box

Parameters:

  • numIons – number of ions

  • charge – charge of the generated ions

  • corner – lower corner of the box (xLow,yLow,zLow corner)

  • boxSize – size of the box in x,y,z direction

  • timeOfBirthRange – ions are generated with times of birth uniformly distributed in this range

Returns:

randomly vector of ions in a box

std::vector<std::unique_ptr<Core::Particle>> getIonOnLineVector(unsigned int numIons, double charge, double x, double y, double z, double timeOfBirthRange = 0.0)

Generates a starting vector at position x,y,z

Parameters:

  • numIons – number of ions

  • charge – charge of the generated ions

  • x – x position

  • y – y position

  • z – z position

  • timeOfBirthRange – ions are generated with times of birth uniformly distributed in this range

Returns:

vector of ions in a straight line

PSim_math.hpp / .cpp bundles some math functions:

namespace ParticleSimulation

Functions

std::vector<double> linspace(double lower, double upper, int n)

Computes an linearly spaced vector of double values (similar to the corresponding matlab and numpy methods) (The returned vector contains the mathematical interval [lower,upper], so the boundary values are both part of the returned vector)

Parameters:

  • lower – a lower boundary of the computed values

  • upper – a upper boundary (which

  • n – the number of calculated values

Returns:

a std::vector with linearly spaced values between [lower,upper]

std::vector<double> fillVector(double value, int n)

Fill a vector with a given value

Parameters:

  • value – the value to fill in the vector

  • n – length of the vector to create

Returns:

a std::vector of length n filled with the value