Common
Table of Contents
1 Summary
2 Angular Momentum
Azimuthal quantum number, repsesented as \( s,p,d,\dots \) .
2.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.
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
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
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
MandatoryorOptional - 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
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.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
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
root |
Path to the QCaml source directory |
name |
"QCaml" |
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
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
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 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 |
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
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
include module type of Hashtbl.Make(Zkey)