This repository contains the code used for the manuscript Topological Autoencoders++: Fast and Accurate Cycle-Aware Dimensionality Reduction (to be published in IEEE TVCG).

The method was integrated into The Topology ToolKit. See this example.

You can choose either the scripted or step-by-step installation method.

The following script was tested on a fresh installation of Ubuntu 24.04 in a VirtualBox VM. If you want to install on your own system, you probably should follow the step-by-step installation.

If you are not using Python 3.12 (e.g., if you use an older version of Ubuntu in your VM), change the occurrences of python3.12 in install.sh by the version you are using.

Go to the root of this repository and run the install.sh script:

chmod +x install.sh
. ./install.sh

Change by install+CUDA.sh if you own a CUDA-compatible device and want to use it (this is not required); however in this case you need to install CUDA drivers beforehand.

The script will download all dependencies and compile both ParaView and TTK, which can take a while.

1. Install dependencies. On Ubuntu:

   sudo apt install -y cmake ninja-build libboost-system-dev libopengl-dev libxcursor-dev
   sudo apt install -y qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools qttools5-dev qtxmlpatterns5-dev-tools libqt5x11extras5-dev libqt5svg5-dev qttools5-dev libqt5x11extras5-dev libqt5svg5-dev qtxmlpatterns5-dev-tools 
   sudo apt install -y libcgal-dev
   sudo apt install -y python3-sklearn python3-pip
   sudo apt install -y git
   

   To enable the comparison with UMAP (and PCA, MDS, Isomap, t-SNE), install it:

   pip install umap-learn
   

2. Download Torch

   Go to the root of this repository. Choose a version of LibTorch to download on https://pytorch.org/get-started/locally/. If you own a CUDA-compatible device and want to use it, download a CUDA version. Otherwise, download the CPU version. Note that the experiments reported in the manuscript were done with LibTorch 2.4.0 and CUDA 12.1.

   Example for the CPU version:

   wget https://download.pytorch.org/libtorch/cpu/libtorch-cxx11-abi-shared-with-deps-2.4.0%2Bcpu.zip
   unzip libtorch-cxx11-abi-shared-with-deps-2.4.0%2Bcpu.zip
   rm libtorch-cxx11-abi-shared-with-deps-2.4.0%2Bcpu.zip
   

   Example for the CUDA version:

   wget https://download.pytorch.org/libtorch/cu121/libtorch-cxx11-abi-shared-with-deps-2.4.0%2Bcu121.zip
   unzip libtorch-cxx11-abi-shared-with-deps-2.4.0+cu121.zip
   rm libtorch-cxx11-abi-shared-with-deps-2.4.0+cu121.zip
   

3. Install ParaView

   git clone https://github.com/topology-tool-kit/ttk-paraview.git
   cd ttk-paraview
   git checkout 5.13.0
   mkdir build
   cd build
   cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DPARAVIEW_USE_PYTHON=ON -DPARAVIEW_INSTALL_DEVELOPMENT_FILES=ON -DCMAKE_INSTALL_PREFIX=../install ..
   ninja install
   

   Set the following environment variable (replace 3.12 by your version of Python).

   PV_PREFIX=`pwd`/../install
   export PATH=$PATH:$PV_PREFIX/bin
   export LD_LIBRARY_PATH=$PV_PREFIX/lib:$LD_LIBRARY_PATH
   export PYTHONPATH=$PYTHONPATH:$PV_PREFIX/lib/python3.12/site-packages
   

4. Install TTK

   cd ../../ttk-tcdr
   mkdir build
   cd build
   paraviewPath=`pwd`/../../ttk-paraview/install/lib/cmake/paraview-5.13
   torchPath=`pwd`/../../libtorch/share/cmake/Torch/
   cmake -G Ninja -DCMAKE_INSTALL_PREFIX=../install -DParaView_DIR=$paraviewPath -DTorch_DIR=$torchPath ..
   ninja install
   

   Set the following environment variable (replace 3.12 by your version of Python).

   TTK_PREFIX=`pwd`/../install
   export PV_PLUGIN_PATH=$TTK_PREFIX/bin/plugins/TopologyToolKit
   export LD_LIBRARY_PATH=$TTK_PREFIX/lib:$LD_LIBRARY_PATH
   export PYTHONPATH=$PYTHONPATH:$TTK_PREFIX/lib/python3.12/site-packages
   

1. You can run a ParaView state with:

   paraview states/SingleCell.pvsm
   

2. To reproduce the comparison tables in the manuscript (figures 1, 13 and 14), run:

   python3 scripts/runComparison.py
   

   You can specify the files to run with the option -f or --files and the methods to compare with the option -m or --methods, for example:

   python3 scripts/runComparison.py -f COIL20-1 MoCap SingleCell -m TopoAE TopoAE++
   

   The file names to use are 3Clusters, Twist, K4, K5, COIL20-1, MoCap and SingleCell and the available methods are listed below:

   Method name to use	Implementation
   PCA	scikit-learn
   MDS	scikit-learn
   Isomap	scikit-learn
   LLE	scikit-learn
   tSNE	scikit-learn
   UMAP	umap-learn
   TopoMap	TTK
   TopoAE	TTK
   TopoAE+W1	TTK
   TopoAE++	TTK

   This script will save:

   • 2D renders of the projections of the different methods in scripts_results/figures
   • the projections themselves in scripts_results/data
   • a CSV file containing quality indicators in scripts_results/metrics.csv

Please note that TopoAE-based methods are non-deterministic. Therefore, the resulting projections and quality indicators may differ from those presented in the paper.