Gravity Pipes (GRAPEs)

MDGRAPE-2 Programming

Access to the MDGRAPE-2 boards is provided by link libraries. Two versions exist: one which accesses the MDGRAPE-2 through the operating system's PCI device drivers (lib*pcim.a), and a second library (lib*host.a) which emulates the MDGRAPE-2 boards on the host machine but does not require the MDGRAPE-2 boards or device drivers to be installed. Files and links of interest to MDGRAPE-2 programmers include: 

/usr/local/include            Directory for C include files
/usr/local/lib/m2             Directory for Fortran include files
/usr/local/lib/libm2.a        M2 library which uses the MDGRAPE-2 boards
/usr/local/lib/libm2host.a    M2 library using host CPU instead of MDGRAPE-2 boards
/usr/local/lib/libmd1pcim.a   MDOne library which uses the MDGRAPE-2 boards
/usr/local/lib/libmd1host.a   MDOne library using host CPU instead of MDGRAPE-2 boards
/usr/local/bin                Directory for initialization commands
$MDGRAPE-2/gentable             Program to generate example Function Evalulator Tables
Fortran API documentaion      Fortran subroutine calls(HTML or PostScript)
C API documentaion            C function calls (HTML or PostScript)
To compile and link a program to use the MDGRAPE-2, use a compile command like: 
    g77 -I/usr/local/lib/m2 -L/usr/local/lib/ program.f -lm2
or
    gcc  -I/usr/local/include -L/usr/local/lib/ program.c -lm2

The "Hello World" of MDGRAPE-2 programming

A simple example of Fortran force programming of the MDGRAPE-2 would be: 

      INCLUDE 'm2_unit_f77.h'
      DOUBLE PRECISION R1(3, 1)
      DOUBLE PRECISION R2(3, 1)
      DOUBLE PRECISION Q1(1)
      DOUBLE PRECISION Q2(1)
      DOUBLE PRECISION E(3, 1)
      INTEGER U
      INTEGER J
      DATA R1 /0, 1, 0/
      DATA R2 /0, 2, 0/
      DATA Q1 /-1/
      DATA Q2 /4/
      U = M2_ALLOCATE_UNIT('grav.table', M2_FORCE, -0.1D0, 2.1D0,
     -     NULL_INTEGER)
      CALL M2_SET_POSITIONS(U, R2, 1)
      CALL M2_SET_CHARGES(U, Q2, 1)
      CALL M2_CALCULATE_FORCES(U, R1, 1, E)
      CALL M2_FREE_UNIT(U) 
      WRITE(*,*) (Q1(1) * E(J, 1), J = 1, 3)
      END
In this example:
  • M2_ALLOCATE_UNIT loads the 1/r**2 force model from the ACSII file grav.table into the MDGRAPE-2's FET.

  • M2_SET_POSITIONS and M2_SET_CHARGES loads the position (R2) and charge (Q2) of the virtual particle into the MDGRAPE-2's memory.

  • M2_CALCULATE_FORCES loads a pipeline particle's position into the MDGRAPE-2's pipeline, calculates and returns the force vector for that particle.

  • M2_FREE_UNIT frees the MDGRAPE-2 board for use by other programs.

  • Then the pipeline particle's charge is applied to the force vector and printed out.

Some notes about this example:

  • This example has both + and - charges (Q2 & Q1 respectively) and would represent a coulomb force law and not gravity.

  • A similar setup is used to calculate the potentials by loading the gravpot.table with the M2_POTENTIAL parameter in the M2_ALLOCATE_UNIT call and calling M2_CALCULATE_POTENTIALS instead of M2_CALCULATE_FORCES.

  • M2_CALCULATE_FORCES is a blocking call in that all of the forces must be calculated before control is returned to the user's program. M2_START_FORCE_CALCULATION or M2_START_POTENTIAL_CALCULATION can be called with the M2_WAIT_CALCULATION used to block on the MDGRAPE-2's results.

  • Note that the virtual particles loaded into the MDGRAPE-2's memory do not necessarily need to be the same particles as run through the MDGRAPE-2's pipeline; however, often they are.

  • The MDGRAPE-2's virtual particle memory can hold approximately 1 million (X,Y,Z) coordinates plus charges

  • The MDGRAPE-2's pipelines can handle 24 pipeline particles at a time.

Documentation on all the function calls available for the MDGRAPE-2 boards are available for both Fortran and C. These function calls fall into a few main catagories:

  • device allocation
  • force modeling issues
  • gauge settings
  • loading virtual particle positions & charges
  • loading pipeline particle positions
  • calculating forces/potentials/neighbors
  • neighbors