Metadata-Version: 2.4
Name: sigma-c-framework
Version: 2.1.0
Summary: Critical Susceptibility Framework for Quantum, GPU, Financial, Climate, Seismic, and Magnetic analysis
Author-email: ForgottenForge <info@forgottenforge.xyz>
License: AGPL-3.0-or-later OR Commercial
Project-URL: Homepage, https://github.com/forgottenforge/sigmacore
Project-URL: Documentation, https://github.com/forgottenforge/sigmacore/blob/main/DOCUMENTATION.md
Project-URL: Repository, https://github.com/forgottenforge/sigmacore
Project-URL: Issues, https://github.com/forgottenforge/sigmacore/issues
Keywords: critical-phenomena,phase-transitions,quantum-computing,gpu-optimization,financial-analysis,climate-science,seismology,susceptibility
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Programming Language :: C++
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.txt
License-File: license_AGPL.txt
License-File: license_COMMERCIAL.txt
Requires-Dist: numpy>=1.20.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: tqdm>=4.60.0
Requires-Dist: matplotlib>=3.4.0
Requires-Dist: seaborn>=0.11.0
Requires-Dist: requests>=2.25.0
Requires-Dist: yfinance>=0.1.63
Requires-Dist: pynvml>=11.0.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: quantum
Requires-Dist: amazon-braket-sdk>=1.9.0; extra == "quantum"
Provides-Extra: gpu
Requires-Dist: cupy>=9.0.0; extra == "gpu"
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: black>=21.0; extra == "dev"
Requires-Dist: mypy>=0.900; extra == "dev"
Dynamic: license-file

# Sigma-C Framework v2.1.0

**Universal Criticality Analysis & Active Control System**

[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
[![Version](https://img.shields.io/badge/version-2.1.0-green.svg)](https://pypi.org/project/sigma-c-framework/)
[![Status](https://img.shields.io/badge/status-production-success.svg)]()

## Overview

Sigma-C is a framework for detecting and analyzing **critical phase transitions** across physical, computational, and data-driven systems. It provides a unified susceptibility-based approach: sweep a control parameter, compute the response function (susceptibility), and locate the critical point where the system transitions between qualitatively different regimes.

The core idea is simple: for any system with a tunable parameter and a measurable observable, the susceptibility `chi = dO/d(epsilon)` peaks at the critical point `sigma_c`. The sharpness of that peak (`kappa`) quantifies how pronounced the transition is.

### Peer-Reviewed Application

The methodology behind Sigma-C has been validated in a peer-reviewed publication:

> **"Operational scale detection in quantum magnetism"**
> AVS Quantum Science, Volume 8, Issue 1, Article 013804 (2026)
> [https://doi.org/10.1116/5.0254846](https://doi.org/10.1116/5.0254846)

This paper demonstrates the framework's application to **quantum computing on real hardware** (Rigetti Ankaa-3), where Sigma-C successfully identifies the critical noise threshold at which quantum algorithms lose their advantage over classical computation. The detected critical point (`sigma_c = 0.070 +/- 0.009`) and correlation length (`xi_c = 8.00 +/- 0.50 qubits`) are consistent with theoretical predictions from quantum error correction theory.

## Core Capabilities

- **Susceptibility Analysis**: Detect critical points via `chi = dO/d(epsilon)` with Gaussian kernel smoothing
- **Active Control**: PID controller to maintain systems at or near critical points
- **Streaming Computation**: O(1) real-time susceptibility updates using Welford's algorithm
- **Observable Discovery**: Automatic identification of optimal order parameters
- **Multi-Scale Analysis**: Wavelet-based criticality detection across scales
- **Statistical Rigor**: Jonckheere-Terpstra trend tests, isotonic regression with bootstrap CI
- **High-Performance Core**: Optional C++ backend via pybind11, CUDA acceleration via CuPy

## Domain Adapters

| Domain | Adapter | Key Methods |
|--------|---------|-------------|
| Quantum | `QuantumAdapter` | Noise sweep, depth scaling, idle sensitivity, Fisher information |
| GPU/HPC | `GPUAdapter` | Cache transition detection, roofline analysis, thermal throttling |
| Finance | `FinancialAdapter` | Hurst exponent, GARCH(1,1) volatility, order flow imbalance |
| Climate | `ClimateAdapter` | Mesoscale boundary detection, vertical stability analysis |
| Seismic | `SeismicAdapter` | Gutenberg-Richter b-value, Omori aftershock scaling |
| Magnetic | `MagneticAdapter` | Critical exponents (beta, gamma, alpha), finite size scaling |
| ML | `MLAdapter` | Training robustness, learning rate sensitivity |
| Edge/IoT | `EdgeAdapter` | Power efficiency phase transitions |
| LLM Cost | `LLMCostAdapter` | Cost-quality Pareto frontier analysis |

## Integrations

| Category | Integration | Description |
|----------|------------|-------------|
| **Quantum** | Qiskit | Circuit noise sensitivity analysis |
| | PennyLane | VQA criticality tracking device |
| | Cirq | Circuit optimization for stability |
| | AWS Braket | Native quantum hardware adapter |
| **ML Frameworks** | PyTorch | `CriticalModule` with activation tracking |
| | TensorFlow | `SigmaCCallback` for Keras training |
| | JAX | `critical_jit` decorator, `CriticalOptimizer` |
| | CUDA/CuPy | GPU-accelerated susceptibility computation |
| **APIs** | REST | FastAPI endpoint (`SigmaCAPI`) |
| | GraphQL | Strawberry + built-in zero-dep resolver |
| | WASM | Browser-native JS module generator |
| **Monitoring** | Grafana | Prometheus metrics export (push + pull) |
| | Kubernetes | Pod criticality monitoring + autoscaling |
| | GitHub Actions | AST-based code complexity CI gate |
| **Finance** | QuantLib | Black-Scholes with criticality adjustment |
| | Zipline | Crash avoidance trading strategy |
| **Platforms** | Home Assistant | Smart home criticality sensor |
| | VSCode | Real-time code complexity status bar |
| **Reporting** | LaTeX | Publication-ready tables, figures, reports |
| **Bindings** | Julia | `SigmaC.jl` native binding |
| | Mathematica | `SigmaC.m` Wolfram Language binding |
| | Lean 4 | `SigmaC.lean` theorem prover binding |

## Installation

```bash
# Core framework
pip install sigma-c-framework

# With quantum integrations
pip install sigma-c-framework[quantum]

# With GPU acceleration
pip install sigma-c-framework[gpu]
```

## Quick Start

### Detecting a Phase Transition (Ising Model)

```python
import numpy as np
from sigma_c import Universe

# Generate synthetic magnetization data across temperatures
temperatures = np.linspace(1.5, 3.5, 50)
Tc = 2.269  # Exact 2D Ising critical temperature
magnetization = np.where(
    temperatures < Tc,
    np.abs(Tc - temperatures)**0.125,
    0.01 * np.random.randn(np.sum(temperatures >= Tc))
)

# Find the critical point using susceptibility analysis
mag = Universe.magnetic()
result = mag.compute_susceptibility(temperatures, magnetization)

print(f"Detected Tc:    {result['sigma_c']:.3f}")
print(f"Theoretical Tc: {Tc}")
print(f"Peak sharpness: {result['kappa']:.1f}")
```

### Quantum Noise Threshold Detection

```python
import numpy as np
from sigma_c import Universe

qpu = Universe.quantum(device='simulator')
result = qpu.run_optimization(
    circuit_type='grover',
    epsilon_values=np.linspace(0.0, 0.25, 20),
    shots=1000
)

print(f"Critical noise level: {result['sigma_c']:.4f}")
print(f"Peak clarity (kappa): {result['kappa']:.1f}")
# Above sigma_c, Grover's algorithm loses quantum advantage
```

### Financial Volatility Regime Detection

```python
import numpy as np
from sigma_c import Universe

fin = Universe.finance()
returns = np.random.randn(1000) * 0.02  # Simulated daily returns

# GARCH(1,1) volatility clustering analysis
garch = fin.analyze_volatility_clustering(returns)
print(f"Persistence: {garch['persistence']:.3f}")
print(f"Regime:      {'Critical' if garch['persistence'] > 0.95 else 'Stable'}")
```

## Examples

The `examples/v4/` directory contains 12 demo files covering every module:

| Demo | Covers |
|------|--------|
| `demo_quantum.py` | Quantum noise threshold detection |
| `demo_finance.py` | GARCH volatility, Hurst exponent |
| `demo_climate.py` | Atmospheric mesoscale boundary |
| `demo_magnetic.py` | 2D Ising Curie temperature |
| `demo_seismic.py` | Gutenberg-Richter b-value |
| `demo_gpu.py` | GPU cache transition, roofline |
| `demo_diagnostics.py` | Universal diagnostics system |
| `demo_integrations.py` | GraphQL, CI, REST, WASM, HA, TF, LaTeX, Bridge |
| `demo_ml_frameworks.py` | PyTorch, JAX, CUDA, TensorFlow |
| `demo_quantum_connectors.py` | Qiskit, PennyLane, Cirq |
| `demo_edge_llm.py` | Edge IoT, ML hyperparameters, LLM cost |
| `demo_optimization.py` | ML optimizer, brute force, QuantLib, Zipline, Grafana/K8s |

All demos run locally without external services or optional dependencies.

## Documentation

- [API Reference](docs/API_REFERENCE_v2.0.md)
- [Release Notes](docs/releases/)
- [Examples](examples/v4/)

## License

**Open Source**: AGPL-3.0-or-later
**Commercial**: Contact [nfo@forgottenforge.xyz](mailto:nfo@forgottenforge.xyz)

Copyright (c) 2025 ForgottenForge.xyz
