.. include:: references.txt .. _gala-install: ************ Installation ************ With ``uv`` and ``pip`` (recommended) ===================================== To install the latest stable version using ``uv pip``, use:: uv pip install gala This is the recommended way to install ``gala``. To install the development version:: uv pip install git+https://github.com/adrn/gala Or, to add ``gala`` to an existing ``uv`` environment:: uv add gala .. note:: The pre-built wheels on PyPI (for Linux x86-64 and Apple Silicon macOS) come with :ref:`GSL support ` built in: a copy of GSL is bundled in the wheel, so you do not need to install GSL yourself. The bundled GSL is distributed under the GNU General Public License v3 (see ``GSL_LICENSE.txt``, included with the wheel's license files); gala itself is MIT licensed. The pre-built wheels do **not** include support for `EXP `_ potentials. To use :class:`~gala.potential.potential.EXPPotential`, you must build gala from source against your EXP installation; see :ref:`exp_tutorial`. .. _gala-install-source: From Source: Cloning, Building, Installing ========================================== The latest development version of gala can be cloned from `GitHub `_ using ``git``:: git clone git://github.com/adrn/gala.git To build and install the project (from the root of the source tree, e.g., inside the cloned ``gala`` directory):: uv pip install . .. _gala-install-dev: Installing development dependencies ----------------------------------- The dependencies needed for development (running the tests, building the documentation, and executing the tutorials) are defined as `dependency groups `_ in ``pyproject.toml``: ``test``, ``docs``, ``tutorials``, and ``dev`` (which includes all of the others). From the root of the cloned ``gala`` repository, ``uv sync`` creates a virtual environment (``.venv``) with an editable install of gala and the ``dev`` group:: uv sync To install only a specific group (for example, just the testing dependencies), disable the default ``dev`` group:: uv sync --no-default-groups --group test Then run commands in that environment with ``uv run``, e.g., ``uv run pytest``. If you are not using ``uv``, ``pip`` >= 25.1 also supports dependency groups. The groups include gala itself (with its optional dependencies), so install the local package in the same command as the group:: pip install -e . --group test Architecture-Specific Optimizations =================================== For performance reasons, the pre-compiled wheels installed via ``pip`` are built assuming a minimum CPU architecture. For Linux x86-64 CPUs (e.g. Intel), the wheels are built against ``x86-64-v3``, which is supported by most Intel CPUs since 2013. For macOS on ARM (Apple Silicon), the wheels are built against ``apple-m1`` and require an M1 (2020) or newer Mac. .. note:: Pre-built macOS wheels are only available for **Apple Silicon (arm64)** Macs. Intel Mac users must :ref:`build from source ` (see below). For the best performance, you may wish to build from source (see above) with the following environment variable set:: export CXXFLAGS=-march=native This will likely have the biggest effect on orbit integration. Be aware that compiling with this flag means that Gala will only run on the same type of CPU that it was compiled on! If your CPU does not support the instruction set that Gala was compiled for, you will likely receive an "illegal instruction error" (``SIGILL``). If that happens, try recompiling from source, without any ``-march`` flags. Installing on Windows ===================== We have successfully installed Gala on Windows within an Anaconda installation, or with the Windows Subsystem for Linux (WSL), which acts as a Linux environment within Windows. Either way, we recommend using GCC to compile any C code. Unfortunately, Gala will not work with Microsoft Visual Studio's C compiler because it is not C99 compliant. .. _gala-gsl: GSL support =========== Some functionality in Gala depends on the GNU Scientific Library (GSL), a C library for numerical and mathematical programming. By default, Gala will determine whether to install with or without GSL support depending on whether it can find a GSL installation on your machine. If you are not sure whether you have GSL installed or not, try running:: gsl-config --version in your terminal. If that returns a version number, you likely have GSL installed. If it errors, you will need to install it. Additionally, if your version of GSL is <1.14, we recommend updating to a newer version, as Gala has only been tested with GSL >= 1.14. On Linux and Mac, you can install GSL using a package manager, such as ``apt`` or ``homebrew``. For example, on a Mac with ``homebrew``, you can install GSL with:: brew install gsl Or on Linux with ``apt``:: apt-get install gsl-bin libgsl0-dev .. note:: **Intel Mac users:** pre-built wheels are not available for Intel (x86_64) Macs. After installing GSL via Homebrew (above), install Gala from source:: uv pip install gala --no-binary gala Forcing gala to install without GSL support ------------------------------------------- You can force Gala to build without GSL support using the ``--nogsl`` flag passed to setup.py. To use this flag, you must install Gala from source by cloning the repository (see above) and running:: uv pip install gala --install-option="--nogsl" Python Dependencies =================== Gala has the following build dependencies: * `Python`_ >= 3.12 * `Numpy`_ * `Cython `_ * ``setuptools`` * ``setuptools_scm`` * ``pybind11`` Gala follows `SPEC 0 `_ for its minimum supported versions of Python and core dependencies: support for a Python version is dropped 3 years after its initial release, and support for a core dependency version (e.g., numpy, scipy, matplotlib) is dropped 2 years after its initial release. See ``pyproject.toml`` for the current minimum versions. Gala has the following runtime dependencies: * `Numpy`_ * `Astropy`_ * `PyYAML`_ * `scipy`_ Optional -------- - `Sympy`_ for creating :class:`~gala.potential.potential.PotentialBase` subclass instances from a mathematical expression using :func:`~gala.potential.potential.from_equation()`. - ``galpy`` - ``h5py`` - ``matplotlib``