Strilight (v0.2.0)

面向 Python 和 C 的高性能代数循环提升与精确有理递推引擎

---

概述：既然能求解，何必迭代？

传统编译器、运行时和 JIT 引擎（如 GCC、Clang、PyPy 或 Numba）将循环视为重复的控制流序列，逐条执行指令：

$$ \text{Runtime Cost} = \mathcal{O}(N) $$

当 $N = 10^6$ 或 $10^9$ 时，顺序执行会消耗数十亿个 CPU 周期。Strilight 通过符号代数提升从根本上重新设计了循环执行方式：

1. 状态转移建模：它静态检查循环体，并构建其数学状态转移矩阵：

$$ \vec{\mathbf{X}}(N) = \mathbf{A}^N \cdot \vec{\mathbf{X}}0 + \sum{k=0}^{N-1} \mathbf{A}^{N-1-k} \vec{\mathbf{B}} $$

2. 闭式解：它以闭式形式求解递推系统，将执行时间从 $\mathcal{O}(N)$ 降至 $\mathcal{O}(1)$（适用于标量/周期/伸缩级数）或 $\mathcal{O}(\log N)$（通过快速二进制矩阵幂运算）。

---

设计理念：开发者体验优先

Strilight 并不假装引入了什么深奥的魔法；它本质上是一个开发者体验工具。

在物理建模、科学计算和数值仿真中，工程师经常面临一个令人沮丧的两难困境：

• 可读的代码：自然、富有表现力的方程，与教科书中的物理公式一致，但迭代数百万次时执行缓慢。
• 手工优化的代码：复杂的手动展开循环和晦涩的算术技巧，运行速度快，但脆弱、难以调试，且掩盖了底层物理本质。

Strilight 解决了这一困境。 你可以用任何自己偏好的直白、自然的语法来书写物理或数学概念。Strilight 会检查你的循环结构，推导出精确的闭式递推公式，并在幕后加速执行——同时保持代码库的完全可读性和简洁性。

---

架构基础

1. 基于 $\mathbb{Q}$ 的精确有理算术（零精度损失）

浮点运算会引入累积截断误差（$1/3 \times 3 \approx 0.9999999999999999$）。Strilight 在有理数域 $\mathbb{Q}$ 上执行仿射归纳和步长分析：

• 乘数和偏移量被建模为规范分数（$\frac{p}{q}$）。
• 在 C 中生成双精度内核，在 Python 中生成精确的 Fraction 表示，保证 100% 位精确的数学一致性。

2. 多变量耦合递推系统（$\mathcal{O}(\log N)$）

相互依赖的变量（例如，位置依赖于速度、速度依赖于加速度的物理仿真）会被自动提取为变量耦合矩阵（$\mathbf{A}$）。Strilight 对 $\mathbf{A}$ 执行二进制幂运算，在不到 2 纳秒内完成数百万次迭代。

3. 透明的 @accelerate 装饰器（工作原理）

用 @accelerate 装饰任何标准 Python 函数，都会在函数定义时执行一条自动化流水线（每次调用时零运行时分析开销）：

1. AST 提取：检查函数 AST，识别 for 循环结构，并提取归纳变量。
2. 闭式合成：将循环转换为等价的闭式递推模型或二进制矩阵幂核。
3. 原地拼接：原地替换循环 AST 节点，将可调用对象编译到内存中，并注入运行时全局变量（Fraction、math），且不污染模块命名空间。
4. 契约反射：将 _loop_summary 和 _invariant_contract 附加到编译后的函数对象上，使下游编译器和验证工具能够检查底层的转移矩阵 $\mathbf{A}$。
5. 优雅回退：如果遇到非线性索引或不支持的动态调用，Strilight 会发出诊断警告，并干净地回退到原生执行，而不会崩溃。

from strilight import accelerate

@accelerate
def compute_simulation(steps: int) -> int:
    acc = 0
    for i in range(steps):
        acc += (i * 3) + 7
    return acc

# Executes in O(1) time (~0.001 ms even if steps = 100,000,000)
result = compute_simulation(100_000_000)

4. 契约引导的 C 源码指令（#pragma strilight）

与 Python 的动态反射不同，Strilight 中的 C 代码变换严格遵循通过 OpenMP 风格 pragma 指令实现的显式开发者契约模型。引擎绝不会隐式修改 C 源代码；仅当由显式开发者契约子句（contract、target、include、model）指示时才会执行变换：

• #pragma strilight accelerate：显式授权 Strilight 将标注的 C for 循环提升为等价的闭式数学表达式。
• #pragma strilight fuse：显式开发者指令，指示 Strilight 将共享相同迭代域的指定相邻循环融合为统一的 $\mathcal{O}(\log N)$ 二元矩阵递推内核。

// Example of contract-guided multi-loop fusion via developer directive
int simulate_motion(int n) {
    int pos = 0, vel = 10;

    #pragma strilight fuse
    for (int i = 0; i < n; i++) {
        pos += vel;
    }
    for (int i = 0; i < n; i++) {
        vel += 2;
    }
    return pos;
}

5. 跨文件符号与常量解析（CrossFileResolver）

数值模拟经常在单独的头文件或配置模块中定义参数。Strilight 的 CrossFileResolver：

• 静态追踪本地模块导入以及 C 的 #include / #define 指令。
• 通过 AST 求值跨文件计算字面常量表达式（例如 SOLAR_MASS = 4 * PI * PI），而不执行任意运行时代码，也不使用不安全的 eval。

6. 数组切片归纳与循环表查找

• 循环数组查找：将循环表查找（table[i % P]）提升为预计算前缀和的闭式公式，复杂度为 $\mathcal{O}(1)$。
• 原地数组切片修改：对常量填充和等差数列进行分类，合成最优的硬件 memset 调用或向量切片赋值（arr[:N] = ...）。

7. 物理与运动学加速的底层工作原理

在力学和天体物理模拟中（例如 $N$ 体系统、轨道力学、粒子运动学），物理实体经常在长时间内沿平滑、无扰动的轨迹运动，而不会发生突然碰撞或方向改变：

• 解析轨迹合成：当 Strilight 识别出某个粒子或天体正在沿无扰动的引力或线性轨迹运动时，它会将迭代时间步进循环折叠为尽可能少的数学运算（解析开普勒/谐波轨道公式）——同时不牺牲坐标精度。
• 向复杂事件过渡：当复杂事件发生时（离散碰撞、边界墙撞击或不规则多体耦合），执行会转入专门的碰撞耦合矩阵（$\mathbf{A}$）或局部化模拟阶段。
• 零代码风险：Strilight 完全非侵入式。在 Python 中，它只是一个 @accelerate 装饰器；在 C 中，它只是一个标准 #pragma。你可以随时添加或移除它，而无需改动算法或业务逻辑。
• 果断的优雅回退：如果 Strilight 遇到具有非结构化副作用、未知外部调用或非仿射动力学的循环，它会果断且干净地停止加速尝试，并回退到原生执行。你的程序永远不会崩溃。

8. 与 AI 编程助手协作及检查加速后的代码

现代 AI 编程助手（如 Claude、Gemini、GPT 或 Jules）在处理代数公式和闭式方程时表现出色。Strilight 让开发者和 AI 代理能够直接检查合成代码和数学契约：

在 Python 中检查数学契约：

from strilight import accelerate

@accelerate
def compute_energy(steps: int) -> int:
    total = 0
    for i in range(steps):
        total += 15
    return total

# Execute once to trigger definition-time synthesis
result = compute_energy(100)

# Inspect the underlying mathematical contract:
summary = compute_energy._loop_summary
print("Extracted Induction Formulas:", summary.to_induction_formulas())
print("Invariant Contract:", compute_energy._invariant_contract.to_dict())

生成独立的加速 C 源代码：

你可以直接将 C 源代码传递给 accelerate_c_source，以生成可检查、人类可读的加速 C 内核：

import strilight as sl

c_source = """
long long simulate(void) {
    long long total = 0;
    #pragma strilight accelerate target(total)
    for (int i = 0; i < 1000000; i++) {
        total += 42;
    }
    return total;
}
"""

accelerated_c = sl.accelerate_c_source(c_source)
print(accelerated_c)
# Emits: total += (42LL * 1000000);

9. 现实预期与开发者契约

我们信奉工程透明度：

• 不做笼统保证：Strilight 并不声称每一个任意、无约束的循环都会神奇地变成 $\mathcal{O}(1)$。高度不规则的指针追逐、任意动态 I/O 或非代数外部函数调用在根本上不可约简。
• 可预测的成功：对于结构化循环——标量归约、多变量线性耦合、循环数组以及契约引导的循环——Strilight 能够可靠地成功。在 C 中，提供显式的 pragma 子句（target、include、model）可提供确定性的转换保证。

---

基准测试结果

在高迭代数值循环上进行评估，比较原生执行与 Strilight 加速：

基准测试场景	迭代次数（$N$）	原生基线	Strilight 加速	实测加速比	精度保真度
耦合 4x4 线性系统（Python）	$1,000,000$	$75.2\text{ ms}$	$0.0002\text{ ms}$	$376,000\times$	100% 位精确
耦合 4x4 线性系统（GCC -O2）	$1,000,000$	$1.1\text{ ms}$	$0.00002\text{ ms}$	$55,000\times$	100% 位精确
循环数组查找求和	$1,000,000$	$74.8\text{ ms}$	$0.0044\text{ ms}$	$17,000\times$	100% 位精确
行星 N 体天体力学	$100,000$	$7.17\text{ ms}$	$0.051\text{ ms}$	$140\times$	解析轨道一致性

---

架构与执行流水线

flowchart TD
    SRC["Source Code (Python / C)"] --> LIFTER["SourceLifter: AST & Pragma Parser"]
    LIFTER --> RESOLV["CrossFileResolver: Static Import Resolution"]
    RESOLV --> VSA["Algebraic Induction Engine: models.py"]
    VSA --> MATRIX["VariableCouplingMatrix: System Transition Matrix A"]
    VSA --> QFIELD["Exact Rational Domain over Q: AffineExpr"]
    REDUCE --> CODEGEN["CodeGenerator: C / Python Synthesis"]
    VSA --> REDUCE["Schur Reduction & Block-Diagonal Decomposition"]
    CODEGEN --> OUT["O(1) / O(log N) Executable Kernel"]

---

关键应用与实际使用场景

Strilight 解决了科学、工程和金融领域的计算瓶颈：

1. 科学与天体物理模拟

• 领域：N 体天体力学、轨道状态传播和多粒子运动学级联。
• 优势：绕过迭代式 $\mathcal{O}(N)$ 数值时间步进。直接在 $\mathcal{O}(1)$ 或 $\mathcal{O}(\log N)$ 内评估任意未来时刻 $T$ 的状态向量，通过 $\mathbb{Q}$ 上的精确有理数运算消除累积数值漂移。

2. 量化金融与精算分析

• 领域：复利累积流、年金、固定收益建模和多期资产折旧。
• 优势：用微秒级的精确闭式求值替代数千步的模拟循环。保证 100% 位精确的有理数精度，消除金融法规禁止的浮点舍入差异。

3. 实时图形与游戏引擎物理

• 领域：粒子发射器、抛射体轨迹和连续相机动画。
• 优势：在实时 60/120 FPS 帧周期中，将繁重的顺序循环从 CPU 卸载，把迭代累加过程折叠为在亚纳秒内执行的单周期代数求值。

4. 嵌入式系统与硬实时计算（IoT / 边缘）

• 领域：在严格功耗和时钟限制下运行的资源受限微控制器（ARM Cortex-M、RISC-V、ESP32）。
• 优势：将十亿次迭代周期折叠为瞬时的 $\mathcal{O}(1)$ 算术语句，带来显著的节能效果，并保证有界、确定性的执行截止时间。

5. 编译器、静态分析与形式化验证

• 领域：不变式推断、符号执行和自动定理证明（SMT/Z3）。
• 优势：无需内存密集型的循环展开，即可合成形式化数学归纳契约（LoopInvariantContract）。

---

安装

从 PyPI / Wheel 发行版安装：

pip install strilight

从源码运行（开发模式）：

git clone https://github.com/asama7706r-ui/strilight.git
cd strilight
pip install -e .

验证与示例

执行测试套件和可复现的基准测试：

# Run the 60-test unit and induction verification suite:
pytest

# Python recurrence acceleration:
python examples/01_python_recurrence_acceleration.py