Geometry

abstract type AbstractCosmoGeometry end

Abstract type for (multi-dimensional) geometry volumes, particularly for filtering with filter.

Any subtypes of AbstractCosmoGeometry have to implement the following methods:

• CosmoParticles.geometry_enclosing_corners
• CosmoParticles.mask_in!

The following methods are optional, but have default implementations:

• CosmoParticles.geometry_enclosing_center
• CosmoParticles.mask_in
• CosmoParticles.translate

geometry_enclosing_corners(geo::AbstractCosmoGeometry)

Return the lower left and upper right corners of the enclosing box of the geometry as a tuple of vectors.

The enclosing box is not necessarily the tightest fitting box.

This is not exported.

geometry_enclosing_center(geo::AbstractCosmoGeometry)

Return the center of the enclosing box of the geometry as a vector.

This is not exported.

mask_in(pos::AbstractMatrix{<:Number}, geo::AbstractCosmoGeometry)

Return the BitArray mask of the positions ($\mathrm{dims} × N$) located within the geometry.

Calls mask_in! by default.

This is not exported.

mask_in!(mask::BitVector, pos::AbstractMatrix{<:Number}, geo::AbstractCosmoGeometry)

Return the BitVector mask of the positions ($\mathrm{dims} × N$) located within the geometry.

This is not exported.

struct CosmoHyperrectangle{T,N} <: AbstractCosmoGeometry where {T<:Number}
    lowerleft::Vector{T}
    upperright::Vector{T}
end

N-dimensional hyperrectangle aligned with the coordinate system axes given by its lower left and upper right corners.

The dimensions of space are given by N.

CosmoCuboid{T} = CosmoHyperrectangle{T,3}

Alias for a 3D CosmoHyperrectangle.

CosmoRectangle{T} = CosmoHyperrectangle{T,2}

Alias for a 2D CosmoHyperrectangle.

CosmoHypercube(center::AbstractVector{<:Number}, radius::Number)

Return a cubic CosmoCuboid centered around center, with equal sidelengths.

CosmoCube(center::AbstractVector{<:Number}, radius::Number)

Return a cubic CosmoCuboid centered around center, with equal sidelengths.

CosmoSquare(center::AbstractVector{<:Number}, radius::Number)

Return a square CosmoRectangle centered around center, with equal sidelengths.

struct CosmoHypersphere{T,N} <: AbstractCosmoGeometry where {T<:Number}
    center::Vector{T}
    radius::T
end

N-dimensional hypersphere given by its center and radius.

If different types are passed to the constructor, the types will be promoted without throwing an error.

CosmoHypersphere(N::Integer, radius::T)

Returns an N-dimensional hypersphere around the origin.

CosmoSphere{T} = CosmoHypersphere{T,3}

Alias for a 2D CosmoHypersphere.

CosmoSphere(radius::T)

Returns a sphere around the origin.

CosmoCircle{T} = CosmoHypersphere{T,2}

Alias for a 2D CosmoHypersphere.

CosmoCircle(radius::T)

Returns a circle around the origin.

struct CosmoCylinder{T} <: AbstractCosmoGeometry where {T<:Number}
    startpos::Vector{T}
    endpos::Vector{T}
    radius::T
end

Cylinder given by its end points startpos and endpos and radius.

If different types are passed to the constructor, the types will be promoted without throwing an error.

CosmoCylinder(c::CosmoStandingCylinder)

Create a cylinder from a standing cylinder.

struct CosmoStandingCylinder{T} <: AbstractCosmoGeometry where {T<:Number}
    center::Vector{T}
    height::T
    radius::T
end

Standing cylinder given by its center, height, and radius.

Standing means that the cylinder is oriented such that its axis is aligned with the z axis. If different types are passed to the constructor, the types will be promoted without throwing an error.

CosmoStandingCylinder(c::CosmoCylinder)

Create a standing cylinder from a cylinder.

The end positions of the cylinder have to have the same x and y coordinates.

struct CosmoEllipse{T,U} <: AbstractCosmoGeometry where {T<:Number,U<:Real}
    a::T
    q::U
end

Ellipse around the origin given by the semi-major axis a and the axis ratio q = b/a (where b is the semi-minor axis).

CosmoEllipse(a::T; q::U=1, constant_area=false) where {T<:Number,U<:Real}

Returns an ellipse around the origin with semi-major axis a and the axis ratio q.

If constant_area=true, the semi-major axis of the ellipse is picked such that its area is equal to that of a circle with radius a.

The axis ratio q has to be between 0 and 1.

struct CosmoEllipsoid{T,U} <: AbstractCosmoGeometry where {T<:Number,U<:Real}
    a::T
    q::U
    s::U
end

Ellipsoid around the origin given by the largest semi-major axis a, and the axis ratios q = b/a and s = c/a (where b and c are the semi-minor axes with b ≥ c).

CosmoEllipsoid(a::Number; q::Real=1, s::Real=1, constant_volume=false)

Returns an ellipsoid around the origin with semi-major axis a and the axis ratios q and s.

If constant_volume=true, the semi-major axis of the ellipsoid is picked such that its volume is equal to that of a sphere with radius a.

Both q and s have to be between 0 and 1, and q ≥ s has to hold.

CosmoEllipsoid(a::Number, b::Number, c::Number)

Returns an ellipsoid around the origin with semi axes a, b, and c, with a ≥ b ≥ c.

If c is nothing, a CosmoEllipse is created instead.

struct CosmoHomoeoid2D{T,U} <: AbstractCosmoGeometry where {T<:Number,U<:Real}
    a1::T
    a2::T
    q::U
end

Homoeoid in two dimensions around the origin given by the inner and outer semi-major axes a1 and a2, and the axis ratio q = b/a.

CosmoHomoeoid2D(a1::Number, a2::Number; q::Real=1, constant_area=false)
CosmoHomoeoid2D(a::Number, b::Number; a2::Number)

Returns a 2D homoeoid around the origin with semi-major axes a1 ≤ a2 and the axis ratio q.

If constant_area=true, the semi-major axes of the ellipse are picked such that the enclosed area is equal to that enclosed by two circles with radii a1 and a2.

The axis ratio q has to be between 0 and 1.

For the second method, a2 can also be smaller than a1. It is only important that a and b both either correspond to the inner or outer ellipse.

struct CosmoHomoeoid{T,U} <: AbstractCosmoGeometry where {T<:Number,U<:Real}
    a1::T
    a2::T
    q::U
    s::U
end

Homoeoid in three dimensions around the origin given by the inner and outer semi-major axes a1 and a2, and the axis ratios q = b/a and s = c/a.

CosmoHomoeoid(a1::Number, a2::Number; q::Real=1, s::Real=1, constant_volume=false)

Returns a 3D homoeoid around the origin with semi-major axes a1 ≤ a2 and the axis ratios q and s.

If constant_volume=true, the semi-major axes of the ellipsoids are picked such that the enclosed volume is equal to that enclosed by two spheres with radii a1 and a2.

The axis ratios q and s have to be between 0 and 1.

CosmoHomoeoid(a::Number, b::Number, c::Number; a2::Number)

Returns a 3D homoeoid around the origin with semi axes a ≥ b ≥ c and another enclosing similar ellipsoid specified by the semi-major axis a2.

The semi-major axis a2 can be smaller or larger than a.

If c is nothing, a CosmoHomoeoid2D is created instead.

colnormell(a::AbstractMatrix, q[, s])

Returns a new Vector with the columnwise elliptical norms of a.

In the 2D case: $\sqrt{x^2 + \frac{y^2}{q^2}}$. In the 3D case: $\sqrt{x^2 + \frac{y^2}{q^2} + \frac{z^2}{s^2}}$.

See also colnormell2.

colnormell2(a::AbstractMatrix, q[, s])

Returns a new Vector with the columnwise squared elliptical norms of a.

In the 2D case: $x^2 + \frac{y^2}{q^2}$. In the 3D case: $x^2 + \frac{y^2}{q^2} + \frac{z^2}{s^2}$.

See also colnormell.

triaxiality(q::Real, s::Real)
triaxiality(e::Union{CosmoEllipsoid,CosmoHomoeoid})

Triaxiality from the axis ratios q and s.

• $0 < T < 1/3$: oblate
• $1/3 < T < 2/3$: triaxial
• $2/3 < T < 1$: prolate

ellipticity(q::Real)
ellipticity(e::Union{CosmoEllipse,CosmoHomoeoid2D})

Ellipticity from axis ratio q: $ϵ = 1 - q$

eccentricity(q::Real)
eccentricity(e::Union{CosmoEllipse,CosmoHomoeoid2D})

Eccentricity from axis ratio q: $e = \sqrt{1 - q^2}$

struct CosmoUnionGeometry <: AbstractCosmoGeometry
    geos::Tuple
end

Union of multiple geometries.

This union geometry represents all of the volumes contained within the geometries.

This is not exported.

struct CosmoIntersectGeometry <: AbstractCosmoGeometry
    geos::Tuple
end

Intersect of multiple geometries.

This intersect geometry represents the volume that is shared among all of the geometries.

This is not exported.

struct CosmoDiffGeometry <: AbstractCosmoGeometry
    geo::AbstractCosmoGeometry
    geos::Tuple
end

Difference of a geometry with multiple geometries.

This difference geometry represents the volume of geo, but that is not contained in any of the geometries geos.

This is not exported.

Base.union(geos::AbstractCosmoGeometry...)

Create a union of geometries from the passed geometries.

Examples

using CosmoParticles
using CosmoParticles: mask_in

pos::Matrix # 3×n

g1 = CosmoSphere([1, 2, 3], 4)
g2 = CosmoSphere([3, 2, 3], 4)
geo = union(g1, g2)

mask_in(pos, geo) == mask_in(pos, g1) .| mask_in(pos, g2)

Base.intersect(geos::AbstractCosmoGeometry...)

Create an intersect of geometries from the passed geometries.

Examples

using CosmoParticles
using CosmoParticles: mask_in

pos::Matrix # 3×n

g1 = CosmoSphere([1, 2, 3], 4)
g2 = CosmoSphere([3, 2, 3], 4)
geo = intersect(g1, g2)

mask_in(pos, geo) == mask_in(pos, g1) .& mask_in(pos, g2)

Base.setdiff(geo::AbstractCosmoGeometry, geos::AbstractCosmoGeometry...)

Create a difference of geometries from the passed geometries.

Examples

using CosmoParticles
using CosmoParticles: mask_in

pos::Matrix # 3×n

g1 = CosmoSphere([1, 2, 3], 4)
g2 = CosmoSphere([3, 2, 3], 4)
geo = setdiff(g1, g2)

mask_in(pos, geo) == mask_in(pos, g1) .& .~mask_in(pos, g2)

struct Rotated{G,R} <: AbstractCosmoGeometry where {G<:AbstractCosmoGeometry,R<:AbstractMatrix}
    geo::G
    rotmat::R
end

Rotated geometry defined by a rotation matrix.

This can be created by rotate applied to a geometry.

This is not exported.

rotate(geo::AbstractCosmoGeometry, rotmat::AbstractMatrix{<:Real})

Returns a rotated geometry rotated by the rotation matrix.

Individual geometries may specify that this returns a different type than Rotated.

rotation_matrix(rot::Rotated)

Returns the rotation matrix that rotates the original geometry into the rotated state.

This is not exported.

rotation_matrix_inv(rot::Rotated)

Returns the rotation matrix that rotates the rotated geometry back to its original orientation.

Use this to rotate objects in the rotated frame of reference to the original frame of reference of the geometry.

This is not exported.

struct Translated{G,L} <: AbstractCosmoGeometry where {G<:AbstractCosmoGeometry,L<:AbstractVector}
    geo::G
    Δx::L
end

Translated geometry defined by a translation vector.

This can be created by translate applied to a geometry.

This is not exported.

translate(geo::AbstractCosmoGeometry, Δx::AbstractVector{<:Number})

Returns a new geometry translated by Δx.

Individual geometries may specify that this returns a different type than Translated.