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 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
A suitable compiler (Clang, GCC, MSVC, etc.)
Gurobi (optional, if not installed then HiGHS will be used as the MIP solver)
OpenMP 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 as an open source MIP solver alternative to Gurobi.
CLI11 (for command line interface)
Catch2 (for testing)
Armadillo (for matrix reading)

CMake and compilers

CMake 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, macOS, Windows, and further information

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) and CMake 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 for Ubuntu versions 18.04 or below.

Install the essential libraries for building the project

 sudo apt update
 sudo apt install -y build-essential cmake-extras cmake
  

Clone the repository using the following command or download it as a *.zip file:
```
 git clone https://github.com/battery-intelligence-lab/dtw-cpp.git
```

After downloading the source files, you need to create a build folder and go into the build folder:

 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. 
  

Then, create Makefiles by running:
```
 cmake -G "Unix Makefiles" .. 
```
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.
```
 cmake --build . -j4 --config Release
```
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
```
 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.

macOS

Install the latest version of Xcode.

Install command line tools, Homebrew and CMake by executing following commands on the terminal:

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
  

Clone the repository using the following command or download it as a *.zip file:
```
 git clone https://github.com/battery-intelligence-lab/dtw-cpp.git
```

After downloading the source files, you need to create a build folder and go into the build folder:

 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. 
  

Then, create Makefiles by running:
```
 cmake .. 
```
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.
```
 cmake --build . -j4 --config Release
```
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
```
 cd ../bin
 ./dtwc_main # to run the code in main.cpp
 ./dtwc_cl # to run the command line interface
```

Note

Windows

On Windows platforms, you probably need to install CMake and a C++ compiler:

Install the latest version of the CMake binary.
You can then install a compiler of your choice. We suggest installing MVSC and/or Clang via Visual Studio 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 then run choco install mingw command.
Download the repository as a *.zip file, or if you have git installed you may run the following command in the git bash:
```
 git clone https://github.com/battery-intelligence-lab/dtw-cpp.git
```

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:

 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. 
  

Then, create compilation files by running:

 cmake -G "MinGW Makefiles" .. # if you use MinGW GCC compiler.
 cmake -G "Visual Studio 16 2019" ..  # if you use Visual Studio's compiler.
  

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.
```
 cmake --build . -j4 --config Release
```
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
```
 cd ../bin
 ./dtwc_main # to run the code in main.cpp
 ./dtwc_cl # to run the command line interface
```

Note

If you are using Visual Studio Community, you may also open the folder in Visual Studio directly, without using CMake. See this page 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:

Download and install Visual Studio Code
Install CMake and a suitable compiler and download using the above guidelines for our operating system.
Download the DTW-C++ code using git or zip.
Open VScode and install extensions C/C++ Extension Pack and CMake Tools.
Open the dtw-cpp folder with the VScode.
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).
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