PyUNLocBoX

https://pyunlocbox.readthedocs.io/en/latest/
Admin
PyUNLocBoX is a Python package that uses proximal splitting methods to solve non-differentiable...
Tokens:1,831
Snippets:31
Trust Score:9.6
Update:4 months ago
Show doc for...
Tokens:
Raw
### Quick Project Setup with 'just'

Source: https://pyunlocbox.readthedocs.io

Use the 'just' command runner for a streamlined setup process, including dependency installation and pre-commit hook configuration.

```bash
$ just setup  # Installs dependencies and sets up pre-commit hooks
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://pyunlocbox.readthedocs.io

Clone the PyUNLocBoX repository and install development dependencies using UV. Activate the virtual environment for subsequent commands.

```bash
$ git clone https://github.com/epfl-lts2/pyunlocbox.git
$ cd pyunlocbox
$ uv sync --dev
$ source .venv/bin/activate  # On Windows: .venv\Scripts\activate
```

--------------------------------

### Install PyUNLocBoX with UV

Source: https://pyunlocbox.readthedocs.io

Commands to add and install the PyUNLocBoX package using the UV package manager.

```bash
$ uv add pyunlocbox
```

```bash
$ uv pip install pyunlocbox
```

--------------------------------

### Install PyUNLocBoX with Pip

Source: https://pyunlocbox.readthedocs.io

Command to install the PyUNLocBoX package using Pip.

```bash
$ pip install pyunlocbox
```

--------------------------------

### Install PyUNLocBoX with Conda

Source: https://pyunlocbox.readthedocs.io

Command to install the PyUNLocBoX package from conda-forge using Conda.

```bash
$ conda install -c conda-forge pyunlocbox
```

--------------------------------

### Install Pre-commit Hooks

Source: https://pyunlocbox.readthedocs.io

Set up pre-commit hooks to automatically run code formatting and linting checks before each commit. This ensures consistent code style and quality.

```bash
$ uv run pre-commit install
```

--------------------------------

### Solve Optimization Problem with PyUNLocBoX

Source: https://pyunlocbox.readthedocs.io

A typical usage example demonstrating how to solve an optimization problem composed of the sum of two convex functions using PyUNLocBoX. It shows instantiation of function and solver objects, and calling the `solve` function.

```python
>>> from pyunlocbox import functions, solvers
>>> f1 = functions.norm_l2(y=[4, 5, 6, 7])
>>> f2 = functions.dummy()
>>> solver = solvers.forward_backward()
>>> ret = solvers.solve([f1, f2], [0., 0, 0, 0], solver, atol=1e-5)
Solution found after 9 iterations:
    objective function f(sol) = 6.714385e-08
    stopping criterion: ATOL
>>> ret['sol']
array([3.99990766, 4.99988458, 5.99986149, 6.99983841])
```

--------------------------------

### Define Custom Function in PyUNLocBoX

Source: https://pyunlocbox.readthedocs.io

Example of how to define a custom function by inheriting from `pyunlocbox.functions.func` and implementing the `_eval`, `_grad`, and `_prox` methods.

```python
>>> from pyunlocbox import functions
>>> class myfunc(functions.func):
...     def _eval(self, x):
...         return 0  # Function evaluated at x.
...     def _grad(self, x):
...         return x  # Gradient evaluated at x, if available.
...     def _prox(self, x, T):
...         return x  # Proximal operator evaluated at x, if available.
```

--------------------------------

### Set up Development Environment with UV

Source: https://pyunlocbox.readthedocs.io

Steps to clone the PyUNLocBoX repository and set up a development environment using UV.

```bash
$ git clone https://github.com/epfl-lts2/pyunlocbox.git
$ cd pyunlocbox
$ uv sync --dev
```

--------------------------------

### Build Documentation with Sphinx

Source: https://pyunlocbox.readthedocs.io

Build the project documentation using Sphinx. This command generates HTML documentation from the source files in the 'doc' directory.

```bash
$ uv run sphinx-build -b html doc/ doc/_build/
```

--------------------------------

### Format Code with Black and isort

Source: https://pyunlocbox.readthedocs.io

Apply code formatting using Black for consistent Python style and isort for organizing imports. These commands format the code in the current directory.

```bash
$ uv run black .
$ uv run isort .
```

--------------------------------

### Run Tests with Pytest

Source: https://pyunlocbox.readthedocs.io

Execute the test suite using pytest. This command runs all tests defined in the project.

```bash
$ uv run pytest
```

--------------------------------

### Run All Pre-commit Checks Manually

Source: https://pyunlocbox.readthedocs.io

Manually trigger all pre-commit checks across all files in the repository. This is useful for verifying code quality before committing.

```bash
$ uv run pre-commit run --all-files
```

--------------------------------

### Run Linting with Flake8

Source: https://pyunlocbox.readthedocs.io

Execute the flake8 linter to check for code quality and style issues. The `--doctests` flag includes doctests in the check, and `--exclude` skips specified directories.

```bash
$ uv run flake8 --doctests --exclude=doc,.venv
```

--------------------------------

### Run Tests with Coverage

Source: https://pyunlocbox.readthedocs.io

Run tests with pytest and generate an HTML report for code coverage. This helps identify areas of the code that are not adequately tested.

```bash
$ uv run pytest --cov=pyunlocbox --cov-report=html
```

--------------------------------

### Run Specific Test Files

Source: https://pyunlocbox.readthedocs.io

Execute a specific test file using pytest. This is useful for focusing on a particular test case or module.

```bash
$ uv run pytest pyunlocbox/tests/test_acceleration.py
```

--------------------------------

### PyUNLocBoX Citation

Source: https://pyunlocbox.readthedocs.io

A BibTeX entry for citing the PyUNLocBoX library in academic publications. It includes title, authors, DOI, and URL for the project.

```bibtex
@misc{pyunlocbox,
  title = {PyUNLocBoX: Optimization by Proximal Splitting},
  author = {Defferrard, Micha"el and Pena, Rodrigo and Perraudin, Nathana"el},
  doi = {10.5281/zenodo.1199081},
  url = {https://github.com/epfl-lts2/pyunlocbox/},
}
```
Tokens:
Raw