sa-sv-duality 1.0.0__tar.gz

sa_sv_duality-1.0.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,35 @@
+---
+name: Bug report
+about: Report something that isn't working as expected
+title: "[BUG] "
+labels: bug
+assignees: ""
+---
+
+## Description
+
+A clear and concise description of the bug.
+
+## Steps to reproduce
+
+1. ...
+2. ...
+3. ...
+
+## Expected behavior
+
+What you expected to happen.
+
+## Actual behavior
+
+What actually happened (include full error messages / tracebacks if any).
+
+## Environment
+
+- Package version: (`pip show <package-name>` or `git describe --tags`)
+- Python version:
+- OS:
+
+## Additional context
+
+Anything else relevant — logs, screenshots, related issues.

sa_sv_duality-1.0.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,29 @@
+---
+name: Feature request
+about: Suggest a new feature, module, or enhancement
+title: "[FEATURE] "
+labels: enhancement
+assignees: ""
+---
+
+## Summary
+
+A clear and concise description of the feature.
+
+## Motivation
+
+Why is this needed? What problem does it solve, or what new capability
+does it enable within the GenesisAeon ecosystem?
+
+## Proposed approach
+
+How might this be implemented? (Sketches, pseudocode, references to
+related GenesisAeon packages or Diamond Interface methods are welcome.)
+
+## Alternatives considered
+
+Any alternative approaches you've thought about.
+
+## Additional context
+
+Links to relevant papers, prior discussion, or related issues/PRs.

sa_sv_duality-1.0.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,31 @@
+## Summary
+
+What does this PR do, in one or two sentences?
+
+## Related issue(s)
+
+Closes #...
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Breaking change (Diamond Interface or other public API)
+- [ ] Documentation
+- [ ] Tooling / CI / release process
+- [ ] Dependency update
+
+## Checklist
+
+- [ ] Tests added/updated and passing locally (`pytest`)
+- [ ] `CHANGELOG.md` updated under `## [Unreleased]`
+- [ ] Documentation updated (README, docstrings, notebooks if relevant)
+- [ ] If this changes `run_cycle` / `get_crep_state` / `get_utac_state` /
+      `get_phase_events` / `to_zenodo_record`: noted as a breaking change
+      and version bump plan described above
+- [ ] If this touches scientific claims/predictions: sources cited and
+      speculative vs. validated status is clear
+
+## Additional notes
+
+Anything reviewers should know.

sa_sv_duality-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,63 @@
+name: CI
+
+on:
+  push:
+    branches: ["main", "master", "claude/**"]
+  pull_request:
+    branches: ["main", "master"]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint (ruff + mypy)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dev dependencies
+        run: pip install -e ".[dev]"
+      - name: Run ruff
+        run: ruff check src tests
+      - name: Run mypy
+        run: mypy src
+
+  test:
+    name: Tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+      - name: Run pytest with coverage
+        run: pytest --cov=src --cov-report=xml
+      - name: Upload coverage
+        if: matrix.python-version == '3.11'
+        uses: codecov/codecov-action@v4
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: coverage.xml
+
+  docs:
+    name: Docs (mkdocs --strict)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dev and docs dependencies
+        run: pip install -e ".[dev,docs]"
+      - name: Build docs
+        run: mkdocs build --strict

sa_sv_duality-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,118 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+      - "v*.*.*-rc*"
+      - "v*.*.*-alpha*"
+      - "v*.*.*-beta*"
+
+permissions:
+  contents: write
+  id-token: write   # for PyPI trusted publishing, if configured
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade pip build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  test:
+    name: Run test suite
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install package with dev/test extras
+        run: |
+          python -m pip install --upgrade pip
+          if python -c "import tomllib" 2>/dev/null; then :; fi
+          pip install -e ".[dev]" 2>/dev/null || pip install -e ".[test]" 2>/dev/null || pip install -e "."
+          pip install pytest pytest-cov
+
+      - name: Run tests
+        run: pytest -q || pytest -q --no-header
+
+  publish-canary:
+    name: Publish canary (TestPyPI + pre-release)
+    needs: [build, test]
+    if: contains(github.ref_name, '-rc') || contains(github.ref_name, '-alpha') || contains(github.ref_name, '-beta')
+    runs-on: ubuntu-latest
+    environment: testpypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          password: ${{ secrets.TEST_PYPI_API_TOKEN }}
+          skip-existing: true
+
+      - name: Create GitHub pre-release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          prerelease: true
+          generate_release_notes: true
+
+  publish-production:
+    name: Publish production (PyPI + release + Zenodo archive)
+    needs: [build, test]
+    if: ${{ !contains(github.ref_name, '-rc') && !contains(github.ref_name, '-alpha') && !contains(github.ref_name, '-beta') }}
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          skip-existing: true
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          prerelease: false
+          generate_release_notes: true
+
+      # NOTE: Zenodo archival of this GitHub Release happens automatically
+      # IF this repo has Zenodo-GitHub integration enabled at
+      # https://zenodo.org/account/settings/github/ (a per-repo, per-owner
+      # OAuth toggle on zenodo.org — cannot be set from a workflow file).
+      # Once enabled, every GitHub Release like this one mints/updates a
+      # Zenodo DOI automatically using the .zenodo.json metadata in this repo.

sa_sv_duality-1.0.0/.gitignore

@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+.uv/
+
+# Testing
+.coverage
+htmlcov/
+.pytest_cache/
+
+# Docs
+site/
+
+# Editors
+.vscode/
+.idea/
+*.swp

sa_sv_duality-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,17 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: debug-statements

sa_sv_duality-1.0.0/.zenodo.json

@@ -0,0 +1,33 @@
+{
+  "title": "sa-sv-duality — P36: S_A / S_V Entropy Duality - GenesisAeon Package 36 - Standalone Foundational Module",
+  "description": "<p>S_A / S_V Entropy Duality - GenesisAeon Package 36 - Standalone Foundational Module</p><p>Part of the <strong>GenesisAeon</strong> ecosystem (P36, domain: mathematical physics / entropy duality (foundational)).</p><p>See <a href=\"https://github.com/GenesisAeon/sa-sv-duality\">github.com/GenesisAeon/sa-sv-duality</a> for source, documentation, and reproducibility notebooks.</p>",
+  "creators": [
+    {
+      "name": "Römer, Johann",
+      "affiliation": "Independent Researcher / MOR Research Collective"
+    }
+  ],
+  "license": "MIT",
+  "upload_type": "software",
+  "access_right": "open",
+  "keywords": [
+    "GenesisAeon",
+    "P36",
+    "mathematical physics / entropy duality (foundational)",
+    "UTAC",
+    "CREP",
+    "open science"
+  ],
+  "related_identifiers": [
+    {
+      "identifier": "10.5281/zenodo.19645351",
+      "relation": "isPartOf",
+      "resource_type": "publication-article",
+      "scheme": "doi"
+    }
+  ],
+  "version": "1.0.0",
+  "communities": [
+    { "identifier": "genesisaeon" }
+  ]
+}

sa_sv_duality-1.0.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [1.0.0] - 2026
+### Added
+- Initial v1.0.0 release as part of the GenesisAeon ecosystem-wide 1.0.0
+  milestone.
+- Standardized release tooling: `.zenodo.json`, GitHub Actions release
+  workflow (`.github/workflows/release.yml`), `RELEASE_GUIDE.md`,
+  `CONTRIBUTING.md`, issue/PR templates.
+
+### Changed
+- Project metadata (`pyproject.toml`) normalized: version bumped from
+  0.1.0 to 1.0.0.

sa_sv_duality-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,49 @@
+# Contributing
+
+Thanks for your interest in contributing to this GenesisAeon ecosystem
+package!
+
+## Getting started
+
+1. Fork and clone the repository.
+2. Create a virtual environment: `python -m venv .venv && source .venv/bin/activate`
+   (or `.venv\Scripts\activate` on Windows).
+3. Install in editable mode with dev dependencies:
+   `pip install -e ".[dev]"` (or `.[test]` if `dev` extras don't exist).
+4. Run the test suite: `pytest`.
+
+## Code style
+
+- Format with `ruff format` and lint with `ruff check`.
+- Type-check with `mypy` where the package uses type hints.
+- Keep functions documented with docstrings (Google or NumPy style,
+  whichever this repo already uses).
+
+## Diamond Interface packages
+
+If this package implements the GenesisAeon Diamond Interface
+(`run_cycle`, `get_crep_state`, `get_utac_state`, `get_phase_events`,
+`to_zenodo_record`), any change to these methods' signatures or return
+shapes is a **breaking change** and requires a MAJOR version bump (see
+`RELEASE_GUIDE.md`).
+
+## Pull requests
+
+- One logical change per PR.
+- Add or update tests for any behavioral change.
+- Update `CHANGELOG.md` under an `## [Unreleased]` section.
+- Fill out the PR template (`.github/PULL_REQUEST_TEMPLATE.md`).
+
+## Reporting issues
+
+Please use the issue templates in `.github/ISSUE_TEMPLATE/` — they help us
+triage bug reports vs. feature requests quickly.
+
+## Scientific claims
+
+This is part of a research framework. If your contribution touches any
+scientific model, prediction, or benchmark (e.g. CREP `Γ` values, UTAC
+parameters, falsifiable predictions), please:
+- Cite the source (paper, dataset, or prior GenesisAeon Zenodo record).
+- Clearly mark speculative vs. validated claims, consistent with this
+  repo's existing `DISCLAIMER.md` (if present).

sa_sv_duality-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JohannRömer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sa_sv_duality-1.0.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: sa-sv-duality
+Version: 1.0.0
+Summary: S_A / S_V Entropy Duality - GenesisAeon Package 36 - Standalone Foundational Module
+Project-URL: Homepage, https://github.com/GenesisAeon/sa-sv-duality
+Project-URL: Repository, https://github.com/GenesisAeon/sa-sv-duality
+Project-URL: Zenodo, https://doi.org/10.5281/zenodo.17472834
+Author: Johann Roemer - MOR Research Collective
+License: MIT
+License-File: LICENSE
+Keywords: CREP,GenesisAeon,UTAC,duality,entropy,mathematical-physics
+Classifier: Development Status :: 3 - Alpha
+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 :: Physics
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: scipy>=1.12.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.7.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
+Requires-Dist: mkdocs>=1.6.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# sa-sv-duality
+
+**S_A / S_V Entropy Duality** -- GenesisAeon Package 36
+
+[![CI](https://github.com/GenesisAeon/sa-sv-duality/actions/workflows/ci.yml/badge.svg)](https://github.com/GenesisAeon/sa-sv-duality/actions/workflows/ci.yml)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Zenodo](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.17472834-blue)](https://doi.org/10.5281/zenodo.17472834)
+
+Standalone foundational module implementing the duality between **Action Entropy** (S_A)
+and **Volume Entropy** (S_V) -- the mathematical core underlying diffusive routing (P30),
+the unified GenesisAeon Lagrangian, and the AFET field equations.
+
+---
+
+## The Duality
+
+```
+S_A  =  integral of sigma_s(H,Gamma) dt    (entropy produced along a path)
+S_V  =  -integral p(H) ln p(H) dH          (Shannon entropy of state distribution)
+
+S_A * S_V = const  (along the optimal UTAC trajectory)
+```
+
+**Lagrangian interpretation:**
+
+```
+L = T - V + Phi(H) + Gamma(C,R,E,P)
+         ^^^^^^^^^^   ^^^^^^^^^^^^^
+         S_A coupling  S_V coupling
+```
+
+The variational principle `delta(S_A - lambda * S_V) = 0` reproduces the UTAC ODE --
+this is the deepest formulation of the GenesisAeon dynamics.
+
+---
+
+## Installation
+
+```bash
+pip install sa-sv-duality
+# or
+uv tool install sa-sv-duality
+```
+
+## Usage
+
+### CLI
+
+```bash
+# Run a full S_A/S_V cycle (Gamma = 0.251, sigma = 2.2)
+sav run
+
+# Custom parameters
+sav run --gamma 0.46 --sigma 2.2 --duration 20
+
+# Show S_A, S_V for all 16 Q4 states
+sav q4-map
+
+# Find the optimal entropy path through Q4 state space
+sav route 0 15 --lambda 1.0
+
+# Run benchmarks
+sav benchmark
+sav benchmark --fast
+```
+
+### Python API
+
+```python
+from sa_sv_duality import SAVDuality, ActionEntropy, VolumeEntropy, Q4SAVMap
+
+# Full Diamond interface
+system = SAVDuality(gamma=0.251, sigma=2.2)
+result = system.run_cycle(duration_years=10.0)
+print(result["S_A"], result["S_V"], result["duality_constant"])
+
+# CREP state
+print(system.get_crep_state())  # {"C": ..., "R": ..., "E": ..., "P": ..., "Gamma": 0.251}
+
+# Q4 entropy map
+q4 = system.q4_entropy_map()   # {0: (S_A, S_V), ..., 15: (S_A, S_V)}
+
+# Optimal path through Q4 space (= diffusive routing from P30)
+path = system.optimal_path(start=0, end=15)
+
+# Zenodo-compatible record
+record = system.to_zenodo_record()
+
+# Lower-level components
+ae = ActionEntropy()
+t, H = ae.generate_trajectory(H0=0.1, T=10.0)
+S_A = ae.integrate(H.tolist(), times=t.tolist())
+
+sv = VolumeEntropy()
+S_V = sv.from_trajectory(H.tolist())
+print(S_A * S_V)   # duality constant
+```
+
+## Module Structure
+
+```
+src/sa_sv_duality/
+  __init__.py           -- public API
+  constants.py          -- Phi, sigma_UTAC, Gamma_universal, Q4 constants
+  action_entropy.py     -- S_A = integral sigma_s(H,Gamma) dt
+  volume_entropy.py     -- S_V = -integral p*ln(p) + Q4 discrete entropies
+  duality_relation.py   -- S_A * S_V conservation + hyperbola geometry
+  lagrangian_bridge.py  -- Phi(H) = S_A coupling, Gamma = S_V coupling
+  variational.py        -- delta(S_A - lambda*S_V) = 0 solver
+  q4_sav_map.py         -- (S_A, S_V) for all 16 Q4 states
+  network_routing.py    -- SAV-optimal routing via modified Dijkstra
+  system.py             -- Diamond interface (run_cycle, CREP/UTAC state)
+  cli.py                -- `sav` CLI
+  benchmark.py          -- Package 36 benchmark targets
+```
+
+## Q4 State Entropy Map
+
+Each of the 16 Q4 states (4-bit encoding of C/R/E/P activation) carries
+a characteristic (S_A, S_V) pair:
+
+| State | Bits | S_V    | Meaning                    |
+|-------|------|--------|----------------------------|
+| 0     | 0000 | 0.000  | No active channels          |
+| 1     | 0001 | 0.693  | C only (coherence)          |
+| 15    | 1111 | 1.609  | All channels active         |
+
+S_V ordering: monotone non-decreasing with number of active bits.
+S_A ordering: depends on effective Gamma of each state.
+
+## Benchmark Targets (from Feldtheorie Preprint)
+
+| Target                          | Expected | Tolerance |
+|---------------------------------|----------|-----------|
+| duality_constant_stability      | True     | --        |
+| routing_improvement_vs_dijkstra | 10%      | +/-8%     |
+| q4_entropy_ordering             | True     | --        |
+| lagrangian_consistency          | True     | --        |
+| variational_minimum             | True     | --        |
+
+## Connection to Other Packages
+
+| Package | Connection |
+|---------|-----------|
+| P30 diffusive-routing | route = argmin S_A + argmax S_V |
+| P31 vrig-cosmological | v_RIG = information-geometric speed in S_A/S_V space |
+| P32 beta-clustering   | beta_domain proportional to S_A/S_V ratio |
+| P34 afet-tensions     | H0_eff(beta) driven by S_A / S_V hierarchy |
+| P37 eml-utac-bridge   | EML operator encodes L = T-V + S_A + S_V |
+| P38 phi-validator     | Phi^(1/3) scaling in S_A/S_V Q4 entropy ratios |
+
+## Development
+
+```bash
+git clone https://github.com/GenesisAeon/sa-sv-duality.git
+cd sa-sv-duality
+uv sync --dev
+uv run pytest
+```
+
+## Citation
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.PLACEHOLDER.svg)](https://doi.org/10.5281/zenodo.PLACEHOLDER)
+
+DOI will be assigned automatically on first GitHub Release once
+Zenodo–GitHub integration is enabled for this repo.
+
+---
+
+**Reference:** Johann Roemer * MOR Research Collective * Mai 2026
+DOI: [10.5281/zenodo.17472834](https://doi.org/10.5281/zenodo.17472834)
+UTAC v1.0: [10.5281/zenodo.17472834](https://doi.org/10.5281/zenodo.17472834)