Metadata-Version: 2.4
Name: QSignature
Version: 1.0.4
Summary: Data Physics Framework for Physical Systems
Author-email: Ahmad Muhammad <ahmadmuhammad325@gmail.com>, Salim Jibrin Danbatta <salimdambatta@gmail.com>, Muhammad Abubakar Isah <maisah@ticaret.edu.tr>, Ibrahim Yahaya Muhammad <ibrahimyahayamuhammad@gmail.com>, Sulaiman Sulaiman Ahmad <Sulaiman365@gmail.com>, Abdelrahman Ghozlan <aamghuzlan@gmail.com>, Ahmet Sait AlAli <saitnuclear@gmail.com>
Maintainer-email: Ahmad Muhammad <ahmadmuhammad325@gmail.com>, Salim Jibrin Danbatta <salimdambatta@gmail.com>
License: MIT License
Project-URL: Homepage, https://github.com/1030ahmad1030/QSignature
Project-URL: Repository, https://github.com/1030ahmad1030/QSignature
Project-URL: Documentation, https://qsignature.readthedocs.io
Project-URL: Issues, https://github.com/1030ahmad1030/QSignature/issues
Project-URL: Paper (ISDFS 2026), https://ieeexplore.ieee.org/document/11459049
Project-URL: Paper (Theorems), https://www.researchsquare.com/article/rs-8916580/v1
Keywords: signal-processing,time-series,dynamical-systems,classification,centroid,envelope,lambda,qspace,causal-inference,system-identification,data-physics,pdf-analysis,entropy,peak-detection
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy>=1.21.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: matplotlib>=3.4.0
Requires-Dist: scikit-learn>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: isort>=5.0.0; extra == "dev"
Requires-Dist: flake8>=5.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=5.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
Requires-Dist: sphinxcontrib-bibtex>=2.0.0; extra == "docs"
Requires-Dist: nbsphinx>=0.9.0; extra == "docs"
Dynamic: license-file

# QSignature

**Model-free dynamical regime classification for time series data.**

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19984222.svg)](https://doi.org/10.5281/zenodo.19984222)
[![PyPI version](https://badge.fury.io/py/QSignature.svg)](https://badge.fury.io/py/QSignature)
[![Documentation Status](https://readthedocs.org/projects/qsignature/badge/?version=latest)](https://qsignature.readthedocs.io/)

---
## 🙏 Acknowledgments

This work was developed with the assistance of **DeepSeek AI**, which provided technical guidance, code review, and documentation support throughout the development of the QSignature framework.

---

## 🤝 Contributing

Contributions are welcome! Please see our [Contributing Guidelines](CONTRIBUTING.md).

---

## 📄 License

MIT License — see [LICENSE.txt](LICENSE.txt) for details.


## 📖 Overview

**QSignature** is a **Data Physics framework** that extracts physical signatures from causal response signals — **without assuming any model**. It transforms raw time-series data into diagnostic fingerprints that reveal the underlying physical regime, memory structure, and dynamical properties.

**Key Capabilities:**
- **Model-Free** — No assumptions about system order, linearity, or excitation
- **Data-Driven** — Extracts everything directly from the signal
- **Universal** — Works for any causal response data
- **Interpretable** — Each diagnostic has clear physical meaning

---

## 🚀 Quick Start

```python
import numpy as np
from QSignature import compute_all, QPDF, QSpace, QSynthetic

# Generate synthetic data
t = np.linspace(0, 10, 1000)
R = QSynthetic.physical.exponential_step(t, tau=2.0, R_inf=1.0)

# Core analysis — timescales and ratios
results = compute_all(t, R)
print(f"τ_s = {results['tau_s']:.4f}")
print(f"τ_u = {results['tau_u']:.4f}")
print(f"Δ_su = {results['Delta_su']:.4f}")
print(f"ρ₂₃ = {results['rho_23']:.4f}")

# Full signature with PDF analysis
results = compute_all(t, R, return_pdf=True)
print(f"PDF Shape: {results['pdf_shape']}")
print(f"Entropy: {results['entropy']:.4f}")
print(f"Time Signature: {results['time_signature']['signature']}")
