Module particle_array
The ParticleArray class itself is documented as below.
A ParticleArray represents a collection of particles.
- class pysph.base.particle_array.ParticleArray(str name='', default_particle_tag=Local, constants=None, backend=None, **props)
Class to represent a collection of particles.
- name
name of this particle array.
- Type:
str
- properties
dictionary of {prop_name:carray}.
- Type:
dict
- constants
dictionary of {const_name: carray}
- Type:
dict
Examples
There are many ways to create a ParticleArray:
>>> p = ParticleArray(name='fluid', x=[1.,2., 3., 4.]) >>> p.name 'fluid' >>> p.x, p.tag, p.pid, 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() 'int'
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.]})
Constructor
- Parameters:
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.
- __reduce__(self)
Implemented to facilitate pickling of extension types
- __setstate__(self, d)
Load the particle array object from the saved dictionary
- add_constant(self, str 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.
- Parameters:
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.
Notes
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, str name, str type='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.
- Parameters:
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.
Notes
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.
Warning
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.
Notes
Pseudo-code:
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 else index_arr[i] = i next_insert += 1 else 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
- backend
str
- Type:
backend
- clear(self)
Clear all data held by this array
- constants
dict
- Type:
constants
- 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.
Examples
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
- Parameters:
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
- default_values
dict
- Type:
default_values
- 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
- Parameters:
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.
Notes
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.
- argsadditional args
a list of property names.
Notes
The returned numpy array does NOT own its data. Other operations may be performed.
- Return type:
Numpy array.
- get_carray(self, str prop) BaseArray
Return the c-array for the property or constant.
- get_lb_props(self)
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.
- Parameters:
all (bint) – Flag to select all arrays
only_real (bint) – Flag to select Local/Remote particles
Notes
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
- gpu
object
- Type:
gpu
- has_array(self, str arr_name)
Returns true if the array arr_name is present
- name
str
- Type:
name
- num_real_particles
‘long’
- Type:
num_real_particles
- output_property_arrays
list
- Type:
output_property_arrays
- properties
dict
- Type:
properties
- property_arrays
list
- Type:
property_arrays
- 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.
Notes
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 array.remove(sorted_indices)
- remove_property(self, str 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.
Notes
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, str 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
Notes
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)
- stride
dict
- Type:
stride
- time
‘double’
- Type:
time
- 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
- pysph.base.utils.create_dummy_particles(info)[source]
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.
- Parameters:
additional_props (list) – If specified, add these properties.
constants (dict) – Any constants to be added to the particle array.
props (dict) – Additional keywords passed are set as the property arrays.
Examples
>>> x = linspace(0,1,10) >>> pa = get_particle_array(name='fluid', x=x) >>> pa.properties.keys() ['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() ['alpha']
- 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
props (dict) – Additional keywords passed are set as the property arrays.
See also
- 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
props (dict) – Additional keywords passed are set as the property arrays.
See also
- 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
props (dict) – Additional keywords passed are set as the property arrays.
See also
- 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
props (dict) – Additional keywords passed are set as the property arrays.
See also
- 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
props (dict) – Additional keywords passed are set as the property arrays.
See also
- 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
props (dict) – Additional keywords passed are set as the property arrays.
See also
- 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
props (dict) – Additional keywords passed are set as the property arrays.
See also