Euclidean-norm ball (Ball2)

Ball2{N<:AbstractFloat, VN<:AbstractVector{N}} <: AbstractCentrallySymmetric{N}

Type that represents a ball in the 2-norm.

Fields

• center – center of the ball as a real vector
• radius – radius of the ball as a real scalar ($≥ 0$)

Notes

Mathematically, a ball in the 2-norm is defined as the set

where $c ∈ \mathbb{R}^n$ is its center and $r ∈ \mathbb{R}_+$ its radius. Here $‖ ⋅ ‖_2$ denotes the Euclidean norm (also known as 2-norm), defined as $‖ x ‖_2 = \left( \sum\limits_{i=1}^n |x_i|^2 \right)^{1/2}$ for any $x ∈ \mathbb{R}^n$.

Examples

Create a five-dimensional ball B in the 2-norm centered at the origin with radius 0.5:

julia> B = Ball2(zeros(5), 0.5)
Ball2{Float64,Array{Float64,1}}([0.0, 0.0, 0.0, 0.0, 0.0], 0.5)

julia> dim(B)
5

Evaluate B's support vector in the direction $[1,2,3,4,5]$:

julia> σ([1.,2.,3.,4.,5.], B)
5-element Array{Float64,1}:
 0.06741998624632421
 0.13483997249264842
 0.20225995873897262
 0.26967994498529685
 0.3370999312316211

σ(d::AbstractVector{N}, B::Ball2{N}) where {N<:AbstractFloat}

Return the support vector of a 2-norm ball in a given direction.

Input

• d – direction
• B – ball in the 2-norm

Output

The support vector in the given direction. If the direction has norm zero, the origin is returned.

Notes

Let $c$ and $r$ be the center and radius of a ball $B$ in the 2-norm, respectively. For nonzero direction $d$ we have

This function requires computing the 2-norm of the input direction, which is performed in the given precision of the numeric datatype of both the direction and the set. Exact inputs are not supported.

∈(x::AbstractVector{N}, B::Ball2{N}) where {N<:AbstractFloat}

Check whether a given point is contained in a ball in the 2-norm.

Input

• x – point/vector
• B – ball in the 2-norm

Output

true iff $x ∈ B$.

Notes

This implementation is worst-case optimized, i.e., it is optimistic and first computes (see below) the whole sum before comparing to the radius. In applications where the point is typically far away from the ball, a fail-fast implementation with interleaved comparisons could be more efficient.

Algorithm

Let $B$ be an $n$-dimensional ball in the 2-norm with radius $r$ and let $c_i$ and $x_i$ be the ball's center and the vector $x$ in dimension $i$, respectively. Then $x ∈ B$ iff $\left( ∑_{i=1}^n |c_i - x_i|^2 \right)^{1/2} ≤ r$.

Examples

julia> B = Ball2([1., 1.], sqrt(0.5))
Ball2{Float64,Array{Float64,1}}([1.0, 1.0], 0.7071067811865476)

julia> [.5, 1.6] ∈ B
false

julia> [.5, 1.5] ∈ B
true

center(B::Ball2{N}) where {N<:AbstractFloat}

Return the center of a ball in the 2-norm.

Input

• B – ball in the 2-norm

Output

The center of the ball in the 2-norm.

rand(::Type{Ball2}; [N]::Type{<:Real}=Float64, [dim]::Int=2,
     [rng]::AbstractRNG=GLOBAL_RNG, [seed]::Union{Int, Nothing}=nothing)

Create a random ball in the 2-norm.

Input

• Ball2 – type for dispatch
• N – (optional, default: Float64) numeric type
• dim – (optional, default: 2) dimension
• rng – (optional, default: GLOBAL_RNG) random number generator
• seed – (optional, default: nothing) seed for reseeding

Output

A random ball in the 2-norm.

Algorithm

All numbers are normally distributed with mean 0 and standard deviation 1. Additionally, the radius is nonnegative.

sample(B::Ball2{N, VN}, nsamples::Int=1;
       [rng]::AbstractRNG=GLOBAL_RNG,
       [seed]::Union{Int, Nothing}=nothing) where {N<:AbstractFloat, VN<:AbstractVector{N}}

Return samples from a uniform distribution on the given ball in the 2-norm.

Input

• B – ball in the 2-norm
• nsamples – (optional, default: 1) number of samples
• rng – (optional, default: GLOBAL_RNG) random number generator
• seed – (optional, default: nothing) seed for reseeding

Output

A linear array of nsamples elements drawn from a uniform distribution in B.

Algorithm

Random sampling with uniform distribution in B is computed using Muller's method of normalized Gaussians. This function requires the package Distributions. See _sample_unit_nball_muller! for implementation details.

sample(X::LazySet{N}, num_samples::Int;
       [sampler]=nothing,
       [rng]::AbstractRNG=GLOBAL_RNG,
       [seed]::Union{Int, Nothing}=nothing) where {N}

Sampling of an arbitrary bounded set X.

Input

• X – (bounded) set to be sampled
• num_samples – number of random samples
• sampler – sampler used (default: nothing, which falls back to RejectionSampler)
• rng – (optional, default: GLOBAL_RNG) random number generator
• seed – (optional, default: nothing) seed for reseeding

Output

A vector of num_samples vectors. If num_samples is not passed, the result is just one sample (not wrapped in a vector).

Algorithm

See the documentation of the respective Sampler.

translate(B::Ball2{N}, v::AbstractVector{N}) where {N<:AbstractFloat}

Translate (i.e., shift) a ball in the 2-norm by a given vector.

Input

• B – ball in the 2-norm
• v – translation vector

Output

A translated ball in the 2-norm.

Algorithm

We add the vector to the center of the ball.

chebyshev_center(B::Ball2{N}; compute_radius::Bool=false
                ) where {N<:AbstractFloat}

Compute the Chebyshev center of a ball in the 2-norm.

Input

• B – ball in the 2-norm
• compute_radius – (optional; default: false) option to additionally return the radius of the largest ball enclosed by B around the Chebyshev center

Output

If compute_radius is false, the result is the Chebyshev center of B. If compute_radius is true, the result is the pair (c, r) where c is the Chebyshev center of B and r is the radius of the largest ball with center c enclosed by B.

Notes

The Chebyshev center of a ball in the 2-norm is just the center of the ball.

volume(B::Ball2{N}) where {N<:AbstractFloat}

Return the volume of a ball in the 2-norm.

Input

• B – ball in the 2-norm

Output

The volume of $B$.

Algorithm

This function implements the well-known formula for the volume of an n-dimensional ball using factorials. For details see the wikipedia article Volume of an n-ball.