Installation#

Requirements#

Python ≥ 3.9
PyTorch ≥ 2.0 (the active backend; TensorFlow and NumPy backends are no longer maintained)
healpy — HEALPix Python bindings
NumPy
SciPy
Matplotlib

Install from PyPI#

The simplest path:

pip install foscat

Full environment (recommended for notebooks)#

For running the example notebooks from demo-foscat-pangeo-eosc:

micromamba / conda

micromamba create -n foscat python=3.10
micromamba activate foscat
pip install foscat
pip install torch healpy xarray gcsfs zarr jupyterlab matplotlib scipy

pip only

python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install foscat torch healpy xarray zarr jupyterlab matplotlib scipy

GPU support#

FOSCAT’s synthesis loop and neural-network modules run on GPU automatically when PyTorch detects a CUDA-capable device. Install PyTorch with CUDA support first:

# CUDA 12.1
pip install torch --index-url https://download.pytorch.org/whl/cu121

# CUDA 11.8
pip install torch --index-url https://download.pytorch.org/whl/cu118

When instantiating a FoCUS operator you can select the GPU with gpupos:

import foscat.scat_cov as sc

# Use GPU 0 (default)
scat_op = sc.funct(KERNELSZ=5, NORIENT=4, gpupos=0)

# Use GPU 1 in a multi-GPU node
scat_op = sc.funct(KERNELSZ=5, NORIENT=4, gpupos=1)

MPI-parallel synthesis#

For distributed HPC jobs with mpi4py:

pip install mpi4py
mpirun -n 4 python my_synthesis_script.py

Pass isMPI=True to FoCUS:

scat_op = sc.funct(KERNELSZ=5, NORIENT=4, isMPI=True)

Install from source (development)#

git clone https://github.com/jmdelouis/FOSCAT.git
cd FOSCAT
pip install -e .

Verify the installation#

import foscat.scat_cov as sc
import numpy as np

nside = 16
x = np.random.randn(12 * nside**2)
op = sc.funct(KERNELSZ=3, NORIENT=4, nstep_max=2, silent=True)
stat = op.eval(x)
print("FOSCAT installed successfully. Descriptor size:", stat.numel)

FOSCAT data cache#

The first time you instantiate FoCUS at a given (nside, KERNELSZ, NORIENT) combination, it computes and stores wavelet stencil tables in ~/.FOSCAT/data/. Subsequent instantiations load from cache. Ensure that directory is writable (or pass a custom path via TEMPLATE_PATH).