# YMeRo coordinator¶

The coordinator class stitches together data containers, Particle Vectors, and all the handlers, and provides functions to manipulate the system components.

One and only one instance of this class should be created in the beginning of any simulation setup.

Note

Creating the coordinator will internally call MPI_Init() function, and its destruction will call MPI_Finalize(). Therefore if using a mpi4py Python module, it should be imported in the following way:

import  mpi4py
mpi4py.rc(initialize=False, finalize=False)
from mpi4py import MPI

class ymero

Main coordination class, should only be one instance at a time

Methods

 __init__(*args, **kwargs) Overloaded function. applyObjectBelongingChecker(checker, pv, …) Apply the checker to the given particle vector. computeVolumeInsideWalls(walls, nSamplesPerRank) Compute the volume inside the given walls in the whole domain (negative values are the ‘inside’ of the simulation). dumpWalls2XDMF(walls, h, float, float], filename) Write Signed Distance Function for the intersection of the provided walls (negative values are the ‘inside’ of the simulation) getState(self) Return ymero state isComputeTask(self) Returns whether current rank will do compute or postrprocess isMasterTask(self) Returns whether current task is the very first one makeFrozenRigidParticles(checker, shape, …) Create particles frozen inside object. makeFrozenWallParticles(pvName, walls, …) Create particles frozen inside the walls. registerBouncer(arg0) Register Object Bouncer registerIntegrator(arg0) Register Integrator registerInteraction(arg0) Register Interaction registerObjectBelongingChecker(checker, ov) Register Object Belonging Checker registerParticleVector(pv, ic, checkpoint_every) Register particle vector registerPlugins(arg0, arg1) Register Plugins registerWall(wall, check_every) Register Wall restart(arg0) Restart the simulation run(arg0) Run the simulation save_dependency_graph_graphml(arg0) Exports GraphML file with task graph for the current simulation time-step setBouncer(arg0, arg1, arg2) Set Bouncer setIntegrator(arg0, arg1) Set Integrator setInteraction(interaction, pv1, pv2) Forces between two Particle Vectors (they can be the same) name1 and name2 will be computed according to the defined interaction. setWall(arg0, arg1) Set Wall start_profiler(self) Tells nvprof to start recording timeline stop_profiler(self) Tells nvprof to stop recording timeline
__init__(*args, **kwargs)

1. __init__(nranks: Tuple[int, int, int], domain: Tuple[float, float, float], dt: float, log_filename: str = ‘log’, debug_level: int = 3, checkpoint_every: int = 0, restart_folder: str = ‘restart/’, cuda_aware_mpi: bool = False, no_splash: bool = False) -> None

Args:
nranks:

number of MPI simulation tasks per axis: x,y,z. If postprocess is enabled, the same number of the postprocess tasks will be running

domain:

size of the simulation domain in x,y,z. Periodic boundary conditions are applied at the domain boundaries. The domain will be split in equal chunks between the MPI ranks. The largest chunk size that a single MPI rank can have depends on the total number of particles, handlers and hardware, and is typically about $$120^3 - 200^3$$.

dt:

timestep of the simulation

log_filename:

prefix of the log files that will be created. Logging is implemented in the form of one file per MPI rank, so in the simulation folder NP files with names log_00000.log, log_00001.log, … will be created, where NP is the total number of MPI ranks. Each MPI task (including postprocess) writes messages about itself into his own log file, and the combined log may be created by merging all the individual ones and sorting with respect to time. If this parameter is set to ‘stdout’ or ‘stderr’ standard output or standard error streams will be used instead of the file, however, there is no guarantee that messages from different ranks are synchronized

debug_level:

Debug level varies from 1 to 8:

1. only report fatal errors
2. report serious errors
3. report warnings (this is the default level)
4. report not critical information
5. report some debug information
6. report more debug
7. report all the debug
8. force flushing to the file after each message

Debug levels above 4 or 5 may significanlty increase the runtime, they are only recommended to debug errors. Flushing increases the runtime yet more, but it is required in order not to lose any messages in case of abnormal program abort.

checkpoint_every:

save state of the simulation components (particle vectors and handlers like integrators, plugins, etc.)

restart_folder:

folder where the checkpoint files will reside

cuda_aware_mpi: enable CUDA Aware MPI (GPU RDMA). As of now it may crash, or may yield slower execution. no_splash: Don’t display the splash screen when at the start-up.

2. __init__(commPtr: int, nranks: Tuple[int, int, int], domain: Tuple[float, float, float], dt: float, log_filename: str = ‘log’, debug_level: int = 3, checkpoint_every: int = 0, restart_folder: str = ‘restart/’, cuda_aware_mpi: bool = False) -> None

Args:

commPtr: pointer to communicator

applyObjectBelongingChecker(checker: ObjectBelongingChecker, pv: ParticleVector, correct_every: int = 0, inside: str = '', outside: str = '', checkpoint_every: int = 0) → ParticleVector

Apply the checker to the given particle vector. One and only one of the options inside or outside has to be specified.

Parameters: checker – instance of BelongingChecker pv – ParticleVector that will be split (source PV) inside – if specified and not “none”, a new ParticleVector with name inside will be returned, that will keep the inner particles of the source PV. If set to “none”, None object will be returned. In any case, the source PV will only contain the outer particles outside – if specified and not “none”, a new ParticleVector with name outside will be returned, that will keep the outer particles of the source PV. If set to “none”, None object will be returned. In any case, the source PV will only contain the inner particles correct_every – If greater than zero, perform correction every this many time-steps. Correction will move e.g. inner particles of outer PV to the :inner PV and viceversa. If one of the PVs was defined as “none”, the ‘wrong’ particles will be just removed. checkpoint_every – every that many timesteps the state of the newly created ParticleVector (if any) will be saved to disk into the ./restart/ folder. Default value of 0 means no checkpoint. New ParticleVector or None depending on inside and outside options
computeVolumeInsideWalls(walls: List[Wall], nSamplesPerRank: int = 100000) → float

Compute the volume inside the given walls in the whole domain (negative values are the ‘inside’ of the simulation). The computation is made via simple Monte-Carlo.

Parameters: walls – sdf based walls nSamplesPerRank – number of Monte-Carlo samples used per rank
dumpWalls2XDMF(walls: List[Wall], h: Tuple[float, float, float], filename: str = 'xdmf/wall') → None

Write Signed Distance Function for the intersection of the provided walls (negative values are the ‘inside’ of the simulation)

Parameters: h – cell-size of the resulting grid
getState(self: ymero) → YmrState

Return ymero state

isComputeTask(self: ymero) → bool

Returns whether current rank will do compute or postrprocess

isMasterTask(self: ymero) → bool

Returns whether current task is the very first one

makeFrozenRigidParticles(checker: ObjectBelongingChecker, shape: ObjectVector, icShape: InitialConditions, interactions: List[Interaction], integrator: Integrator, density: float, nsteps: int = 1000) → ParticleVector

Create particles frozen inside object.

Note

A separate simulation will be run for every call to this function, which may take certain amount of time. If you want to save time, consider using restarting mechanism instead

Parameters: checker – object belonging checker shape – object vector describing the shape of the rigid object icShape – initial conditions for shape interactions – list of Interaction that will be used to construct the equilibrium particles distribution integrator – this Integrator will be used to construct the equilibrium particles distribution density – target particle density nsteps – run this many steps to achieve equilibrium New ParticleVector that will contain particles that are close to the wall boundary, but still inside the wall.
makeFrozenWallParticles(pvName: str, walls: List[Wall], interactions: List[Interaction], integrator: Integrator, density: float, nsteps: int = 1000) → ParticleVector

Create particles frozen inside the walls.

Note

A separate simulation will be run for every call to this function, which may take certain amount of time. If you want to save time, consider using restarting mechanism instead

Parameters: pvName – name of the created particle vector walls – array of instances of Wall for which the frozen particles will be generated interactions – list of Interaction that will be used to construct the equilibrium particles distribution integrator – this Integrator will be used to construct the equilibrium particles distribution density – target particle density nsteps – run this many steps to achieve equilibrium New ParticleVector that will contain particles that are close to the wall boundary, but still inside the wall.
registerBouncer(arg0: Bouncer) → None

Register Object Bouncer

registerIntegrator(arg0: Integrator) → None

Register Integrator

registerInteraction(arg0: Interaction) → None

Register Interaction

registerObjectBelongingChecker(checker: ObjectBelongingChecker, ov: ObjectVector) → None

Register Object Belonging Checker

Parameters: checker – instance of BelongingChecker ov – ObjectVector belonging to which the checker will check
registerParticleVector(pv: ParticleVector, ic: InitialConditions = None, checkpoint_every: int = 0) → None

Register particle vector

Parameters: pv – ParticleVector ic – InitialConditions that will generate the initial distibution of the particles checkpoint_every – every that many timesteps the state of the Particle Vector across all the MPI processes will be saved to disk into the ./restart/ folder. The checkpoint files may be used to restart the whole simulation or only some individual PVs from the saved states. Default value of 0 means no checkpoint.
registerPlugins(arg0: SimulationPlugin, arg1: PostprocessPlugin) → None

Register Plugins

registerWall(wall: Wall, check_every: int = 0) → None

Register Wall

restart(arg0: str) → None

Restart the simulation

run(arg0: int) → None

Run the simulation

save_dependency_graph_graphml(arg0: str) → None

Exports GraphML file with task graph for the current simulation time-step

setBouncer(arg0: Bouncer, arg1: ObjectVector, arg2: ParticleVector) → None

Set Bouncer

setIntegrator(arg0: Integrator, arg1: ParticleVector) → None

Set Integrator

setInteraction(interaction: Interaction, pv1: ParticleVector, pv2: ParticleVector) → None

Forces between two Particle Vectors (they can be the same) name1 and name2 will be computed according to the defined interaction.

setWall(arg0: Wall, arg1: ParticleVector) → None

Set Wall

start_profiler(self: ymero) → None

Tells nvprof to start recording timeline

stop_profiler(self: ymero) → None

Tells nvprof to stop recording timeline