ParticleArray

Particles are ubiquitous in SPH and in PySPH. The domain is discretized with a finite number of points, to which are assigned physical properties corresponding to the fluid being modelled. This leads us to the concept of a set of arrays that represent a fluid.

In PySPH, a homogeneous collection of particles is represented by a ParticleArray as shown in the figure:

../_images/particle-array.png

The figure shows only a subset of the attributes of a ParticleArray pertinent to this discussion. Refer to the reference documentation (Module particle_array) for a more complete listing of class attributes and methods.

Creating particle arrays

From the user’s perspective, a ParticleArray may be created like so: .. sourcecode:: python

import numpy

# Import the base module import pysph.base.api as base

# create the numpy arrays representing the properties x = numpy.linspace(...) y = numpy.linspace(...) . . . f = numpy.sin(x)

fluid = base.get_particle_array(name=”fluid”, x=x, y=y, ..., f=f)

This creates an instance of a ParticleArray, fluid with the requested properties. From within python, the properties may be accessed via the standard attribute access method for Python objects:

In [10] : fluid.x
Out[4] : array([....])

Important ParticleArray attributes

name: PySPH permits the use of multiple arrays and warrants the
use of a unique name identifier to distinguish between different particle arrays.
constants: Properties that are constant in space and time for all
particles of a given type are stored in the constants attribute.
is_dirty: In PySPH, the indexing scheme for the particles may be
rendered invalid after updating the particle properties. Moreover, other particle arrays like stationary boundaries remain fixed and the initial indexing is valid.. The is_dirty flag essentially helps PySPH distinguish these two cases, thus saving time that would have been spent re-indexing these particles. Thus, setting the is_dirty flag for a ParticleArray forces PySPH to re-compute neighbors for that array.
num_real_particles: Every ParticleArray object is given a
set of deault properties, one of which is the tag property. The tag of a particle is an integer which is used by PySPH to determine if a particle belongs to a remote processor (0 local, else remote). The num_real_particles attributes counts the number of properties that have the tag value 0.

Data buffers and the carray

The numpy arrays that are used to create the ParticleArray object are used to construct a raw data buffer which is accessible through Cython at C speed. Internally, each property for the particle array is stored as a carray.

Note

This discussion may be omitted by the casual end user. If you are extending PySPH and speed is a concern, read on.

Each carray has an associated data type corresponding to the particle property. The available types are:

  • IntArray
  • LongArray
  • FloatArray
  • DoubleArray

The type of a carray may be determined via it’s get_c_type() method.

The carray object provides faster access to the data when compared with the corresponding numpy arrays, even in Python. Particle properties may be accessed using the following methods:

get(i)

Get the element at the specified index.

set(i, val)

Set the element at the specified index to the given value. The value must be of the same c-type as the array.

Faster buffer access

As mentioned, the data represented by a carray may be accessed at C speed using Cython. This is done using the data attribute only accessible through Cython:

arr = pa.get_carray(prop)
val =  arr.data[index]

Peep into the functions (sph.funcs) to learn how to use this feature.

Particles

Since PySPH supports an arbitrary number of ParticleArray objects, it would be convenient to group them all together into a single container. This way, common functions like updating the indexing scheme (for particle arrays that are dirty) may be called consistently on each array. This is accomplished by the object Particles:

class Particles(arrays[, locator_type])
arrays : A list of ParticleArray objects

You must provide an instance of Particles to PySPH to carry out a simulation.

Specifying an indexing scheme

Upon creation of a Particles instance, we can pass arguments to indicate the kind of spatial indexing scheme to use. The default is a box sort algorithm (see Module nnps: Nearest Neighbor Particle Search). Currently, this is the only indexing scheme implemented.

See the reference documentation Module particle_array for a further description.

Summary

In PySPH, a ParticleArray object may be instantiated from numpy arrays. We may use an arbitrary collection of these objects with the only restriction that their names are unique. The ParticleArray objects are grouped together to form a Particles object which is used by PySPH. This container may be heterogeneous in that different particle arrays correspond to different types.