From f95d9740b667b91456ef4eff9da538b33592713c Mon Sep 17 00:00:00 2001
From: Anthony Scemama <scemama@irsamc.ups-tlse.fr>
Date: Sat, 3 Mar 2018 22:13:14 +0100
Subject: [PATCH] Documentation

---
 Nuclei/Element.mli           | 18 ++++++++++++++++--
 Nuclei/Mass.ml               |  2 ++
 Nuclei/Mass.mli              |  3 +++
 Nuclei/Nuclei.ml             | 16 +++++++++++-----
 Nuclei/Nuclei.mli            | 26 ++++++++++++++++++++++++++
 Nuclei/Xyz_ast.mli           | 11 +++++++----
 Simulation.ml                |  6 ++----
 {Nuclei => Utils}/Charge.ml  | 11 +++++++++++
 {Nuclei => Utils}/Charge.mli |  6 ++++++
 Utils/Electrons.ml           |  4 ++++
 Utils/Electrons.mli          |  4 ++++
 11 files changed, 92 insertions(+), 15 deletions(-)
 create mode 100644 Nuclei/Mass.mli
 create mode 100644 Nuclei/Nuclei.mli
 rename {Nuclei => Utils}/Charge.ml (53%)
 rename {Nuclei => Utils}/Charge.mli (71%)

diff --git a/Nuclei/Element.mli b/Nuclei/Element.mli
index 9cf2c97..7bf9ee7 100644
--- a/Nuclei/Element.mli
+++ b/Nuclei/Element.mli
@@ -1,4 +1,4 @@
-(** Chemical elements. *)
+(** Chemical elements.  *)
 
 exception ElementError of string
 
@@ -42,11 +42,25 @@ Example:
 [Element.(to_long_string Fe) -> "Iron"]
 *)
 
-(** Properties *)
 val to_int : t -> int 
+(** Convert to the atomic charge, with [int] type. *)
+
 val of_int : int -> t
+(** Create from the atomic charge, with [int] type. *)
+
 val to_charge : t -> Charge.t
+(** Convert to the atomic charge, with {!Charge.t} type. *)
+
 val of_charge : Charge.t -> t
+(** Create from the atomic charge, with {!Charge.t} type. *)
+
 val covalent_radius : t -> NonNegativeFloat.t
+(** Covalent radii of the elements, in atomic units. *)
+
 val vdw_radius : t -> NonNegativeFloat.t
+(** Van der Waals radii of the elements, in atomic units. *)
+
 val mass : t -> Mass.t
+(** Atomic mass of the elements, in atomic units. *)
+
+
diff --git a/Nuclei/Mass.ml b/Nuclei/Mass.ml
index 98c4393..5eb07ee 100644
--- a/Nuclei/Mass.ml
+++ b/Nuclei/Mass.ml
@@ -1 +1,3 @@
+(** Atomic mass. *)
+
 include NonNegativeFloat
diff --git a/Nuclei/Mass.mli b/Nuclei/Mass.mli
new file mode 100644
index 0000000..d942ece
--- /dev/null
+++ b/Nuclei/Mass.mli
@@ -0,0 +1,3 @@
+(** Atomic mass. *)
+
+include module type of NonNegativeFloat
diff --git a/Nuclei/Nuclei.ml b/Nuclei/Nuclei.ml
index 51fea16..14acda5 100644
--- a/Nuclei/Nuclei.ml
+++ b/Nuclei/Nuclei.ml
@@ -3,7 +3,7 @@ open Xyz_ast
 
 type t = (Element.t * Coordinate.t) array
 
-let of_xyz_file ~filename =
+let of_xyz_file filename =
   let lexbuf =
     let ic = open_in filename in
     Lexing.from_channel ic
@@ -25,7 +25,7 @@ let of_xyz_file ~filename =
 
 
 
-let of_zmt_file ~filename =
+let of_zmt_file filename =
   let ic = open_in filename in
   let rec aux accu =
     try
@@ -38,7 +38,7 @@ let of_zmt_file ~filename =
   in aux []
   |> Zmatrix.of_string
   |> Zmatrix.to_xyz
-  |> Array.map (fun (e,x,y,z) -> (e, (Angstrom.make {Point.x ; y ; z} )))
+  |> Array.map (fun (e,x,y,z) -> (e, Coordinate.angstrom_to_bohr (Angstrom.make {Point.x ; y ; z} )))
     
 
 let to_string atoms =
@@ -67,11 +67,11 @@ let to_string atoms =
 "
 
 
-let of_filename ~filename =
+let of_filename filename =
     of_xyz_file filename
   
 
-let repulsion ~nuclei =
+let repulsion nuclei =
   let get_charge e = 
     Element.to_charge e
     |> Charge.to_float
@@ -86,3 +86,9 @@ let repulsion ~nuclei =
       ) 0. nuclei
     ) 0.  nuclei
 
+
+let charge nuclei = 
+  Array.fold_left (fun accu (e, _) -> accu + Charge.to_int (Element.to_charge e) )
+    0 nuclei 
+  |> Charge.of_int
+
diff --git a/Nuclei/Nuclei.mli b/Nuclei/Nuclei.mli
new file mode 100644
index 0000000..4aee0d5
--- /dev/null
+++ b/Nuclei/Nuclei.mli
@@ -0,0 +1,26 @@
+(** Data structure for the molecular geometry, represented as an array
+of tuples ({!Element.t}, {!Coordinate.t}).
+*)
+
+type t = (Element.t * Bohr.t) array
+
+
+val of_xyz_file : string -> t
+(** Create from a file, in [xyz] format. *)
+
+val of_zmt_file : string -> t
+(** Create from a file, in z-matrix format. *)
+
+val to_string : t -> string
+(** Transform to a string, for printing. *)
+
+val of_filename : string -> t
+(** Detects the type of file ([xyz], z-matrix) and reads the file. *)
+
+
+val repulsion : t -> float
+(** Nuclear repulsion energy, in atomic units. *)
+
+val charge : t -> Charge.t
+(** Sum of the charges of the nuclei. *)
+
diff --git a/Nuclei/Xyz_ast.mli b/Nuclei/Xyz_ast.mli
index c1fc73f..1c2fa4c 100644
--- a/Nuclei/Xyz_ast.mli
+++ b/Nuclei/Xyz_ast.mli
@@ -1,13 +1,16 @@
+(** When an [xyz] file is read by the [Xyz_parser.mly], it is converted into
+ an {!xyz_file} data structure. *)
+
 type nucleus =
   {
     element: Element.t ;
-    coord: Angstrom.t;
+    coord  : Angstrom.t;
   }
 
 type xyz_file =
   {
-    number_of_atoms : int;
-    file_title : string;
-    nuclei : nucleus list;
+    number_of_atoms : int ;
+    file_title      : string ;
+    nuclei          : nucleus list ;
   }
 
diff --git a/Simulation.ml b/Simulation.ml
index 0442f9a..157d1ed 100644
--- a/Simulation.ml
+++ b/Simulation.ml
@@ -21,9 +21,7 @@ let make ?multiplicity:(multiplicity=1) ?charge:(charge=0) ~nuclei basis =
     Electrons.make ~multiplicity ~charge nuclei
   in
   let charge = 
-    Array.fold_left (fun accu (e, _) -> accu + Charge.to_int (Element.to_charge e) )
-      0 nuclei - Electrons.(electrons.n_alpha + electrons.n_beta)
-    |> Charge.of_int
+    Charge.(Nuclei.charge nuclei + Electrons.charge electrons)
   in
   let overlap = 
     lazy (Overlap.of_basis basis)
@@ -41,7 +39,7 @@ let make ?multiplicity:(multiplicity=1) ?charge:(charge=0) ~nuclei basis =
 
 let of_filenames ?multiplicity:(multiplicity=1) ?charge:(charge=0) ~nuclei basis =
   let nuclei =
-    Nuclei.of_filename ~filename:nuclei
+    Nuclei.of_filename nuclei
   in
   let basis =
     Basis.of_nuclei_and_basis_filename ~nuclei ~filename:basis
diff --git a/Nuclei/Charge.ml b/Utils/Charge.ml
similarity index 53%
rename from Nuclei/Charge.ml
rename to Utils/Charge.ml
index d4f1738..317493b 100644
--- a/Nuclei/Charge.ml
+++ b/Utils/Charge.ml
@@ -12,3 +12,14 @@ let to_string x =
   else
     Printf.sprintf "%f" x
 
+let ( + ) a b =
+  (to_float a) +. (to_float b) |> of_float
+
+let ( - ) a b =
+  (to_float a) -. (to_float b) |> of_float
+
+let ( * ) a b =
+  (to_float a) *. b |> of_float
+
+let ( / ) a b =
+  (to_float a) /. b |> of_float
diff --git a/Nuclei/Charge.mli b/Utils/Charge.mli
similarity index 71%
rename from Nuclei/Charge.mli
rename to Utils/Charge.mli
index bc455bf..9a398ee 100644
--- a/Nuclei/Charge.mli
+++ b/Utils/Charge.mli
@@ -10,3 +10,9 @@ val of_int   : int -> t
 
 val to_string: t -> string 
 val of_string: string -> t
+
+val ( + ) : t -> t -> t
+val ( - ) : t -> t -> t
+val ( * ) : t -> float -> t
+val ( / ) : t -> float -> t 
+
diff --git a/Utils/Electrons.ml b/Utils/Electrons.ml
index 769fce3..b8b41f8 100644
--- a/Utils/Electrons.ml
+++ b/Utils/Electrons.ml
@@ -21,3 +21,7 @@ let make ?multiplicity:(multiplicity=1) ?charge:(charge=0) nuclei =
     invalid_arg (__FILE__^": make");
   result
 
+let charge e =
+  - (e.n_alpha + e.n_beta)
+  |> Charge.of_int
+
diff --git a/Utils/Electrons.mli b/Utils/Electrons.mli
index c85b048..248a68d 100644
--- a/Utils/Electrons.mli
+++ b/Utils/Electrons.mli
@@ -15,3 +15,7 @@ val make : ?multiplicity:int -> ?charge:int -> Nuclei.t -> t
   @raise Invalid_argument if the spin multiplicity is not compatible with
     the molecule and the total charge.
   *)
+
+val charge : t -> Charge.t
+(** Sum of the charges of the electrons. *)
+