Narrow Escape Simulator

This is a python 3 library which provides ready-made simulations for determining the average escape time for a Brownian particle out of a container.

This software can be used by anyone wanting to simulate how long a particle under Brownian motion will take to escape from a container with a number of escape pores on it's surface. This was developed with a cellular biology context, however usage in chemistry, physics and animal sciences could easily be imagined. Software is presented as easily modifiable.

Statement of need

Many tutorials, examples and solutions to random walks are widely available. Solutions with boundary conditions are rare, but still given. For the more complex, such as in three dimensions and in specific shapes this is difficult problem with no standard solution.

We provide this library to give a simple protocol for estimating narrow escape problems. By using stochastic simulations results can be quickly found.

In particular, this library is useful for working with specifically, or randomly, placed exit pores with varying sizes and with non-standard shapes ( we provide a cube example).

A note on running

This software can be run on a standard PC, we have tested for both OSX and Linux. However, running large numbers of simulations is best done on high-performance-computing equiment. This package is optimised for larger number of CPUs. Runnining on older/slower hardware may require additional time.

As a command line app

To get results for a model with:

Diffusion coefficient (D) of 400
Volume (v) of 1um^3
Pore area (a) of 0.1
Number of pores (p) of 1
Number of simulations (N) of 10

You can run:

PyEscape -D 400 -v 1 -a 0.1 -p 1 -N 1

For help type:

PyEscape --help

To run as a python package

To get a single simulation result:

from PyEscape.escape_plan import escape
from PyEscape.escape_points import fibonacci_spheres


D = 400
v = 1
p = 1
a = 0.1
dt = 1e-6 # dt approaching 0 will take longer but give more accurate results

pores = fibonacci_spheres(p, v)

res = escape(D, v, a, pores, dt=dt)

print(res)

To get a more accurate value, multiple simulations are required e.g. :

from PyEscape.escape_plan import escape
from PyEscape.escape_points import fibonacci_spheres
import numpy as np

D = 400
v = 1
a = 0.1
p = 1
dt = 1e-6 # dt approaching 0 will take longer but give more accurate results

pores = fibonacci_spheres(p, v)

res = [escape(D, v, a, pores, dt=dt) for i in range(100)]

res_mean = np.mean(res)

print(res_mean)

To extend this further, we much wish to multi-process to speed up simulations: (tqdm is now used to monitor progress, can be removed!)

from PyEscape.escape_plan import escape
from PyEscape.escape_points import fibonacci_spheres
import numpy as np
import multiprocessing
import os
import tqdm

D = 400
v = 1
a = 0.1
p = 1
N = 100
dt = 1e-6 # dt approaching 0 will take longer but give more accurate results
pores = fibonacci_spheres(p, v)


def esc(i):
    res = escape(D, v, a, pores, dt=dt)
    return res


with multiprocessing.Pool(processes=os.cpu_count()) as pool:
    res = list(tqdm.tqdm(pool.imap(esc, np.arange(0, N)), total=N))

res_mean = np.mean(res)

print(res_mean)

Installation

With python 3.6+ clone the repository and run:

pip install .

Alternatively, installing locally:

pip install . --user

To run tests you will require pytest and the pytest-timeout module:

pip install pytest pytest-timeout
pytest

Contributions

Any and all suggestions for improvements and feature additions are welcome. We ask that new features be requested with specific data, test case scenarios and desired outputs. Python code submitted for pull requests should be appropriately formatted to a PEP8 standard.

Bug reports and other issues can be made through the issues report feature of github.

Requests for collboration, or research based questions can be made to Aoife.Hughes@jic.ac.uk

Acknowledgements

We thank Prof. Richard Morris for supervising and providing instrumental advice in the development of this research, Dr. Melissa Tomkins for help, advice and problem solving and BBSRC + Norwich Research Park Doctoral Training Programme for their funding and support.

borisbolliet/PyEscape