README.md

---
base_model:
- google/gemma-3-1b-pt
library_name: transformers
license: gemma
tags:
- pruning
- sparsity
- 2:4-sparsity
- patch
- maskllm
- mask
pipeline_tag: text-generation
---

<div align="center">
<img src="./PATCH-Logo.png" alt="PATCH" width="360">
</div>

# gemma_3_1b-PATCH-35Sparse

> **This checkpoint** (Gemma-3 1B, PATCH-Joint, 35% sparsity): **43.30%** average zero-shot accuracy, **11.48** WikiText2 perplexity.

[![Paper](https://img.shields.io/badge/arXiv-2509.23410-b31b1b.svg)](https://arxiv.org/abs/2509.23410) [![GitHub](https://img.shields.io/badge/GitHub-Paramathic%2Fpatch-black.svg?logo=github)](https://github.com/Paramathic/patch)

This repository hosts a **mask only** release for the paper
**[PATCH: Learnable Tile-level Hybrid Sparsity for LLMs](https://arxiv.org/abs/2509.23410)**.
PATCH (Pruning with a Learnable Tile-level Configuration for Hybrid Sparsity) learns a structured mask on **frozen** pretrained weights, assigning each tile as dense (0% sparsity) or 2:4 sparse (50% sparsity) to hit a flexible global sparsity target while staying hardware-friendly.

Because PATCH/MaskLLM keep the base weights **frozen**, we distribute *only the
binary keep/prune mask* (bit-packed in `mask.npz`) - **no weight values**. You
recover the sparse model by downloading the original base model and applying the
mask.

- Base model: [`google/gemma-3-1b-pt`](https://huggingface.co/google/gemma-3-1b-pt)
- Method: **PATCH-Joint** &nbsp;|&nbsp; Target sparsity: **35%** &nbsp;|&nbsp; Pattern: **Dense / 2:4 tiles**
- Measured mask sparsity: **35.04%**.

<div align="center">
<img src="./PATCH-Pipeline.svg" alt="PATCH pipeline" width="760">
</div>

## Results (Gemma-3 1B)

| Sparsity | Method | Pattern | Avg Acc (% ↑) | WikiText2 PPL (↓) |
|---|---|---|---|---|
| 0% | Dense | - | 47.01 | 11.67 |
| 50% | Magnitude | 2:4 | 31.66 | 5005.56 |
| 50% | Wanda | 2:4 | 34.16 | 69.41 |
| 50% | SparseGPT | 2:4 | 35.58 | 44.59 |
| 50% | Thanos | 2:4 | 35.09 | 62.63 |
| 50% | ProxSparse | 2:4 | 36.63 | 90.50 |
| 50% | MaskLLM | 2:4 | 41.84 | 12.82 |
| 45% | PATCH-Joint | Dense/2:4 | 42.80 | 11.96 |
| 35% | **PATCH-Joint** ⭐ | Dense/2:4 | **43.30** | **11.48** |
| 25% | PATCH-Joint | Dense/2:4 | 44.07 | 11.17 |


Per-task zero-shot accuracy (%) for this checkpoint:

| MMLU | PIQA | ARC-E | ARC-C | WinoG. | OBQA | RACE | HellaS. | **Average** |
|---|---|---|---|---|---|---|---|---|
| 25.38 | 72.31 | 63.80 | 27.39 | 56.67 | 24.00 | 34.74 | 42.07 | **43.30** |

All numbers are from the PATCH paper ([arXiv:2509.23410](https://arxiv.org/abs/2509.23410)); accuracy
is the average over MMLU, PIQA, ARC-Easy, ARC-Challenge, Winogrande, OpenBookQA,
RACE and HellaSwag, evaluated with the LM-Evaluation-Harness. PPL is WikiText2.

## Training hyper-parameters

| Hyper-parameter | Value |
|---|---|
| Fine-tuning dataset | SlimPajama (2B tokens) |
| Training steps | 2000 |
| Global batch size | 256 |
| Sequence length | 4096 |
| Mask tile size | 128 x 128 (hardware tiles: 128x128 / 128x64 / 64x128 / 64x64) |
| Logits init. | N(0, 0.014) |
| Tile-logit prior | SparseGPT (strength 3) |
| Regularization scope | Global (single target density) |
| Evaluation | LM-Eval-Harness (8 zero-shot tasks) + WikiText2 PPL @ seqlen 4096 |
| Hardware | 1 node x 4 GPUs, data parallel (HuggingFace Trainer) |
| Optimizer | Adam |
| Learning rate | 1e-3 |
| Gumbel scaling (kappa) | 25 -> 350 |
| Gumbel temp (tau) | 2 -> 0.05 |
| Sparsity reg. (lambda1) | 7 |
| Weight reg. (lambda2) | 10 |

## How to use

```python
from huggingface_hub import hf_hub_download
from transformers import AutoModelForCausalLM
import torch
from load_patch_mask import apply_patch_mask  # shipped in this repo

npz = hf_hub_download(repo_id="mohammad-mozaffari/gemma_3_1b-PATCH-35Sparse", filename="mask.npz")
model = AutoModelForCausalLM.from_pretrained("google/gemma-3-1b-pt", torch_dtype=torch.bfloat16)
apply_patch_mask(model, npz)   # zeroes the pruned weights in place
```

Or from the command line:

```bash
python load_patch_mask.py --base_model google/gemma-3-1b-pt --mask_repo mohammad-mozaffari/gemma_3_1b-PATCH-35Sparse
```

Speedup on real hardware requires a 2:4-aware / hybrid sparse kernel; see the
[GitHub repository](https://github.com/Paramathic/patch) and [STOICC](https://github.com/Paramathic/stoicc).

## License

The released mask is a derivative of the base model and is distributed under the
base model's license (**`gemma`**). You must comply with that license and
obtain access to the base model separately.

> Gemma is provided under and subject to the Gemma Terms of Use.

The mask-generation code is released under the MIT license (see the
[PATCH repository](https://github.com/Paramathic/patch)).

## Citation

```bibtex
@article{hourri2025patch,
    title  = {PATCH: Learnable Tile-level Hybrid Sparsity for LLMs},
    author = {Hourri, Younes and Mozaffari, Mohammad and Mehri Dehnavi, Maryam},
    year   = 2025,
    journal = {arXiv preprint arXiv:2509.23410}
}
```