diff --git a/.github/workflows/ubuntu-unit.yml b/.github/workflows/ubuntu-unit.yml index d7e9cfe..c6bf74e 100644 --- a/.github/workflows/ubuntu-unit.yml +++ b/.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 diff --git a/CHANGELOG.md b/CHANGELOG.md index 321b4bf..bec88bf 100644 --- a/CHANGELOG.md +++ b/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.

# DTWC v0.3.0 diff --git a/CMakeLists.txt b/CMakeLists.txt index 0e9c3fe..6770374 100644 --- a/CMakeLists.txt +++ b/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() \ No newline at end of file +cpm_licenses_create_disclaimer_target(write-licenses "${CMAKE_CURRENT_SOURCE_DIR}/bin/third_party.txt" "${CPM_PACKAGES}") \ No newline at end of file diff --git a/cmake/CPM.cmake b/cmake/CPM.cmake index 09c5a30..16ff082 100644 --- a/cmake/CPM.cmake +++ b/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") diff --git a/cmake/Dependencies.cmake b/cmake/Dependencies.cmake index 728ee40..1e5bd52 100644 --- a/cmake/Dependencies.cmake +++ b/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() diff --git a/cmake/FindGUROBI.cmake b/cmake/FindGUROBI.cmake index 27a78a2..1ee8cee 100644 --- a/cmake/FindGUROBI.cmake +++ b/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) \ No newline at end of file +find_package_handle_standard_args(Gurobi DEFAULT_MSG GUROBI_LIBRARY GUROBI_INCLUDE_DIR GUROBI_SRC_DIR) diff --git a/docs/1_getting_started/1_installation.md b/docs/1_getting_started/1_installation.md new file mode 100644 index 0000000..e701012 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/docs/1_getting_started/cli.md b/docs/1_getting_started/2_cli.md similarity index 84% rename from docs/1_getting_started/cli.md rename to docs/1_getting_started/2_cli.md index 4dbbcbf..08f75e6 100644 --- a/docs/1_getting_started/cli.md +++ b/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 ``` diff --git a/docs/1_getting_started/supported_data.md b/docs/1_getting_started/3_supported_data.md similarity index 100% rename from docs/1_getting_started/supported_data.md rename to docs/1_getting_started/3_supported_data.md diff --git a/docs/1_getting_started/examples.md b/docs/1_getting_started/4_examples.md similarity index 96% rename from docs/1_getting_started/examples.md rename to docs/1_getting_started/4_examples.md index 4a1f631..358588f 100644 --- a/docs/1_getting_started/examples.md +++ b/docs/1_getting_started/4_examples.md @@ -8,6 +8,9 @@ nav_order: 8 +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 diff --git a/docs/1_getting_started/dependencies.md b/docs/1_getting_started/dependencies.md deleted file mode 100644 index b880c0a..0000000 --- a/docs/1_getting_started/dependencies.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -layout: default -title: Dependencies -nav_order: 3 ---- - -# Dependencies - -There are several pre-requisite installations required to compile and run DTW-C++. - -The following dependencies need to be installed by the user if they do not already exist: -- CMake -- OpenMP -- 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 -- CLI11 -- Catch2 (for testing) - -See `cmake/Dependencies.cmake` for a detailed list of libraries/packages installed by CPM. - -## CMake - -CMake is a metabuild system required to provide the correct compilation commands to the compiler. Please follow the official guidelines to download it for your preference of operating system. - -## 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. - -### Linux installation - -1. Download the installation file. Then extract it to a folder (preferably the `opt` folder) using the following command: - ```bash - tar xvfz gurobi9.5.2_linux64.tar.gz -C /opt/ - ``` -2. Then add necessary variables to the end of your `~/.bashrc` file. - ```bash - export GUROBI_HOME=/opt/gurobi952/linux64 - export PATH=$GUROBI_HOME/bin:$PATH - export LD_LIBRARY_PATH=$GUROBI_HOME/lib:$LD_LIBRARY_PATH - ``` -3. Don't forget to source your `~/.bashrc` file. - ```bash - source ~/.bashrc - ``` -4. Then you need to add a licence. If you are an academic, obtain an academic licence from the Gurobi website. Then use `grbgetkey` command to validate your licence. - ```bash - grbgetkey HERE-SHOULD-BE-YOUR-LICENSE-KEY - ``` -5. To test if the installation was correct, use the command: - ```bash - gurobi_cl $GUROBI_HOME/examples/data/afiro.mps - ``` - -There is a [visual guide](https://www.youtube.com/watch?v=yNmeG6Wom1o) available for Linux installation. - - -### macOS installation - -There is a [visual guide](https://www.youtube.com/watch?v=ZcL-NmckTxQ) available for macOS installation. diff --git a/docs/1_getting_started/direct_use.md b/docs/1_getting_started/direct_use.md deleted file mode 100644 index 0135fe7..0000000 --- a/docs/1_getting_started/direct_use.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -layout: default -title: Direct use -nav_order: 4 ---- - -# Direct use - -Although DTW-C++ is easiest to use via the command line interface executable, it can also be used directly as follows: - -- Install [the dependencies](dependencies.md). -- Download the source code and extract it if it is zipped. -- Copy your data into the `data` folder in one of the [supported data formats](supported_data.md). -- Edit `main.cpp` in the `dtwc` folder using the examples in the `examples` folder or [examples page](examples.md). -- Compile the code using [these instructions](run.md), and after compilation use the `dtwc_main` executable located in the `./dtw-cpp/bin` folder. diff --git a/docs/1_getting_started/index.md b/docs/1_getting_started/index.md index f4a7563..ff0d540 100644 --- a/docs/1_getting_started/index.md +++ b/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). diff --git a/docs/1_getting_started/run.md b/docs/1_getting_started/run.md deleted file mode 100644 index b443c0b..0000000 --- a/docs/1_getting_started/run.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -layout: default -title: Running -nav_order: 2 ---- - -# Running 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: - -- Use DTW-C++ as an external library in your C++ project by linking the `dtwc++` target in your project. -- Use DTW-C++ from the command line interface, by using the `dtwc_cl` executable after compilation. -- Edit `main.cpp` in the `dtwc` folder and use the `dtwc_main` executable after compilation using the examples in `examples` folder. -- As a subdirectory: 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. - - -## 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 - -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: - -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 - 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: - ```bash - cd DTWC++ # 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: - ```bash - cmake -G "Unix Makefiles" .. - ``` -4. Compile the files: - ```bash - cmake --build . -j32 # Assuming that you are still in the build folder. - ``` - -```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). -``` - -### 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. -``` - -```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. -``` diff --git a/dtwc/CMakeLists.txt b/dtwc/CMakeLists.txt index 6aedb4b..776b6f2 100644 --- a/dtwc/CMakeLists.txt +++ b/dtwc/CMakeLists.txt @@ -1,6 +1,8 @@ cmake_minimum_required(VERSION 3.21) add_library(dtwc++ STATIC) +target_compile_definitions(dtwc++ PUBLIC DTWC_ROOT_FOLDER="${DTWC_ROOT_FOLDER}") +target_compile_definitions(dtwc++ PUBLIC CURRENT_ROOT_FOLDER="${CURRENT_ROOT_FOLDER}") add_subdirectory(mip) @@ -39,5 +41,6 @@ target_link_libraries(dtwc++ find_package(OpenMP) if(OpenMP_CXX_FOUND) + message("OpenMP is found!") target_link_libraries(dtwc++ PUBLIC OpenMP::OpenMP_CXX) -endif() \ No newline at end of file +endif() diff --git a/dtwc/Data.hpp b/dtwc/Data.hpp index b6b808a..9ecb596 100644 --- a/dtwc/Data.hpp +++ b/dtwc/Data.hpp @@ -1,9 +1,10 @@ /** - * Data.hpp + * @file Data.hpp * * @brief Encapsulating DTWC data in a class. * - * @author Volkan Kumtepeli, Becky Perriment + * @author Volkan Kumtepeli + * @author Becky Perriment * @date 04 Dec 2022 */ diff --git a/dtwc/DataLoader.hpp b/dtwc/DataLoader.hpp index 7118245..0716bde 100644 --- a/dtwc/DataLoader.hpp +++ b/dtwc/DataLoader.hpp @@ -2,7 +2,8 @@ * @file DataLoader.hpp * @brief Encapsulating DTWC data loading configurations in a class. * Uses method chaining for easier input taking. - * @author Volkan Kumtepeli, Becky Perriment + * @author Volkan Kumtepeli + * @author Becky Perriment * @date 04 Dec 2022 */ diff --git a/dtwc/Problem.cpp b/dtwc/Problem.cpp index a00a8f8..bfdb112 100644 --- a/dtwc/Problem.cpp +++ b/dtwc/Problem.cpp @@ -5,8 +5,9 @@ * @details This file includes the implementation of the Problem class, which contains methods for clustering, * initializing clusters, calculating distances, and other functionalities related to the DTWC problem. * - * @date Created on: 06 Nov 2022 - * @author Volkan Kumtepeli, Becky Perriment + * @date 06 Nov 2022 + * @author Volkan Kumtepeli + * @author Becky Perriment */ #include "Problem.hpp" diff --git a/dtwc/Problem.hpp b/dtwc/Problem.hpp index 16590d6..3d40a1c 100644 --- a/dtwc/Problem.hpp +++ b/dtwc/Problem.hpp @@ -5,8 +5,9 @@ * @details This file contains the definition of the Problem class used in DTWC applications. * It includes various methods for manipulating and analyzing clusters. * - * @date Created on 19 Oct 2022 - * @author Volkan Kumtepeli, Becky Perriment + * @date 19 Oct 2022 + * @author Volkan Kumtepeli + * @author Becky Perriment */ #pragma once diff --git a/dtwc/Problem_IO.cpp b/dtwc/Problem_IO.cpp index 9369ac1..6310e18 100644 --- a/dtwc/Problem_IO.cpp +++ b/dtwc/Problem_IO.cpp @@ -6,7 +6,8 @@ * distance matrices to files, as well as reading distance matrices from files. * * @date 25 Dec 2023 - * @author Volkan Kumtepeli, Becky Perriment + * @author Volkan Kumtepeli + * @author Becky Perriment */ #include "Problem.hpp" @@ -65,7 +66,7 @@ void Problem::printClusters() const std::cout << '\n'; for (const auto i_c : Range(Nc)) { - std::cout << get_name(centroids_ind[i_c]) << " has: "; + std::cout << "The cluster with centroid " << get_name(centroids_ind[i_c]) << " has following members: "; for (const auto i_p : Range(size())) if (clusters_ind[i_p] == i_c) diff --git a/dtwc/dtwc.hpp b/dtwc/dtwc.hpp index e0753d3..eb74dae 100644 --- a/dtwc/dtwc.hpp +++ b/dtwc/dtwc.hpp @@ -1,11 +1,9 @@ -/* - * dtwc.hpp - * - * Main file to include to use DTWC++ library. - * Please only include this file. - * - * Created on: 15 Dec 2021 - * Author(s): Volkan Kumtepeli, Becky Perriment +/** + * @file dtwc.hpp + * @brief Main header to include to use DTWC++ library. Please only include this file. + * @author Volkan Kumtepeli + * @author Becky Perriment + * @date 15 Dec 2021 */ #pragma once diff --git a/dtwc/dtwc_cl.cpp b/dtwc/dtwc_cl.cpp index 3c981f4..7ad4dce 100644 --- a/dtwc/dtwc_cl.cpp +++ b/dtwc/dtwc_cl.cpp @@ -2,11 +2,12 @@ * @file dtwc_cl.cpp * @brief Command line interface for DTWC++ * - * This file contains the implementation of the command line interface for DTWC++. + * @details This file contains the implementation of the command line interface for DTWC++. * It provides a command line interface for users to interact with the DTWC++ library. * * @date 11 Dec 2023 - * @authors Volkan Kumtepeli, Becky Perriment + * @authors Volkan Kumtepeli + * @authors Becky Perriment */ #include "dtwc.hpp" diff --git a/dtwc/enums/Method.hpp b/dtwc/enums/Method.hpp index 74ed55b..1e1faed 100644 --- a/dtwc/enums/Method.hpp +++ b/dtwc/enums/Method.hpp @@ -1,10 +1,9 @@ -/* - * Method.hpp - * - * Method enum for classification method - - * Created on: 11 Dec 2023 - * Author(s): Volkan Kumtepeli, Becky Perriment +/** + * @file Method.hpp + * @brief Method enum for classification method. + * @author Volkan Kumtepeli + * @author Becky Perriment + * @date 11 Dec 2023 */ #pragma once diff --git a/dtwc/enums/Solver.hpp b/dtwc/enums/Solver.hpp index 4813f2d..0631fc2 100644 --- a/dtwc/enums/Solver.hpp +++ b/dtwc/enums/Solver.hpp @@ -1,10 +1,9 @@ -/* - * Solver.hpp - * - * Solver enum for MIP solver selection - - * Created on: 11 Dec 2023 - * Author(s): Volkan Kumtepeli, Becky Perriment +/** + * @file Solver.hpp + * @brief Solver enum for MIP solver selection. + * @author Volkan Kumtepeli + * @author Becky Perriment + * @date 11 Dec 2023 */ #pragma once diff --git a/dtwc/enums/enums.hpp b/dtwc/enums/enums.hpp index da00e35..b6f1ede 100644 --- a/dtwc/enums/enums.hpp +++ b/dtwc/enums/enums.hpp @@ -2,11 +2,12 @@ * @file enums.hpp * @brief Include all enums * - * This header file is used to include all the necessary enums used throughout + * @details This header file is used to include all the necessary enums used throughout * the project. It includes various enum classes like Method, Solver. * * @date 11 Dec 2023 - * @author Volkan Kumtepeli, Becky Perriment + * @author Volkan Kumtepeli + * @author Becky Perriment */ #pragma once diff --git a/dtwc/fileOperations.hpp b/dtwc/fileOperations.hpp index 1a58f35..8b1c384 100644 --- a/dtwc/fileOperations.hpp +++ b/dtwc/fileOperations.hpp @@ -9,7 +9,8 @@ * read specific rows and columns from files, and handle data from directories or batch files. * * @date 21 Jan 2022 - * @author Volkan Kumtepeli, Becky Perriment + * @author Volkan Kumtepeli + * @author Becky Perriment */ #pragma once diff --git a/dtwc/initialisation.cpp b/dtwc/initialisation.cpp index d763581..2081ba4 100644 --- a/dtwc/initialisation.cpp +++ b/dtwc/initialisation.cpp @@ -20,7 +20,8 @@ * are defined elsewhere and are being properly included in this file. * * @date 19 Jan 2021 - * @author Volkan Kumtepeli, Becky Perriment + * @author Volkan Kumtepeli + * @author Becky Perriment */ #include "initialisation.hpp" diff --git a/dtwc/initialisation.hpp b/dtwc/initialisation.hpp index ba6850c..3cefe80 100644 --- a/dtwc/initialisation.hpp +++ b/dtwc/initialisation.hpp @@ -5,7 +5,8 @@ * This file contains the declarations of initialisation functions for the dtwc namespace. * * @date 19 Jan 2021 - * @authors Volkan Kumtepeli, Becky Perriment + * @author Volkan Kumtepeli + * @author Becky Perriment */ #pragma once diff --git a/dtwc/mip/CMakeLists.txt b/dtwc/mip/CMakeLists.txt index 89f3323..08eae7d 100644 --- a/dtwc/mip/CMakeLists.txt +++ b/dtwc/mip/CMakeLists.txt @@ -1,6 +1,9 @@ cmake_minimum_required(VERSION 3.21) add_library(mip-solvers OBJECT) +target_compile_definitions(mip-solvers PUBLIC CURRENT_ROOT_FOLDER="${CURRENT_ROOT_FOLDER}") +target_compile_definitions(mip-solvers PUBLIC DTWC_ROOT_FOLDER="${DTWC_ROOT_FOLDER}") + target_sources(mip-solvers PRIVATE mip_Gurobi.cpp diff --git a/dtwc/mip/mip.hpp b/dtwc/mip/mip.hpp index c92933c..7e552a0 100644 --- a/dtwc/mip/mip.hpp +++ b/dtwc/mip/mip.hpp @@ -1,10 +1,9 @@ -/* - * mip.hpp - * - * Encapsulating mixed-integer program functions in a class. - - * Created on: 06 Nov 2022 - * Author(s): Volkan Kumtepeli, Becky Perriment +/** + * @file mip.hpp + * @brief Collecting mixed-integer program functions. + * @author Volkan Kumtepeli + * @author Becky Perriment + * @date 06 Nov 2022 */ #pragma once diff --git a/dtwc/mip/mip_Gurobi.cpp b/dtwc/mip/mip_Gurobi.cpp index d88e348..0b5fcb3 100644 --- a/dtwc/mip/mip_Gurobi.cpp +++ b/dtwc/mip/mip_Gurobi.cpp @@ -1,11 +1,9 @@ -/* - * mip.cpp - * - * Encapsulating Gurobi-related mixed-integer programming functions in a class. - - * Created on: 25 Dec 2022 - * Author(s): Volkan Kumtepeli, Becky Perriment - * +/** + * @file mip_Gurobi.cpp + * @brief Encapsulating Gurobi-related mixed-integer programming functions in a class. + * @author Volkan Kumtepeli + * @author Becky Perriment + * @date 25 Dec 2022 */ #include "mip.hpp" @@ -19,14 +17,10 @@ #include #include - #ifdef DTWC_ENABLE_GUROBI - #include "gurobi_c++.h" - #endif - namespace dtwc { void MIP_clustering_byGurobi(Problem &prob) { diff --git a/dtwc/mip/mip_Highs.cpp b/dtwc/mip/mip_Highs.cpp index bbb92c0..ce0ca03 100644 --- a/dtwc/mip/mip_Highs.cpp +++ b/dtwc/mip/mip_Highs.cpp @@ -1,10 +1,9 @@ -/* - * mip_Highs.cpp - * - * Encapsulating mixed-integer program functions - - * Created on: 06 Nov 2022 - * Author(s): Volkan Kumtepeli, Becky Perriment +/** + * @file mip_Highs.cpp + * @brief Encapsulating mixed-integer program functions using Highs solver. + * @author Volkan Kumtepeli + * @author Becky Perriment + * @date 06 Nov 2022 */ #include "mip.hpp" diff --git a/dtwc/parallelisation.hpp b/dtwc/parallelisation.hpp index 6eb2d2f..fb8d5ae 100644 --- a/dtwc/parallelisation.hpp +++ b/dtwc/parallelisation.hpp @@ -2,12 +2,13 @@ * @file parallelisation.hpp * @brief Header for parallelisation functions. * - * @details This header file provides functionalities for parallelising tasks using OpenMP. + * @details This header file provides functionalities for parallelising tasks using standard parallelisation. * It includes functions for running individual tasks in parallel and adjusting * the level of parallelism. Functions are templated to support various task types. * * @date 15 Dec 2021 - * @author Volkan Kumtepeli, Becky Perriment + * @author Volkan Kumtepeli + * @author Becky Perriment */ #pragma once diff --git a/dtwc/scores.cpp b/dtwc/scores.cpp index 2d1d418..78bd473 100644 --- a/dtwc/scores.cpp +++ b/dtwc/scores.cpp @@ -8,7 +8,8 @@ * a common method to evaluate the validity of a clustering solution. * * @date 06 Nov 2022 - * @author Volkan Kumtepeli, Becky Perriment + * @author Volkan Kumtepeli + * @author Becky Perriment */ #include "scores.hpp" diff --git a/dtwc/scores.hpp b/dtwc/scores.hpp index cb5d8bd..3678f57 100644 --- a/dtwc/scores.hpp +++ b/dtwc/scores.hpp @@ -2,13 +2,14 @@ * @file scores.hpp * @brief Header file for calculating different types of scores in clustering algorithms. * - * This file contains the declarations of functions used for calculating different types + * @details This file contains the declarations of functions used for calculating different types * of scores, focusing primarily on the silhouette score for clustering analysis. The * silhouette score is a measure of how well an object lies within its cluster and is * a common method to evaluate the validity of a clustering solution. * * @date 06 Nov 2022 - * @author Volkan Kumtepeli, Becky Perriment + * @author Volkan Kumtepeli + * @author Becky Perriment */ #pragma once diff --git a/dtwc/settings.hpp b/dtwc/settings.hpp index e0a4563..380b1bb 100644 --- a/dtwc/settings.hpp +++ b/dtwc/settings.hpp @@ -2,15 +2,20 @@ * @file settings.hpp * @brief This file contains settings and configurations for DTWC++ library. * - * It includes settings for data types, random number generation, filesystem paths, + * @details It includes settings for data types, random number generation, filesystem paths, * debugging options, and default algorithmic settings. * * @date 21 Jan 2022 - * @author Volkan Kumtepeli, Becky Perriment + * @author Volkan Kumtepeli + * @author Becky Perriment */ #pragma once +#ifndef DTWC_ROOT_FOLDER +#define DTWC_ROOT_FOLDER "." +#endif + #include "enums/enums.hpp" #include @@ -45,7 +50,8 @@ namespace fs = std::filesystem; /// @details This path is used to define subdirectories for data and results. /// The root folder path is obtained from the DTWC_ROOT_FOLDER macro /// which leads to the path of the top-level CMakeLists.txt. -const static fs::path root_folder(DTWC_ROOT_FOLDER); +const static fs::path root_folder{ CURRENT_ROOT_FOLDER }; +const static fs::path dtwc_folder{ DTWC_ROOT_FOLDER }; /// @brief Path to the results directory. /// @details Concatenates the root folder path with a subdirectory named "results". @@ -54,6 +60,7 @@ const auto resultsPath = root_folder / "results/"; /// @brief Path to the data directory. /// @details Concatenates the root folder path with a subdirectory named "data". const auto dataPath = root_folder / "data"; +const auto dtwc_dataPath = dtwc_folder / "data"; /// @brief Flag for debug mode for developers. /// @details When set to true, the program may output additional debug information. diff --git a/dtwc/timing.hpp b/dtwc/timing.hpp index 2e6328c..cf42675 100644 --- a/dtwc/timing.hpp +++ b/dtwc/timing.hpp @@ -2,9 +2,10 @@ * @file timing.hpp * @brief Timing functions * - * Contains the definition and implementation of a Clock structure for timing purposes. + * @details Contains the definition and implementation of a Clock structure for timing purposes. * - * @author Volkan Kumtepeli, Becky Perriment + * @author Volkan Kumtepeli + * @author Becky Perriment * @date 01 Mar 2022 */ diff --git a/dtwc/types/Index.hpp b/dtwc/types/Index.hpp index b3ec036..addfe1d 100644 --- a/dtwc/types/Index.hpp +++ b/dtwc/types/Index.hpp @@ -1,10 +1,9 @@ -/* - * Index.hpp - * - * A basic Index class for Range class - * - * Created on: 18 Aug 2022 - * Author: Volkan Kumtepeli +/** + * @file Index.hpp + * @brief A basic Index class for Range class + * @author Volkan Kumtepeli + * @author Becky Perriment + * @date 18 Aug 2022 */ #pragma once diff --git a/dtwc/types/Range.hpp b/dtwc/types/Range.hpp index c20c02a..85ab70d 100644 --- a/dtwc/types/Range.hpp +++ b/dtwc/types/Range.hpp @@ -1,10 +1,8 @@ -/* - * Range.hpp - * - * A basic Range class not to create vector for Iota - * - * Created on: 18 Aug 2022 - * Author: Volkan Kumtepeli +/** + * @file Range.hpp + * @brief A basic Range class not to create vector for Iota + * @author Volkan Kumtepeli + * @date 18 Aug 2022 */ #pragma once diff --git a/dtwc/types/element_types.hpp b/dtwc/types/element_types.hpp index 66cfe82..770d2b7 100644 --- a/dtwc/types/element_types.hpp +++ b/dtwc/types/element_types.hpp @@ -1,13 +1,11 @@ -/* - * element_types.hpp - * - * Helper classes for sparse matrix utilities. - - * Created on: 29 Oct 2023 - * Author(s): Volkan Kumtepeli, Becky Perriment +/** + * @file element_types.hpp + * @brief Helper classes for sparse matrix utilities. + * @author Volkan Kumtepeli + * @author Becky Perriment + * @date 29 Oct 2023 */ - #pragma once #include "types_util.hpp" diff --git a/dtwc/types/types.hpp b/dtwc/types/types.hpp index e91863d..9877402 100644 --- a/dtwc/types/types.hpp +++ b/dtwc/types/types.hpp @@ -1,3 +1,11 @@ +/** + * @file types.hpp + * @brief Header for types folder. + * @author Volkan Kumtepeli + * @author Becky Perriment + * @date 19 Dec 2022 + */ + #pragma once #include "Range.hpp" diff --git a/dtwc/types/types_util.hpp b/dtwc/types/types_util.hpp index 0764aa5..989cbdc 100644 --- a/dtwc/types/types_util.hpp +++ b/dtwc/types/types_util.hpp @@ -1,10 +1,9 @@ -/* - * types_util.hpp - * - * Utility functions for types - - * Created on: 19 Dec 2022 - * Author(s): Volkan Kumtepeli, Becky Perriment +/** + * @file types_util.hpp + * @brief Utility functions for types + * @author Volkan Kumtepeli + * @author Becky Perriment + * @date 19 Dec 2022 */ #pragma once diff --git a/dtwc/utility.hpp b/dtwc/utility.hpp index c16f68b..7befbef 100644 --- a/dtwc/utility.hpp +++ b/dtwc/utility.hpp @@ -2,7 +2,7 @@ * @file utility.hpp * @brief Utility functions and common includes. * - * This file acts as a central inclusion point for commonly used utilities and types + * @details This file acts as a central inclusion point for commonly used utilities and types * in the project. It includes settings, custom types, file operations, parallelization, * and timing functionalities. * diff --git a/dtwc/warping.hpp b/dtwc/warping.hpp index bfd9429..41ecf73 100644 --- a/dtwc/warping.hpp +++ b/dtwc/warping.hpp @@ -2,7 +2,7 @@ * @file warping.hpp * @brief Time warping functions. * - * This file contains functions for dynamic time warping, which is a method to + * @details This file contains functions for dynamic time warping, which is a method to * compare two temporal sequences that may vary in time or speed. It includes * different versions of the algorithm for full, light (L), and banded computations. * @@ -84,7 +84,7 @@ data_t dtwFull_L(const std::vector &x, const std::vector &y) { if (&x == &y) return 0; // If they are the same data then distance is 0. constexpr data_t maxValue = std::numeric_limits::max(); - thread_local std::vector short_side(data_t(10e3)); + thread_local static std::vector short_side(10000); const auto &[short_vec, long_vec] = (x.size() < y.size()) ? std::tie(x, y) : std::tie(y, x); const auto m_short{ short_vec.size() }, m_long{ long_vec.size() }; @@ -105,7 +105,11 @@ data_t dtwFull_L(const std::vector &x, const std::vector &y) short_side[0] += distance(short_vec[0], long_vec[j]); for (size_t i = 1; i < m_short; i++) { - const auto next = std::min({ diag, short_side[i - 1], short_side[i] }) + distance(short_vec[i], long_vec[j]); + const data_t min1 = std::min(short_side[i - 1], short_side[i]); + const auto shr = short_vec.at(i); + const auto lng = long_vec.at(j); + const data_t dist = std::abs(shr - lng); + const data_t next = std::min(diag, min1) + dist; diag = short_side[i]; short_side[i] = next; diff --git a/examples/example_project/CMakeLists.txt b/examples/example_project/CMakeLists.txt new file mode 100644 index 0000000..1b5fa14 --- /dev/null +++ b/examples/example_project/CMakeLists.txt @@ -0,0 +1,20 @@ +cmake_minimum_required(VERSION 3.21) + +project(MY_AWESOME_PROJECT VERSION "0.0.1" + LANGUAGES CXX C) + +set(CMAKE_CXX_STANDARD 17) + +include(CPM.cmake) + +CPMAddPackage( + NAME dtw-cpp + URL "https://github.com/Battery-Intelligence-Lab/dtw-cpp/archive/refs/heads/documentation_update.zip" +) + +add_executable(MY_AWESOME_PROJECT + main.cpp) + +target_link_libraries(MY_AWESOME_PROJECT dtwc++) + +set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}) \ No newline at end of file diff --git a/examples/example_project/CPM.cmake b/examples/example_project/CPM.cmake new file mode 100644 index 0000000..16ff082 --- /dev/null +++ b/examples/example_project/CPM.cmake @@ -0,0 +1,24 @@ +# 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") +elseif(DEFINED ENV{CPM_SOURCE_CACHE}) + set(CPM_DOWNLOAD_LOCATION "$ENV{CPM_SOURCE_CACHE}/cpm/CPM_${CPM_DOWNLOAD_VERSION}.cmake") +else() + set(CPM_DOWNLOAD_LOCATION "${CMAKE_BINARY_DIR}/cmake/CPM_${CPM_DOWNLOAD_VERSION}.cmake") +endif() + +# Expand relative path. This is important if the provided path contains a tilde (~) +get_filename_component(CPM_DOWNLOAD_LOCATION ${CPM_DOWNLOAD_LOCATION} ABSOLUTE) + +file(DOWNLOAD + https://github.com/cpm-cmake/CPM.cmake/releases/download/v${CPM_DOWNLOAD_VERSION}/CPM.cmake + ${CPM_DOWNLOAD_LOCATION} EXPECTED_HASH SHA256=${CPM_HASH_SUM} +) + +include(${CPM_DOWNLOAD_LOCATION}) \ No newline at end of file diff --git a/examples/example_project/main.cpp b/examples/example_project/main.cpp new file mode 100644 index 0000000..8493a03 --- /dev/null +++ b/examples/example_project/main.cpp @@ -0,0 +1,39 @@ +#include "dtwc.hpp" + +int main() +{ + dtwc::Clock clk; // Create a clock object + std::string probName = "DTW_kMeans_results"; + + auto Nc = 3; // Number of clusters + int Ndata_max = 20; // Load maximum 20 of data. + + // For path, we have several predefined variables: + // dtwc::settings::dtwc_folder = source folder of the DTW-C++ library + // dtwc::settings::dtwc_dataPath = data folder inside the source folder of DTW-C++ library. + // dtwc::settings::root_folder = folder with the main CMakeLists.txt, hence your main project folder. + // dtwc::settings::dataPath = data folder inside your main project folder, hence if you have `data` folder inside your main. + + // Here as we use the "dummy" data inside dtwc library, we use `dtwc_dataPath` + dtwc::DataLoader dl{ dtwc::settings::dtwc_dataPath / "dummy", Ndata_max }; + dl.startColumn(1).startRow(1); // Since dummy files are in Pandas format skip first row/column. + + dtwc::Problem prob{ probName, dl }; // Create a problem. + prob.maxIter = 100; + + prob.set_numberOfClusters(Nc); // Nc = number of clusters. + prob.N_repetition = 5; // Repeat the iterative algorithm + + prob.set_solver(dtwc::Solver::HiGHS); // MIP solver type. + prob.band = -1; // Sakoe chiba band length. + + prob.cluster_by_MIP(); + + prob.writeDistanceMatrix(); + + prob.printClusters(); // Prints to screen. + prob.writeClusters(); // Prints to file. + prob.writeSilhouettes(); + + std::cout << "Finished all tasks " << clk << "\n"; +} diff --git a/tests/test_util.hpp b/tests/test_util.hpp index 1e08262..c40e71b 100644 --- a/tests/test_util.hpp +++ b/tests/test_util.hpp @@ -1,9 +1,10 @@ -/* - * test_util.hpp +/** + * @file test_util.hpp + * @brief Auxillary functions for testing * - * Auxillary functions for testing - * Created on: 29 Dec 2023 - * Author(s): Volkan Kumtepeli, Becky Perriment + * @author Volkan Kumtepeli + * @author Becky Perriment + * @date 29 Dec 2023 */ #pragma once diff --git a/tests/unit/unit_test_Clock.cpp b/tests/unit/unit_test_Clock.cpp index 1912bb3..f1133c8 100644 --- a/tests/unit/unit_test_Clock.cpp +++ b/tests/unit/unit_test_Clock.cpp @@ -1,9 +1,10 @@ -/* - * unit_test_Clock.cpp +/** + * @file unit_test_Clock.cpp + * @brief Unit test file for time Clock class * - * Unit test file for time Clock class - * Created on: 16 Dec 2023 - * Author(s): Volkan Kumtepeli, Becky Perriment + * @author Volkan Kumtepeli + * @author Becky Perriment + * @date 16 Dec 2023 */ #include diff --git a/tests/unit/unit_test_Data.cpp b/tests/unit/unit_test_Data.cpp index 6525ca1..ea8e93e 100644 --- a/tests/unit/unit_test_Data.cpp +++ b/tests/unit/unit_test_Data.cpp @@ -1,9 +1,10 @@ -/* - * unit_test_Data.cpp +/** + * @file unit_test_Data.cpp + * @brief Unit test file for Data class * - * Unit test file for time Data class - * Created on: 16 Dec 2023 - * Author(s): Volkan Kumtepeli, Becky Perriment + * @author Volkan Kumtepeli + * @author Becky Perriment + * @date 16 Dec 2023 */ #include diff --git a/tests/unit/unit_test_DataLoader.cpp b/tests/unit/unit_test_DataLoader.cpp index 7412756..4eb1b3f 100644 --- a/tests/unit/unit_test_DataLoader.cpp +++ b/tests/unit/unit_test_DataLoader.cpp @@ -1,9 +1,10 @@ -/* - * unit_test_DataLoader.cpp +/** + * @file unit_test_DataLoader.cpp + * @brief Unit test file for time DataLoader class * - * Unit test file for time DataLoader class - * Created on: 29 Dec 2023 - * Author(s): Volkan Kumtepeli, Becky Perriment + * @author Volkan Kumtepeli + * @author Becky Perriment + * @date 29 Dec 2023 */ #include diff --git a/tests/unit/unit_test_Problem.cpp b/tests/unit/unit_test_Problem.cpp index c9d7cf0..1d56c8a 100644 --- a/tests/unit/unit_test_Problem.cpp +++ b/tests/unit/unit_test_Problem.cpp @@ -1,9 +1,10 @@ -/* - * unit_test_warping.cpp +/** + * @file unit_test_Problem.cpp + * @brief Unit test file for Problem class * - * Unit test file for time warping functions - * Created on: 03 Dec 2023 - * Author(s): Volkan Kumtepeli, Becky Perriment + * @author Volkan Kumtepeli + * @author Becky Perriment + * @date 03 Dec 2023 */ #include diff --git a/tests/unit/unit_test_fileOperations.cpp b/tests/unit/unit_test_fileOperations.cpp index b6ca31d..69b8dea 100644 --- a/tests/unit/unit_test_fileOperations.cpp +++ b/tests/unit/unit_test_fileOperations.cpp @@ -1,9 +1,10 @@ -/* - * unit_test_fileOperations.cpp +/** + * @file unit_test_fileOperations.cpp + * @brief Unit test file for file reading functions * - * Unit test file for file reading functions - * Created on: 25 Dec 2023 - * Author(s): Volkan Kumtepeli, Becky Perriment + * @author Volkan Kumtepeli + * @author Becky Perriment + * @date 25 Dec 2023 */ #include diff --git a/tests/unit/unit_test_parallelisation.cpp b/tests/unit/unit_test_parallelisation.cpp index 0dcf252..94522b0 100644 --- a/tests/unit/unit_test_parallelisation.cpp +++ b/tests/unit/unit_test_parallelisation.cpp @@ -1,9 +1,10 @@ -/* - * unit_test_parallelisation.cpp +/** + * @file unit_test_parallelisation.cpp + * @brief Unit test file for parallelisation functions * - * Unit test file for parallelisation functions - * Created on: 16 Dec 2023 - * Author(s): Volkan Kumtepeli, Becky Perriment + * @author Volkan Kumtepeli + * @author Becky Perriment + * @date 16 Dec 2023 */ #include diff --git a/tests/unit/unit_test_warping.cpp b/tests/unit/unit_test_warping.cpp index ed95094..e9e3723 100644 --- a/tests/unit/unit_test_warping.cpp +++ b/tests/unit/unit_test_warping.cpp @@ -1,9 +1,10 @@ -/* - * unit_test_warping.cpp +/** + * @file unit_test_warping.cpp + * @brief Unit test file for time warping functions * - * Unit test file for time warping functions - * Created on: 03 Dec 2023 - * Author(s): Volkan Kumtepeli, Becky Perriment + * @author Volkan Kumtepeli + * @author Becky Perriment + * @date 03 Dec 2023 */ #include