nlp2MCP (Jeffreyhorn)

NLP2MCP：通过KKT条件将GAMS NLP转换为MCP

](https://pypi.org/project/nlp2mcp/) 

一种Python工具，通过生成Karush-Kuhn-Tucker（KKT）条件，将用GAMS编写的非线性规划（NLP）模型转换为等效的混合互补问题（MCP）。

概述

该项目自动化了将GAMS NLP模型转换为基于KKT的MCP公式的过程，这对以下方面很有用：

• 数学研究：分析非线性程序的平稳性条件
• 解决方案开发：测试MCP求解器在NLP问题上的表现
• 教育目的：了解NLP和MCP公式之间的关系
• 高级建模：处理平衡问题和互补条件

背景

NLP的标准配方→ MCP转换为：

1. 从非线性程序（NLP）开始
2. 写下它的KKT（卡鲁什-库恩-塔克）条件
3. 将这些KKT条件编码为混合互补问题（MCP）：

- 平稳性和等式约束方程 - 不等式和界的互补对

有关更多详细信息，请参阅 docs/概念/IDA.md 和 文档/概念/NLP2MCP_HIGH_LEVEL.md.

特性

Epic 1（Sprints 1-5）已经完成，提供了核心NLP到MCP的转换功能。有关详细的sprint摘要，请参阅 docs/规划/EPIC_1/SUMMARY.md.

Epic 2（Sprints 6-12）已经完成，将解析器覆盖率扩展到100%（28/28型号），增加了26.19%的术语缩减，并建立了全面的CI基础设施。有关详细的sprint摘要，请参阅 docs/规划/EPIC_2/SUMMARY.md.

Epic 3（Sprints 13-17）已经完成，提供GAMSLIB测试基础设施、自动报告和v1.1.0版本。有关详细的sprint摘要，请参阅 docs/规划/EPIC_3/SUMMARY.md.

Epic 4（精灵18-28）以GAMSLIB凸连续语料库为目标，目标是带来完整的管道（解析→ 翻译→ 解决→ 匹配NLP参考），并在尽可能多的模型上进行匹配。18-25的冲刺已经完成；Sprint 26是下一个计划周期。

Sprint 25最终指标（2026-05-05，范围内=142个凸连续模型）：

Sprint 25亮点： Day 5 pivot通过可重用的跟踪+发射工件+形式衍生方法，推翻了三个第一阶段模型（qabel、abel、launch）上的原始模式A别名AD假设；模式C缩小到启动IndexOffset的形状别名（#1306）；修复原地序列#1338..#1352恢复了原来的检查点2 NO-GO（匹配52→60,求解92→104,模型不可行14→4);WS4小优先级#1270（多解门方法A-saras驱动程序）和#1271(_loop_tree_to_gams 调度器重构，删除约140个LOC，在所有141个当前正在翻译的模型中验证字节差异）。有关完整的冲刺历史和每个冲刺指标，请参阅 文档/规划/EPIC_4/PROJECT_PLAN.md §“滚动KPI和跟踪”和个人冲刺回顾 docs/planning/EPIC_4/SPRINT_*/SPRINT_RETROSPECTIVE.md.

安装

需求

• Python 3.11或更高版本
• 点21.3或更高

快速开始

从PyPI安装：

pip install nlp2mcp

验证安装：

nlp2mcp --help

来源（发展）

为了贡献或发展：

# Clone the repository
git clone https://github.com/jeffreyhorn/nlp2mcp.git
cd nlp2mcp

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install with development dependencies
make install-dev

# Or manually:
pip install -e .
pip install -r requirements.txt

测试版/预发布版本

要测试测试版，请执行以下操作：

# Install specific version
pip install nlp2mcp==0.5.0b0

# Or install from TestPyPI
pip install --index-url https://test.pypi.org/simple/ \
    --extra-index-url https://pypi.org/simple/ \
    nlp2mcp

# Or install directly from GitHub
pip install git+https://github.com/jeffreyhorn/nlp2mcp.git

用法

命令行界面

注意：该包公开了一个控制台脚本 nlp2mcp （定义见 pyproject.toml 作为 [project.scripts] nlp2mcp = "src.cli:main").安装软件包后（例如 和 pip install -e . 或 pip install nlp2mcp)，the nlp2mcp 命令将在您的PATH上可用 并将调用 src.cli:main.

如果您不想安装该软件包，可以直接从存储库中运行CLI，方法是：

python -m src.cli examples/simple_nlp.gms -o output_mcp.gms

# Convert NLP to MCP
nlp2mcp input.gms -o output_mcp.gms

# Print to stdout
nlp2mcp input.gms

# Verbose output (show pipeline stages)
nlp2mcp input.gms -o output.gms -v

# Very verbose (show detailed statistics)
nlp2mcp input.gms -o output.gms -vv

# Quiet mode (errors only)
nlp2mcp input.gms -o output.gms --quiet

# Show model statistics
nlp2mcp input.gms -o output.gms --stats

# Export Jacobian structure for analysis
nlp2mcp input.gms -o output.gms --dump-jacobian jacobian.mtx

# Apply Curtis-Reid scaling for ill-conditioned systems
nlp2mcp input.gms -o output.gms --scale auto

# Enable smooth abs() approximation
nlp2mcp input.gms -o output.gms --smooth-abs

# Customize model name
nlp2mcp input.gms -o output.gms --model-name my_mcp_model

# Disable explanatory comments
nlp2mcp input.gms -o output.gms --no-comments

# Show excluded duplicate bounds
nlp2mcp input.gms -o output.gms --show-excluded

# NLP pre-solve for non-convex models (warm-start MCP duals)
nlp2mcp input.gms -o output.gms --nlp-presolve

CLI选项：

• -o, --output FILE：输出文件路径（默认：stdout）
• -v, --verbose：增加详细程度（可堆叠：-v、-vv、-vvv）
• -q, --quiet：抑制无错误输出
• --model-name NAME：自定义GAMS模型名称（默认：mcp_model）
• --show-excluded / --no-show-excluded：显示排除的重复边界（默认值：否）
• --no-comments：禁用输出中的解释性注释
• --stats：打印模型统计数据（方程式、变量、非零）
• --dump-jacobian FILE：将雅可比结构导出为矩阵市场格式
• --scale {none,auto,byvar}：应用缩放（默认值：无）
• --simplification {none,basic,advanced,aggressive}：表达式简化模式（默认：高级）
• --smooth-abs：通过sqrt（x²+ε）启用平滑abs（）近似
• --smooth-abs-epsilon FLOAT：Epsilon用于腹肌平滑（默认值：1e-6）
• --nlp-presolve：首先解决原始NLP，以热启动MCP双变量（帮助非凸模型收敛）
• --check-convexity-numerical：运行计算凸性测试（需要 -oGAMS和源校验；比较冷启动和热启动目标以检测非凸性）
• --help：显示帮助消息

表达式简化

nlp2mcp自动简化导数表达式，以产生更紧凑、更高效的MCP配方。简化模式可以通过以下方式控制 --simplification 标志或配置文件。

简化模式

高级（默认） - --simplification advanced

• 应用所有基本简化和代数项集合

*附加项收集：*

• 持续收集: 1 + x + 1 → x + 2
• 喜欢术语集合: x + y + x + y → 2*x + 2*y
• 系数采集: 2*x + 3*x → 5*x
• 条款取消: x - x → 0, x + y - x → y
• 复杂基地: x*y + 2*x*y → 3*x*y

*乘法项集合：*

• 变量集合: x * x → x^2, x * x * x → x^3
• 功率倍增: x^2 * x^3 → x^5
• 混合乘法: x^2 * x → x^3, x * x^2 → x^3

*其他代数规则：*

• 乘法取消: 2*x / 2 → x, 2*x / (1+1) → x
• 权力划分: x^5 / x^2 → x^3, x / x^2 → 1/x
• 嵌套权力: (x^2)^3 → x^6

推荐用于大多数用例-产生最干净的输出

激进的 - --simplification aggressive *（Sprint 11）*

• 应用所有高级简化以及10个额外的代数变换和公共子表达式消除（CSE）
• 高优先级转换（T1-T3）：

- 共同因素提取： a*x + a*y → a*(x + y) - 馏分组合： a/c + b/c → (a + b)/c - 部门简化： (x*y)/y → x - 关联性规范化： (a + b) + c → a + b + c

• 中等优先级转换（T4）：

- 电源规则： x^a * x^b → x^(a+b), (x^a)^b → x^(a*b) - 对数规则： log(a*b) → log(a) + log(b), log(a^n) → n*log(a) - 三角恒等式： sin(x)^2 + cos(x)^2 → 1 - 嵌套操作简化： x*y*z*x → x^2*y*z

• 低优先级转换（T5-CSE）：

- 嵌套CSE：提取重复的复杂子表达式（≥3次出现） - 乘法CSE：提取重复的乘法模式（≥4次） - 支持别名的CSE：重用现有的变量别名，而不是创建新的临时变量

• 用于需要最大程度简化的具有复杂导数的大型模型
• 可以为CSE创建临时变量，转换时间稍长

基本 - --simplification basic

• 仅应用基本的简化规则：

- 持续折叠： 2 + 3 → 5, 4 * 5 → 20 - 零淘汰： x + 0 → x, 0 * x → 0 - 身份消除： x * 1 → x, x / 1 → x, x^1 → x - 代数恒等式： x - x → 0, x / x → 1

• 当您希望表达式的最小转换时使用

无 - --simplification none

• 未应用简化
• 派生表达式保持原始微分形式
• 有助于调试或理解差异化过程
• 可能会产生非常大的表情

示例

# Default: advanced simplification
nlp2mcp model.gms -o output.gms

# Explicitly use advanced
nlp2mcp model.gms -o output.gms --simplification advanced

# Use aggressive simplification (Sprint 11: 10 transforms + CSE)
nlp2mcp model.gms -o output.gms --simplification aggressive

# Use basic simplification only
nlp2mcp model.gms -o output.gms --simplification basic

# Disable simplification
nlp2mcp model.gms -o output.gms --simplification none

配置文件

您可以在中设置默认简化模式 pyproject.toml:

[tool.nlp2mcp]
simplification = "advanced"  # or "basic" or "none"
scale = "none"
smooth_abs = false

何时使用每种模式

• 高级 （默认）：最适合生产使用-产生最干净、最可读的输出
• 基本：当您需要可预测的转换而无需进行激进的优化时
• 无：用于调试、教育或需要查看原始派生表达式时

完整示例

输入 (examples/scalar_nlp.gms):

Variables x, obj;
Scalars a /2.0/;
Equations objective, stationarity;

objective.. obj =E= x;
stationarity.. x + a =E= 0;

Model mymodel /all/;
Solve mymodel using NLP minimizing obj;

运行nlp2mcp:

nlp2mcp examples/scalar_nlp.gms -o output_mcp.gms

输出 (output_mcp.gms):

* Generated by nlp2mcp
* KKT System with stationarity, complementarity, and multipliers

Scalars
    a /2.0/
;

Variables
    x
    obj
    nu_objective
    nu_stationarity
;

Equations
    stat_x
    objective
    stationarity
;

stat_x.. 1 + nu_stationarity =E= 0;
objective.. obj =E= x;
stationarity.. x + a =E= 0;

Model mcp_model /
    stat_x.x,
    objective.obj,
    stationarity.nu_stationarity
/;

Solve mcp_model using MCP;

Python API

已安装的软件包将其模块暴露在 src.* 命名空间（per pyproject.toml [tool.setuptools.packages.find] include = ["src*"]).可编辑安装后(pip install -e .)您可以直接导入它们：

from src.ir.parser import parse_model_file
from src.ir.normalize import normalize_model
from src.ad.gradient import compute_objective_gradient
from src.ad.constraint_jacobian import compute_constraint_jacobian
from src.kkt.assemble import assemble_kkt_system
from src.emit.emit_gams import emit_gams_mcp

# Full pipeline
model = parse_model_file("examples/simple_nlp.gms")
normalize_model(model)
gradient = compute_objective_gradient(model)
J_eq, J_ineq = compute_constraint_jacobian(model)
kkt = assemble_kkt_system(model, gradient, J_eq, J_ineq)
gams_code = emit_gams_mcp(kkt, model_name="mcp_model", add_comments=True)

print(gams_code)

等效CLI调用：

nlp2mcp examples/simple_nlp.gms -o output_mcp.gms     # installed
python -m src.cli examples/simple_nlp.gms -o output_mcp.gms  # from source checkout

项目结构

nlp2mcp/
├── src/
│   ├── ad/           # Symbolic differentiation engine
│   │   ├── api.py                  # High-level differentiation API
│   │   ├── ad_core.py              # Core symbolic operations
│   │   ├── derivative_rules.py     # Per-function derivative rules
│   │   ├── evaluator.py            # AST evaluation
│   │   ├── gradient.py             # Objective gradient
│   │   ├── jacobian.py             # Equality Jacobian
│   │   ├── constraint_jacobian.py  # Constraint Jacobian (eq + ineq)
│   │   ├── index_mapping.py        # Index/instance enumeration
│   │   ├── lp_coefficients.py      # LP coefficient extraction
│   │   ├── minmax_flattener.py     # min/max smoothing
│   │   ├── sparsity.py             # Sparsity tracking
│   │   ├── term_collection.py      # Like-term + power collection
│   │   └── validation.py           # Finite-difference validation
│   ├── emit/         # GAMS MCP code generation
│   │   ├── emit_gams.py            # Top-level emitter
│   │   ├── equations.py            # Equation block emit
│   │   ├── expr_to_gams.py         # Expression → GAMS string
│   │   ├── model.py                # Model statement emit
│   │   ├── original_symbols.py     # Source-symbol re-emission
│   │   └── templates.py            # Comment / banner templates
│   ├── gams/         # GAMS grammar (Lark)
│   ├── ir/           # Intermediate representation
│   │   ├── ast.py                  # Expression AST nodes
│   │   ├── condition_eval.py       # Static $cond evaluation
│   │   ├── diagnostics.py          # Parse-time diagnostics
│   │   ├── metrics.py              # Model statistics
│   │   ├── minmax_detection.py     # min/max detection
│   │   ├── model_ir.py             # Model IR data structures
│   │   ├── normalize.py            # Constraint normalization
│   │   ├── parser.py               # GAMS parser (parse tree → IR)
│   │   ├── preprocessor.py         # $include / $ifThen / macros
│   │   ├── scalar_offset_resolver.py  # IndexOffset resolution
│   │   ├── simplification_pipeline.py # Simplification orchestration
│   │   ├── symbols.py              # Symbol table definitions
│   │   └── transformations/        # IR rewriting passes
│   ├── kkt/          # KKT system assembly
│   │   ├── assemble.py             # Top-level KKT assembly
│   │   ├── complementarity.py      # Comp pairs (bounds + ineq)
│   │   ├── empty_equation_detector.py
│   │   ├── kkt_system.py           # KKT data structures
│   │   ├── naming.py               # Multiplier / equation naming
│   │   ├── objective.py            # Objective expansion
│   │   ├── partition.py            # Equality / inequality split
│   │   ├── reformulation.py        # MCP reformulations
│   │   ├── scaling.py              # Curtis-Reid / byvar scaling
│   │   ├── sqr_reformulation.py    # power(x,2) → x*x
│   │   └── stationarity.py         # Stationarity equations
│   ├── validation/   # Multi-solve driver gate (#1265, #1270)
│   └── utils/        # Utility functions
├── tests/
│   ├── unit/         # Fast unit tests (~10s)
│   ├── integration/  # Integration tests (~60s)
│   ├── e2e/          # End-to-end tests
│   └── validation/   # Validation tests
├── examples/         # Example GAMS models
├── data/gamslib/     # GAMSLIB pipeline (raw sources, MCP outputs, status)
├── docs/             # Documentation
│   ├── ad/                   # AD module docs
│   ├── architecture/         # System architecture
│   ├── concepts/             # Original concepts (IDEA, NLP2MCP_HIGH_LEVEL)
│   ├── emit/                 # GAMS emission docs
│   ├── issues/               # In-tree issue tracking
│   ├── kkt/                  # KKT assembly docs
│   └── planning/             # Per-Epic plans, sprints, retrospectives
├── scripts/gamslib/  # Pipeline runners + status reporting
├── pyproject.toml    # Project configuration
├── Makefile          # Development commands
└── README.md         # This file

发展

可用的生成命令

make help         # Show all available commands
make install      # Install the package
make install-dev  # Install with dev dependencies
make lint         # Run linters (ruff, mypy)
make format       # Format code (black, ruff)
make test         # Run tests
make clean        # Remove build artifacts

运行测试

测试套件分为四层，用于快速反馈。

📊 查看测试金字塔可视化 -请参阅按模块和类型划分的测试覆盖率明细。

# Run fast unit tests only (~10 seconds)
./scripts/test_fast.sh
# Or: pytest tests/unit/ -v

# Run unit + integration tests (~30 seconds)
./scripts/test_integration.sh
# Or: pytest tests/unit/ tests/integration/ -v

# Run complete test suite (~60 seconds)
./scripts/test_all.sh
# Or: pytest tests/ -v

# Run specific test category
pytest -m unit          # Only unit tests
pytest -m integration   # Only integration tests
pytest -m e2e          # Only end-to-end tests
pytest -m validation   # Only validation tests

# Run specific test file
pytest tests/unit/ad/test_arithmetic.py -v

# Run with coverage
pytest --cov=src tests/

# Run tests in parallel (faster, ~2 minutes for full suite)
pytest -n 4             # Use 4 workers
pytest -n auto          # Auto-detect CPU count

并行测试： 测试套件支持并行执行，使用 pytest-xdist.跑步 -n 4 将测试时间从3-4分钟缩短到2分钟。所有测试都是隔离的，可以安全地并行执行。

测试组织

测试套件分为单元、集成、e2e和验证层。您可以使用中的脚本运行不同的子集 ./scripts/ 或者直接通过pytest。冲刺25结束（2026-05-05）： 4735项测试通过 在 make test （跳过10次，2次失败）。对于每层标记计数，您可以在本地复制：

# Total collected tests
python3 -m pytest --collect-only -q | wc -l

# Per-marker counts
python3 -m pytest -m unit --collect-only -q | wc -l
python3 -m pytest -m integration --collect-only -q | wc -l
python3 -m pytest -m e2e --collect-only -q | wc -l
python3 -m pytest -m validation --collect-only -q | wc -l

典型布局：

tests/
├── unit/
├── integration/
├── e2e/
└── validation/

测试金字塔指导：在开发过程中更喜欢快速的单元测试，运行integration/e2e以获得跨模块的信心，并在发布前运行完整的验证/确认套件。

代码风格

本项目使用：

• 黑色 用于代码格式化（行长：100）
• 拉夫 用于梳理和进口分拣
• MyPy 的 用于类型检查

在提交之前格式化代码：

make format
make lint

示例

这 examples/ 目录包含示例GAMS NLP模型：

• simple_nlp.gms -具有目标和约束的基本索引NLP
• scalar_nlp.gms -简单标量优化问题
• indexed_balance.gms -带有索引平衡方程的模型
• bounds_nlp.gms -演示变量边界处理
• nonlinear_mix.gms -混合非线性函数

支持的GAMS子集

宣言

• ✅ Sets 有明确的成员
• ✅ Aliases
• ✅ Parameters （标量和索引）
• ✅ Scalars
• ✅ Variables （标量和索引）
• ✅ Equations （标量和索引）
• ✅ Table 数据块

评论

• ✅ GAMS在线评论(* comment)
• ✅ C风格线条注释(// comment)
• ✅ 阻止评论($ontext ... $offtext)

注： 在解析过程中，输入文件注释会被删除，不会出现在输出中。但是，发射器可以在输出中添加解释性注释（由控制 --no-comments 旗）。用于全预处理器/ $-指令覆盖范围见下文§“预处理器/编译指令”。

表达方式

• ✅ 算术： +, -, *, /, ^, **
• ✅ 指数偏移： i+1, t-2等等。（恒定整数偏移）
• ✅ 可区分的功能： exp, log, log2, log10, sqrt, sin, cos, tan, power(x,n), sqr(x), abs() （平滑近似 --smooth-abs)
• ✅ 设置/索引内部函数： ord(i), card(i), sameas(i, j), i.first, i.last, i.pos
• ✅ 聚合： sum(i, expr), prod(i, expr), smax(i, expr), smin(i, expr)
• ✅ 条件聚合： sum(i$cond, expr) 和 (i,j)$cond 元组域
• ✅ 比较： =, <>, `, =`
• ✅ 逻辑： and, or, not
• ✅ min() / max() （重新表述为互补性）
• ✅ 美元条件： expr$cond, lvalue$cond = rhs

方程

• ✅ 关系： =e= （平等）， =l= (≤), =g= (≥)
• ✅ 变量边界： .lo, .up, .fx （标量+索引+表达式值）
• ✅ 可变比例： .scale （冲刺23#835）

控制流

• ✅ Loop(set, ...) 并过滤 Loop(i$cond, ...) （解析器+发射器——Sprint 25#1271调度器重构统一了替换和非替换路径）
• ✅ If(cond, then ; elseif cond, ... ; else ...)
• ✅ While(cond, body)

预处理器/编译指令

• ✅ $include （嵌套的相对路径）
• ✅ $if, $ifThen / $endIf / $else / $elseIf （#705+Sprint 24#1264零件供应）
• ✅ $set / $setglobal，源头宏观扩张
• ✅ $ontext / $offtext, $onEcho / $offEcho, $onEps / $offEps
• ✅ $title, $eolcom, $onImplicitAssign / $offImplicitAssign
• ✅ $onMultiR / $offMultiR

模型

• ✅ Model 带有方程式列表的声明或 /all/
• ✅ Solve 声明与 using NLP|DNLP|QCP|MCP|CNS [minimizing|maximizing]

高级功能

• ✅ NLP预解决: --nlp-presolve 从NLP优化开始热启动MCP（帮助非凸模型）
• ✅ 扩展Curtis Reid和byvar缩放(--scale auto|byvar)
• ✅ 诊断：模型统计(--stats)，雅可比导出(--dump-jacobian)
• ✅ 配置: pyproject.toml 支持默认选项
• ✅ 日志记录：具有详细度控制的结构化日志记录(--verbose, --quiet)
• ✅ 多解决驱动器门 （Sprints 24-25，#1265+#1270）：拒绝Dantzig–Wolfe/列生成/saras风格的原始对偶脚本，其中收敛目标是迭代不动点，而不是单个NLP的最优值

尚未支持

• ❌ AD层的真正不可微函数： floor, ceil, sign, mod, round。这些解析，但它们的导数没有实现（今天唯一可平滑的情况是 abs() 通过 --smooth-abs).
• ❌ 随机/抽样函数： uniform, normal, gamma, loggamma, psi解析，但无法区分。
• ❌ 外部/用户定义函数
• ❌ 参数值 IndexOffset （例如。 x(i+li(k)) 哪里 li 是一个 Parameter).已追踪 #1224 Sprint 26。
• ❌ MIP/MILP/离散变量。设计不在KKT范围内。

文档

概念与规划

• docs/概念/IDA.md -原始概念：KKT条件如何将NLP转换为MCP
• 文档/概念/NLP2MCP_HIGH_LEVEL.md -可行性研究及实施蓝图

根据Epic计划 （每个Epic都围绕一个主题进行了几次冲刺）：

有关任何Epic下每个冲刺的详细信息，请参阅 docs/planning/EPIC_N/SPRINT_M/SPRINT_RETROSPECTIVE.md （如适用）。Sprint 25回顾生活在 文档/规划/EPIC_4/SPRINT_25/SPRINT_RETROPSPECTIVE.md.

• docs/development/AGENTS.md -基于代理的开发说明

技术文档

系统架构：

• docs/architecture/系统架构.md -整体系统数据流
• docs/architecture/数据结构.md -IR和KKT数据结构

自动微分：

• docs/ad/README.md -AD模块概述和快速启动
• docs/ad/ARCHITECTURE.md -设计决策和基本原理
• docs/ad/DESIGN.md -详细的实施方法
• docs/ad/DRIVATIVE_RULES.md -完整的衍生规则参考

KKT组装和代码生成：

• docs/kkt/kkt_ASSEMBLY.md -KKT系统组装（数学背景、实现）
• docs/EMISSION/GAMS_Eemission.md -GAMS MCP代码生成（语法、模式、示例）

贡献

请阅读 贡献.md 贡献之前！

该项目正在积极开发中。Sprint 25（Epic 4-GAMSLIB语料库管道）于2026年5月5日关闭；Sprint 26接下来将重点关注模式C门泛化、模式A队列重新分类和AD残差 otpop。欢迎投稿！

贡献者快速入门

1. 阅读指南: 贡献.md 和 docs/development/AGENTS.md
2. 设置环境:

   python3.12 -m venv .venv
   source .venv/bin/activate
   make install-dev

1. 创建特征分支: git checkout -b feature/amazing-feature
2. 进行更改：遵循CONTRIBUTING.md中的代码样式
3. 质量检查:

   make format   # Auto-format code
   make lint     # Type checking and linting
   make test     # All tests must pass (4,735+ as of Sprint 25)

1. 提交PR：在GitHub上推送分支并创建Pull Request

需求

• 带有现代类型提示的Python 3.12+
• 所有测试均已通过
• 代码格式为黑色+Ruff
• 用mypy检查类型

看 贡献.md 详细指南。

许可证

MIT许可证-有关详细信息，请参阅许可证文件

致谢

• 基于非线性优化KKT条件的数学框架
• 用途 云雀 用于解析GAMS语法
• 受GAMS/PATH和其他MCP求解器的启发

路线图

史诗1——基础（精灵1-5）：

• v0.1.0 （Sprint 1）：✅ 解析器和IR
• v0.2.0版本 （Sprint 2）：✅ 符号微分
• v0.3.0 （Sprint 3）：✅ KKT合成和MCP码生成
• v0.3.1 （Sprint 3之后）：✅ 问题#47修复（索引方程）
• v0.4.0 （Sprint 4）：✅ 扩展功能和鲁棒性
• v1.0.0 （Sprint 5）：✅ 生产准备就绪，包括硬化、包装和全面的文件记录

Epic 2——解析器覆盖率+简化（Sprints 6-12）： ✅ 完成——在28个夹具组上，解析器覆盖率达到100%；积极简化，术语减少26.19%；完整的CI基础设施。

Epic 3-GAMSLIB测试基础设施（Sprints 13-17）： ✅ 完成——管道流道(scripts/gamslib/run_full_test.py)，自动报告，模式版本化状态JSON， v1.1.0版本发布.

Epic 4-GAMSLIB语料库管道（精灵18-28）： 🔄 Sprint 25正在进行中。

• ✅ 完成18-25次冲刺 --解析142/142（100%），翻译133/142（93.7%），求解104（78.2%的翻译），匹配60（42.3%的范围内），4735个测试通过
• 🔄 Sprint 26 （计划中）-模式C门泛化（#1354/#1355/#1356/#1357），模式A队列重新分类，AD残差（#1334/#1335）。目标：匹配率≥45%（≥64），求解率≥81%，路径语法错误≤6。
• 🔄 短跑27-28 --解决方案咨询、绩效基准、， v2.0.0版本.

有关跟踪每个冲刺实际值+修订目标的滚动KPI表，请参阅 文档/规划/EPIC_4/PROJECT_PLAN.md §“滚动KPI和跟踪”。

联系

如有疑问、问题或建议，请在GitHub上发布问题。