Module particle_array

The ParticleArray class itself is documented as below.

A ParticleArray represents a collection of particles.

class pysph.base.particle_array.ParticleArray(unicode name=u'', default_particle_tag=Local, constants=None, backend=None, **props)

Bases: object

Class to represent a collection of particles.


name of this particle array.


dictionary of {prop_name:carray}.


dictionary of {const_name: carray}



There are many ways to create a ParticleArray:

>>> p = ParticleArray(name='fluid', x=[1.,2., 3., 4.])
>>> p.x, p.tag,, p.gid

For a full specification of properties with their type etc.:

>>> p = ParticleArray(name='fluid',
...                   x=dict(data=[1,2], type='int', default=1))
>>> p.get_carray('x').get_c_type()

The default value is what is used to set the default value when a new particle is added and the arrays auto-resized.

To create constants that are not resized with added/removed particles:

>>> p = ParticleArray(name='f', x=[1,2], constants={'c':[0.,0.,0.]})


  • name (str) – name of this particle array.
  • default_particle_tag (int) – one of Local, Remote or Ghost
  • constants (dict) – dictionary of constant arrays for the entire particle array. These must be arrays and are not resized when particles are added or removed. These are stored as CArrays internally.
  • props – any additional keyword arguments are taken to be properties, one for each property.
add_constant(self, unicode name, data)

Add a constant property to the particle array.

A constant property is an array but has a fixed size in that it is never resized as particles are added or removed. These properties are always stored internally as CArrays.

An example of where this is useful is if you need to calculate the center of mass of a solid body or the net force on the body.

  • name (str) – name of the constant
  • data (array-like) – the value for the data.
add_output_arrays(self, list props)

Append props to the existing list of output arrays

Parameters:props (list) – The additional list of property arrays to save
add_particles(self, align=True, **particle_props)

Add particles in particle_array to self.

Parameters:particle_props (dict) – a dictionary containing numpy arrays for various particle properties.


  • all properties should have same length arrays.
  • all properties should already be present in this particles array. if new properties are seen, an exception will be raised.
add_property(self, unicode name, unicode type=u'double', default=None, data=None, stride=1)

Add a new property to the particle array.

If a default is not supplied 0 is assumed. The stride is useful when many elements are needed per particle. For example if stride is 3 then 3 elements are allocated per particle.

  • name (str) – compulsory name of property.
  • type (str) – specifying the data type of this property (‘double’, ‘int’ etc.)
  • default (value) – specifying the default value of this property.
  • data (ndarray) – specifying the data associated with each particle.
  • stride (int) – the number of elements per particle.


If there are no particles currently in the particle array, and a new property with some particles is added, all the remaining properties will be resized to the size of the newly added array.

If there are some particles in the particle array, and a new property is added without any particles, then this new property will be resized according to the current size.

If there are some particles in the particle array and a new property is added with a different number of particles, then an error will be raised.


  • it is best not to add properties with data when you already have particles in the particle array. Reason is that, the particles in the particle array will be stored so that the ‘Real’ particles are in the top of the list and later the dummy ones. The data in your property array should be matched to the particles appropriately. This may not always be possible when there are particles of different type in the particle array.
  • Properties without any values can be added anytime.
  • While initializing particle arrays only using the add_property function, you will have to call align_particles manually to make sure particles are aligned properly.
align_particles(self) → int

Moves all ‘Local’ particles to the beginning of the array

This makes retrieving numpy slices of properties of ‘Local’ particles possible. This facility will be required frequently.



index_arr = LongArray(n)

next_insert = 0
for i from 0 to n
    p <- ith particle
    if p is Local
        if i != next_insert
            tmp = index_arr[next_insert]
            index_arr[next_insert] = i
            index_arr[i] = tmp
            next_insert += 1
            index_arr[i] = i
            next_insert += 1
        index_arr[i] = i

 # we now have the new index assignment.
 # swap the required values as needed.
 for every property array:
     for i from 0 to n:
         if index_arr[i] != i:
             tmp = prop[i]
             prop[i] = prop[index_arr[i]]
             prop[index_arr[i]] = tmp
append_parray(self, ParticleArray parray, bool align=True, bool update_constants=False) → int

Add particles from a particle array

properties that are not there in self will be added




Clear all data held by this array



copy_over_properties(self, dict props)

Copy the properties from one set to another.

Parameters:props (dict) – A mapping between the properties to be copied.


To save the properties ‘x’ and ‘y’ to say ‘x0’ and ‘y0’:

>>> pa.copy_over_properties(props = {'x':'x0', 'y':'y0'}
copy_properties(self, ParticleArray source, long start_index=-1, long end_index=-1)

Copy properties from source to self

  • source (ParticleArray) – the particle array from where to copy.
  • start_index (long) – the first particle in self which maps to the 0th particle in source
  • end_index (long) – the index of first particle from start_index that is not copied


empty_clone(self, props=None) → ParticleArray

Creates an empty clone of the particle array

ensure_properties(self, ParticleArray src, list props=None)

Ensure that the particle array has the same properties as the one given.

Note that this does not check for any constants but only properties.

If the optional props argument is passed it only checks for these.

extend(self, int num_particles)

Increase the total number of particles by the requested amount

New particles are added at the end of the list, you will have to manually call align_particles later in order to update the number of particles.

extract_particles(self, indices, ParticleArray dest_array=None, bool align=True, list props=None) → ParticleArray

Create new particle array for particles with indices in index_array

  • indices (list/array/LongArray) – indices of particles to be extracted (can be a LongArray or list/numpy array).
  • dest_array (ParticleArray) – optional Particle array to populate. Note that this array should have the necessary properties. If none is passed a new particle array is created and returned.
  • align (bool) – Specify if the destination particle array is to be aligned after particle extraction.
  • props (list) – the list of properties to extract, if None all properties are extracted.


The algorithm is as follows:

  • create a new particle array with the required properties.
  • resize the new array to the desired length (index_array.length)
  • copy the properties from the existing array to the new array.
get(self, *args, only_real_particles=True)

Return the numpy array/constant for the property names in the arguments.

Parameters:only_real_particles (bool) –
indicates if properties of only real particles need to be
returned or all particles to be returned. By default only real particles will be returned.
args : additional args
a list of property names.


The returned numpy array does NOT own its data. Other operations may be performed.

Return type:Numpy array.
get_carray(self, unicode prop) → BaseArray

Return the c-array for the property or constant.


Return the properties that are to be load balanced. If none are explicitly set by the user, return all of the properties.

get_number_of_particles(self, bool real=False) → int

Return the number of particles

get_property_arrays(self, all=True, only_real=True)

Return a dictionary of arrays held by the ParticleArray container.

This does not include the constants.

  • all (bint) – Flag to select all arrays
  • only_real (bint) – Flag to select Local/Remote particles


The dictionary returned is keyed on the property name and the value is the NumPy array representing the data. If all is set to False, the list of arrays is determined by the output_property_arrays data attribute.

get_time(self) → double


has_array(self, unicode arr_name)

Returns true if the array arr_name is present











remove_particles(self, indices, align=True)

Remove particles whose indices are given in index_list.

We repeatedly interchange the values of the last element and values from the index_list and reduce the size of the array by one. This is done for every property that is being maintained.

Parameters:indices (array) – an array of indices, this array can be a list, numpy array or a LongArray.


Pseudo-code for the implementation:

if index_list.length > number of particles
    raise ValueError

sorted_indices <- index_list sorted in ascending order.

for every every array in property_array
remove_property(self, unicode prop_name)

Removes property prop_name from the particle array

remove_tagged_particles(self, int tag, bool align=True)

Remove particles that have the given tag.

Parameters:tag (int) – the type of particles that need to be removed.
resize(self, long size)

Resize all arrays to the new size. Note that this does not update the number of particles, as this just resizes the internal arrays. To do that, you need to call align_particles.

set(self, **props)

Set properties from numpy arrays like objects

Parameters:props (dict) – a dictionary of properties containing the arrays to be set.


  • the properties being set must already be present in the properties dict.
  • the size of the data should match the array already present.
set_device_helper(self, gpu)

Set the device helper to push/pull from a hardware accelerator.

set_lb_props(self, list lb_props)
set_name(self, unicode name)
set_num_real_particles(self, long value)
set_output_arrays(self, list props)

Set the list of output arrays for this ParticleArray

Parameters:props (list) – The list of property arrays


In PySPH, the solver obtains the list of property arrays to output by calling the ParticleArray.get_property_arrays method. If detailed output is not requested, the output_property_arrays attribute is used to determine the arrays that will be written to file

set_pid(self, int pid)

Set the processor id for all particles

set_tag(self, long tag_value, LongArray indices)

Set value of tag to tag_value for the particles in indices

set_time(self, double time)
set_to_zero(self, list props)




update_backend(self, backend=None)
update_min_max(self, props=None)

Update the min,max values of all properties

pysph.base.particle_array.get_ghost_tag() → int
pysph.base.particle_array.get_local_tag() → int
pysph.base.particle_array.get_remote_tag() → int
pysph.base.particle_array.is_ghost(int tag) → bool
pysph.base.particle_array.is_local(int tag) → bool
pysph.base.particle_array.is_remote(int tag) → bool

Convenience functions to create particle arrays

There are several convenience functions that provide a particle array with a requisite set of particle properties that are documented below.

pysph.base.utils.arange_long(start, stop=-1)[source]

Creates a LongArray working same as builtin range with upto 2 arguments both expected to be positive


Returns a replica (empty) of a list of particles

pysph.base.utils.get_particle_array(additional_props=None, constants=None, backend=None, **props)[source]

Create and return a particle array with default properties.

The default properties are [‘x’, ‘y’, ‘z’, ‘u’, ‘v’, ‘w’, ‘m’, ‘h’, ‘rho’, ‘p’, ‘au’, ‘av’, ‘aw’, ‘gid’, ‘pid’, ‘tag’], this set is available in DEFAULT_PROPS.

  • additional_props (list) – If specified, add these properties.
  • constants (dict) – Any constants to be added to the particle array.
Other Parameters:

props (dict) – Additional keywords passed are set as the property arrays.


>>> x = linspace(0,1,10)
>>> pa = get_particle_array(name='fluid', x=x)
['x', 'z', 'rho', 'pid', 'v', 'tag', 'm', 'p', 'gid', 'au',
 'aw', 'av', 'y', 'u', 'w', 'h']
>>> pa1 = get_particle_array(name='fluid', additional_props=['xx', 'yy'])
>>> pa = get_particle_array(name='fluid', x=x, constants={'alpha': 1.0})
>>> pa.constants.keys()
pysph.base.utils.get_particle_array_gasd(constants=None, **props)[source]

Return a particle array for a Gas Dynamics problem.

Parameters:constants (dict) – Dictionary of constants
Other Parameters:
 props (dict) – Additional keywords passed are set as the property arrays.
pysph.base.utils.get_particle_array_iisph(constants=None, **props)[source]

Get a particle array for the IISPH formulation.

The default properties are:

['x', 'y', 'z', 'u', 'v', 'w', 'm', 'h', 'rho', 'p', 'au', 'av', 'aw',
'gid', 'pid', 'tag' 'uadv', 'vadv', 'wadv', 'rho_adv', 'au', 'av',
'aw','ax', 'ay', 'az', 'dii0', 'dii1', 'dii2', 'V', 'aii', 'dijpj0',
'dijpj1', 'dijpj2', 'p', 'p0', 'piter', 'compression'
Parameters:constants (dict) – Dictionary of constants
Other Parameters:
 props (dict) – Additional keywords passed are set as the property arrays.
pysph.base.utils.get_particle_array_rigid_body(constants=None, **props)[source]

Return a particle array for a rigid body motion.

For multiple bodies, add a body_id property starting at index 0 with each index denoting the body to which the particle corresponds to.

Parameters:constants (dict) – Dictionary of constants
Other Parameters:
 props (dict) – Additional keywords passed are set as the property arrays.
pysph.base.utils.get_particle_array_swe(constants=None, **props)[source]

Return a particle array for the shallow water formulation

This sets the default properties to be:

['x', 'y', 'z', 'u', 'v', 'w', 'h', 'rho', 'arho' 'm', 'p', 'V', 'A',
'cs', 'n', 'rho0', 'rho_prev_iter', 'rho_residual',
'positive_rho_residual', 'summation_rho', 'dw', 'alpha', 'exp_lambda',
'tv', 'tu', 'au', 'av', 'u_prev_step', 'v_prev_step', 'uh', 'vh',
'dt_cfl', 'pa_to_split', 'Sfx', 'Sfy', 'psi', 'sum_Ak', 'u_parent',
'v_parent', 'uh_parent', 'vh_parent', 'parent_idx', 'b', 'bx', 'by',
'bxx', 'bxy', byy', 'closest_idx', 'is_merged_pa', 'merge',
'dw_inner_reimann', 'u_inner_reimann', 'v_inner_reimann', 'shep_corr',
'is_wall_boun_pa', 'dw_at_t', 'pa_out_of_domain', 'ob_pa_to_remove',
'ob_pa_to_tag', 'pa_alpha_zero', 'fluid_pa_to_remove']
Parameters:constants (dict) – Dictionary of constants
Other Parameters:
 props (dict) – Additional keywords passed are set as the property arrays.
pysph.base.utils.get_particle_array_tvf_fluid(constants=None, **props)[source]

Return a particle array for the TVF formulation for a fluid.

Parameters:constants (dict) – Dictionary of constants
Other Parameters:
 props (dict) – Additional keywords passed are set as the property arrays.
pysph.base.utils.get_particle_array_tvf_solid(constants=None, **props)[source]

Return a particle array for the TVF formulation for a solid.

Parameters:constants (dict) – Dictionary of constants
Other Parameters:
 props (dict) – Additional keywords passed are set as the property arrays.
pysph.base.utils.get_particle_array_wcsph(constants=None, **props)[source]

Return a particle array for the WCSPH formulation.

This sets the default properties to be:

['x', 'y', 'z', 'u', 'v', 'w', 'h', 'rho', 'm', 'p', 'cs', 'ax', 'ay',
'az', 'au', 'av', 'aw', 'x0','y0', 'z0','u0', 'v0','w0', 'arho',
'rho0', 'div', 'gid','pid', 'tag']
Parameters:constants (dict) – Dictionary of constants
Other Parameters:
 props (dict) – Additional keywords passed are set as the property arrays.

Return the array information for a list of particles.

  • An OrderedDict containing the property information for a list of
  • particles. This dict can be used for example to set-up dummy/empty
  • particle arrays.

Returns True if the given method is overloaded from any of its bases.