M2 library

SUSUKITA, Ryutaro¹

The M2 library is used to access and manipulate the MDGRAPE-2 boards from C programs. The library can be linked with the parameters "-L/usr/local/lib -lm2"

Units
m2_allocate_unit
m2_allocate_periodic_unit
m2_free_unit
m2_get_num_pipelines
m2_set_host_function
m2_set_positions
m2_set_rscale
m2_set_rscales
m2_set_rscale_matrix
m2_set_charge
m2_set_charges
m2_set_charge_matrix
m2_set_types
m2_set_pipeline_types
m2_set_softening
m2_set_softenings
m2_set_softening_matrix
m2_set_pipeline_softenings
m2_set_particle_offset
m2_set_cells
m2_set_neighbor_radius
m2_set_neighbor_radii
m2_set_neighbor_radius_matrix
m2_set_pipeline_neighbor_radii
m2_calculate_forces
m2_calculate_potentials
m2_start_force_calculation
m2_start_potential_calculation
m2_wait_calculation
m2_get_neighbors

Groups
m2_allocate_group
m2_allocate_member
m2_allocate_periodic_member
m2_free_group
m2_get_num_group_pipelines
m2_set_member_positions
m2_wait_member_calculation

Units

A unit is a logical unit resources of one or more MDGRAPE-2 boards are allocated for. Units have all data necessary to use MDGRAPE-2. For units, M2 library provides the following functions. The functions and identifiers used for the functions are declared in "m2_unit.h".

• M2_UNIT *m2_allocate_unit(const char *function, int mode, double lower, double upper, int num_pipelines)

  m2_allocate_unit allocates a unit. Resources which are not currently allocated for other units and groups (see section 2) are allocated.

  
  

  Table 1: Function tables and C-langauge functions included in M2 library.

  function table

  C-langauge function

  force or potential function

  grav.table

  m2_grav

  $-w^{-1.5}$

  gravpot.table

  m2_gravpot

  $w^{-0.5}$

  lj.table

  m2_lj

  $-2 w^{-7} + w^{-4}$	if $0.25 \leq w \leq 64$
  $0$	otherwise

  ljpot.table

  m2_ljpot

  $w^{-6} - w^{-3}$	if $0.25 \leq w \leq 64$
  $0$	otherwise

  real.table

  m2_real

  $-(2 e^{-w} / (\sqrt{\pi} w) + {\rm erfc}(\sqrt{w}) w^{-1.5})$

  realpot.table

  m2_realpot

  ${\rm erfc}(\sqrt{w}) w^{-0.5}$

  
  

  function specifies the function table which corresponds a force function or a potential function calculated by the unit. M2 library includes the function tables listed in Table 1.

  mode must be M2_FORCE or M2_POTENTIAL if the function represents a force or a potential, respectively.

  lower and upper specify the range which includes coordinates of positions of particles which appear in the calculation of force or potential. lower and upper must be less and greater than all the coordinates, respectively. If the specified range is wider than it must be, the accuracy of the calculation may not be optimized.

  num_pipelines specifies the number of pipelines allocated for the unit.

  The environment variable M2_ON specifies a list of boards. The pipelines on only the boards are allowed to be allocated for the unit. M2_ON must be a list of board numbers or ranges of board numbers. The numbers or the ranges must be separated by ,. A range of $b_1$-$b_2$ is equivalent to $b_1$,...,$b_2$. If M2_ON is not set, all boards are allowed to be allocated.

  The environment variable M2_SIZE specifies the number of boards if num_pipelines is NULL_INT. The pipelines on boards of the number are allocated for the unit. If M2_SIZE is not set, pipelines on all boards are allocated.

  The particle offset of the unit is set to 0.

  m2_allocate_unit returns a pointer to the unit on success. It returns NULL on failure.

• M2_UNIT *m2_allocate_periodic_unit(const char *function, int mode, double period, int num_pipelines)

  m2_allocate_periodic_unit is similar to m2_allocate_unit except that period specifies the period of the unit.

• void m2_free_unit(M2_UNIT *mu)

  m2_free_unit frees the unit mu.

• int m2_get_num_pipelines(const M2_UNIT *mu)

  m2_get_num_pipelines returns the number of pipelines allocated for the unit mu.

• void m2_set_host_function(M2_UNIT *mu, double (*f)(double))

  m2_set_host_function sets the C-langauge function which corresponds to a force function or a potential function calculated by the unit mu to f. M2 library includes the C-langauge functions listed in Table 1.

• void m2_set_positions(M2_UNIT *mu, double (*rj)[3], long n)

  m2_set_positions sets the positions of particle $j_0$, ..., particle $j_0 + {\tt n} - 1$ of the unit mu to the 2-dimensional array rj, where $j_0$ is the particle offset of the unit. rj[j][0], rj[j][1] and rj[j][2] specify the x, y and z coordinates of the position of particle $j_0 + {\tt j}$, respectively. If m2_set_cells was not called and the particle offset of the unit is 0, m2_set_positions sets the number of the cells of the unit to 1 and the base and sets the number of the particles of cell 0 to 0 and n, respectively.

• void m2_set_rscale(M2_UNIT *mu, double a)

  m2_set_rscale set the rscale of the unit mu to a. a must be 0 or positive.

• void m2_set_rscales(M2_UNIT *mu, const double *aj, long n)

  m2_set_rscales sets the rscale of particle $j_0$, ..., the rscale of particle $j_0 + {\tt n} - 1$ of the unit mu to aj[0], ..., aj[n - 1], respectively, where $j_0$ is the particle offset of the unit. aj[0], ..., aj[n - 1] must be 0 or positive. If any two of the charge, the softening and the neighbor radius of each particle of the unit were set, m2_set_rscales fails.

• void m2_set_rscale_matrix(M2_UNIT *mu, const double *acicj, int nci, int ncj)

  m2_set_rscale_matrix sets the rscale matrix of the unit mu to an ${\tt nci} \times {\tt ncj}$ matrix whose component (i, j) is specified by acicj[i * ncj + j]. acicj[0], ..., acicj[nci * ncj - 1] must be 0 or positive. If any two of charge matrix, softening matrix and neighbor radius matrix of the unit were set, m2_set_rscale_matrix fails.

• void m2_set_charge(M2_UNIT *mu, double b)

  m2_set_charge set the charge of the unit mu to b.

• void m2_set_charges(M2_UNIT *mu, const double *bj, long n)

  m2_set_charges sets the charge of particle $j_0$, ..., the charge of particle $j_0 + {\tt n} - 1$ of the unit mu to bj[0], ..., bj[n - 1], respectively, where $j_0$ is the particle offset of the unit. If any two of the rscale, the softening and the neighbor radius of each particle of the unit were set, m2_set_charges fails.

• void m2_set_charge_matrix(M2_UNIT *mu, const double *bcicj, int nci, int ncj)

  m2_set_charge_matrix sets the charge matrix of the unit mu to an ${\tt nci} \times {\tt ncj}$ matrix whose component (i, j) is specified by bcicj[i * ncj + j]. If any two of rscale matrix, softening matrix and neighbor radius matrix of the unit were set, m2_set_charge_matrix fails.

• void m2_set_types(M2_UNIT *mu, const int *cj, long n)

  m2_set_types sets the types of particle $j_0$, ..., the type of particle $j_0 + {\tt n} - 1$ of the unit mu to cj[0], ..., cj[n - 1], respectively, where $j_0$ is the particle offset of the unit.

• void m2_set_pipeline_types(M2_UNIT *mu, const int *ci, long n)

  m2_set_pipeline_types sets the types of the particles on which forces are calculated by m2_calculate_forces or whose potentials are calculated by m2_calculate_potential afterwards. mu specifies the unit. ci[0], ..., ci[n - 1] specify the type of particle 0, ..., the type of particle ${\tt n} - 1$, respectively.

• void m2_set_softening(M2_UNIT *mu, double e)

  m2_set_softening sets the softening of the unit mu to e.

• void m2_set_softenings(M2_UNIT *mu, const double *ej, long n)

  m2_set_softenings sets the softening of particle $j_0$, ..., the softening of particle $j_0 + {\tt n} - 1$ of the unit mu to ej[0], ..., ej[n - 1], respectively, where $j_0$ is the particle offset of the unit. If any two of the rscale, the charge and the neighbor radius of each particle of the unit were set, m2_set_softenings fails.

• void m2_set_softening_matrix(M2_UNIT *mu, const double *ecicj, int nci, int ncj)

  m2_set_softening_matrix sets the softening matrix of the unit mu to an ${\tt nci} \times {\tt ncj}$ matrix whose component (i, j) is specified by ecicj[i * ncj + j]. If any two of rscale matrix, charge matrix and neighbor radius matrix of the unit were set, m2_set_softening_matrix fails.

• void m2_set_pipeline_softenings(M2_UNIT *mu, const double *ei, long n)

  m2_set_pipeline_softenings sets the softenings of the particles on which forces are calculated by m2_calculate_forces or whose potentials are calculated by m2_calculate_potential afterwards. mu specifies the unit. ei[0], ..., ei[n - 1] specify the softening of particle 0, ..., the softening of particle ${\tt n} - 1$, respectively.

• void m2_set_particle_offset(M2_UNIT *mu, long offset)

  m2_set_particle_offset sets the particle offset of the unit mu to offset.

• void m2_set_cells(M2_UNIT *mu, const M2_CELL *cells, int n)

  m2_set_cells sets cell 0, ..., cell ${\tt n} - 1$ of the unit mu to cells[0], ..., cells[n - 1], respectively. The M2_CELL structure contains the following members

  long base
  long size
  cells[k].base and cells[k].size specify the base and the number of the particles of cell k, respectively.

• void m2_set_neighbor_radius(M2_UNIT *mu, double h)

  m2_set_neighbor_radius sets the neighbor radius of the unit mu to h. h must be 0 or positive.

• void m2_set_neighbor_radii(M2_UNIT *mu, const double *hj, long n)

  m2_set_neighbor_radii sets the neighbor radius of particle $j_0$, ..., the neighbor radius of particle $j_0 + {\tt n} - 1$ of the unit mu to hj[0], ..., hj[n - 1], respectively, where $j_0$ is the particle offset of the unit. hj[0], ..., hj[n - 1] must be 0 or positive. If any two of the rscale, the charge and the softening of each particle of the unit were set, m2_set_neighbor_radii fails.

• void m2_set_neighbor_radius_matrix(M2_UNIT *mu, const double *hcicj, int nci, int ncj)

  m2_set_neighbor_radius_matrix sets the neighbor radius matrix of the unit mu to an ${\tt nci} \times {\tt ncj}$ matrix whose component (i, j) is specified by hcicj[i * ncj + j]. hcicj[0], ..., hcicj[nci * ncj - 1] must be 0 or positive. If any two of rscale matrix, charge matrix and softening matrix of the unit were set, m2_set_neighbor_radius_matrix fails.

• void m2_set_pipeline_neighbor_radii(M2_UNIT *mu, const double *hi, long n)

  m2_set_pipeline_neighbor_radii sets the neighbor radii of the particles on which forces are calculated by m2_calculate_forces or whose potentials are calculated by m2_calculate_potential afterwards. mu specifies the unit. hi[0], ..., hi[n - 1] specify the neighbor radius of particle 0, ..., the neighbor radius of particle ${\tt n} - 1$, respectively. hi[0], ..., hi[n - 1] must be 0 or positive.

• void m2_calculate_forces(M2_UNIT *mu, double (*ri)[3], long n, double (*fi)[3])

  m2_calculate_forces calculates the force exerted on each given particle and searches for neighbors of the particle.

  mu specifies the unit which calculates and searches.

  The 2-dimensional array ri specifies the positions of particle 0, ..., particle ${\tt n} - 1$. ri[i][0], ri[i][1] and ri[i][2] specify the x, y and z coordinates of the position of particle i, respectively.

  The force exerted on the given particle $i$ is calculated as
  

  $$\mbox{\boldmath$f$}_i = \sum_{c = 0}^{N - 1} \: \sum_{j = j_{... ...r$}_{ij}\vert^2 + {\epsilon_{ij}}^2))\mbox{\boldmath$r$}_{ij},$$
  
  
  where terms with $r$$_{ij} = 0$ are excluded. These quantities represent as follows:

  $N$	the number of the cells
  $j_{0_c}$	the base of cell $c$
  $n_c$	the number of the particles of cell $c$
  $g(w)$	the force function

  If the unit was allocated by m2_allocate_unit,
  
  $$\mbox{\boldmath$r$}_{ij} = \mbox{\boldmath$r$}_j' - \mbox{\boldmath$r$}_i,$$
  
  
  where $\mbox{\boldmath$r$}_j'$ is the position of particle $j$ of the unit and $\mbox{\boldmath$r$}_i$ is the position of the given particle $i$. If the unit was allocated by m2_allocate_periodic_unit,
  
  $$\mbox{\boldmath$r$}_{ij} = \mbox{\boldmath$r$}_j' - \mbox{\boldmath$r$}_i + (n_xl, \: n_yl, \: n_zl),$$
  
  
  where $l$ is the period of the unit and the integers $n_x$, $n_y$ and $n_z$ are chosen such that each coordinate of $r$$_{ij}$ is equal to or greater than $-l / 2$ and less than $l / 2$. If the rscale of the unit was set to $A$,
  
  $$a_{ij} = A.$$
  
  
  If the rscale of each particle $j$ of the unit was set to $A'_j$,
  
  $$a_{ij} = A'_j.$$
  
  
  If the rscale matrix of the unit was set to $\bf A''$, the type of each particle $j$ of the unit was set to $c_j$ and the type of each given particle $i$ was set to $c_i$,
  
  $$a_{ij} = A''_{c_ic_j}.$$
  
  
  Otherwise,
  
  $$a_{ij} = 1.$$
  
  
  The coefficient $b_{ij}$ is determined in a similar way to $a_{ij}$ except that $b_{ij}$ is determined from charge. If the softening of the unit was set to $E$,
  
  $$\epsilon_{ij} = E.$$
  
  
  If the softening of each particle $j$ of the unit was set to $E'_j$,
  
  $$\epsilon_{ij} = E'_j.$$
  
  
  If the softening matrix of the unit was set to $\bf E''$, the type of each particle $j$ of the unit was set to $c_j$ and the type of each given particle $i$ was set to $c_i$,
  
  $$\epsilon_{ij} = E''_{c_ic_j}.$$
  
  
  If the softening of each given particle $i$ was set to $E'''_i$,
  
  $$\epsilon_{ij} = E'''_i.$$
  
  
  Otherwise,
  
  $$\epsilon_{ij} = 0.$$
  
  

  As neighbors of the given particle $i$, particles of the unit which satisfy $\vert\mbox{\boldmath$r$}_{ij}\vert < h_{ij}$ are searched for, where the coefficient $h_{ij}$ is determined in a similar way to $\epsilon_{ij}$ except that $h_{ij}$ is determined from neighbor radius.

  The 2-dimensional array fi returns $\mbox{\boldmath$f$}_0$, ..., $\mbox{\boldmath$f$}_{\tt {n} - 1}$. fi[i][0], fi[i][1] and fi[i][2] returns the x, y and z coordinate of $\mbox{\boldmath$f$}_{\tt i}$, respectively.

• void m2_calculate_potentials(M2_UNIT *mu, double (*ri)[3], long n, double *pi)

  m2_calculate_potentials is similar to m2_calculate_forces except that the potential of each given particle is calculated. The potential of the given particle $i$ is calculated as
  

  $$\phi_i = \sum_{c = 0}^{N - 1} \: \sum_{j = j_{0_c}}^{j_{0_c} ... ...} (\vert\mbox{\boldmath$r$}_{ij}\vert^2 + {\epsilon_{ij}}^2)),$$
  
  
  where terms with $r$$_{ij} = 0$ are excluded. pi[0], ..., pi[n - 1] returns $\phi_0$, ..., $\phi_{\tt {n} - 1}$, respectively.

• void m2_start_force_calculation(M2_UNIT *mu, double (*ri)[3], long n, double (*fi)[3])

  m2_start_force_calculation is similar to m2_calculate_forces except that the array fi return the forces after m2_wait_calculation is called for the unit mu and the array fi may not return the forces if any element of the array ri is changed before m2_wait_calculation is called for the unit mu.

• void m2_start_potential_calculation(M2_UNIT *mu, double (*ri)[3], long n, double *pi)

  m2_start_potential_calculation is similar to m2_calculate_potentials except that the array pi returns the potentials after m2_wait_calculation is called for the unit mu and the array pi may not return the potentials if any element of the array ri is changed before m2_wait_calculation is called for the unit mu.

• void m2_wait_calculation(M2_UNIT *mu)

  See m2_start_force_calculation and m2_start_potential_calculation.

• long *m2_get_neighbors(const M2_UNIT *mu, long *nli, long n)

  m2_get_neighbors is called to get the neighbors which were found by m2_calculate_forces or m2_calculate_potentials.

  mu specifies the unit which found the neighbors.

  m2_get_neighbors allocates memory to contain the particle number of the neighbors. nli[0], ..., nli[n - 1] returns offsets in the memory to be referred to as follows: l[0], ..., l[nli[0] - 1] return the particle numbers of the neighbors of particle 0, respectively, where l is a pointer to the memory and the type is long *. ... l[nli[n - 2]], ..., l[nli[n - 1] - 1] return the particle numbers of the neighbors of particle ${\tt n} - 1$, respectively.

  m2_get_neighbors returns a pointer to the memory. The memory is freed by free.

Groups

A group is a group of units resources of one or more MDGRAPE-2 boards are allocated for. For groups, M2 library provides the following functions. The functions and identifiers for the functions are declared in "m2_group.h".

• M2_GROUP *m2_allocate_group(int num_pipelines)

  m2_allocate_group allocates a group which has no units. Resources which are not currently allocated for other unit groups and units are allocated. The number of allocated pipelines is determined in a similar way to m2_allocate_unit. m2_allocate_group returns a pointer to the group on success. It returns NULL on failure.

• M2_UNIT *m2_allocate_member(M2_GROUP *mg, const char *function, int mode, double lower, double upper, int num_pipelines, unsigned int private)

  m2_allocate_member is similar to m2_allocate_unit except that the allocated unit becomes a member of the unit group mg and quantities of the unit private does not specify may be shared. If a quantity is shared, a library function called to set the quantity of the unit also sets the same quantities of other member units of the group. If a quantity is not shared, it is private. private must be 0, NULL_UNSIGNED or the bitwise inclusive OR of one or more of the following flags:

  flag	quantity of unit
  M2_POSITIONS	positions of particles
  M2_RSCALE	rscale
  M2_RSCALES	rscales of particles
  M2_RSCALE_MATRIX	rscale matrix
  M2_CHARGE	charge
  M2_CHARGES	charges of particles
  M2_CHARGE_MATRIX	charge matrix
  M2_NEIGHBOR_RADIUS	neighbor radius
  M2_NEIGHBOR_RADII	neighbor radii of particles
  M2_NEIGHBOR_RADIUS_MATRIX	neighbor radius matrix
  M2_SOFTENING	softening
  M2_SOFTENINGS	softenings of particles
  M2_SOFTENING_MATRIX	softening matrix
  M2_TYPES	types of particles
  M2_CELLS	cells
  M2_PARTICLE_OFFSET	particle offset

  If private is 0, no quantities are private. If private is NULL_UNSIGNED, all quantities are private. If private is the bitwise inclusive OR of one or more of these flags, the quantity which corresponds to each flag is private. If num_pipelines is too large or the number of private quantities are larger than it must be, m2_allocate_member may fails.

• M2_UNIT *m2_allocate_periodic_member(M2_GROUP *mg, const char *function, int mode, double period, int num_pipelines, unsigned int private)

  m2_allocate_periodic_member is similar to m2_allocate_member except that period specifies the period of the unit.

• void m2_free_group(M2_GROUP *mg)

  m2_free_group frees all member units of the group mg and the group.

• int m2_get_num_group_pipelines(const M2_GROUP *mg)

  m2_get_num_group_pipelines returns the number of pipelines allocated for the group mg.

• void m2_set_member_positions(M2_GROUP *mg, double (*rj)[3], long n)

  m2_set_member_positions is equivalent to calling m2_set_positions for each member unit of the group mg.

• void m2_wait_member_calculation(M2_GROUP *mg)

  m2_wait_member_calculation is equivalent to calling m2_wait_calculation for each member unit of the group mg.

About this document ...

M2 library

This document was generated using the LaTeX2HTML translator Version 99.2beta6 (1.42)

Copyright © 1993, 1994, 1995, 1996, Nikos Drakos, Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999, Ross Moore, Mathematics Department, Macquarie University, Sydney.

The command line arguments were:
latex2html -split 0 document

The translation was initiated by on 2001-05-10

Footnotes

... Ryutaro¹

susukita@postman.riken.go.jp