Module: collisionModels
The collisionModels module provides models to describe the collisional interaction between charged particles and neutral background gas.
Collision models
Base Classes
CollisionModel::AbstractCollisionModel is the abstract base class for all collision models.
-
class AbstractCollisionModel
Subclassed by CollisionModel::HardSphereModel, CollisionModel::MDInteractionsModel, CollisionModel::MDInteractionsModelExperimental, CollisionModel::MultiCollisionModel, CollisionModel::SoftSphereModel, CollisionModel::StatisticalDiffusionModel
CollisionModel::MultiCollisionModel combines multiple collision models, primarily CollisionModel::HardSphereModel, to model background gas mixtures in the hard sphere model.
-
class MultiCollisionModel : public CollisionModel::AbstractCollisionModel
Public Functions
-
explicit MultiCollisionModel(std::vector<std::unique_ptr<AbstractCollisionModel>> models)
Constructs a multi collision model from a vector of collision models. Note that the multi collision model does not check in any way if the combination of collision models is physically reasonable at all.
- Parameters:
models – a vector of collision models to be combined
-
virtual void updateModelParticleParameters(Core::Particle &ion) const override
Calls updateModelParticleParameters for all combined sub models
-
virtual void initializeModelParticleParameters(Core::Particle &ion) const override
Calls initializeModelParticleParameters for all combined sub models
-
virtual void updateModelTimestepParameters(unsigned int timestep, double time) override
Calls updateModelTimestepParameters for all combined sub models
-
virtual void modifyAcceleration(Core::Vector &acceleration, Core::Particle &ion, double dt) override
Calls modifyAcceleration for all combined sub models
-
explicit MultiCollisionModel(std::vector<std::unique_ptr<AbstractCollisionModel>> models)
Hard Sphere Collision Model
CollisionModel::HardSphereModel implements a low pressure, collision model based on hard sphere collisions:
-
class HardSphereModel : public CollisionModel::AbstractCollisionModel
Public Functions
-
HardSphereModel(double staticPressure, double staticTemperature, double collisionGasMassAmu, double collisionGasDiameterM, bool maxwellianApproximation = false)
Constructor for static background gas pressure and temperature
if maxwellianApproximation is true, the colliding background gas particle velocity is drawn from a Maxwell Boltzmann distribution instead of the more correct relative velocity distribution between charged particle and background gas
-
HardSphereModel(std::function<double(Core::Vector &location)> pressureFunction, std::function<Core::Vector(Core::Vector &location)> velocityFunction, double StaticTemperature, double collisionGasMassAmu, double collisionGasDiameterM, bool maxwellianApproximation = false)
Constructor for location dependent pressure and velocity, given as spatially resolved functions.
-
HardSphereModel(double staticPressure, double staticTemperature, double collisionGasMassAmu, double collisionGasDiameterM, std::function<void(RS::CollisionConditions, Core::Particle&)> afterCollisionFunction, bool maxwellianApproximation = false)
Constructor for static background gas pressure and temperature with a custom after collision function (most probably to model collision based reactions). After collision functions perform custom operations with the colliding particle and the conditions of the individual collision.
-
HardSphereModel(std::function<double(Core::Vector &location)> pressureFunction, std::function<Core::Vector(Core::Vector &location)> velocityFunction, std::function<double(const Core::Vector&)> temperatureFunction, double collisionGasMassAmu, double collisionGasDiameterM, std::function<void(RS::CollisionConditions, Core::Particle&)> afterCollisionFunction, bool maxwellianApproximation = false)
Constructor for location dependent pressure and velocity, given as spatially resolved functions and custom after collision function (most probably to model collision based reactions).
-
virtual void updateModelTimestepParameters(unsigned int timestep, double time) override
-
virtual void modifyAcceleration(Core::Vector &acceleration, Core::Particle &ion, double dt) override
-
virtual void modifyVelocity(Core::Particle &ion, double dt) override
Modify the velocity of a charged particle “ion” with a potential random collision in time step “dt” (only one or none collision can happen, not multiple. Thus, the probability of multiple colllision events happening in “dt” has to be low)
-
HardSphereModel(double staticPressure, double staticTemperature, double collisionGasMassAmu, double collisionGasDiameterM, bool maxwellianApproximation = false)
Statistical Diffusion Collision Model
CollisionModel::StatisticalDiffusionModel implements a high pressure statistical collision model:
-
class StatisticalDiffusionModel : public CollisionModel::AbstractCollisionModel
Public Functions
-
StatisticalDiffusionModel(double staticPressure, double staticTemperature, double collisionGasMassAmu, double collisionGasDiameterM, CollisionStatistics cs = CollisionStatistics())
Constructs a statistical diffusion model with static background gas (no velocity, static pressure and static temperature)
- Parameters:
staticPressure – static background gas pressure (in Pa)
staticTemperature – static background temperature (in K)
collisionGasMassAmu – mass of the background gas particles (in amu)
collisionGasDiameterM – effective collison diameter of the background gas particles (in m)
cs – normalized diffusive collision statistics
-
StatisticalDiffusionModel(double staticPressure, double staticTemperature, Core::Vector staticGasVelocity, double collisionGasMassAmu, double collisionGasDiameterM, CollisionStatistics cs = CollisionStatistics())
Constructs a statistical diffusion model with uniformly flowing background gas (static velocity vector, static pressure and static temperature)
- Parameters:
staticPressure – static background gas pressure (in Pa)
staticTemperature – static background temperature (in K)
staticGasVelocity – static gas velocity (m/s)
collisionGasMassAmu – mass of the background gas particles (in amu)
collisionGasDiameterM – effective collison diameter of the background gas particles (in m)
cs – normalized diffusive collision statistics
-
StatisticalDiffusionModel(std::function<double(const Core::Vector &location)> pressureFunction, std::function<double(const Core::Vector &location)> temperatureFunction, std::function<Core::Vector(const Core::Vector &location)> velocityFunction, double collisionGasMassAmu, double collisionGasDiameterM, CollisionStatistics cs = CollisionStatistics())
Constructs a statistical diffusion model with variable background gas (pressure, temperature and velocity given by arbitrary functions)
- Parameters:
pressureFunction – Function to map spatial location to pressure (in Pa)
temperatureFunction – Function to map spatial location to temperature (in K)
velocityFunction – Function to map spatial location to velocity vector (in m/s)
collisionGasMassAmu – mass of the background gas particles (in amu)
collisionGasDiameterM – effective collison diameter of the background gas particles (in m)
cs – normalized diffusive collision statistics
-
void setSTPParameters(Core::Particle &ion) const
Calculates and sets the average velocity, the default stokes damping and the average mean free path for an ion at standard conditions (STP)
- Parameters:
ion – The ion to calculate the parameters for
-
virtual void updateModelParticleParameters(Core::Particle &ion) const override
Updates internal model parameters for an ion which are dependent on ion position / timestep
-
virtual void initializeModelParticleParameters(Core::Particle &ion) const override
Inits model parameters which are not dependent on ion position / timestep for an ion
-
virtual void updateModelTimestepParameters(unsigned int timestep, double time) override
Updates model parameters dependent on timestep or simulation time
-
virtual void modifyAcceleration(Core::Vector &acceleration, Core::Particle &ion, double dt) override
Modifies the acceleration due to the background gas interaction
- Parameters:
acceleration – The current acceleration of the ion which is modified (the acceleration stored in the given particle object is usually later overwritten in the integration mechanism)
ion – An ion the acceleration is calculated for
dt – The length of the current time step
-
virtual void modifyVelocity(Core::Particle &ion, double dt) override
The ion velocity is not modified by the SDS model
-
virtual void modifyPosition(Core::Vector &position, Core::Particle &ion, double dt) override
Modifies the position of a particle according to the background gas interaction modeled with the SDS approach
- Parameters:
position – The current position of the particle which is modified (the position stored in the particle object is usually later overwritten in the integration mechanism)
ion – A ion the position is calculated for
dt – The length of the current time step
-
StatisticalDiffusionModel(double staticPressure, double staticTemperature, double collisionGasMassAmu, double collisionGasDiameterM, CollisionStatistics cs = CollisionStatistics())
CollisionModel::CollisionStatistics provides normalized collision statistics / density functions for statistical diffusion collision models:
-
class CollisionStatistics
Public Functions
-
CollisionStatistics()
Default constructor: Inits collision statistics with a default dataset
-
explicit CollisionStatistics(const std::string &statisticsFilename)
Constructor: Creates collision statistics from a collision statistics file (e.g. generated by the CollisionStatistics.jl)
- Parameters:
statisticsFilename – the name / path to a collision statistics parameter file
-
int getNDist() const
Gets the number of collision statistics (individual collision ICDFs)
- Returns:
the number of individual collision ICDFs in the collision statistics
-
int getNDistPoints() const
Gets the number of points / steps in the probabilty dimension of the ICDFs. The probability interval [0..1] is splitted in nDistPoints equidistant steps.
- Returns:
Number of points / steps in the ICDFs.
-
int getNCollisions() const
Gets the number of collisions which was performed to simulate / calculate the ICDFs.
- Returns:
Number of collisions in the Monte-Carlo simulations leading to the ICDFs.
-
std::vector<double> getMassRatios() const
Returns the mass ratios of the ICDFs.
- Returns:
A vector with the mass ratios used in the Monte-Carlo simulations leading to the ICDFs.
-
double getLogMassRatio(std::size_t icdfIndex) const
Returns the logarithm of the mass ratio of an ICDF
- Parameters:
icdfIndex – the index of the ICDF
- Returns:
log(mass ratio) of the ICDF with index icdfIndex
-
double getLogMassRatioDistance(std::size_t index) const
Returns the difference of the logarithmic mass ratios between ICDF with indices index and index+1
- Parameters:
index – the index of the mass ratio difference
- Returns:
difference of logarithmic mass ratios of ICDF with indices index and index+1
-
std::vector<std::vector<double>> getICDFs() const
Gets the ICDFs from the collision statistics. The ICDFs are a vector of double vectors, one per mass ratio, with nDistPoints steps each.
- Returns:
The ICDFs from the collision statistics
-
std::size_t findUpperDistIndex(double logMassRatio) const
Gets the index of the collision distribution with a logMassRatio above the given logMassRatio
- Parameters:
logMassRatio – the logarithmic mass ratio to find the distribution index for
- Returns:
index of the collision distribution with a logarithmic mass ratio above logMassRatio
-
CollisionStatistics()
Molecular Dynamics Collision Model
CollisionModel::MDInteractionsModel implements a molecular dynamics collision model with resolvment of the individual collision events by full trajectory integration of both particles:
-
class MDInteractionsModel : public CollisionModel::AbstractCollisionModel
Public Functions
-
MDInteractionsModel() = default
-
void setTrajectoryWriter(const std::string &trajectoryFileName, double trajectoryDistance, unsigned int startTimeStep = 0)
Activates trajectory writing and sets trajectory writer configuration
- Parameters:
trajectoryFileName – Trajectory Output filename
trajectoryDistance – Distance between ion and background gas in m after which trajectory gets recorded
-
void writeTrajectory(double distance, Core::Vector positionBgMolecule, Core::Vector velocityBgMolecule, std::vector<Core::Vector> forceMolecules, bool endOfTrajectory, std::ofstream *file, double time, double dt)
Writes trajectory data to a predefined file. Individual collisions are separated by a line containing ‘###’.
Ouput includes: position of background gas, distance between the two molecules, integration time, velocity of the background gas, force acting on the background gas and timestep length
-
bool leapfrogIntern(std::vector<CollisionModel::Molecule*> moleculesPtr, double dt, double finalTime, double requiredRad)
Leapfrog method to integrate trajectories of particles involved in a collision. The leapfrog method is of second order and symplectic.
- Parameters:
moleculesPtr – collection of molecule pointer
dt – timestep length
finalTime – maximum integration time
requiredRad – radius defining the collision sphere, i.e. the distance that needs to be undercut for a collision to be considered (same radius which is used to estimate the collision probability)
-
bool rk4Intern(std::vector<CollisionModel::Molecule*> moleculesPtr, double dt, double finalTime, double requiredRad)
Runge-Kutta 4 method to integrate trajectories of particles involved in a collision. The RK4 is of fourth order. This integrator should NOT be used except for testing purposes as the adaptive step size method is faster.
- Parameters:
moleculesPtr – collection of molecule pointer
dt – timestep length
finalTime – maximum integration time
requiredRad – radius defining the collision sphere, i.e. the distance that needs to be undercut for a collision to be considered (same radius which is used to estimate the collision probability)
-
bool rk4InternAdaptiveStep(std::vector<CollisionModel::Molecule*> moleculesPtr, double dt, double finalTime, double requiredRad, double tolerance)
Adaptive step size Runge-Kutta-Fehlberg 45 method to integrate trajectories of particles involved in a collision. This method is of fourth order and uses error control of fifth order on the velocity to adaptively increase or decrease the timestep length reducing the overall computation time.
- Parameters:
moleculesPtr – collection of molecule pointer
dt – timestep length
finalTime – maximum integration time
requiredRad – radius defining the collision sphere, i.e. the distance that needs to be undercut for a collision to be considered (same radius which is used to estimate the collision probability)
tolerance – defines the allowed error threshold to control the timestep lengths
-
virtual void updateModelTimestepParameters(unsigned int timestep, double time)
Updates trajectory recording if timestep recording parameter is exceeded
-
virtual void modifyVelocity(Core::Particle &particle, double dt)
Modifies the velocity of the particle based on a molecular dynamics approach. Collision probability is estimated by a hard-sphere model. Trajectory is checked for energy conservation of 10 % and if necessary is repeated for up to 100 times under modification of the starting timestep length.
- Parameters:
particle – particle whose velocity is to be modified
dt – timestep length of overarching ion simulation
-
MDInteractionsModel() = default
Utilities
CollisionModel_util.hpp / .cpp bundles a set of utility functions in the CollisionModel::util namespace:
-
namespace util
Functions
-
double getAirToGas(double massIon_amu, double diameterIon_nm, double collisionGasMass_amu, double collisionGasDiameter_nm)
Calculates a scaling constant airToGas between the reduced ion mobilities of an ion in air K0air and in a collision gas K0gas: K0gas = K0air * airToGas.
The ion is characterized by its ion mass (amu) and effective ion diameter (m) while the collision gas to calculate airToGas for is defined by the mass (amu) and effective diameter (m) of collision gas mass particles.
-
double estimateCollisionDiameterFromMass(double massIon_amu)
Get rough estimate of ion diameter (in nm) from ion mass (in amu). (Emperical formula noted in SDS paper.)
-
double estimateMobility(double massIon_amu, double diameterIon_nm, double collisionGasMass_amu, double collisionGasDiameter_nm)
Estimates ion mobility (k0) in (10-4 m2 V-1 s-1) from the mass of an ion (in amu), effective diameter of ion (in nm) and the collision gas particle mass (in amu) and effective diamenter (in nm).
-
double getAirToGas(double massIon_amu, double diameterIon_nm, double collisionGasMass_amu, double collisionGasDiameter_nm)
CollisionModel_MathFunctions.hpp / .cpp bundles some math functions:
-
namespace CollisionModel
CollisionModel::Atom provides additional functionality for use in the CollisionModel::MDInteractionsModel class:
-
class Atom
Public Types
Public Functions
-
Atom() = default
-
~Atom() = default
-
Atom(const Core::Vector &relPos, double massAMU, double chargeElemCharges)
Creates an atom with mass and charge at a position relative to the parent molecule
- Parameters:
relPos – the relative position of the created atom
massAMU – the mass of the atom (in units of atomic mass)
chargeElemCharges – the charge of the atom (in units of elementary charges)
-
Atom(const Core::Vector &relPos, double massAMU, double chargeElemCharges, double partChargeElemCharges)
Creates an atom with mass, charge and partial charges at a position relative to the parent molecule
- Parameters:
relPos – the relative position of the created atom
massAMU – the mass of the atom (in units of atomic mass)
chargeElemCharges – the charge of the atom (in units of elementary charges)
partChargeElemCharges – the partial charge of the atom (in units of elementary charge)
-
Atom(const Core::Vector &relPos, double massAMU, double chargeElemCharges, double partChargeElemCharges, AtomType element, std::size_t speciesIndex, double sig, double eps)
Creates an atom with mass, charge and partial charges at a position relative to the parent molecule
- Parameters:
relPos – the relative position of the created atom
massAMU – the mass of the atom (in units of atomic mass)
chargeElemCharges – the charge of the atom (in units of elementary charges)
partChargeElemCharges – the partial charge of the atom (in units of elementary charge)
element – the atom type
speciesIndex – a unique numerical ID for the atomic species of this atom
sig – the Lennard-Jones parameter sigma of the atom (in units of meter)
eps – the Lennard-Jones parameter epsilon of the atom (in units of Joule)
-
void setMass(double massAMU)
Sets new mass
- Parameters:
massAMU – the new mass in atomic units
-
void setSpeciesIndex(std::size_t)
Sets the numeric species index
-
void setSigma(double sig)
Sets new LJ parameter sigma
-
void setEpsilon(double eps)
Sets new LJ paramter epsilon
-
void setCharge(double chargeElemCharges)
Sets new charge
- Parameters:
chargeElemCharges – the new charge in units of elementary charge
-
void setPartCharge(double partChargeElemCharges)
Sets new partial charge
- Parameters:
partChargeElemCharges – the new partial charge in units of elementary charge
-
double getMass() const
Get atom mass
-
std::size_t getSpeciesIndex() const
Get numeric atomic species index
-
double getSigma() const
Get LJ parameter sigma
-
double getEpsilon() const
Get LJ parameter epsilon
-
double getCharge() const
Get atom charge
-
double getPartCharge() const
Get partial atom charge
-
void rotate(const Core::Vector &angles)
Rotates atoms w.r.t its parent molecule based on given rotation angles in the x-y-z coordinate system. The implicitly given bond lengths are preserved. The angles are given as the accumalative angles in relation to the standard configuration of the molecule (all three angles are zero), e.g. rotate([0,0,pi/2]) rotates by pi/2 about z from the zero configuration and not by an additional pi/2 from the current configuration.
- Parameters:
angles – The current x-y-z rotation angles of the molecule
-
Atom() = default
CollisionModel::Molecule provides additional functionality for use in the CollisionModel::MDInteractionsModel class:
-
class Molecule
Public Functions
-
Molecule() = default
-
~Molecule() = default
-
Molecule(const Core::Vector &comPos, const Core::Vector &comVel)
Creates an empty molecule with a center-of-mass position and velocity
- Parameters:
comPos – the center-of-mass position of the created molecule
comVel – the center-of-mass velocity of the created molecule
Creates a molecule with given atoms and the starting angle configuration (rotation). The mass and dipole is calculated through the information given by the atoms and does not need to be specified.
- Parameters:
comPos – the center-of-mass position of the created molecule
comVel – the center-of-mass velocity of the created molecule
agls – the angles in x-y-z of the atoms relative position w.r.t the center-of-mass
atms – the vector with atoms contained in the molecule
diam – molecule diameter in m
Creates a molecule given by the molecular structure. The mass and dipole is calculated through the information given by the atoms and does not need to be specified.
- Parameters:
comPos – the center-of-mass position of the created molecule
comVel – the center-of-mass velocity of the created molecule
structure – molecular structure
-
void setAngles(Core::Vector agls)
Sets new angles of the atoms w.r.t. the center-of-mass of the molecule
-
void setDiameter(double diam)
Sets new diameter of the molecule
-
void setMolecularStructureName(std::string name)
Sets name of the molecular structure
-
bool getIsDipole() const
Returns if the molecule is a permanent dipole or not
-
bool getIsIon() const
Returns if the molecule is an ion or not
-
double getMass() const
Gets mass of the molecule
-
double getDipoleMag() const
Gets the dipole magnitude
-
std::size_t getAtomCount() const
Gets the number of atoms belonging to the molecule
-
std::vector<std::shared_ptr<CollisionModel::Atom>> &getAtoms()
Gets the vector of atoms belonging to the molecule
-
double getDiameter() const
Gets the diameter
-
std::string getMolecularStructureName() const
Gets the identifier of the molecular structure
Adds an additional atom to the molecule. Mass and dipole are recalculated.
Removes an atom from the molecule. Mass and dipole are recalculated.
-
void rotateMolecule()
Rotates the molecule by an angle set beforehand
-
Molecule() = default
CollisionModel::MolecularStructure provides the general structure for rigid body representations:
-
class MolecularStructure
Public Functions
-
MolecularStructure() = default
-
~MolecularStructure() = default
Creates a molecular structur with given atoms. The mass and dipole is calculated through the information given by the atoms and does not need to be specified.
- Parameters:
atms – the vector with atoms contained in the molecule
diam – molecule diameter in m
-
void setDiameter(double diam)
Sets new diameter of the MolecularStructure
-
void setName(std::string name)
-
bool getIsDipole() const
Returns if the MolecularStructure is a permanent dipole or not
-
bool getIsIon() const
Returns if the MolecularStructure is an ion or not
-
double getMass() const
Gets mass of the MolecularStructure
-
double getDipoleMag() const
Gets the dipole magnitude
-
std::size_t getAtomCount() const
Gets the number of atoms belonging to the MolecularStructure
-
std::vector<std::shared_ptr<CollisionModel::Atom>> getAtoms() const
Gets the vector of atoms belonging to the MolecularStructure
-
double getDiameter() const
Gets the diameter
-
std::string getName() const
Adds an additional atom to the MolecularStructure. Mass and dipole are recalculated.
Removes an atom from the MolecularStructure. Mass and dipole are recalculated.
-
MolecularStructure() = default