Module: RS - Reaction Simulation

Particle based modeling of chemical kinetics and reaction dynamics of charged particles.

Base Classes / Simulation System

class Simulation

Public Types

using index_t = std::size_t

using particleReactedFctType = std::function<void(RS::ReactiveParticle *particle)>

using reactionConditionFctType = std::function<ReactionConditions(RS::ReactiveParticle *particle, double time)>

Public Functions

explicit Simulation(const std::string &configFileName)

Constructs a RS Simulation with a simulation configuration given by a simulation configuration file

explicit Simulation(std::unique_ptr<RS::SimulationConfiguration> simConf)

Constructs a RS Simulation with a given simulation configuration

SimulationConfiguration *simulationConfiguration() const

bool addParticle(RS::ReactiveParticle *particle, index_t index)

void removeParticle(index_t index)

ReactiveParticle &getParticle(index_t index) const

std::map<Substance*const, int> discreteConcentrations() const

long totalReactionEvents() const

long illEvents() const

long reactionEvents(AbstractReaction *reaction) const

void performTimestep(ReactionConditions &conditions, double dt, const particleReactedFctType &particleReactedFct = nullptr)

Performs a time step with static reaction conditions (same reaction conditions for all particles)

Parameters:

• conditions – The reaction conditions for the time step

• dt – The time step length

• particleReactedFct – An optional function, which is performed for the particles which have reacted

void performTimestep(const reactionConditionFctType &conditionFct, double dt, const particleReactedFctType &particleReactedFct = nullptr)

Performs a time step with variable reaction conditions for the individual particles, defined by a function. The function takes individual particles and the time at time step begin as parameters.

Parameters:

• conditionFct – A function which generates individual reaction conditions for the particles

• dt – The time step length

• particleReactedFct – An optional function, which is performed for the particles which have reacted

void doReaction(RS::AbstractReaction *reaction, RS::ReactiveParticle *particle, RS::Substance *product)

Actually perform a reaction: The particle with index “index” is changed into the product species

Parameters:

• particle – the particle to react

• product – the new chemical species for this particle

bool react(index_t index, ReactionConditions &conditions, double dt)

Let a particle react: The independent reactions of that particle are tested if they occur, if one reaction occurs, that reaction is performed

Parameters:

• index – the index of the particle to react

• conditions – the parameters present while the reaction occurs

• dt – the time step length

Returns:

true if a reaction had occurred

bool collisionReact(index_t index, RS::Substance *reactionPartnerSpecies, CollisionConditions &conditions)

void advanceTimestep(double dt)

int timestep() const

double simulationTime() const

void printConcentrations() const

void printReactionStatistics() const

void logConcentrations(std::shared_ptr<spdlog::logger> &logger) const

void logReactionStatistics(std::shared_ptr<spdlog::logger> &logger) const

Friends

friend std::ostream &operator<<(std::ostream &os, const RS::Simulation &sim)

class SimulationConfiguration

Public Functions

bool addSubstance(std::unique_ptr<Substance> &subst)

Substance *substance(std::size_t index) const

Substance *substanceByName(std::string substanceName) const

std::vector<Substance*> getAllSubstances() const

std::vector<Substance*> getAllDiscreteSubstances() const

bool addReaction(std::unique_ptr<AbstractReaction> &reac)

AbstractReaction *reaction(std::size_t index) const

std::vector<AbstractReaction*> getAllReactions() const

void updateConfiguration()

class ReactiveParticle : public Core::Particle

A reactive particle: A particle (most probably ionic) which is able to react in a chemical reaction

Public Functions

explicit ReactiveParticle(Substance *species)

ReactiveParticle(Substance *species, Core::Vector location)

ReactiveParticle(Substance *species, Core::Vector location, double charge)

void setSpecies(Substance *species)

Sets a new species for the reactive particle

Warning: This sets the low field mobility and the actual current mobility to the low field mobility of the species

Substance *getSpecies() const

Friends

friend std::ostream &operator<<(std::ostream &os, const RS::ReactiveParticle &particle)

Reactions

RS provides different reaction types. Each reaction type is a subclass of RS::AbstractReaction

class AbstractReaction

An abstract chemical (elementary) reaction, base class for chemical reactions. It has educts and products and can calculate somehow a reaction rate / rate constant (the details are implemented in the non virtual / non abstract derived classes of this abstract base class).

This class is intended to model elementary reactions, thus all stochiometric factors are integer values.

The chemical substances are stored as pointers to Substances, thus all the comparisons and equality checks in this class are based on the address identity of a substance.

Subclassed by RS::FieldDependentVantHoffReaction, RS::SimpleCollisionStepReaction, RS::StaticReaction, RS::StaticThermalizingReaction, RS::VantHoffReaction

Public Functions

AbstractReaction(std::map<Substance*, int> educts, std::map<Substance*, int> products, bool isCollisionReaction, std::string typeLabel, std::string label)

The default constructor of an abstract reaction

Parameters:

• educts – a map of references / pointers to the educt Substances and their stociometric factors

• products – a map of references / pointers to the product substances and their stochiometric factors

• label – a textual label of this reaction (which is also used for equality checks)

virtual ~AbstractReaction() = default

std::string getLabel() const

Gets the textual label from this reaction

Returns:

the text label of this reaction

std::string getTypeLabel() const

Gets the textual type label from this reaction which identifies the type of this reaction

Returns:

the type text label of this reaction

bool generateRandomDecision(double probability) const

Generate a random decision: The result is true with the given probability

Parameters:

probability – the probabilty for the result to be true

Returns:

the random decision

virtual ReactionEvent attemptReaction(ReactionConditions conditions, ReactiveParticle *particle, double dt) const = 0

virtual ReactionEvent attemptReaction(CollisionConditions conditions, ReactiveParticle *particle) const = 0

bool isIndependent() const

Independent reactions are dependent on only one discrete educt / substance modeled in terms of discrete particles

Returns:

if this reaction is independent

bool isCollisionReaction() const

Collision reactions are reactions which are modeled by individual collision events of an external particle tracing model which is not part of RS instead of an averaged approach where the reaction probability is calculated by the timestep length.

Returns:

if this reactiion is a collision based reaction

double staticReactionConcentration() const

The static probability is the product of all concentrations of isotropic / static educt species for this reaction.

Returns:

the static reaction probability of this reaction

void updateStaticReactionConcentration()

Updates / reacalculates the product of static reaction partner concentrations of this reaction from the current concentrations of the isotropic / static educts.

const std::map<Substance*, int> *products() const

Gets the product substance map of this reaction.

Returns:

the map of products with their stociometric factors

const std::map<Substance*, int> *educts() const

Gets the educt substance map of this reaction.

Returns:

the map of educts with their stociometric factors

const std::map<Substance*, int> *discreteProducts() const

Gets the substance map of all discrete products.

Returns:

the map of discrete (modeled in terms of discrete particles) substances

const std::map<Substance*, int> *discreteEducts() const

Gets the substance map of all discrete educts.

Returns:

the map of discrete (modeled in terms of discrete particles) educts

Friends

friend std::ostream &operator<<(std::ostream &os, const RS::AbstractReaction &reac)

Output stream operator

Parameters:

• os – an output stream

• reac – a chemical reaction

Returns:

the modified output stream (for chaining)

class StaticReaction : public RS::AbstractReaction

Public Functions

StaticReaction(const std::map<Substance*, int> &educts, const std::map<Substance*, int> &products, double rateConstant, std::string label)

virtual RS::ReactionEvent attemptReaction(ReactionConditions conditions, ReactiveParticle *particle, double dt) const override

virtual RS::ReactionEvent attemptReaction(CollisionConditions conditions, ReactiveParticle *particle) const override

class StaticThermalizingReaction : public RS::AbstractReaction

Public Functions

StaticThermalizingReaction(const std::map<Substance*, int> &educts, const std::map<Substance*, int> &products, double rateConstant, std::string label)

virtual RS::ReactionEvent attemptReaction(ReactionConditions conditions, ReactiveParticle *particle, double dt) const override

virtual RS::ReactionEvent attemptReaction(CollisionConditions conditions, ReactiveParticle *particle) const override

class SimpleCollisionStepReaction : public RS::AbstractReaction

Public Functions

SimpleCollisionStepReaction(const std::map<Substance*, int> &educts, const std::map<Substance*, int> &products, double activationEnergy_eV, std::string label)

virtual RS::ReactionEvent attemptReaction(ReactionConditions conditions, ReactiveParticle *particle, double dt) const override

virtual RS::ReactionEvent attemptReaction(CollisionConditions conditions, ReactiveParticle *particle) const override

class VantHoffReaction : public RS::AbstractReaction

Public Functions

VantHoffReaction(const std::map<Substance*, int> &educts, const std::map<Substance*, int> &products, double H_R, double K_s, double k_backward, std::string label)

virtual RS::ReactionEvent attemptReaction(ReactionConditions conditions, ReactiveParticle *particle, double dt) const override

virtual RS::ReactionEvent attemptReaction(CollisionConditions conditions, ReactiveParticle *particle) const override

class FieldDependentVantHoffReaction : public RS::AbstractReaction

A field dependent van’t Hoff reaction.

This class represents a van’t Hoff style reaction of an ion where the forward reaction rate is calculated from thermophysical parameters (reaction enthalpy and equilibrium constant) of the equilibrium between the forward and backward reaction and the effective ion temperature.

The effective ion temperature is calculated from the ion mobility (at standard conditions), the molecular mass of the backgorund gas and the local background temperature and pressure.

Public Functions

FieldDependentVantHoffReaction(const std::map<Substance*, int> &educts, const std::map<Substance*, int> &products, double H_R, double K_s, double kBackward, double electricMobility, double energyLossRatio, double collisionGasMassAmu, std::string label)

Default constructor: Constructs and initialized the reaction

Parameters:

• educts – Map of educt species

• products – Map of product species

• H_R – the forward reaction enthalpy of this reaction

• K_s – the equilibrium constant between forward and backward reaction rate

• kBackward – the backward reaction rate (reaction rate of the background reaction)

• electricMobility – the electrical mobility of the ionic educt (in SI units, pressure is in Pa) at standard conditions (101325 Pa and 271.15 K)

• energyLossRatio –

• collisionGasMassAmu – the molecular mass of the background gas particles (in AMU)

• label – a texutal label to identify the reaction

virtual RS::ReactionEvent attemptReaction(ReactionConditions conditions, ReactiveParticle *particle, double dt) const override

virtual RS::ReactionEvent attemptReaction(CollisionConditions conditions, ReactiveParticle *particle) const override

Data Import / Export

class ConfigFileParser

Public Functions

std::pair<std::vector<std::string>, std::vector<std::string>> splitString(std::string str, const std::string &patterntxt) const

std::unique_ptr<SimulationConfiguration> parseText(const std::string &confStr) const

std::unique_ptr<SimulationConfiguration> parseFile(const std::string &filename) const

std::unique_ptr<SimulationConfiguration> getTestConfigWaterClusters() const

Returns:

std::unique_ptr<SimulationConfiguration> getTestConfigSimple() const

Returns:

class ConcentrationFileWriter

Public Functions

explicit ConcentrationFileWriter(std::string transientFilename)

void initFile(SimulationConfiguration *simConf)

void closeFile()

void writeTimestep(Simulation &sim)

void writeReactionStatistics(Simulation &sim)

Utilities

RS_util.hpp / .cpp bundles a set of utility functions in the RS::util namespace:

namespace util

Functions

Core::Vector maxwellBoltzmannRandomVelocity(double temperature_K, double gasParticleMass_amu)

Generates a Maxwell Boltzmann distributed random velocity sample for a given temperature and particle mass

Parameters:

• temperature_K – the temperature of the gas

• gasParticleMass_amu – the gas particle mass in amu

Returns:

a random sampled velocity vector

RS_constants.hpp bundles a set of constants:

namespace RS

Variables

const double T_STANDARD = 298.15

the standard temperature (K)

const double K_BOLTZMANN = 1.3806505e-23

const double R_GAS = 8.3145

const double KG_PER_AMU = 1.66053873e-27