amoc-utac 1.0.0__tar.gz

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

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

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

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

@@ -0,0 +1,48 @@
+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)
+    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 amoc_utac tests
+
+  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=amoc_utac --cov-report=xml -v
+      - name: Upload coverage
+        if: matrix.python-version == '3.11'
+        uses: codecov/codecov-action@v4
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: coverage.xml

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

amoc_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

amoc_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

amoc_utac-1.0.0/.zenodo.json

@@ -0,0 +1,33 @@
+{
+  "title": "amoc-utac — P18: AMOC collapse early warning — GenesisAeon Package 18 (UTAC/CREP dynamical system)",
+  "description": "<p>AMOC collapse early warning — GenesisAeon Package 18 (UTAC/CREP dynamical system). The UTAC-Logistic ODE identifies critical thresholds in Atlantic Meridional Overturning Circulation (AMOC) strength time series, enabling early-warning detection of potential collapse events; CREP metrics characterise coherence and emergence in thermohaline circulation dynamics.</p><p>Part of the <strong>GenesisAeon</strong> ecosystem (P18, domain: oceanography / AMOC tipping). Within the GenesisAeon CREP Criticality Spectrum, this package's characteristic coupling value is Γ ≈ 0.251.</p><p>See <a href=\"https://github.com/GenesisAeon/amoc-utac\">github.com/GenesisAeon/amoc-utac</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",
+    "P18",
+    "oceanography / AMOC tipping",
+    "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" }
+  ]
+}

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

amoc_utac-1.0.0/CITATION.cff

@@ -0,0 +1,65 @@
+cff-version: 1.2.0
+message: >
+  If you use amoc-utac in your research, please cite both this software
+  and the primary reference (van Westen et al. 2024).
+
+title: "amoc-utac — Atlantic Meridional Overturning Circulation Collapse Early Warning"
+version: 0.1.0
+date-released: "2026-04-23"
+license: MIT
+repository-code: "https://github.com/genesisaeon/amoc-utac"
+
+authors:
+  - family-names: Römer
+    given-names: Johann
+    affiliation: "MOR Research Collective"
+
+abstract: >
+  GenesisAeon Package 18. Models the Atlantic Meridional Overturning
+  Circulation (AMOC) as a UTAC dynamical system with CREP tensor coupling.
+  Central result: Γ_AMOC = arctanh(η=0.50) / σ=2.2 ≈ 0.251, placing AMOC
+  in the medium-CREP regime and establishing cross-domain universality with
+  neural criticality (Package 20) at the 50% homeostatic efficiency setpoint.
+
+keywords:
+  - AMOC
+  - tipping point
+  - UTAC
+  - CREP
+  - ocean circulation
+  - GenesisAeon
+  - early warning signal
+  - critical slowing down
+
+references:
+  - type: article
+    title: >
+      Physics-based early warning signal shows that AMOC is on tipping course
+    authors:
+      - family-names: van Westen
+        given-names: René M.
+      - family-names: Kliphuis
+        given-names: Michiel
+      - family-names: Dijkstra
+        given-names: Henk A.
+    journal: "Science Advances"
+    volume: 10
+    issue: 6
+    year: 2024
+    doi: 10.1126/sciadv.adk1189
+
+  - type: article
+    title: "Warning of a forthcoming collapse of the AMOC"
+    authors:
+      - family-names: Ditlevsen
+        given-names: Peter
+      - family-names: Ditlevsen
+        given-names: Susanne
+    journal: "Nature Communications"
+    year: 2023
+    doi: 10.1038/s41467-023-39810-w
+
+identifiers:
+  - type: doi
+    value: 10.5281/zenodo.19645351
+    description: "Zenodo archive"

amoc_utac-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,48 @@
+# 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]"`.
+4. Run the test suite: `pytest`.
+
+## Code style
+
+- Format and lint with `ruff check amoc_utac tests`.
+- Type-check with `mypy` (this repo uses `strict = true`).
+- Keep functions documented with docstrings.
+
+## Diamond Interface
+
+`amoc_utac.AmocUTAC` 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 package implements a physics-based early-warning model for AMOC
+collapse (Γ_AMOC ≈ 0.251). If your contribution touches the scientific
+model, prediction, or benchmark data:
+- Cite the source (e.g. van Westen et al. 2024, Ditlevsen & Ditlevsen
+  2023).
+- Clearly mark speculative vs. validated claims.

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

amoc_utac-1.0.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: amoc-utac
+Version: 1.0.0
+Summary: AMOC collapse early warning — GenesisAeon Package 18 (UTAC/CREP dynamical system)
+Project-URL: Homepage, https://github.com/genesisaeon/amoc-utac
+Project-URL: Repository, https://github.com/genesisaeon/amoc-utac
+Project-URL: Zenodo, https://doi.org/10.5281/zenodo.19645351
+Project-URL: Reference, https://doi.org/10.1126/sciadv.adk1189
+Author-email: Johann Römer <j.roemer@mor-research.org>
+License: MIT
+License-File: LICENSE
+Keywords: AMOC,CREP,GenesisAeon,UTAC,climate,early warning,ocean circulation,tipping point
+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 :: Atmospheric Science
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.11
+Requires-Dist: matplotlib>=3.9
+Requires-Dist: numpy>=1.26
+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: mypy>=1.10.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: notebooks
+Requires-Dist: ipykernel>=6.0.0; extra == 'notebooks'
+Requires-Dist: jupyter>=1.0.0; extra == 'notebooks'
+Description-Content-Type: text/markdown
+
+# amoc-utac
+
+> GenesisAeon Package 18 — Atlantic Meridional Overturning Circulation as UTAC System
+
+<p align="center">
+  <a href="https://doi.org/10.5281/zenodo.19645351"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.19645351.svg" alt="DOI (GenesisAeon Whitepaper)"/></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License"/></a>
+  <a href="https://creativecommons.org/licenses/by/4.0/"><img src="https://img.shields.io/badge/docs-CC%20BY%204.0-lightblue.svg" alt="CC BY 4.0"/></a>
+  <a href="https://github.com/GenesisAeon/genesis-os"><img src="https://img.shields.io/badge/part%20of-genesis--os-blueviolet" alt="Part of genesis-os"/></a>
+  <img src="https://img.shields.io/badge/UTAC-package%2018-orange" alt="Package 18"/>
+</p>
+
+**AMOC modelled as UTAC dynamical system** with physics-based early-warning from van Westen et al. (2024).
+
+**Key result**: Γ_AMOC ≈ 0.251 (medium-CREP) → same universality point as neural criticality (η = 50 %).
+
+## Installation
+
+```bash
+pip install amoc-utac
+```
+
+For development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+```bash
+amoc-utac run --duration 120
+amoc-utac tipping-estimate
+amoc-utac zenodo-export
+```
+
+## Integration in genesis-os
+
+```python
+from genesis_os import GenesisOS
+os = GenesisOS()
+amoc = os.load_package(18)
+results = amoc.run_cycle(duration_years=120)
+```
+
+## Benchmark
+
+Validated against RAPID array, van Westen 2024 & Ditlevsen 2023.
+
+## Falsifiable Prediction
+
+AMOC crosses 50 % weakening (H* = 0.5 K) between 2045–2065.
+
+## Role in the GenesisAeon Ecosystem
+
+`amoc-utac` is **P18** in the GenesisAeon ecosystem, covering the
+oceanography / AMOC tipping domain. It applies the UTAC-Logistic ODE and
+CREP metrics to the Atlantic Meridional Overturning Circulation, sharing
+its criticality framework (Γ ≈ 0.251) with sibling packages across other
+domains (e.g. neuroscience, heliophysics).
+
+## 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.
+
+## License
+
+Code: MIT • Docs & Data: CC BY 4.0

amoc_utac-1.0.0/README.md

@@ -0,0 +1,71 @@
+# amoc-utac
+
+> GenesisAeon Package 18 — Atlantic Meridional Overturning Circulation as UTAC System
+
+<p align="center">
+  <a href="https://doi.org/10.5281/zenodo.19645351"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.19645351.svg" alt="DOI (GenesisAeon Whitepaper)"/></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License"/></a>
+  <a href="https://creativecommons.org/licenses/by/4.0/"><img src="https://img.shields.io/badge/docs-CC%20BY%204.0-lightblue.svg" alt="CC BY 4.0"/></a>
+  <a href="https://github.com/GenesisAeon/genesis-os"><img src="https://img.shields.io/badge/part%20of-genesis--os-blueviolet" alt="Part of genesis-os"/></a>
+  <img src="https://img.shields.io/badge/UTAC-package%2018-orange" alt="Package 18"/>
+</p>
+
+**AMOC modelled as UTAC dynamical system** with physics-based early-warning from van Westen et al. (2024).
+
+**Key result**: Γ_AMOC ≈ 0.251 (medium-CREP) → same universality point as neural criticality (η = 50 %).
+
+## Installation
+
+```bash
+pip install amoc-utac
+```
+
+For development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+```bash
+amoc-utac run --duration 120
+amoc-utac tipping-estimate
+amoc-utac zenodo-export
+```
+
+## Integration in genesis-os
+
+```python
+from genesis_os import GenesisOS
+os = GenesisOS()
+amoc = os.load_package(18)
+results = amoc.run_cycle(duration_years=120)
+```
+
+## Benchmark
+
+Validated against RAPID array, van Westen 2024 & Ditlevsen 2023.
+
+## Falsifiable Prediction
+
+AMOC crosses 50 % weakening (H* = 0.5 K) between 2045–2065.
+
+## Role in the GenesisAeon Ecosystem
+
+`amoc-utac` is **P18** in the GenesisAeon ecosystem, covering the
+oceanography / AMOC tipping domain. It applies the UTAC-Logistic ODE and
+CREP metrics to the Atlantic Meridional Overturning Circulation, sharing
+its criticality framework (Γ ≈ 0.251) with sibling packages across other
+domains (e.g. neuroscience, heliophysics).
+
+## 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.
+
+## License
+
+Code: MIT • Docs & Data: CC BY 4.0