trunk/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 a software library for carrying out three-dimensional computations
   5 of the Voronoi tessellation. A distinguishing feature of the Voro++ library
   6 is that it carries out cell-based calculations, computing the Voronoi cell
   7 for each particle individually, rather than computing the Voronoi
   8 tessellation as a global network of vertices and edges. It is particularly
   9 well-suited for applications that rely on cell-based statistics, where
  10 features of Voronoi cells (eg. volume, centroid, number of faces) can be
  11 used to analyze a system of particles
  12
  13 Voro++ comprises of several C++ classes that can be built as a static library
  14 and linked to. A command-line utility is also provided that can analyze text
  15 files of particle configurations and use most of the features of the code.
  16 Numerous examples are provided to demonstrate the library's features and all of
  17 these are discussed in detail on the library website.
  18
  19
  20 Compilation - Linux / Mac OS / Windows with Cygwin
  21 ==================================================
  22 The code is written in ANSI C++, and compiles on many system architectures. The
  23 package contains the C++ source code, example files, miscellaneous utilities
  24 and documentation. On Linux, Mac OS, and Windows (using Cygwin), the
  25 compilation and installed can be carried out using GNU Make.
  26
  27 To begin, the user should review the file "config.mk" in the top level
  28 directory, to make sure that the compilation and installation settings are
  29 appropriate for their system. Typing "make" will then compile the static
  30 library, command-line utility, and examples. The command-line utility and
  31 library will appear within the "src" directory.
  32
  33 Following successful compilation, the library, command-line utility, and
  34 documentation can be installed by typing "sudo make install". By default, the
  35 program files are installed into /usr/local, and it may be necessary to modify
  36 your environment variables in order to access the installed files:
  37
  38 - to use the command-line utility, the variable PATH should contain
  39   /usr/local/bin.
  40 - to access the Voro++ man page, the variable MANPATH should contain
  41   /usr/local/man.
  42 - to access the Voro++ header files, code compilation should include
  43   the flag '-I/usr/local/include/voro++'.
  44 - to link to the static library, code compilation should include the
  45   flags '-L/usr/local/lib' to tell the linker where to look, and then
  46   '-lvoro++' to link to the library.
  47
  48 The library website contains additional notes on setting environment variables,
  49 and many guides are available on the Internet.
  50
  51 The code can later be uninstalled with "sudo make uninstall". It is also
  52 possible to use the library and command-line utility without installation by
  53 calling the files directly once they have been compiled. On systems where the
  54 user does not have root privileges to install into /usr/local, the "config.mk"
  55 file can be modified to install into the user's home directory by setting
  56 PREFIX=$(HOME). Voro++ supports parallel compilation by using the "make -j <n>"
  57 command where n is the number of threads.
  58
  59
  60 Compilation - Windows without Cygwin
  61 ====================================
  62 On a Windows machine without a terminal environment like Cygwin, it is possible
  63 to import and compile the library in many standard C++ development
  64 environments. Users have reported success in building the library with
  65 Microsoft Visual C++ Express and Code::Blocks.
  66
  67
  68 Related programs
  69 ================
  70 No external dependencies are required to compile and run the code, but several
  71 programs may be useful for analyzing the output:
  72
  73 - The freeware plotting program Gnuplot (available at www.gnuplot.info) can be
  74   used for rapid 2D and 3D visualization of the program output.
  75
  76 - The freeware raytracer POV-Ray (available at www.povray.org) can be used for
  77   high-quality renderings of the program output.
  78
  79 - The reference manual is generated from comments in the source code using
  80   Doxygen (available at www.doxygen.org). This package is only required if the
  81   library files are being developed and the reference manuals need to be
  82   regenerated. The complete reference manual to the current code is available
  83   online at http://math.lbl.gov/voro++/doc/refman/
  84
  85
  86 Contents
  87 ========
  88 examples - many documented examples making use of the library
  89 html - an HTML-based reference manual (generated by Doxygen)
  90 man - contains the man page that is installed with the program
  91 scripts - miscellaneous helper scripts
  92 src - source code files
  93
  94
  95 Usage
  96 =====
  97 Voro++ is released as free software through the Lawrence Berkeley National
  98 Laboratory - a detailed copyright notice is provided below, and the complete
  99 terms of the license can be found in the LICENSE file.
 100
 101 I am very interested to hear from users of the software, so if you find this
 102 useful, please email me at chr@alum.mit.edu. Also, if you plan to publish an
 103 academic paper using this software, please consider citing one of the following
 104 publications:
 105
 106 - Chris H. Rycroft, "Voro++: A three-dimensional Voronoi cell library in C++",
 107   Chaos 19, 041111 (2009).
 108
 109 - Chris H. Rycroft, Gary S. Grest, James W. Landry, and Martin Z. Bazant,
 110   "Analysis of Granular Flow in a Pebble-Bed Nuclear Reactor",
 111   Phys. Rev. E 74, 021306 (2006).
 112
 113 - Chris H. Rycroft, "Multiscale Modeling in Granular Flow", PhD thesis
 114   submitted to the Massachusetts Institute of Technology, September 2007.
 115   (http://math.berkeley.edu/~chr/publish/phd.html)
 116
 117 The first reference contains a one-page overview of the library. The second
 118 reference contains some of the initial images that were made using a very early
 119 version of this code, to track small changes in packing fraction in a large
 120 particle simulation. The third reference discusses the use of 3D Voronoi cells,
 121 and describes the algorithms that were employed in the early version of this
 122 code. Since the publication of the above references, the algorithms in Voro++
 123 have been significantly improved, and a paper specifically devoted to the
 124 current code architecture will be published during 2012.
 125
 126
 127 Copyright Notice
 128 ================
 129 Voro++ Copyright (c) 2008, The Regents of the University of California, through
 130 Lawrence Berkeley National Laboratory (subject to receipt of any required
 131 approvals from the U.S. Dept. of Energy). All rights reserved.
 132
 133 If you have questions about your rights to use or distribute this software,
 134 please contact Berkeley Lab's Technology Transfer Department at TTD@lbl.gov.
 135
 136 NOTICE. This software was developed under partial funding from the U.S.
 137 Department of Energy. As such, the U.S. Government has been granted for itself
 138 and others acting on its behalf a paid-up, nonexclusive, irrevocable, worldwide
 139 license in the Software to reproduce, prepare derivative works, and perform
 140 publicly and display publicly. Beginning five (5) years after the date
 141 permission to assert copyright is obtained from the U.S. Department of Energy,
 142 and subject to any subsequent five (5) year renewals, the U.S. Government is
 143 granted for itself and others acting on its behalf a paid-up, nonexclusive,
 144 irrevocable, worldwide license in the Software to reproduce, prepare derivative
 145 works, distribute copies to the public, perform publicly and display publicly,
 146 and to permit others to do so.
 147
 148
 149 Acknowledgments
 150 ===============
 151 This work was supported by the Director, Office of Science, Computational and
 152 Technology Research, U.S. Department of Energy under Contract No.
 153 DE-AC02-05CH11231.