Module: Core

The Core module bundles basic data structures, particularly the basic spatial vector class, and basic facilities required in most other modules.

Basic 3D Vector: Core::Vector

Core::Vector is the fundamental spatial vector class used in IDSimF:

class Vector

Simple 3d vector

Public Functions

Vector() = default

Vector(double x, double y, double z)

Constructs vector with components

Parameters:

• x – x component

• y – y component

• z – z component

explicit Vector(const double*)

Constructs vector with components passed as array

Parameters:

coord – three element array with x,y,z components

double x() const

x component

double y() const

y component

double z() const

z component

void set(double x, double y, double z)

Sets new components

Parameters:

• x – x component

• y – y component

• z – z component

void x(double x)

Set new x component

void y(double y)

Set new y component

void z(double z)

Set new z component

double magnitude() const

Returns the magnitude of the vector

double magnitudeSquared() const

Returns the square of magnitude of the vector

Vector crossProduct(const Vector &rhs) const

Vector &operator+=(const Vector &rhs)

void printState() const

Prints vector state / vector components

Friends

friend Vector operator+(const Vector &lhs, const Vector &rhs)

friend Vector operator-(const Vector &lhs, const Vector &rhs)

friend double operator*(const Vector &lhs, const Vector &rhs)

friend Vector operator*(const Vector &lhs, double rhs)

friend Vector operator/(const Vector &lhs, double rhs)

friend Vector operator*(double lhs, const Vector &rhs)

friend bool operator==(Vector const &lhs, Vector const &rhs)

friend bool operator!=(const Vector &lhs, const Vector &rhs)

Particle Class

IDSimF implements particle based simulation methods. Core::Particle is the current base class for all simulated particles in IDSimF. It bundles the basic characteristics of simulated charged particles in IDSimF.

class Particle

Defines a simulated particle, which can be managed by a geometrical Core

Subclassed by RS::ReactiveParticle

Public Functions

Particle() = default

virtual ~Particle() = default

Particle(const Core::Vector &location, double chargeElemCharges)

Creates a massless charged particle at a location

Parameters:

• location – the location of the created particle

• chargeElemCharges – the charge of the particle (in units of elementary charges)

Particle(const Core::Vector &location, const Core::Vector &velocity, double chargeElemCharges, double massAMU)

Creates a charged particle at a location

Parameters:

• location – the location of the created particle

• velocity – the velocity of the created particle

• chargeElemCharges – the charge of the particle (in units of elementary charges)

• massAMU – the mass of the charged particle (in atomic mass units)

Particle(const Core::Vector &location, const Core::Vector &velocity, double chargeElemCharges, double massAMU, double timeOfBirth)

Creates a charged particle at a location

Parameters:

• location – the location of the created particle

• velocity – the velocity of the created particle

• chargeElemCharges – the charge of the particle (in units of elementary charges)

• massAMU – the mass of the charged particle (in atomic mass units)

• timeOfBirth – the time when this particle was created

Particle(const Core::Vector &location, const Core::Vector &velocity, double chargeElemCharges, double massAMU, double collisionDiameterM, double timeOfBirth)

Creates a charged particle at a location

Parameters:

• location – the location of the created particle

• velocity – the velocity of the created particle

• chargeElemCharges – the charge of the particle (in units of elementary charges)

• massAMU – the mass of the charged particle (in atomic mass units)

• collisionDiameterM – the effective collision diameter of the particle (in m)

• timeOfBirth – the time when this particle was created

Particle(const Core::Vector &location, const Core::Vector &velocity, double chargeElemCharges, double massAMU, double collisionDiameterM, double timeOfBirth, std::shared_ptr<CollisionModel::MolecularStructure> moleculeStructure)

Creates a charged particle at a location

Parameters:

• location – the location of the created particle

• velocity – the velocity of the created particle

• chargeElemCharges – the charge of the particle (in units of elementary charges)

• massAMU – the mass of the charged particle (in atomic mass units)

• collisionDiameterM – the effective collision diameter of the particle (in m)

• timeOfBirth – the time when this particle was created

• moleculeStructure – pointer to the molecule which should be used in the MD Collision Model

void setLocation(Core::Vector location)

Sets a new location

Core::Vector &getLocation()

Gets the location

void setVelocity(Core::Vector velocity)

Sets a velocity

Core::Vector &getVelocity()

Gets the velocity

void setAcceleration(Core::Vector velocity)

Sets the acceleration

Core::Vector &getAcceleration()

Gets the acceleration

void setIndex(size_t index)

Sets the external index of the particle

std::size_t getIndex() const

Gets the external index of the particle

void setChargeElementary(double chargeElemCharges)

Sets the charge in units of elementary charges

Parameters:

chargeElemCharges – the new charge in units of elementary charges

double getCharge() const

Gets the charge of the particle

Returns:

charge of the particle (in Coulomb)

void setActive(bool active)

Sets active state of the particle

bool isActive() const

Gets the active state of the particle

Returns:

true if the particle is active

void setInvalid(bool invalid)

Sets the invalid state of the particle

bool isInvalid() const

Gets the invalid state of the particle

Returns:

true if the particle is invalid

double getFloatAttribute(const std::string &key) const

Gets a floating point particle attribute

Parameters:

key – a textual key which identifies the attribute

Returns:

the value of the attribute with the given key

void setFloatAttribute(const std::string &key, double value)

Sets a floating point particle attribute

Parameters:

• key – a textual key which identifies the attribute

• value – the new value of the attribute

int getIntegerAttribute(const std::string &key) const

Gets an integer particle attribute

Parameters:

key – a textual key which identifies the attribute

Returns:

the value of the attribute with the given key

void setIntegerAttribute(const std::string &key, int value)

Sets an integer particle attribute

Parameters:

• key – a textual key which identifies the attribute

• value – the new value of the attribute

std::array<double, 3> &getAuxCollisionParams()

Accesses the array of auxiliary parameters for collision models

void setMobility(double mobility)

Sets the (actual) electrical mobility

double getMobility() const

Gets the (actual) electrical mobility

void setLowFieldMobility(double lowFieldMobility)

Sets the low field electrical mobility (reduced mobility with vanishing electric field)

double getLowFieldMobility() const

Gets the low field electrical mobility (reduced mobility with vanishing electric field)

void setMeanFreePathSTP(double meanFreePathSTP)

Sets the mean free path at standard temperature and standard pressure

double getMeanFreePathSTP() const

Gets the mean free path at standard temperature and standard pressure

void setMeanThermalVelocitySTP(double meanVelocitySTP)

Sets the mean thermal velocity at standard tempeature and standard pressure

double getMeanThermalVelocitySTP() const

Gets the mean velocity at standard temperature and standard pressure

void setMassAMU(double massAMU)

Sets the mass

Parameters:

massAMU – mass in atomic mass units

double getMass() const

Gets the mass (in kg)

Returns:

the mass in kg

void setDiameter(double diameter)

Sets the particle diameter

double getDiameter() const

Gets the particle diameter

void setTimeOfBirth(double timeOfBirth)

Sets the time of particle creation / “birth”

double getTimeOfBirth() const

Gets the time of particle creation / “birth”

void setSplatTime(double splatTime)

Sets the “splat” / termination time

double getSplatTime() const

Gets the “splat” / termination time

void setMolecularStructure(std::shared_ptr<CollisionModel::MolecularStructure> molecularStructurePtr)

Sets the molecular structure pointer

std::shared_ptr<CollisionModel::MolecularStructure> getMolecularStructure()

Gets the molecular structure pointer

Random Generators / Random Distributions

Random sources

The Core module provides basic randomness / random bit sources:

class RandomSource

Generalized source for randomness. Allows to produce uniformly and normal distributed random values and random bits

Subclassed by Core::RandomGeneratorPool::RNGPoolElement, Core::TestRandomGeneratorPool::TestRNGPoolElement, Core::XoshiroTestRandomGeneratorPool::XoshiroTestRNGPoolElement

Public Functions

virtual ~RandomSource() = default

virtual double uniformRealRndValue() = 0

virtual double normalRealRndValue() = 0

virtual RandomBitSource<rndBit_type> *getRandomBitSource() = 0

class MersenneBitSource : public Core::RandomBitSource<rndBit_type>

Random bit source based on mersenne twister

Public Functions

MersenneBitSource()

Creates a mersenne bit source (initialized by the global seed generator)

void seed(rndBit_type seed)

Sets the random seed of the bit source

virtual rndBit_type operator()() override

Maximum value of the value range Minimum value of the value range Gets a random bit value

Public Members

std::mt19937_64 internalRandomSource

class TestBitSource : public Core::RandomBitSource<rndBit_type>

Random bit source, which generates NO random bits but a short sequence of predefined bits for testing purposes

Public Functions

TestBitSource()

Creates a test (essentially non random) bit source.

virtual rndBit_type operator()() override

Maximum value of the value range Minimum value of the value range Generates next value from the predefined, short, list of bit values / bit patterns

Random pools

Randomness generators are organized in pools for multithreaded applications:

class AbstractRandomGeneratorPool

Generalized pool of random sources, usually one per thread. This allows to provide individual, seperate random sources for individual threads and can produce random distribution objects.

Subclassed by Core::RandomGeneratorPool, Core::TestRandomGeneratorPool, Core::XoshiroTestRandomGeneratorPool

Public Functions

virtual ~AbstractRandomGeneratorPool() = default

virtual void setSeedForElements(rndBit_type newSeed) = 0

virtual RndDistPtr getUniformDistribution(double min, double max) = 0

virtual RandomSource *getThreadRandomSource() = 0

virtual RandomSource *getRandomSource(std::size_t index) = 0

class RandomGeneratorPool : public Core::AbstractRandomGeneratorPool

Pool of random sources, with random sources based on Mersenne Twister

Public Functions

RandomGeneratorPool()

Constructs the productive random generator pool

virtual void setSeedForElements(rndBit_type newSeed) override

Sets a new random seed for all elements of the pools

virtual RndDistPtr getUniformDistribution(double min, double max) override

Get a new uniform random distribution in the interval [min, max]. Note that the underlying random bit source is the random bit source associated to the current thread. The random bit source is NOT changed if the distribution is called from another thread.

Parameters:

• min – Lower boundary of the interval of the random values

• max – Upper boundary of the interval of the random values

Returns:

A new uniform random distribution in the interval [min, max)

virtual RNGPoolElement *getThreadRandomSource() override

Gets the random source associated to the current thread

Returns:

A random source, which is associated to the current thread

virtual RNGPoolElement *getRandomSource(std::size_t index) override

Gets the random source associated to a thread, specified by an index

Parameters:

index – The index of the random source

Returns:

A random source, which is associated the specified thread

class RNGPoolElement : public Core::RandomSource

Public Functions

RNGPoolElement() = default

void seed(rndBit_type seed)

Sets the random seed of the random generator pool element

virtual double uniformRealRndValue() override

Get uniformly distributed random value

Returns:

random value, uniformly distrbuted in the interval [0, 1)

virtual double normalRealRndValue() override

Get normal distributed random value

Returns:

random value, normally distributed

virtual MersenneBitSource *getRandomBitSource() override

Gets the random bit source of this random source

Returns:

A random bit source, based on the mersenne twister

class TestRandomGeneratorPool : public Core::AbstractRandomGeneratorPool

Pool of “random” sources, with test random sources and test distributions which produce short, predifined sequences of values / bits.

Public Functions

TestRandomGeneratorPool() = default

virtual void setSeedForElements(rndBit_type newSeed) override

Sets new random seed (currently not implemented, does nothing!)

virtual RndDistPtr getUniformDistribution(double min, double max) override

Get a new uniform test distribution in the interval [min, max).

Parameters:

• min – Lower boundary of the interval of the random values

• max – Upper boundary of the interval of the random values

Returns:

A new uniform test distribution in the interval [min, max)

virtual TestRNGPoolElement *getThreadRandomSource() override

Gets a test random source for the current thread

Returns:

Test random source

virtual TestRNGPoolElement *getRandomSource(std::size_t index) override

Gets a test random source for a specified thread

Returns:

Test random source

class TestRNGPoolElement : public Core::RandomSource

Public Functions

TestRNGPoolElement() = default

virtual double uniformRealRndValue() override

Get uniformly distributed test value from a short list of predefined, uniformly distributed values

Returns:

test value, uniformly distributed in the interval [0, 1)

virtual double normalRealRndValue() override

Get normal distributed test value from a short list of predefined, normally distrbuted values

Returns:

test value, normally distributed

virtual TestBitSource *getRandomBitSource() override

Gets the test bit source of this test random source

Returns:

A random bit source, based on the mersenne twister

Random distributions

The random generators can return random distributions, which generates random variables with a defined statistical distribution:

class RandomDistribution

Random distribution which produces random samples with a specific distribution

Subclassed by Core::NormalTestDistribution, Core::NormalTestDistributionXoshiro, Core::UniformRandomDistribution, Core::UniformTestDistribution, Core::UniformTestDistributionXoshiro

Public Functions

virtual double rndValue() = 0

virtual ~RandomDistribution() = default

class UniformRandomDistribution : public Core::RandomDistribution

Uniform random distribution, which generates random samples in a specified interval

Public Functions

UniformRandomDistribution(double min, double max, RandomBitSource<rndBit_type> *randomSource)

Construct a custom uniform random distribution with a custom interval

Parameters:

• min – lower boundary of the interval

• max – upper boundary of the interval

virtual double rndValue() override

Generate random value in the uniform distribution

Returns:

uniformly distributed random value

Test distributions

Similarly to the test random generator, there are test random distributions which generate a small, predictable sequence of pre calculated values for testing purposes:

class UniformTestDistribution : public Core::RandomDistribution

A uniform distribution, which generates non random test samples in a specified interval. The samples are sequentially chosen from a small set of predetermined test values

Public Functions

UniformTestDistribution() = default

UniformTestDistribution(double min, double max)

Construct a custom test distribution with a custom interval

Parameters:

• min – lower boundary of the interval

• max – upper boundary of the interval

virtual double rndValue() override

Generate non random test value in the uniform distribution

Returns:

uniformly distributed test value

class NormalTestDistribution : public Core::RandomDistribution

Test random distribution which non random samples which are gaussian normal distributed (with mu=0.0 and sigma=1.0). The samples are sequentially chosen from a small set of predetermined test values

Public Functions

NormalTestDistribution()

Construct normal test distribution

virtual double rndValue() override

Generate normal test value

Returns:

non random normal distributed test value

Physical Constants

Core_constants.hpp defines a set of physical constants widely used across IDSimF:

namespace Core

Variables

constexpr double ELEMENTARY_CHARGE = 1.60217e-19

Elementary charge (Coulomb)

constexpr double EPSILON_0 = 8.854e-12

Vacuum permittivity (Farad / m)

constexpr double ELECTRIC_CONSTANT = (4.0 * M_PI * EPSILON_0)

Electrical constant.

constexpr double AMU_TO_KG = 1.66048e-27

(kg/amu) conversion factor

constexpr double K_BOLTZMANN = 1.3806505e-23

Boltzmann constant (J/K)

constexpr double RGas = 8.3145

Ideal gas constant (J/(mol*K))

constexpr double JOULE_TO_EV = 6.2415095e+18

(eV/J) conversion factor

constexpr double N_AVOGADRO = 6.02214199e23

Avogadro’s number.

constexpr double MOL_VOLUME = 22.413996e-3

constexpr double PI_2 = 2.0 * M_PI

Math Functions

Core_math.hpp defines a set of general mathematical functions used elsewhere in the framework

double Core::degToRad(double phi)

Convert from degrees to radians

double Core::radToDeg(double phi)

Convert from radians to degrees

Core::Vector Core::cartesianToPolar(Core::Vector vec)

Convert a cartesian vector ‘vec’ to polar coordinates (coordinate system convention is y upwards)

Returns:

A three dimensional vector with the elements {radius, azimuth, elevation}

Core::Vector Core::elevationRotate(Core::Vector vec, double angle)

Rotates a vector ‘vec’ an ‘angle’ around the elevation axis (which is the z axis in cartesian coordinates)

Core::Vector Core::azimuthRotate(Core::Vector vec, double angle)

Rotates a vector ‘vec’ an ‘angle’ around the azimuth axis (which is the y axis in cartesian coordinates)