Metadata-Version: 2.4
Name: proploss
Version: 0.5.0
Summary: Gradient-Free Deep Classification — Zero iterations, beats backprop
Home-page: https://github.com/umiteknoloji/proploss-classifier
Author: Ümit Öztürk
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Intended Audience :: Science/Research
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# PropLoss — Gradient-Free Deep Classification

**Zero gradient. Zero iterations. Zero backward pass.**  
All weights computed analytically from data statistics in a single pass.

## Results

| Layers | PropLoss | Backprop (500 iter) | Speed |
|--------|----------|---------------------|-------|
| 2      | **72.5%** | 70.5% | **41x faster** |
| 3      | **73.5%** | 59.8% | **26x faster** |
| 4      | **74.7%** | 43.8% | **24x faster** |
| 6      | **75.3%** | 24.4% | **22x faster** |

PropLoss beats backpropagation at every depth. As networks get deeper, backprop suffers from vanishing gradients — PropLoss does not, because it uses no gradients at all.

## Installation

```bash
pip install proploss
```

Or from source:
```bash
git clone https://github.com/umiteknoloji/proploss-classifier.git
cd proploss-classifier
pip install -e .
```

## Quick Start

```python
from proploss import PropLossClassifier

model = PropLossClassifier(n_hidden=4, hidden_dim=128)
model.fit(X_train, y_train)

predictions = model.predict(X_test)
accuracy = model.score(X_test, y_test)
probabilities = model.predict_proba(X_test)
```

## How It Works

### The Core Formula — BackLoss F2

```
w_ci = (μ_ci − μ_i) / (D × σ_i)
```

Where:
- `μ_ci` = mean of feature i for class c
- `μ_i` = global mean of feature i
- `σ_i` = standard deviation of feature i
- `D` = number of features (dimensionality)

This computes how much each feature deviates from the global mean for each class, normalized by variance. No gradient needed — pure statistics.

### PropLoss — Multi-Layer Extension

Each hidden layer uses three formulas and automatically selects the best directions:

| Formula | What it does | When it's selected |
|---------|-------------|-------------------|
| **A — BackLoss Discriminant** | Finds directions that separate classes | High Fisher score on class boundaries |
| **B — PCA** | Preserves maximum variance | When variance carries class information |
| **D — LDA** | Minimizes within-class, maximizes between-class variance | Strongest for overlapping classes |

Selection is automatic via **Fisher score** + **greedy orthogonal selection**. Each neuron gets the formula that works best for it.

### Key Property: Class Separability Increases With Depth

```
Layer 1: separability 0.28 → 0.39 ↑
Layer 2: separability 0.39 → 0.43 ↑
Layer 3: separability 0.43 → 0.51 ↑
Layer 4: separability 0.51 → 0.56 ↑
Layer 5: separability 0.56 → 0.57 ↑
```

Unlike backprop where deep networks suffer from vanishing gradients, PropLoss **improves** with depth because each layer analytically enhances class separation.

## API Reference

### `PropLossClassifier(n_hidden=2, hidden_dim=128, min_count=3)`

**Parameters:**
- `n_hidden` — Number of hidden layers (0-10, default 2)
- `hidden_dim` — Neurons per hidden layer (default 128)
- `min_count` — Minimum samples per class (default 3)

**Methods:**
- `fit(X, y)` — Train the model (single pass)
- `predict(X)` — Return class labels
- `predict_proba(X)` — Return probability distributions
- `score(X, y)` — Return accuracy
- `summary()` — Print model architecture

## Use Cases

PropLoss is ideal when:
- **Speed is critical** — real-time classification, edge devices
- **No GPU available** — runs on CPU, Raspberry Pi, mobile
- **Frequent retraining** — new data → instant model update
- **Deep networks needed** — PropLoss gets better with depth, backprop gets worse

Applications: medical imaging, cybersecurity, quality control, speaker identification, species recognition, fraud detection.

## Requirements

- Python ≥ 3.8
- NumPy ≥ 1.20

No PyTorch. No TensorFlow. No GPU. Just NumPy.

## Citation

```
@software{proploss2026,
  author = {Öztürk, Ümit},
  title = {PropLoss: Gradient-Free Deep Classification},
  year = {2026},
  url = {https://github.com/umiteknoloji/proploss-classifier}
}
```

## License

MIT
