Skip to content

Installation

CDTS is designed to be easy to install and run across different environments.

Standard Installation

The easiest way to install CDTS is via Python's package manager, pip. We provide pre-compiled binaries (wheels) for Windows, macOS, and Linux, supporting Python 3.9 and newer. Because we distribute pre-compiled binaries, you do not need a C++ compiler installed on your machine for the standard installation.

pip install cdts

This command automatically installs all required Python dependencies, including xarray, dask, scikit-learn, rasterio, torch, and pystac-client.

macOS: Apple Silicon vs. Intel

Prebuilt wheels are published for whichever architecture GitHub Actions' macos-latest runner uses at build time, which is Apple Silicon (arm64) as of this writing. If pip install cdts on an Intel Mac reports no matching distribution, pip will fall back to building from source automatically — see Installing from Source below for the compiler prerequisites that requires.

Verifying the Installation

Once installed, confirm the package and its CLI are working:

python -c "from importlib.metadata import version; print(version('cdts'))"
cdts --help

Optional Dependencies

For development and running tests, you can install the optional development dependencies:

pip install cdts[dev]

Installing from Source

If you need to modify the C++ backend, use the latest unreleased features, or build the package on an unsupported architecture, you will need to install CDTS from the source.

Requirements

  • Python 3.9+
  • A C++ Compiler supporting C++17 (GCC, Clang, or MSVC)
  • macOS only: the Xcode Command Line Tools provide the Clang compiler used to build the extension. Install them first if you haven't already: 
    xcode-select --install

Instructions

  1. Clone the repository from GitHub: 

    git clone https://github.com/sacridini/cdts.git
cd cdts

  2. Install the package in editable mode: 

    pip install -e .

This process will invoke pybind11 and your system's C++ compiler to build the core statistical engines (src/main.cpp, src/landtrendr.cpp, src/ccdc.cpp) and link them with the Eigen3 library.

Enabling OpenMP on macOS (Apple Silicon & Intel)

By default, the Apple Clang compiler does not include native support for OpenMP. As a result, when installing via standard Wheels or basic source installation, CDTS falls back to single-threaded mode for its C++ mathematical operations on macOS. (Note: Dask still parallelizes effectively at the chunk level).

If you want the maximum possible performance out of the C++ core on macOS, you can enable OpenMP by installing it via Homebrew and compiling CDTS from source:

  1. Install the libomp library using Homebrew: 

    brew install libomp

  2. Point the compiler and linker at Homebrew's libomp — setup.py's OpenMP detection compiles a test snippet against <omp.h>, which it won't find unless these are set, since Homebrew doesn't add libomp to the default include/lib search paths (it's keg-only): 

    export CFLAGS="-I$(brew --prefix libomp)/include"
export CXXFLAGS="-I$(brew --prefix libomp)/include"
export LDFLAGS="-L$(brew --prefix libomp)/lib -lomp"

  3. With those exported in the same shell, install CDTS from source. setup.py will now detect libomp and compile with OpenMP support: 

    pip install --no-binary cdts cdts
# or, if cloning from GitHub: pip install -e .

OpenMP on Windows and Linux

Unlike macOS, Windows (MSVC) and Linux (GCC) ship with native OpenMP support, so no extra steps are needed — setup.py enables it automatically for both a standard pip install cdts (wheel) and a source install.

GPU Acceleration for cdts.ai

The deep learning models in cdts.ai (UTAE, LTAE/LightTAE, TempCNN, Siamese Change Detector, GeoFoundationViT) are plain PyTorch nn.Modules and run on whatever device you move them to — none of them hard-code CUDA.

  • NVIDIA GPUs (Linux/Windows): the standard pip install cdts installs a torch build with CUDA support where available. Use torch.device("cuda") as usual.
  • Apple Silicon (any M-series chip): PyTorch's Metal (mps) backend gives you native GPU acceleration on macOS — no CUDA or extra install needed, since it ships in the same torch package: 
    device = torch.device("mps" if torch.backends.mps.is_available() else "cpu")
model = model.to(device)
    Every tutorial in AI & Deep Learning picks "cuda" vs. "cpu" in its example — swap in the snippet above on macOS to use the GPU.
  • CPU fallback: works everywhere, just slower.

Docker and MPS

The Docker image is built on a CUDA base image and has no access to Apple's Metal APIs. To use mps acceleration on macOS, install CDTS natively with pip rather than through Docker.