Lumerical LDF Reader

让智能体在未安装 Lumerical 的机器上读取、检查与导出 .ldf D-card 数据

An Agent Skill for inspecting verified Lumerical MODE/FDTD LDF files without Lumerical

中文 · English

中文说明

lumerical-ldf-reader 是一个面向智能体的只读 Agent Skill，用于解析经过验证的 Ansys Lumerical MODE/FDTD .ldf D-card 文件。它不依赖 Lumerical 安装，可列出数据卡、元数据、记录名、数组形状与数据类型，并将第一张 D-card 导出为 NumPy .npz 或 MATLAB v5 .mat。

这个项目尤其适合把 Lumerical 产生的模式场数据带到 macOS、Linux、CI 或其他没有 Lumerical 的分析环境中，供智能体继续检查、比较和处理。

核心能力

• 读取已验证的 Lumerical data file 1, version 1.0 文件
• 恢复 Lumerical 的列主序数组和原生单例维度
• 保留 complex128 电磁场数据
• 输出严格 JSON 摘要，不生成非法的 Infinity 数值
• 导出压缩 NumPy .npz
• 通过 SciPy 导出 MATLAB v5 .mat
• 对未知版本、非法标记、计数不一致和截断文件明确报错
• 无需启动或安装 Lumerical

快速开始

安装为 Agent Skill

以 Codex 为例：

git clone https://github.com/Wonham/lumerical-ldf-reader.git \
  ~/.codex/skills/lumerical-ldf-reader

重启客户端，然后在任务中调用 $lumerical-ldf-reader。其他支持本地 SKILL.md 的智能体环境，可将本仓库克隆到其 Skills 目录，并把仓库根目录注册为一个 Agent Skill。

命令行读取

python scripts/lumerical_ldf.py input.ldf --json

导出第一张 D-card：

python scripts/lumerical_ldf.py input.ldf --export output.npz
python scripts/lumerical_ldf.py input.ldf --export output.mat

Python 调用

from scripts.lumerical_ldf import read_ldf

document = read_ldf("input.ldf")
card = document.cards[0]

print(document.version)
print(card.name)
print(card["Ex"].shape, card["Ex"].dtype)
print(card.scalar("neff"))

支持边界

LDF 是专有且未公开说明的二进制格式。本项目只支持已经与 Lumerical 导出结果交叉验证过的 version 1.0 MODE/FDE D-card 布局，不会猜测未知格式。

如果新文件触发 LDFError，正确做法是记录其文件头和版本，并在获得可公开、可回归的测试样本后扩展解析器，而不是关闭版本、标记、计数或截断检查。

本工具只读取和转换 LDF 数据：

• 不写入 .ldf 文件
• 不重建 Lumerical D-card
• 不替代 Lumerical 求解器
• 不保证支持所有来自 MODE/FDTD 的历史或未来 LDF 布局

数据约定

项目	行为
复数场	NumPy complex128 数组
数组顺序	恢复列主序，保留原生维度
JSON	记录名称、形状、类型和标量摘要
.npz	使用 NumPy 压缩存储
.mat	使用 SciPy 写入 MATLAB v5 文件
未知或损坏数据	抛出 LDFError

绘图时可以在确认单例轴含义后使用 numpy.squeeze，但归档、比较和往返检查应保留原生形状。独立求解得到的本征模还可能相差一个全局复相位，比较场分布前应先对齐相位。

环境要求

• 支持 SKILL.md 的智能体环境，或 Python 3.10+
• NumPy
• 可选：SciPy，仅在导出 .mat 时需要

仓库结构

.
├── README.md
├── LICENSE
├── SKILL.md
├── agents/
│   └── openai.yaml
└── scripts/
    └── lumerical_ldf.py

• SKILL.md 定义智能体的读取、验证、导出流程及安全边界。
• lumerical_ldf.py 提供只读解析器、命令行入口和 Python API。

English

lumerical-ldf-reader is a read-only Agent Skill for inspecting verified Ansys Lumerical MODE/FDTD .ldf D-card files on machines where Lumerical is not installed.

It restores native column-major arrays, preserves complex mode fields, emits strict JSON summaries, and exports the first D-card to NumPy .npz or MATLAB v5 .mat. The parser intentionally rejects unsupported versions, malformed records, and truncated files instead of guessing an undocumented binary layout.

Support is currently limited to the verified Lumerical data file 1, version 1.0 MODE/FDE D-card layout. See SKILL.md for the complete agent workflow and operating boundaries.

License

MIT