Metadata-Version: 2.4
Name: entro-pulse
Version: 1.0.0
Summary: ENTRO-PULSE: Periodic Entropy Pulsing and Informational Wave Management in High-Velocity AI Systems
Author-email: Samir Baladi <gitdeeper@gmail.com>
License: MIT
Project-URL: Homepage, https://entro-pulse.netlify.app
Project-URL: GitHub, https://github.com/gitdeeper10/ENTRO-PULSE
Project-URL: GitLab, https://gitlab.com/gitdeeper10/ENTRO-PULSE
Project-URL: Bitbucket, https://bitbucket.org/gitdeeper-10/entro-pulse
Project-URL: Codeberg, https://codeberg.org/gitdeeper10/entro-pulse
Project-URL: DOI, https://doi.org/10.5281/zenodo.19547863
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
License-File: AUTHORS.md
Dynamic: license-file

# 💓 ENTRO-PULSE (E-LAB-09)

### Periodic Entropy Pulsing and Informational Wave Management in High-Velocity AI Systems

[![PyPI version](https://badge.fury.io/py/entro-pulse.svg)](https://pypi.org/project/entro-pulse/)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19547863.svg)](https://doi.org/10.5281/zenodo.19547863)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![Tests](https://img.shields.io/badge/tests-25%2F25-brightgreen.svg)](https://github.com/gitdeeper10/ENTRO-PULSE)
[![Coverage](https://img.shields.io/badge/coverage-89%25-yellowgreen.svg)](https://github.com/gitdeeper10/ENTRO-PULSE)
[![E-LAB](https://img.shields.io/badge/E--LAB-09-red.svg)](https://entropia-lab.netlify.app)

---

## Overview

ENTRO-PULSE introduces **Periodic Entropy Pulsing (PEP)** — a control paradigm that transforms entropy flow management from continuous suppression into a rhythmically-managed oscillatory regime.

Rather than fighting entropy accumulation reactively, PEP orchestrates it: drawing on the cardiac pulsing model, PWM principles from power electronics, and the Kuramoto model of coupled oscillator synchronization to turn system stress into a structured, predictable wave.

### Core Contributions

| Component | Full Name | Role |
|-----------|-----------|------|
| **EPWM** | Entropy Pulse Width Modulation | Adaptive duty-cycle control of entropy flow |
| **RRL** | Rhythmic Resonance Law | Anti-phase Kuramoto synchronization across agents |
| **PGC** | Pulse-Ghost Controller | Integration bridge with ENTRO-GHOST (E-LAB-08) |

### Validated Results

| Metric | ENTRO-PULSE | Baseline |
|--------|-------------|----------|
| Throughput gain | **+38.7%** | — |
| Collapse events under burst overload | **0%** | 23.4% |
| Peak network load reduction | **86.1%** | — |
| Burst survival rate | **100%** | — |

---

## Installation

```bash
pip install entro-pulse
```

---

## Quick Start

### EPWM Controller

```python
from entro_pulse import EntropyPulseController

# Initialize with angular frequency and max duty cycle
epwm = EntropyPulseController(omega=0.8, delta_max=0.7)

# Execute a control step
result = epwm.step(psi=0.85, u_base=0.1)

print(f"Duty cycle : {result.duty_cycle:.3f}")
print(f"Output     : {result.u_output:.3f}")
```

### Pulse-Ghost Controller

Integrates entropic memory traces from ENTRO-GHOST (E-LAB-08).

```python
from entro_pulse import PulseGhostController

pgc = PulseGhostController(omega=0.8, delta_max=0.7, zeta=0.65, rho=0.4)
result = pgc.step(psi=0.85, u_base=0.1)

print(f"Ghost trace : {result.ghost_trace:.3f}")
print(f"Ghost pull  : {result.ghost_pull:.3f}")
```

### Rhythmic Resonance Law — Distributed Systems

```python
from entro_pulse import RhythmicResonanceController

rrl = RhythmicResonanceController(n_agents=8, K=0.5)
phases = rrl.step(100)

r = rrl.order_parameter()   # r → 0 confirms anti-phase synchronization
print(f"Order parameter: {r:.4f}")
```

---

## Documentation

| Resource | Link |
|----------|------|
| Website | https://entro-pulse.netlify.app |
| Research Paper | https://doi.org/10.5281/zenodo.19547863 |
| API Reference | https://entro-pulse.readthedocs.io |

---

## Project Structure

```
ENTRO-PULSE/
│
├── entro_pulse/
│   ├── __init__.py
│   ├── epwm.py           # EPWM Controller  — Eq 3.1, 3.2, 4.1, 4.2
│   ├── rrl.py            # RRL Controller   — Eq 5.1, 5.2, 5.3
│   ├── pgc.py            # Pulse-Ghost Controller — Eq 6.1, 6.2, 6.3
│   └── utils.py          # Simulation utilities
│
├── tests/
│   ├── test_epwm.py      # 8 tests
│   ├── test_rrl.py       # 5 tests
│   ├── test_pgc.py       # 8 tests
│   └── test_utils.py     # 4 tests
│
├── examples/
│   ├── example_epwm.py
│   ├── example_rrl.py
│   └── example_pgc.py
│
├── results/
│   ├── daily_report_2026-04-14.txt
│   ├── weekly_report_week15_2026.txt
│   ├── monthly_report_april_2026.txt
│   ├── alerts.log
│   └── coverage_report_2026-04-14.txt
│
├── docs/
│   ├── conf.py
│   ├── index.rst
│   └── api.rst
│
├── Netlify/
│   ├── index.html
│   ├── dashboard.html
│   ├── reports.html
│   └── documentation.html
│
├── bin/
│   └── run_simulation.py
│
├── scripts/
├── data/
├── dist/
│   └── entro-pulse-1.0.0.tar.gz
│
├── pyproject.toml
├── requirements.txt
├── requirements-dev.txt
├── Dockerfile
├── Makefile
├── VERSION
├── CITATION.cff
├── AUTHORS.md
├── CHANGELOG.md
├── CONTRIBUTING.md
├── SECURITY.md
├── DEPLOY.md
├── INSTALL.md
└── COMPLETION.md
```

### Codebase Statistics

| Metric | Value |
|--------|-------|
| Python modules | 5 |
| Test files | 4 |
| Test cases | 25 / 25 passed |
| Coverage | 89% |
| Governing equations | 12+ |

---

## EntropyLab Research Program

ENTRO-PULSE is the ninth project in the **EntropyLab** series — a unified research program bridging thermodynamic entropy, Shannon information theory, and AI systems control.

| E-LAB | Project | Focus |
|-------|---------|-------|
| 01 | ENTROPIA | Theoretical foundations |
| 02 | ENTRO-AI | AI inference stability |
| 03 | ENTRO-CORE | Core entropy measurement |
| 04 | ENTRO-ENGINE | System coupling |
| 05 | ENTRO-EVO | Adaptive weighting |
| 06 | ENTRO-NET | Distributed synchronization |
| 07 | ENTRO-QUANTUM | Probabilistic states |
| 08 | ENTRO-GHOST | Entropic memory |
| **09** | **ENTRO-PULSE** | **Periodic pulsing** |
| 10 | ENTRO-MANIFESTO | Unified manifesto |

→ Program home: [entropia-lab.netlify.app](https://entropia-lab.netlify.app)

---

## Citation

```bibtex
@software{baladi2026entropulse,
  author    = {Samir Baladi},
  title     = {ENTRO-PULSE: Periodic Entropy Pulsing and Informational Wave Management
               in High-Velocity AI Systems},
  year      = {2026},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.19547863},
  note      = {EntropyLab E-LAB-09},
  url       = {https://doi.org/10.5281/zenodo.19547863}
}
```

---

## License

MIT License © 2026 Samir Baladi
Ronin Institute / Rite of Renaissance · ORCID [0009-0003-8903-0029](https://orcid.org/0009-0003-8903-0029)

---

> *"A system that pulses does not merely survive its entropy dynamics — it dances with them."*
>
> — EntropyLab Research Program
