A high volume fraction sphere packing library
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
benches
examples
src
tests
.codecov.yml
.gitignore
.travis.yml
Cargo.toml
LICENSE-APACHE
LICENSE-MIT
README.md

README.md

Spherical Cow

A high volume fraction sphere packing library

Crates.io Docs.rs Travis-ci Codecov FOSSA Status

Based on the advancing fronts algorithm outlined in Valera et al., Computational Particle Mechanics 2, 161 (2015).

Milk production at a dairy farm was low, so the farmer wrote to the local university, asking for help from academia. A multidisciplinary team of professors was assembled, headed by a theoretical physicist, and two weeks of intensive on-site investigation took place. The scholars then returned to the university, notebooks crammed with data, where the task of writing the report was left to the team leader. Shortly thereafter the physicist returned to the farm, saying to the farmer, "I have the solution, but it works only in the case of spherical cows in a vacuum".

Usage

Complete documentation can be found at docs.rs.

A simple example to get you packing spheres of radii (0.1..0.2) into a container sphere of radius 2.

extern crate nalgebra;
extern crate rand;
extern crate spherical_cow;

use spherical_cow::shapes::Sphere;
use rand::distributions::Uniform;
use nalgebra::Point3;

fn main() {
    let boundary = Sphere::new(Point3::origin(), 2.0).unwrap();
    let mut sizes = Uniform::new(0.1, 0.2);

    let spheres = spherical_cow::pack_spheres(boundary, &mut sizes).unwrap();

    println!("Number of spheres: {}", spheres.len());
}

More elaborate examples can be found in the examples directory.

Output

True to its name, it is indeed possible to build a spherical cow:

spherical cow in vacuum

You can run this example yourself from show_in_cow.

Example use cases

The paper which this algorithm comes from gives two examples of real world use cases:

  1. Sphere packing a skull model to study fractures due to shocks and penetrating objects.
  2. Sphere packing a cutting tool to identify the failure / breaking points when the tool is placed under load.

The reason this library was initially written was to optimise the layout of inflatable space habitats which may one day be constructed on the Moon and Mars.

Changelog

  • 0.1.2

    • Patch release to fix hard failures due to rust-lang/rust#49799 (thanks hdhoang)
    • Small performance improvements via algebraic simplifications and minimising vector allocations.
    • Add itertools to simplify pair collection using .collect_tuple().
    • Added sphere_pack benchmarking target using criterion.
    • Upgrade to rand v0.5 which now uses HC-128: increasing our efficiency.
  • 0.1.1

    • Complete error handling.
    • Code coverage and testing suite filled out.
    • Add float-cmp for more robust floating point comparisons.
  • 0.1

    • Initial release.
    • Sphere and cuboid container shapes.
    • Contained trait for user defined shapes.
    • Fully functional in arbitrary geometry using user defined trimeshes.
    • Utility to identify volume of trimeshes using tetrahedron summation.
    • Utility to identify if spheres are contained within trimeshes via ray casting.
    • Volume fraction, void ratio, coordination number and fabric tensors provide quantitative analysis of packing.

License

Licensed under the Apache License, Version 2.0 or the MIT license, at your option. These files may not be copied, modified, or distributed except according to those terms.

FOSSA Status

Deeply linked dependencies

The wayland-protocols library (released under an MIT license) is used by kiss3d and obj, both of which are only extant in the examples directory of this project (and thus are NOT a part of the library). Content therein: the file misc/server-decoration.xml, is Copyright (C) 2015 Martin Gräßlin and licensed under the GNU Lesser General Public Library, version 2.1. You can find a copy of this license at https://www.gnu.org/licenses/lgpl-2.1.en.html