🖥️ Installation

Dependencies

The mandatory dependencies of PyProximal are limited to:

We encourage using the Anaconda Python distribution or its standalone package manager Conda. Especially for Intel processors, this ensures a higher performance with no configuration (e.g., the linking to Intel MKL library, a highly optimized BLAS library created by Intel).

For learning, however, the standard installation is often good enough; in that case, we recommend using uv, a modern Python package manager that is easy to use and has a very fast dependency resolver.

Step-by-step installation for users

From Package Manager

First install pyproximal with your package manager of choice.

>> conda install --channel conda-forge pyproximal

which installs also the required dependencies, if not already present in your environment.

>> uv add pyproximal

which installs also the required dependencies, if not already present in your environment. To also install the optional dependencies, run:

>> uv add "pyproximal[advanced]"

From Source

To access the latest source from GitHub:

>> pip install https://github.com/PyLops/pyproximal.git@dev

>> uv add git+https://github.com/PyLops/pyproximal.git --branch dev

Step-by-step installation for developers

Fork PyProximal

Fork the PyProximal repository and clone it by executing the following in your terminal:

>> git clone https://github.com/YOUR-USERNAME/pyproximal.git

Install dependencies

We recommend installing dependencies into a separate environment. For that end, we provide a Makefile with useful commands for setting up the environment.

>> make dev-install_conda # for x86 (Intel or AMD CPUs)
>> make dev-install_conda_arm # for arm (M-series Mac)

This creates and activate an environment called pyproximal, with all required and optional dependencies.

>> make dev-install_uv

This creates a virtual environment .venv that can be activated at any time with source .venv/bin/activate (Linux/macOS).

Run tests

To ensure that everything has been setup correctly, run tests:

>> make tests

>> make tests_uv

Make sure no tests fail, this guarantees that the installation has been successful.

Add remote (optional)

To keep up-to-date on the latest changes while you are developing, you may optionally add the PyLops repository as a remote. Run the following command to add the PyLops repo as a remote named upstream:

>> git remote add upstream https://github.com/PyLops/pylops

From then on, you can pull changes (for example, in the dev branch) with:

>> git pull upstream dev

Install pre-commit hooks

To ensure consistency in the coding style of our developers we rely on pre-commit to perform a series of checks when you are ready to commit and push some changes. This is accomplished by means of git hooks that have been configured in the .pre-commit-config.yaml file.

In order to setup such hooks in your local repository, run:

>> pre-commit install

>> uv run pre-commit install

Once this is set up, when committing changes, pre-commit will reject and “fix” your code by running the proper hooks. At this point, the user must check the changes and then stage them before trying to commit again.

Final steps

PyProximal does enforce the use of a linter (ruff), which is run both as a pre-commit hook and as a GitHub Action. The linter can also be run locally with:

>> make lint

>> make lint_uv

In addition, it is highly encouraged to build the docs prior to submitting a Pull Request. Apart from ensuring that docstrings are properly formatted, they can aid in catching bugs during development. Build (or update) the docs with:

>> make doc

>> make doc_uv

or

>> make docupdate

>> make docupdate_uv