l0-python 0.4.1__py3-none-any.whl → 0.4.3__py3-none-any.whl

l0/calibration.py

@@ -444,9 +444,9 @@ class SparseCalibrationWeights(nn.Module):
                                 rel_errors[group_mask].mean().item()
                             )
                             group_losses.append(group_mean_err)
-                        mean_group_loss = np.mean(group_losses)
+                        mean_group_mare = np.mean(group_losses)
                     else:
-                        mean_group_loss = mean_rel_err
+                        mean_group_mare = mean_rel_err
 
                     # Calculate sparsity percentage
                     sparsity_pct = 100 * (
@@ -461,7 +461,7 @@ class SparseCalibrationWeights(nn.Module):
                     if target_groups is not None:
                         print(
                             f"Epoch {epoch+1:4d}: "
-                            f"mean_group_loss={mean_group_loss:.1%}, "
+                            f"mean_group_mare={mean_group_mare:.4%}, "
                             f"max_error={max_rel_err:.1%}, "
                             f"total_loss={actual_total_loss:.3f}, "
                             f"active={active_info['count']:4d}/{self.n_features} ({sparsity_pct:.1f}% sparse)"
@@ -469,7 +469,7 @@ class SparseCalibrationWeights(nn.Module):
                     else:
                         print(
                             f"Epoch {epoch+1:4d}: "
-                            f"mean_error={mean_rel_err:.1%}, "
+                            f"mean_error={mean_rel_err:.4%}, "
                             f"max_error={max_rel_err:.1%}, "
                             f"total_loss={actual_total_loss:.3f}, "
                             f"active={active_info['count']:4d}/{self.n_features} ({sparsity_pct:.1f}% sparse)"

{l0_python-0.4.1.dist-info → l0_python-0.4.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: l0-python
-Version: 0.4.1
+Version: 0.4.3
 Summary: L0 regularization for sparse neural networks and intelligent sampling
 Author-email: PolicyEngine <hello@policyengine.org>
 License: MIT License
@@ -65,21 +65,15 @@ Dynamic: license-file
 
 # L0 Regularization
 
-A PyTorch implementation of L0 regularization for neural network sparsification and intelligent sampling, based on [Louizos, Welling, & Kingma (2017)](https://arxiv.org/abs/1712.01312).
+[![PyPI version](https://badge.fury.io/py/l0-python.svg)](https://pypi.org/project/l0-python/)
+[![CI](https://github.com/PolicyEngine/L0/actions/workflows/push.yml/badge.svg)](https://github.com/PolicyEngine/L0/actions)
 
-## Features
-
-- **Hard Concrete Distribution**: Differentiable approximation of L0 norm
-- **Sparse Neural Network Layers**: L0Linear, L0Conv2d with automatic pruning
-- **Intelligent Sampling**: Sample/feature selection gates for calibration
-- **L0L2 Combined Penalty**: Recommended approach to prevent overfitting
-- **Temperature Scheduling**: Annealing for improved convergence
-- **TDD Development**: Comprehensive test coverage
+A PyTorch implementation of L0 regularization based on [Louizos, Welling, & Kingma (2017)](https://arxiv.org/abs/1712.01312), designed for survey calibration and sparse regression.
 
 ## Installation
 
 ```bash
-pip install l0
+pip install l0-python
 ```
 
 For development:
@@ -89,119 +83,117 @@ cd L0
 pip install -e .[dev]
 ```
 
-## Quick Start
+## Our Approach to Test-Time Gates
 
-### Neural Network Sparsification
+The original Hard Concrete formulation uses temperature (β) during training to control the sharpness of stochastic gates. At test time, there's a design choice: whether to include temperature in the deterministic gate computation.
 
+We include temperature at test time:
 ```python
-import torch
-from l0 import L0Linear, compute_l0l2_penalty, TemperatureScheduler, update_temperatures
-
-# Create a sparse model
-class SparseModel(torch.nn.Module):
-    def __init__(self):
-        super().__init__()
-        self.fc1 = L0Linear(784, 256, init_sparsity=0.5)
-        self.fc2 = L0Linear(256, 10, init_sparsity=0.7)
-    
-    def forward(self, x):
-        x = torch.relu(self.fc1(x))
-        return self.fc2(x)
-
-model = SparseModel()
-optimizer = torch.optim.Adam(model.parameters())
-scheduler = TemperatureScheduler(initial_temp=1.0, final_temp=0.1)
-
-# Training loop
-for epoch in range(100):
-    # Update temperature
-    temp = scheduler.get_temperature(epoch)
-    update_temperatures(model, temp)
-    
-    # Forward pass
-    output = model(input_data)
-    ce_loss = criterion(output, target)
-    
-    # Add L0L2 penalty
-    penalty = compute_l0l2_penalty(model, l0_lambda=1e-3, l2_lambda=1e-4)
-    loss = ce_loss + penalty
-    
-    # Backward pass
-    optimizer.zero_grad()
-    loss.backward()
-    optimizer.step()
+# Our approach: include temperature
+z = sigmoid(log_alpha / beta) * (zeta - gamma) + gamma
+
+# Alternative: omit temperature
+z = sigmoid(log_alpha) * (zeta - gamma) + gamma
 ```
 
-### Intelligent Sample Selection
+Including temperature produces sharper 0/1 decisions, which we find beneficial for achieving clean sparsity in our applications. See `examples/sparse_regression_demo.py` for a demonstration on a 4-variable regression problem.
+
+## Primary Use Case: Survey Calibration
+
+This package was developed for PolicyEngine's survey calibration, where we select a sparse subset of survey households while matching population targets.
 
 ```python
-from l0 import SampleGate, HybridGate
-
-# Pure L0 selection
-gate = SampleGate(n_samples=10000, target_samples=1000)
-selected_data, indices = gate.select_samples(data)
-
-# Hybrid selection (25% L0, 75% random)
-hybrid = HybridGate(
-    n_items=10000,
-    l0_fraction=0.25,
-    random_fraction=0.75,
-    target_items=1000
+import numpy as np
+from scipy import sparse as sp
+from l0.calibration import SparseCalibrationWeights
+
+# Setup: Q targets, N households
+Q, N = 200, 10000
+M = sp.random(Q, N, density=0.3, format="csr")  # Household characteristics
+y = np.random.uniform(1e6, 1e8, size=Q)          # Population targets
+
+# Initialize model
+model = SparseCalibrationWeights(
+    n_features=N,
+    beta=0.35,
+    gamma=-0.1,
+    zeta=1.1,
+    init_keep_prob=0.5,
+    init_weights=1.0,
+    log_weight_jitter_sd=0.05,
+    device="cuda",
+)
+
+# Train with L0+L2 regularization
+model.fit(
+    M=M,
+    y=y,
+    lambda_l0=1e-6,
+    lambda_l2=1e-8,
+    lr=0.15,
+    epochs=2000,
+    loss_type="relative",
+    verbose=True,
 )
-selected, indices, types = hybrid.select(data)
+
+# Get results
+active = model.get_active_weights()
+print(f"Selected {active['count']} of {N} households")
+print(f"Sparsity: {model.get_sparsity():.1%}")
 ```
 
-### Feature Selection
+### Key Features
+
+- **Non-negative weights**: Constrained via log-space parameterization
+- **L0 sparsity**: Directly minimizes the count of active weights
+- **Relative loss**: Scale-invariant for targets spanning orders of magnitude
+- **Group-wise averaging**: Balance loss across target groups with different sizes
+- **GPU support**: CUDA acceleration for large problems
+
+## Sparse Regression
+
+For sparse linear regression with scipy sparse matrices:
 
 ```python
-from l0 import FeatureGate
+from scipy import sparse as sp
+from l0.sparse import SparseL0Linear
 
-# Select top features
-gate = FeatureGate(n_features=1000, max_features=50)
-selected_data, feature_indices = gate.select_features(data)
+# Sparse design matrix
+X = sp.random(1000, 500, density=0.1, format="csr")
+y = np.random.randn(1000)
 
-# Get feature importance
-importance = gate.get_feature_importance()
+model = SparseL0Linear(n_features=500)
+model.fit(X, y, lambda_l0=0.001, epochs=1000)
+
+# Get sparse coefficients
+coef = model.get_coefficients(threshold=0.01)
 ```
 
-## Integration with PolicyEngine
+## Example: Variable Selection
 
-This package is designed to work with PolicyEngine's calibration system:
+The `examples/sparse_regression_demo.py` script demonstrates L0 regularization on a simple problem where the true coefficients are `[1, 0, -2, 0]`:
 
-```python
-# In policyengine-us-data or similar
-from l0 import HardConcrete
-
-# Use for household selection in CPS calibration
-gates = HardConcrete(
-    len(household_weights),
-    temperature=0.25,
-    init_mean=0.999  # Start with most households
-)
-
-# Apply gates during reweighting
-masked_weights = weights * gates()
+```bash
+python examples/sparse_regression_demo.py
 ```
 
-## Documentation
+Output:
+```
+True coefficients:        [ 1.  0. -2.  0.]
+Recovered coefficients:   [ 1.039  0.    -2.069 -0.   ]
+Gates:                    [1. 0. 1. 0.]
+```
 
-Full documentation available at: https://policyengine.github.io/L0/
+The model correctly identifies that only variables 1 and 3 contribute to the outcome.
 
 ## Testing
 
-Run tests with:
 ```bash
 pytest tests/ -v --cov=l0
 ```
 
-## Acknowledgments
-
-This implementation is inspired by and builds upon the [original L0 regularization code](https://github.com/AMLab-Amsterdam/L0_regularization) by AMLab Amsterdam, which accompanied the paper by Louizos et al. (2018).
-
 ## Citation
 
-If you use this package, please cite:
-
 ```bibtex
 @article{louizos2017learning,
   title={Learning Sparse Neural Networks through L0 Regularization},
@@ -213,4 +205,4 @@ If you use this package, please cite:
 
 ## License
 
-MIT License - see [LICENSE](LICENSE) file for details.
+MIT License - see [LICENSE](LICENSE) for details.

{l0_python-0.4.1.dist-info → l0_python-0.4.3.dist-info}/RECORD

@@ -1,12 +1,12 @@
 l0/__init__.py,sha256=ezGVLGbdU_jAElAJSdLKjSWCnZRILAZi8qMBPjcHwQc,1192
-l0/calibration.py,sha256=EnIhQPkC6yvRp0-o1qG3SCVUp6pIqwkqkx3DX3uWdG0,17838
+l0/calibration.py,sha256=3VM-28M1yp-DM6AlHX7sqZCaE7OJevpY9Ey-syjSPik,17838
 l0/distributions.py,sha256=GvVoDasdxoDlPPdzt33lFzkuJgQsfkEn9e-abxru3nM,6325
 l0/gates.py,sha256=54OORMg9qSsdbIyzYIL9t9CCHWsKbumSKl_d4-YFuNU,11443
 l0/layers.py,sha256=j_DPEFdfUc37ojtoK2ufGzVYzZ_DwusqTcJXCVxZS68,13785
 l0/penalties.py,sha256=okqXgX2eGUmg5prcDclicTQALPPPF9FA5eQP09V4GTE,9569
 l0/sparse.py,sha256=UVpkrrJBnQ9iSNDoWK5F_sr43tQareWXzYHyMq_cKss,9726
-l0_python-0.4.1.dist-info/licenses/LICENSE,sha256=LoyFJ8qmpwWPp5RmxFGHhdBxsemvp_BqGyiCgNAZHlk,1069
-l0_python-0.4.1.dist-info/METADATA,sha256=K89M7X45E5jCgA_2-YBGY238rfLlxQOUFWePoFPGiLk,6839
-l0_python-0.4.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-l0_python-0.4.1.dist-info/top_level.txt,sha256=brP2SoElgmGhNJk-qRFEQZ5UE-d1e87Tr60hSSh8n34,3
-l0_python-0.4.1.dist-info/RECORD,,
+l0_python-0.4.3.dist-info/licenses/LICENSE,sha256=LoyFJ8qmpwWPp5RmxFGHhdBxsemvp_BqGyiCgNAZHlk,1069
+l0_python-0.4.3.dist-info/METADATA,sha256=gN2ufd7zkVDielkTS2iGbUeKkf9bIMTiGZtvCkpc960,7095
+l0_python-0.4.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+l0_python-0.4.3.dist-info/top_level.txt,sha256=brP2SoElgmGhNJk-qRFEQZ5UE-d1e87Tr60hSSh8n34,3
+l0_python-0.4.3.dist-info/RECORD,,