Metadata-Version: 2.4
Name: aeglib
Version: 0.0.2
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: License :: OSI Approved :: Apache Software 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: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Dist: sympy>=1.12 ; extra == 'sympy'
Requires-Dist: pytest ; extra == 'test'
Requires-Dist: sympy>=1.12 ; extra == 'test'
Provides-Extra: sympy
Provides-Extra: test
License-File: LICENSE-APACHE
License-File: LICENSE-MIT
Summary: AEG symbolic/numerical computation library (M0: exact algebra and Sturm certificates)
Keywords: arithmetic-expression-geometry,symbolic-computation,certification,mathematics
Author: aeglib contributors
License-Expression: MIT OR Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/mountain/aeglib
Project-URL: Repository, https://github.com/mountain/aeglib

# aeglib

**AEG 理论的符号与数值计算库。M0 第一切片已落地：Rust 精确代数 + Sturm 证书 + PyO3/SymPy 桥 + hilbert-16 示例。**

AEG（Arithmetic Expression Geometry，算术表达式几何）研究的不是表达式的最终数值，而是
表达式的**有序求值历史**：同一个值可以由不同的词、不同的操作顺序、不同的射影延拓得到，
而这些区别往往正是定理的内容。`aeglib` 的目标，是为这一整套理论提供一个可组合、可复现、
可认证的计算基座，而不是再造一个通用计算机代数系统。

当前的需求分析与架构设计以 [`hilbert-16`](../hilbert-16) 为第一个真实负载：平面多项式
向量场、Abel 积分、Picard–Fuchs 方程、Gauss–Manin 联络、返回映射与极限环计数。但库的
边界必须比 hilbert-16 更宽，因为 AEG 的另一半——分析——才是它未来最主要的使用场景。

## 这个库不是什么

- 不是 SymPy / Mathematica / Sage 的替代品。通用化简、符号积分、方程求解继续交给
  SymPy；`aeglib` 负责 SymPy 不擅长的部分：精确结构、定义域、认证数值、过程溯源。
  CAS 后端只做 SymPy，不引入 Symbolica/Mathematica 适配。
- 不是定理证明器。它产出**可独立检查的证书**，但不替代 Lean/Coq；与 Lean 的接口是
  未来的可选目标。
- 不是一个 GUI 或 notebook 产品。Python 层提供 notebook 友好的 API，但核心是库。
- 不是 hilbert-16 的专用工具。hilbert-16 是第一个“垂直切片”，不是库的边界。

## 设计原则（摘要）

1. **过程优先。** 表达式、历史、调度、occurrence 是不同对象；不能用一个 `Expr` 全部压平。
2. **相等是多层的。** 至少区分 `value_eq` / `operator_eq` / `presentation_eq`；
   `k(z+p)` 与 `kz+kp` 算子相等而历史不等。
3. **定义域是一等公民。** 除法、射影映射、分支、穿孔、参数退化都必须显式携带
   `Domain` / `Guard` / `Undefined(reason)`，不能靠抛异常或返回 `NaN`。
4. **判定带证书。** 返回值是 `Proven(cert) | Refuted(cert) | Unknown(budget)`，
   不是 `bool`；`Unknown` 必须说明预算与已穷尽范围。
5. **精确优先，浮点显式，认证可选。** `Explore` / `Compute` / `Certify` 三种模式；
   浮点结果永远不冒充证明。
6. **Python 是一等公民，但不是语义所有者。** Rust 核心拥有语义；Python 负责编排、
   SymPy/NumPy/SciPy 适配与交互。
7. **小内核，大生态。** 可信内核尽量小；多项式、ODE、拓扑等以 crate/插件扩展。
8. **可重放，而不是可打印。** 证书记录输入、假设、方法、版本与有理界；跨平台重算
   同一命题，而不是比较浮点末位。

## 文档

- [需求分析](docs/01-requirements.md)
- [架构设计](docs/02-architecture.md)
- [ADR-0001：Rust 还是 Zig](docs/adr/0001-rust-vs-zig.md)
- [ADR-0002：Python 边界](docs/adr/0002-python-boundary.md)
- [ADR-0003：认证模型与证书](docs/adr/0003-certification.md)
- [Gauss–Manin / Picard–Fuchs](docs/04-gm-pf.md)
- [局部单值与连接矩阵](docs/05-monodromy.md)
- [12 小时冲刺计划](docs/07-12h-sprint.md)
- [V12 证书层试点](docs/09-v12-certificate.md)
- [发布与命名策略](docs/14-release-and-naming.md)
- [hilbert-16 使用方案（2026-11-09 更新）](docs/10-hilbert16-usage-plan.md)
- [AEG 原生层：现状评估与补完方案](docs/16-aeg-native-layer.md)
- [VdP tube 重放审计](docs/18-vdp-tube-replay-audit.md)
- [C11 独立评审](docs/19-c11-independent-review.md)
- [TileLang 与矩阵/多元层：机会评估与 API 借鉴](docs/20-tilelang-assessment.md)
- [note 53 约化义务 vs aeglib：逐项缺口对照](docs/21-note53-reduction-gap.md)
- [发布手册（crates.io / PyPI）](RELEASE.md)

## Python 用法（M0）

```python
import sympy as sp
import aeglib

x = sp.Symbol("x")
p = aeglib.from_sympy(x**2 - 2)        # SymPy -> exact aeglib.Poly
print(p.coeffs())                       # ['-2', '0', '1']
print(p.sturm_count("0", "2"))          # 1

cert = aeglib.SturmCertificate.build(p, "0", "2", 1)
cert.verify()                           # raises CertificateError if mutated
cert.save("sturm-cert.json")            # versioned JSON evidence
aeglib.SturmCertificate.load("sturm-cert.json").verify()
```

SymPy 是可选桥接层；核心 crate 不依赖 Python/SymPy。

## 与其它仓库的关系

```text
aeg-paper/     理论：Paper 0–VI 的定义、定理、证明与状态登记
hilbert-16/    应用：以极限环计数为第一个真实计算负载
aeglib/        库：本文档所在的仓库；被上面两者依赖，而不反向依赖它们
```

`aeglib` 不复制论文中的家族常数、论文编号或某条定理的专用代码。hilbert-16 的
具体工作流应作为 `aeglib` 的示例/集成测试，或留在 hilbert-16 仓库中通过公开 API
调用。

## 状态

- 2026-11-09：需求分析与架构设计；ADR-0001/0002/0003 接受；四项范围决策确认。
- 2026-11-09：M0 第一切片落地——`aeg-core`、`aeg-algebra`、`aeg-certify`、
  `aeg-hilbert16`、`aeg-cli`；58 个默认 Rust 测试通过；`abelian_horner` 示例可运行。
- 2026-11-09：PyO3 + SymPy 桥落地——`aeg-py`（独立包，maturin 构建）、
  `python/aeglib`、`SturmCertificate` JSON/replay；10 个 Python 测试通过。
- 2026-11-09：CLI `verify/replay` 与可选 `arb` 后端落地；`arb` 目前链接系统
  FLINT 3.6（LGPL），默认构建仍是纯 Rust。
- 2026-11-09：`aeg-cert/1` 的 Arb enclosure 证据落地——`ArbExpr` AST、精确有理端点、
  `EnclosureCertificate`、CLI v1 verify/replay。`aeg-cert/0` 保持兼容。
- 2026-11-09：Gauss–Manin / Picard–Fuchs 精确核落地——`RatFn`、`aeg-analysis` 的
  `Connection`/`LinearOde`、三次族的 `M(h)`、留数、J0/J0²/M2 的 PF；
  `gauss_manin.py`、`weight2_pf.py` 的精确部分已对上。
- 2026-11-09：三次族周期 `J_0(h)`、`J_1(h)` 的 Arb 区间包络落地——根隔离 +
  Taylor-model 认证积分；与 `scipy.quad` 的数值一致到 ~1e-15，Arb 半径 ~1e-20。
- 2026-11-09：局部单值与连接矩阵落地——`exp(2πiR_p)` 用 Arb 矩阵指数；
  `P' = P M(h)` 的路径有序连接矩阵（128-bit RK4）；环路单值共轭到共同基点
  `h0=1/12`，trace/det/unipotent 检查通过。
- 2026-11-09：V12 证书层试点——FLINT `(0,1)` Sturm 快速路径让 51 次 `L`
  在 `(2,8)` 上 **0.029 s** 得 5 个根（SymPy 3.4 s / 无 gmpy2 34 s）；
  `SturmCertificate.from_chain` 独立验证 SymPy 的 52 项整数化链；
  负控制拒绝改 count/改链/符号翻转。V11 的 179 块聚合层 checker 也落地。
  可移植 wheel（`--features flint --auditwheel repair`）在干净 venv 中验证通过；
  SymPy 仍是可选依赖，核心不装 SymPy 也能 import。
- 2026-11-09：按 `docs/10` 补 V12 简单根预检——`Poly.is_squarefree`、
  `is_coprime`、`gcd_degree`、`gcd` 走 FLINT（V12 gcd 约 0.0003 s）；V12 示例现在检查
  六点符号、系数 SHA、gcd=0、根数 5/4 和链证书。
- 2026-11-09：`RatFn` Python API 与 V13 有理子恒等式落地；V13 的
  `asin/sqrt` Wronskian 仍明确未做。
- 2026-11-09：`ArbBall`/`ArbExpr`/`EnclosureCertificate` 在
  `--features "arb flint"` 下暴露；V11 单块动态 Taylor 重放
  （`v11_block.py`）已通过；`--all` 的 179 块串行重放为 179/179、0 failures、
  588.9 s。
- 当前测试：64 个默认 Rust、29 个 FLINT algebra、12 个 FLINT certify、
  44 个 Python（默认 builds 39 passed + 4 skipped）。
- 2026-11-09：发布路线落档——PyPI/crates.io 的 `aeglib` 名称用户确认可用；
  私有阶段用 GitHub Release wheel，约一个月后公开；详见
  [发布与命名策略](docs/14-release-and-naming.md) 与
  [ADR-0004](docs/adr/0004-release-channels.md)。
- 2026-11-09：发布准备代码落地——新增 `crates/aeglib` facade、MIT/Apache
  文本、LGPL/GPL 文本与 `THIRD_PARTY_NOTICES.md`，并打进 fast wheel。
- 2026-11-09：AEG 原生层 A0/A1 落地——`aeg-core` 的 `ExprArena`/`Affine1`/`AffineWord`/`eq_at`、
  `aeg-algebra` 的 `MPoly`/`MRatFn`、新 crate `aeg-calculus`（`Form`/`δ`/`ContactModel`/
  `AmWord`/`AcsPath`/`NormalModel`）；`aeg_native_slice` 输出六轴校准。
- 2026-11-09：A2.5 gate 层落地——`RegId`、`aeg-calculus::program` 的 `AmProgram`/`AmGate`
  （常量门、源读取端口、`run_traced`/`replay`），`am_program` 示例门级重放 note 34 的
  Horner 词与 note 49 的五步词。
- 2026-11-10：A3 一般 `AesSpec` 落地——新增 `aeg-geometry`：共形图表、eikonal 校验、
  canonical frame、`KPunctureModel`（k 穿孔族）、`ConformalMap` 拉回与 `z2_quotient`/
  `z2_cover`；`aes_spec` 示例覆盖 C3/C8。
- 2026-11-10：A4 transport/holonomy/torsion 落地——`DeltaCalculus::transport`/`holonomy`、
  `AcsPath::torsion`/`is_closed`/`is_scale_compatible`、开/闭水平回路，以及常系数
  Chen shuffle（`shuffle.rs`）；`transport` 示例覆盖 C10。
- 2026-11-10：A4.5 非定常 Liénard C10/C11 落地（数值）——`LienardCubic` 的半支
  `M2+M2'=(1/2)AB`，`vdp_periodic_orbit` 的 `ΔA_hor=Δy−∫y²dt`；`lienard` 示例给出
  0.3858903529 与 −13.7222。
- 2026-11-10：Arb 认证落地——`aeg-hilbert16::lienard_certified`（`--features arb`）
  用 Taylor 积分包络 C10 的 `A`、`B`、`(1/2)AB`，用嵌套区间包络 `M2`/`M2'`，
  并认证 harmonic C11；`lienard_certified` 示例给出 Arb 区间。VdP 周期轨道仍待认证。
- 2026-11-10：A5 部分落地——Python 只读 API `LienardCubic`/`CubicIterated`/`VdpOrbit`/
  `vdp_periodic_orbit`，Arb 构建下 `C10Enclosure`/`HarmonicC11Enclosure` 与 `to_json()`。
- 2026-11-10：Python 矩阵 API 落地——`RatMatrix`、`RatFnMatrix`（构造、add/sub/mul/
  scale/transpose/trace/det/derivative/eval/residue_at）；`aeg-algebra` 新增通用
  `Matrix<C>`。
- 当前测试：135 个默认 Rust（含 facade doctest、43 个 `aeg-calculus`、5 个 `aeg-geometry`）、
  51 个 Python 测试（`--features "arb flint"`：51 passed；无 flint 的 wheel：
  48 passed + 3 skipped；新增 4 个校准 + 3 个矩阵测试）；
  `aeg-hilbert16 --features arb` 22 tests。
- 下一步：VdP 的区间 ODE Taylor 管 + Newton；Python 几何 API（`Form`/`ContactModel`/
  `AesSpec`）；局部基归一化 `C_p`、V13 Wronskian、V11 动态重算、CI flint wheel。

```bash
# Rust 核心
cargo test --workspace
# 可选 Arb 后端（需要 FLINT 3.6；macOS: brew install flint）
cargo test -p aeg-certify --features arb
cargo run -p aeg-hilbert16 --example abelian_horner
cargo run -p aeg-hilbert16 --example cubic_gm
cargo run -p aeg-calculus --example aeg_native_slice
cargo run -p aeg-calculus --example am_program
cargo run -p aeg-calculus --example transport
cargo run -p aeg-calculus --example lienard
cargo run -p aeg-hilbert16 --features arb --example lienard_certified

# Python 只读 API（需 maturin 重建）
maturin develop --release --features arb
python -c "import aeglib; print(aeglib.LienardCubic.standard(0.08).values().shuffle_sum)"
cargo run -p aeg-geometry --example aes_spec
cargo run -p aeg-hilbert16 --features arb --example period_j
cargo run -p aeg-hilbert16 --features arb --example cubic_monodromy
cargo run -p aeg-certify --features arb --example arb_enclosure
cargo run -p aeg-cli -- sturm-count -2,0,1 0 2
cargo run -p aeg-cli -- verify sturm-cert.json
cargo run -p aeg-cli -- replay sturm-cert.json

# v1 Arb enclosure 证书（需要 --features arb）
cargo run -p aeg-cli --features arb --example arb_certificate > /tmp/arb-cert.json
cargo run -p aeg-cli --features arb -- verify /tmp/arb-cert.json
cargo run -p aeg-cli --features arb -- replay /tmp/arb-cert.json

# Python 绑定（aeg-py 是独立 workspace，不参与核心 cargo --workspace）
# 在 aeglib/ 下，使用已激活的 venv：
maturin develop --release
pytest python/tests -q
python python/examples/hilbert16_abelian_horner.py
python python/examples/period_scipy.py

# V12 证书层（需要 FLINT；从仓库根目录构建，确保装到 aeglib._aeglib）
maturin develop --release --features flint
python python/examples/v12_certificate.py
python python/examples/v13_rational.py
python python/examples/v11_endpoint.py
python python/examples/v11_block.py --index 0
python python/examples/v11_block.py --all
python scripts/bench_sturm.py

# Arb/Enclosure Python API（需要 arb+flint）
maturin develop --release --features "arb flint"
python scripts/check_v11_certificate.py --self-test
```

## 构建特性（feature）与 V11 固定输入

三个可选构建层次：

- 默认（无 feature）：纯 Rust，`Poly`/`RatFn`/`SturmCertificate` 可用；
  `fast_sturm_count` 抛 `RuntimeError("flint backend not enabled")`。
- `--features flint`：启用 FLINT 快速 Sturm/GCD（`fast_sturm_count`、`gcd`、
  `is_squarefree`/`is_coprime`/`gcd_degree`）。
- `--features "arb flint"`：再启用 `ArbBall`/`ArbExpr`/`EnclosureCertificate`。

`arb` 链接系统 FLINT 3.6（LGPL）；默认构建仍是纯 Rust。

**V11 示例依赖相邻 hilbert-16 仓库的固定证书。** `python/examples/v11_endpoint.py`、
`python/examples/v11_block.py` 与 `scripts/check_v11_certificate.py` 读取
`../hilbert-16/research/am-radial-control-v11/certificate.json`。单独 clone aeglib
无法重放：请把 `hilbert-16` clone 到 aeglib 旁边（使 `../hilbert-16` 存在），或用
`--certificate` 显式指定路径；缺失时脚本给出明确错误（`v11_endpoint.py` 则静默 skip）。
固定输入的权威动态证据仍是 hilbert-16 的 `certify.py --check-frozen`；上述脚本只做
聚合层 / 端点层 / 单块补充重放，不替代它。

## 许可

待定。核心计划采用 MIT / Apache-2.0 双许可；GMP/MPFR/FLINT 等 LGPL 依赖将作为
可选特性隔离，具体见架构文档的“许可与依赖”一节。

