branches/2d/boundary/README

   1 2D Boundary command-line utility
   2 by Cody Robert Dance, Jeff Johnson, and Chris H. Rycroft
   3 ========================================================
   4
   5 Input file
   6 ----------
   7 This command-line utility demonstrates the functionality of the 2D Voronoi
   8 boundary code. The utility accepts a single argument as the name of the
   9 input file to read. The input file must have lines of three entries, separated
  10 by spaces, corresponding to a particle ID, and its (x,y) position:
  11
  12 <id> <x> <y>
  13 <id> <x> <y>
  14 ...
  15
  16 To create a boundary loop, the keywords "# Start" and "# End" must be included
  17 on separate lines. A loop of three particles would look like this:
  18
  19 # Start
  20 <id> <x> <y>
  21 <id> <x> <y>
  22 <id> <x> <y>
  23 # End
  24
  25 The utility checks for many simple errors in the input file, such as finding
  26 two start tokens in succession, or finding a boundary loop without any
  27 terminating end token.
  28
  29 The boundaries must have the correct winding direction, so that they go
  30 counter-clockwise around the outer edge. Holes are also allowed, and for these,
  31 they must be specified in a clockwise direction. In both cases, the interior is
  32 on the left as the boundary is traversed. The utility does not do any checks of
  33 boundary winding, and this may cause errors if the winding is not specified
  34 correctly.
  35
  36
  37 Computation
  38 -----------
  39 The command-line utility first reads in the contents of the file. It computes
  40 the size of the domain that the particles are in, and counts the number of
  41 particles.
  42
  43 To carry out the computation, the library divides the domain into a rectangular
  44 grid of equally-sized boxes. The optimal performance is obtained for around
  45 five to fifteen particles per box, and performance is further improved if the
  46 boxes are close to squares. The utility estimates the number of boxes based on
  47 the domain size and the number of particles.
  48
  49 It then constructs the container, and imports the particles. After this is
  50 carried out, a routine called "setup" is run, which carries out additional
  51 computations that are needed for the non-convex case prior to computing Voronoi
  52 cells. It scans the boundary, and searches for particles that may need to be
  53 excluded from certain Voronoi cell computations because they lie close to a
  54 wall.
  55
  56
  57 Output
  58 ------
  59 The code outputs several files that are designed to be plotted with Gnuplot,
  60 although since they are text files, it should be possible to view them in other
  61 plotting programs. Three files are created:
  62
  63 <filename>.bd - a drawing of the boundary
  64 <filename>.gnu - a file with the computed Voronoi cells
  65 <filename>.net - a file visualizing the cell connectivity
  66
  67 These files can be plotted in Gnuplot using the command
  68
  69 plot '<filename>.gnu' t "Voronoi cells", '<filename>.bd' lw 3 t "Boundary", \
  70      '<filename>.net' t "Connections", '<filename>' u 2:3 w p pt 7 t "Generators"
  71
  72
  73 Examples
  74 --------
  75 Four example files are included. They can be run with the commands
  76
  77 ./voro++_bdry input1
  78 ./voro++_bdry input2
  79 ./voro++_bdry input3
  80 ./voro++_bdry input4
  81
  82 This will generate many output files. If the Gnuplot script figs.gnuplot is
  83 run, by typing "gnuplot figs.gnuplot", then four EPS figures will be created.