UP | HOME

# Common

## Table of Contents

- 1. Summary
- 2. Electrons
  - 2.1. Type
  - 2.2. Creation
  - 2.3. Access
  - 2.4. Printers
  - 2.5. Tests
- 3. Element
  - 3.1. Type
  - 3.2. Conversion
  - 3.3. Database information
  - 3.4. Printers
- 4. Atomic mass
- 5. Nuclei
  - 5.1. Type
  - 5.2. xyz file lexer/parser
    - 5.2.1. Lexer
    - 5.2.2. Parser
  - 5.3. Conversion
  - 5.4. Query
  - 5.5. TREXIO
    - 5.5.1. Read
    - 5.5.2. Write
  - 5.6. Printers
  - 5.7. Tests
- 6. Z-matrix
  - 6.1. Type
  - 6.2. Conversion
  - 6.3. Printers

## 1 Summary

## 2 Electrons

Data structure which contains the number of α and β electrons.

### 2.1 Type

    type t

### 2.2 Creation

    open Common

    val make : int -> int -> t

    val of_atoms : ?multiplicity:int -> ?charge:int -> Nuclei.t -> t
    (* @param multiplicity default is 1
       @param charge       default is 0
       @raise Invalid_argument if the spin multiplicity is not compatible with
        the molecule and the total charge.
    *)

`make` | `make n_alfa n_beta`
`of_atoms` | Creates the data relative to electrons for a molecular system described by `Nuclei.t` for a given total charge and spin multiplicity.

### 2.3 Access

    val charge       : t -> Charge.t
    val n_elec       : t -> int
    val n_alfa       : t -> int
    val n_beta       : t -> int
    val multiplicity : t -> int

`charge` | Sum of the charges of the electrons
`n_elec` | Number of electrons
`n_alfa` | Number of alpha electrons
`n_beta` | Number of beta electrons
`multiplicity` | Spin multiplicity: \(2S+1\)

### 2.4 Printers

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

### 2.5 Tests

## 3 Element

Chemical elements.

### 3.1 Type

    type t =
      |X
      |H                                                 |He
      |Li|Be                              |B |C |N |O |F |Ne
      |Na|Mg                              |Al|Si|P |S |Cl|Ar
      |K |Ca|Sc|Ti|V |Cr|Mn|Fe|Co|Ni|Cu|Zn|Ga|Ge|As|Se|Br|Kr
      |Rb|Sr|Y |Zr|Nb|Mo|Tc|Ru|Rh|Pd|Ag|Cd|In|Sn|Sb|Te|I |Xe
                              |Pt

    exception ElementError of string

    open Common

### 3.2 Conversion

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

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

    val to_charge : t -> Charge.t
    val of_charge : Charge.t -> t

`of_string` | Creates an `Element.t` from a chemical symbol or from the full name of the element (case insensitive)
`to_string` | Gets the chemical symbol of the `Element.t` in a string
`to_long_string` | Gets the full name of the `Element.t` in a string
`to_int` | Convert to the atomic charge, with `int` type
`of_int` | Create from the atomic charge, with `int` type
`to_charge` | Convert to the atomic charge, with `Charge.t` type
`of_charge` | Create from the atomic charge, with `Charge.t` type

    Element.of_string "Fe" ;;
    - : Element.t = Particles.Element.Fe

    Element.of_string "hydrogen" ;;
    - : Element.t = Particles.Element.H

    Element.of_string "Kryptonite" ;;
    Exception: Particles.Element.ElementError "Element Kryptonite unknown".

    Element.(to_long_string Fe) ;;
    - : string = "Iron"

    Element.(to_string Fe);;
    - : string = "Fe"

### 3.3 Database information

    val covalent_radius : t -> Non_negative_float.t
    val vdw_radius      : t -> Non_negative_float.t
    val mass            : t -> Mass.t
    val small_core      : t -> int
    val large_core      : t -> int

`covalent_radius` | Covalent radii of the elements, in atomic units
`vdw_radius` | Van der Waals radii of the elements, in atomic units
`mass` | Atomic mass of the elements, in atomic units)
`small_core` | Number of electrons in the small core model (all except the outermost two shells)
`large_core` | Number of electrons in the large core model (all except the outermost shell)

### 3.4 Printers

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

## 4 Atomic mass

Atomic mass, a non-negative float.

    include module type of Common.Non_negative_float

## 5 Nuclei

### 5.1 Type

`Nuclei.t`

    open Common

    type t = (Element.t * Coordinate.t) array

### 5.2 xyz file lexer/parser

#### 5.2.1 Lexer

`nuclei_lexer.mll` contains the description of the lexemes used in an xyz file.

    {
    open Xyz_parser
    }

    let eol = ['\n']
    let white = [' ' '\t']+
    let word = [^' ' '\t' '\n']+
    let letter = ['A'-'Z' 'a'-'z']
    let integer = ['0'-'9']+
    let real = '-'? (integer '.' integer | integer '.' | '.' integer) (['e' 'E'] ('+'|'-')? integer)?

    rule read_all = parse
      | eof            { EOF }
      | eol            { EOL }
      | white   as w   { SPACE w }
      | integer as i   { INTEGER (int_of_string i) }
      | real    as f   { FLOAT (float_of_string f) }
      | word    as w   { WORD w }

    {
    (* DEBUG
     let () =
       let ic = open_in "h2o.xyz" in
       let lexbuf = Lexing.from_channel ic in
       while true do
         let s =
          match read_all lexbuf with
          | EOL -> "EOL"
          | SPACE w -> "SPACE("^w^")"
          | INTEGER i -> "INTEGER("^(string_of_int i)^")"
          | FLOAT f -> "FLOAT("^(string_of_float f)^")"
          | WORD w -> "WORD("^w^")"
          | EOF -> "EOF"
         in
         print_endline s
       done;
    *)
    }

#### 5.2.2 Parser

`xyz_parser.mly` parses nuclear coordinates in xyz format.

    %{
    open Common

    let make_angstrom x y z =
      Coordinate.(make_angstrom {
        x ; y ; z
      })

    let output_of f x y z =
      let a = make_angstrom x y z in
      fun e ->
      {
        Xyz_ast.
        element = f e;
        coord = a ;
      }

    let output_of_string = output_of Element.of_string
    let output_of_int    = output_of Element.of_int

    %}

    %token EOL
    %token <string> SPACE
    %token <string> WORD
    %token <int> INTEGER
    %token <float> FLOAT
    %token EOF

    %start input
    %type <Xyz_ast.xyz_file> input

    %% /* Grammar rules and actions follow */

    input:
      | integer title atoms_xyz {
          {
            number_of_atoms = $1;
            file_title = $2;
            nuclei = $3;
          }
        }
    ;

    integer:
      | INTEGER EOL { $1 }
      | INTEGER SPACE EOL { $1 }
      | SPACE INTEGER EOL { $2 }
      | SPACE INTEGER SPACE EOL { $2 }
    ;

    title:
      | title_list EOL { $1 }
    ;

    text:
      | WORD    { $1 }
      | SPACE   { $1 }
      | FLOAT   { (string_of_float $1)}
      | INTEGER { (string_of_int $1)}
    ;

    title_list:
      | { "" }
      | title_list text { ($1 ^ $2) }
    ;

    atoms_xyz:
      | atoms_list EOL { List.rev $1 }
      | atoms_list EOF { List.rev $1 }
    ;

    atoms_list:
      | { [] }
      | atoms_list WORD    SPACE FLOAT SPACE FLOAT SPACE FLOAT       EOL { output_of_string $4 $6 $8 $2 :: $1 }
      | atoms_list WORD    SPACE FLOAT SPACE FLOAT SPACE FLOAT SPACE EOL { output_of_string $4 $6 $8 $2 :: $1 }
      | atoms_list INTEGER SPACE FLOAT SPACE FLOAT SPACE FLOAT       EOL { output_of_int    $4 $6 $8 $2 :: $1 }
      | atoms_list INTEGER SPACE FLOAT SPACE FLOAT SPACE FLOAT SPACE EOL { output_of_int    $4 $6 $8 $2 :: $1 }
      | atoms_list SPACE WORD    SPACE FLOAT SPACE FLOAT SPACE FLOAT       EOL { output_of_string $5 $7 $9 $3 :: $1 }
      | atoms_list SPACE WORD    SPACE FLOAT SPACE FLOAT SPACE FLOAT SPACE EOL { output_of_string $5 $7 $9 $3 :: $1 }
      | atoms_list SPACE INTEGER SPACE FLOAT SPACE FLOAT SPACE FLOAT       EOL { output_of_int    $5 $7 $9 $3 :: $1 }
      | atoms_list SPACE INTEGER SPACE FLOAT SPACE FLOAT SPACE FLOAT SPACE EOL { output_of_int    $5 $7 $9 $3 :: $1 }
    ;

When an xyz file is read by `xyz_parser.mly`, it is converted into an `xyz_file` data structure.

    open Common

    type nucleus =
      {
        element: Element.t ;
        coord  : Coordinate.angstrom Coordinate.point;
      }

    type xyz_file =
      {
        number_of_atoms : int ;
        file_title      : string ;
        nuclei          : nucleus list ;
      }

### 5.3 Conversion

    val of_xyz_string : string -> t
    val to_xyz_string  : t -> string
    val of_xyz_file   : string -> t

    val of_zmt_string : string -> t
    val of_zmt_file   : string -> t

    val to_string      : t -> string

    val of_filename : string -> t

`of_xyz_string` | Create from a string, in xyz format
`of_xyz_file` | Create from a file, in xyz format
`of_zmt_string` | Create from a string, in z-matrix format
`of_zmt_file` | Create from a file, in z-matrix format
`to_string` | Transform to a string, for printing
`of_filename` | Detects the type of file (xyz, z-matrix) and reads the file

### 5.4 Query

    val formula    : t -> string
    val repulsion  : t -> float
    val charge     : t -> Charge.t
    val small_core : t -> int
    val large_core : t -> int

`formula` | Returns the chemical formula
`repulsion` | Nuclear repulsion energy, in atomic units
`charge` | Sum of the charges of the nuclei
`small_core` | Number of core electrons in the small core model
`large_core` | Number of core electrons in the large core model

### 5.5 TREXIO

#### 5.5.1 Read

    val of_trexio : Trexio.trexio_file -> t

#### 5.5.2 Write

    val to_trexio : Trexio.trexio_file -> t -> unit

### 5.6 Printers

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

### 5.7 Tests

## 6 Z-matrix

Z-matrix representation of nuclear coordinates.

### 6.1 Type

    type t

### 6.2 Conversion

    val of_string      : string -> t
    val to_xyz         : t -> (Element.t * float * float * float) array
    val to_xyz_string  : t -> string

`of_string` | Reads a z-matrix from a string
`to_xyz` | Converts to xyz format, as in the `Nuclei` module
`to_xyz_string` | Converts to xyz format, as a string

    let zmt = Zmatrix.of_string "
     n
     n    1 nn
     h    1 hn         2 hnn
     h    2 hn         1 hnn          3 dih4
     h    1 hn         2 hnn          4 dih5
     h    2 hn         1 hnn          3 dih5

    nn          1.446
    hn          1.016
    hnn         106.0
    dih4        -54.38
    dih5         54.38
    " ;;
    - : Zmatrix.t = N
    N       1 1.446000
    H       1 1.016000     2 106.000000
    H       2 1.016000     1 106.000000     3 -54.380000
    H       1 1.016000     2 106.000000     4 54.380000
    H       2 1.016000     1 106.000000     3 54.380000

    Zmatrix.to_xyz zmt ;;
    - : (Element.t * float * float * float) array =
    [|(N, 0., 0., 0.); (N, 0., 0., 1.446);
      (H, -0.976641883073332107, 0., -0.280047553510071046);
      (H, -0.568802835186988709, 0.793909757123734683, 1.726047553510071);
      (H, 0.314092649983635563, 0.924756819385119, -0.280047553510071101);
      (H, -0.568802835186988709, -0.793909757123734683, 1.726047553510071)|]

    Zmatrix.to_xyz_string zmt ;;
    - : string =
    "N 0.000000 0.000000 0.000000
    N 0.000000 0.000000 1.446000
    H -0.976642 0.000000 -0.280048
    H -0.568803 0.793910 1.726048
    H 0.314093 0.924757 -0.280048
    H -0.568803 -0.793910 1.726048"

### 6.3 Printers

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

Author: Anthony Scemama

Created: 2023-04-24 Mon 18:07

Validate