Issue 5: Update to v1.2 (#6)

Co-authored-by: Ivan Scivetti <ivan.scivetti@stfc.ac.uk>

README.md

@@ -35,11 +35,13 @@ ALC_TRAJECTORY contains the following set of files and folders (in italic-bold):
 * [***source***](./source): contains the source code. Files have the *.F90* extension
 * [***tools***](./tools): shell files for building, compiling and testing the code automatically.
 * [.gitignore](./.gitignore): instructs Git which file to ignore for development and integration.
+* [gitlab-ci.yml](gitlab-ci.yml): settings for automatic CI building and testing.
+* [CI_instructions.md](./CI_instructions.md): instructions to new developers for CI.
 * [CMakeList.txt](./CMakeList.txt): sets the framework for code building and testing with CMake. This file must ONLY be modified to add test cases.
-* [Jenkinsfile](./Jenkinsfile): file with specifications to build and run the testing infrastructure.
 * [LICENSE](./LICENSE): BSD 3-Clause License for ALC_TRAJECTORY. 
 * README.md: this file.
 * [cmake_building.md](./cmake_building.md): steps to build, compile and run tests using the CMake platform.
+* [coding_protocol.md](./coding_protocol.md): details the instructions of the adopted protocol for code development with Fortran.
 * [use_code.md](./use_code.md): provides instructions for use together with a detailed description of the implemented capabilties. 
 
 ## Dependencies
@@ -54,21 +56,26 @@ Information in parenthesis indicates the minimum version tested during the devel
 
 ## Getting started
 
-### Downloading the code
+### Obtaining the code
 The user with account *"username"* can clone the code locally (in machine *"wherever"*) by executing the following command with the SSH protocol
 ```sh
-username@wherever:/home/username/codes$ git clone git@github.com:stfc/alc_trajectory.git
+username@wherever:/home/username/codes$ git clone git@gitlab.stfc.ac.uk:alc_trajectory/alc_trajectory.git
 ```
-Instead, if the user wants to use the HTTPS protocol it must execute
-```sh
-username@wherever:/home/username/codes$ git clone https://github.com/stfc/alc_trajectory.git
-```
-Both ways generate the ***alc_trajectory*** folder as the root directory. Alternatively, the code can be downloaded from any of the available assets.  
-
+which generate the ***alc_trajectory*** folder as the root directory. Alternatively, the code can be downloaded from any of the available assets.
 
 ### Building and testing the code with CMake
 Details can be found in file [cmake_building.md](./cmake_building.md)
 
 ### Making use of the software
 Once the code has been installed and tested, the user should create a folder where to run the code from. In such folder, the MD trajectory must be copied to the TRAJECTORY file. The user also needs to provide the SETTINGS file with instructions for the type of analysis to execute. Instructions of the implemented capabilities can be found in the [use_code.md](./use_code.md) file. The SETTINGS files in folder [***examples***](./examples) offer explanatory templates, which are intended to help new users in the setting of input directives for execution. In each of the directories, the user will also find the corresponding TRAJECTORY files.
 
+## Contributing 
+Contributions from STFC staff are welcome as long as they comply with the coding protocols, as described in the [coding_protocol.md](./coding_protocol.md) file. Instructions for CI practices are provided in the [CI_instructions.md](./CI_instructions.md) file. New implementation must compulsory include test(s) for CI purposes. 
+
+Contributors should first create a fork using the [**Gitlab STFC**](https://gitlab.stfc.ac.uk/) web user-interface from the main [**ALC_TRAJECTORY**](https://gitlab.stfc.ac.uk/alc_trajectory/alc_trajectory) repository. For instructions of how to create a fork, please refer to the following [**link**](https://docs.gitlab.com/ee/user/project/repository/forking_workflow.html#creating-a-fork). Access to the generated fork will be available from the *Project* tab of [**Gitlab STFC**](https://gitlab.stfc.ac.uk/), which will be located at the address <span style="color:blue">https://gitlab.stfc.ac.uk/user_id/alc_trajectory</span>. In this address, *user_id* will be the user identification in [**Gitlab STFC**](https://gitlab.stfc.ac.uk/). Once the fork is created, the user can clone the *main* branch in the account *"username"* of the local machine *"wherever"* by executing the following command
+```sh
+username@wherever:/home/username/codes$ git clone -b main git@gitlab.stfc.ac.uk:user_id/alc_trajectory.git alc_trajectory
+```
+where ***alc_trajectory*** is set as the root directory. This folder will have been created following the execution of the command above. Any other name can be chosen.  
+
+Contributors should also request to become part of the ALC_TRAJECTORY project by contacting the individual in charge (owner) of the repository. 

examples/Nafion-hydrated/SETTINGS

@@ -84,15 +84,58 @@ change_chemistry True                             # Indicate the algorithm to lo
 ##### The &monitored_species block. This blocks defines the particular type of species to "monitor" along the trajectory
 # The defined species MUST NOT be the changing chemical species
 &monitored_species
-  name H2O                                        # Name of the species. In this case water.
+  name H2O                                        # Name of the species: water in this case.
   reference_tag Ow                                # Only Ow atoms will be part of water. Ow sites can also form chemical species as described above
+  # Atomic definition of the monitored species
+  ############################################
   &atomic_components                              ##### This is to define the atomic composition of the monitored species. For the case of water it is obvious, but the structure of the block allows defining more complex structures:
     number_components 2                           # Number of atomic components (H and O)
     H  2                                          # 2 H atoms
     O  1                                          # 1 O atom
   &end_atomic_components                          #####
+  ############################################
   bond_cutoff      1.2 Angstrom                   # The maximum distance criteria for atomic bonding in this species is 1.2 Angstrom. Units can also be in "Bohr"
   compute_amount   .True.                         # Computes the average number (and STD) of the monitored species. The computed number depends on the settings for the &region block and the ignore_initial directive, if defined 
+
+  ##### Subblock for computation of intramolecular geometry (distances and angles) for monitored species
+  &intramol_stat_settings
+    # Computation of probability density for intramolecular distances
+    &distance_parameters
+      species  O H                                # Only consider distances between the species O and H
+      lower_bound    0.8 Angstrom                 # Consider distances larger than 0.8 Angstrom
+      upper_bound    1.4 Angstrom                 # Consider distance lower than 1.4 Angstrom
+      delta    0.005  Angstrom                    # Use a discretization of 0.005 Angstrom between 0.8 and 1.4 Angstrom 
+   &end_distance_parameters
+
+    # Computation of the probability density for intramolecular angles, only involving the species as defined below 
+    &angle_parameters
+      species    H O H                            # Species involved: the order of the species is relevant, with the species being the central one. Here we compute the angle formed between O and the two H.
+      lower_bound     80   degrees                # Consider angles larger than 80 degress
+      upper_bound     130  degrees                # Consider angles larger than 130 degress
+      delta       0.5    degrees                  # Use a discretization of 0.5 degrees between 80 and 130 degrees
+    &end_angle_parameters
+
+  &end_intramol_stat_settings
+
+  ##### Subblock for computation of intermolecular distances and angles between monitored species
+  &Intermol_stat_settings
+   # Computation of probability density for intermolecular distances between monitored species
+   # Here we do not need to defined the species involved as ALC_TRAJECTORY will automatically select the species defined for "reference_tar" above
+   # ALC_TRAJECTORY will compute the probability denstities for the first and the second nearest neighbour distances
+   &distance_parameters                           
+     delta    0.01  Angstrom                     # Use a discretization of 0.01 Angstrom between 2.3 and 4.0 Angstrom 
+     lower_bound    2.3  Angstrom                # Consider distance lower than 2.3 Angstrom
+     upper_bound    4.0 Angstrom                 # Consider distance lower than 4.0 Angstrom
+   &end_distance_parameters
+
+   # Computation of the probability density for the angle that each monitored species form with the first and the second nearest species
+   &angle_parameters
+     lower_bound    30   degrees                 # Consider angles larger than 30 degress
+     upper_bound    180  degrees                 # Consider angles larger than 180 degress
+     delta          2    degrees                 # Use a discretization of 2 degrees between 30 and 180 degrees
+   &end_angle_parameters
+  &end_intermol_stat_settings
+
 &end_monitored_species                            
 #############################################################################################
 
@@ -168,3 +211,18 @@ print_retagged_trajectory  TRUE              # Print tagged trajectory (False by
   tag  Sch                                        # Requested species tag
   list_indexes  133  134 135  136                 # Atomic indexes. If these indexes do not correspond to the requested tag, the execution is aborted
 &end_track_unchanged_chemistry 
+
+#### The &coord_distrib block: computed the probability of finding a given species along the selected coordinate (x, y or z) for the trajectory
+&coord_distrib
+  species Ow                                      # species to compute the probability
+  coordinate z                                    # coordinate under consideration 
+  delta  0.1 Angstrom                             # coordinate discretization
+&end_coord_distrib
+
+#### The &shortest_pair block: computes the probability density for the closest distance between the species defined in tag, between lower_bound and uooer_bound
+&shortest_pair  
+  tag_species    Ow*  Ow                      # consider the pairs between Ow* and Ow                                                   
+  lower_bound    2.3  Angstrom                # Consider distance lower than 2.3 Angstrom
+  upper_bound    3.0 Angstrom                 # Consider distance lower than 3.0 Angstrom
+  delta    0.01  Angstrom                     # Use a discretization of 0.01 Angstrom between 2.4 and 3.0 Angstrom
+&end_shortest_pair

examples/bulk-water/SETTINGS

@@ -58,6 +58,46 @@ cell_units   Angstrom                             #  Units for the simulation ce
     O  1                                          # 1 O atom
   &end_atomic_components                          #####
   bond_cutoff  1.2 Angstrom                       # The maximum distance criteria for atomic bonding in this species is 1.2 Angstrom. Units can also be in "Bohr" 
+
+ ##### Subblock for computation of intramolecular geometry (distances and angles) for monitored species
+ &intramol_stat_settings
+   # Computation of probability density for intramolecular distances
+   &distance_parameters
+     species  H O                                # Only consider distances between the species O and H
+     lower_bound    0.8 Angstrom                 # Consider distances larger than 0.8 Angstrom
+     upper_bound    1.4 Angstrom                 # Consider distance lower than 1.4 Angstrom
+     delta    0.005  Angstrom                    # Use a discretization of 0.005 Angstrom between 0.8 and 1.4 Angstrom
+  &end_distance_parameters
+
+   # Computation of the probability density for intramolecular angles, only involving the species as defined below
+   &angle_parameters
+     species    H O H                            # Species involved: the order of the species is relevant, with the species being the central one. Here we compute the angle formed between O and the two H.
+     lower_bound     80   degrees                # Consider angles larger than 80 degress
+     upper_bound     130  degrees                # Consider angles larger than 130 degress
+     delta       0.5    degrees                  # Use a discretization of 0.5 degrees between 80 and 130 degrees
+   &end_angle_parameters
+
+ &end_intramol_stat_settings
+
+ ##### Subblock for computation of intermolecular distances and angles between monitored species
+ &Intermol_stat_settings
+  # Computation of probability density for intermolecular distances between monitored species
+  # Here we do not need to defined the species involved as ALC_TRAJECTORY will automatically select the species defined for "reference_tar" above
+  # ALC_TRAJECTORY will compute the probability denstities for the first and the second nearest neighbour distances
+  &distance_parameters
+    delta    0.01  Angstrom                     # Use a discretization of 0.01 Angstrom between 2.3 and 4.0 Angstrom
+    lower_bound    2.3  Angstrom                # Consider distance lower than 2.3 Angstrom
+    upper_bound    4.0 Angstrom                 # Consider distance lower than 4.0 Angstrom
+  &end_distance_parameters
+
+  # Computation of the probability density for the angle that each monitored species form with the first and the second nearest species
+  &angle_parameters
+    lower_bound    30   degrees                 # Consider angles larger than 30 degress
+    upper_bound    180  degrees                 # Consider angles larger than 180 degress
+    delta          2    degrees                 # Use a discretization of 2 degrees between 30 and 180 degrees
+  &end_angle_parameters
+ &end_intermol_stat_settings
+
 &end_monitored_species                            
 #############################################################################################
 

scripts/clean_data.sh

@@ -1,14 +1,21 @@
 #!/usr/bin/env bash
 
-[ -f 'TRACK_CHEMISTRY' ]      && rm  TRACK_CHEMISTRY 
-[ -f 'OUTPUT' ]               && rm  OUTPUT  
-[ -f 'TAGGED_TRAJECTORY' ]    && rm  TAGGED_TRAJECTORY
-[ -f 'OCF' ]                  && rm  OCF 
-[ -f 'OCF_AVG' ]              && rm  OCF_AVG 
-[ -f 'MSD' ]                  && rm  MSD
-[ -f 'MSD_AVG' ]              && rm  MSD_AVG 
-[ -f 'RDF' ]                  && rm  RDF 
-[ -f 'TCF' ]                  && rm  TCF
-[ -f 'TCF_AVG' ]              && rm  TCF_AVG
-[ -f 'UNCHANGED_CHEMISTRY' ]  && rm  UNCHANGED_CHEMISTRY
-[ -f 'RES_TIMES' ]            && rm  RES_TIMES
+[ -f 'TRACK_CHEMISTRY' ]         && rm  TRACK_CHEMISTRY 
+[ -f 'OUTPUT' ]                  && rm  OUTPUT  
+[ -f 'TAGGED_TRAJECTORY' ]       && rm  TAGGED_TRAJECTORY
+[ -f 'OCF' ]                     && rm  OCF 
+[ -f 'OCF_AVG' ]                 && rm  OCF_AVG 
+[ -f 'MSD' ]                     && rm  MSD
+[ -f 'MSD_AVG' ]                 && rm  MSD_AVG 
+[ -f 'RDF' ]                     && rm  RDF 
+[ -f 'TCF' ]                     && rm  TCF
+[ -f 'TCF_AVG' ]                 && rm  TCF_AVG
+[ -f 'UNCHANGED_CHEMISTRY' ]     && rm  UNCHANGED_CHEMISTRY
+[ -f 'RES_TIMES' ]               && rm  RES_TIMES
+[ -f 'COORD_DISTRIBUTION' ]      && rm  COORD_DISTRIBUTION
+[ -f 'INTRAMOL_DISTANCES' ]      && rm  INTRAMOL_DISTANCES
+[ -f 'INTRAMOL_ANGLES' ]         && rm  INTRAMOL_ANGLES 
+[ -f 'INTERMOL_DISTANCES_NN1' ]  && rm  INTERMOL_DISTANCES_NN1
+[ -f 'INTERMOL_DISTANCES_NN2' ]  && rm  INTERMOL_DISTANCES_NN2
+[ -f 'INTERMOL_ANGLES_NN' ]      && rm  INTERMOL_ANGLES_NN
+[ -f 'DISTANCE_SHORTEST_PAIR' ]  && rm  DISTANCE_SHORTEST_PAIR