PyStokes API¶

PyStokes is a numerical library for Phoresis and Stokesian hydrodynamics in Python. It uses a grid-free method, combining the integral representation of Stokes and Laplace 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 see installation instructions and more details in the README.md on GitHub.

API Reference¶

Stokes flow in an unbounded domain¶

Hydrodynamic interactions of active particles in an unbounded domain.

RBM (Rigid Body Motion: Velocity and Angular Velocity)¶

class pystokes.unbounded.Rbm¶

Rigid body motion (RBM) - velocity and angular velocity

Methods in this class update velocities or angular velocities using the inputs of - arrays of positions, velocity or angular velocity, along with an array of forces or torques or a slip mode

The array of velocity or angular velocities is then update by each method.

…

radius: float: Radius of the particles (a).
particles: int: Number of particles (Np)
viscosity: float: Viscosity of the fluid (eta)

mobilityRR()¶

Compute angular velocity due to body torques using $o=\mu^{RR}\cdot T$ …

Parameters:	o (np.array) – An array of angular velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, T (np.array) – An array of forces An array of size 3*Np,

mobilityRT()¶

Compute angular velocity due to body forces using $o=\mu^{RT}\cdot F$ …

Parameters:	o (np.array) – An array of angular velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, F (np.array) – An array of forces An array of size 3*Np,

mobilityTR()¶

Compute velocity due to body torque using $v=\mu^{TR}\cdot T$ …

Parameters:	v (np.array) – An array of velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, T (np.array) – An array of torques An array of size 3*Np,

mobilityTT()¶

Compute velocity due to body forces using $v=\mu^{TT}\cdot F$ …

Parameters:	v (np.array) – An array of velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, F (np.array) – An array of forces An array of size 3*Np,

Examples

An example of the RBM

>>> import pystokes, numpy as np, matplotlib.pyplot as plt
>>> # particle radius, self-propulsion speed, number and fluid viscosity
>>> b, vs, Np, eta = 1.0, 1.0, 128, 0.1

>>> #initialise
>>> r = pystokes.utils.initialCondition(Np)  # initial random distribution of positions
>>> p = np.zeros(3*Np); p[2*Np:3*Np] = -1    # initial orientation of the colloids
>>>
>>> rbm   = pystokes.unbounded.Rbm(radius=b, particles=Np, viscosity=eta)
>>> force = pystokes.forceFields.Forces(particles=Np)
>>>
>>> def rhs(rp):
>>>     # assign fresh values at each time step
>>>     r = rp[0:3*Np];   p = rp[3*Np:6*Np]
>>>     F, v, o = np.zeros(3*Np), np.zeros(3*Np), np.zeros(3*Np)
>>>
>>>     force.lennardJonesWall(F, r, lje=0.01, ljr=5, wlje=1.2, wljr=3.4)
>>>     rbm.mobilityTT(v, r, F)
>>>     return np.concatenate( (v,o) )
>>>
>>> # simulate the resulting system
>>> Tf, Npts = 150, 200
>>> pystokes.utils.simulate(np.concatenate((r,p)),
>>>      Tf,Npts,rhs,integrator='odeint', filename='crystallization')

noiseRR()¶

Compute rotational Brownian motion …

Parameters:	o (np.array) – An array of angular velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np,

noiseTT()¶

Compute translation Brownian motion …

Parameters:	v (np.array) – An array of velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np,

propulsionR2s()¶

Compute angular velocity due to 2s mode of the slip $v=\pi^{R,2s}\cdot S$ …

Parameters:	o (np.array) – An array of angular velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, S (np.array) – An array of 2s mode of the slip An array of size 5*Np,

propulsionR3a()¶

Compute angular velocity due to 3a mode of the slip $v=\pi^{R,3a}\cdot V$ …

Parameters:	o (np.array) – An array of angular velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, V (np.array) – An array of 3a mode of the slip An array of size 5*Np,

propulsionR3s()¶

Compute angular velocity due to 3s mode of the slip $v=\pi^{R,3s}\cdot G$ …

Parameters:	o (np.array) – An array of angular velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, G (np.array) – An array of 3s mode of the slip An array of size 7*Np,

propulsionR4a()¶

Compute angular velocity due to 4a mode of the slip $v=\pi^{R,4a}\cdot M$ …

Parameters:	o (np.array) – An array of angular velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, M (np.array) – An array of 4a mode of the slip An array of size 7*Np,

propulsionT2s()¶

Compute velocity due to 2s mode of the slip $v=\pi^{T,2s}\cdot S$ …

Parameters:	v (np.array) – An array of velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, S (np.array) – An array of 2s mode of the slip An array of size 5*Np,

propulsionT3a()¶

Compute velocity due to 3a mode of the slip $v=\pi^{T,3a}\cdot V$ …

Parameters:	v (np.array) – An array of velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, V (np.array) – An array of 3a mode of the slip An array of size 5*Np,

propulsionT3s()¶

Compute velocity due to 3s mode of the slip $v=\pi^{T,3s}\cdot G$ …

Parameters:	v (np.array) – An array of velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, G (np.array) – An array of 3s mode of the slip An array of size 7*Np,

propulsionT3t()¶

Compute velocity due to 3t mode of the slip $v=\pi^{T,3t}\cdot D$ …

Parameters:	v (np.array) – An array of velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, D (np.array) – An array of 3t mode of the slip An array of size 3*Np,

propulsionT4a()¶

Compute velocity due to 4a mode of the slip $v=\pi^{T,4a}\cdot M$ …

Parameters:	v (np.array) – An array of velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, M (np.array) – An array of 4a mode of the slip An array of size 7*Np,

Flow¶

class pystokes.unbounded.Flow¶

Flow at given points

…

Parameters:	radius (float) – Radius of the particles. particles (int) – Number of particles viscosity (viscosity of the fluid) – gridpoints (int) – Number of grid points

Examples

An example of the RBM

flowField1s()¶

Compute flow field at field points due body forces …

Parameters:	vv (np.array) – An array of flow at field points An array of size 3Nt, rt (np.array) – An array of field points An array of size 3Nt, r (np.array) – An array of positions An array of size 3Np, F (np.array) – An array of body force An array of size 3Np,

Examples

An example of the Flow field due to $1s$ mode of force per unit area

>>> 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])
>>> F1s  = pystokes.utils.irreducibleTensors(1, p)
>>>
>>> # space dimension , extent , discretization
>>> dim, L, Ng = 3, 10, 64;
>>>
>>> # instantiate the Flow class
>>> flow = pystokes.unbounded.Flow(radius=b, particles=Np, viscosity=eta, gridpoints=Ng*Ng)
>>>
>>> # create grid, evaluate flow and plot
>>> rr, vv = pystokes.utils.gridXY(dim, L, Ng)
>>> flow.flowField1s(vv, rr, r, F1s)
>>> pystokes.utils.plotStreamlinesXY(vv, rr, r, offset=6-1, density=1.4, title='1s')

flowField2a()¶

Compute flow field at field points due body Torque …

Parameters:	vv (np.array) – An array of flow at field points An array of size 3Nt, rt (np.array) – An array of field points An array of size 3Nt, r (np.array) – An array of positions An array of size 3Np, T (np.array) – An array of body torque An array of size 3Np,

Examples

An example of the RBM

# Example 1: Flow field due to $2a$ mode of force per unit area >>> 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]) >>> V2a = pystokes.utils.irreducibleTensors(1, 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.gridXY(dim, L, Ng) >>> flow.flowField2a(vv, rr, r, V2a) >>> pystokes.utils.plotStreamlinesXY(vv, rr, r, offset=6-1, density=1.4, title=‘2s’)

flowField2s()¶

Compute flow field at field points due to 2s mode of the slip …

Parameters:	vv (np.array) – An array of flow at field points An array of size 3Nt, rt (np.array) – An array of field points An array of size 3Nt, r (np.array) – An array of positions An array of size 3Np, S (np.array) – An array of 2s mode of the slip An array of size 5Np,

Examples

An example of the Flow field due to $3t$ 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])
>>> V3t  = pystokes.utils.irreducibleTensors(1, 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.gridXY(dim, L, Ng)
>>> flow.flowField3t(vv, rr, r, V3t)
>>> pystokes.utils.plotStreamlinesXY(vv, rr, r, offset=6-1, density=1.4, title='1s')

flowField3a()¶

Compute flow field at field points due to 3a mode of the slip …

Parameters:	vv (np.array) – An array of flow at field points An array of size 3Nt, rt (np.array) – An array of field points An array of size 3Nt, r (np.array) – An array of positions An array of size 3Np, V (np.array) – An array of 3a mode of the slip An array of size 5Np,

flowField3s()¶

Compute flow field at field points due to 3s mode of the slip …

Parameters:	vv (np.array) – An array of flow at field points An array of size 3Nt, rt (np.array) – An array of field points An array of size 3Nt, r (np.array) – An array of positions An array of size 3Np, G (np.array) – An array of 3s mode of the slip An array of size 7Np,

flowField3t()¶

Compute flow field at field points due to 3t mode of the slip …

Parameters:	vv (np.array) – An array of flow at field points An array of size 3Nt, rt (np.array) – An array of field points An array of size 3Nt, r (np.array) – An array of positions An array of size 3Np, D (np.array) – An array of 3t mode of the slip An array of size 3Np,

Examples

An example of the Flow field due to $3t$ 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])
>>> V3t  = pystokes.utils.irreducibleTensors(1, 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.gridXY(dim, L, Ng)
>>> flow.flowField3t(vv, rr, r, V3t)
>>> pystokes.utils.plotStreamlinesXY(vv, rr, r, offset=6-1, density=1.4, title='2s')

flowField4a()¶

Compute flow field at field points due to 4a mode of the slip …

Parameters:	vv (np.array) – An array of flow at field points An array of size 3Nt, rt (np.array) – An array of field points An array of size 3Nt, r (np.array) – An array of positions An array of size 3Np, M (np.array) – An array of 4a mode of the slip An array of size 7Np,

Stokes flow near interfaces¶

Hydrodynamic interactions of active particles in the half-space bounded by a plane no-shear surface

RBM (Rigid Body Motion: Velocity and Angular Velocity)¶

class pystokes.interface.Rbm¶

Rigid body motion (RBM)

…

Parameters:	radius (float) – Radius of the particles (a) particles (int) – Number of particles (Np) viscosity (float) – Viscosity of the fluid (eta)

mobilityTR()¶

Compute velocity due to body forces using $v=\mu^{TR}\cdot T$ …

Parameters:	v (np.array) – An array of velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, T (np.array) – An array of forces An array of size 3Np, ll (float*) – viscosity ratio of the two fluids Default is zero

mobilityTT()¶

Compute velocity due to body forces using $v=\mu^{TT}\cdot F$ …

Parameters:	v (np.array) – An array of velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, F (np.array) – An array of forces An array of size 3Np, ll (float*) – viscosity ratio of the two fluids Default is zero

Examples

An example of the RBM

>>> import pystokes, numpy as np, matplotlib.pyplot as plt
>>> # particle radius, self-propulsion speed, number and fluid viscosity
>>> b, vs, Np, eta = 1.0, 1.0, 128, 0.1
>>> #initialise
>>> r = pystokes.utils.initialCondition(Np)  # initial random distribution of positions
>>> p = np.zeros(3*Np); p[2*Np:3*Np] = -1    # initial orientation of the colloids
>>>
>>> rbm = pystokes.interface.Rbm(radius=b, particles=Np, viscosity=eta)
>>> force = pystokes.forceFields.Forces(particles=Np)
>>>
>>> def rhs(rp):
>>>     # assign fresh values at each time step
>>>     r = rp[0:3*Np];   p = rp[3*Np:6*Np]
>>>     F, v, o = np.zeros(3*Np), np.zeros(3*Np), np.zeros(3*Np)
>>>
>>>     force.lennardJonesWall(F, r, lje=0.01, ljr=5, wlje=1.2, wljr=3.4)
>>>     rbm.mobilityTT(v, r, F)
>>>     return np.concatenate( (v,o) )
>>>
>>> # simulate the resulting system
>>> Tf, Npts = 150, 200
>>> pystokes.utils.simulate(np.concatenate((r,p)),
>>>    Tf,Npts,rhs,integrator='odeint', filename='crystallization')

noiseRR()¶

Compute rotational Brownian motion …

Parameters:	o (np.array) – An array of angular velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np,

noiseTT()¶

Compute translation Brownian motion …

Parameters:	v (np.array) – An array of velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np,

propulsionT2s()¶

Compute velocity due to 2s mode of the slip $v=\pi^{T,2s}\cdot S$ …

Parameters:	v (np.array) – An array of velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, S (np.array) – An array of 2s mode of the slip An array of size 5*Np,

propulsionT3t()¶

Compute velocity due to 3t mode of the slip $v=\pi^{T,3t}\cdot D$ …

Parameters:	v (np.array) – An array of velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, D (np.array) – An array of 3t mode of the slip An array of size 3*Np,

Flow¶

class pystokes.interface.Flow¶

Flow at given points

…

Parameters:	radius (float) – Radius of the particles. particles (int) – Number of particles viscosity (viscosity of the fluid) – gridpoints (int) – Number of grid points

Examples

An example of the RBM

flowField1s()¶

Compute flow field at field points due body forces …

Parameters:	vv (np.array) – An array of flow at field points An array of size 3Nt, rt (np.array) – An array of field points An array of size 3Nt, r (np.array) – An array of positions An array of size 3Np, F (np.array) – An array of body force An array of size 3Np,

Examples

An example of the Flow field due to $1s$ mode of force per unit area

>>> 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])
>>> F1s  = pystokes.utils.irreducibleTensors(1, p)
>>>
>>> # space dimension , extent , discretization
>>> dim, L, Ng = 3, 10, 64;
>>>
>>> # instantiate the Flow class
>>> flow = pystokes.interface.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.flowField1s(vv, rr, r, F1s)
>>> pystokes.utils.plotStreamlinesYZsurf(vv, rr, r, offset=6-1, density=1.4, title='1s')

Stokes flow bounded by a wall¶

Hydrodynamic interactions of active particles in the half-space bounded by a plane no-slip surface

RBM (Rigid Body Motion: Velocity and Angular Velocity)¶

class pystokes.wallBounded.Rbm¶

Rigid body motion (RBM)

…

Parameters:	radius (float) – Radius of the particles (a) particles (int) – Number of particles (Np) viscosity (float) – Viscosity of the fluid (eta)

mobilityRR()¶

Compute angular velocity due to body torques using $o=\mu^{RR}\cdot T$ …

Parameters:	o (np.array) – An array of angular velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, T (np.array) – An array of forces An array of size 3*Np,

mobilityRT()¶

Compute angular velocity due to body forces using $o=\mu^{RT}\cdot F$ …

Parameters:	o (np.array) – An array of angular velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, F (np.array) – An array of forces An array of size 3*Np,

mobilityTR()¶

Compute velocity due to body torque using $v=\mu^{TR}\cdot T$ …

Parameters:	v (np.array) – An array of velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, T (np.array) – An array of torques An array of size 3*Np,

mobilityTT()¶

Compute velocity due to body forces using $v=\mu^{TT}\cdot F$ …

Parameters:	v (np.array) – An array of velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, F (np.array) – An array of forces An array of size 3*Np,

Examples

An example of the RBM

>>> import pystokes, numpy as np, matplotlib.pyplot as plt
>>> # particle radius, self-propulsion speed, number and fluid viscosity
>>> b, vs, Np, eta = 1.0, 1.0, 128, 0.1
>>> #initialise
>>> r = pystokes.utils.initialCondition(Np)  # initial random distribution of positions
>>> p = np.zeros(3*Np); p[2*Np:3*Np] = -1    # initial orientation of the colloids
>>>
>>> rbm = pystokes.wallBounded.Rbm(radius=b, particles=Np, viscosity=eta)
>>> force = pystokes.forceFields.Forces(particles=Np)
>>>
>>> def rhs(rp):
>>>     # assign fresh values at each time step
>>>     r = rp[0:3*Np];   p = rp[3*Np:6*Np]
>>>     F, v, o = np.zeros(3*Np), np.zeros(3*Np), np.zeros(3*Np)
>>>
>>>     force.lennardJonesWall(F, r, lje=0.01, ljr=5, wlje=1.2, wljr=3.4)
>>>     rbm.mobilityTT(v, r, F)
>>>     return np.concatenate( (v,o) )
>>>
>>> # simulate the resulting system
>>> Tf, Npts = 150, 200
>>> pystokes.utils.simulate(np.concatenate((r,p)),
>>>    Tf,Npts,rhs,integrator='odeint', filename='crystallization')

noiseRR()¶

Compute rotational Brownian motion …

Parameters:	o (np.array) – An array of angular velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np,

noiseTT()¶

Compute translation Brownian motion …

Parameters:	v (np.array) – An array of velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np,

propulsionT2s()¶

Compute velocity due to 2s mode of the slip $v=\pi^{T,2s}\cdot S$ …

Parameters:	v (np.array) – An array of velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, S (np.array) – An array of 2s mode of the slip An array of size 5*Np,

propulsionT3t()¶

Compute velocity due to 3t mode of the slip $v=\pi^{T,3t}\cdot D$ …

Parameters:	v (np.array) – An array of velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, D (np.array) – An array of 3t mode of the slip An array of size 3*Np,

Flow¶

class pystokes.wallBounded.Flow¶

Flow at given points

…

Parameters:	radius (float) – Radius of the particles. particles (int) – Number of particles viscosity (viscosity of the fluid) – gridpoints (int) – Number of grid points

Examples

An example of the RBM

flowField1s()¶

Compute flow field at field points due body forces …

Parameters:	vv (np.array) – An array of flow at field points An array of size 3Nt, rt (np.array) – An array of field points An array of size 3Nt, r (np.array) – An array of positions An array of size 3Np, F (np.array) – An array of body force An array of size 3Np,

Examples

An example of the Flow field due to $1s$ mode of force per unit area

>>> 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])
>>> F1s  = pystokes.utils.irreducibleTensors(1, 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.flowField1s(vv, rr, r, F1s)
>>> pystokes.utils.plotStreamlinesYZsurf(vv, rr, r, offset=6-1, density=1.4, title='1s')

flowField2a()¶

Compute flow field at field points due body Torque …

Parameters:	vv (np.array) – An array of flow at field points An array of size 3Nt, rt (np.array) – An array of field points An array of size 3Nt, r (np.array) – An array of positions An array of size 3Np, T (np.array) – An array of body torque An array of size 3Np,

Examples

An example of the RBM

# Example 1: Flow field due to $2a$ mode of force per unit area >>> 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]) >>> V2a = pystokes.utils.irreducibleTensors(1, 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.flowField2a(vv, rr, r, V2a) >>> pystokes.utils.plotStreamlinesYZsurf(vv, rr, r, offset=6-1, density=1.4, title=‘2s’)

flowField2s()¶

Compute flow field at field points due to 2s mode of the slip …

Parameters:	vv (np.array) – An array of flow at field points An array of size 3Nt, rt (np.array) – An array of field points An array of size 3Nt, r (np.array) – An array of positions An array of size 3Np, S (np.array) – An array of 2s mode of the slip An array of size 5Np,

Examples

An example of the Flow field due to $3t$ 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])
>>> V3t  = pystokes.utils.irreducibleTensors(1, 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.flowField3t(vv, rr, r, V3t)
>>> pystokes.utils.plotStreamlinesYZsurf(vv, rr, r, offset=6-1, density=1.4, title='1s')

flowField3t()¶

Compute flow field at field points due to 3t mode of the slip …

Parameters:	vv (np.array) – An array of flow at field points An array of size 3Nt, rt (np.array) – An array of field points An array of size 3Nt, r (np.array) – An array of positions An array of size 3Np, D (np.array) – An array of 3t mode of the slip An array of size 3Np,

Examples

An example of the Flow field due to $3t$ 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])
>>> V3t  = pystokes.utils.irreducibleTensors(1, 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.flowField3t(vv, rr, r, V3t)
>>> pystokes.utils.plotStreamlinesYZsurf(vv, rr, r, offset=6-1, density=1.4, title='1s')

Stokes flow in a Hele-Shaw cell¶

Stokesian hydrodynamic in a Hele-Shaw cell

RBM (Rigid Body Motion: Velocity and Angular Velocity)¶

class pystokes.twoWalls.Rbm¶

Rigid body motion (RBM)

…

radius: float: Radius of the particles (a).
particles: int: Number of particles (Np)
viscosity: float: Viscosity of the fluid (eta)

mobilityTT()¶

Compute velocity due to body forces using $v=\mu^{TT}\cdot F$ …

Parameters:	v (np.array) – An array of velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, F (np.array) – An array of forces An array of size 3Np, H (float*) – Height of the Hele-Shaw cell

propulsionT2s()¶

Compute velocity due to 2s mode of the slip …

Parameters:	v (np.array) – An array of velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, S (np.array) – An array of forces An array of size 5Np, H (float*) – Height of the Hele-Shaw cell

propulsionT3t()¶

Compute velocity due to 3t mode of the slip …

Parameters:	v (np.array) – An array of velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, D (np.array) – An array of forces An array of size 3Np, H (float*) – Height of the Hele-Shaw cell

Flow¶

class pystokes.twoWalls.Flow¶

Flow at given points

…

Parameters:	radius (float) – Radius of the particles. particles (int) – Number of particles viscosity (viscosity of the fluid) – gridpoints (int) – Number of grid points

flowField1s()¶

Compute flow field at field points due body forces …

Parameters:	vv (np.array) – An array of flow at field points An array of size 3Nt, rt (np.array) – An array of field points An array of size 3Nt, r (np.array) – An array of positions An array of size 3Np, F (np.array) – An array of body force An array of size 3Np, H (float) – Height of the Hele-Shaw cell

flowField2s()¶

Compute flow field at field points due to 2s mode of th slip …

Parameters:	vv (np.array) – An array of flow at field points An array of size 3Nt, rt (np.array) – An array of field points An array of size 3Nt, r (np.array) – An array of positions An array of size 3Np, S (np.array) – An array of 2s mode of the slip An array of size 5Np, H (float) – Height of the Hele-Shaw cell

flowField3t()¶

Compute flow field at field points due to 3t mode of th slip …

Parameters:	vv (np.array) – An array of flow at field points An array of size 3Nt, rt (np.array) – An array of field points An array of size 3Nt, r (np.array) – An array of positions An array of size 3Np, D (np.array) – An array of 2s mode of the slip An array of size rNp, H (float) – Height of the Hele-Shaw cell

Stokes flow in a periodic domain¶

Hydrodynamic interactions of active particles in a periodic 3D space

RBM (Rigid Body Motion: Velocity and Angular Velocity)¶

class pystokes.periodic.Rbm¶

Rigid body motion (RBM) - velocity and angular velocity

Methods in this class update velocities or angular velocities using the inputs of - arrays of positions, velocity or angular velocity, along with an array of forces or torques or a slip mode

The array of velocity or angular velocities is then update by each method.

…

radius: float: Radius of the particles (a).
particles: int: Number of particles (Np)
viscosity: float: Viscosity of the fluid (eta)
boxSize: float: Length of the box which is reperated periodicly in 3D

mobilityRR()¶

Compute angular velocity due to body torques using $o=\mu^{RR}\cdot T$ …

Parameters:	o (np.array) – An array of angular velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, T (np.array) – An array of forces An array of size 3Np, Nb (int) – Number of periodic boxed summed Default is 6 Nm (int*) – Number of Fourier modes summed Default is 6

mobilityRT()¶

Compute angular velocity due to body forces using $o=\mu^{RT}\cdot F$ …

Parameters:	o (np.array) – An array of angular velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, F (np.array) – An array of forces An array of size 3Np, Nb (int) – Number of periodic boxed summed Default is 6 Nm (int*) – Number of Fourier modes summed Default is 6

mobilityTR()¶

Compute velocity due to body torque using $v=\mu^{TR}\cdot T$ …

Parameters:	v (np.array) – An array of velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, T (np.array) – An array of torques An array of size 3Np, Nb (int) – Number of periodic boxed summed Default is 6 Nm (int*) – Number of Fourier modes summed Default is 6

mobilityTT()¶

Compute velocity due to body forces using $v=\mu^{TT}\cdot F$ …

Parameters:	v (np.array) – An array of velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, F (np.array) – An array of forces An array of size 3Np, Nb (int) – Number of periodic boxed summed Default is 10 Nm (int*) – Number of Fourier modes summed Default is 1

propulsionR2s()¶

Compute angular velocity due to 2s mode of the slip $v=\pi^{R,2s}\cdot S$ …

Parameters:	o (np.array) – An array of angular velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, S (np.array) – An array of 2s mode of the slip An array of size 5Np, Nb (int) – Number of periodic boxed summed Default is 6 Nm (int*) – Number of Fourier modes summed Default is 6

propulsionR3a()¶

Compute angular velocity due to 3a mode of the slip $v=\pi^{R,3a}\cdot V$ …

Parameters:	o (np.array) – An array of angular velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, V (np.array) – An array of 3a mode of the slip An array of size 5Np, Nb (int) – Number of periodic boxed summed Default is 6 Nm (int*) – Number of Fourier modes summed Default is 6

propulsionR3s()¶

Compute angular velocity due to 3s mode of the slip $v=\pi^{R,3s}\cdot G$ …

Parameters:	o (np.array) – An array of angular velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, G (np.array) – An array of 3s mode of the slip An array of size 7Np, Nb (int) – Number of periodic boxed summed Default is 6 Nm (int*) – Number of Fourier modes summed Default is 6

propulsionR4a()¶

Compute angular velocity due to 4a mode of the slip $v=\pi^{R,4a}\cdot M$ …

Parameters:	o (np.array) – An array of angular velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, M (np.array) – An array of 4a mode of the slip An array of size 7Np, Nb (int) – Number of periodic boxed summed Default is 6 Nm (int*) – Number of Fourier modes summed Default is 6

propulsionT2s()¶

Compute velocity due to 2s mode of the slip $v=\pi^{T,2s}\cdot S$ …

Parameters:	v (np.array) – An array of velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, S (np.array) – An array of 2s mode of the slip An array of size 5Np, Nb (int) – Number of periodic boxed summed Default is 6 Nm (int*) – Number of Fourier modes summed Default is 6

propulsionT3a()¶

Compute velocity due to 3a mode of the slip $v=\pi^{T,3a}\cdot V$ …

Parameters:	v (np.array) – An array of velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, V (np.array) – An array of 3a mode of the slip An array of size 5Np, Nb (int) – Number of periodic boxed summed Default is 6 Nm (int*) – Number of Fourier modes summed Default is 6

propulsionT3s()¶

Compute velocity due to 3s mode of the slip $v=\pi^{T,3s}\cdot G$ …

Parameters:	v (np.array) – An array of velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, G (np.array) – An array of 3s mode of the slip An array of size 7Np, Nb (int) – Number of periodic boxed summed Default is 6 Nm (int*) – Number of Fourier modes summed Default is 6

propulsionT3t()¶

Compute velocity due to 3t mode of the slip $v=\pi^{T,3t}\cdot D$ …

Parameters:	v (np.array) – An array of velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, D (np.array) – An array of 3t mode of the slip An array of size 3Np, Nb (int) – Number of periodic boxed summed Default is 6 Nm (int*) – Number of Fourier modes summed Default is 6

propulsionT4a()¶

Compute velocity due to 4a mode of the slip $v=\pi^{T,4a}\cdot M$ …

Parameters:	v (np.array) – An array of velocities An array of size 3Np, r (np.array) – An array of positions An array of size 3Np, M (np.array) – An array of 4a mode of the slip An array of size 7Np, Nb (int) – Number of periodic boxed summed Default is 6 Nm (int*) – Number of Fourier modes summed Default is 6

Flow¶

class pystokes.periodic.Flow¶

Flow at given points

…

Parameters:	radius (float) – Radius of the particles. particles (int) – Number of particles viscosity (viscosity of the fluid) – gridpoints (int) – Number of grid points boxsize (int) – Box size

flowField1s()¶

Compute flow field at field points due body forces …

Parameters:	vv (np.array) – An array of flow at field points An array of size 3Nt, rt (np.array) – An array of field points An array of size 3Nt, r (np.array) – An array of positions An array of size 3Np, F (np.array) – An array of body force An array of size 3Np, Nb (int) – Number of periodic boxed summed Default is 6 Nm (int) – Number of Fourier modes summed Default is 6

Examples

An example of the Flow field due to $1s$ mode of force per unit area

>>> 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])
>>> F1s  = pystokes.utils.irreducibleTensors(1, p)
>>>
>>> # space dimension , extent , discretization
>>> dim, L, Ng = 3, 10, 64;
>>>
>>> # instantiate the Flow class
>>> flow = pystokes.periodic.Flow(radius=b, particles=Np, viscosity=eta, gridpoints=Ng*Ng,
>>>         boxSize=L)
>>>
>>> # create grid, evaluate flow and plot
>>> rr, vv = pystokes.utils.gridXY(dim, L, Ng)
>>> flow.flowField1s(vv, rr, r, F1s)
>>> pystokes.utils.plotStreamlinesXY(vv, rr, r, offset=6-1, density=1.4, title='1s')

flowField2s()¶

Compute flow field at field points due to 2s mode of the slip …

Parameters:

vv (np.array) – An array of flow at field points An array of size 3*Nt,
rt (np.array) – An array of field points An array of size 3*Nt,
r (np.array) – An array of positions An array of size 3*Np,
S (np.array) – An array of 2s mode of the slip An array of size 5*Np,
Nb (int) – Number of periodic boxed summed Default is 6
Nm (int) – Number of Fourier modes summed Default is 6

flowField3t()¶

Compute flow field at field points due to 3t mode of the slip …

Parameters:

vv (np.array) – An array of flow at field points An array of size 3*Nt,
rt (np.array) – An array of field points An array of size 3*Nt,
r (np.array) – An array of positions An array of size 3*Np,
D (np.array) – An array of 3t mode of the slip An array of size 3*Np,
Nb (int) – Number of periodic boxed summed Default is 6
Nm (int) – Number of Fourier modes summed Default is 6

Phoresis in an unbounded domain¶

Phoretic motion in an infinite space

Phoresis¶

class pystokes.phoreticUnbounded.Phoresis¶

…

Parameters:	radius (float) – Radius of the particles. particles (int) – Number of particles phoreticConstant (float) – PhoreticConstant

Examples

An example of Phoresis

Field¶

class pystokes.phoreticUnbounded.Field¶

Phoretic field at given points

…

Parameters:	radius (float) – Radius of the particles. particles (int) – Number of particles phoreticConstant (float) – PhoreticConstant of the fluid gridpoints (int) – Number of grid points

Phoresis in a space bounded by a wall¶

Phoresis in the half-space bounded by a plane no-slip wall

Phoresis¶

class pystokes.phoreticWallBounded.Phoresis¶

…

Parameters:	radius (float) – Radius of the particles. particles (int) – Number of particles phoreticConstant (float) – PhoreticConstant

Examples

An example of Phoresis

Field¶

class pystokes.phoreticWallBounded.Field¶

Phoretic field at given points

…

Parameters:	radius (float) – Radius of the particles. particles (int) – Number of particles phoreticConstant (float) – PhoreticConstant of the fluid gridpoints (int) – Number of grid points

Force fields in colloidal systems¶

Force fields in colloidal systems

Forces¶

class pystokes.forceFields.Forces¶

Computes forces in a system of colloidal particles

Methods in the Forces class take input,

arrays of positions, forces
parameters for a given potential

The array of forces is then update by each method.

…

Parameters:	particles (int) – Number of particles (Np)

harmonicConfinement()¶: Forces on colloids in a harmonic trap

lennardJones()¶

The standard Lennard-Jones potential truncated at the minimum (aslo called WCA potential)

We choose phi(r) = lje/12 (rr^12 - 2*rr^6 ) + lje/12, as the standard WCA potential. ljr: minimum of the LJ potential and rr=ljr/r.

…

Parameters:	r (np.array) – An array of positions An array of size 3Np, F (np.array) – An array of forces An array of size 3Np, lje (float) – Strength of the LJ ljr (float) – Range of the LJ

lennardJonesWall()¶

The standard Lennard-Jones potential truncated at the minimum (aslo called WCA potential)

We choose phi(r) = lje/12 (rr^12 - 2*rr^6 ) + lje/12, as the standard WCA potential. ljr: minimum of the LJ potential and rr=ljr/r.

…

Parameters:	r (np.array) – An array of positions An array of size 3Np, F (np.array) – An array of forces An array of size 3Np, lje (float) – Strength of the LJ ljr (float) – Range of the LJ

lennardJonesXWall()¶

The standard Lennard-Jones potential truncated at the minimum (aslo called WCA potential)

We choose phi(r) = lje/12 (rr^12 - 2*rr^6 ) + lje/12, as the standard WCA potential. ljr: minimum of the LJ potential and rr=ljr/r. This force is only in z-direction due to wall at x=0

…

Parameters:	r (np.array) – An array of positions An array of size 3Np, F (np.array) – An array of forces An array of size 3Np, lje (float) – Strength of the LJ ljr (float) – Range of the LJ

membraneBound()¶

Force on colloids in membraneSurface

…

Parameters:	r (np.array) – An array of positions An array of size 3Np, r0 (np.array) – An array of trap centers An array of size 3Np, F (np.array) – An array of forces An array of size 3Np, cn (float*) – Stiffness of the trap

membraneConfinement()¶

Force on colloids in membraneSurface

…

Parameters:	r (np.array) – An array of positions An array of size 3Np, r0 (np.array) – An array of trap centers An array of size 3Np, F (np.array) – An array of forces An array of size 3Np, cn (float*) – Stiffness of the trap

membraneSurface()¶

Force on colloids connected as a membrane

…

Parameters:	r (np.array) – An array of positions An array of size 3Np, F (np.array) – An array of forces An array of size 3Np, bondLength (float) – The size of natural spring springModulus (float) – Stiffness of the trap bendModulus (float) – Bending cost

multiRingpolymers()¶

Force on colloids connected by a spring in a ring polymer

…

Parameters:	r (np.array) – An array of positions F (np.array) – An array of forces An array of size 3Np, An array of size 3Np, bondLength (float) – The size of natural spring springModulus (float) – Stiffness of the trap

multipolymers()¶

Force on colloids in many polymers connected by a spring

…

Parameters:	r (np.array) – An array of positions F (np.array) – An array of forces An array of size 3Np, An array of size 3Np, bondLength (float) – The size of natural spring springModulus (float) – Stiffness of the trap

opticalConfinement()¶

Force on colloids in optical traps of varying stiffnesses

…

Parameters:	r (np.array) – An array of positions An array of size 3Np, r0 (np.array) – An array of trap centers An array of size 3Np, F (np.array) – An array of forces An array of size 3Np, k (float*) – Stiffness of the trap

sedimentation()¶

Force on colloids in sedimentation

…

Parameters:	r (np.array) – An array of positions An array of size 3Np, F (np.array) – An array of forces An array of size 3Np, g (float) – Gravity

softSpringWall()¶: F = -k(r-rmin)

spring()¶

Force on colloids connected by a spring in a single polymer

…

Parameters:	r (np.array) – An array of positions F (np.array) – An array of forces An array of size 3Np, An array of size 3Np, bondLength (float) – The size of natural spring springModulus (float) – Stiffness of the trap

Torques¶

class pystokes.forceFields.Torques¶

Computes torques in a system of colloidal particles

Methods in the Torques class take input,

arrays of positions, Torques
parameters for a given potential

The array of torques is then update by each method.

…

Parameters:	particles (int) – Number of particles (Np)

bottomHeaviness()¶

Torque due to bottom-heaviness

…

Parameters:	p (np.array) – An array of Orientations An array of size 3Np, F (np.array) – An array of Torques An array of size 3Np, bh (float) – bottomHeaviness

Utils: Miscellaneous function¶

utils.irreducibleTensors()¶

Uniaxial paramterization of the tensorial harmonics (Yl) of order l …

Parameters:	l (int) – Tensorial Harmonics of order l p (np.rrray) – An array of size 3 Axis along which the mode is paramterized Y0 (float) – Strength of the mode returns (Yl - tensorialHarmonics of rank l) –

utils.gridXY()¶

Returns the grid in XY direction centered around zero …

Parameters:	L (float) – Length of the grid Ng (int) – Number of grid points

Examples

An example of creating grid

>>> import numpy as np, pystokes
>>> dim, L, Ng = 3, 10, 32
>>>  rr, vv = pystokes.utils.gridXY(dim, L, Ng)

utils.gridYZ()¶

Returns the grid in YZ direction centered around zero …

Parameters:	L (float) – Length of the grid Ng (int) – Number of grid points

Examples

An example of creating grid

>>> import numpy as np, pystokes
>>> dim, L, Ng = 3, 10, 32
>>>  rr, vv = pystokes.utils.gridYZ(dim, L, Ng)

utils.simulate()¶

Simulates using choice of integrator

…

Parameters:	rp0 (np.array) – Initial condition Tf (int) – Final time Npts (int) – Number of points to return data rhs (Python Function) – Right hand side to integrate integrator (string) – Default is ‘odeint’ of scipy filename (string) – filename to write the data. Deafult is ‘this.mat’