Developer Installation#

Prerequisites#

Before you can start contributing to Acoular

  • Create a fork of the Acoular repository on GitHub

  • Clone your fork to your local machine via

$ git clone <https://your_fork>
$ cd acoular

We encourage using the latest compatible Python version, which is currently 3.13.

Creating a development environment#

For development, a virtual environment is needed. Create one with your preferred tool:

$ uv venv

Note

uv will handle environment activation implicitly (the environment is created at .venv).

$ python3 -m venv my-env

and activate the environment with:

$ source my-env/bin/activate

$ mamba create -n my-env

and activate the environment with:

$ mamba activate my-env

$ conda create -n my-env

and activate the environment with:

$ conda activate my-env

Editable installation#

Next, we need to make an editable installation of Acoular with:

Note

uv defaults to an editable installation, so nothing needs to be done here.

Make sure to use an up-to-date version of pip that supports dependency-groups. You can update pip with:

$ pip install --upgrade pip

Then, make an editable installation of Acoular and its dev dependencies with:

$ pip install -Ue .'[full]' --group dev

Install pip with:

$ mamba install pip

Then, make an editable installation of Acoular and its dev dependencies with:

$ pip install -Ue .'[full]' --group dev

Install pip with:

$ conda install pip

Then, make an editable installation of Acoular and its dev dependencies with:

$ pip install -Ue .'[full]' --group dev

An editable installation allows you to make changes to the source code and see the effects immediately without having to reinstall the package.

The --group dev argument is responsible for installing the corresponding dependency group as defined in:

pyproject.toml (click to expand)
[dependency-groups]
docs = [
    "ipython",
    "graphviz",
    "matplotlib",
    "numpydoc",
    "pickleshare",
    "pydata-sphinx-theme",
    "sounddevice",
    "sphinx",
    "sphinx-copybutton",
    "sphinx-design",
    "sphinx-gallery",
    "sphinxcontrib-bibtex",
    "setuptools", # unfortunately still needed for sphinxcontrib-bibtex (https://github.com/mcmtroffaes/sphinxcontrib-bibtex/issues/345)
]

lint = ["ruff==0.14.2"]

test = [
    "h5py",
    "pylops",
    "pytest",
    "pytest-mock",
    "pytest-cov",
    "pytest-regtest",
    "pytest-cases",
    "pytest-env",
    "pytest-profiling",
    "PyYAML",
    "sounddevice",
    "traitsui",
]

dev = [
    {include-group = "docs"},
    {include-group = "lint"},
    {include-group = "test"},
]

If omitted, the dependencies have to be installed manually.

System dependencies#

Some of the Acoular dependencies require system packages to be installed. On Ubuntu, we frequently encounter that PortAudio is missing, which is required by the sounddevice library. In addition, Graphviz is required for the Acoular documentation. You can install both with:

$ sudo apt install graphviz libportaudio2