UP | HOME

# Common

## Table of Contents

- 1. Summary
- 2. Angular Momentum
  - 2.1. Type
  - 2.2. Conversions
  - 2.3. Shell functions
  - 2.4. Arithmetic
  - 2.5. Printers
  - 2.6. TODO Tests
- 3. Bit string
  - 3.1. Type
  - 3.2. General implementation
  - 3.3. Printers
- 4. Charge
  - 4.1. Type
  - 4.2. Conversions
  - 4.3. Simple operations
  - 4.4. Printers
- 5. Command line
  - 5.1. Types
  - 5.2. Mutable attributes
  - 5.3. Query functions
  - 5.4. Specification
- 6. Constants
  - 6.1. Thresholds
  - 6.2. Mathematical constants
  - 6.3. Physical constants
- 7. Coordinate
  - 7.1. Type
  - 7.2. Creation
  - 7.3. Conversion
  - 7.4. Vector operations
  - 7.5. Printers
- 8. Non-negative float
  - 8.1. Type
  - 8.2. Conversions
- 9. Powers
  - 9.1. Type
  - 9.2. Conversions
  - 9.3. Operations
  - 9.4. Printers
- 10. QCaml
- 11. Range
  - 11.1. Type
  - 11.2. Conversion
  - 11.3. Printers
- 12. Spin
  - 12.1. Type
  - 12.2. Functions
  - 12.3. Printers
- 13. Util
  - 13.1. External C functions
    - 13.1.1. Erf
    - 13.1.2. Erfc
    - 13.1.3. Gamma
    - 13.1.4. Popcnt
    - 13.1.5. Trailz
    - 13.1.6. Leadz
    - 13.1.7. Test
  - 13.2. General functions
  - 13.3. Functions related to the Boys function
  - 13.4. List functions
  - 13.5. Array functions
  - 13.6. Seq functions
  - 13.7. Printers
- 14. Zkey
  - 14.1. Types
  - 14.2. Conversions
  - 14.3. Functions for hash tables
  - 14.4. Printers
- 15. Zmap
  - 15.1. Type

## 1 Summary

## 2 Angular Momentum

Azimuthal quantum number, repsesented as \( s,p,d,\dots \) .

### 2.1 Type

`Angular_momentum.t`

    type t =
      | S | P | D | F | G | H | I | J | K | L | M | N | O
      | Int of int

    exception Angular_momentum_error of string

    type kind =
        Singlet of t
      | Doublet of (t * t)
      | Triplet of (t * t * t)
      | Quartet of (t * t * t * t)

An exception is raised when the `Angular_momentum.t` element can't be created.

The `kind` is used to build shells, shell doublets, triplets or quartets, use in the two-electron operators.

### 2.2 Conversions

    val of_char : char -> t
    val to_char : t -> char

    val to_int : t -> int
    val of_int : int -> t

    val to_string : t -> string

`of_char` | Returns an `Angular_momentum.t` when a shell is given as a character (case insensitive)
`to_char` | Converts the angular momentum into a char
`of_int` | Returns a shell given an \(l\) value.
`to_int` | Returns the \(l_{max}\) value of the shell
`to_string` | Converts the angular momentum into a string

Example:

    Angular_momentum.of_char 'p';;
    - : Angular_momentum.t = P

    Angular_momentum.(to_char P);;
    - : char = 'P'

    Angular_momentum.of_int 2;;
    - : Angular_momentum.t = D

    Angular_momentum.(to_int D);;
    - : int = 2

    Angular_momentum.(to_string D);;
    - : string = "D"

### 2.3 Shell functions

    val n_functions : t -> int
    val zkey_array  : kind -> Zkey.t array

`n_functions` | Returns the number of cartesian functions in a shell.
`zkey_array` | Array of `Zkey.t`, where each element is a a key associated with the the powers of \(x,y,z\).

Example:

    Angular_momentum.(n_functions D) ;;
    - : int = 6

    Angular_momentum.( zkey_array (Doublet (P,S)) );;
    - : Zkey.t array =
    [|< 01125899906842624 | 1, 0, 0, 0, 0, 0 >;
      < 01099511627776 | 0, 1, 0, 0, 0, 0 >;
      < 01073741824 | 0, 0, 1, 0, 0, 0 >|]

### 2.4 Arithmetic

    val ( + ) : t -> t -> t
    val ( - ) : t -> t -> t

Example:

    Angular_momentum.(D + P);;
    - : Angular_momentum.t = F

    Angular_momentum.(F - P);;
    - : Angular_momentum.t = D

### 2.5 Printers

Printers can print as a string (default) or as an integer.

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

### 2.6 TODO Tests

## 3 Bit string

We define here a data type to handle bit strings efficiently. When the bit string contains less than 64 bits, it is stored internally in a 63-bit integer and uses bitwise instructions. When more than 63 bits are required, the `zarith` library is used to consider the bit string as a multi-precision integer.

### 3.1 Type

`Bitstring.t`

    type t

### 3.2 General implementation

    val of_int : int -> t
    val of_z   : Z.t -> t
    val zero   : int -> t

    val is_zero : t -> bool
    val numbits : t -> int
    val testbit : t -> int -> bool

    val neg            : t -> t
    val shift_left     : t -> int -> t
    val shift_right    : t -> int -> t
    val shift_left_one : int -> int -> t

    val logor  : t -> t -> t
    val logxor : t -> t -> t
    val logand : t -> t -> t
    val lognot : t -> t

    val plus_one  : t -> t
    val minus_one : t -> t

    val hamdist        : t -> t -> int
    val trailing_zeros : t -> int
    val popcount       : t -> int

    val to_list      : ?accu:(int list) -> t -> int list
    val permutations : int -> int -> t list

`of_int` | Creates a bit string from an `int`
`of_z` | Creates a bit string from an `Z.t` multi-precision integer
`zero` | `zero n` creates a zero bit string with `n` bits
`is_zero` | True if all the bits of the bit string are zero.
`numbits` | Returns the number of bits used to represent the bit string
`testbit` | `testbit t n` is true if the `n`-th bit of the bit string `t` is set to `1`
`neg` | Returns the negative of the integer interpretation of the bit string
`shift_left` | `shift_left t n` returns a new bit strings with all the bits shifted `n` positions to the left
`shift_right` | `shift_right t n` returns a new bit strings with all the bits shifted `n` positions to the right
`shift_left_one` | `shift_left_one size n` returns a new bit strings with the `n`-th bit set to one. It is equivalent as shifting `1` by `n` bits to the left, `size` is the total number of bits of the bit string
`logor` | Bitwise logical or
`logxor` | Bitwise logical exclusive or
`logand` | Bitwise logical and
`lognot` | Bitwise logical negation
`plus_one` | Takes the integer representation of the bit string and adds one
`minus_one` | Takes the integer representation of the bit string and removes one
`hamdist` | Returns the Hamming distance, i.e. the number of bits differing between two bit strings
`trailing_zeros` | Returns the number of trailing zeros in the bit string
`permutations` | `permutations m n` generates the list of all possible `n`-bit strings with `m` bits set to `1`. Algorithm adapted from Bit twiddling hacks
`popcount` | Returns the number of bits set to one in the bit string
`to_list` | Converts a bit string into a list of integers indicating the positions where the bits are set to `1`. The first value for the position is not `0` but `1`

Example:

    Bitstring.of_int 15;;
    - : Bitstring.t =
    ++++------------------------------------------------------------

Example:

    Bitstring.(shift_left (of_int 15) 2);;
    - : Bitstring.t =
    --++++----------------------------------------------------------

    Bitstring.(shift_right (of_int 15) 2);;
    - : Bitstring.t =
    ++--------------------------------------------------------------

    Bitstring.shift_left_one 32 4;;
    - : Bitstring.t =
    ----+-----------------------------------------------------------

    Bitstring.(testbit (of_int 15) 3);;
    - : bool = true

    Bitstring.(testbit (of_int 15) 4);;
    - : bool = false

Example:

    Bitstring.(logor (of_int 15) (of_int 73));;
    - : Bitstring.t =
    ++++--+---------------------------------------------------------

    Bitstring.(logand (of_int 15) (of_int 10));;
    - : Bitstring.t =
    -+-+------------------------------------------------------------

    Bitstring.(logxor (of_int 15) (of_int 73));;
    - : Bitstring.t =
    -++---+---------------------------------------------------------

Example:

    Bitstring.(plus_one (of_int 15));;
    - : Bitstring.t =
    ----+-----------------------------------------------------------

    Bitstring.(minus_one (of_int 15));;
    - : Bitstring.t =
    -+++------------------------------------------------------------

Example:

    Bitstring.(trailing_zeros (of_int 12));;
    - : int = 2

    Bitstring.(hamdist (of_int 15) (of_int 73));;
    - : int = 3

    Bitstring.(popcount (of_int 15));;
    - : int = 4

Example:

    Bitstring.(to_list (of_int 45));;
    - : int list = [1; 3; 4; 6]

Example:

       Bitstring.permutations 2 4;;
    - : Bitstring.t list =
    [++--------------------------------------------------------------;
     +-+-------------------------------------------------------------;
     -++-------------------------------------------------------------;
     +--+------------------------------------------------------------;
     -+-+------------------------------------------------------------;
     --++------------------------------------------------------------]

### 3.3 Printers

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

## 4 Charge

### 4.1 Type

`Charge.t`

    type t

This type should be used for all charges in the program (electrons, nuclei,…).

### 4.2 Conversions

    val of_float : float -> t
    val to_float : t -> float

    val of_int   : int -> t
    val to_int   : t -> int

    val of_string: string -> t
    val to_string: t -> string

### 4.3 Simple operations

    val ( + ) : t -> t -> t
    val ( - ) : t -> t -> t
    val ( * ) : t -> float -> t
    val ( / ) : t -> float -> t
    val is_null : t -> bool

### 4.4 Printers

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

## 5 Command line

This module is a wrapper around the `Getopt` library and helps to define command-line arguments.

Here is an example of how to use this module. First, define the specification:

    let open Command_line in
    begin
      set_header_doc (Sys.argv.(0) ^ " - One-line description");
      set_description_doc "Long description of the command.";
      set_specs
        [ { short='c'; long="check"; opt=Optional;
            doc="Checks the input data";
            arg=Without_arg; };

          { short='b' ; long="basis" ; opt=Mandatory;
            arg=With_arg "<string>";
            doc="Name of the file containing the basis set"; } ;

          { short='m' ; long="multiplicity" ; opt=Optional;
            arg=With_arg "<int>";
            doc="Spin multiplicity (2S+1). Default is singlet"; } ;
        ]
    end;

Then, define what to do with the arguments:

    let c =
      Command_line.get_bool "check"
    in

    let basis =
      match Command_line.get "basis" with
      | Some x -> x
      | None -> assert false
    in

    let multiplicity =
      match Command_line.get "multiplicity" with
      | None -> 1
      | Some n -> int_of_string n
    in

### 5.1 Types

    type short_opt     = char
    type long_opt      = string
    type optional      = Mandatory | Optional
    type documentation = string
    type argument      = | With_arg of string
                         | Without_arg
                         | With_opt_arg of string

    type description = {
      short: short_opt ;
      long : long_opt  ;
      opt  : optional  ;
      doc  : documentation ;
      arg  : argument ;
    }

- Short option: in the command line, a dash with a single character (ex: `ls -l`)
- Long option: in the command line, two dashes with a word (ex: `ls --directory`)
- Command-line options can be `Mandatory` or `Optional`
- Documentation of the option is used in the help function
- Some options require an argument (`ls --ignore="*.ml"` ), some don't (`ls -l`) and for some arguments the argument is optional (`git --log[=<n>]`)

### 5.2 Mutable attributes

All the options are stored in the hash table `dict` where the key is the long option and the value is a value of type `description`.

    val set_header_doc : string -> unit
    val set_description_doc : string -> unit
    val set_footer_doc : string -> unit

Functions to set the header, footer and main description of the documentation provided by the `help` function:

    val anonymous : long_opt -> optional -> documentation -> description

Function to create an anonymous argument.

### 5.3 Query functions

    val get       : long_opt -> string option
    val get_bool  : long_opt -> bool
    val anon_args : unit -> string list

`get` | Returns the argument associated with a long option
`get_bool` | True if the `Optional` argument is present in the command-line
`anon_args` | Returns the list of anonymous arguments

### 5.4 Specification

    val set_specs : description list -> unit

Sets the specifications of the current program from a list of `descrption` variables.

## 6 Constants

All constants used in the program.

### 6.1 Thresholds

    val epsilon          : float
    val integrals_cutoff : float

`epsilon` | Value below which a float is considered null. Default is ε = 2.10-15
`integrals_cutoff` | Cutoff value for integrals. Default is ε

### 6.2 Mathematical constants

    val pi             : float
    val two_pi         : float
    val sq_pi          : float
    val sq_pi_over_two : float
    val pi_inv         : float
    val two_over_sq_pi : float

`pi` | \(\pi = 3.141~592~653~589~793~12\)
`two_pi` | \(2 \pi\)
`sq_pi` | \(\sqrt{\pi}\)
`sq_pi_over_two` | \(\sqrt{\pi} / 2\)
`pi_inv` | \(1 / \pi\)
`two_over_sq_pi` | \(2 / \sqrt{\pi}\)

### 6.3 Physical constants

    val a0       : float
    val a0_inv   : float
    val ha_to_ev : float
    val ev_to_ha : float

`a0` | Bohr's radius : \(a_0 = 0.529~177~210~67(23)\) angstrom
`a0_inv` | \(1 / a_0\)
`ha_to_ev` | Hartree to eV conversion factor : \(27.211~386~02(17)\)
`ev_to_ha` | eV to Hartree conversion factor : 1 / `ha_to_ev`

## 7 Coordinate

Coordinates in 3D space.

All operations on points are done in atomic units. Therefore, all coordinates are given in bohr and manipulated with this module.

### 7.1 Type

`Coordinate.t`

    type bohr
    type angstrom

    type xyz = {
      x : float ;
      y : float ;
      z : float ;
    }

    type 'a point = xyz

    type t = bohr point

    type axis = X | Y | Z

### 7.2 Creation

    val make          : 'a point -> t
    val make_angstrom : 'a point -> angstrom point
    val zero          : bohr point

`make` | Creates a point in atomic units
`make_angstrom` | Creates a point in angstrom
`zero` | \((0., 0., 0.)\)

### 7.3 Conversion

    val bohr_to_angstrom : bohr point -> angstrom point
    val angstrom_to_bohr : angstrom point -> bohr point

`bohr_to_angstrom` | Converts a point in bohr to angstrom
`angstrom_to_bohr` | Converts a point in angstrom to bohr

### 7.4 Vector operations

    val neg    : t -> t
    val get    : axis -> bohr point -> float
    val dot    : t -> t -> float
    val norm   : t -> float
    val ( |. ) : float -> t -> t
    val ( |+ ) : t -> t -> t
    val ( |- ) : t -> t -> t

`neg` | Negative of a point
`get` | Extracts the projection of the coordinate on an axis
`dot` | Dot product
`norm` | \(\ell{^2}\) norm of the vector
$| .$ | Scales the vector by a constant
\(\vert +\) | Adds two vectors
\(\vert -\) | Subtracts two vectors

Example:

    Coordinate.neg { x=1. ; y=2. ; z=3. } ;;
    - : Coordinate.t =  -1.0000  -2.0000  -3.0000

    Coordinate.(get Y { x=1. ; y=2. ; z=3. }) ;;
    - : float = 2.

    Coordinate.(
      2. |. { x=1. ; y=2. ; z=3. }
    ) ;;
    - : Coordinate.t =   2.0000   4.0000   6.0000

    Coordinate.(
      { x=1. ; y=2. ; z=3. } |+ { x=2. ; y=3. ; z=1. }
    );;
    - : Coordinate.t =   3.0000   5.0000   4.0000

    Coordinate.(
      { x=1. ; y=2. ; z=3. } |- { x=2. ; y=3. ; z=1. }
    );;
    - : Coordinate.t =  -1.0000  -1.0000   2.0000

### 7.5 Printers

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

Coordinates can be printed in bohr or angstrom.

## 8 Non-negative float

### 8.1 Type

<

    type t = private float

### 8.2 Conversions

    val of_float        : float -> t
    val unsafe_of_float : float -> t
    val to_float        : t -> float

    val of_string       : string -> t
    val to_string       : t -> string

The `of_float` function checks that the float is non-negative. The unsafe variant doesn't do this check.

## 9 Powers

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

### 9.1 Type

`Powers.t`

    type t = private {
      x   : int ;
      y   : int ;
      z   : int ;
      tot : int ;
    }

`tot` always contains `x+y+z`.

### 9.2 Conversions

    val of_int_tuple : int * int * int -> t
    val to_int_tuple : t -> int * int * int

Example:

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

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

### 9.3 Operations

    val get  : Coordinate.axis -> t -> int
    val incr : Coordinate.axis -> t -> t
    val decr : Coordinate.axis -> t -> t

`get` | Returns the value of the power for \(x\), \(y\) or \(z\)
`incr` | Returns a new `Powers.t` with the power on the given axis incremented
`decr` | Returns a new `Powers.t` with the power on the given axis decremented. As opposed to `of_int_tuple`, the values may become negative

Example:

    Powers.get Coordinate.Y (Powers.of_int_tuple (2,3,1));;
    - : int = 3

    Powers.incr Coordinate.Y (Powers.of_int_tuple (2,3,1));;
    - : Powers.t = x^2 + y^4 + z^1

    Powers.decr Coordinate.Y (Powers.of_int_tuple (2,3,1));;
    - : Powers.t = x^2 + y^2 + z^1

### 9.4 Printers

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

## 10 QCaml

QCaml-specific parameters

    val root : string
    val name : string
    val num_domains : int

`root` | Path to the QCaml source directory
`name` | `"QCaml"`
`num_domains` | Number of threads in parallel computations

## 11 Range

A range is a sorted list of integers in an interval.

- `"[a-b]"` : range between a and b (included)
- `"[a]"` : the list with only one integer a
- `"a"` : equivalent to "[a]"
- `"[36-53,72-107,126-131]"` represents the list of integers [ 37 ; 37 ; 38 ; … ; 52 ; 53 ; 72 ; 73 ; … ; 106 ; 107 ; 126 ; 127 ; … ; 130 ; 131 ].

### 11.1 Type

`Range.t`

    type t

### 11.2 Conversion

    val of_string   : string -> t
    val to_string   : t -> string
    val to_int_list : t -> int list

### 11.3 Printers

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

## 12 Spin

Electron spin

### 12.1 Type

`Spin.t`

    type t = Alfa | Beta

Note : `Alfa` if written with an 'f' instead of 'ph' because it has the same number of letters as `Beta`, so the alignment of the code is nicer.

### 12.2 Functions

    val other : t -> t

Returns the opposite spin

### 12.3 Printers

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

## 13 Util

Utility functions.

### 13.1 External C functions

`erf_float` | Error function `erf` from `libm`
`erfc_float` | Complementary error function `erfc` from `libm`
`gamma_float` | Gamma function `gamma` from `libm`
`popcnt` | `popcnt` instruction
`trailz` | `ctz` instruction
`leadz` | `bsf` instruction

#### 13.1.1 Erf

    external erf_float : float -> float
      = "erf_float_bytecode" "erf_float" [@@unboxed] [@@noalloc]

#### 13.1.2 Erfc

    external erfc_float : float -> float
      = "erfc_float_bytecode" "erfc_float" [@@unboxed] [@@noalloc]

#### 13.1.3 Gamma

    external gamma_float : float -> float
      = "gamma_float_bytecode" "gamma_float" [@@unboxed] [@@noalloc]

#### 13.1.4 Popcnt

    val popcnt : int64 -> int

#### 13.1.5 Trailz

    val trailz : int64 -> int

#### 13.1.6 Leadz

    val leadz : int64 -> int

#### 13.1.7 Test

### 13.2 General functions

    val fact : int -> float
    (* @raise Invalid_argument for negative arguments or arguments >100. *)
    val binom       : int -> int -> int
    val binom_float : int -> int -> float

    val chop              : float -> (unit -> float) -> float
    val pow               : float -> int -> float
    val float_of_int_fast : int -> float

    val of_some : 'a option -> 'a

    exception Not_implemented of string
    val not_implemented : string -> 'a
    (* @raise Not_implemented. *)

`fact` | Factorial function.
`binom` | Binomial coefficient. `binom n k` = \(C_n^k\)
`binom_float` | float variant of `binom`
`pow` | Fast implementation of the power function for small integer powers
`chop` | In `chop a f`, evaluate `f` only if the absolute value of `a` is larger than `Constants.epsilon`, and return `a *. f ()`.
`float_of_int_fast` | Faster implementation of floatofint for small positive ints
`not_implemented` | Fails if some functionality is not implemented
`of_some` | Extracts the value of an option

### 13.3 Functions related to the Boys function

    val incomplete_gamma : alpha:float -> float -> float
    (* @raise Failure when the calculation doesn't converge. *)

The lower Incomplete Gamma function is implemented : \[ \gamma(\alpha,x) = \int_0^x e^{-t} t^{\alpha-1} dt \]

p: \(\frac{1}{\Gamma(\alpha)} \int_0^x e^{-t} t^{\alpha-1} dt\)

q: \(\frac{1}{\Gamma(\alpha)} \int_x^\infty e^{-t} t^{\alpha-1} dt\)

Reference : Haruhiko Okumura: C-gengo niyoru saishin algorithm jiten (New Algorithm handbook in C language) (Gijyutsu hyouron sha, Tokyo, 1991) p.227 [in Japanese]

    val boys_function : maxm:int -> float -> float array

The Generalized Boys function is implemented, `maxm` is the maximum total angular momentum.

\[ F_m(x) = \frac{\gamma(m+1/2,x)}{2x^{m+1/2}} \] where \(\gamma\) is the incomplete gamma function.

- \(F_0(0.) = 1\)
- \(F_0(t) = \frac{\sqrt{\pi}}{2\sqrt{t}} \text{erf} ( \sqrt{t} )\)
- \(F_m(0.) = \frac{1}{2m+1}\)
- \(F_m(t) = \frac{\gamma{m+1/2,t}}{2t^{m+1/2}}\)
- \(F_m(t) = \frac{ 2t\, F_{m+1}(t) + e^{-t} }{2m+1}\)

### 13.4 List functions

    val list_some  : 'a option list -> 'a list
    val list_range : int -> int -> int list
    val list_pack  : int -> 'a list -> 'a list list

`list_some` | Filters out all `None` elements of the list, and returns the elements without the `Some`
`list_range` | Creates a list of consecutive integers
`list_pack` | `list_pack n l` Creates a list of `n`-elements lists

### 13.5 Array functions

    val array_range   : int -> int -> int array
    val array_sum     : float array -> float
    val array_product : float array -> float

`array_range` | Creates an array of consecutive integers
`array_sum` | Returns the sum of all the elements of the array
`array_product` | Returns the product of all the elements of the array

### 13.6 Seq functions

    val seq_range   : int -> int -> int Seq.t
    val seq_to_list : 'a Seq.t -> 'a list
    val seq_fold    : ('a -> 'b -> 'a) -> 'a -> 'b Seq.t -> 'a

`seq_range` | Creates a sequence returning consecutive integers
`seq_to_list` | Read a sequence and put items in a list
`seq_fold` | Apply a fold to the elements of the sequence

### 13.7 Printers

    val pp_float_array_size   : Format.formatter -> float array -> unit
    val pp_float_array        : Format.formatter -> float array -> unit
    val pp_float_2darray_size : Format.formatter -> float array array -> unit
    val pp_float_2darray      : Format.formatter -> float array array -> unit
    val pp_bitstring          : int -> Format.formatter -> Z.t -> unit

`pp_float_array` | Printer for float arrays
`pp_float_array_size` | Printer for float arrays with size
`pp_float_2darray` | Printer for matrices
`pp_float_2darray_size` | Printer for matrices with size
`pp_bitstring` | Printer for bit strings (used by `Bitstring` module)

Example:

    pp_float_array_size:
    [ 6:   1.000000   1.732051   1.732051   1.000000   1.732051   1.000000 ]

    pp_float_array:
    [    1.000000   1.732051   1.732051   1.000000   1.732051   1.000000 ]

    pp_float_2darray_size
    [
      2:[ 6:  1.000000   1.732051   1.732051   1.000000   1.732051   1.000000 ]
        [ 4:  1.000000   2.000000   3.000000   4.000000 ] ]

    pp_float_2darray:
    [ [   1.000000   1.732051   1.732051   1.000000   1.732051   1.000000 ]
      [   1.000000   2.000000   3.000000   4.000000 ] ]

    pp_bitstring 14:
    +++++------+--

## 14 Zkey

Encodes the powers of x, y, z in a compact form, suitable for being used as keys in a hash table.

Internally, the `Zkey.t` is made of two integers, `left` and `right`. The small integers x, y and z are stored compactly in this 126-bits space:

Example:

                                    Left                                                                Right
     3 [--------------------------------------------------------------]       [------------------|---------------|---------------|---------------]
                                                                                                         x               y               z

     6 [--------------------------------------------------------------]       [---|----------|----------|----------|----------|----------|---------]
                                                                                       x1         y1         z1         x2         y2         z2

     9 [---------------------------------|----------|----------|---------]    [---|----------|----------|----------|----------|----------|---------]
                                              x1         y1         z1                 x2         y2         z2         x3         y3         z3

    12 [---|----------|----------|----------|----------|----------|---------] [---|----------|----------|----------|----------|----------|---------]
                x1         y1         z1         x2         y2         z2              x3         y3         z3         x4         y4         z4

The values of x,y,z should be positive and should not exceed 32767 for `kind=3`. For all other kinds kinds the values should not exceed 1023.

### 14.1 Types

`Zkey.t`

    type t

    type kind =
      | Three  of  Powers.t
      | Four   of (int * int * int * int)
      | Six    of (Powers.t * Powers.t)
      | Nine   of (Powers.t * Powers.t * Powers.t)
      | Twelve of (Powers.t * Powers.t * Powers.t * Powers.t)

### 14.2 Conversions

    val of_powers_three  : Powers.t -> t
    val of_powers_six    : Powers.t -> Powers.t -> t
    val of_powers_nine   : Powers.t -> Powers.t -> Powers.t -> t
    val of_powers_twelve : Powers.t -> Powers.t -> Powers.t -> Powers.t -> t
    val of_powers        : kind -> t
    val of_int_array     : int array -> t
    val of_int_four      : int -> int -> int -> int -> t
    val to_int_array     : t -> int array
    val to_powers        : t -> kind
    val to_string        : t -> string

`of_powers_three` | Create from a `Powers.t`
`of_powers_six` | Create from two `Powers.t`
`of_powers_nine` | Create from three `Powers.t`
`of_powers_twelve` | Create from four `Powers.t`
`of_powers` | Create using the `kind` type
`of_int_array` | Convert from an `int` array
`of_int_four` | Create from four `ints`
`to_int_array` | Convert to an `int` array
`to_powers` | Convert to an `Powers.t` array
`to_string` | Pretty printing

### 14.3 Functions for hash tables

    val hash    : t -> int
    val equal   : t -> t -> bool
    val compare : t -> t -> int

`hash` | Associates a nonnegative integer to any Zkey
`equal` | The equal function. True if two Zkeys are equal
`compare` | Comparison function, used for sorting

### 14.4 Printers

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

## 15 Zmap

A hash table where the keys are `Zkey`

### 15.1 Type

`Zmap.t`

    include module type of Hashtbl.Make(Zkey)

Author: Anthony Scemama

Created: 2023-06-16 Fri 18:16

Validate