Metadata-Version: 2.4
Name: vicentin
Version: 1.7.6
Summary: Personal collection of algorithms.
Author: Felipe Vicentin
License: MIT License
Project-URL: Homepage, https://codeberg.org/fsvicentin/vicentin
Project-URL: Bug Tracker, https://codeberg.org/fsvicentin/vicentin/issues
Project-URL: Source Code, https://codeberg.org/fsvicentin/vicentin
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: <3.15,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Provides-Extra: torch
Requires-Dist: torch; extra == "torch"
Provides-Extra: dl
Requires-Dist: torch>=2.5; extra == "dl"
Requires-Dist: torchvision; extra == "dl"
Requires-Dist: tqdm; extra == "dl"
Requires-Dist: tensorboard; extra == "dl"
Requires-Dist: cloudpickle; extra == "dl"
Provides-Extra: hub
Requires-Dist: torch; extra == "hub"
Requires-Dist: huggingface_hub; extra == "hub"
Requires-Dist: onnx; extra == "hub"
Requires-Dist: onnxscript; extra == "hub"
Provides-Extra: svm
Requires-Dist: cvxopt; extra == "svm"
Provides-Extra: plot
Requires-Dist: matplotlib; extra == "plot"
Requires-Dist: networkx; extra == "plot"
Provides-Extra: modal
Requires-Dist: modal; extra == "modal"
Provides-Extra: ssh
Requires-Dist: cloudpickle; extra == "ssh"
Provides-Extra: all
Requires-Dist: vicentin[dl,hub,modal,plot,ssh,svm,torch]; extra == "all"
Provides-Extra: test
Requires-Dist: vicentin[all]; extra == "test"
Requires-Dist: pytest>=6.0; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: scikit-learn; extra == "test"
Requires-Dist: onnxruntime; extra == "test"
Dynamic: license-file

# **Vicentin**

A comprehensive Python library for mathematical optimization, deep learning, computer vision, and classic algorithms. This library is designed with a dual-backend architecture, offering seamless switching between **NumPy** for transparency and **PyTorch** for hardware acceleration and automatic differentiation.

[![CI](https://codeberg.org/fsvicentin/vicentin/actions/workflows/publish.yml/badge.svg)](https://codeberg.org/fsvicentin/vicentin/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
<a href="https://pypi.org/project/vicentin/"><img alt="PyPI - Version" src="https://img.shields.io/pypi/v/vicentin"></a>

---

## **Table of Contents**

- [Introduction](#introduction)
- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Pre-commit Setup](#pre-commit-setup)
- [License](#license)

---

## **Introduction**

`vicentin` is a Python package that contains my personal implementations of a variety of algorithms, data structures, and optimization techniques. It serves as a collection of theoretical and practical programming concepts.

---

## **Features**

- **Data Structures**: [Queue](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/data_structures/queue.py), [Stack](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/data_structures/stack.py), [Tree](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/data_structures/tree.py), [Graph](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/data_structures/graph.py), [Heap](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/data_structures/heap.py), [Priority Queue](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/data_structures/priority_queue.py), [Trie](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/data_structures/trie.py), [Union Find](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/data_structures/union_find.py)
- **Dynamic Programming**: [Knapsack](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/dp/knapsack.py), [Matrix Multiplication](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/dp/matrix_multiplication.py), [Rod Cutting](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/dp/rod_cut.py), [Edit Distance](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/dp/str/edit_distance.py)
- **Graph Algorithms**: [Minimum Spanning Tree (MST)](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/graph/mst.py), [Shortest Path](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/graph/shortest_path.py), [Negative Cycle Detection](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/graph/negative_cycle.py)
- **Image & Video Processing**: [Optical Flow (Horn-Schunck)](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/image/video/optical_flow/horn_schunck/horn_schunck.py), [Differentiation](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/image/differentiation/diff.py), [Regularization](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/image/regularization/regularization.py), [Image-to-Graph](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/image/img2graph.py)
- **Optimization**: [Gradient Descent](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/optimization/minimization/gradient_descent/gradient_descent.py), [Newton's Method](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/optimization/minimization/newton_method/newton.py), [Barrier Method](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/optimization/minimization/barrier_method/barrier.py), [Proximal Gradient Descent](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/optimization/minimization/proximal_gradient_descent/proximal_gradient.py), [ISTA](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/optimization/minimization/ista/ista.py), [Projected Gradient Descent](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/optimization/minimization/projected_gradient_descent/projected_gradient.py), [Newton-Raphson (Root Finding)](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/optimization/root_finding/newton_raphson/newton_raphson.py)
- **Machine Learning**:
    - **[Kernels](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/kernels/base.py)**
    - **Unsupervised Learning**: [PCA](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/machine_learning/pca.py)
    - **Classification**: [Logistic Regression](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/machine_learning/classification/logistic_regression.py), [SVM](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/machine_learning/classification/svm/svm.py)
    - **Regression**: [Ridge Regression](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/machine_learning/regression/ridge_regression.py)
- **Deep Learning**:
    - **Models**: [Autoencoders (AE)](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/deep_learning/models/ae.py), [Variational Autoencoders (VAE)](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/deep_learning/models/vae.py)
    - **Trainers**: [Standard](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/deep_learning/train/StandardTrainer.py), [Supervised](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/deep_learning/train/SupervisedTrainer.py), [GAN](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/deep_learning/train/GANTrainer.py), [Distillation](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/deep_learning/train/DistillationTrainer.py)
    - **Losses**: [Beta-VAE](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/deep_learning/loss/BetaVAELoss.py), [Wasserstein GAN](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/deep_learning/loss/WassersteinGANLoss.py)
- **Sorting**: [Heap Sort](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/sorting/heapsort.py)
- **Mathematical Tools**: [Polynomial Operations](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/misc/polynomial.py)
- **Papers**: [Grad-CAM](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/papers/Grad_CAM), [SimCLR](https://codeberg.org/fsvicentin/vicentin/src/branch/main/src/vicentin/papers/SimCLR)

---

## **Installation**

```bash
pip install vicentin             # core: NumPy backend (numpy, scipy)
pip install "vicentin[torch]"    # + Torch backend for the dual-backend modules
```

Optional extras, combine as needed (e.g. `"vicentin[torch,plot]"`):

| Extra   | Adds                           | For                                       |
|---------|--------------------------------|-------------------------------------------|
| `torch` | torch                          | the Torch backend of any dual-backend module |
| `dl`    | torch, torchvision, tqdm       | `vicentin.deep_learning`, `vicentin.papers` |
| `svm`   | cvxopt                         | the NumPy SVM's QP solver                 |
| `plot`  | matplotlib, networkx           | `Graph.draw()`, trainer visualizations    |
| `all`   | everything above               |                                           |
| `test`  | `all` + pytest, scikit-learn   | running the test suite                    |

For development:

```bash
git clone https://codeberg.org/fsvicentin/vicentin.git
cd vicentin
python -m venv venv && source venv/bin/activate
pip install -e ".[test]"
pytest
```

---

## **Usage**

### Heap data structure

```python
# Example: Using the heap data structure
from vicentin.data_structures.heap import Heap

heap = Heap()
heap.insert(5)
heap.insert(2)
heap.insert(8)

print(heap.extract_min())  # Output: 2
```

### Newton's Method

```python
import torch
from vicentin.optimization.minimization import newton_method

def objective(x):
    return torch.sum(x**2)

x0 = torch.tensor([10.0, 10.0])
A = torch.tensor([[1.0, 1.0]])
b = torch.tensor([1.0])

# Backend (Torch) is automatically detected from x0
x_opt = newton_method(objective, x0, equality=(A, b))
print(f"Optimal solution: {x_opt}")
```

---

## **Pre-commit Setup**

This repository uses `pre-commit` to enforce coding standards, automatic formatting and automatic version bumping before commits.

### **1️⃣ Install `pre-commit`**

```bash
pip install pre-commit
```

### **2️⃣ Install Hooks**

```bash
pre-commit install
```

### 3️⃣ Use [`commitizen`](https://commitizen-tools.github.io/commitizen/) to commit

```bash
cz commit
```

---

## **License**

This project is licensed under the [MIT License](LICENSE).
