Installation documentation update

.github/workflows/ubuntu-unit.yml

@@ -25,9 +25,6 @@ jobs:
           - CC: gcc-12
             CXX: g++-12
             compiler: gcc-12 g++-12
-          - CC: gcc-13
-            CXX: g++-13
-            compiler: gcc-13 g++-13
           - CC: clang-12
             CXX: clang++-12
             compiler: clang-12 libomp-12-dev

CHANGELOG.md

@@ -22,11 +22,12 @@ This changelog contains a non-exhaustive list of new features and notable bug-fi
 
 ## Dependency updates:
 * Required C++ standard is reduced from C++20 to C++17 as it was causing `call to consteval function 'std::chrono::hh_mm_ss::_S_fractional_width' is not a constant expression` error for clang versions older than clang-15.
-* std::execution-based parallelisation replaced with OpenMP.
+* `OpenMP` for parallelisation is adopted as `Apple-clang` does not support `std::execution`. 
 
 ## Developer updates: 
 * The software is now being tested via Catch2 library. 
 * Dependabot is added. 
+* `CURRENT_ROOT_FOLDER` and `DTWC_ROOT_FOLDER` are seperated as DTW-C++ library can be included by other libraries. 
 
 <br/><br/>
 # DTWC v0.3.0

CMakeLists.txt

@@ -11,20 +11,21 @@ project(DTWC++ VERSION "1.0.0"
   HOMEPAGE_URL https://battery-intelligence-lab.github.io/dtw-cpp/
   LANGUAGES CXX C)
 
-# Define the root path
-add_definitions(-DDTWC_ROOT_FOLDER="${CMAKE_SOURCE_DIR}")
+set(CURRENT_ROOT_FOLDER "${CMAKE_SOURCE_DIR}" CACHE STRING "Root folder for main project") 
+set(DTWC_ROOT_FOLDER "${CMAKE_CURRENT_LIST_DIR}" CACHE STRING "Root folder for DTWC project") 
+
 include(cmake/StandardProjectSettings.cmake)
 
 option(DTWC_BUILD_EXAMPLES OFF)
 option(DTWC_BUILD_TESTING OFF)
-option(BUILD_BENCHMARK OFF)
+option(DTWC_BUILD_BENCHMARK OFF)
 
 set(DTWC_ENABLE_GUROBI ON)
 set(DTWC_ENABLE_HIGHS ON)
 include(cmake/Dependencies.cmake) # Include external projects
 include(cmake/FindGUROBI.cmake)
 
-include(cmake/PreventInSourceBuilds.cmake)
+# include(cmake/PreventInSourceBuilds.cmake)
 dtwc_setup_dependencies()
 
 # Link this 'library' to use the warnings specified in CompilerWarnings.cmake
@@ -38,6 +39,7 @@ enable_testing()
 
 add_subdirectory(dtwc bin)
 
+
 add_executable(dtwc_main
   dtwc/main.cpp
 )
@@ -66,27 +68,16 @@ target_link_libraries(dtwc_cl
 include(CTest)
 enable_testing()
 if(DTWC_BUILD_TESTING)
-  #message(AUTHOR_WARNING "Building Tests. Be sure to check out test/constexpr_tests.cpp for constexpr testing")
   include(cmake/Coverage.cmake)
   add_subdirectory(tests)
 endif()
 
-
 if(DTWC_BUILD_EXAMPLES)
   add_subdirectory(examples)
 endif()
 
-if(BUILD_BENCHMARK)
+if(DTWC_BUILD_BENCHMARK)
   add_subdirectory(benchmark)
 endif()
 
-find_package(pybind11 QUIET)
-
-if(pybind11_FOUND)
-    pybind11_add_module(dtwcpp 
-            python/py_main.cpp)
-
-    target_link_libraries(dtwcpp PRIVATE dtwc++ project_warnings project_options armadillo)
-else()
-    message(STATUS "pybind11 not found. Skipping the dtwcpp module.")
-endif()
+cpm_licenses_create_disclaimer_target(write-licenses "${CMAKE_CURRENT_SOURCE_DIR}/bin/third_party.txt" "${CPM_PACKAGES}")

cmake/CPM.cmake

@@ -1,7 +1,9 @@
-# File to download CPM, adapted from https://github.com/cpp-best-practices/cmake_template/tree/main 
-# and https://github.com/TheLartians/ModernCppStarter/blob/master/cmake/CPM.cmake
-set(CPM_DOWNLOAD_VERSION 0.38.7)
-set(CPM_HASH_SUM "83e5eb71b2bbb8b1f2ad38f1950287a057624e385c238f6087f94cdfc44af9c5")
+# SPDX-License-Identifier: MIT
+#
+# SPDX-FileCopyrightText: Copyright (c) 2019-2023 Lars Melchior and contributors
+
+set(CPM_DOWNLOAD_VERSION 0.40.2)
+set(CPM_HASH_SUM "c8cdc32c03816538ce22781ed72964dc864b2a34a310d3b7104812a5ca2d835d")
 
 if(CPM_SOURCE_CACHE)
   set(CPM_DOWNLOAD_LOCATION "${CPM_SOURCE_CACHE}/cpm/CPM_${CPM_DOWNLOAD_VERSION}.cmake")

cmake/Dependencies.cmake

@@ -9,32 +9,31 @@ include(cmake/CPM.cmake)
 function(dtwc_setup_dependencies)
   # For each dependency, see if it's
   # already been provided to us by a parent project
+  CPMAddPackage(
+    NAME CPMLicenses.cmake 
+    GITHUB_REPOSITORY cpm-cmake/CPMLicenses.cmake
+    VERSION 0.0.7
+  )
 
   if(NOT TARGET Catch2::Catch2WithMain) # Catch2 library:
     CPMAddPackage(
       NAME Catch2
-      URL "https://github.com/catchorg/Catch2/archive/refs/tags/v3.3.2.tar.gz"
+      URL "https://github.com/catchorg/Catch2/archive/refs/tags/v3.7.0.tar.gz"
       OPTIONS 
       "CATCH_INSTALL_DOCS OFF" "CATCH_INSTALL_EXTRAS OFF" "CATCH_BUILD_TESTING OFF"
     )
   endif()
 
-  # if(NOT TARGET fmt) # fmt library:
-  # CPMAddPackage(
-  #   NAME fmt
-  #   URL "https://github.com/fmtlib/fmt/archive/refs/tags/10.1.1.tar.gz"
-  # )
-  # endif()
-
   # HiGHS library:
   if(NOT TARGET highs::highs AND DTWC_ENABLE_HIGHS)# HiGHS library:
   CPMAddPackage(
     NAME highs
-    URL "https://github.com/ERGO-Code/HiGHS/archive/refs/tags/v1.6.0.tar.gz"
+    URL "https://github.com/ERGO-Code/HiGHS/archive/refs/tags/v1.7.2.tar.gz"
     SYSTEM
     EXCLUDE_FROM_ALL
     OPTIONS
-    "ZLIB OFF" "FAST_BUILD ON" "BUILD_TESTING OFF" "BUILD_EXAMPLES OFF" "BUILD_SHARED_LIBS OFF")
+    "CI OFF" "ZLIB OFF" "BUILD_EXAMPLES OFF" "BUILD_TESTING OFF"
+    )
   endif()
 
   if (NOT TARGET CLI11::CLI11)
@@ -44,7 +43,7 @@ function(dtwc_setup_dependencies)
     DOWNLOAD_ONLY YES 
   )
 
-  add_library(CLI11::CLI11 INTERFACE IMPORTED)
+   add_library(CLI11::CLI11 INTERFACE IMPORTED)
   set_target_properties(CLI11::CLI11 PROPERTIES
     INTERFACE_INCLUDE_DIRECTORIES "${CLI11_SOURCE_DIR}/include")
   endif()
@@ -55,4 +54,5 @@ function(dtwc_setup_dependencies)
     OPTIONS
     "BUILD_SMOKE_TEST OFF"
   )
+
 endfunction()

cmake/FindGUROBI.cmake

@@ -120,4 +120,4 @@ set(GUROBI_INCLUDE_DIRS "${GUROBI_INCLUDE_DIR}")
 set(GUROBI_LIBRARIES Gurobi::GurobiC Gurobi::GurobiCXX)
 
 include(FindPackageHandleStandardArgs)
-find_package_handle_standard_args(Gurobi  DEFAULT_MSG GUROBI_LIBRARY GUROBI_INCLUDE_DIR GUROBI_SRC_DIR)
+find_package_handle_standard_args(Gurobi  DEFAULT_MSG GUROBI_LIBRARY GUROBI_INCLUDE_DIR GUROBI_SRC_DIR)

docs/1_getting_started/1_installation.md

@@ -0,0 +1,179 @@
+---
+layout: default
+title: Running
+nav_order: 2
+---
+
+# Using DTW-C++ 
+
+DTW-C++ does not offer any binaries or wrappers in other languages at the moment. Therefore, the only way to use DTW-C++ is to compile it from C++ source files. With the appropriate compilers and dependencies installed you can easily compile DTW-C++ and use it, for example:
+
+- Edit `main.cpp` in the `dtwc` folder and use the `dtwc_main` executable after compilation using the examples in `examples` folder. 
+- Use DTW-C++ from the command line interface, by using the `dtwc_cl` executable after compilation. 
+- Use DTW-C++ as an external library in your C++ project by linking the `dtwc++` target in your project. Download the source code to your folder of preference, include the line `add_subdirectory(dtw-cpp)` in your `CMakeLists.txt` file. Then link your library. Alternatively, you may also use [CPM](https://github.com/cpm-cmake/) to interactively download and include DTW-C++. However, it should be noted that including DTWC++ may make the predefined path variables such as `dtwc::settings::dataPath` invalid. Therefore, you may manually define the required paths depending on the structure of your folders. 
+
+# Dependencies
+
+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)
+- [OpenMP](https://www.openmp.org/) this should come with GCC and MSVC libraries; however to install it with Clang, you may install `libomp-xx-dev` where `xx` is your clang version. 
+
+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
+
+[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. 
+
+## 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)
+
+
+# Building from the source
+
+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.   
+
+## 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
+
+    ```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
+    ```
+3. 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. 
+    ```
+4. Then, create Makefiles by running:
+    ```bash
+    cmake -G "Unix Makefiles" .. 
+    ```
+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
+brew install libomp llvm && brew link --force libomp
+```
+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 . -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
+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
+
+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. 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,13 +1,13 @@
 ---
 layout: default
 title: Command line interface (CLI)
-nav_order: 6
+nav_order: 2
 ---
 
 
 # Command line interface (CLI)
 
-It is possible to use DTW-C++ from the command line after successfully compiling the code. Please compile the software using [these instructions](run.md) and run the `bin/dtwc_cl` executable. This will provide you with all the command line interface (CLI) functions. To call the CLI from any other folder, you need to add the `/bin` folder into your path. Alternatively, you can just copy the executable into any folder of your choice. 
+It is possible to use DTW-C++ from the command line after successfully compiling the code. Please compile the software using [these instructions](1_installation.md) and run the `bin/dtwc_cl` executable. This will provide you with all the command line interface (CLI) functions. To call the CLI from any other folder, you need to add the `/bin` folder into your path. Alternatively, you can just copy the executable into any folder of your choice. 
 
 ## Features
 - **Multiple clustering methods**: Supports the k-medoids and MIP methods.
@@ -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