Skip to main content

Phoresis and Stokesian hydrodynamics in Python

Project description


PyStokes: phoresis and Stokesian hydrodynamics in Python Binder Installation Notebooks Documentation Status DOI PyPI Python Version Downloads

About | Blog | News | Installation | Documentation | Examples | Publications | Gallery | Support | License


PyStokes is a numerical library for phoresis and Stokesian hydrodynamics in Python. It uses a grid-free method, combining the integral representation of Laplace and Stokes equations, spectral expansion, and Galerkin discretization, to compute phoretic and hydrodynamic interactions between spheres with slip boundary conditions on their surfaces. The library also computes suspension scale quantities, such as rheological response, energy dissipation and fluid flow. The computational cost is quadratic in the number of particles and upto 1e5 particles have been accommodated on multicore computers. The library has been used to model suspensions of microorganisms, synthetic autophoretic particles and self-propelling droplets.

Please read the PyStokes paper and Wiki before you use PyStokes for your research. Included below are some examples from PyStokes Gallery:

Periodic orbits of active particles


Our work shows that the oscillatory dynamics of a pair of active particles near a boundary, best exemplified by the fascinating dance of the green algae Volvox, can be understood in terms of Hamiltonian mechanics, even though the system does not conserve energy. Read more in the PyStokes Gallery.

Crystallization at a plane no-slip surface

It is well-known that crystallization of colloids approximating hard spheres is due, paradoxically, to the higher entropy of the ordered crystalline state compared to that of the disordered liquid state. Out of equilibrium, no such general principle is available to rationalize crystallization. In this work, we identify a new non-equilibrium mechanism, associated with entropy production rather than entropy gain, which drives crystallization of active colloids near plane walls. Read more in the PyStokes Gallery.

Crystallization of active colloids


26th July 2019 -- PyStokes can compute hydrodynamic and phoretic interactions in autophoretic suspensions.


You can take PyStokes for a spin without installation: Binder. Please be patient while Binder loads.

From a checkout of this repo

Install PyStokes and an extended list of dependencies using

>> git clone
>> cd pystokes
>> pip install -r requirements.txt
>> python install

Install PyStokes and its dependencies in an environment named "pystokes" via Anaconda

>> git clone
>> cd pystokes
>> make env
>> conda activate pystokes
>> make

Via pip

Install the latest PyPI version

>> pip install pystokes


Test installation and running

>> cd tests
>> python

Long test of example notebooks

>> cd tests
>> python


# Example 1: Flow field due to $2s$ mode of active slip
import pystokes, numpy as np, matplotlib.pyplot as plt

# particle radius, self-propulsion speed, number and fluid viscosity
b, eta, Np = 1.0, 1.0/6.0, 1

# initialize
r, p = np.array([0.0, 0.0, 3.4]), np.array([0.0, 1.0, 0])
V2s  = pystokes.utils.irreducibleTensors(2, p)

# space dimension , extent , discretization
dim, L, Ng = 3, 10, 64;

# instantiate the Flow class
flow = pystokes.wallBounded.Flow(radius=b, particles=Np, viscosity=eta, gridpoints=Ng*Ng)

# create grid, evaluate flow and plot
rr, vv = pystokes.utils.gridYZ(dim, L, Ng)
flow.flowField2s(vv, rr, r, V2s)  
pystokes.utils.plotStreamlinesYZsurf(vv, rr, r, offset=6-1, density=1.4, title='2s')
#Example 2: Phoretic field due to active surface flux of l=0 mode
import pystokes, numpy as np, matplotlib.pyplot as plt
# particle radius, fluid viscosity, and number of particles
b, eta, Np = 1.0, 1.0/6.0, 1

r, p = np.array([0.0, 0.0, 5]), np.array([0.0, 0.0, 1])
J0 = np.ones(Np)  # strength of chemical monopolar flux

# space dimension , extent , discretization
dim, L, Ng = 3, 10, 64;

# instantiate the Flow class
phoreticField = pystokes.phoretic.unbounded.Field(radius=b, particles=Np, phoreticConstant=eta, gridpoints=Ng*Ng)

# create grid, evaluate phoretic field and plot
rr, vv = pystokes.utils.gridYZ(dim, L, Ng)
phoreticField.phoreticField0(vv, rr, r, J0)  
pystokes.utils.plotContoursYZ(vv, rr, r, density=.8, offset=1e-16,  title='l=0') 

Other examples include

Selected publications

See full publication list here.


  • For help with and questions about PyStokes, please post to the pystokes-users group.
  • For bug reports and feature requests, please use the issue tracker on GitHub.


We believe that openness and sharing improves the practice of science and increases the reach of its benefits. This code is released under the MIT license. Our choice is guided by the excellent article on Licensing for the scientist-programmer.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pystokes-2.2.6.tar.gz (2.0 MB view hashes)

Uploaded source

Built Distributions

pystokes-2.2.6-py3.9-macosx-11.1-arm64.egg (3.2 MB view hashes)

Uploaded 2 2 6

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page