Home

Awesome

ExactPredicates.jl

→ Documentation

This package provides fast and robust predicates for Euclidean geometry. It is implemented as a code generator that transform any homogeneous polynomial into an algorithm that rigorously determines its sign on any given input points.

Installation

]add ExactPredicates

Features

Robust

Robust means that the code:

Why robustness matters?

When the input data is approximate it looks absurd to insist on exact computation. To determine if a point is inside or outside a circle, one may need more precision than the data really convey. So what is the point?

Robust computation is important because it guarantees soundness with respect to some combinatorial properties of the predicates, on which many algorithms rely. For example

orient(a, b, c) == orient(b, c, a) == orient(c, a, b),

this is a very basic geometric observation, but a floating computation may fail to see this.

“Inexact versions of these tests [orient and incircle] are vulnerable to roundoff error, and the wrong answers they produce can cause geometric algorithms to hang, crash, or produce incorrect output.”

—Jonathan Shewchuk, Robust Adaptive Floating-point Geometric Predicates

Fast

The reference point is the cost of the pure floating point evaluation, without any certification. To evaluate the performance, one need to distinguish several scenarios.

The quick path

For normal input (for example random input), the floating point computation is correct. The only overhead is the computation of the error bound. Expect a 2× slowdown with respect to the reference. On complicated predicates, like insphere, the floating point computation dominates and the slowdown is only 1.3×.

The emphasis in the package is to make the quick path as fast as possible.

The slow path

If the error estimation fails to certify the floating point computation, the code falls back to interval arithmetic, using IntervalArithmetic.jl. It will work especially well if the input points have small integer coordinates. Expect a 50× slowdown.

In this scenario, adaptive methods, like the one famously implemented by Shewchuk, may be more performant.

The worst path

When the input points are maximally degenerate, the code will resort to exact arithmetic using Rational{BigInt}. The computation will always succeed, but expect a 50-100× slowdown.

Usage

Basic usage

The type for representing points is NTuple{N, Float64}, where N is 2 or 3. Very concretely, that is Tuple{Float64,Float64} or Tuple{Float64,Float64,Float64}.

p, q, r, a = (1.0, 3.0), (1.5, 10.0), (-87.0, 1e64), (1e-100, 3.0)

incircle(p, q, r, a)
# -> 1

Working with other types of points

All the predicates will work with a type T, if one of the function Tuple(::T) or coord(::T) is defined and outputs a NTuple{N, Float64} that contains the coordinates the coordinates. Naturally, the computation is only robust if the conversion is robust too. Here is a typical use.

using ExactPredicates
struct Point
    x :: Float64
    y :: Float64
end

Tuple(p :: Point) = (p.x, p.y)
incircle(Point(0.0, 0.0), Point(1.0, 0.0), Point(0.0, 1.0), Point(.5, .5))

A nice type to represent points in the plane is Complex{Float64}. It is not desirable to redefine Tuple(::Complex), so we overload coord instead.

coord(p :: Float64) = (p, 0.0)
coord(p :: Complex) = reim(p)
incircle(0.0, 1.0, complex(0.0, 1.0), complex(.5, .5))

Another interesting type for points is SVector from StaticArrays. Tuple is already defined for this type, so we can use them readily.

using StaticArrays
incircle(SVector(0.0, 0.0), SVector(1.0, 0.0), SVector(0.0, 1.0), SVector(.5, .5))

In all the examples above, the conversion has no overhead.

Extensibility

The code generator turns any piece of code that evaluates a homogeneous polynomial into a robust piece of code that evaluates the sign of the same polynomial. It only needs hint to group variables into homogeneous groups.

For example, the discriminant of a degree 2 polynomial a x^2 + bx + c is b^2 - 4ac, which is a homogeneous polynomial in a, b and c. With ExactPredicates, you can write

using ExactPredicates
using ExactPredicates.Codegen

@genpredicate function discriminant(a, b, c)
    Codegen.group!(a, b, c)
    b*b - 4*a*c
end

It will define a function discriminant(a :: Float64, b :: Float64, c :: Float64) that returns 1, –1 or 0 depending on the sign of the determinant.

How it works

This package implements the method used by CGAL and described in:

The implementation relies on Julia's facilities for code generation and evaluates a priori the precision of the floating evaluation, relatively to the magnitude of the input variables.