macOS Installation Guide

Note

While GPU acceleration via CUDA is not supported on macOS, METADA can still be used with CPU computations or alternative GPU computing solutions.

Prerequisites

Homebrew package manager
Development tools and libraries

Installing Dependencies

Install GFortran and core dependencies:

brew update
# Install gfortran from gcc
brew install gcc@13

# Install other dependencies
brew install \
  cmake@3.30: \
  ninja \
  python \
  numpy \
  googletest \
  llvm \
  lcov \
  yaml-cpp \
  nlohmann-json

Install ng-log from source:

git clone --depth 1 https://github.com/ng-log/ng-log.git
cd ng-log
mkdir build && cd build
cmake .. -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local
ninja
ninja install
cd ../..

Building METADA

Configure the project:

mkdir build
cd build
GFORTRAN_PATH=$(brew --prefix gcc@13)/bin/gfortran-13
cmake -G Ninja \
  -DCMAKE_BUILD_TYPE=Debug \
  -DCMAKE_C_COMPILER=clang \
  -DCMAKE_CXX_COMPILER=clang++ \
  -DCMAKE_CXX_STANDARD=17 \
  -DCMAKE_Fortran_COMPILER=${GFORTRAN_PATH} \
  ..

Build the project:
```
cmake --build .
```

Running Tests

Execute the test suite:

cd build
ctest --output-on-failure

Alternative 1: Using Remote Development

This approach involves developing on macOS but building and running on a remote Linux machine with GPU support.

Prerequisites

Remote Linux machine with NVIDIA GPU (for GPU acceleration)
VS Code on your macOS system
SSH access to the remote machine

Setup Instructions

Install VS Code on macOS
Install the “Remote - SSH” extension
Configure SSH connection to your remote machine
Set up the remote environment:
1. Install required packages on remote machine:
```
sudo apt update
sudo apt install build-essential cmake ninja-build python3 python3-pip
```
2. Install CUDA Toolkit on remote machine (see Linux Installation Guide)
3. Configure VS Code Remote SSH: - Press Cmd+Shift+P - Select “Remote-SSH: Connect to Host” - Enter your SSH connection details

Clone and build on remote machine:

git clone https://github.com/your-org/metada.git
cd metada
cmake -S . -B build
cmake --build build -j$(nproc)

Alternative 2: Using Docker Containers

This approach uses NVIDIA Docker containers for CUDA development.

Prerequisites

Docker Desktop for macOS
Remote machine with NVIDIA GPU (for running containers)

Setup Instructions

Install Docker Desktop for macOS

Set up remote Docker context:

# Create context for remote machine
docker context create remote --docker "host=ssh://user@remote-host"
# Switch to remote context
docker context use remote

Configure remote machine:
1. Install NVIDIA Container Toolkit on remote host
2. Configure Docker daemon for NVIDIA runtime
3. Verify GPU access:
```
docker run --gpus all nvidia/cuda:12.1.0-base nvidia-smi
```
Development workflow:
1. Use VS Code with Remote-Containers extension
2. Open project in container using provided devcontainer configuration
3. Build and run as specified in container documentation

Alternative 3: Using Cloud Services

This approach leverages cloud GPU instances for development.

Available Options

Google Colab
AWS SageMaker
Azure ML Studio

Setup Instructions

Google Colab
1. Upload project notebooks to Google Drive
2. Configure GPU runtime: - Runtime → Change runtime type → GPU
3. Install required packages:
```
!pip install cmake ninja
!git clone https://github.com/your-org/metada.git
```
AWS SageMaker
1. Launch SageMaker notebook instance with GPU
2. Choose ML instance type with NVIDIA GPU
3. Use provided container image or custom container
4. Configure Git repository integration
Azure ML Studio
1. Create compute instance with GPU
2. Use provided Jupyter notebooks
3. Configure development environment: - Install required extensions - Set up Git integration - Configure GPU compute targets