cutlass 0.5.0

Rectified L1 logistic regression with CUTLASS critical range encoding.

CUTLASS

CUTLASS (Critical-range rectified LASSO) packages the workflow developed in the project scripts into a reusable, publishable Python library. It exposes a scikit-learn inspired estimator that rectifies the input space into {-1, +1} indicators, trains an L1-penalised logistic model with an efficient coordinate-descent solver, and optionally compresses the model into a logical rule without any dependence on scikit-learn itself. Version 0.5.0 adds an optional adaptive-L1 mode while preserving the default 0.4.0 L1 workflow.

Features

• Rectifier transformer that infers critical ranges from the positive class and binarises features into {-1, +1}.
• Cross-validated L1 logistic model with warm-started coordinate descent and optional FISTA solver.
• Adaptive-L1 mode (penalty="adaptive_l1") that fits an L2 logistic pilot, reweights the L1 penalty by abs(beta_pilot) + adaptive_eps, and maps coefficients back to the original feature scale.
• Logical compression step mirroring the research code (top-k votes with fixed magnitude K and several intercept policies).
• Serialization helpers to persist rectifier limits and fitted models.
• Lightweight implementation that depends only on NumPy and pandas (matplotlib is optional for plotting diagnostics).

Installation

pip install cutlass

The plotting utilities used by the logical compression step are optional. To enable them, install the plots extra:

pip install cutlass[plots]

Quick start

import pandas as pd
from cutlass import CutlassClassifier

# toy binary dataset
df = pd.DataFrame(
    {
        "feat_a": [0.1, 0.3, 0.7, 0.9],
        "feat_b": [10, 13, 8, 5],
        "INDC": [0, 0, 1, 1],
    }
)

X = df.drop(columns=["INDC"])
y = df["INDC"]

clf = CutlassClassifier(
    rectify=True,
    Cs=15,
    solver="cd",
    cv=3,
    logic_polish=True,
    logic_scale=10.0,
)
clf.fit(X, y)
print(clf.predict_proba(X))
print("limits:", clf.limits_)

The default penalty remains standard L1. To use the adaptive-L1 mode, pass the optional penalty argument:

adaptive_clf = CutlassClassifier(
    rectify=True,
    Cs=15,
    solver="cd",
    cv=3,
    penalty="adaptive_l1",
    adaptive_eps=1e-3,
)
adaptive_clf.fit(X, y)

Vignettes

Additional step-by-step guides live under docs/vignettes/:

• 01_basic_rectified_workflow.md – reproduce the baseline rectified L1 fit.
• 02_logical_polish.md – enable logic polishing and interpret diagnostics.
• 03_batch_experiments.md – run batched experiments and export artifacts.

API highlights

• cutlass.Rectifier: transformer implementing the critical-range binarisation.
• cutlass.CutlassLogisticCV: lower-level L1 or adaptive-L1 logistic with cross-validation.
• cutlass.CutlassClassifier: full workflow composed of the rectifier, optional scaling, and the logistic path solver. Use penalty="l1" for the default behavior or penalty="adaptive_l1" for the adaptive mode.
• cutlass.serialization: helpers for saving rectifier limits and fitted weights.

Refer to the docstrings for detailed parameter descriptions; they mirror the research scripts so existing experiment drivers can be migrated with minimal changes.

Development

To build the package locally:

python -m build

To update the project on PyPI, first bump version in pyproject.toml, commit the release changes, and create a clean source/wheel build with python -m build. After confirming the files under dist/ are correct, upload them with python -m twine upload dist/* using an account or API token that has permission to publish the cutlass package.

Run the unit tests (if any) with:

python -m pytest

License

MIT License. See LICENSE for details.