-------------------------------------------------------------------------
PHYS210: CELLULAR AUTOMATA AND VISUALIZATION UTILITIES

1) Visualization of N-body data

      a) xfpp3d: a utility used from the bash command line to visualize
         N-body results
      b) nbodyout: a Matlab function that writes N-body data to a file
         in the format needed by xfpp3d
      c) tnbodyout: a Matlab script that generates some N-body data
         and outputs it using nbodyout

2) Matlab script, life.m, which implements Conway's Game of Life,
   a 2-dimensional, 2-state cellular automaton (CA)

3) Demonstration of xflat2d_rgb, a utility for visualization of cellular
   automata (CA) results

4) Implementation suggestions for CA programs, and use of latout function
   to write CA data to a file in the format needed by xflat2d_rgb
-------------------------------------------------------------------------

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1) Visualization of N-body data
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

-------------------------------------------------------------------------
a) xfpp3d: Visualizes N-body data
-------------------------------------------------------------------------

- IMPORTANT: xfpp3d must be executed from the shell, NOT in Matlab

- In a terminal window, change to your matlab directory, and start
  Matlab in the background

% cd
% cd matlab
% matlab &

- In the same terminal window, copy the sample data file
  ~phys210/matlab/nbody3.dat

% cp ~phys210/matlab/nbody3.dat .

- Invoke xfpp3d with the '-h' option to get help for the utility
  (also available via

  Course Home Page -> Online Course Resources ->
      Visualization Utilities -> xfpp3d

% xfpp3d -h

   usage: xfpp3d [-h] [-c] [-s] [-w]

   Displays animations of three dimensional particle motion.

      Options: -h   Displays this help message.
               -c   Enables user-specified coloring (RGB) of particles.
               -s   Renders particles as solid spheres.
               -w   Renders particles as wireframe spheres.

   xfpp3d reads ASCII input from standard input in one of the following
   two formats:

   (Note that ! denotes the start of a comment.)

                             .
                             .
                             .

   All values are expected to be real numbers except for <np> which is
   an integer.

- Execute xfpp3d using the sample data file as input, and supplying
  the option -c so that the particles are coloured

  IMPORTANT!! At the current time, xfpp3d only takes input from
  the standard input, so USE INPUT REDIRECTION ('<')

  Also, start the program in the background so that you can continue
  to issue bash commands &

% xfpp3d -c < nbody3.dat

- I WILL DEMONSTRATE USAGE OF xfpp3d

- IMPORTANT: There is no facility to "rewind" or "step back" through
  the time sequence of data.  If you want to re-view the data, you
  must exit the utility, and reexecute the xfpp3d command.

-------------------------------------------------------------------------
b) nbodyout and nbodyout1: Matlab functions to output N-body data in
   xfpp3d format
-------------------------------------------------------------------------

- There are functions in ~phys210/matlab that can be used to output
  N-body data to a file in the format that xfpp3d requires

      nbodyout
      nbodyout1

- In an Matlab session execute

>> help nbodyout
>> help nbodyout1

  for usage information and

>> type nbodyout
>> type nbodyout1

  to see the function definitions

- As with the other instructor-supplied functions and scripts, and
  assuming that you are working on the lab computers, you should be
  able to use these directly in your programs

- NOTE: The only difference between nbodyout and nbodyout1 is the
  following

   - nbodyout assumes that the position array is dimensioned

      r(np, 3, nt)

     where np and nt are the number of particles and time steps,
     respectively, and which is the form advocated in the lecture
     notes

   - nbodyout1 assumes that the position array is dimensioned

      r(3, np, nt)

- IMPORTANT: Both nbodyout and nbodyout1 WILL OVERWRITE THE
  OUTPUT FILE SPECIFIED IN THE ARGUMENT LIST (IF IT EXISTS),
  SO BE SURE TO RENAME/MOVE THE EXISTING FILE, SHOULD YOU WANT
  TO PRESERVE ITS CONTENTS

-------------------------------------------------------------------------
c) tnbodyout: Matlab script that demos the use of nbodyout
-------------------------------------------------------------------------

- There is also a demonstration script file

      ~phys210/matlab/tnbodyout.m

   that generates sample N-body data for a "mock" solar system and
   outputs it using nbodyout

- As usual, use the type command to see its definition, and note that,
  as with any of the other .m files in ~phys210/matlab, you are
  free to copy tnbodyout.m and modify it (or use portions of it), for
  your own purposes

>> type tnbodyout

   % Demonstrates use of nbodyout, which outputs N-body data in the form
   % required for visualization with xfpp3d
   %
   % Data represents particles moving on circular Keplerian
   % orbits at various distances from a central mass (i.e. a mock
   % "solar system")

   % Number of timesteps
   nt = 1501;

   % Minimum and maximum times
   tmin = 0;
   tmax = 8.0;

                          .
                          .
                          .

   % Output the data using 'nbodyout'
   nbodyout('tnbodyout.dat', t, r, m, rgb);


- Run tnbodyout

>> tnbodyout

- And then in the terminal window, execute

% xfpp3d -c < tnbodyout.dat &

  to visualize the output

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2) Scripts to play Conway's Game of Life
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

- There is a huge amount of online information concerning this particular
  cellular automaton, including many applets that play the "game";
  point your browser to the following URL for a typical overview

  http://www.math.com/students/wonders/life/life.html

- IMPORTANT: If necessary, start Matlab from your ~/matlab directory

% cd ~/matlab
% matlab &

- ~phys210/matlab/life.m is a Matlab script that implements the game;
  examine the definition using type

>> type life

   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   % Plays Conway's game of life:
   %
   % 2D 2-state cellular automata using 8 cell neighbourhood and
   % the following update rule (states are 0 ("dead") and 1 ("live")):
   %
   %    S_{n}   N-live  S_{n+1}
                             .
                             .
                             :
            % Update the cell state according to the rules
            if c(i,j,n) == 1
               if (count == 2) | (count == 3)
                  c(i,j,n+1) = 1;
               else
                  c(i,j,n+1) = 0;
               end
            else
               if count == 3
                  c(i,j,n+1) = 1;
               else
                  c(i,j,n+1) = 0;
               end
            end
         end
      end
   end

   % Define colours (3 element vectors of RGB values) for latout ... 
   % 
   % 0 (dead) -> white 
   % 1 (live) -> blue

   rgb = [[1.0 1.0 1.0]; [0.0 0.0 1.0]];

   % Output the entire evolution of the arena states ... Note that 
   % the 4th argument to latout, which is optional, enables tracing
   % messages in the function.  Its value (10 in this case), specifies
   % how frequently messages will be output to the terminal in the 
   % function's main loop ...

   latout('life.dat', c, rgb, 10);


- 'life' uses the function 'latout', defined in ~phys210/matlab/latout.m,
  which outputs CA data in the form expected by xflat2d_rgb

- EXECUTE life

>> life

   id_type = 0
   nx =  50
   ny =  50
   nt =  200
   life: Step 1 of 200
   life: Step 2 of 200
   life: Step 3 of 200
   life: Step 4 of 200
   life: Step 5 of 200
   life: Step 6 of 200
   life: Step 7 of 200
   life: Step 8 of 200
   life: Step 9 of 200
            .
            .
            .
   latout: Wrote 140 of 200
   latout: Wrote 150 of 200
   latout: Wrote 160 of 200
   latout: Wrote 170 of 200
   latout: Wrote 180 of 200
   latout: Wrote 190 of 200
   latout: Wrote 200 of 200
   latout: Wrote nx=50 ny=50 nt=200 to file=life.dat

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
3) Demonstration of xflat2d_rgb, utility for visualization of cellular
   automata results
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

- IMPORTANT: xflat2d_rgb must be executed from the shell, NOT in Matlab

- In a terminal window, change to your matlab directory if necessary

% cd
% cd matlab

- Ensure that you have previously run life from a Matlab session that was
  started from your matlab directory

- You should see 'life.dat' in a listing of that directory

- FIRST, get help for the application, using the -h option and also
  available via

  Course Home Page -> Online Course Resources ->
      Visualization Utilities -> xflat2d_rgb

% xflat2d_rgb -h

   usage: xflat2d_rgb [-h]

   Displays animations of two dimensional binary lattices colored with
   arbitrary RGB values.

   xflat2d_rgb expects the following formatted input on standard input:

   <nx> <ny>                                     ! Dimensions of lattice
   <t>                                           ! FIRST display time
   <val(1,1)>   <R(1,1)>   <G(1,1)>   <B(1,1)>   ! Lat, RGB values for site (1,1)
   <val(2,1)>   <R(2,1)>   <G(2,1)>   <B(2,1)>   ! Lat, RGB values for site (2,1)
                        .
                        .
   <val(nx,1)>  <R(nx,1)>  <G(nx,1)>  <B(nx,1)>  ! Lat, RGB values for site (nx,1)
   <val(1,2)>   <R(1,2)>   <G(1,2)>   <B(1,2)>   ! Lat, RGB values for site (1,2)
                        .
                        .
   <val(nx,2)>  <R(nx,2)>  <G(nx,2)>  <B(nx,2)>  ! Lat, RGB values for site (nx,2)
                        o
                        o
                        o
   Lattice positions (1,1) and (nx,ny) correspond to the upper left and
   lower right positions of the display area respectively.

   Input is stream oriented so carriage returns are effectively ignored.
   Thus for example, the lattice values at a given time could appear on
   a single line, one per line, one row per line etc.

- NOW USE xflat2d_rgb TO VISUALIZE THE OUTPUT FROM life AND lifea

- IMPORTANT!! As with xfpp3d, xflat2d_rgb  only takes input from
  the standard input, so USE INPUT REDIRECTION ('<')

% xflat2d_rgb < life.dat &

- I will demonstrate the usage of 'xflat2d_rgb', but its controls
  (including the mpeg generation panel) are very similar to those
  of xfpp3d

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
4) Implementation suggestions for CA programs, and use of latout to write
   CA data to a file in the format needed by xflat2d_rgb
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

a) If your CA has 'nstate' states, use consecutive integers to represent
   them, i.e.

      0, 1, ..., nstate - 1

   or

      1, 2, ..., nstate

b) Use a 3-dimensional array (called 'c' here) to store your CA data.
Define/initialize the array as follows:

      c = zeros(nx, ny, nt)

   so that c has dimensions nx x ny x nt, where nx, ny, nt are

      nx: size of lattice in x-direction
      nz: size of lattice in y-direction
      nt: number of time steps in simulation

   MAKE SURE THAT THE TIME DIMENSION IS THE LAST ONE, SO THAT YOU CAN
   USE latout (see below) DIRECTLY

   FOR EFFICIENCY, YOU SHOULD *DEFINITELY* USE zeros(...) AS ABOVE
   TO CREATE THE 3D LATTICE BEFORE THE SIMULATION PER SE IS STARTED

c) Define an RGB array that gives the colors which will be used by
   xflat2d_rgb for each state value.

   For example, if your model has four states -- 1, 2, 3 and 4 --
   and you want to use the colors red, green, yellow and white for
   them, then define

      rgb = [ [1.0 0.0 0.0]; [0.0 1.0 0.0]; [1.0 1.0 0.0]; [1.0 1.0 1.0] ];

   i.e. rgb is an nstate x 3 array, where each row is an RGB (red-green-blue)
   triple defining a color (each R, G or B value must be in the range
   0.0 to 1.0)

d) Assuming that you have followed/implemented these "hints" (and
   you should!), then once your script has completed the simulation, so
   that each element of the array has been defined (i.e. all nx x ny x nt
   elements have been assigned a state value), use

      latout('ca.dat', c, rgb);

   to write the CA data to a file (called ca.dat here, you can use
   whatever name you wish), that you can then visualize via

      % xflat2d_rgb < ca.dat

   REMEMBER to execute xflat2d_rgb from the shell, not matlab, and
   use input redirection (<)

   ALSO NOTE THAT latout WILL OVERWRITE THE OUTPUT FILE (ca.dat in
   this example) IF IT EXISTS, SO BE SURE TO RENAME/MOVE THE
   EXISTING FILE, SHOULD YOU WANT TO PRESERVE ITS CONTENTS

e) In an matlab session, use

>> help latout

  for additional usage information for latout, and

>> type latout

  to see the function definition

f) AS ALWAYS, contact me should you have any questions about the scripts
  and functions discussed here, or for other help with your projects