Metadata-Version: 2.4
Name: highfis
Version: 0.16.0
Summary: highFIS is a comprehensive Python package for training and evaluating high-dimensional TSK fuzzy systems, built on PyTorch and compatible with the scikit-learn API.
Project-URL: Homepage, https://github.com/dcruzf/highFIS
Project-URL: Documentation, https://dcruzf.github.io/highFIS/
Project-URL: Source, https://github.com/dcruzf/highFIS
Project-URL: Tracker, https://github.com/dcruzf/highFIS/issues
Project-URL: DOI, https://doi.org/10.5281/zenodo.19489225
Author-email: Daniel França <daniel@ci.ufpb.br>
License: GPLv3
License-File: LICENSE
Keywords: TSK,explainable ai,fuzzy logic,machine learning,neuro-fuzzy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.11
Requires-Dist: numpy<3.0,>=1.24.1
Requires-Dist: scikit-learn>=1.3
Requires-Dist: torch<3,>=2.3
Requires-Dist: tqdm>=4.65.0
Description-Content-Type: text/markdown

# highFIS

[![CI](https://github.com/dcruzf/highFIS/actions/workflows/ci.yaml/badge.svg)](https://github.com/dcruzf/highFIS/actions/workflows/ci.yaml)
[![Documentation](https://github.com/dcruzf/highFIS/actions/workflows/docs.yml/badge.svg)](https://github.com/dcruzf/highFIS/actions/workflows/docs.yml)
[![DOI](https://img.shields.io/badge/doi-10.5281%2Fzenodo.19489225-%2333CA56?logo=DOI&logoColor=white)](https://doi.org/10.5281/zenodo.19489225)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/highfis)](https://pypi.org/project/highfis/)
[![PyPI - Version](https://img.shields.io/pypi/v/highfis?color=%2333CA56)](https://pypi.org/project/highfis/)
[![PyPI - License](https://img.shields.io/pypi/l/highfis?color=%2333CA56)](https://raw.githubusercontent.com/dcruzf/highFIS/refs/heads/main/LICENSE)

highFIS is a PyTorch-based framework for high-dimensional Takagi–Sugeno–Kang
(TSK) fuzzy systems. It brings differentiable fuzzy inference, numerical
stability, and sklearn-compatible estimators to both classification and
regression. The library also includes DGTSK dynamic-gating models for feature
and rule selection in high-dimensional fuzzy systems.

## 🚀 Overview

- Differentiable TSK fuzzy systems built for high-dimensional data.
- Supports both concrete PyTorch model classes and sklearn-compatible estimators.
- Includes adaptive and gated inference variants for feature selection and
  sparse rule extraction.
- Designed for numerical stability with log-space and inverse-log defuzzifiers.

## 📦 Installation

Install from PyPI:

```bash
pip install highfis
```

## 🧠 Quick Start

```python
from highfis import HTSKClassifier

clf = HTSKClassifier(
    n_rules=10,
    mf_init="kmeans",
    epochs=150,
    learning_rate=1e-3,
    random_state=42,
)
clf.fit(X_train, y_train)
print(f"Test accuracy: {clf.score(X_test, y_test):.4f}")
```

highFIS integrates with `sklearn.pipeline.Pipeline`, `GridSearchCV`, and
`cross_val_score`.

## 🧩 Model families

highFIS provides a full family of TSK models, each tuned for a specific
high-dimensional inference strategy.

- `TSK` — vanilla TSK with product antecedent aggregation and sum-based
  normalization.
- `HTSK` — high-dimensional TSK with geometric mean aggregation and log-space
  normalization.
- `LogTSK` — log-domain inverse-log normalization for stable aggregation.
- `MHTSK` — multihead sparse TSK with feature-subset heads and sparse consequents.
- `DombiTSK` — Dombi T-norm aggregation with a learnable shape parameter.
- `ADMTSK` — adaptive Dombi TSK with dimension-dependent Gaussian membership functions.
- `AYATSK` — Yager T-norm aggregation for flexible antecedent behavior.
- `ADATSK` — adaptive softmin-style inference with dynamic rule weighting.
- `ADPTSK` — adaptive double-parameter softmin inference with stable normalized rule weights.
- `FSRE-ADATSK` — adaptive model with gated feature selection and rule extraction.
- `DGTSK` — double-gated training for feature selection and rule extraction.
- `DGALETSK` — adaptive Ln-Exp softmin with embedded feature and rule gates.
- `HDFIS` — high-dimensional inference with product T-norm (`HDFISProd`) and minimum T-norm (`HDFISMin`) variants.

Each family exposes classifier and regressor variants.

## 🔧 Core components

highFIS exposes a compact, model-family-driven API with both concrete
model classes and sklearn-compatible estimator wrappers.

- Model families: `TSK`, `HTSK`, `LogTSK`, `MHTSK`, `DombiTSK`, `ADMTSK`,
  `AYATSK`, `ADATSK`, `ADPTSK`, `FSRE-ADATSK`, `DGTSK`, `DGALETSK`,
  `HDFIS`
- Estimators: `*Classifier` and `*Regressor` variants for each model family,
  accessible directly from `import highfis`
- Building blocks: membership functions (`highfis.memberships`), defuzzifiers
  (`highfis.defuzzifiers`), T-norms (`highfis.t_norms`), and PyTorch model
  classes (`highfis.models`)

For the full class list and API reference, see the documentation:

- [Models](https://dcruzf.github.io/highFIS/latest/api/models)
- [Estimators](https://dcruzf.github.io/highFIS/latest/api/estimators)

## 🛠️ Training options

highFIS uses gradient-based optimization and supports:

- adaptive optimizers like Adam/W and standard SGD
- early stopping with validation
- uniform rule regularization for balanced rule activation
- custom T-norms, custom rule bases, and custom defuzzifiers

## 📚 Documentation

The published documentation is available at:

https://dcruzf.github.io/highFIS

Key reference pages:

- [TSK Vanilla](https://dcruzf.github.io/highFIS/latest/models/tsk-vanilla)
- [LogTSK](https://dcruzf.github.io/highFIS/latest/models/logtsk)
- [AYATSK](https://dcruzf.github.io/highFIS/latest/models/ayatsk)
- [HTSK](https://dcruzf.github.io/highFIS/latest/models/htsk)
- [DombiTSK](https://dcruzf.github.io/highFIS/latest/models/dombitsk)
- [ADPTSK](https://dcruzf.github.io/highFIS/latest/models/adptsk)
- [ADMTSK](https://dcruzf.github.io/highFIS/latest/models/admtsk)
- [ADATSK](https://dcruzf.github.io/highFIS/latest/models/adatsk)
- [DGTSK](https://dcruzf.github.io/highFIS/latest/models/dg-tsk)
- [DG-ALETSK](https://dcruzf.github.io/highFIS/latest/models/dg-aletsk)
- [FSRE-ADATSK](https://dcruzf.github.io/highFIS/latest/models/fsre-adatsk)
- [MHTSK](https://dcruzf.github.io/highFIS/latest/models/mhtsk)
- [HDFIS](https://dcruzf.github.io/highFIS/latest/models/hdfis)

## 🧪 Testing & quality

Run the test suite with coverage:

```bash
hatch test -c -a
```

Format and lint the repository:

```bash
hatch fmt
```

Run static type checks:

```bash
hatch run typing
```

## 🤝 Contributing

Contributions are welcome! Please open issues or pull requests, and refer to
our development guide in the documentation: [contributing](https://dcruzf.github.io/highFIS/latest/contributing/).

## 📄 License

Distributed under the [GPLv3](LICENSE).
