Commit 6cecf2c4 authored by BRAMAS Berenger's avatar BRAMAS Berenger
Browse files

Update API

parent 17c11eb2
......@@ -18,11 +18,34 @@
/**
* @file
* This file defines the API for the USER. The objective is to
* This file defines the API for the C USER. The objective is to
* provide an unified way to compute the Fast Multipole Method with
* ScalFMM's algorithm. The mathematical kernel used can be a user's
* one or ScalFMM implementation of Chebyshev Interpolation or
* Lagrange Interpolation.
* ScalFMM's algorithm. The mathematical kernel used can be defined by
* the user (we refer to user_kernel) or one of the ScalFMM kernels
* (Chebyshev Interpolation or Lagrange Interpolation).
*
* @section Scalfmm Handle
*
* @section Particle indexes
* A index is assign to each particle inserted in the tree.
* It correspond to its position (the first particle has index 0 and so on).
* It is then possible to interact with particles using these indexes.
* Moreover, these indexes are used when get/set function are called,
* (the data for a particle are read/copy using its index).
*
* @section Function names
* Several functions are made to insert, set/get particles data.
* Most these functions have the following syntaxe rule:
* @code {void,int} name_{get,set,add}_properties_[xyz]_[nparts](Handle [, parameters]);
* {void,int} : The function return "int" in case of error code returned.
* {get,set,add} : In case of "get" the data are copied from the particles,
* in case of "set" the data are copied to the particles, and
* in case of "add" the values are add to the particles ones (+=)
* [xyz] : When the values to work on are in shape of an unique array composed
* of 3 values per particles x1y1z1.x2y2z2, ...
* [nparts] : Should be used to work on a part of particles and not all of them.
* In this case an array of int is given in parameter to give the indexes of the particles
* to work on.
*/
......@@ -35,13 +58,13 @@
* Enum over the different kernel usable
*/
typedef enum kernel_type {
user_defined_kernel = 0, /** Case if user provides a complete
* kernel, ie all the needed function to
* compute FMM */
chebyshev = 1, /** Case if user uses ScalFMM's implementation of
* Chebyshev Interpolation */
lagrange = 2, /** Case if user uses ScalFMM's implementation of
* Lagrange Interpolation*/
user_defined_kernel = 0, /** Case if user provides a complete
* kernel, ie all the needed function to
* compute FMM */
chebyshev = 1, /** Case if user uses ScalFMM's implementation of
* Chebyshev Interpolation */
lagrange = 2, /** Case if user uses ScalFMM's implementation of
* Lagrange Interpolation*/
} scalfmm_kernel_type;
......@@ -81,26 +104,24 @@ scalfmm_handle scalfmm_init(int TreeHeight,double BoxWidth,double* BoxCenter, sc
*
* The parts will be inserted with their indices inside the
* array. Each index will be unique.
*
* In case several calls are performed to scalfmm_tree_insert_arrays,
* first call with N particles, and then with M particles.
* The second call particles will have index from [N ; N+M].
*
* Default physical values, potential and forces are set to 0.
*/
void scalfmm_tree_insert_arrays(scalfmm_handle Handle, int NbPositions, double * arrayX, double * arrayY, double * arrayZ);
void scalfmm_tree_insert_particles(scalfmm_handle Handle, int NbPositions, double * arrayX, double * arrayY, double * arrayZ);
/**
* @brief This function insert an array of position into the octree
* @param Handle scalfmm_handle provided by scalfmm_init.
* @param NbPositions Number of position to be inserted
* @param XYZ Array containing the X,Y,Z coordinates for all the
* parts, sequentially stored. Size : NbPositions*3
*
* The parts will be inserted with their indices inside the
* array. Each index will be unique.
* This function is equivalent to scalfmm_tree_insert_particles
* but the given array XYZ should contains a triple value per paticles.
*/
void scalfmm_tree_insert_positions(scalfmm_handle Handle, int NbPositions, double * XYZ);
void scalfmm_tree_insert_particles_xyz(scalfmm_handle Handle, int NbPositions, double * XYZ);
/**
* @brief This function insert an array of physical values into the octree
* @brief This function set the physical values of all the particles
* @param Handle scalfmm_handle provided by scalfmm_init.
* @param nbPhysicalValues Number of physical values to be
* inserted. Must be equal to the number of positions previously
......@@ -109,10 +130,30 @@ void scalfmm_tree_insert_positions(scalfmm_handle Handle, int NbPositions, doubl
* associated to each parts.
*
* The physical values will be stored according to their indices in
* the array
*
* the array. First particle inserted will take value physicalValues[0].
*/
void scalfmm_set_physical_values(scalfmm_handle Handle, int nbPhysicalValues, double * physicalValues);
void scalfmm_get_physical_values(scalfmm_handle Handle, int nbPhysicalValues, double * physicalValues);
/**
*
* @param Handle scalfmm_handle provided by scalfmm_init.
* @param nbPhysicalValues the number of particles to set the physical values to
* @param idxOfParticles an array of indexes of size nbPhysicalValues to know which particles
* to set the values to.
* @param physicalValues the physical values.
*
* For example to set the physical values to particles 0 and 1 to values 1.1 and 1.4:
* @code nbPhysicalValues = 2;
* @code idxOfParticles = {0 , 1};
* @code physicalValues = {1.1 , 1.4};
*
* Be aware that such approach requiere to find particles in the tree which can have high cost.
*/
void scalfmm_set_physical_values_npart(scalfmm_handle Handle, int nbPhysicalValues,
int* idxOfParticles, double * physicalValues);
void scalfmm_get_physical_values_npart(scalfmm_handle Handle, int nbPhysicalValues,
int* idxOfParticles, double * physicalValues);
/**
......@@ -126,7 +167,10 @@ void scalfmm_set_physical_values(scalfmm_handle Handle, int nbPhysicalValues, do
* Forces will be stored sequentially, according to the indices in the
* array. (ie fx1,fy1,fz1,fx2,fy2,fz2,fx3 ....)
*/
void scalfmm_get_forces_xyz(scalfmm_handle Handle, int nbParts, double * forcesToFill);
void scalfmm_get_forces(scalfmm_handle Handle, int nbParts, double * forcesToFill);
void scalfmm_get_forces_npart(scalfmm_handle Handle, int nbParts, int* idxOfParticles, double * forcesToFill);
void scalfmm_get_forces_xyz(scalfmm_handle Handle, int nbParts, double * fX, double* fY, double* fZ);
void scalfmm_get_forces_xyz_npart(scalfmm_handle Handle, int nbParts, int* idxOfParticles, double * fX, double* fY, double* fZ);
/**
......@@ -142,8 +186,10 @@ void scalfmm_get_forces_xyz(scalfmm_handle Handle, int nbParts, double * forcesT
* forces . WARNING : User must allocate the array before call.
*
*/
void scalfmm_get_forces(scalfmm_handle Handle, int nbParts, double * forcesX, double * forcesY, double * forcesZ);
void scalfmm_set_forces(scalfmm_handle Handle, int nbParts, double * forcesToFill);
void scalfmm_set_forces_npart(scalfmm_handle Handle, int nbParts, int* idxOfParticles, double * forcesToFill);
void scalfmm_set_forces_xyz(scalfmm_handle Handle, int nbParts, double * fX, double* fY, double* fZ);
void scalfmm_set_forces_xyz_npart(scalfmm_handle Handle, int nbParts, int* idxOfParticles, double * fX, double* fY, double* fZ);
/**
......@@ -158,6 +204,9 @@ void scalfmm_get_forces(scalfmm_handle Handle, int nbParts, double * forcesX, do
* array.
*/
void scalfmm_get_potentials(scalfmm_handle Handle, int nbParts, double * potentialsToFill);
void scalfmm_set_potentials(scalfmm_handle Handle, int nbParts, double * potentialsToFill);
void scalfmm_get_potentials_npart(scalfmm_handle Handle, int nbParts, int* idxOfParticles, double * potentialsToFill);
void scalfmm_set_potentials_npart(scalfmm_handle Handle, int nbParts, int* idxOfParticles, double * potentialsToFill);
/**
......@@ -169,7 +218,10 @@ void scalfmm_get_potentials(scalfmm_handle Handle, int nbParts, double * potenti
* @param updatedXYZ array of displacement (ie
* dx1,dy1,dz1,dx2,dy2,dz2,dx3 ...)
*/
void scalfmm_update_positions(scalfmm_handle Handle, int NbPositions, double * updatedXYZ)
void scalfmm_add_to_positions(scalfmm_handle Handle, int NbPositions, double * updatedXYZ);
void scalfmm_add_to_positions_xyz(scalfmm_handle Handle, int NbPositions, double * X, double * Y , double * Z);
void scalfmm_add_to_positions_npart(scalfmm_handle Handle, int NbPositions, int* idxOfParticles, double * updatedXYZ);
void scalfmm_add_to_positions_xyz_npart(scalfmm_handle Handle, int NbPositions, int* idxOfParticles, double * X, double * Y , double * Z);
/**
......@@ -187,7 +239,16 @@ void scalfmm_update_positions(scalfmm_handle Handle, int NbPositions, double * u
* compliant.
*
*/
int scalfmm_change_positions(scalfmm_handle Handle, int NbPositions, double * newXYZ)
void scalfmm_set_positions(scalfmm_handle Handle, int NbPositions, double * updatedXYZ);
void scalfmm_set_positions_xyz(scalfmm_handle Handle, int NbPositions, double * X, double * Y , double * Z);
void scalfmm_set_positions_npart(scalfmm_handle Handle, int NbPositions, int* idxOfParticles, double * updatedXYZ);
void scalfmm_set_positions_xyz_npart(scalfmm_handle Handle, int NbPositions, int* idxOfParticles, double * X, double * Y , double * Z);
void scalfmm_get_positions(scalfmm_handle Handle, int NbPositions, double * updatedXYZ);
void scalfmm_get_positions_xyz(scalfmm_handle Handle, int NbPositions, double * X, double * Y , double * Z);
void scalfmm_get_positions_npart(scalfmm_handle Handle, int NbPositions, int* idxOfParticles, double * updatedXYZ);
void scalfmm_get_positions_xyz_npart(scalfmm_handle Handle, int NbPositions, int* idxOfParticles, double * X, double * Y , double * Z);
......@@ -198,6 +259,18 @@ int scalfmm_change_positions(scalfmm_handle Handle, int NbPositions, double * ne
///////////////// User kernel part :
/**
* @param user_kernel Scalfmm_Kernel_Descriptor containing callbacks
* to user Fmm function. Meaningless if using one of our kernel
* (Chebyshev or Interpolation).
* @param userDatas Data that will be passed to each FMM
* function. Can be anything, but allocation/deallocation is user
* side.
*
*/
void scalfmm_user_kernel_config(scalfmm_handle Handle, Scalfmm_Kernel_Descriptor userKernel, void * userDatas);
/**
* @brief Function to be filled by user's P2M
......@@ -286,22 +359,11 @@ struct Scalfmm_Kernel_Descriptor {
//To fill gestion des cellules utilisateurs
///////////////// Common kernel part : /////////////////
/**
*
* @brief This function launch the fmm on the parameters given
* @param Handle scalfmm_handle provided by scalfmm_init
* @param user_kernel Scalfmm_Kernel_Descriptor containing callbacks
* to user Fmm function. Meaningless if using one of our kernel
* (Chebyshev or Interpolation).
* @param userDatas Data that will be passed to each FMM
* function. Can be anything, but allocation/deallocation is user
* side.
*
*/
void scalfmm_execute_kernel(scalfmm_handle Handle, Scalfmm_Kernel_Descriptor userKernel, void * userDatas)
void scalfmm_execute_fmm(scalfmm_handle Handle);
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment