DOCSEARCHbyAlgolia
Submit Docs

Voro++

repository·master·Indexed 42 days ago

https://github.com/chr1shr/voro

A high-performance C++ library for 3D cell-based Voronoi tessellation, optimized for calculating individual particle cell statistics such as volume and centroid. It supports standard and radical Voronoi tessellations for polydisperse packings, handles degenerate vertices via numerical tolerance, and provides tools for importing particle data, managing containers, and exporting results to gnuplot and POV-Ray.

Tokens
6.7K
Snippets
21
Records
41
Agent score
49%

What's inside Voro++

  1. Overview of Voro++

    master

    Voro++ is a C++ library designed for three-dimensional computations of the Voronoi tessellation. Unlike global tessellation methods, Voro++ performs cell-based calculations, computing the Voronoi cell for each particle individually. This makes it ideal for analyzing particle systems where cell-specific statistics—such as volume, centroid, or number of faces—are required.

    The library provides:

    • A set of C++ classes that can be built as a static library.
    • A command-line utility for analyzing particle configuration text files.
    • Numerous examples for various use cases.

  3. Understanding degenerate vertex support in Voro++

    master

    In typical Voronoi tessellations, cell vertices are of order 3 (the intersection of exactly three planes). However, in certain geometries or large systems, multiple planes may intersect at a single point, creating higher-order vertices (e.g., an octahedron).

    Voro++ handles these 'degenerate' cases using a numerical tolerance approach: if a plane is within a specific tolerance of an existing vertex, the library treats the plane as perfectly intersecting that vertex and recomputes the cell topology. This ensures robust handling of complex geometries and prevents errors in large-scale simulations.

  4. Optimize voro++ computational grid performance

    master

    Voro++ divides the computational box into a grid of rectangular blocks. For maximum performance, aim for an average of 3 to 8 particles per block and use blocks that are close to cubes.

    You can manually configure the grid to avoid the overhead of automatic estimation:

    • -l <len>: Specify a typical length scale between particles (e.g., particle diameter) to help estimate the optimal grid size.
    • -n <nx> <ny> <nz>: Manually specify the number of blocks in the x, y, and z directions.
    • -m <mem>: Manually specify the initial number of particles to store in each block (default is 8).

  5. Analyze individual Voronoi cell features in C++

    master
    Since version 0.4, Voro++ provides routines to directly analyze the features of a single Voronoi cell or cells within a particle packing. You can use these routines to inspect cell faces, determine the number of sides per face, and extract geometric properties.

  6. Handle boundary conditions with wall support

    master

    Voro++ handles complicated boundary conditions by adding plane cuts representing walls. The library provides built-in support for plane, cylindrical, and spherical walls. Users can also implement custom wall types by deriving new C++ classes from the pure virtual wall class.

    Important Constraints:

    • Convexity: The current implementation only supports walls that result in convex computational domains. Non-convex domains can lead to non-convex cells, which are not supported. To handle non-convex domains, you should divide the domain into several convex sub-domains, perform calculations in each, and then merge (glue) the cells that cross the boundaries.
    • Curved Wall Accuracy: Currently, curved walls are approximated using a single plane cut. This is accurate when particles are pressed against the walls but may be inaccurate if particles are sparse. Accuracy can be improved by approximating curved surfaces with a sequence of planes instead of a single one.

  7. Iterate over particle subsets using loop classes

    master

    Voro++ provides loop classes to iterate over specific subsets of particles within a container. Two primary classes are used for this purpose:

    • c_loop_order: Used to loop over a specific, pre-computed list of particles.
    • c_loop_subset: Used to loop over particles located within a specific region of the container.

    These classes are useful for performing computations (like Voronoi tessellation) only on particles that meet certain spatial or ordered criteria.

  8. Configure boundary conditions and periodicity in voro++

    master

    By default, voro++ assumes non-periodic boundary conditions. You can enable periodicity using the following flags:

    • -p: Make the container periodic in all three coordinate directions.
    • -px: Make the container periodic in the x direction.
    • -py: Make the container periodic in the y direction.
    • -pz: Make the container periodic in the z direction.

    When periodicity is enabled, particles are re-mapped into the primary domain during import. In the output, negative neighbor IDs (via %n) correspond to periodic images.

  9. Sum volumes in a .vol file with sum.pl

    master
    Use the sum.pl script to calculate the sum of volumes within a .vol file. This is primarily used for verification purposes after generating a .vol file with the Voro++ command-line utility.

  10. Explore Voro++ example programs

    master

    The examples/ directory provides a categorized collection of programs to help you learn how to use the Voro++ library. The examples are organized into the following functional areas:

    • basic: Simple scripts for learning basic classes and performing fundamental operations, such as constructing a single cell or creating a Voronoi tessellation for a small number of random particles in a box.
    • walls: Demonstrations of how to use wall objects to calculate Voronoi cells in non-standard geometries.
    • custom: Guides on customizing library output to include various statistics about computed Voronoi cells, as well as implementing radical tessellations for polydisperse particle packings.
    • interface: Examples specifically demonstrating the features of the Voro++ C++ interface.
    • extra: Miscellaneous applications for non-standard usage, including using wall objects to approximate irregular boundaries.
    • degenerate: Code demonstrating how the library handles "degenerate" vertices (order > 3) that occur when cutting planes align with existing vertices within numerical tolerance.
    • timing: Scripts and programs used to benchmark and test the performance of the library under different configurations.

  11. Install Voro++ on Linux, Mac OS, or Windows with Cygwin

    master

    Voro++ uses GNU Make for compilation and installation on Linux, Mac OS, and Windows (via Cygwin).

    1. Configuration

    Before compiling, review the config.mk file in the top-level directory to ensure the settings match your system architecture and desired installation path.

    2. Compilation

    Run make to compile the static library, command-line utility, and examples. The compiled files will be located in the src directory. You can speed up compilation using parallel threads with make -j <n>.

    3. Installation

    To install the library, utility, and documentation to the default system path (/usr/local), run:

    sudo make install

    Note for users without root privileges: You can install Voro++ to your home directory by modifying config.mk and setting PREFIX=$(HOME) before running make and make install.

    # Compile with n threads
make -j 4

# Install to /usr/local
sudo make install

# Or install to home directory (after modifying config.mk)
make
make install