branches/dynamic/README

   1 Voro++, a 3D cell-based Voronoi library (http://math.lbl.gov/voro++/)
   2 By Chris H. Rycroft (UC Berkeley / Lawrence Berkeley Laboratory)
   3 ================================================================
   4 Voro++ is an object-oriented C++ library for the calculation of the 3D Voronoi
   5 tessellation using a cell-by-cell construction. It is primarily designed for
   6 applications in physics and materials science, where the Voronoi tessellation
   7 can be a useful tool in the analysis of densely-packed particle systems, such
   8 as granular materials or glasses.
   9
  10 Voro++ comprises of several C++ classes that can be modified and incorporated
  11 into other programs. A command-line utility is also provided that can use most
  12 features of the code.
  13
  14
  15 Compilation
  16 ===========
  17 The code is written in ANSI C++, and it should compile on many system
  18 architectures. The compilation is configured in "config.mk" and is currently
  19 set to the GNU C++ compiler, g++. The command-line utility and example scripts
  20 can be compiled by typing "make" in the top-level directory. No external
  21 dependencies are required to compile and run the code, but several programs may
  22 be useful:
  23
  24 - The freeware plotting program Gnuplot (available at www.gnuplot.info) can be
  25   used for rapid 2D and 3D visualization of the program output.
  26
  27 - The freeware raytracer POV-Ray (available at www.povray.org) can be used for
  28   high-quality renderings of the program output.
  29
  30 - The reference manual is generated from comments in the source code using
  31   Doxygen (available at www.doxygen.org). This package is only required if the
  32   library files are being developed and the reference manuals need to be
  33   regenerated. The complete reference manual to the current code is available
  34   online at http://math.lbl.gov/voro++/doc/refman/
  35
  36
  37 Contents
  38 ========
  39 bin - a blank directory, into which the command-line utility is compiled
  40 doc - contains a PDF overview of the software package
  41 examples - many documented examples making use of the library
  42 html - an HTML-based reference manual (generated by Doxygen)
  43 latex - a LaTeX reference manual (generated by Doxygen)
  44 scripts - miscellaneous helper scripts
  45 src - source code files
  46
  47
  48 Usage
  49 =====
  50 Voro++ is released as free software through the Lawrence Berkeley National
  51 Laboratory - a detailed copyright notice is provided below, and the complete
  52 terms of the license can be found in the LICENSE file.
  53
  54 I am very interested to hear from users of the software, so if you find this
  55 useful, please email me at chr@alum.mit.edu. Also, if you plan to publish an
  56 academic paper using this software, please consider citing either or both of
  57 the following publications:
  58
  59 - Chris H. Rycroft, Gary S. Grest, James W. Landry, and Martin Z. Bazant,
  60   "Analysis of Granular Flow in a Pebble-Bed Nuclear Reactor",
  61   Phys. Rev. E 74, 021306 (2006).
  62
  63 - Chris H. Rycroft, "Multiscale Modeling in Granular Flow", PhD thesis
  64   submitted to the Massachusetts Institute of Technology, September 2007.
  65   (http://math.berkeley.edu/~chr/publish/phd.html)
  66
  67 The first reference contains some of the initial images that were made using a
  68 very early version of this code, to track small changes in packing fraction in
  69 a large particle simulation. The second reference discusses the use of 3D
  70 Voronoi cells, and describes the algorithms that were employed in the early
  71 version of this code. Since the publication of the above references, the
  72 algorithms in Voro++ have been significantly improved, and a paper specifically
  73 devoted to the current code architecture will hopefully be published during
  74 2009.
  75
  76
  77 Copyright Notice
  78 ================
  79 Voro++ Copyright (c) 2008, The Regents of the University of California, through
  80 Lawrence Berkeley National Laboratory (subject to receipt of any required
  81 approvals from the U.S. Dept. of Energy). All rights reserved.
  82
  83 If you have questions about your rights to use or distribute this software,
  84 please contact Berkeley Lab's Technology Transfer Department at TTD@lbl.gov.
  85
  86 NOTICE. This software was developed under partial funding from the U.S.
  87 Department of Energy. As such, the U.S. Government has been granted for itself
  88 and others acting on its behalf a paid-up, nonexclusive, irrevocable, worldwide
  89 license in the Software to reproduce, prepare derivative works, and perform
  90 publicly and display publicly. Beginning five (5) years after the date
  91 permission to assert copyright is obtained from the U.S. Department of Energy,
  92 and subject to any subsequent five (5) year renewals, the U.S. Government is
  93 granted for itself and others acting on its behalf a paid-up, nonexclusive,
  94 irrevocable, worldwide license in the Software to reproduce, prepare derivative
  95 works, distribute copies to the public, perform publicly and display publicly,
  96 and to permit others to do so.
  97
  98
  99 Acknowledgments
 100 ===============
 101 This work was supported by the Director, Oﬃce of Science, Computational and
 102 Technology Research, U.S. Department of Energy under Contract No.
 103 DE-AC02-05CH11231.