Source

papl / src / PaplVector.mli

Full commit
(*
  Copyright (c) 2012 Anders Lau Olsen.
  See LICENSE file for terms and conditions.
*)
(** Vectors
*)

type rng_t = PaplRandom.rng_t
type 'a pair_t = 'a * 'a

(** {2 Module types} *)

(** Basic vector operations *)
module type BASE = sig
  type t
(** Vectors. *)

  type box_t = t * t
(** Vector boxes. *)

(** {2 Interpolation} *)

  val interpolate : t PaplInterpolate.t
(**
   Linear interpolation of vectors.
*)

(** {2 Vector space operations} *)

  val ( *: ) : float -> t -> t
(** Scalar multiplication. *)

  val (/:) : t -> float -> t
(** Division of a vector by a scalar. *)

  val (+:) : t -> t -> t
(** Vector addition. *)

  val (-:) : t -> t -> t
(** Vector subtraction. *)

  val neg : t -> t
(** Unary negation. *)

(** {2 Miscellaneous} *)

  val map : (float -> float) -> t -> t
(** Map a function onto the elements of a vector. *)

  val map2 : (float -> float -> float) -> t -> t -> t
(** Zip the pairs of coordinates of two vectors by a scalar function. *)

  val sum : t -> float
(** The sum of the elements. *)

  val abs : t -> t
(** The absolute values. *)

  val sqrt : t -> t
(** The square roots.

    All elements must be non-negative.
*)

  val sign : t -> t
(** The signs of the values.

    Let [b = sign a]: for all [i]: if [a.(i) < 0] then [b.(i) = -1]; otherwise
    [b.(i) = 1].
*)

  val min : t -> t -> t
(** The smallest value for each pair of coordinates.

    If [c = min a b] then [c.(i) = Pervasives.min a.(i) b.(i)] for all [i].
*)

  val max : t -> t -> t
(** The largest value for each pair of coordinates.

    If [c = min a b] then [c.(i) = Pervasives.max a.(i) b.(i)] for all [i].
*)

  val scale : t -> t -> t
(** Pairwise product of two vectors.

    If [c = scale a b] then [ci = a.(i) * b.(i)] for all [i].
*)

  val divide : float -> t -> t
(** Division of a scalar by a vector.

    If [b = divide s a] then [b.(i) = s /. a.(i)] for all [i].

    The elements of [a] must be non-zero.
*)

  val unit : t -> t
(** Scale a vector to unit length.

    The length is measured by [dist2]. If the length of the vector is zero (or
    very near zero), an exception is thrown.
*)

  val box_center : box_t -> t
(** The center of a box.

    The center of the box [(a, b)] is [0.5 *: (a +: b)].
*)

  val box_diagonal : box_t -> t
(** The diagonal of a box.

    The diagonal of the box [(a, b)] is [b -: a].
*)
end

(** Inner products *)
module type DOT = sig
  type t
(** Vectors. *)

(** {2 Inner products} *)

  type dot_t = t -> t -> float
(** The type of an inner product function. *)

  val dot : dot_t
(** Inner product of two vectors. *)

  val dot_weighted : t -> dot_t
(** Weighted inner product of two vectors. *)

(** {2 Projections} *)

  val proj_by : dot_t -> t -> t -> t
(** Projection of a vector onto a vector

    [proj dot a b] is the projection of [a] onto [b] (i.e. the resulting vector
    is parallel to [b]), where [dot] is the inner product of the space.

    The vector [b] must be non-zero.
*)

  val proj : t -> t -> t
(** Projection of a vector onto a vector.

    [proj a b] is equivalent to [proj_by dot a b].
*)

  val proj_unit_by : dot_t -> t -> t -> t
(** Projection of a vector onto a unit-vector.

    [proj_unit dot a b] projects [a] onto [b]. Unlike [proj_by dot a b],
    the function assumes that the norm of [b] is [1.0].
*)

  val proj_unit : t -> t -> t
(** Projection of a vector onto a unit-vector.

    [proj_unit a b] is equivalent to [proj_unit_by dot a b].
*)
end

(** Sampling of vectors *)
module type SAMPLER = sig
  type t
(** Vectors. *)

  type box_t
(** Vector boxes. *)

  val uniform : ?rng:rng_t -> box_t -> t PaplSampler.t
(** Uniform sampling of a configuration space box. *)

  val get_uniform : ?rng:rng_t -> box_t -> t
(** A single configuration sampled uniformly at random from a box. *)
end

(** Union of all vector operations *)
module type ALL = sig
  include BASE

  include DOT with type t := t
  include PaplVectorMetric.S with type t := t and type weight_t = t

  include SAMPLER with type t := t and type box_t := box_t
end

(** {2 Vectors in 2D, 3D, and 4D} *)

(** 2-tuples as vectors. *)
module V2D : sig
  include ALL with type t = float * float

  type triangle_t = t * t * t
  (** The type of a triangle. *)
end

(** 3-tuples as vectors. *)
module V3D : sig
  include ALL with type t = float * float * float

  type triangle_t = t * t * t
  (** The type of a triangle. *)

  val cross : t -> t -> t
  (** The cross product of a pair of vectors. *)

  val uniform_unit : ?rng:rng_t -> unit -> t PaplSampler.t
  (** Unit vectors sampled uniformly at random from the surface of the unit
      sphere.
  *)

  val get_uniform_unit : ?rng:rng_t -> unit -> t
  (** A single unit vector sampled uniformly at random from the surface of the
      unit sphere. *)
end

(** 4-tuples as vectors. *)
module V4D : ALL with type t = float * float * float * float

(** {2 Array vectors} *)

(** Arrays as vectors. *)
module Array : ALL with type t = float BatArray.t