Metadata-Version: 2.4
Name: quaternion_neural_networks
Version: 0.2.0
Summary: A short description of the project.
Author: shreyaskamathkm@gmail.com
License-Expression: GPL-3.0-only
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.11.7
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: rich>=14.1.0
Requires-Dist: click>=8.1.7
Requires-Dist: torch>=2.0.0
Requires-Dist: torchvision>=0.15.0
Requires-Dist: scipy
Provides-Extra: dev
Requires-Dist: ruff>=0.8.3; extra == "dev"
Requires-Dist: mypy>=1.13.0; extra == "dev"
Requires-Dist: pytest>=8.3.2; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: types-PyYAML>=6.0.12.20240311; extra == "dev"
Requires-Dist: mkdocs-material>=9.5.0; extra == "dev"
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == "dev"
Requires-Dist: pre-commit>=3.5.0; extra == "dev"
Requires-Dist: bump-my-version>=0.16.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.2; extra == "dev"
Dynamic: license-file

# Quaternion Neural Networks

This project provides a robust implementation of Quaternion Neural Networks in PyTorch, heavily inspired by and built upon the excellent [Pytorch-Quaternion-Neural-Networks](https://github.com/Orkis-Research/Pytorch-Quaternion-Neural-Networks) by Orkis Research. It extends the original work with improved software engineering practices, type hinting, and strict code quality enforcement.

## Package Management

This package uses `uv` for lightning-fast project dependency management and environment synchronization. `uv sync` is used to strictly resolve dependencies and create reproducible environments.

## Development Commands

This project uses a `Makefile` to provide a convenient interface for common development tasks. You can also run the commands directly with `uv run`.

## Dependencies

Dependencies are defined in [`pyproject.toml`](./pyproject.toml). To synchronize your local virtual environment and install all development tools:

```shell
make edit-install
```
Alternatively, you can run `uv sync` directly:

```shell
uv sync --all-extras
```
After syncing, you can execute any script or test seamlessly using `uv run`, which automatically uses the managed environment:
```shell
uv run pytest
```

To upgrade all dependencies to their latest versions, you can edit the `pyproject.toml` file and then run the install command again.

## Packaging

This project is designed as a Python package, meaning that it can be bundled up and redistributed as a single compressed file. Packaging is configured by:

- [`pyproject.toml`](./pyproject.toml)

To package the project as both a [source distribution](https://packaging.python.org/en/latest/flow/#the-source-distribution-sdist) and a [wheel](https://packaging.python.org/en/latest/specifications/binary-distribution-format/):

Run the `uv build` command:
```shell
uv build
```

This will generate `dist/quaternion_neural_networks-0.1.0.tar.gz` and `dist/quaternion_neural_networks-0.1.0-py3-none-any.whl`.

## Enforcing Code Quality

Automated code quality checks are performed using [Ruff](https://docs.astral.sh/ruff/).

## Unit Testing

Unit testing is performed with [pytest](https://pytest.org/).

To run unit tests:

```shell
make test
```
Alternatively, you can run `pytest` directly:
```shell
uv run pytest
```

Code coverage is provided by the [pytest-cov](https://pytest-cov.readthedocs.io/en/latest/) plugin.

## Code Style Checking

[PEP 8](https://peps.python.org/pep-0008/) is the universally accepted style guide for Python code. PEP 8 code compliance is verified using [Ruff](https://docs.astral.sh/ruff/). Ruff is configured in the `[tool.ruff]` section of [`pyproject.toml`](./pyproject.toml).

To lint code, run:

```shell
make lint
```
Alternatively, you can run `ruff` directly:
```shell
uv run ruff check .
```

To automatically fix fixable lint errors, run:

```shell
uv run ruff check . --fix
```

## Automated Code Formatting

[Ruff](https://docs.astral.sh/ruff/) is used to automatically format code and group and sort imports.

To automatically format code, run:

```shell
make format
```
Alternatively, you can run `ruff` directly:
```shell
uv run ruff format .
```

## Type Checking

[Type annotations](https://docs.python.org/3/library/typing.html) allows developers to include optional static typing information to Python source code. This allows static analyzers such as [mypy](http://mypy-lang.org/) to check that functions are used with the correct types before runtime.

mypy is configured in [`pyproject.toml`](./pyproject.toml). To type check code, run:

```shell
make typecheck
```
Alternatively, you can run `mypy` directly:
```shell
uv run mypy .
```

## Project Structure

This project uses a flat layout. This results in a directory structure like:

```
quaternion_neural_networks
├── quaternion_neural_networks
│   ├── __init__.py
│   ├── quaternion_conv.py
│   ├── quaternion_linear.py
│   ├── quaternion_ops.py
│   └── ...
├── tests
│   └── ...
├── pyproject.toml
└── uv.lock
```

## Licensing

Licensing for the project is defined in:

- [`LICENSE`](./LICENSE)
- [`pyproject.toml`](./pyproject.toml)

This project uses the GNU General Public License v3.0 (GPL-3.0), as it inherits from the original Pytorch-Quaternion-Neural-Networks codebase.

## Container

[Docker](https://www.docker.com/) is a tool that allows for software to be packaged into isolated containers.

The Docker configuration in this repository is optimized for small size and increased security. Docker is configured in:

- [`Dockerfile`](./Dockerfile)
- [`.dockerignore`](./.dockerignore)

To build the container image:

```shell
docker build --tag quaternion_neural_networks .
```

To run the image in a container:

```shell
docker run --rm --interactive --tty quaternion_neural_networks
```
