From be05aecd6c2843f2b5f5521bd0a90d86c6ff83d5 Mon Sep 17 00:00:00 2001 From: Volkan Kumtepeli Date: Fri, 16 Aug 2024 04:43:29 +0100 Subject: [PATCH] Update installation documents --- docs/1_getting_started/1_installation.md | 148 +++++++++++++++--- docs/1_getting_started/{cli.md => 2_cli.md} | 4 +- ...{supported_data.md => 3_supported_data.md} | 0 .../{examples.md => 4_examples.md} | 5 +- docs/1_getting_started/dependencies.md | 61 -------- docs/1_getting_started/direct_use.md | 15 -- docs/1_getting_started/index.md | 10 +- 7 files changed, 135 insertions(+), 108 deletions(-) rename docs/1_getting_started/{cli.md => 2_cli.md} (99%) rename docs/1_getting_started/{supported_data.md => 3_supported_data.md} (100%) rename docs/1_getting_started/{examples.md => 4_examples.md} (96%) delete mode 100644 docs/1_getting_started/dependencies.md delete mode 100644 docs/1_getting_started/direct_use.md diff --git a/docs/1_getting_started/1_installation.md b/docs/1_getting_started/1_installation.md index e06fd5a..0871c51 100644 --- a/docs/1_getting_started/1_installation.md +++ b/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) \ 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 99% rename from docs/1_getting_started/cli.md rename to docs/1_getting_started/2_cli.md index 1a302a6..08f75e6 100644 --- a/docs/1_getting_started/cli.md +++ b/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 ``` 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 123653f..0000000 --- a/docs/1_getting_started/dependencies.md +++ /dev/null @@ -1,61 +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 -- 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 1f1a7e0..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](1_installation.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).