Models

`AsynchronousVicsek`(pos, vel, v, jump_rate, ...)	Vicsek model with random jumps.
`Vicsek`(pos, vel, v, sigma, nu, ...[, ...])	Vicsek model with gradual alignment and diffusion.
`SynchronousVicsek`(pos, vel, v, dt, kappa, ...)	Vicsek model with synchronous random jumps.
`BOAsynchronousVicsek`(pos, bo, v, jump_rate, ...)	Asynchronous Vicsek model for body-oriented particles.
`VolumeExclusion`(pos, interaction_radius, ...)	Spherical particles interacting via short-range repulsion.
`AttractionRepulsion`(pos, vel, ...[, p, ...])	Self-propelled particles with attraction and repulsion forces.

class sisyphe.models.AsynchronousVicsek(pos, vel, v, jump_rate, kappa, interaction_radius, box_size, vision_angle=6.283185307179586, axis=None, boundary_conditions='periodic', variant=None, options=None, sampling_method='vonmises', block_sparse_reduction=False, number_of_cells=1024)

Vicsek model with random jumps.

The asynchronous Vicsek Model is described in [DM2016].

The velocity of each particle is a unit vector in the sphere \(\mathbb{S}^{d-1}\). The velocity of each particle is updated at random times by computing first a target (Tensor) in \(\mathbb{R}^d\) using the parameters contained in target and then a new velocity in \(\mathbb{S}^{d-1}\) is sampled using a method specified by sampling_method. Between two jumps, a particle moves in straight line at a constant speed.

DM2016: G. Di Marco, S. Motsch, Self-alignment driven by jump processes: Macroscopic limit and numerical investigation, Math. Models Methods Appl. Sci. Vol. 26, No. 7 (2016).

name

"Asynchronous Vicsek" and the value of the key "name" in the dictionary target.

Type: str

v

The speed of the particles.

Type: float

dt

Discretisation time-step. It is equal to 0.01 divided by jumprate.

Type: float

jumprate

Each particle has an independent Poisson clock with parameter jumprate.

Type: float

kappa

Concentration parameter.

Type: (1,) Tensor

target

Target dictionary. Contains the target name and its parameters. To be passed to the method compute_target() in the argument which_target.

Type: dict

options

Options dictionary. Each key is an option’s name and its value contains the parameters of the option. To be passed to the method compute_target() in the argument which_options.

Type: dict

sampling_method

The new velocity is sampled using one of the following methods.

"vonmises" : Von Mises distribution with center given by the normalised target and the concentration parameter given by the norm of target.

"uniform" : Uniform distribution in the ball around the normalised target with deviation given by the inverse of the norm of target. Dimension 2 only.

"projected_normal" : Sample first a gaussian random variable in \(\mathbb{R}^d\) with center the normalised target and standard deviation the inverse of the norm of target. Then project the result on the sphere \(\mathbb{S}^{d-1}\).

"vectorial_noise" : Same as "projected_normal" where the normally distributed random variable is replaced by a uniformly distributed random variable on the sphere, divided by the norm of target.

Type: str

parameters

The parameters of the model.

Type: str

update()

Update the positions and velocities.

Update the positions using a first order explicit Euler method during the time step dt. The particles which update their velocities in the time interval dt are given by the boolean mask of size N who_jumps. The probability for a particle to jump is equal to exp(-jumprate * dt).

Returns: Positions and velocities.
Return type: dict

class sisyphe.models.Vicsek(pos, vel, v, sigma, nu, interaction_radius, box_size, vision_angle=6.283185307179586, axis=None, boundary_conditions='periodic', variant=None, options=None, numerical_scheme='projection', dt=0.01, block_sparse_reduction=False, number_of_cells=1600)

Vicsek model with gradual alignment and diffusion.

The Vicsek model is described in [DM2008].

The velocity of each particle is a unit vector in the sphere \(\mathbb{S}^{d-1}\). The velocity of each particle is continuously updated by a combination of two effects.

A deterministic drift tends to relax the velocity towards a target computed using target. The intensity of the drift may depend on the norm of the target.

A random diffusion.

The speed of the particles is constant.

DM2008: P. Degond, S. Motsch, Continuum limit of self-driven particles with orientation interaction, Math. Models Methods Appl. Sci. Vol. 18, Suppl. (2008).

name

"Vicsek" and the value of the key "name" in the dictionary target.

Type: str

v

The speed of the particles.

Type: float

dt

Discretisation time-step.

Type: float

sigma

The diffusion coefficient.

Type: float

nu

The drift coefficient

Type: float

kappa

Concentration parameter equal to the ratio of nu over sigma.

Type: (1,) Tensor

target

Target dictionary. Contains the target name and its parameters. To be passed to the method compute_target() in the argument which_target.

Type: dict

options

Options dictionary. Each key is an option’s name and its value contains the parameters of the option. To be passed to the method compute_target() in the argument which_options.

Type: dict

scheme

The numerical scheme used to discretise the SDE. Can be one of the following:

"projection" : Projected Euler-Maruyama scheme on the manifold \(\mathbb{S}^{d-1}\).

"expEM" : In dimension 2, Euler-Maruyama scheme in the Lie algebra and exponentiation.

Type: str

parameters

The parameters of the model.

Type: str

update()

Update the positions and velocities.

Update the positions using a first order explicit Euler method during the time step dt. Update the velocities using the numerical scheme scheme and the method one_step_velocity_scheme().

Returns: positions and velocities.
Return type: dict

one_step_velocity_scheme(targets)

One time step of the numerical scheme for the velocity.

Parameters: targets ((N,d) Tensor) –
Returns: (N,d) Tensor

class sisyphe.models.SynchronousVicsek(pos, vel, v, dt, kappa, interaction_radius, box_size, vision_angle=6.283185307179586, axis=None, boundary_conditions='periodic', variant=None, options=None, sampling_method='uniform', block_sparse_reduction=False, number_of_cells=1024)

Vicsek model with synchronous random jumps.

This is the original Vicsek model described in [CGGR2008].

The velocity of each particle is a unit vector in the sphere \(\mathbb{S}^{d-1}\). The velocity of each particle is updated at each iteration by computing first a target (Tensor) in \(\mathbb{R}^d\) using the parameters contained in the dictionary target and then a new velocity in \(\mathbb{S}^{d-1}\) is sampled using a method specified by sampling_method. The particles move in straight line at a constant speed.

CGGR2008: H. Chaté, F. Ginelli, G. Grégoire, F. Raynaud, Collective motion of self-propelled particles interacting without cohesion, Phys. Rev. E., Vol. 77, No. 4 (2008).

name

"Synchronous Vicsek" and the value of the key "name" in the dictionary target.

Type: str

v

The speed of the particles.

Type: float

dt

Discretisation time-step.

Type: float

kappa

Concentration parameter.

Type: (1,) Tensor

target

Target dictionary. Contains the target name and its parameters. To be passed to the method compute_target() in the argument which_target.

Type: dict

options

Options dictionary. Each key is an option’s name and its value contains the parameters of the option. To be passed to the method compute_target() in the argument which_options.

Type: dict

sampling_method

The new velocity is sampled using one of the following methods.

"vonmises" : Von Mises distribution with center given by the normalised target and the concentration parameter given by the norm of target.

"uniform" : Uniform distribution in the ball around the normalised target with deviation given by the inverse of the norm of target. Dimension 2 only.

"projected_normal" : Sample first a gaussian random variable in \(\mathbb{R}^d\) with center the normalised target and standard deviation the inverse of the norm of target. Then project the result on the sphere \(\mathbb{S}^{d-1}\).

"vectorial_noise" : Same as "projected_normal" where the normally distributed random variable is replaced by a uniformly distributed random variable on the sphere, divided by the norm of target.

Type: str

parameters

The parameters of the model.

Type: str

update()

Update the positions and velocities.

Update the positions using a first order explicit Euler method during the time step dt. Update the velocities by sampling new velocities using the method given by sampling_method.

Returns: Positions and velocities.
Return type: dict

class sisyphe.models.CuckerSmale(pos, vel, sigma, nu, interaction_radius, box_size, alpha, beta, vision_angle=6.283185307179586, axis=None, boundary_conditions='periodic', variant=None, options=None, dt=0.01, block_sparse_reduction=False, number_of_cells=1600)

class sisyphe.models.BOAsynchronousVicsek(pos, bo, v, jump_rate, kappa, interaction_radius, box_size, vision_angle=6.283185307179586, axis=None, boundary_conditions='periodic', variant=None, options=None, sampling_method='vonmises', block_sparse_reduction=False, number_of_cells=1600)

Asynchronous Vicsek model for body-oriented particles.

The asynchronous Vicsek Model is described in [DFM2017].

The body-orientation of each particle is updated at random times by computing first a target (Tensor) in \(SO(3)\) using the parameters contained in the dictionary target and then a new body-orientation in \(SO(3)\) is sampled using a method specified by sampling_method. Between two jumps, a particle moves in straight line at a constant speed.

DFM2017: P. Degond, A. Frouvelle, S. Merino-Aceituno, A new flocking model through body attitude coordination, Math. Models Methods Appl. Sci. Vol. 27, No. 6 (2017).

name

"Body-Orientation Asynchronous Vicsek" and the value of the key "name" in the dictionary target.

Type: str

v

The speed of the particles.

Type: float

dt

Discretisation time-step. It is equal to 0.01 divided by jumprate.

Type: float

jumprate

Each particle has an independent Poisson clock with parameter jumprate.

Type: float

kappa

Concentration parameter.

Type: (1,) Tensor

target

Target dictionary. Contains the target name and its parameters. To be passed to the method compute_target() in the argument which_target.

Type: dict

options

Options dictionary. Each key is an option’s name and its value contains the parameters of the option. To be passed to the method compute_target() in the argument which_options.

Type: dict

sampling_method

The new velocity is sampled using one of the following methods.

"vonmises" : Von Mises distribution with center given by the normalised target and the concentration parameter given by the norm of target.

"uniform" : Uniform distribution in the ball around the normalised target with deviation given by the inverse of the norm of target. Dimension 2 only.

Type: str

parameters

The parameters of the model.

Type: str

update()

Update the positions and body-orientations.

Update the positions using a first order explicit Euler method during the time step dt. The particles which update their body-orientations in the time interval dt are given by the boolean mask of size N who_jumps. The probability for a particle to jump is equal to exp(-jumprate * dt).

Returns: Positions and body-orientations.
Return type: dict

class sisyphe.models.VolumeExclusion(pos, interaction_radius, box_size, alpha, division_rate, death_rate, dt, Nmax=20000, boundary_conditions='open', block_sparse_reduction=False, number_of_cells=1024)

Spherical particles interacting via short-range repulsion.

The model is described in [MP2017].

Each particle has a fixed radius and the particles repulse each other when they overlap. In addition the particles die and can divide at a constant rate. Currently implemented in an open domain only.

MP2017: S. Motsch, D. Peurichard, From short-range repulsion to Hele-Shaw problem in a model of tumor growth, J. Math. Biology, Vol. 76, No. 1, 2017.

alpha

Drift coefficient.

Type: float

mu

Division rate.

Type: float

nu

Death rate.

Type: float

dt0

Default time step.

Type: float

dt

Current discretisation time step (adaptive).

Type: float

Nmax

Maximum number of particles.

Type: int

age

Age of the particles.

Type: (self.N,) Tensor

name

"Volume exclusion".

Type: str

property E

The energy of the particle system.

The force exerted by a particle located at \(x_j\) with radius \(R_j\) on a particle located at \(x_i\) with radius \(R_i\) is

\[F = -\frac{\alpha}{R_i} \nabla_{x_i} U\left(\frac{|x_i - x_j|^2}{(R_i + R_j)^2}\right),\]

where the potential is

\[U(s) = -\log(s) + s - 1\,\,\text{for}\,\, s<1 \,\,\text{and}\,\, U(s) = 0\,\, \text{for}\,\, s>1.\]

The energy of the couple is

\[E_{ij} = U\left(\frac{|x_i - x_j|^2}{(R_i + R_j)^2}\right) (R_i + R_j)^2.\]

The total energy of the system is

\[E = -\frac{1}{2}\sum_{i\ne j} E_{ij}.\]

Returns: The total energy of the system.
Return type: (1,) Tensor

add_particle(who)

Some particle divide.

When a particle at \(x_i\) with radius \(R_i\) divides, a new particle is added at position \(x_i + 2R_iu\) where \(u\) is uniformly sampled on the unit sphere. The radius of the new particle is \(R_i\).

Parameters: who ((N,) BoolTensor) – Boolean mask giving the particles which divide.

remove_particle(who): The particles in the boolean mask who die.

update()

Update the positions.

First compute the force. The Energy satisfies

\[\frac{\mathrm{d}}{\mathrm{d}t} E = -\frac{1}{2} \sum_{i\ne j} \frac{\alpha}{R_i} \left|\frac{\mathrm{d}x_i}{\mathrm{d}t}\right|^2 \leq0.\]

Update the position using an adaptive time step:

Compute the energy of the system E.
Set dt = dt0.
Compute the new positions with time step dt.
Compute the energy of the new system.
If the energy of the new system is higher than E then set dt = dt/2 and return to 3.

Once the positions are updated, compute the set of particles which divide during the time interval dt. Each particle has a probability exp(-dt * mu) to divide. Divisions are not allowed if there are more than Nmax particles. Finally compute the set of particles which die during the interval dt. Each particle has a probability exp(-dt * nu) to die. Death is not allowed if there are less that 2 particles.

Returns: Positions.
Return type: dict

class sisyphe.models.AttractionRepulsion(pos, vel, interaction_radius, box_size, propulsion, friction, Ca, la, Cr, lr, dt, p=2, isaverage=False, vision_angle=6.283185307179586, axis=None, boundary_conditions='open', block_sparse_reduction=False, number_of_cells=1000)

Self-propelled particles with attraction and repulsion forces.

The model is studied in [DCBC2006].

The attraction-repulsion force is derived from the Morse potential. The self-propulsion force tends to relax the speed of the particles towards the ratio of the parameters alpha and beta.

DCBC2006: M. R. D’Orsogna, Y. L. Chuang, A. L. Bertozzi, L. S. Chayes, Self-Propelled Particles with Soft-Core Interactions: Patterns, Stability, and Collapse, Phys. Rev. Lett., Vol. 96, No. 10 (2006).

alpha

Propulsion parameter.

Type: float

beta

Friction parameter.

Type: float

Ca

Attraction coefficient.

Type: float

la

Attraction length.

Type: float

Cr

Repulsion coefficient.

Type: float

lr

Repulsion length.

Type: float

p

Exponent of the Morse potential.

Type: int

dt

Time step.

Type: float

isaverage

Use the mean-field scaling or not.

Type: bool

mass

The mass is proportional to the volume.

Type: (N,) Tensor

name

'Self-propulsion and Attraction-Repulsion'.

Type: str

parameters

Parameters.

Type: str

compute_force(): Return the sum of the self-propulsion and attraction-repulsion forces.

update()

Update the positions and velocities. RK4 numerical scheme.

Returns: Positions and velocities.
Return type: dict

class sisyphe.models.HardSpheres(pos, vel, radius, box_size, boundary_conditions, dt0, fig=None)