Conatus

Try: Floquet, Orszag, checkpoints, resume_or_start, h5py

    Install

    Install

    Conatus 0.1.1 installs with pip from a binary wheel, with its compiled core inside: no compiler needed. The CPU wheel is on PyPI; a CUDA 12 wheel for NVIDIA GPUs, in beta, is attached to the GitHub release. It also builds from source.

    Requirements

    System
    Linux x86-64. Python 3.11, 3.12 or 3.13: 3.12 runs the whole test suite; on all three the wheel installs, imports, solves a problem and passes doctor in a clean manylinux_2_28 image; 3.12 is recommended. A newer Python is refused until it is tested.
    Python dependencies
    NumPy ≥ 1.26, SciPy ≥ 1.11, SymPy ≥ 1.12, h5py ≥ 3.8, installed by pip; matplotlib ≥ 3.7 with the tutorials extra.
    Wheels
    Linux x86-64 with glibc 2.28 or newer (RHEL 8, Ubuntu 20.04 and later). The CUDA wheel needs an NVIDIA driver for CUDA 12.9 (≥ 575, or an older 12.x driver through minor-version compatibility); it pulls the CUDA runtime, cuFFT and cuBLAS as pip wheels (about 700 MB). Built for A100 (sm_80) and L40S (sm_89); beta.
    Build tools (from source)
    A C++20 compiler (GCC 13 from conda-forge), CMake ≥ 3.24, scikit-build-core and nanobind (fetched by pip).
    LAPACK, BLAS
    From conda-forge, in the active environment; the build looks nowhere else, so you always know which libraries you use. The core has no FFT library of its own: CPU transforms are NumPy/SciPy, GPU transforms cuFFT.
    GPU (optional)
    An NVIDIA GPU; to build from source, the CUDA 12 toolkit (nvcc, cuFFT, cuBLAS) from conda-forge.

    Install with pip

    CPU

    $ python3.12 -m venv venv && . venv/bin/activate
$ pip install "conatus[tutorials]==0.1.1"     # CPU wheel from PyPI + matplotlib, xarray for the tutorials
$ python -m conatus doctor                   # what this machine can run

    GPU (CUDA 12, beta)

    # the CUDA wheel of the GitHub release (here for Python 3.12; cp311 and cp313 exist too)
$ python3.12 -m venv venv && . venv/bin/activate
$ pip install "conatus[gpu,tutorials] @ https://github.com/rubendahan/conatus/releases/download/v0.1.1/conatus-0.1.1+cu12-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl"
$ python -m conatus doctor                   # on a GPU node: "GPU (backend='cuda')": ok

    Install from source

    CPU

    1. Create a conda environment with the compiled dependencies

      # LAPACK and BLAS come from the active conda env only (no system fallback)
$ micromamba create -n conatus -c conda-forge python=3.12 gxx_linux-64=13 liblapack libblas
$ micromamba activate conatus

    2. Build and install

      pip install ".[tutorials]" compiles the C++20 core (conatus._core, via scikit-build-core, CMake and nanobind), installs it inside the package with its dependencies (h5py included: outputs and checkpoints) and adds matplotlib, which the tutorials use for their figures. pip install . alone skips matplotlib.

      $ git clone --branch v0.1.1 https://github.com/rubendahan/conatus && cd conatus
$ pip install ".[tutorials]"                      # CPU (the default) + matplotlib for the tutorials

    3. Check

      See Check your installation below.

    GPU (CUDA)

    1. Start from the CPU environment and add the CUDA toolkit

      # in the same env: nvcc, cuFFT, cuBLAS and CuPy from conda-forge (CUDA 12.9 tested)
$ micromamba install -c conda-forge cuda-version=12.9 cuda-nvcc cuda-cudart-dev libcufft-dev libcublas-dev cupy-core

    2. Build with the CUDA backend

      The CUDA backend is switched on at build time. CuPy comes from conda here: do not add the gpuextra, which would install a second CuPy from pip.

      $ pip install . -Ccmake.define.CONATUS_CUDA=ON \
      -Ccmake.define.CMAKE_CUDA_COMPILER=$CONDA_PREFIX/bin/nvcc \
      -Ccmake.define.CMAKE_CUDA_HOST_COMPILER=$CONDA_PREFIX/bin/x86_64-conda-linux-gnu-g++ \
      -Ccmake.define.CUDAToolkit_ROOT=$CONDA_PREFIX
# to target your GPU architecture, add
#   -Ccmake.define.CMAKE_CUDA_ARCHITECTURES=<your arch>

    3. Check on a GPU node

      If the GPU cannot be used, Conatus says why: the core was built without CUDA, or no device is visible.

    Optional extras

    Extras add optional Python packages; they are combined as usual, e.g. pip install "conatus[tutorials,notebook]".

    ExtraAddsFor
    tutorialsmatplotlib ≥ 3.7The figures of the tutorials (the optional Dedalus check of tutorial 14 needs Dedalus).
    gpucupy-cuda12x ≥ 13Device arrays, with the CUDA wheel (a source build also needs CONATUS_CUDA=ON).
    notebookipywidgets ≥ 8Rich displays of explain() in Jupyter.
    dedalus-comparededalus ≥ 3.0Side-by-side comparisons with Dedalus.
    docssphinx ≥ 7, myst-parser ≥ 2Building the documentation site.
    devpytest ≥ 8, ruff ≥ 0.5, mpmath ≥ 1.3Tests and lint.
    alltutorials, notebook, gpu, docs, devEverything above except dedalus-compare.

    Check your installation

    $ python -m conatus doctor
# what this machine can run (compiled core, GPU), and what to do about what is missing
$ python -c "import conatus.expert as ex; print(ex.explain())"
# what the single import contains, and any name clash
$ python -c "import conatus.runtime as r; print(r.CORE_SOURCE)"
installed
# CUDA wheel or build only: True on a node with a visible GPU
$ python -c "from conatus.runtime import cuda; print(cuda.available())"

    doctor tells you what this machine can run and how to fix what is missing. Conatus always says which compiled core it loaded; it never switches to another copy behind your back.

    An installed package writes nothing inside its environment: live-monitoring data go to ~/.cache/conatus (or $XDG_CACHE_HOME, CN_CACHE, CN_TMP), and doctor prints these directories.

    Then start the tutorials with tutorial 0, getting started.