### Voro++ pre_container usage example

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/09-pre-container.md

Demonstrates creating a pre_container, importing particles from a file, guessing optimal block counts, creating a container, and transferring particles using setup().

```cpp
#include "voro++.hh"
using namespace voro;

int main() {
    // Create pre-container for domain [0, 10]³
    pre_container pre(0, 10, 0, 10, 0, 10, false, false, false);
    
    // Import particles from file (unknown count)
    pre.import("particles.txt");
    
    printf("Total particles: %d\n", pre.total_particles());
    
    // Guess optimal block configuration
    int nx, ny, nz;
    pre.guess_optimal(nx, ny, nz);
    printf("Optimal blocks: %d × %d × %d\n", nx, ny, nz);
    
    // Create container with optimal parameters
    container con(0, 10, 0, 10, 0, 10, nx, ny, nz, false, false, false, 8);
    
    // Transfer particles to container
    pre.setup(con);
    
    // Now use container normally
    con.draw_cells_gnuplot("cells.gnu");
    
    return 0;
}
```

--------------------------------

### Define Example Executables

Source: https://github.com/chr1shr/voro/blob/master/CMakeLists.txt

Builds example executables if VORO_BUILD_EXAMPLES is enabled. It iterates through example source files, creates executables, links them to the Voro++ library, and sets their runtime output directories.

```cmake
if (${VORO_BUILD_EXAMPLES})
	file(GLOB EXAMPLE_SOURCES examples/*/*.cc) 
	foreach(SOURCE ${EXAMPLE_SOURCES})
	string(REGEX REPLACE "^.*/([^/]*)\.cc$" "\1" PROGNAME "${SOURCE}")
	if (NOT PROGNAME STREQUAL ellipsoid) #ellipsoid is broken
		string(REGEX REPLACE "^.*/(examples/.*)/${PROGNAME}\.cc$" "\1" DIRNAME "${SOURCE}")
		add_executable(${PROGNAME} ${SOURCE})
		target_link_libraries(${PROGNAME} PRIVATE voro++)
		set_target_properties(${PROGNAME} PROPERTIES 
		runtime_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/${DIRNAME}" )
	endif()
	endforeach(SOURCE)
endif()
```

--------------------------------

### Custom Wall Implementation Example

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/07-walls.md

Example demonstrating how to create a custom wall by deriving from the 'wall' class and adding it to a Voro++ container.

```APIDOC
### Usage Pattern

```cpp
// Create a custom wall by deriving from wall class
class my_wall : public wall {
public:
    bool point_inside(double x, double y, double z) {
        // Implementation
    }
    bool cut_cell(voronoicell &c, double x, double y, double z) {
        // Implementation
    }
    bool cut_cell(voronoicell_neighbor &c, double x, double y, double z) {
        // Implementation
    }
};

container con(...);
my_wall w;
con.add_wall(w);
```
```

--------------------------------

### Install Voro++ Headers and Man Page

Source: https://github.com/chr1shr/voro/blob/master/CMakeLists.txt

Installs the Voro++ header files from the 'src' directory and the man page to their respective installation destinations.

```cmake
file(GLOB_RECURSE VORO_HEADERS src/*.hh)
install(FILES ${VORO_HEADERS} DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/man/voro++.1 DESTINATION ${CMAKE_INSTALL_MANDIR}/man1)
```

--------------------------------

### Basic Voro++ Initialization and Setup

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/10-types.md

Demonstrates how to include the Voro++ library, access configuration constants, and set up a spherical subset for processing.

```cpp
#include "voro++.hh"
using namespace voro;

int main() {
    // Use configuration constants
    printf("Default tolerance: %.2e\n", tolerance);
    printf("Default particle radius: %g\n", default_radius);
    printf("Optimal particles/block: %g\n", optimal_particles);
    
    // Create loop subset with enumeration
    c_loop_subset loop(con);
    loop.setup_sphere(5.0, 5.0, 5.0, 2.0);  // loop_subset_mode::sphere
    
    return 0;
}
```

--------------------------------

### Minimal Voro++ Example

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/14-quick-start.md

This is a minimal example demonstrating the basic usage pattern of Voro++. It creates a container, adds particles, and outputs Voronoi cells to a file. Compile and link using the provided commands.

```cpp
#include "voro++.hh"
using namespace voro;

int main() {
    // Step 1: Create container
    // Domain: [0, 10]³ divided into 4×4×4 blocks
    container con(0, 10, 0, 10, 0, 10, 4, 4, 4, false, false, false, 8);
    
    // Step 2: Add particles
    con.put(0, 2.5, 2.5, 2.5);
    con.put(1, 5.0, 5.0, 5.0);
    con.put(2, 7.5, 7.5, 7.5);
    
    // Step 3: Compute and output cells
    con.draw_cells_gnuplot("cells.gnu");
    
    return 0;
}
```

```bash
g++ -I/usr/local/include/voro++ -c program.cc
g++ program.o -L/usr/local/lib -lvoro++ -o program
./program
```

--------------------------------

### setup (direct)

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/09-pre-container.md

Transfers all stored particles to a target container_poly. This is a direct transfer without considering any specific ordering.

```APIDOC
## setup (direct)

### Description
Transfers all stored particles to a target container_poly. This is a direct transfer without considering any specific ordering.

### Method
`void setup(container_poly &con)`

### Parameters
- **con** (container_poly&) - Target container

### Returns
None
```

--------------------------------

### Voro++ Setup with File Input

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/README.md

Demonstrates how to initialize a Voro++ container by importing particle data from a text file and optimizing the grid settings.

```cpp
pre_container pre(0, 10, 0, 10, 0, 10, false, false, false);
pre.import("particles.txt");

int nx, ny, nz;
pre.guess_optimal(nx, ny, nz);

container con(0, 10, 0, 10, 0, 10, nx, ny, nz, false, false, false, 8);
pre.setup(con);

con.draw_cells_gnuplot("cells.gnu");
```

--------------------------------

### setup Method (with ordering)

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/09-pre-container.md

Transfers stored particles to a target container and records their order for later iteration using a provided particle_order object.

```APIDOC
## setup Method (with ordering)

### Description
Transfers stored particles to a target container and records their order for later iteration using a provided particle_order object.

### Parameters
#### Path Parameters
- **vo** (particle_order&) - Order tracking object
- **con** (container&) - Target container

### Returns
None
```

--------------------------------

### setup Method (Direct)

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/09-pre-container.md

Transfers stored particles to a target container. This method automatically determines optimal block parameters internally.

```APIDOC
## setup Method (Direct)

### Description
Transfers stored particles to a target container. This method automatically determines optimal block parameters internally.

### Parameters
#### Path Parameters
- **con** (container&) - Target container to receive particles

### Returns
None

**Note:** Container must be empty. This method guesses optimal block counts and transfers particles.
```

--------------------------------

### Voro++ Voronoi Cell Usage Example

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/01-voronoicell-base.md

Demonstrates the basic usage of the `voronoicell_base` class. It initializes a cell, performs a plane cut to simulate a Voronoi computation, and then prints the cell's volume, surface area, and centroid. The example also shows how to output the cell geometry for visualization.

```cpp
#include "voro++.hh"
using namespace voro;

int main() {
    // Create a cell as a box
    voronoicell_base cell(1000.0);
    cell.init_base(-1, 1, -1, 1, -1, 1);
    
    // Cut cell by a plane (perpendicular bisector from origin to (0.5, 0.5, 0.5))
    // This simulates computing the Voronoi cell for a particle at origin
    // with respect to a neighbor at (0.5, 0.5, 0.5)
    
    // Compute statistics
    double vol = cell.volume();
    double sa = cell.surface_area();
    double cx, cy, cz;
    cell.centroid(cx, cy, cz);
    
    printf("Volume: %g\n", vol);
    printf("Surface Area: %g\n", sa);
    printf("Centroid: (%g, %g, %g)\n", cx, cy, cz);
    
    // Output in Gnuplot format
    cell.draw_gnuplot(0, 0, 0, "cell.gnu");
    
    return 0;
}
```

--------------------------------

### Voro++ Wall Plane Usage Example

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/07-walls.md

Demonstrates creating a Voro++ container and adding two opposing plane walls to constrain particles. The example shows how to define planes with normals pointing in opposite directions and how to add particles before drawing the resulting cells.

```cpp
#include "voro++.hh"
using namespace voro;

int main() {
    container con(0, 10, 0, 10, 0, 10, 4, 4, 4, false, false, false, 8);
    
    // Create plane at z=5, with normal pointing in +z direction
    wall_plane lower_wall(0, 0, 1, 5);
    con.add_wall(lower_wall);
    
    // Create plane at z=5, with normal pointing in -z direction (upper bound)
    wall_plane upper_wall(0, 0, -1, -5);
    con.add_wall(upper_wall);
    
    // Add particles
    con.put(0, 5.0, 5.0, 2.0);
    con.put(1, 5.0, 5.0, 8.0);
    
    // Cells will be constrained between z=0 and z=10
    con.draw_cells_gnuplot("cells.gnu");
    
    return 0;
}
```

--------------------------------

### Install Voro++ Library

Source: https://github.com/chr1shr/voro/blob/master/CMakeLists.txt

Installs the Voro++ library target to the appropriate directory based on CMAKE_INSTALL_LIBDIR.

```cmake
install(TARGETS voro++ EXPORT VORO_Targets LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR} ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR})
```

--------------------------------

### Voro++ Container Usage Example

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/04-container.md

Demonstrates the basic usage of the Voro++ container, including initialization, particle addition, cell and particle output, volume summation, and iterating through particles.

```cpp
#include "voro++.hh"
using namespace voro;

int main() {
    // Create container: [0, 10]³, divided into 4×4×4 blocks, non-periodic
    container con(0, 10, 0, 10, 0, 10, 4, 4, 4, false, false, false, 8);
    
    // Add some particles
    con.put(0, 2.5, 2.5, 2.5);
    con.put(1, 5.0, 5.0, 5.0);
    con.put(2, 7.5, 7.5, 7.5);
    
    // Compute and output all Voronoi cells
    con.draw_cells_gnuplot("cells.gnu");
    
    // Output particles
    con.draw_particles("particles.txt");
    
    // Sum volumes (should equal 1000 for [0,10]³)
    double vol_sum = con.sum_cell_volumes();
    printf("Total cell volume: %g (container: 1000)\n", vol_sum);
    
    // Use a loop to process specific particles
    c_loop_all loop(con);
    loop.start();
    do {
        double x, y, z;
        loop.pos(x, y, z);
        printf("Particle %d at (%.2f, %.2f, %.2f)\n", loop.pid(), x, y, z);
    } while (loop.inc());
    
    return 0;
}
```

--------------------------------

### Compute Voronoi Cells and Get Neighbors

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/12-voronoicell-neighbor.md

This example shows how to create a container, add particles, and then iterate through each particle to compute its Voronoi cell using `voronoicell_neighbor`. It retrieves and prints the number of faces and the IDs of neighboring particles.

```cpp
#include "voro++.hh"
using namespace voro;

int main() {
    // Create a simple container
    container con(0, 10, 0, 10, 0, 10, 4, 4, 4, false, false, false, 8);
    
    // Add particles
    con.put(0, 2.5, 2.5, 2.5);
    con.put(1, 5.0, 5.0, 5.0);
    con.put(2, 7.5, 7.5, 7.5);
    con.put(3, 2.5, 7.5, 7.5);
    
    // Use neighbor-tracking cell
    c_loop_all loop(con);
    if (loop.start()) {
        do {
            voronoicell_neighbor c;
            if (con.compute_cell(c, loop)) {
                // Get neighbor information
                std::vector<int> neighbors;
                c.neighbors(neighbors);
                
                printf("Particle %d: %d faces\n", loop.pid(), neighbors.size());
                printf("  Neighbors: ");
                for (int n : neighbors) {
                    printf("%d ", n);
                }
                printf("\n");
            }
        } while (loop.inc());
    }
    
    return 0;
}
```

--------------------------------

### Generate and Install Package Configuration Files

Source: https://github.com/chr1shr/voro/blob/master/CMakeLists.txt

Generates and installs the VOROConfig.cmake and VOROConfigVersion.cmake files, which are used by other CMake projects to find and use the Voro++ library.

```cmake
# no external deps for we can use target file as config file
install(EXPORT VORO_Targets FILE VOROConfig.cmake NAMESPACE VORO:: DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/VORO)
include(CMakePackageConfigHelpers)
write_basic_package_version_file("VOROConfigVersion.cmake" VERSION ${PROJECT_VERSION} COMPATIBILITY ExactVersion)
install(FILES "${CMAKE_CURRENT_BINARY_DIR}/VOROConfigVersion.cmake" DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/VORO)
```

--------------------------------

### Minimal Voro++ Container Setup

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/README.md

This snippet shows the most basic way to initialize a Voro++ container, add particles, and draw the resulting Voronoi cells to a file.

```cpp
#include "voro++.hh"
using namespace voro;

int main() {
    container con(0, 10, 0, 10, 0, 10, 4, 4, 4, false, false, false, 8);
    con.put(0, 2.5, 2.5, 2.5);
    con.put(1, 5.0, 5.0, 5.0);
    con.draw_cells_gnuplot("cells.gnu");
    return 0;
}
```

--------------------------------

### setup (with ordering)

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/09-pre-container.md

Transfers stored particles to a target container_poly and records their order using a provided particle_order object. This is useful for maintaining a specific sequence of particles.

```APIDOC
## setup (with ordering)

### Description
Transfers stored particles to a target container_poly and records their order using a provided particle_order object. This is useful for maintaining a specific sequence of particles.

### Method
`void setup(particle_order &vo, container_poly &con)`

### Parameters
- **vo** (particle_order&) - Order tracking object
- **con** (container_poly&) - Target container

### Returns
None
```

--------------------------------

### Voro++ Usage Example with pre_container_poly

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/09-pre-container.md

Demonstrates the typical workflow of using pre_container_poly to import particles with radii, determine optimal container parameters, and transfer them to a container_poly for Voronoi cell computation.

```cpp
#include "voro++.hh"
using namespace voro;

int main() {
    // Create pre-container for particles with radii
    pre_container_poly pre(0, 10, 0, 10, 0, 10, false, false, false);
    
    // Import particles from file (format: id x y z radius)
    pre.import("particles_with_radii.txt");
    
    printf("Total particles: %d\n", pre.total_particles());
    
    // Determine optimal block grid
    int nx, ny, nz;
    pre.guess_optimal(nx, ny, nz);
    
    // Create container_poly with optimal parameters
    container_poly con(0, 10, 0, 10, 0, 10, nx, ny, nz, false, false, false, 8);
    
    // Transfer particles
    pre.setup(con);
    
    // Use container
    con.draw_cells_gnuplot("radical_cells.gnu");
    
    return 0;
}
```

--------------------------------

### Voro++ Periodic Container Usage Example

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/08-periodic-containers.md

Demonstrates creating a simple cubic periodic domain, adding particles, computing Voronoi cells, and drawing them using Gnuplot. Includes volume verification.

```cpp
#include "voro++.hh"
using namespace voro;

int main() {
    // Create orthogonal periodic domain (simple cubic)
    // Domain: 0≤x<10, 0≤y<10, 0≤z<10
    container_periodic con(10, 0, 10, 0, 0, 10, 4, 4, 4, 8);
    
    // Add particles
    con.put(0, 2.5, 2.5, 2.5);
    con.put(1, 5.0, 5.0, 5.0);
    con.put(2, 7.5, 7.5, 7.5);
    
    // Compute Voronoi cells
    con.draw_cells_gnuplot("periodic_cells.gnu");
    
    // Verify volume
    double vol = con.sum_cell_volumes();
    printf("Total cell volume: %g (domain: 1000)\n", vol);
    
    return 0;
}
```

--------------------------------

### Voro++ Usage Example with Cylindrical Wall

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/07-walls.md

Demonstrates creating a container, adding a cylindrical wall along the z-axis, adding particles inside the cylinder, and visualizing the resulting cells.

```cpp
#include "voro++.hh"
using namespace voro;

int main() {
    container con(-10, 10, -10, 10, -10, 10, 4, 4, 4, false, false, false, 8);
    
    // Create cylinder along z-axis at origin with radius 5
    // Direction vector (0, 0, 1) normalized to length 1
    wall_cylinder cyl(0, 0, 0, 0, 0, 1, 5);
    con.add_wall(cyl);
    
    // Add particles in cylinder
    con.put(0, 0, 0, 5);
    con.put(1, 3, 0, -3);
    con.put(2, 0, 4, 0);
    
    con.draw_cells_gnuplot("cells_in_cylinder.gnu");
    
    return 0;
}
```

--------------------------------

### Voro++ Non-Orthogonal Domain Example

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/08-periodic-containers.md

Demonstrates how to create and use a non-orthogonal periodic container in Voro++. Includes setting up the domain vectors, adding particles, and outputting cell data.

```cpp
#include "voro++.hh"
using namespace voro;

int main() {
    // Create non-orthogonal domain with vectors:
    // v1 = (10, 0, 0)
    // v2 = (2, 10, 0)    [sheared in x-direction]
    // v3 = (0, 0, 10)
    double bx = 10, bxy = 2, by = 10, bxz = 0, byz = 0, bz = 10;
    
    container_periodic con(bx, bxy, by, bxz, byz, bz, 4, 4, 4, 8);
    
    // Add particles
    for (int i = 0; i < 20; i++) {
        double x = (double)rand() / RAND_MAX * bx;
        double y = (double)rand() / RAND_MAX * by;
        double z = (double)rand() / RAND_MAX * bz;
        con.put(i, x, y, z);
    }
    
    // Compute and output
    con.draw_cells_gnuplot("sheared_cells.gnu");
    
    return 0;
}
```

--------------------------------

### Voro++ Simulation with Cone Wall

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/07-walls.md

Example demonstrating how to create a container, add a wall_cone, add particles, and visualize the cells. The cone is defined with its apex at the origin, axis along +z, and a half-angle of 30 degrees.

```cpp
#include "voro++.hh"
using namespace voro;

int main() {
    container con(-10, 10, -10, 10, -10, 10, 4, 4, 4, false, false, false, 8);
    
    // Create cone with apex at origin, axis along +z, half-angle 30°
    double angle = M_PI / 6;  // 30 degrees in radians
    wall_cone cone(0, 0, 0, 0, 0, 1, angle);
    con.add_wall(cone);
    
    // Add particles inside cone
    con.put(0, 0, 0, 3);
    con.put(1, 2, 2, 5);
    
    con.draw_cells_gnuplot("cells_in_cone.gnu");
    
    return 0;
}
```

--------------------------------

### Wall Integration with Neighbor Tracking

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/12-voronoicell-neighbor.md

This example shows how to add a wall with a specific ID to the container and then compute a cell. If the cell intersects the wall, the wall's ID will appear in the neighbor list obtained via `c.neighbors()`.

```cpp
container con(0, 10, 0, 10, 0, 10, 4, 4, 4, false, false, false, 8);

// Add a wall with ID 100
wall_plane boundary(0, 0, 1, 5, 100);
con.add_wall(boundary);

con.put(0, 5.0, 5.0, 2.0);

voronoicell_neighbor c;
con.compute_cell(c, 0, 0);

std::vector<int> neighbors;
c.neighbors(neighbors);

// If cell touches wall, neighbor list will contain 100
for (int n : neighbors) {
    if (n == 100) {
        printf("Cell touches wall\n");
    }
}
```

--------------------------------

### Set Include Directories for Voro++

Source: https://github.com/chr1shr/voro/blob/master/CMakeLists.txt

Configures public include directories for the Voro++ library, making its headers available during build and installation.

```cmake
#for voro++.hh
target_include_directories(voro++ PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src> $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>)
```

--------------------------------

### Voro++ Usage Example with Spherical Wall

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/07-walls.md

Demonstrates how to create a Voro++ container, add a spherical wall at the origin with a radius of 8, add particles inside this sphere, and then draw the resulting Voronoi cells.

```cpp
#include "voro++.hh"
using namespace voro;

int main() {
    container con(-10, 10, -10, 10, -10, 10, 4, 4, 4, false, false, false, 8);
    
    // Add a spherical boundary at origin with radius 8
    wall_sphere sphere(0, 0, 0, 8);
    con.add_wall(sphere);
    
    // Add particles inside sphere
    for (int i = 0; i < 10; i++) {
        double angle = 2 * M_PI * i / 10;
        double x = 6 * cos(angle);
        double y = 6 * sin(angle);
        double z = 3;
        con.put(i, x, y, z);
    }
    
    con.draw_cells_gnuplot("cells_in_sphere.gnu");
    
    return 0;
}
```

--------------------------------

### Voro++ Periodic Container with Radius Usage Example

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/08-periodic-containers.md

Demonstrates initializing a container_periodic_poly, adding particles with radii, and drawing the resulting radical Voronoi cells using gnuplot.

```cpp
#include "voro++.hh"
using namespace voro;

int main() {
    container_periodic_poly con(10, 0, 10, 0, 0, 10, 4, 4, 4, 8);
    
    con.put(0, 2.5, 2.5, 2.5, 1.0);
    con.put(1, 5.0, 5.0, 5.0, 1.2);
    con.put(2, 7.5, 7.5, 7.5, 0.9);
    
    con.draw_cells_gnuplot("radical_cells.gnu");
    
    return 0;
}
```

--------------------------------

### Iterate Over All Particles

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/06-loops.md

Use c_loop_all to iterate through every particle in the container. Ensure the container is initialized and particles are added before starting the loop.

```cpp
#include "voro++.hh"
using namespace voro;

int main() {
    container con(0, 10, 0, 10, 0, 10, 4, 4, 4, false, false, false, 8);
    con.put(0, 2.5, 2.5, 2.5);
    con.put(1, 5.0, 5.0, 5.0);
    con.put(2, 7.5, 7.5, 7.5);
    
    // Iterate over all particles
    c_loop_all loop(con);
    if (loop.start()) {
        do {
            double x, y, z;
            loop.pos(x, y, z);
            printf("Particle %d at (%.2f, %.2f, %.2f)\n", loop.pid(), x, y, z);
        } while (loop.inc());
    }
    
    return 0;
}
```

--------------------------------

### Usage Example: Creating and Processing Radical Cells

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/05-container-poly.md

Demonstrates creating a container_poly, adding particles with radii, computing and outputting radical Voronoi cells, and outputting particles with radii. Computes the total radical cell volume.

```cpp
#include "voro++.hh"
using namespace voro;

int main() {
    // Create container_poly: [0, 10]³, divided into 4×4×4 blocks
    container_poly con(0, 10, 0, 10, 0, 10, 4, 4, 4, false, false, false, 8);
    
    // Add particles with radii
    con.put(0, 2.5, 2.5, 2.5, 1.0);   // radius 1.0
    con.put(1, 5.0, 5.0, 5.0, 1.5);   // radius 1.5
    con.put(2, 7.5, 7.5, 7.5, 0.8);   // radius 0.8
    
    // Compute and output radical Voronoi cells
    con.draw_cells_gnuplot("radical_cells.gnu");
    
    // Output particles with radii
    con.draw_particles("particles_with_radii.txt");
    
    // Compute total volume
    double vol_sum = con.sum_cell_volumes();
    printf("Total radical cell volume: %g\n", vol_sum);
    
    return 0;
}
```

--------------------------------

### c_loop_all Class

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/06-loops.md

Iterates over all particles in the container in a defined order. It provides methods to start the loop, advance to the next particle, and access particle information.

```APIDOC
## c_loop_all Class

Iterates over all particles in the container, scanning blocks in order and particles within each block in order.

### Constructor

```cpp
template<class c_class>
c_loop_all(c_class &con);
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `con` | c_class& | Container to iterate over |

### Methods

#### start

```cpp
inline bool start();
```

Initializes the loop to the first particle.

**Returns:** True if there is at least one particle, False if container is empty

#### inc

```cpp
inline bool inc();
```

Advances to the next particle.

**Returns:** True if another particle exists, False if end of particles reached

### Usage Example

```cpp
#include "voro++.hh"
using namespace voro;

int main() {
    container con(0, 10, 0, 10, 0, 10, 4, 4, 4, false, false, false, 8);
    con.put(0, 2.5, 2.5, 2.5);
    con.put(1, 5.0, 5.0, 5.0);
    con.put(2, 7.5, 7.5, 7.5);
    
    // Iterate over all particles
    c_loop_all loop(con);
    if (loop.start()) {
        do {
            double x, y, z;
            loop.pos(x, y, z);
            printf("Particle %d at (%.2f, %.2f, %.2f)\n", loop.pid(), x, y, z);
        } while (loop.inc());
    }
    
    return 0;
}
```
```

--------------------------------

### c_loop_subset Class

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/06-loops.md

Iterates over particles within a specified geometric region such as a sphere, box, or a range of computational blocks. It requires setup methods to define the region before starting the iteration.

```APIDOC
## c_loop_subset Class

Iterates over particles within a specified geometric region (sphere, box, or block range).

### Constructor

```cpp
template<class c_class>
c_loop_subset(c_class &con);
```

### Setup Methods

#### setup_sphere

```cpp
void setup_sphere(double vx, double vy, double vz, double r, bool bounds_test = true);
```

Configures loop to iterate over particles within a sphere.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `vx, vy, vz` | double | — | Sphere center |
| `r` | double | — | Sphere radius |
| `bounds_test` | bool | true | Whether to test bounds of region |

#### setup_box

```cpp
void setup_box(double xmin, double xmax, double ymin, double ymax, 
               double zmin, double zmax, bool bounds_test = true);
```

Configures loop to iterate over particles within a rectangular box.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `xmin, xmax` | double | — | X coordinate range |
| `ymin, ymax` | double | — | Y coordinate range |
| `zmin, zmax` | double | — | Z coordinate range |
| `bounds_test` | bool | true | Whether to test bounds |

#### setup_intbox

```cpp
void setup_intbox(int ai_, int bi_, int aj_, int bj_, int ak_, int bk_);
```

Configures loop to iterate over particles within a range of computational blocks.

| Parameter | Type | Description |
|-----------|------|-------------|
| `ai_, bi_` | int | Block index range in x (ai_ inclusive, bi_ exclusive) |
| `aj_, bj_` | int | Block index range in y |
| `ak_, bk_` | int | Block index range in z |

### Methods

#### start

```cpp
bool start();
```

Initializes the loop to the first particle in the subset.

**Returns:** True if particles exist in subset, False otherwise

#### inc

```cpp
inline bool inc();
```

Advances to the next particle in the subset.

**Returns:** True if another particle exists, False if end reached

### Usage Example

```cpp
#include "voro++.hh"
using namespace voro;

int main() {
    container con(0, 10, 0, 10, 0, 10, 4, 4, 4, false, false, false, 8);
    
    // Add many particles...
    for (int i = 0; i < 100; i++) {
        double x = (double)rand() / RAND_MAX * 10;
        double y = (double)rand() / RAND_MAX * 10;
        double z = (double)rand() / RAND_MAX * 10;
        con.put(i, x, y, z);
    }
    
    // Iterate over particles in a sphere at center (5,5,5) with radius 2
    c_loop_subset loop(con);
    loop.setup_sphere(5.0, 5.0, 5.0, 2.0);
    
    if (loop.start()) {
        int count = 0;
        do {
            count++;
        } while (loop.inc());
        printf("Particles in sphere: %d\n", count);
    }
    
    return 0;
}
```
```

--------------------------------

### Get Face Perimeters

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/01-voronoicell-base.md

Computes and stores the perimeter of each face in the provided vector. Useful for edge-length related analyses.

```cpp
void face_perimeters(std::vector<double> &v);
```

--------------------------------

### Get Face Areas

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/01-voronoicell-base.md

Computes and stores the area of each face in the provided vector. Use this for surface-based calculations or comparisons.

```cpp
void face_areas(std::vector<double> &v);
```

--------------------------------

### Get Face Orders

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/01-voronoicell-base.md

Stores the number of sides for each face in the provided vector. This indicates the polygon type of each face.

```cpp
void face_orders(std::vector<int> &v);
```

--------------------------------

### Get Face Normals

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/01-voronoicell-base.md

Computes and stores normal vectors for each face. Each normal vector consists of 3 double-precision components.

```cpp
void normals(std::vector<double> &v);
```

--------------------------------

### Complete Voro++ Workflow with pre_container

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/09-pre-container.md

This C++ code demonstrates the full process of importing particles, determining an optimal grid, setting up the Voronoi container, and outputting results. It requires an input file containing particle coordinates.

```cpp
#include "voro++.hh"
using namespace voro;

int main(int argc, char **argv) {
    if (argc < 2) {
        fprintf(stderr, "Usage: %s <input_file>\n", argv[0]);
        return 1;
    }
    
    // Stage 1: Import particles of unknown count
    pre_container pre(0, 10, 0, 10, 0, 10, false, false, false);
    pre.import(argv[1]);
    
    int np = pre.total_particles();
    printf("Imported %d particles\n", np);
    
    // Stage 2: Determine optimal block structure
    int nx, ny, nz;
    pre.guess_optimal(nx, ny, nz);
    printf("Optimal block grid: %d × %d × %d\n", nx, ny, nz);
    printf("Particles per block: %.1f\n", 
           (double)np / (nx * ny * nz));
    
    // Stage 3: Create container with optimal parameters
    container con(0, 10, 0, 10, 0, 10, nx, ny, nz, false, false, false, 8);
    particle_order order;
    pre.setup(order, con);
    
    // Stage 4: Compute and analyze Voronoi cells
    double total_vol = con.sum_cell_volumes();
    printf("Total cell volume: %g (domain: 1000)\n", total_vol);
    
    // Stage 5: Output results
    con.draw_particles("particles.txt");
    con.draw_cells_gnuplot("cells.gnu");
    con.draw_domain_gnuplot("domain.gnu");
    
    printf("Results written to cells.gnu and domain.gnu\n");
    
    return 0;
}

```

--------------------------------

### Get Vertex Coordinates

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/01-voronoicell-base.md

Stores all vertex coordinates in the provided vector. Each vertex is represented by 3 double-precision floating-point numbers.

```cpp
void vertices(std::vector<double> &v);
```

--------------------------------

### Include Main Header and Namespace

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/00-index.md

Include the main Voro++ header file to access all necessary classes and use the voro namespace.

```cpp
#include "voro++.hh"
using namespace voro;
```

--------------------------------

### Initialize and Iterate with c_loop_order

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/06-loops.md

Demonstrates how to add particles to a container, record their order, and then iterate through them using `c_loop_order`. This is useful when you need to process particles in a specific sequence.

```cpp
#include "voro++.hh"
using namespace voro;

int main() {
    container con(0, 10, 0, 10, 0, 10, 4, 4, 4, false, false, false, 8);
    particle_order order;
    
    // Add particles, recording order
    con.put(order, 0, 1.0, 1.0, 1.0);
    con.put(order, 1, 2.0, 2.0, 2.0);
    con.put(order, 2, 3.0, 3.0, 3.0);
    
    // Iterate in the recorded order
    c_loop_order loop(con, order);
    if (loop.start()) {
        do {
            voronoicell c;
            if (con.compute_cell(c, loop)) {
                printf("Cell %d volume: %g\n", loop.pid(), c.volume());
            }
        } while (loop.inc());
    }
    
    return 0;
}
```

--------------------------------

### Get Solid Angles

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/01-voronoicell-base.md

Computes and stores the solid angle subtended by each face at the cell center. This is relevant for volumetric or angular analyses.

```cpp
void solid_angles(std::vector<double> &v);
```

--------------------------------

### Input File Format for pre_container_poly (with radii)

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/09-pre-container.md

This is the format for input files when using `pre_container_poly` and particle radii are provided. Each line should contain the particle ID, X, Y, Z coordinates, and the particle's radius.

```text
particle_id x y z radius
1 1.0 2.0 3.0 1.2
2 4.5 5.5 6.5 0.8
3 7.0 8.0 9.0 1.5
...

```

--------------------------------

### Retrieve Particle Position (Coordinates Only)

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/06-loops.md

Use this method to get the x, y, and z coordinates of the current particle. The output parameters are passed by reference.

```cpp
inline void pos(double &x, double &y, double &z);
```

--------------------------------

### Building and Linking Voro++

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/00-index.md

Instructions for including Voro++ headers and linking against the static library during compilation.

```bash
# Include path
-I/usr/local/include/voro++

# Link with static library
-L/usr/local/lib -lvoro++
```

--------------------------------

### Get Total Particle Count

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/03-container-base.md

Returns the total number of particles currently stored within the container. This is an inline method for efficient retrieval.

```cpp
inline int total_particles();
```

--------------------------------

### Define User Input Options

Source: https://github.com/chr1shr/voro/blob/master/CMakeLists.txt

Defines boolean options for users to control build features such as shared libraries, examples, command-line tools, and Doxygen.

```cmake
option(VORO_BUILD_SHARED_LIBS "Build shared libs" ON)
include(GNUInstallDirs)

option(VORO_BUILD_EXAMPLES "Build examples" ON)
option(VORO_BUILD_CMD_LINE "Build command line project" ON)
option(VORO_ENABLE_DOXYGEN "Enable doxygen" ON)
```

--------------------------------

### Periodic Domain Container Initialization

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/14-quick-start.md

Use this constructor for simulation domains with periodic boundaries, common in molecular dynamics. It sets up the domain for periodic calculations.

```cpp
container_periodic con(bx, bxy, by, bxz, byz, bz, nx, ny, nz, init_mem);
```

--------------------------------

### Get Vertex Orders

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/01-voronoicell-base.md

Stores the number of adjacent vertices for each vertex in the provided vector. Use this to understand the connectivity of the Voronoi cell's vertices.

```cpp
void vertex_orders(std::vector<int> &v);
```

--------------------------------

### Handle Unknown Particle Count with Pre-Container

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/00-index.md

Uses a pre-container to import particles from a file when the exact particle count is unknown, guesses optimal grid dimensions, and then sets up the main container.

```cpp
pre_container pre(ax, bx, ay, by, az, bz, xp, yp, zp);
pre.import("large_file.txt");
int nx, ny, nz;
pre.guess_optimal(nx, ny, nz);
container con(ax, bx, ay, by, az, bz, nx, ny, nz, xp, yp, zp, 8);
pre.setup(con);
```

--------------------------------

### Fix 'Container out of bounds' Error in Voro++

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/14-quick-start.md

Ensure particle positions are within the defined domain bounds. This example shows an incorrect placement and the expected error.

```cpp
container con(0, 10, 0, 10, 0, 10, ...);
con.put(0, 11, 5, 5);  // ERROR: x=11 > 10
```

--------------------------------

### Importing Particles from File

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/05-container-poly.md

Shows how to import particles with radii from a file into a container_poly and then draw the resulting Voronoi cells. The input file must follow the format: particle_id x y z radius.

```cpp
container_poly con(0, 10, 0, 10, 0, 10, 4, 4, 4, false, false, false, 8);
con.import("particles_with_radii.txt");
con.draw_cells_gnuplot("cells.gnu");
```

--------------------------------

### Wall ID and Neighbor Tracking with wall_plane

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/07-walls.md

Demonstrates how to add a wall with an ID for neighbor tracking and how to retrieve this ID from computed voronoicell_neighbor objects.

```cpp
wall_plane wall_with_id(0, 0, 1, 5, 100);  // Wall ID = 100
con.add_wall(wall_with_id);

c_loop_all loop(con);
loop.start();
do {
    voronoicell_neighbor c;
    con.compute_cell(c, loop);
    
    // Get neighbor information (includes wall IDs)
    std::vector<int> neighbors;
    c.neighbors(neighbors);
    
    // neighbors vector will contain wall IDs for faces touching walls
} while (loop.inc());
```

--------------------------------

### Get Displaced Vertex Coordinates

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/01-voronoicell-base.md

Stores all vertex coordinates displaced by a given offset vector. Useful for visualizing or analyzing cells relative to a shifted origin.

```cpp
void vertices(double x, double y, double z, std::vector<double> &v);
```

--------------------------------

### Get Maximum Radius Squared from Origin

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/01-voronoicell-base.md

Returns the maximum distance squared from the origin to any vertex of the cell. Useful for bounding box calculations or spatial queries.

```cpp
double max_radius_squared();
```

--------------------------------

### pre_container_poly Constructor

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/09-pre-container.md

Initializes a new pre_container_poly instance. It takes bounding box dimensions and periodicity flags as parameters, similar to the container_poly constructor.

```APIDOC
## Constructor pre_container_poly

### Description
Initializes a new pre_container_poly instance. It takes bounding box dimensions and periodicity flags as parameters, similar to the container_poly constructor.

### Parameters
- **ax_, bx_** (double) - X-axis bounding box limits
- **ay_, by_** (double) - Y-axis bounding box limits
- **az_, bz_** (double) - Z-axis bounding box limits
- **xperiodic_** (bool) - Whether the X-axis is periodic
- **yperiodic_** (bool) - Whether the Y-axis is periodic
- **zperiodic_** (bool) - Whether the Z-axis is periodic

### Returns
New pre_container_poly instance
```

--------------------------------

### Container Initialization with Block Count

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/14-quick-start.md

Initialize a container with a specified block count for optimal performance. Aim for 5-10 particles per block.

```cpp
int np = 1000;  // particles
int n = (int)pow(np / 5.6, 1.0/3.0);  // ~9 for 1000 particles
container con(0, L, 0, L, 0, L, n, n, n, false, false, false, 8);
```

--------------------------------

### Import Particles with Order Tracking

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/05-container-poly.md

Imports particles and records their ordering for later reference. Supports both file streams and filenames.

```cpp
void import(particle_order &vo, FILE *fp = stdin);
```

```cpp
void import(particle_order &vo, const char *filename);
```

--------------------------------

### pre_container_poly Constructor

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/09-pre-container.md

Initializes a new pre_container_poly instance. It takes boundary dimensions and periodicity flags as parameters, similar to the pre_container.

```cpp
pre_container_poly(double ax_, double bx_, double ay_, double by_, double az_, double bz_,
                   bool xperiodic_, bool yperiodic_, bool zperiodic_);
```

--------------------------------

### Initialize and Draw Unit Cell

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/08-periodic-containers.md

Demonstrates the initialization of a `unitcell` object and drawing its domain to a file. This is a foundational step for periodic Voronoi cell computations.

```cpp
unitcell unit;  // Stores pre-computed unit Voronoi cell
unit.draw_domain_gnuplot("domain.gnu");
```

--------------------------------

### Import Particles from File

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/00-index.md

Imports particle data from a text file into a Voro container. The expected file format is 'id x y z'.

```cpp
container con(...);
con.import("particles.txt");  // Format: id x y z
```

--------------------------------

### step_div: Integer Division

Source: https://github.com/chr1shr/voro/blob/master/_autodocs/11-voro-base.md

Performs integer division with consistent behavior for negative numbers, returning the floor of a/b. Example: (-2,-1,0,1,2) step_div 2 → (-1,-1,0,0,1).

```cpp
protected: inline int step_div(int a, int b);
```