Commit 90a880d4 authored by Roger Wesson's avatar Roger Wesson

upstream verion 0.4.6

parents
Voro++ Copyright (c) 2008, The Regents of the University of California, through
Lawrence Berkeley National Laboratory (subject to receipt of any required
approvals from the U.S. Dept. of Energy). All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
(1) Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
(2) Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
(3) Neither the name of the University of California, Lawrence Berkeley
National Laboratory, U.S. Dept. of Energy nor the names of its contributors may
be used to endorse or promote products derived from this software without
specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
You are under no obligation whatsoever to provide any bug fixes, patches, or
upgrades to the features, functionality or performance of the source code
("Enhancements") to anyone; however, if you choose to make your Enhancements
available either publicly, or directly to Lawrence Berkeley National
Laboratory, without imposing a separate written license agreement for such
Enhancements, then you hereby grant the following license: a non-exclusive,
royalty-free perpetual license to install, use, modify, prepare derivative
works, incorporate into other computer software, distribute, and sublicense
such enhancements or derivative works thereof, in binary and source code form.
# Voro++ makefile
#
# Author : Chris H. Rycroft (LBL / UC Berkeley)
# Email : chr@alum.mit.edu
# Date : August 30th 2011
# Tell make that these are phony targets
.PHONY: all help clean install uninstall
include config.mk
# Build all of the executable files
all:
$(MAKE) -C src
$(MAKE) -C examples
# Build the help files (with Doxygen)
help:
$(MAKE) -C src help
# Clean up the executable files
clean:
$(MAKE) -C src clean
$(MAKE) -C examples clean
# Install the executable, man page, and shared library
install:
$(MAKE) -C src
$(INSTALL) -d $(IFLAGS_EXEC) $(PREFIX)/bin
$(INSTALL) -d $(IFLAGS_EXEC) $(PREFIX)/lib
$(INSTALL) -d $(IFLAGS_EXEC) $(PREFIX)/man
$(INSTALL) -d $(IFLAGS_EXEC) $(PREFIX)/man/man1
$(INSTALL) -d $(IFLAGS_EXEC) $(PREFIX)/include
$(INSTALL) -d $(IFLAGS_EXEC) $(PREFIX)/include/voro++
$(INSTALL) $(IFLAGS_EXEC) src/voro++ $(PREFIX)/bin
$(INSTALL) $(IFLAGS) man/voro++.1 $(PREFIX)/man/man1
$(INSTALL) $(IFLAGS) src/libvoro++.a $(PREFIX)/lib
$(INSTALL) $(IFLAGS) src/voro++.hh $(PREFIX)/include/voro++
$(INSTALL) $(IFLAGS) src/c_loops.hh $(PREFIX)/include/voro++
$(INSTALL) $(IFLAGS) src/cell.hh $(PREFIX)/include/voro++
$(INSTALL) $(IFLAGS) src/common.hh $(PREFIX)/include/voro++
$(INSTALL) $(IFLAGS) src/config.hh $(PREFIX)/include/voro++
$(INSTALL) $(IFLAGS) src/container.hh $(PREFIX)/include/voro++
$(INSTALL) $(IFLAGS) src/container_prd.hh $(PREFIX)/include/voro++
$(INSTALL) $(IFLAGS) src/rad_option.hh $(PREFIX)/include/voro++
$(INSTALL) $(IFLAGS) src/pre_container.hh $(PREFIX)/include/voro++
$(INSTALL) $(IFLAGS) src/unitcell.hh $(PREFIX)/include/voro++
$(INSTALL) $(IFLAGS) src/v_base.hh $(PREFIX)/include/voro++
$(INSTALL) $(IFLAGS) src/v_compute.hh $(PREFIX)/include/voro++
$(INSTALL) $(IFLAGS) src/wall.hh $(PREFIX)/include/voro++
$(INSTALL) $(IFLAGS) src/worklist.hh $(PREFIX)/include/voro++
# Uninstall the executable, man page, and shared library
uninstall:
rm -f $(PREFIX)/bin/voro++
rm -f $(PREFIX)/man/man1/voro++.1
rm -f $(PREFIX)/lib/libvoro++.a
rm -f $(PREFIX)/include/voro++/voro++.hh
rm -f $(PREFIX)/include/voro++/c_loops.hh
rm -f $(PREFIX)/include/voro++/cell.hh
rm -f $(PREFIX)/include/voro++/common.hh
rm -f $(PREFIX)/include/voro++/config.hh
rm -f $(PREFIX)/include/voro++/container.hh
rm -f $(PREFIX)/include/voro++/container_prd.hh
rm -f $(PREFIX)/include/voro++/pre_container.hh
rm -f $(PREFIX)/include/voro++/rad_option.hh
rm -f $(PREFIX)/include/voro++/unitcell.hh
rm -f $(PREFIX)/include/voro++/v_base.hh
rm -f $(PREFIX)/include/voro++/v_compute.hh
rm -f $(PREFIX)/include/voro++/wall.hh
rm -f $(PREFIX)/include/voro++/worklist.hh
rmdir $(PREFIX)/include/voro++
This diff is collapsed.
Voro++, a 3D cell-based Voronoi library (http://math.lbl.gov/voro++/)
By Chris H. Rycroft (UC Berkeley / Lawrence Berkeley Laboratory)
================================================================
Voro++ is a software library for carrying out three-dimensional computations
of the Voronoi tessellation. A distinguishing feature of the Voro++ library
is that it carries out cell-based calculations, computing the Voronoi cell
for each particle individually, rather than computing the Voronoi
tessellation as a global network of vertices and edges. It is particularly
well-suited for applications that rely on cell-based statistics, where
features of Voronoi cells (eg. volume, centroid, number of faces) can be
used to analyze a system of particles
Voro++ comprises of several C++ classes that can be built as a static library
and linked to. A command-line utility is also provided that can analyze text
files of particle configurations and use most of the features of the code.
Numerous examples are provided to demonstrate the library's features and all of
these are discussed in detail on the library website.
Compilation - Linux / Mac OS / Windows with Cygwin
==================================================
The code is written in ANSI C++, and compiles on many system architectures. The
package contains the C++ source code, example files, miscellaneous utilities
and documentation. On Linux, Mac OS, and Windows (using Cygwin), the
compilation and installed can be carried out using GNU Make.
To begin, the user should review the file "config.mk" in the top level
directory, to make sure that the compilation and installation settings are
appropriate for their system. Typing "make" will then compile the static
library, command-line utility, and examples. The command-line utility and
library will appear within the "src" directory.
Following successful compilation, the library, command-line utility, and
documentation can be installed by typing "sudo make install". By default, the
program files are installed into /usr/local, and it may be necessary to modify
your environment variables in order to access the installed files:
- to use the command-line utility, the variable PATH should contain
/usr/local/bin.
- to access the Voro++ man page, the variable MANPATH should contain
/usr/local/man.
- to access the Voro++ header files, code compilation should include
the flag '-I/usr/local/include/voro++'.
- to link to the static library, code compilation should include the
flags '-L/usr/local/lib' to tell the linker where to look, and then
'-lvoro++' to link to the library.
The library website contains additional notes on setting environment variables,
and many guides are available on the Internet.
The code can later be uninstalled with "sudo make uninstall". It is also
possible to use the library and command-line utility without installation by
calling the files directly once they have been compiled. On systems where the
user does not have root privileges to install into /usr/local, the "config.mk"
file can be modified to install into the user's home directory by setting
PREFIX=$(HOME). Voro++ supports parallel compilation by using the "make -j <n>"
command where n is the number of threads.
Compilation - Windows without Cygwin
====================================
On a Windows machine without a terminal environment like Cygwin, it is possible
to import and compile the library in many standard C++ development
environments. Users have reported success in building the library with
Microsoft Visual C++ Express and Code::Blocks.
Related programs
================
No external dependencies are required to compile and run the code, but several
programs may be useful for analyzing the output:
- The freeware plotting program Gnuplot (available at www.gnuplot.info) can be
used for rapid 2D and 3D visualization of the program output.
- The freeware raytracer POV-Ray (available at www.povray.org) can be used for
high-quality renderings of the program output.
- The reference manual is generated from comments in the source code using
Doxygen (available at www.doxygen.org). This package is only required if the
library files are being developed and the reference manuals need to be
regenerated. The complete reference manual to the current code is available
online at http://math.lbl.gov/voro++/doc/refman/
Contents
========
examples - many documented examples making use of the library
html - an HTML-based reference manual (generated by Doxygen)
man - contains the man page that is installed with the program
scripts - miscellaneous helper scripts
src - source code files
Usage
=====
Voro++ is released as free software through the Lawrence Berkeley National
Laboratory - a detailed copyright notice is provided below, and the complete
terms of the license can be found in the LICENSE file.
I am very interested to hear from users of the software, so if you find this
useful, please email me at chr@alum.mit.edu. Also, if you plan to publish an
academic paper using this software, please consider citing one of the following
publications:
- Chris H. Rycroft, "Voro++: A three-dimensional Voronoi cell library in C++",
Chaos 19, 041111 (2009).
- Chris H. Rycroft, Gary S. Grest, James W. Landry, and Martin Z. Bazant,
"Analysis of Granular Flow in a Pebble-Bed Nuclear Reactor",
Phys. Rev. E 74, 021306 (2006).
- Chris H. Rycroft, "Multiscale Modeling in Granular Flow", PhD thesis
submitted to the Massachusetts Institute of Technology, September 2007.
(http://math.berkeley.edu/~chr/publish/phd.html)
The first reference contains a one-page overview of the library. The second
reference contains some of the initial images that were made using a very early
version of this code, to track small changes in packing fraction in a large
particle simulation. The third reference discusses the use of 3D Voronoi cells,
and describes the algorithms that were employed in the early version of this
code. Since the publication of the above references, the algorithms in Voro++
have been significantly improved, and a paper specifically devoted to the
current code architecture will be published during 2012.
Copyright Notice
================
Voro++ Copyright (c) 2008, The Regents of the University of California, through
Lawrence Berkeley National Laboratory (subject to receipt of any required
approvals from the U.S. Dept. of Energy). All rights reserved.
If you have questions about your rights to use or distribute this software,
please contact Berkeley Lab's Technology Transfer Department at TTD@lbl.gov.
NOTICE. This software was developed under partial funding from the U.S.
Department of Energy. As such, the U.S. Government has been granted for itself
and others acting on its behalf a paid-up, nonexclusive, irrevocable, worldwide
license in the Software to reproduce, prepare derivative works, and perform
publicly and display publicly. Beginning five (5) years after the date
permission to assert copyright is obtained from the U.S. Department of Energy,
and subject to any subsequent five (5) year renewals, the U.S. Government is
granted for itself and others acting on its behalf a paid-up, nonexclusive,
irrevocable, worldwide license in the Software to reproduce, prepare derivative
works, distribute copies to the public, perform publicly and display publicly,
and to permit others to do so.
Acknowledgments
===============
This work was supported by the Director, Office of Science, Computational and
Technology Research, U.S. Department of Energy under Contract No.
DE-AC02-05CH11231.
# Voro++, a 3D cell-based Voronoi library
#
# Author : Chris H. Rycroft (LBL / UC Berkeley)
# Email : chr@alum.mit.edu
# Date : August 28th 2011
# This a common configuration file that includes definitions used by all
# the Makefiles.
# C++ compiler
CXX=g++
# Flags for the C++ compiler
CFLAGS=-Wall -ansi -pedantic -O3
# Relative include and library paths for compilation of the examples
E_INC=-I../../src
E_LIB=-L../../src
# Installation directory
PREFIX=/usr/local
# Install command
INSTALL=install
# Flags for install command for executable
IFLAGS_EXEC=-m 0755
# Flags for install command for non-executable files
IFLAGS=-m 0644
# Voro++ makefile
#
# Author : Chris H. Rycroft (LBL / UC Berkeley)
# Email : chr@alum.mit.edu
# Date : August 30th 2011
# Makefile rules
all: ex_basic ex_walls ex_custom ex_extra ex_degenerate ex_interface
ex_basic:
$(MAKE) -C basic
ex_walls:
$(MAKE) -C walls
ex_custom:
$(MAKE) -C custom
ex_extra:
$(MAKE) -C extra
ex_degenerate:
$(MAKE) -C degenerate
ex_interface:
$(MAKE) -C interface
clean:
$(MAKE) -C basic clean
$(MAKE) -C walls clean
$(MAKE) -C custom clean
$(MAKE) -C extra clean
$(MAKE) -C degenerate clean
$(MAKE) -C interface clean
.PHONY: all ex_basic ex_walls ex_custom ex_extra ex_degenerate clean
Voro++ example directory
========================
These directories contain example programs that make use of the Voro++ code,
and they are divided into six sections:
basic - this contains several simple scripts that introduce this basic classes
and carry out simple operations, such as constructing a single cell, or making
a Voronoi tessellation for a small number of a random particles in a box.
walls - these programs demonstrate the use of wall objects, to calculate the
Voronoi cells in non-standard geometries.
custom - these programs demonstrate how to customize the output of the library
to contain a variety of different statistics about the computed Voronoi cells.
The radical tessellation for a polydisperse packing of particles is also
demonstrated.
interface - these programs demonstrate features of the library's C++ interface.
extra - this contains miscellaneous additional applications of the library for
non-standard usage. It also includes an example of using a wall object to
approximately deal with a case of an irregular boundary.
degenerate - these codes demonstrate cases when "degenerate" vertices of order
bigger than 3 are created, when the cutting planes are aligned to existing
vertices within the numerical tolerance.
timing - these programs and scripts can be used to test the performance of the
code under different configurations.
# Voro++ makefile
#
# Author : Chris H. Rycroft (LBL / UC Berkeley)
# Email : chr@alum.mit.edu
# Date : August 30th 2011
# Load the common configuration file
include ../../config.mk
# List of executables
EXECUTABLES=single_cell platonic random_points import
# Makefile rules
all: $(EXECUTABLES)
single_cell: single_cell.cc
$(CXX) $(CFLAGS) $(E_INC) $(E_LIB) -o single_cell single_cell.cc -lvoro++
platonic: platonic.cc
$(CXX) $(CFLAGS) $(E_INC) $(E_LIB) -o platonic platonic.cc -lvoro++
random_points: random_points.cc
$(CXX) $(CFLAGS) $(E_INC) $(E_LIB) -o random_points random_points.cc -lvoro++
import: import.cc
$(CXX) $(CFLAGS) $(E_INC) $(E_LIB) -o import import.cc -lvoro++
clean:
rm -f $(EXECUTABLES)
.PHONY: all clean
Voro++ basic example codes
==========================
These programs demonstrate some basic usage of the Voro++ library.
1. single_cell.cc introduces the basic voronoicell class. It creates a simple
cell by cutting it with a number of random planes. It outputs the cell to a file
called single_cell.gnu, which can be visualized in gnuplot using the following
commands:
set style data lines
splot 'single_cell.gnu'
2. platonic.cc uses the voronoicell class to make the five Platonic solids,
which are output to files that can be visualized in gnuplot.
3. random_points.cc introduces the container class, for holding particle
positions in a box. After creating a container, it adds a small number of
random points to the box. It then calculates the sum of the volumes of the
Voronoi cells, and compares it to the container volume - since the cells should
perfectly partition the container, these two should be identical to within
numerical accuracy. The code then saves the particle positions to
"random_points_p.gnu" and the Voronoi cells to "random_points_v.gnu". These can
be visualized in gnuplot using the command:
splot 'random_points_p.gnu' u 2:3:4 with points, 'random_points_v.gnu' with lines
4. import.cc demonstrates the ability of the code to import a list of particles
from a text file. The code imports a text file called 'pack_ten_cube' which
contains a thousand particles in a cube of side length 10. Each line of this
file has the form:
<Numerical ID> <x coordinate> <y coordinate> <z coordinate>
The code imports the particles into the container, and then saves the particles
and Voronoi cells in gnuplot and POV-Ray formats. To visualize the particles in
gnuplot, use the command:
splot 'pack_ten_cube' u 2:3:4 with points, 'pack_ten_cube.gnu' with lines
To create a POV-Ray rendering of the particles, the scene header file
import.pov must be used, which includes the output from the program. To render
an 800x600 image with antialiasing, use the command:
povray +W800 +H600 +A0.01 +Oimport.png import.pov
// File import example code
//
// Author : Chris H. Rycroft (LBL / UC Berkeley)
// Email : chr@alum.mit.edu
// Date : August 30th 2011
#include "voro++.hh"
using namespace voro;
// Set up constants for the container geometry
const double x_min=-5,x_max=5;
const double y_min=-5,y_max=5;
const double z_min=0,z_max=10;
// Set up the number of blocks that the container is divided into
const int n_x=6,n_y=6,n_z=6;
int main() {
// Create a container with the geometry given above, and make it
// non-periodic in each of the three coordinates. Allocate space for
// eight particles within each computational block
container con(x_min,x_max,y_min,y_max,z_min,z_max,n_x,n_y,n_z,
false,false,false,8);
//Randomly add particles into the container
con.import("pack_ten_cube");
// Save the Voronoi network of all the particles to text files
// in gnuplot and POV-Ray formats
con.draw_cells_gnuplot("pack_ten_cube.gnu");
con.draw_cells_pov("pack_ten_cube_v.pov");
// Output the particles in POV-Ray format
con.draw_particles_pov("pack_ten_cube_p.pov");
}
#version 3.6;
// Right-handed coordinate system in which the z-axis points upwards
camera {
location <30,-50,25>
sky z
right -0.24*x*image_width/image_height
up 0.24*z
look_at <0,0,4.5>
}
// White background
background{rgb 1}
// Two lights with slightly different colors
light_source{<-8,-20,30> color rgb <0.77,0.75,0.75>}
light_source{<25,-12,12> color rgb <0.38,0.40,0.40>}
// Radius of the Voronoi cell network
#declare r=0.08;
// Radius of the particles
#declare s=0.5;
// Particles
union{
#include "pack_ten_cube_p.pov"
pigment{rgb 0.95} finish{reflection 0.1 specular 0.3 ambient 0.42}
}
// Voronoi cells
union{
#include "pack_ten_cube_v.pov"
pigment{rgb <1,0.4,0.45>} finish{specular 0.5 ambient 0.42}
}
This diff is collapsed.
// Platonic solids example code
//
// Author : Chris H. Rycroft (LBL / UC Berkeley)
// Email : chr@alum.mit.edu
// Date : August 30th 2011
#include "voro++.hh"
using namespace voro;
// Golden ratio constants
const double Phi=0.5*(1+sqrt(5.0));
const double phi=0.5*(1-sqrt(5.0));
int main() {
voronoicell v;
// Create a tetrahedron
v.init(-2,2,-2,2,-2,2);
v.plane(1,1,1);
v.plane(1,-1,-1);
v.plane(-1,1,-1);
v.plane(-1,-1,1);
v.draw_gnuplot(0,0,0,"tetrahedron.gnu");
// Create a cube. Since this is the default shape
// we don't need to do any plane cutting.
v.init(-1,1,-1,1,-1,1);
v.draw_gnuplot(0,0,0,"cube.gnu");
// Create an octahedron
v.init(-2,2,-2,2,-2,2);
v.plane(1,1,1);
v.plane(-1,1,1);
v.plane(1,-1,1);
v.plane(-1,-1,1);
v.plane(1,1,-1);
v.plane(-1,1,-1);
v.plane(1,-1,-1);
v.plane(-1,-1,-1);
v.draw_gnuplot(0,0,0,"octahedron.gnu");
// Create a dodecahedron
v.init(-2,2,-2,2,-2,2);
v.plane(0,Phi,1);
v.plane(0,-Phi,1);
v.plane(0,Phi,-1);
v.plane(0,-Phi,-1);
v.plane(1,0,Phi);
v.plane(-1,0,Phi);
v.plane(1,0,-Phi);
v.plane(-1,0,-Phi);
v.plane(Phi,1,0);
v.plane(-Phi,1,0);
v.plane(Phi,-1,0);
v.plane(-Phi,-1,0);
v.draw_gnuplot(0,0,0,"dodecahedron.gnu");
// Create an icosahedron
v.init(-2,2,-2,2,-2,2);
v.plane(1,1,1);
v.plane(-1,1,1);
v.plane(1,-1,1);
v.plane(-1,-1,1);
v.plane(1,1,-1);
v.plane(-1,1,-1);
v.plane(1,-1,-1);
v.plane(-1,-1,-1);
v.plane(0,phi,Phi);
v.plane(0,phi,-Phi);
v.plane(0,-phi,Phi);
v.plane(0,-phi,-Phi);
v.plane(Phi,0,phi);
v.plane(Phi,0,-phi);
v.plane(-Phi,0,phi);
v.plane(-Phi,0,-phi);
v.plane(phi,Phi,0);
v.plane(phi,-Phi,0);
v.plane(-phi,Phi,0);
v.plane(-phi,-Phi,0);
v.draw_gnuplot(0,0,0,"icosahedron.gnu");