Simulation

class Simulation : protected mirheo::MirObject

Manage and combine all MirObject objects to run a simulation.

All MirObject objects must be registered and set before calling run().

This must be instantiated only by ranks that have access to a GPU. Optionally, this class can communicate with a Postprocess one held on a different rank. This option is used for Plugins.

Public Functions

Simulation(const MPI_Comm &cartComm, const MPI_Comm &interComm, MirState *state, CheckpointInfo checkpointInfo, real maxObjHalfLength, bool gpuAwareMPI = false)

Construct an empty Simulation object.

Parameters
  • cartComm: a cartesian communicator that holds all ranks of the simulation.
  • interComm: An inter communicator to communicate with the Postprocess ranks.
  • state: The global state of the simulation. Does not pass ownership.
  • checkpointInfo: Configuration of checkpoint
  • maxObjHalfLength: Half of the maximum length of all objects.
  • gpuAwareMPI: Performance parameter that controls if communication can be performed through RDMA.

void restart(const std::string &folder)

restore the simulation state from a folder that contains all restart files

void checkpoint()

Dump the whole simulation state to the checkpoint folder and advance the checkpoint ID.

void registerParticleVector(std::shared_ptr<ParticleVector> pv, std::shared_ptr<InitialConditions> ic)

register a ParticleVector and initialize it with the gien InitialConditions.

Parameters

void registerWall(std::shared_ptr<Wall> wall, int checkEvery = 0)

register a Wall

Parameters
  • wall: The Wall to register
  • checkEvery: The particles that will bounce against this wall will be checked (inside/outside log info) every this number of time steps. 0 means no check.

void registerInteraction(std::shared_ptr<Interaction> interaction)

register an Interaction

See
setInteraction().
Parameters

void registerIntegrator(std::shared_ptr<Integrator> integrator)

register an Integrator

See
setIntegrator().
Parameters

void registerBouncer(std::shared_ptr<Bouncer> bouncer)

register a Bouncer

See
setBouncer().
Parameters
  • bouncer: the Bouncer to register.

void registerPlugin(std::shared_ptr<SimulationPlugin> plugin, int tag)

register a SimulationPlugin

Note
If there is a Postprocess rank, it might need to register the corrsponding PostprocessPlugin.
Parameters
  • plugin: the SimulationPlugin to register.
  • tag: A unique tag per plugin, used by MPI communications. Must be different for every plugin.

void registerObjectBelongingChecker(std::shared_ptr<ObjectBelongingChecker> checker)

register a ObjectBelongingChecker

See
applyObjectBelongingChecker()
Parameters

void deregisterIntegrator(Integrator *integrator)

deregister an Integrator

See
registerIntegrator().
Parameters

void deregisterPlugin(SimulationPlugin *plugin)

deregister a SimulationPlugin

Note
If there is a Postprocess rank, the corresponding PostprocessPlugin must also be deregistered.
Parameters

void setIntegrator(const std::string &integratorName, const std::string &pvName)

Assign a registered Integrator to a registered ParticleVector.

Parameters
  • integratorName: Name of the registered integrator (will die if it does not exist)
  • pvName: Name of the registered ParticleVector (will die if it does not exist)

void setInteraction(const std::string &interactionName, const std::string &pv1Name, const std::string &pv2Name)

Assign two registered Interaction to two registered ParticleVector objects.

This was designed to handle

PairwiseInteraction, which needs up to two ParticleVector. For self interaction cases (such as MembraneInteraction), pv1Name and pv2Name must be the same.
Parameters
  • interactionName: Name of the registered interaction (will die if it does not exist)
  • pv1Name: Name of the first registered ParticleVector (will die if it does not exist)
  • pv2Name: Name of the second registered ParticleVector (will die if it does not exist)

void setBouncer(const std::string &bouncerName, const std::string &objName, const std::string &pvName)

Assign a registered Bouncer to registered ObjectVector and ParticleVector.

Parameters
  • bouncerName: Name of the registered bouncer (will die if it does not exist)
  • objName: Name of the registered ObjectVector that contains the surface to bounce on (will die if it does not exist)
  • pvName: Name of the registered ParticleVector to bounce (will die if it does not exist)

void setWallBounce(const std::string &wallName, const std::string &pvName, real maximumPartTravel)

Set a registered ParticleVector to bounce on a registered Wall.

Parameters
  • wallName: Name of the registered wall (will die if it does not exist)
  • pvName: Name of the registered ParticleVector (will die if it does not exist)
  • maximumPartTravel: Performance parameter. See Wall for more information.

void setObjectBelongingChecker(const std::string &checkerName, const std::string &objName)

Associate a registered ObjectBelongingChecker to a registered ObjectVector.

Note
this is required before calling applyObjectBelongingChecker()
Parameters

void applyObjectBelongingChecker(const std::string &checkerName, const std::string &source, const std::string &inside, const std::string &outside, int checkEvery)

Enable a registered ObjectBelongingChecker to split particles of a registered ParticleVector.

inside or outside can take the reserved value “none”, in which case the corresponding particles will be deleted. Furthermore, exactly one of inside and outside must be the same as source.

Parameters
  • checkerName: The name of the ObjectBelongingChecker. Must be associated to an ObjectVector with setObjectBelongingChecker() (will die if it does not exist)
  • source: The registered ParticleVector that must be split (will die if it does not exist)
  • inside: Name of the ParticleVector that will contain the particles of source that are inside the objects. See below for more information.
  • outside: Name of the ParticleVector that will contain the particles of source that are outside the objects. See below for more information.
  • checkEvery: The particle split will be performed every this amount of time steps.

If inside or outside has the name of a ParticleVector that is not registered, this call will create an empty ParticleVector with the given name and register it in the Simulation. Otherwise the already registered ParticleVector will be used.

void init()

setup all the simulation tasks from the registered objects and their relation. Must be called after all the register and set methods.

void run(MirState::StepType nsteps)

advance the system for a given number of time steps. Must be called after init()

void notifyPostProcess(int tag, int msg) const

Send a tagged message to the Postprocess rank.

This is useful to pass special messages, e.g. termination or checkpoint.

std::vector<ParticleVector *> getParticleVectors() const

Return
a list of all ParticleVector registered objects

ParticleVector *getPVbyName(const std::string &name) const

Return
ParticleVector with given name if found, nullptr otherwise

ParticleVector *getPVbyNameOrDie(const std::string &name) const

Return
ParticleVector with given name if found, die otherwise

ObjectVector *getOVbyName(const std::string &name) const

Return
ObjectVector with given name if found, nullptr otherwise

ObjectVector *getOVbyNameOrDie(const std::string &name) const

Return
ObjectVector with given name if found, die otherwise

std::shared_ptr<ParticleVector> getSharedPVbyName(const std::string &name) const

Return
ParticleVector with the given name if found, nullptr otherwise

Wall *getWallByNameOrDie(const std::string &name) const

Return
Wall with the given name if found, die otherwise

CellList *gelCellList(ParticleVector *pv) const

This method will die if

pv was not registered
Return
the CellList associated to the given ParticleVector, nullptr if there is none
Parameters

void startProfiler() const

start the cuda profiler; used for nvprof

void stopProfiler() const

end the cuda profiler; used for nvprof

MPI_Comm getCartComm() const

Return
the cartesian communicator of the Simulation

int3 getRank3D() const

Return
the coordinates in the cartesian communicator of the current rank

int3 getNRanks3D() const

Return
the dimensions of the cartesian communicator

real getCurrentDt() const

Return
The current time step

real getCurrentTime() const

Return
The current simulation time

real getMaxEffectiveCutoff() const

This takes into account the intermediate interactions, e.g. in SDPD this will corrspond to the cutoff used for the density + the one from the SDPD kernel. Useful e.g. to decide the widh of frozen particles in walls.

Return
The largest cut-off radius of all “full” force computation.

void dumpDependencyGraphToGraphML(const std::string &fname, bool current) const

dump the task dependency of the simulation in graphML format.

Parameters
  • fname: The file name to dump the graph to (without extension).
  • current: if true, will only dump the current tasks; otherwise, will dump all possible ones.