seismic-utac 1.0.0__tar.gz

seismic_utac-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 seismic-utac` or `git describe --tags`)
+- Python version:
+- OS:
+
+## Additional context
+
+Anything else relevant — logs, screenshots, related issues.

seismic_utac-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.

seismic_utac-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.

seismic_utac-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.10", "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 dependencies
+        run: pip install -e ".[dev]"
+      - name: Build docs
+        run: mkdocs build --strict

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

@@ -0,0 +1,79 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install build tools
+        run: pip install build
+      - name: Build wheel and sdist
+        run: python -m build
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub Release
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true
+          draft: false
+          prerelease: ${{ contains(github.ref, 'alpha') || contains(github.ref, 'beta') || contains(github.ref, 'rc') }}
+
+  publish-zenodo:
+    name: Publish to Zenodo
+    needs: github-release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Upload to Zenodo
+        run: |
+          echo "Zenodo upload triggered for tag ${{ github.ref_name }}"
+          echo "Configure ZENODO_TOKEN secret and zenodraft/action for automatic upload."
+        # Replace with actual zenodo-upload action when token is configured:
+        # uses: zenodraft/action@main
+        # with:
+        #   concept-doi: 10.5281/zenodo.XXXXXXXX  # <- enter your concept DOI
+        #   token: ${{ secrets.ZENODO_TOKEN }}

seismic_utac-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

seismic_utac-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

seismic_utac-1.0.0/.zenodo.json

@@ -0,0 +1,62 @@
+{
+  "title": "seismic-utac: Earthquake Seismicity & Gutenberg-Richter SOC (GenesisAeon Package 23)",
+  "version": "1.0.0",
+  "description": "UTAC/CREP model of global earthquake seismicity. Models the Gutenberg-Richter power law as a CREP-mediated Self-Organized Critical (SOC) phenomenon. Calibrated against the IRIS 50-year global catalog (154,383 earthquakes, magnitudes 0.01–8.40, 6 global regions). Implements the Diamond interface (run_cycle, get_crep_state, get_utac_state, get_phase_events, to_zenodo_record) and yields Γ_seismic ≈ 0.200 at the crustal SOC regime (b ≈ 1.7). Part of the GenesisAeon Entropy Atlas Expansion (Packages 23–30).",
+  "keywords": [
+    "seismicity",
+    "Gutenberg-Richter",
+    "SOC",
+    "self-organized criticality",
+    "CREP",
+    "UTAC",
+    "b-value",
+    "Omori-Utsu",
+    "earthquake",
+    "geophysics",
+    "entropy",
+    "GenesisAeon",
+    "Package 23"
+  ],
+  "creators": [
+    {
+      "name": "Römer, Johann",
+      "affiliation": "MOR Research Collective"
+    }
+  ],
+  "license": "MIT",
+  "upload_type": "software",
+  "access_right": "open",
+  "related_identifiers": [
+    {
+      "identifier": "10.1029/JB094iB11p15635",
+      "relation": "isSupplementTo",
+      "scheme": "doi",
+      "resource_type": "publication-article"
+    },
+    {
+      "identifier": "10.1029/2002JB002230",
+      "relation": "isSupplementTo",
+      "scheme": "doi",
+      "resource_type": "publication-article"
+    },
+    {
+      "identifier": "10.1016/j.chaos.2020.110634",
+      "relation": "isSupplementTo",
+      "scheme": "doi",
+      "resource_type": "publication-article"
+    },
+    {
+      "identifier": "10.5281/zenodo.19645351",
+      "relation": "isDocumentedBy",
+      "scheme": "doi",
+      "resource_type": "publication"
+    },
+    {
+      "identifier": "https://github.com/GenesisAeon/seismic-utac",
+      "relation": "isSupplementedBy",
+      "scheme": "url"
+    }
+  ],
+  "language": "eng",
+  "notes": "GenesisAeon Entropy Atlas — Package 23 of 30. CREP criticality position: Γ ≈ 0.200 (crustal SOC regime). The b-value decrease before major earthquakes maps onto rising Γ — a falsifiable UTAC precursor signal testable against SCEDC real-time data."
+}

seismic_utac-1.0.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# 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.
+- Full Diamond Interface implementation on `SeismicUTAC` (`run_cycle`,
+  `get_crep_state`, `get_utac_state`, `get_phase_events`,
+  `to_zenodo_record`).
+- Governance docs: `RELEASE_GUIDE.md`, `CONTRIBUTING.md`, issue/PR
+  templates.
+
+### Changed
+- Project metadata (`pyproject.toml`, `.zenodo.json`) bumped to version
+  1.0.0.

seismic_utac-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# 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 `uv sync --dev`).
+4. Run the test suite: `pytest`.
+
+## Code style
+
+- Format and lint with `ruff` (`ruff format`, `ruff check`).
+- Type-check with `mypy` (strict mode is enabled in `pyproject.toml`).
+- Keep functions documented with docstrings.
+
+## Diamond Interface
+
+This package implements the GenesisAeon Diamond Interface
+(`run_cycle`, `get_crep_state`, `get_utac_state`, `get_phase_events`,
+`to_zenodo_record`) on `SeismicUTAC`. 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 the
+seismicity/Gutenberg-Richter SOC model (e.g. the calibrated `Γ_seismic`
+value, b-value fits, or precursor-signal claims), please:
+- Cite the source (paper, dataset, or prior GenesisAeon Zenodo record).
+- Clearly mark speculative vs. validated claims.

seismic_utac-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.

seismic_utac-1.0.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: seismic-utac
+Version: 1.0.0
+Summary: Package 23: Earthquake Seismicity & Gutenberg-Richter SOC - UTAC/CREP model (GenesisAeon)
+Project-URL: Homepage, https://github.com/GenesisAeon/seismic-utac
+Project-URL: Repository, https://github.com/GenesisAeon/seismic-utac
+Project-URL: Documentation, https://genesisaeon.github.io/seismic-utac
+Project-URL: Issues, https://github.com/GenesisAeon/seismic-utac/issues
+Project-URL: Zenodo, https://doi.org/10.5281/zenodo.XXXXXXX
+Project-URL: Bak & Tang (1989), https://doi.org/10.1029/JB094iB11p15635
+Author-email: Johann Römer <joberoemer@gmail.com>
+Maintainer-email: GenesisAeon <joberoemer@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: CREP,GenesisAeon,Gutenberg-Richter,Omori-Utsu,SOC,UTAC,b-value,earthquake,entropy,geophysics,seismicity,self-organized-criticality
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.26
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: scipy>=1.13
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: mkdocs-material>=9.5.0; extra == 'dev'
+Requires-Dist: mkdocs>=1.6.0; 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'
+Requires-Dist: types-pyyaml>=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
+
+# seismic-utac
+
+**Package 23 — Earthquake Seismicity & Gutenberg-Richter SOC**
+GenesisAeon · MOR Research Collective
+
+[![CI](https://github.com/GenesisAeon/seismic-utac/actions/workflows/ci.yml/badge.svg)](https://github.com/GenesisAeon/seismic-utac/actions/workflows/ci.yml)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org)
+[![Package 23](https://img.shields.io/badge/GenesisAeon-Package%2023-blueviolet)](https://github.com/GenesisAeon/seismic-utac)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![DOI](https://img.shields.io/badge/DOI-10.1029%2FJB094iB11p15635-orange)](https://doi.org/10.1029/JB094iB11p15635)
+
+Models global earthquake seismicity as a **UTAC (Unified Threshold-Activated Criticality)** system,
+grounding the Gutenberg-Richter power law as a CREP-mediated Self-Organized Critical (SOC)
+phenomenon. Calibrated against the IRIS 50-year global catalog (154,383 earthquakes).
+
+> Bak, P. & Tang, C. (1989). Earthquakes as a self-organized critical phenomenon.
+> *J. Geophys. Res.* 94(B11), 15,635. [DOI: 10.1029/JB094iB11p15635](https://doi.org/10.1029/JB094iB11p15635)
+
+---
+
+## CREP Criticality Position
+
+```
+Γ_seismic ≈ 0.200   (b-value = 1.7, crustal SOC regime)
+
+Spectrum:  Qubit(0.050) — Cellular(0.090) — Seismic(0.200) — AMOC/Neural(0.251) — BTW(0.296)
+```
+
+The b-value decrease before major earthquakes maps directly onto rising Γ — a falsifiable
+UTAC precursor signal.
+
+---
+
+## Install
+
+```bash
+pip install -e ".[dev]"
+# or
+uv sync --dev
+```
+
+## Quickstart
+
+```python
+from seismic_utac import SeismicUTAC
+
+system = SeismicUTAC()
+result = system.run_cycle(duration_years=50.0)
+
+print(f"Γ = {result['gamma']:.4f}")          # ≈ 0.200
+print(f"b-value = {result['b_value']:.3f}")  # ≈ 1.7
+print(f"Phase events: {len(result['phase_events'])}")
+```
+
+## CLI
+
+```bash
+# Run full 50-year UTAC cycle
+seismic-utac run --catalog iris --region global --duration 50
+
+# Monitor b-value and phase transition risk
+seismic-utac b-value-monitor --region southern-california
+
+# Forecast probability of M≥7.5 within 365 days
+seismic-utac predict --magnitude 7.5 --horizon 365
+
+# Run benchmark suite against Bak & Tang (1989) targets
+seismic-utac benchmark
+```
+
+## Diamond Interface
+
+`SeismicUTAC` implements the full GenesisAeon Diamond contract:
+
+| Method | Returns |
+|--------|---------|
+| `run_cycle(duration_years)` | Full cycle result dict |
+| `get_crep_state()` | `{C, R, E, P, Gamma}` |
+| `get_utac_state()` | `{H, dH_dt, H_star, K_eff}` |
+| `get_phase_events()` | List of M≥6.5 rupture events |
+| `to_zenodo_record()` | Zenodo-compatible metadata dict |
+
+Also: `b_value_current()`, `predict_major_event_probability(magnitude, horizon_days)`
+
+## Physical Mapping
+
+| UTAC variable | Seismic meaning |
+|---------------|----------------|
+| `H(t)` | Normalised crustal strain energy ∈ [0, 1] |
+| `H*` | Critical strain at GR rollover (b-value change point) |
+| `K` | Max energy before M8+ event (~10¹⁷ J) |
+| `Γ` | CREP tensor from b-value, foreshock clustering, entropy |
+| `r` | Tectonic strain loading rate (~0.05/year) |
+
+## Benchmark Targets
+
+| Target | Expected | Tolerance |
+|--------|----------|-----------|
+| `b_value_global` | 1.00 | ±0.10 |
+| `b_value_swarm_max` | 2.50 | ±0.30 |
+| `gamma_seismic` | 0.200 | ±0.03 |
+| `aftershock_omori_p` | 1.10 | ±0.10 |
+
+```bash
+uv run pytest tests/test_seismic_utac.py -v
+```
+
+## Repository Structure
+
+```
+seismic-utac/
+├── src/seismic_utac/
+│   ├── system.py              # SeismicUTAC — Diamond interface
+│   ├── gutenberg_richter.py   # GR law, b-value MLE (Aki 1965)
+│   ├── strain_accumulation.py # Crustal strain energy → UTAC H(t)
+│   ├── b_value_monitor.py     # Sliding-window b-value tracker
+│   ├── entropy_seismic.py     # Permutation entropy → CREP P
+│   ├── crep_seismic.py        # Seismic CREP tensor
+│   ├── aftershock.py          # Omori-Utsu aftershock model
+│   ├── catalog_loader.py      # Synthetic + YAML catalog loader
+│   ├── benchmark.py           # Bak & Tang (1989) benchmark suite
+│   ├── cli.py                 # Typer CLI
+│   └── constants.py           # SIGMA=2.2, B_SOC_TYPICAL=1.7, …
+├── data/
+│   ├── iris_catalog_summary.yaml
+│   └── bak1989_targets.yaml
+└── tests/
+    └── test_seismic_utac.py   # 17 tests, all passing
+```
+
+## References
+
+- Bak & Tang (1989). [DOI: 10.1029/JB094iB11p15635](https://doi.org/10.1029/JB094iB11p15635)
+- Al-Kindy & Main (2003). [DOI: 10.1029/2002JB002230](https://doi.org/10.1029/2002JB002230)
+- da Silva et al. (2021). [DOI: 10.1016/j.chaos.2020.110634](https://doi.org/10.1016/j.chaos.2020.110634)
+
+## 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.
+
+---
+
+Also includes the **diamond-setup** scaffold tool used to generate this project.
+Run `diamond scaffold <name>` to create new GenesisAeon packages.
+
+Built with [uv](https://docs.astral.sh/uv/) · [NumPy](https://numpy.org/) · [SciPy](https://scipy.org/) · [Typer](https://typer.tiangolo.com/) · [Rich](https://rich.readthedocs.io/)