Update installation documents

docs/1_getting_started/1_installation.md

@@ -14,64 +14,164 @@ DTW-C++ does not offer any binaries or wrappers in other languages at the moment
 
 # Dependencies
 
-DTW-C++ aims to 
+DTW-C++ aims to be easily compilable and usable; therefore, it includes only a few libraries where most of the dependencies are automatically installed.  
 
+There are several pre-requisite installations required to compile and run DTW-C++.
 
+The following dependencies need to be manually installed by the user if they do not already exist:
+- [CMake](https://cmake.org/)
+- A suitable compiler (Clang, GCC, MSVC, etc.)
+- Gurobi (optional, if not installed then HiGHS will be used as the MIP solver)
 
+The following dependencies are installed by the CPM package manager: 
+- [HiGHS](https://highs.dev/) as an open source MIP solver alternative to Gurobi. 
+- [CLI11](https://github.com/CLIUtils/CLI11) (for command line interface)
+- [Catch2](https://github.com/catchorg/Catch2/) (for testing)
+- [Armadillo](https://arma.sourceforge.net/) (for matrix reading)
 
+## CMake and compilers
 
-## Building from the source
+[CMake](https://cmake.org/) is a metabuild system required to provide the correct compilation commands to the compiler. It will be explained how to install CMake and compilers depending on your operating system below. 
 
-DTW-C++ aims to be compatible with different compilers and platforms. 
+## Gurobi
 
+Gurobi is a powerful optimisation solver that is free for academic use. If you do not wish to use Gurobi, HiGHS will be used instead. Please see the following guidelines for installation on [Ubuntu](https://www.youtube.com/watch?v=yNmeG6Wom1o), [macOS](https://www.youtube.com/watch?v=ZcL-NmckTxQ), [Windows](https://www.youtube.com/watch?v=z7t0p5J9YcQ), and [further information](https://support.gurobi.com/hc/en-us/sections/360010017231-Platforms-and-Installation)
 
-You may easily install DTW-C++ using CMake (although it is not an absolute requirement). Therefore, you need a suitable C++ compiler (preferably [GCC](https://gcc.gnu.org/)) and [CMake](https://cmake.org/) to follow this installation guide.   
 
+# Building from the source
 
-### Linux
+DTW-C++ aims to be compatible with different compilers and platforms. You may easily install DTW-C++ using CMake (although it is not an absolute requirement). Therefore, you need a suitable C++ compiler (preferably [GCC](https://gcc.gnu.org/)) and [CMake](https://cmake.org/) to follow this installation guide.   
 
-Generally, both GCC and CMake are installed by default on Linux platforms. However, in some cases you may need to install them. For example, Ubuntu 18.04 comes with an older compiler that does not support some of the functionalities in this code directly. Therefore, you may want to [install a newer version of GCC](https://linuxize.com/post/how-to-install-gcc-compiler-on-ubuntu-18-04/). After this:
+## Linux (Debian / Ubuntu 20.04+)
+
+Here we present the default compilation comments targetting new Ubuntu versions above 20.04. As long as there is `CMake 3.21` and a `C++17` capable compiler is installed DTW-C++ should work. However, the compilers installed with default commands in older Ubuntu versions may be older compilers that do not support some of the functionalities in this code directly. Therefore, please refer to [install a newer version of GCC](https://linuxize.com/post/how-to-install-gcc-compiler-on-ubuntu-18-04/) for Ubuntu versions 18.04 or below.
+
+1. Install the essential libraries for building the project
 
-1. Download the repository as a [*.zip file](https://github.com/battery-intelligence-lab/dtw-cpp/archive/refs/heads/main.zip), or clone it using following command: 
+    ```bash
+    sudo apt update
+    sudo apt install -y build-essential cmake-extras cmake
+    ```
+
+2. Clone the repository using the following command or download it as a [*.zip file](https://github.com/battery-intelligence-lab/dtw-cpp/archive/refs/heads/main.zip): 
     ```bash
     git clone https://github.com/battery-intelligence-lab/dtw-cpp.git
     ```
-2. After downloading the source files, you need to create a build folder and go into the build folder:
+3. After downloading the source files, you need to create a build folder and go into the build folder:
     ```bash
-    cd DTWC++  # Go into the main directory of source files.
+    cd dtw-cpp  # Go into the main directory of source files.
     mkdir build # Create a build folder if it is not present.
     cd build # Go into the build directory. 
     ```
-3. Then, create Makefiles by running:
+4. Then, create Makefiles by running:
     ```bash
     cmake -G "Unix Makefiles" .. 
     ```
-4. Compile the files:
+5. Compile the files. Here `-j4` command specifies the number of parallel jobs (threads) to use during the build process and `4` is given as example. For a more powerful computer with many cores you may opt for up to double number of the processors you have. Programmatically you may also use `-j$(( $(nproc) * 2 -1))` where `$(nproc)` denotes number of processors you have. 
+    ```bash
+    cmake --build . -j4 --config Release
+    ```
+6. After this, both executables (`dtwc_main` and `dtwc_cl`) will be ready to run `dtw-cpp/bin` folder. To run the the main application you may use 
+    ```bash
+    cd ../bin
+    ./dtwc_main # to run the code in main.cpp
+    ./dtwc_cl # to run the command line interface
+    ```
+
+```note
+In case you encounter sudden crash of the program, you may also try to complile the program with ```--config Debug```, where you can receive a better message for the crash. For further information on using CMake, please refer to the [CMake guide](https://cmake.org/cmake/help/git-stage/index.html).
+```
+
+## macOS 
+
+1. Install the latest version of [Xcode](https://developer.apple.com/support/xcode/).
+2. Install command line tools, [Homebrew](https://brew.sh/) and CMake by executing following commands on the terminal: 
+```bash
+xcode-select --install
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+brew install cmake
+```
+3. Clone the repository using the following command or download it as a [*.zip file](https://github.com/battery-intelligence-lab/dtw-cpp/archive/refs/heads/main.zip): 
+    ```bash
+    git clone https://github.com/battery-intelligence-lab/dtw-cpp.git
+    ```
+4. After downloading the source files, you need to create a build folder and go into the build folder:
+    ```bash
+    cd dtw-cpp  # Go into the main directory of source files.
+    mkdir build # Create a build folder if it is not present.
+    cd build # Go into the build directory. 
+    ```
+5. Then, create Makefiles by running:
+    ```bash
+    cmake .. 
+    ```
+6. Compile the files. Here `-j4` command specifies the number of parallel jobs (threads) to use during the build process and `4` is given as example. For a more powerful computer with many cores you may opt for up to double number of the processors you have. Programmatically you may also use `-j$(( $(nproc) * 2 -1))` where `$(nproc)` denotes number of processors you have. 
     ```bash
-    cmake --build . -j32 # Assuming that you are still in the build folder. 
+    cmake --build . -j4 --config Release
+    ```
+7. After this, both executables (`dtwc_main` and `dtwc_cl`) will be ready to run `dtw-cpp/bin` folder. To run the the main application you may use 
+    ```bash
+    cd ../bin
+    ./dtwc_main # to run the code in main.cpp
+    ./dtwc_cl # to run the command line interface
     ```
 
 ```note
-After this, executable will be ready to run at ```../Release/dtwc_main```. By default ```CMAKE_BUILD_TYPE``` is set to ```Release```. If desired, you may also use one of the other options such as ```Debug```, ```Release```, ```RelWithDebInfo```, ```MinSizeRel```. To build using an alternative build type you must explicitly define a ```CMAKE_BUILD_TYPE``` variable. For example, for building with debug mode, use the command:
-```cmake --build . -DCMAKE_BUILD_TYPE=Debug```
-For further information on using CMake, please refer to the [CMake guide](https://cmake.org/cmake/help/git-stage/index.html).
+In case you encounter sudden crash of the program, you may also try to complile the program with ```--config Debug```, where you can receive a better message for the crash. For further information on using CMake, please refer to the [CMake guide](https://cmake.org/cmake/help/git-stage/index.html).
 ```
 
-### Windows
+## Windows
 
 On Windows platforms, you probably need to install CMake and a C++ compiler:
 
 1. Install the latest version of the [CMake binary](https://cmake.org/download/#latest).
-2. You can then install a compiler of your choice. If you are going to use GCC, we suggest installing [TDM-GCC](https://jmeubank.github.io/tdm-gcc/download/) (preferably the **MinGW-w64 based edition**). Otherwise, you can install the [Visual Studio Community](https://visualstudio.microsoft.com/vs/community/) IDE which comes with its own compiler.
-3. You can then follow steps 1--4 as per the [Linux section](#linux), except that in step 3, you should write following command: 
-```bash
-cmake -G "MinGW Makefiles" ..  # if you use MinGW GCC compiler.
-```
-Alternatively, you can create a ```*.sln``` file as well as build files via following command if you use Visual Studio Community:
-```bash
-cmake -G "Visual Studio 16 2019" ..  # if you use Visual Studio's compiler.
+2. You can then install a compiler of your choice. We suggest installing MVSC and/or Clang via [Visual Studio Community](https://visualstudio.microsoft.com/vs/community/) even though you do not use the IDE which comes with its own compiler. Otherwise, for `GCC`, easiest way is to install package manager [chocolatey](https://docs.chocolatey.org/en-us/choco/setup/#non-administrative-install) then run `choco install mingw` command. 
+3. Download the repository as a [*.zip file](https://github.com/battery-intelligence-lab/dtw-cpp/archive/refs/heads/main.zip), or if you have [git](https://git-scm.com/download/win) installed you may run the following command in the git bash: 
+    ```bash
+    git clone https://github.com/battery-intelligence-lab/dtw-cpp.git
+    ```
+3. After downloading the source files, you need to create a build folder and go into the build folder. You may type the following commands into the command line:
+    ```bash
+    cd dtw-cpp  # Go into the main directory of source files.
+    mkdir build # Create a build folder if it is not present.
+    cd build # Go into the build directory. 
+    ```
+4. Then, create compilation files by running:
+    ```bash
+    cmake -G "MinGW Makefiles" .. # if you use MinGW GCC compiler.
+    cmake -G "Visual Studio 16 2019" ..  # if you use Visual Studio's compiler.
+    ```
+5. Compile the files. Here `-j4` command specifies the number of parallel jobs (threads) to use during the build process and `4` is given as example. For a more powerful computer with many cores you may opt for up to double number of the processors you have. 
+    ```bash
+    cmake --build . -j4 --config Release
+    ```
+6. After this, both executables (`dtwc_main` and `dtwc_cl`) will be ready to run `dtw-cpp/bin` folder. To run the the main application you may use 
+    ```bash
+    cd ../bin
+    ./dtwc_main # to run the code in main.cpp
+    ./dtwc_cl # to run the command line interface
+    ```
+
+```note
+In case you encounter sudden crash of the program, you may also try to complile the program with ```--config Debug```, where you can receive a better message for the crash. For further information on using CMake, please refer to the [CMake guide](https://cmake.org/cmake/help/git-stage/index.html).
 ```
 
 ```note
 If you are using Visual Studio Community, you may also open the folder in Visual Studio directly, without using CMake. See [this page](https://docs.microsoft.com/en-us/visualstudio/ide/develop-code-in-visual-studio-without-projects-or-solutions?view=vs-2019) for detailed explanation.
 ```
+
+## Visual Studio Code
+
+Visual Studio Code (VScode) is one of the powerful editors and we personally prefer using this editor. To use this editor: 
+
+1. Download and install [Visual Studio Code](https://code.visualstudio.com/download)
+2. Install `CMake` and a suitable compiler and download using the above guidelines for our operating system. 
+3. Download the `DTW-C++` code using `git` or `zip`.
+4. Open VScode and install extensions `C/C++ Extension Pack` and `CMake Tools`. 
+5. Open the `dtw-cpp` folder with the VScode. 
+6. Let the VScode to configure the folder. Now it will scan the kits where you can select a suitable kit (use the 64-bit kits). 
+7. It will compile all targets and you can select `dtwc_main` as your target to run the code in `main.cpp`. 
+
+## Importing as a library
+
+DTW-C++ is designed to be used both as a standalone application and a library where you can add into your existing C++ code. You may copy and use the [example project on our GitHub page](https://github.com/Battery-Intelligence-Lab/dtw-cpp/tree/main/examples/example_project)

docs/1_getting_started/cli.md → docs/1_getting_started/2_cli.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Command line interface (CLI)
-nav_order: 6
+nav_order: 2
 ---
 
 
@@ -38,7 +38,7 @@ DTW-C++ provides a command line interface (CLI) for easy interaction. Below are
 
 The following instruction will, as an example, read in data from the file `dummy`, search for 5 clusters, skip the first row and column in the datasets, terminate after 5 repetitions, and use the mixed integer programming method.
 
-```
+```bash
 dtwc_cl.exe -i "../data/dummy" --Nc=5 --skipRows 1 --skipCols 1 --Nrep=5 --method=mip
 ```
 

docs/1_getting_started/examples.md → docs/1_getting_started/4_examples.md

@@ -8,6 +8,9 @@ nav_order: 8
 
 <!--- Here will be some Google Colab files as example. -->
 
+You may directly edit `main.cpp` and use these examples. 
+
+## k-medoids clustering
 Example code using k-mediods for clustering:
 
 ```cpp
@@ -45,7 +48,7 @@ int main()
 }
 ```
 
-
+## MIP clustering
 Example code using multiple MIP for clustering:
 
 ```cpp

docs/1_getting_started/index.md

@@ -6,13 +6,13 @@ nav_order: 1
 
 # Getting started
 
-To get started, users should first check the [dependencies](dependencies.md) to ensure they are ready to run the _DTW-C++_ software.
+To get started, users should first check the [dependencies](1_installation.md#dependencies) to ensure they are ready to run the _DTW-C++_ software.
 
-Then users can choose to run the code [directly](direct_use.md), using a source-code editor such as Visual Studio Code, which gives the user more freedom. Or for simpler implementation, the user can use the [command line interface](cli.md).
+Then users can choose to run the code by editing `main.cpp`, using a source-code editor such as Visual Studio Code, which gives the user more freedom. Or for simpler implementation, the user can use the [command line interface](2_cli.md).
 
-The format for your input data is detailed [here](supported_data.md). The results are output as .csv files, which the user can specify the location of if desired. The output results include:
+The format for your input data is detailed [here](3_supported_data.md). The results are output as .csv files, which the user can specify the location of if desired. The output results include:
 - DTW matrix, which contains the DTW distance each all time series with each other.
-- Clustering results, which contains the cluster centers and the time series belonging to each cluster. The total [cost](../2_method/3_mip.md) of the clustering problem is included at tht bottom on this .csv.
+- Clustering results, which contains the cluster centers and the time series belonging to each cluster. The total [cost](../2_method/3_mip.md) of the clustering problem is included at tht bottom on this `.csv`.
 - Silhouette score, showing the silouhette score for each time series. The mean of all of these can be considered the total silouhette score for the clustering problem.
 
-Some examples for using the software are detailed [here](examples.md).
+Some examples for using the software are detailed [here](4_examples.md).