Common

Table of Contents

"Utility functions used by all the other directories."

1 Angular Momentum

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

1.1 Type

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.

1.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
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"

1.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\).
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 >|]

1.4 Arithmetic

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

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

1.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

1.6 TODO Tests

2 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.

2.1 Type

type t

2.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
Bitstring.of_int 15;;
- : Bitstring.t =
++++------------------------------------------------------------
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
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 =
-++---+---------------------------------------------------------
Bitstring.(plus_one (of_int 15));;
- : Bitstring.t =
----+-----------------------------------------------------------
   
Bitstring.(minus_one (of_int 15));;
- : Bitstring.t =
-+++------------------------------------------------------------
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
Bitstring.(to_list (of_int 45));;
- : int list = [1; 3; 4; 6]
   Bitstring.permutations 2 4;;
- : Bitstring.t list =
[++--------------------------------------------------------------;
 +-+-------------------------------------------------------------;
 -++-------------------------------------------------------------;
 +--+------------------------------------------------------------;
 -+-+------------------------------------------------------------;
 --++------------------------------------------------------------]

2.3 Printers

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

3 Charge

3.1 Type

type t

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

3.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 

3.3 Simple operations

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

3.4 Printers

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

4 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

4.1 Type

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>])

4.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.

4.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

4.4 Specification

val set_specs : description list -> unit

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

5 Constants

All constants used in the program.

5.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 ε

5.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}\)

5.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

6 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.

6.1 Type

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

6.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.)\)

6.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

6.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
¦+ Adds two vectors
¦- Subtracts two vectors
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

6.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.

7 Non-negative float

7.1 Type

type t = private float

7.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.

8 Powers

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

8.1 Type

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

tot always contains x+y+z.

8.2 Conversions

val of_int_tuple : int * int * int -> t
val to_int_tuple : t -> int * int * int 
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)

8.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
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

8.4 Printers

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

9 QCaml

QCaml-specific parameters

val root : string
val name : string
root Path to the QCaml source directory
name "QCaml"

10 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 ].

10.1 Type

type t

10.2 Conversion

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

10.3 Printers

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

11 Spin

Electron spin

11.1 Type

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.

11.2 Functions

val other : t -> t

Returns the opposite spin

11.3 Printers

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

12 Util

Utility functions.

12.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

12.1.1 Erf

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

12.1.2 Erfc

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

12.1.3 Gamma

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

12.1.4 Popcnt

val popcnt : int64 -> int

12.1.5 Trailz

val trailz : int64 -> int

12.1.6 Leadz

val leadz : int64 -> int

12.1.7 Test

12.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

12.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}\)

12.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

12.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

12.6 Stream functions

val stream_range   : int -> int -> int Stream.t
val stream_to_list : 'a Stream.t -> 'a list
val stream_fold    : ('a -> 'b -> 'a) -> 'a -> 'b Stream.t -> 'a
stream_range Creates a stream returning consecutive integers
stream_to_list Read a stream and put items in a list
stream_fold Apply a fold to the elements of the stream

12.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)
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:
+++++------+--

13 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:

                                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.

13.1 Types

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)

13.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

13.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

13.4 Printers

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

14 Zmap

A hash table where the keys are Zkey

14.1 Type

include module type of Hashtbl.Make(Zkey)

Author: Anthony Scemama

Created: 2021-01-01 Fri 17:05

Validate