PyRID: A Brownian dynamics simulator for reacting and interacting particles written in Python.

Disclaimer: PyRID is currently in early state development (version 0.1). As such, there is no guaranty that any of the functions are bug free. Careful validation of any results is recommended.

PyRID is a tool for particle based reaction diffusion simulations and is highly influenced and inspired by

• ReaDDy

• MCell

• Sarkas

PyRID is an attempt to combine several features of the above mentioned tools, which include

• unimolecular and bimolecular Reactions (ReaDDy, MCell)

• pair-interactions (ReaDDy)

• mesh based compartments and surface diffusion (MCell)

• pure Python implementation (Sarkas)

Introduction

Several tools have been developed that target the simulation of cell biological processes. MCell and Smoldyn, e.g., are popular representatives of the category of particle-based reaction diffusion simulators. Both are powerful tools but cannot simulate particle-particle interactions. Another tool, ReaDDy, has also been developed to fill the gap between classical molecular dynamics and particle-based reaction-diffusion simulations and allows for reactions and interactions between particles. So why do we need PyRID then? While ReaDDy combines some of the features of MCell, Smoldyn, and classical MD, some features are missing.

1. PyRID supports triangulated mesh geometries, whereas ReaDDy only supports spherical or box-shaped compartments via external potentials. While these two shapes are sufficient in some situations, they are not in others where we want to, e.g., combine compartments to investigate narrow escape properties or where we are interested in the effect of more complex shapes on molecule dynamics.

2. PyRID supports rigid bead models of molecules. Rigid bead models are a method of minimal coarse-graining that have some essential benefits. A rigid bead topology replaces strong, short ranged interactions between atoms. Thereby, integration time steps can be several orders larger than in atomic-scale simulations. Usually, the beads of a rigid bead model do not represent single atoms but pattern the geometry of the molecule of interest [1], significantly reducing the number of particles that need to be simulated. In addition, experimentally or theoretically estimated diffusion tensors can be used to describe the diffusive motion of molecules accurately. Importantly, patches on the bead model surface can describe multivalent protein-protein interactions.

3. PyRID accounts for polydispersity of particle sizes. Polydispersity, however, becomes a critical performance issue if we would like to simulate proteins of very different sizes or even proteins in the presence of large diffusing structures such as synaptic vesicles. PyRID uses a hierarchical grid data structure such that polydisperse systems can be simulated with basically no performance loss.

4. PyRID supports fixed concentration boundary conditions. These can be useful if we would like to simulate sub-regions within a larger system. PyRID supports fixed concentration boundaries for volume and surface molecules and even supports the overlap of mesh compartments with the simulation box boundary.

5. PyRID supports simulations in the NPT ensemble using the Berendsen barostat.

6. PyRID can be modified and expanded reasonably easily by anyone with solid knowledge of the Python programming language. Also, by using technologies such as Cython, PyPy, and Numba, Python can reach up to C speed! Using Numba, the MD tool Sarkas has shown that Python is even suited to do molecular dynamics simulations, although still limited to a single core and single thread computation! Inspired by Sarkas, PyRID is also solely written in Python by extensively using Numbas jit compilation. Thereby, PyRID can achieve comparable performance to that of ReaDDy. In addition, PyRID is lightweight, with the core modules having less than 10.000 lines of code (excluding documentation).

Feature comparison

Please note that this feature comparison is not complete and biased towards PyRID as only the main features of PyRID are compared to the other tools. Each of the tools mentioned here have some unique abilities and features that are not necessarily supported by the other tools/PyRID. However, to do an all-encompassing comparison would go beyond the scope of this documentation.

Table 1 Feature comparison

Features	PyRID	ReaDDy	MCell	Smoldyn
Reactions	Very Good (zeroth order, unimolecular, bimolecular, arbitrary number of products, compartment specific, different reaction paths)	Good	Excellent (Integration with BioNetGen)	Excellent (Integration with BioNetGen)
Reaction accuracy	Volume: Good (Not exact close to boundary, reversible fusion reactions of interacting particles do not obey detailed balance) Surface: Good (euclidian distance only)	Volume: Very Good (Not exact close to boundary, reversible fusion reactions obey detailed balance) Surface: Good (euclidian distance only)	Volume: Very Good, Surface: Very Good	Volume: Very Good, Surface: Very Good
Diffusion	Anisotropic translational and rotaional diffusion, integrated diffusion tensors calculation	Isotropic translational diffusion	Isotropic translational diffusion	Anisotropic translational diffusion
Molecular structure	Molecules modeled explicitly (by interaction potential and /or rigid bodies).	Molecules modeled explicitly (only by interaction potential).	Indirectly by internal state variables (only point particles).	Indirectly by internal state variables (spherical particle approximation).
Surfaces	Arbitrary surfaces (triangulated mesh, supports obj. format)	Only via external potentials (Box and Sphere)	Arbitrary surfaces triangulated mesh, blender interface)	Arbitrary surfaces (6 elementary shapes, custom format)
Interactions	Selection of several pair-potentials, custom potentials can be added easily.	Selection of 4 potentials, custom potentials require altering C++ source code.	No Interactions	/ Excluded volume approximation for spheres.
Boundary Conditions	Periodic, Repulsive, Fixed concentration	Periodic, Repulsive	Periodic, Repulsive, Fixed concentration	Periodic, Repulsive, Fixed concentration
Polydispersity	Efficient simulation of polydisperse system by the use of a hierarchical grid data structure	Polydisperse systems result in performance drop.	Does not apply	Does not apply
API	Python	Python	Blender GUI, Python	Python, Text based
Modifiability	Excellent (All source code in Python, little dependencies)	Ok (Requires changing C++ source code)	Ok (Requires changing C++ source code)	Ok (Requires changing C++ source code, Libsmoldyn API)

Contents

Users

• Installation
• User Guide
  • Simulation setup
  • Molecules
  • Interaction potentials
  • Reactions
  • Compartments
  • Molecule distribution
  • Observables
  • Run simulation
  • Evaluation
  • Blender Add-on
• Examples
  • Large scale toy-model
  • Fixed concentration boundary
  • Dendritic Spine
• Advanced
  • Accessing particle and molecule properties
  • Increasing the maximum molecule size

Developers

• Overview
• Developer API
  • data_structures
    • cell_list_util
    • dynamic_array_util
    • h_grid_util
  • evaluation
    • evaluation_util
    • diffusion_util
    • direct_coexistence_method_util
    • rdf_util
  • geometry
    • intersections_util
    • load_wavefront
    • mesh_util
    • ray_march_util
  • math
    • random_util
    • transform_util
  • molecules
    • particles_util
    • rigidbody_util
    • hydro_util
  • observables
    • checkpoint_util
    • observables_util
    • plot_util
    • write_util
  • reactions
    • reactions_registry_util
    • reactions_util
    • update_reactions
  • system
    • distribute_surface_util
    • distribute_vol_util
    • potentials_util
    • system_util
    • update_force
    • update_pos
  • run
• Theory
  • Introduction
    • The cell environment
    • Modeling approaches
  • Theory and Methods
    • Rigid bead molecules
    • Compartments
    • Boundary Conditions
    • Reactions
    • Potentials
    • Observables
    • Berendsen barostat
    • Distribution of molecules
    • Fast algorithms for Brownian dynamics of reacting and interacting particles
    • Polydispersity
    • Simulation loop
    • Visualization
  • Results and validation
    • Anisotropic diffusion
    • Diffusion tensor of igG3
    • Fixed concentration boundary
    • Choosing the right reaction rate and radius
    • Bi-molecular reactions between rigid bead molecules
    • Reactions between surface molecules
    • Hard sphere fluid
    • LLPs of Patchy Particles
    • Benchmarks
  • Discussion
    • On hydrodynamic interactions
    • Limitations of the Brownian dynamics approach
  • Appendix
    • Appendix A
• Validation
  • Diffusion
  • Hard-Sphere Fluid
  • Reactions
  • LLPS

References

• References

Indices and tables

• Index

• Module Index

• Search Page

Links

• GitHub
• PyPI
• Youtube
• license