This repository contains an example of using the Rust implementation of PaCMAP (Pairwise Controlled Manifold Approximation), a dimensionality reduction and visualization algorithm. This example demonstrates how to reduce the MNIST digits dataset from 784 dimensions to 2D and create an interactive visualization.

You'll need:

• Rust toolchain (1.70 or later)
• GCC 13 or later (required for compiling dependencies)
• An internet connection (for downloading Rust and the MNIST dataset)
• Basic familiarity with command line operations

This project requires GCC 13 or later due to dependency requirements. For Ubuntu, upgrade to 24.04. On Debian:

# Add testing repo
echo "deb http://deb.debian.org/debian testing main" | sudo tee /etc/apt/sources.list.d/testing.list
sudo apt-get update

# Install GCC 13
sudo apt-get install gcc-13 g++-13

# Set as default compiler
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-13 60 \
  --slave /usr/bin/g++ g++ /usr/bin/g++-13 \
  --slave /usr/bin/gcov gcov /usr/bin/gcov-13

# Set environment variables
export CC=/usr/bin/gcc-13
export CXX=/usr/bin/g++-13

On other distributions, please consult your package manager's documentation.

1. Clone this repository:

git clone https://github.com/beamform/pacmap-rs-example
cd pacmap-rs-example

2. Install Rust using the provided Makefile:

make install

After installation, you'll need to either restart your terminal or run:

source $HOME/.cargo/env

The project includes a Makefile with several helpful commands:

• Build the project in development mode:

make build

• Build the project in release mode (recommended for better performance):

make build-release

• Run the example (will build in release mode):

make run

If you prefer to run the example using Docker, you don't need to install Rust or GCC locally. Simply ensure you have Docker installed on your system.

1. Build the Docker image:

make docker-build

2. Run the example in a container:

make docker-run

Or do both steps at once:

make docker-all

The visualization file pacmap_visualization.html will be created in your current directory.

To clean up the Docker image when you're done:

make docker-clean

When you run the example:

1. It downloads the MNIST digits dataset (70,000 images)
2. Applies PaCMAP dimensionality reduction to reduce from 784 dimensions to 2D
3. Creates an interactive visualization saved as pacmap_visualization.html

The visualization will show the MNIST digits dataset reduced to 2D, with points colored by their digit class (0-9).

• src/main.rs - The main example code
• Cargo.toml - Project dependencies and configuration
• Dockerfile - Container configuration
• Makefile - Build and run commands

To remove build artifacts:

make clean

If you encounter any issues:

1. Make sure you have GCC 13 or later installed and set as the default compiler
2. Verify Rust is installed correctly with rustc --version
3. Ensure you have an internet connection for downloading the MNIST dataset
4. Try cleaning and rebuilding: make clean && make build-release

The project uses different BLAS/LAPACK backends depending on the platform:

• macOS: Accelerate Framework
• Windows: system provided Intel MKL
• Linux: system provided OpenBLAS

To use a different backend, modify Cargo.toml and change the pacmap dependency to specify your preferred backend. Available features are:

# Intel MKL options:
pacmap = { version = "0.2", features = ["intel-mkl-static"] }  # Statically linked
pacmap = { version = "0.2", features = ["intel-mkl-system"] }  # System provided

# OpenBLAS options:
pacmap = { version = "0.2", features = ["openblas-static"] }   # Statically linked
pacmap = { version = "0.2", features = ["openblas-system"] }   # System provided

# Netlib options:
pacmap = { version = "0.2", features = ["netlib-static"] }     # Statically linked
pacmap = { version = "0.2", features = ["netlib-system"] }     # System provided

• Rust PaCMAP Documentation
• Original PaCMAP Library
• Original PaCMAP Paper
• MNIST Dataset
• Rust Programming Language
• Rust Book
• Cargo Book

Apache License, Version 2.0