# 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:

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 `cyarray.carray.BaseArray`.

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.