QCaml/common/lib/powers.mli

(** Powers *)

(* Contains powers of $x$, $y$ and $z$ describing the polynomials in
 * atomic basis sets.
 *)

(** Type *)

type t = private {
  x   : int ;
  y   : int ;
  z   : int ;
  tot : int ; (* ~tot~ always contains ~x+y+z~. *)
}

(** Conversions *)

val of_int_tuple : int * int * int -> t
(** Powers.of_int_tuple (2,3,1);;
 *  - : Powers.t = x^2 + y^3 + z^1
 *)

val to_int_tuple : t -> int * int * int

(** Powers.(to_int_tuple (of_int_tuple (2,3,1)));;
 *  - : int * int * int = (2, 3, 1)
 *)


(** Operations *)

val get  : Coordinate.axis -> t -> int
(** Returns the value of the power for $x$, $y$ or $z$.
 *
 *  Powers.get Coordinate.Y (Powers.of_int_tuple (2,3,1));;
 *  - : int = 3
 *
 *)

val incr : Coordinate.axis -> t -> t
(** Returns a new ~Powers.t~ with the power on the given axis incremented.
 *
 * Powers.incr Coordinate.Y (Powers.of_int_tuple (2,3,1));;
 * - : Powers.t = x^2 + y^4 + z^1
 *)

val decr : Coordinate.axis -> t -> t
(** Returns a new ~Powers.t~ with the power on the given axis decremented.
 *  As opposed to ~of_int_tuple~, the values may become negative.
 *
 * Powers.decr Coordinate.Y (Powers.of_int_tuple (2,3,1));;
 * - : Powers.t = x^2 + y^2 + z^1
 *)


(** Printers *)

val pp : Format.formatter -> t -> unit