3.2.1.8.3 Advanced use of Arrays

This section explains how to make a multi variable array. The tric is to
initiate an array entry with an other array (let us call them 
sub-arrays).
This can rapidly lead to high dimensional arrays with sub-arrays inside
sub-arrays and so on, so it is better to define words for all those 
indices
in order to keep track of things.

The best way to show this is an example. Say you are animating moving
particles inside a cell that can bump to each other or bounch from the 
walls
of the cell.

--------------------------------- light blue
background -----------------------------
#declare N = 24;
#declare Cell = array[N+1]
// 24 particles + 1; not initialised.
// Global variables, so all macro's and inc-files can reach Cell.
// Index zero is used for times you need during computation.
// The rest are the 24 particles.
#declare Times = 0;

// Declare a time array; initialise them: -1 means no value available 
yet.
// RunTime: Time after all position updates are done and we wait for the
next one.
// FirstEventTime: The first EventTime of all the particles in the cell.
#declare Ar_Times       = array[2] {-1,-1}
#declare RunTime        = 0;
#declare FirstEventTime = 1;
#declare Cell[Times]    = Ar_Times;

// Declare a particle array; index zero is for Times.
#declare Particle  = array[..]      // .. = at the moment 
dimension_size is
6
#declare Mass      = 1;
#declare Radius    = 2;
#declare Position  = 3;
#declare Velocity  = 4;
#declare EventType = 5;
// etc., add what ever you need.

// Declare the various sub-arrays for Particle.
// For the event times of a particle we use Ar_Times again.
#declare Ar_Mass      = array[1] {-1}
#declare Ar_Radius    = array[1] {-1}
#declare Ar_Position  = array[1] {<-1,-1,-1>}
#declare Ar_Velocity  = array[1] {<-1,-1,-1>}
#declare Ar_EventType = array[1] {-1}
// etc., add what ever you need.

// Couple the sub-arrays.
#declare Particle[Times]     = Ar_Times;
#declare Particle[Mass]      = Ar_Mass;
#declare Particle[Radius]    = Ar_Radius;
#declare Particle[Position]  = Ar_Position;
#declare Particle[Velocity]  = Ar_Velocity;
#declare Particle[EventType] = Ar_EventType;
// etc., add what ever you need.

// Fill the Cell with particles
#for (I, 1, N)
 Cell[I] = Particle;
 // A good place to initialise the Mass, Radius, etc of a particle
 Cell[I][Times][RunTime] = 0;
 Cell[I][Mass][0]        = ....
 Cell[I][Radius][0]      = .....
 // etc.
#end
-------------------------------------------------------------------------
---
--------

The advantage of this method is ease of access in the array. If you want 
the
velocity of the seventh particle: Cell[7][Velocity][0].
Another advantage is the ease of changing and adding. If for instance 
you
want to upgrade the system to a box filled with Cells you just do the
following:

--------------------------------- light blue
background -----------------------------
#declare DimX = 12;
#declare DimY = 8;
#declare DimZ = 5;
#declare Box = array[DimX-1][DimY-1][DimZ-1] // with DimX*DimY*DimZ 
Cells.

// Fill the Box with Cells
#for (IX,0,DimX-1)
  #for (IY,0,DimY-1)
    #for (IZ,0,DimZ-1)
      Box[IX][IY][IZ] = Cell;
    #end
  #end
#end
-------------------------------------------------------------------------
---
--------

The velocity of the seventh particle in a cell is now:
Box[IX][IY][IZ][7][Velocity][0].

Because you have plugged arrays in arrays, you can now extract parts of 
the
total array Box, for instance:

--------------------------------- light blue
background -----------------------------
#local PartA = Box[IX][IY][IZ][J];   // Particle number J in this Cell
#local PartB = Box[IX][IY][IZ][K];   // Particle number K in this Cell
-------------------------------------------------------------------------
---
--------

If the structure of an array becomes complicated, use a diagram to keep
track of your indices.

***** Here the Array_Diagram.jpg **********