Metadata-Version: 2.2
Name: alcnet
Version: 0.1.1
Summary: Adaptive Layer Condensation Networks - Learning Dynamic Compression Ratios for Hierarchical Feature Selection
Author-email: Ananda Jana <captainajunited@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/anandajana/alcnet
Project-URL: Documentation, https://github.com/anandajana/alcnet#readme
Project-URL: Repository, https://github.com/anandajana/alcnet
Project-URL: Bug Tracker, https://github.com/anandajana/alcnet/issues
Keywords: deep-learning,neural-networks,compression,feature-selection,adaptive-architecture,pytorch,machine-learning
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=1.9.0
Requires-Dist: numpy>=1.19.0
Requires-Dist: tqdm>=4.50.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.12; extra == "dev"
Requires-Dist: black>=21.0; extra == "dev"
Requires-Dist: flake8>=3.9; extra == "dev"
Requires-Dist: mypy>=0.910; extra == "dev"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.3.0; extra == "viz"
Provides-Extra: examples
Requires-Dist: torchvision>=0.10.0; extra == "examples"
Requires-Dist: scikit-learn>=0.24.0; extra == "examples"
Dynamic: requires-python

# ALCNet - Adaptive Layer Condensation Networks

[![PyPI version](https://badge.fury.io/py/alcnet.svg)](https://badge.fury.io/py/alcnet)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Learning Dynamic Compression Ratios for Hierarchical Feature Selection**

ALCNet is a neural network architecture where compression ratios at each layer are learned as trainable parameters rather than fixed before training. This enables task-adaptive architecture optimization without expensive neural architecture search.

## Key Features

- **Learnable Compression Ratios**: Target sparsity at each layer adapts during training
- **Task-Adaptive**: Simple tasks learn aggressive compression, complex tasks preserve features
- **Differentiable**: End-to-end training with backpropagation
- **No NAS Required**: Eliminates expensive architecture search
- **Interpretable**: Learned compression ratios reveal task complexity

## Installation

```bash
pip install alcnet
```

## Quick Start

```python
import torch
from alcnet import ALCNet, ALCNetTrainer
import torch.optim as optim

# Create model with learnable compression ratios
model = ALCNet([784, 256, 128, 64, 10])

# Setup training
optimizer = optim.Adam(model.parameters(), lr=0.001)
trainer = ALCNetTrainer(model, optimizer, lambda_sparse=0.001, lambda_ratio=0.01)

# Train on your data
history = trainer.fit(train_loader, val_loader, epochs=50)

# Check learned compression ratios
print(model.get_compression_ratios())
```

## How It Works

Unlike traditional networks with fixed layer sizes, ALCNet learns optimal compression at each layer:

1. **Standard Approach**: You decide `[784, 256, 128, 64, 10]` before training
2. **ALCNet Approach**: Network learns how much to compress at each layer based on task

### Architecture

```
Input Layer (784) 
    ↓  [Learnable ρ⁽¹⁾]
Hidden Layer (256)
    ↓  [Learnable ρ⁽²⁾]
Hidden Layer (128)
    ↓  [Learnable ρ⁽³⁾]
Hidden Layer (64)
    ↓
Output (10)
```

Each ρ⁽ⁱ⁾ ∈ (0,1) controls compression intensity at layer i.

## Example Results

Simple tasks may learn aggressive early compression:
```
layer_1: ρ = 0.20 (keep 20% of neurons)
layer_2: ρ = 0.15
layer_3: ρ = 0.10
```

Complex tasks preserve more features:
```
layer_1: ρ = 0.70 (keep 70% of neurons)
layer_2: ρ = 0.60
layer_3: ρ = 0.40
```

## Advanced Usage

### Analysis and Visualization

```python
from alcnet import CompressionAnalyzer

analyzer = CompressionAnalyzer(model)

# Plot compression evolution during training
analyzer.plot_compression_evolution(history)

# Compute feature survival probabilities
survival = analyzer.compute_feature_survival(dataloader)

# Get summary statistics
stats = analyzer.get_summary_stats(history)
```

### Custom Configuration

```python
# Specify initial compression ratios
initial_ratios = [0.5, 0.4, 0.3]
model = ALCNet([784, 256, 128, 64, 10], initial_ratios=initial_ratios)

# Adjust loss weights
trainer = ALCNetTrainer(
    model, 
    optimizer,
    lambda_sparse=0.005,  # Sparsity weight
    lambda_ratio=0.05     # Ratio matching weight
)
```

## Examples

See the `examples/` directory:
- `mnist_example.py`: Complete MNIST classification example
- More examples coming soon

## Requirements

- Python ≥ 3.7
- PyTorch ≥ 1.9.0
- NumPy
- matplotlib (optional, for visualization)
- scikit-learn (optional, for data utilities)

## Citation

If you use ALCNet in your research, please cite:

```bibtex
@article{jana2026alcnet,
  title={Adaptive Layer Condensation Networks: Learning Dynamic Compression Ratios for Hierarchical Feature Selection},
  author={Jana, Ananda},
  journal={arXiv preprint},
  year={2026}
}
```

## Paper

The full paper describing the theory, implementation, and experimental validation of ALCNet is available at: [Link to paper]

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Author

**Ananda Jana**  
Indian Institute of Science Education and Research Thiruvananthapuram (IISER TVM), Kerala, India

## Acknowledgments

This work explores learnable compression mechanisms in neural network architectures through independent research into adaptive feature selection and hierarchical compression strategies.
