Sets and Grids in Codes

This module defines the classes needed to map functions defined by the codes into particle sets and grids.

The attribute values of Particles or Gridpoints are stored in Particle Sets or Grids. These sets or grids manage:

  1. The storage allocation (deletion and removal of particles)

  2. The attribute access (getting or setting the value(s) of attribute(s))

  3. Queries or selections of particles (selection of subsets of particles)

All 3 functions can be provided by a code. The classes in this module provide a mapping from the functions in a code to the datamodel used in AMUSE.

When a code manages a particular set all the data of that set is stored in the memory space of that code. The code needs to provide functions to acces the data in the set.

Note

Most codes already implement a particle set or a grid. The only extra requirement for AMUSE is to provide functions to access this set. When a code does not have any knowlegde of sets or grids, the management will take place in AMUSE and only some data transfer code is needed

All incode storage is build on mapping attributes to functions. These mappings are provided by a number of helper classes:

setter/getter

ParticleGetAttributesMethod

Given particle indices or gridpoints (i,j,k) return a vector quantity for each attribute

ParticleSetAttributesMethod

Send values to the code given particle indices or gridpoints (i,j,k) and a vector quantities for each attribute.

new/delete

NewParticleMethod

Given vector quantities for attributes return the indices of newly allocated particles

function

ParticleMethod

Given particle indices or gridpoints (i,j,k) and optional arguments return one or more vector quantities

selection

ParticleSpecificSelectMethod

Given a particle return a subset of particles. For links between particles (nearest neighbor, subparticle)

ParticleQueryMethod

Retrieve indices from the code and return a subset of particles. For selection of a limited number of particles by the code (get the escaper)

ParticleSetSelectSubsetMethod

Like ParticleQueryMethod but can handle larger subsets of particles, the code can provide a special function the return the number of particles in the set.

The InCode storage system is based on a number of classes:

AbstractInCodeAttributeStorage

Handle attribute set/get functionality but no particle or grid management

InCodeAttributeStorage

Subclass of AbstractInCodeAttributeStorage, manages particles

InCodeGridAttributeStorage

Subclass of AbstractInCodeAttributeStorage, manages grids

class amuse.datamodel.incode_storage.AbstractInCodeAttributeStorage(code_interface, setters, getters, extra_keyword_arguments_for_getters_and_setters={})

Bases: AttributeStorage

Abstract base storage for incode attribute storage. It provides functions to handle getters and setters of attributes but not for creating or deleting of particles as this differs between grids and particle sets.

get_defined_attribute_names()
get_defined_settable_attribute_names()
select_getters_for(attributes)
select_setters_for(attributes)
class amuse.datamodel.incode_storage.InCodeAttributeStorage(code_interface, new_particle_method, delete_particle_method, number_of_particles_method, setters, getters, name_of_the_index)

Bases: AbstractInCodeAttributeStorage

Manages sets of particles stored in codes.

Maps indices returned by the code to keys defined in AMUSE.

add_particles_to_store(keys, attributes=[], values=[])

Adds particles with the given keys to the set. If attribute names and values are specified these are also set for the new particles.

can_extend_attributes()
get_all_indices_in_store()

Gets the list of all valid indices in store.

get_all_keys_in_store()

Gets the list of all keys stored

get_indices_of(keys)
get_key_indices_of(keys)
get_positions_of_indices(indices)
get_value_of(index, attribute)
get_values_in_store(indices_in_the_code, attributes)

Gets the values for the attributes of the particles at the given indices.

get_values_in_store_async(indices_in_the_code, attributes)
has_key_in_store(key)

Returns true if the given key can be found in the store

remove_particles_from_store(indices_in_the_code)

Removes particles with the given keys from the set.

set_values_in_store(indices_in_the_code, attributes, values)

Sets the attributes of the particles at the given indices to the given values.

set_values_in_store_async(indices_in_the_code, attributes, values)
class amuse.datamodel.incode_storage.InCodeGridAttributeStorage(code_interface, get_range_method, setters, getters, extra_keyword_arguments_for_getters_and_setters={})

Bases: AbstractInCodeAttributeStorage

Manages grids stored in codes.

add_particles_to_store(keys, attributes=[], quantities=[])

Adds particles with the given keys to the set. If attribute names and values are specified these are also set for the new particles.

can_extend_attributes()
copy()
get_all_keys_in_store()

Gets the list of all keys stored

get_defined_attribute_names()
get_defined_settable_attribute_names()
get_values_in_store(indices, attributes)

Gets the values for the attributes of the particles at the given indices.

get_values_in_store_async(indices, attributes)
has_key_in_store(key)

Returns true if the given key can be found in the store

remove_particles_from_store(keys)

Removes particles with the given keys from the set.

set_values_in_store(indices, attributes, quantities)

Sets the attributes of the particles at the given indices to the given values.

set_values_in_store_async(indices, attributes, quantities)
storage_shape()
class amuse.datamodel.incode_storage.NewParticleMethod(method, attribute_names=None)

Bases: ParticleSetAttributesMethod

Instances wrap a method to create particles. The method may take attributes values to set initial values on the created particles.

The new particle functions work a lot like the set attribute methods, only the new particle function is supposed to return an array of the indices of the created particles.

indices = instance.new_particle(x, y, z)
add_entities(attributes, values)
class amuse.datamodel.incode_storage.ParticleGetAttributesMethod(method, attribute_names=None)

Bases: ParticleMappingMethod

Instances wrap other methods and provide mappings from attribute names to results.

Simple attribute getter methods take an array of indices and return a tuple with arrays of result values.

x, y, z = instance.get_xyz(indices)

Instances of this class make it possible to access the return values by their attribute names.

For this it employs two strategies:

  1. It uses the provided array of names and maps each name to the positional output.

  2. If no array of names is provided it asks the wrapped method for all the names of the output parameters (this scheme only works for legacy functions or for wrapped legacy functions)

attribute_names
check_arguments(storage, attributes_to_return, *indices)
convert_return_value(return_value, storage, attributes_to_return)
get_attribute_values(storage, attributes_to_return, *indices)
get_attribute_values_async(storage, attributes_to_return, *indices)
class amuse.datamodel.incode_storage.ParticleGetGriddedAttributesMethod(method, get_range_method, attribute_names=None)

Bases: ParticleGetAttributesMethod

get_attribute_values(storage, attributes_to_return, *indices)
class amuse.datamodel.incode_storage.ParticleGetIndexMethod

Bases: object

Instances return the index of a particle in the code

ATTRIBUTE_NAME = 'index_in_code'
attribute_names
get_attribute_values(storage, attributes_to_return, *indices)
class amuse.datamodel.incode_storage.ParticleMappingMethod(method, attribute_names=None)

Bases: AbstractCodeMethodWrapper

name_of_the_indexing_parameter
class amuse.datamodel.incode_storage.ParticleMethod(method, public_name=None)

Bases: AbstractCodeMethodWrapper

Instances wrap a function that returns quanties given particle indices and optional arguments. Instances have a lot in common with attribute getters, but can take extra arguments.

pressure = instance.get_pressure(index, gamma)
apply_on_all(particles, *list_arguments, **keyword_arguments)
apply_on_one(set, particle, *list_arguments, **keyword_arguments)
class amuse.datamodel.incode_storage.ParticleQueryMethod(method, names=(), public_name=None, query_superset=False)

Bases: object

Instances wrap a function that can take one or more arguments and returns an index (or a list of indices, if the arguments are lists). This method is most useful to select one particle form all particles in the set

index = instance.get_escaper()

The index or indices are converted to a particle subset.

apply_for_superset(particles, *args, **kwargs)
apply_normal(particles, *args, **kwargs)
class amuse.datamodel.incode_storage.ParticleSetAttributesMethod(method, attribute_names=None)

Bases: ParticleMappingMethod

Instances wrap other methods and provide mappings from attribute names to input parameters.

Simple attribute setter methods take an array of indices and one or more arrays of new values.

instance.set_xyz(indices, x, y, z)

Instances of this class make it possible to access the possitional parameters with attribute names.

Note

the index argument is assumed to always come first!

For this it employs two strategies:

  1. It uses the provided array of names and maps each name to the positional output.

  2. If no array of names is provided it asks the wrapped method for all the names of the input parameters (this scheme works for legacy functions and sometimes for python native functions (if they have named arguments))

attribute_names
convert_attributes_and_values_to_list_and_keyword_arguments(attributes, values)
names_to_index
optional_attribute_names
set_attribute_values(storage, attributes, values, *indices)
set_attribute_values_async(storage, attributes, values, *indices, **extra_keyword_arguments_for_getters_and_setters)
class amuse.datamodel.incode_storage.ParticleSetGriddedAttributesMethod(method, get_range_method, attribute_names=None)

Bases: ParticleSetAttributesMethod

set_attribute_values(storage, attributes, values, *indices)
set_attribute_values_async(storage, attributes, values, *indices)
class amuse.datamodel.incode_storage.ParticleSetSelectSubsetMethod(method, set_query_arguments_method=None, get_number_of_particles_in_set_method=None, public_name=None)

Bases: object

Generic method to query and retrieve particles from the set. This selection can have up to tree stages:

  1. start the query given a number of optional arguments

  2. get the number of selected particles

  3. get the index of each particle

The pseudo-code for this selection is:

set_selection_criteria(r = 10.0 | units.m)
n = get_number_of_selected_particles()
for i in range(n):
    particle_index = get_index_of_selected_particle(i)

The first and second step are optional. If no number of particles method is provided the class assumes the selection only returns 1 particle.

Generalisation of ParticleQueryMethod

apply_on_all(particles, *list_arguments, **keyword_arguments)
class amuse.datamodel.incode_storage.ParticleSpecificSelectMethod(method, names=(), public_name=None)

Bases: object

Instances wrap a function that can take a particle index and returns one or more indices (but a limited and fixed number of indices). This method is most useful to return links between particles (subparticles or nearest neighbors)

output_index = instance.get_nearest_neigbord(input_index)

The idex or indices are converted to a particle subset.

apply_on_all(particles)
apply_on_one(set, particle)
class amuse.datamodel.incode_storage.ParticleSpecificSelectSubsetMethod(method, get_number_of_particles_in_set_method=None, public_name=None)

Bases: object

Instances wrap a function that can take a particle index, plus a list offset and returns one index. This method is most useful to return links between particles (subparticles or nearest neighbors). Instances also need a function to get the number of links.

output_index = instance.get_nearest_neigbors(index_of_the_particle, input_index)

The index or indices are converted to a particle subset.

apply_on_all(particles)
apply_on_one(set, particle)
class amuse.datamodel.incode_storage.ParticlesAddedUpdateMethod(get_number_of_particles_added_method=None, get_id_of_added_particles_method=None)

Bases: object

apply_on_all(particles, *list_arguments, **keyword_arguments)