QSignature 1.0.5

Data Physics Framework for Physical Systems

like this...

QSignature

Data Physics Framework.

---

📖 Overview

QSignature is a Data Physics framework that extracts physical signatures from causal response data (R(t)) — without any formal assumption or imporsing constraints. It transforms raw response 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 Physics directly from response data R(t)
• Universal — Works for any causal response signal
• Interpretable — Every output has a clear physical meaning

---

🚀 Quick Start

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']}")

---

📦 Installation

pip install QSignature

For development installation:

git clone https://github.com/1030ahmad1030/QSignature.git
cd QSignature
pip install -e .

---

🧩 Modules

Module	Description
QSignature Core	8 timescale estimators, 3 higher moments, 18 diagnostic ratios
QPDF	Probability Density Function analysis (entropy, peaks, confidence)
QSpace	Universal landscape mapping and system classification
QSynthetic	Synthetic data generation from canonical systems

---

📊 Core Estimators

Timescales (8)

Estimator	Definition	Meaning
τ_s	Signed centroid (fallback)	Step-response specific
τ_s2	Signed centroid (pure)	Response-agnostic
τ_s3	Signed centroid (hybrid)	Best for oscillatory systems
τ_u	Unsigned centroid	Always positive, robust
τ_2	Step-response	Lag area
τ_3	Autocorrelation	Memory horizon
τ_pole	Spectral pole	Frequency domain
τ_g	Generalized persistence	State-based persistence

Higher Moments (3)

Moment	Meaning
τ_u2	Variance (spread)
τ_u3	Skewness (asymmetry)
τ_u4	Kurtosis (tailedness)

Diagnostic Ratios (18)

Category	Ratios
Oscillation & Direction	Δ_su, Δ_su2, Δ_su3, R_su, R_su2, R_su3
Memory Type	ρ₁₃, ρ₁₃_s2, ρ₁₃_s3, ρᵤ₃, ρ₂₃
Step Consistency	ρ₁₂, ρ₁₂_s2, ρ₁₂_s3
Shape Diagnostics	κ_u, γ_u, β_u
Shape vs Memory	ρᵤ₂,₃, ρᵤ₃,₃, ρᵤ₄,₃

---

📈 Full Signature (64 Features)

# Get everything — QSignature + QPDF + Time Signature
results = compute_all(t, R, return_pdf=True)

# Access all features
print(f"τ_s = {results['tau_s']:.4f}")
print(f"Δ_su = {results['Delta_su']:.4f}")
print(f"PDF Shape: {results['pdf_shape']}")
print(f"Entropy: {results['entropy']:.4f}")
print(f"Peaks: {results['n_peaks']}")
print(f"Time Signature: {results['time_signature']['signature']}")

---

📚 Documentation

• Official Docs: https://qsignature.readthedocs.io/
• GitHub: https://github.com/1030ahmad1030/QSignature
• PyPI: https://pypi.org/project/QSignature/

Papers

• QSignature 1.0 Framework: IEEE ISDFS 2026
• Theorems for Environmental Signature: Research Square

---

🛠️ Requirements

• Python >= 3.9
• numpy >= 1.21.0
• scipy >= 1.7.0
• pandas >= 1.3.0
• matplotlib >= 3.4.0
• scikit-learn >= 1.0.0

---

👥 Contributors

The QSignature framework was developed by:

Name	Role	Affiliation
Ahmad Muhammad	Lead Developer	Data Physics Research Group
Salim Jibrin Danbatta	Software Engineering	Uskudar University
Muhammad Abubakar Isah	Mathematics	Istanbul Ticaret Universitesi
Ibrahim Yahaya Muhammad	Theoretical & Computational Physics	KMUTT
Sulaiman Sulaiman Ahmad	Electrical Engineering	KFUPM
Abdelrahman Ghozlan	Physics and Materials Sciences	Qatar University
Ahmet Sait ALALI	Department of Physics	Istanbul Technical University, Istanbul, Turkiye
Faiz Ahmed Mohammed Elfaki	Mathematics and Statistics	Qatar University
Asmau Abdullahi	Physics and Materials Sciences	Qatar University
Aisha Farida Ahmed	Computer Science	Kano State Polytechnic, Nigeria
Abdulsalam Ahmed Kawu	Department of Physics	Federal University Kashere, Gombe, Nigeria
DeepSeek AI	Technical Guidance, Code Review & Documentation	DeepSeek AI

---

📄 License

MIT License — see LICENSE.txt for details.

---

📝 Citation

If you use QSignature in your research, please cite:

@inproceedings{qsignature2026_isdfs,
  title={QSignature 1.0: A Dynamical Regime Classification Framework for Causal Time Series Data},
  author={Muhammad, Ahmad and Danbatta, Salim Jibrin and Isah, Muhammad Abubakar and others},
  booktitle={IEEE ISDFS 2026},
  year={2026}
}