Eidos is a project for educational purpose to build an entire deep learning library from scratch in C++. It implemented MLP, CNN, RNN and helper utilities (e.g. data loader) using only Eigen for parallelized linear algebra.

The goal is to understand the underlying concepts of these models and how they work. The project is inspired by the libtorch, PyTorch's C++ frontend. We aim to provide a similar API interface to PyTorch and Keras for ease of use. We achieved similar performance with PyTorch on simple datasets such as MNIST.

DISCLAIMER: The models are not optimized for performance like PyTorch or libtorch. Thus, it will take (considerably) longer to train on large datasets. Please do not use the library for production.

The library is built using CMake and requires Eigen3. Eigen is a C++ template library for parallelized linear algebra: matrices, vectors, numerical solvers, and related algorithms.

• You can install Eigen3 using your package manager or download it from the official website.

• You can install cmake using your package manager or download it from the official website.

The following method will compile and install the library to your local path and allows you to use the library.

First, clone the repository from GitHub. Then follow these steps:

mkdir build && cd build
cmake .. && make
sudo make install

We support building from scratch on Windows using Microsoft Visual Studio (MSVC) and CMake.

1. After cloninig the repository, generate the Visual Studio solution and project files

mkdir build && cd build
cmake ..

2. Once the project files are generated, open the eidos.sln file in Visual Studio:

.\eidos.sln

3. Select the desired build configuration (Release/Debug) and build the solution.

4. After building, the static library (.lib file) will be available in the build\release or build\debug directory.

Alternatively, if you use the Developer Command Prompt:

msbuild eidos.sln /p:Configuration=Release

You can now link your projects to this .lib file.

Pre-built binaries are supported for MacOS, Linux and Windows. You can download the binaries from the releases page

After downloading the tarball, extract it to your desired location:

# For Linux and MacOS
tar -xzvf Eidos.tar.gz -C /desired/location/

# For Windows
unzip Eidos.zip -d C:\desired\location\

Add the library to your path:

# For Linux and MacOS
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/desired/location/lib

# For Windows
setx PATH "%PATH%;C:\desired\location\lib"

In your source code, include the main header #include <Eidos/Eidos.h>. Compile your source file by either:

1. Manual linking with compiler (clang++, g++) such as g++ main.cpp -I/path/to/installed/Eidos -I/path/to/Eigen -L/path/to/installed/lib -lEidos, and on MSVC follow this stackoverflow post

2. Recommended: use cmake's find_package(Eidos REQUIERD). A sample is provided in demo/CMakeLists.txt

This project uses Google Test for unit testing. The unit tests contained in tests/ are basic and more like sanity checks. You do not need to install the library to run UTs. To run the tests, follow these steps:

cd tests && mkdir build && cd build
cmake .. && make
ctest # or ./run_tests

Usage of our library is extremely similar to PyTorch and Keras to make it easy for python ML practioneres. A very simple example for a MLP is shown below:

#include <Eidos/Eidos.h>

int main() {

    // Create a label map for the data loader
    std::map<std::string, int> label_map;
    for (int i = 0; i < 10; ++i) {
        label_map[std::to_string(i)] = i;
    }

    // Load data and split into training and testing
    auto data = NumericDataLoader("mnist_train.csv", "label", label_map).train_test_split(0.8, 32);

    // Create model and add fully connected layers
    Model model;
    model.Add(new DenseLayer(784, 128));
    model.Add(new ReLU());
    model.Add(new DenseLayer(128, 10));

    // Create optimizer and loss function
    Adam optimizer(0.001);
    CrossEntropyLoss loss_fn;

    // Train and test the model using convenience API
    model.Train(data.training.inputs, data.training.targets, 5, &optimizer, &loss_fn);
    model.Test(data.testing.inputs, data.testing.targets, &loss_fn);

    // Save the model
    model.Serialize("myModel.bin");
}

You should consult the full documentation in docs/ and sample code in demo/ for more powerful features such as CNN, RNN, regularisation, custom training loops, data preprocessing, etc. You can check out docs/experiments.md to explore ways to experiment with different dataset with Eidos.

If understanding and true opinion are distinct, then these ‘by themselves’ things definitely exist – these Forms (Eidos), the objects not of our sense perception, but of understanding only. (Plato, Timaeus, 51d)

"Eidos", a Greek word meaning "form" or "essence", is derived from Plato's Theory of the Forms, representing our pursuit of understanding the essential principles underlying machine learning. Just as forms in Plato’s philosophy are timeless, absolute truths behind the imperfect representations of the physical world, deep learning methods allow us to discern patterns and insights from complex data, transcending the mutable and flawed representations we observe. Our library, crafted from scratch as an educational journey, embodies this philosophical aspiration: not just to create, but to learn and uncover the foundational truths of AI.

We welcome contributions to the project. Please refer to the CONTRIBUTING.md for more information.

Jet Chiang, James Zheng

Feel free to contact us at our LinkedIn profiles for any questions or feedback.