PhotonCir

PhotonCir 用 Python 描述光子器件拓扑，并导出平坦的 PhotonCir .cir 文件。后端实现器独立读取 .cir，结合器件实现库生成 MATLAB .m 或其他目标模块。

Python DSL -- build --> .cir -- implementer --> module

初版只实现静态复线性光网络。光学端口保留双向连接和内部反馈；温度、电压、波长等数值作为输入传给生成模块。热状态、控制器、采样和系统时序属于 Simulink 等下游系统。

安装

需要 Python 3.11 或更高版本。PyPI 当前已发布版本仍为：

python -m pip install "photoncir==0.1.0a1"

本仓库源码已经进入 0.1.0a2 候选版，其中包含完整双向 Y-junction 物理修正；在 a2 发布前，PyPI 上的 a1 不包含该修正。

从源码开发：

python -m venv .venv
source .venv/bin/activate
python -m pip install -e .

核心包没有第三方运行时依赖。器件参数使用国际单位制数值，例如长度和波长用米、温度用 K、功率衰减系数用 1/m。

当前 wheel 是纯 Python 通用包；MATLAB/Simulink 只用于运行生成模块和系统复现，不是安装 PhotonCir 的依赖。

前端：Python DSL 到 .cir

建模代码从两个公开命名空间导入：

from photoncir.base import *
from photoncir.devices import *

最小电路：

with Circuit("demo") as circuit:
    left = WaveGuide(length=10e-6)
    right = WaveGuide(length=20e-6)

    left.o_right | right.o_left
    left.o_left = Input("field")
    Probe("result", right.o_right)

build(circuit, "demo.cir")

前端语义固定为：

• device.o_xxx | other.o_xxx：双向光学端口连接；
• device.t_xxx = Input("name")：控制或光学输入绑定；
• Probe("name", device.port)：一次声明一个输出观测目标。

Input 只有 Input(name) 一种构造方式。温度、电压、波长、占空比和外部光注入都是输入；当前没有独立的 Output 类型，也没有 Probe.bind()。

Device 是叶器件，声明固定 name、端口和参数。Module 与 Device 使用相同的端口和连接语法，但拥有自己的内部 Circuit。build 按实例化顺序深度优先展开 Module，使用 union-find 合并边界端口，自动生成 net 和器件编号，最后写出平坦 .cir。Module 不生成 .subckt。

当前内置叶器件声明与 free 实现一一对应：

• 光传播与耦合：WaveGuide、DirectionalCoupler、YJunction；
• 静态有源波导：VoltageTunableWaveguide。

free YJunction 使用理想对称、互易、无损时幺正的完整三端口 S 矩阵，保留从两臂入射时的反射和臂间耦合；它不是为匹配单程 MZI 曲线而截断的 splitter/combiner。实际 PDK 应通过独立器件实现库替换为 FDTD 或测量得到的完整复 S 参数。

组合器件由上述叶器件构图，并在 build 时递归展开：

• SingleBusRing、AddDropRing、SecondOrderRing；
• MicroringModulator、MachZehnderInterferometer、MachZehnderModulator。

VoltageTunableWaveguide 保留电压相关的有效折射率、功率衰减和结电容四阶多项式。结电容作为观测量导出，电路动态由下游系统实现；MRM/MZM 的 PDK 拟合系数由调用者提供。

后端：.cir 到 module

后端不导入 Python DSL，只消费 .cir 和显式实现库：

from photoncir.implementer import compile_matlab, free_linear_library

source = compile_matlab(
    "demo.cir",
    free_linear_library(),
    path="demo.m",       # 可选；不提供时只返回源码
)

free_linear_library() 加载内置 free 线性器件实现。也可以使用 load_linear_library(directory) 加载另一个 Python 实现目录，因此 free/pro 或云端实现不需要修改 .cir。

当前后端器件实现不使用 JSON。每个实现文件导出一个 IMPLEMENTATION 对象，其中包含固定器件名、端口契约、参数契约、Python generator 和实现专用数据。generator 返回局部复数 S 矩阵、目标语言前置计算和观测表达式。

编译器先收集器件的单向参数计算，再组装局部 S 矩阵、全局拓扑矩阵 C 和外部输入，最后生成静态线性求解：

outgoing = (I - S C)^(-1) S external_field
incoming = C outgoing + external_field

生成 MATLAB 时使用反斜杠线性求解，不生成显式矩阵逆。MATLAB 不是 Python 包的运行时依赖；测试可以先验证源码和契约，再在装有 MATLAB 的环境执行生成函数。

包内结构

photoncir/
├── __init__.py
├── base.py                 # 公开 DSL 原语和 build
├── devices.py              # 公开前端器件 facade
├── naming.py               # CIR 器件名和实例名规则
├── dsl/                    # DSL 内部实现
│   ├── core.py             # Component、Device、Module、端口、参数
│   ├── circuit.py          # Circuit 作用域和连接登记
│   ├── io.py               # Input、Probe
│   ├── compiler.py         # 深度优先展开、union-find、CIR 构建
│   └── devices/            # 前端器件声明
├── cir/                    # 平坦 CIR 数据对象、序列化和 parser
└── implementer/            # 后端契约、库加载和目标代码生成
    ├── library.py          # Python 实现对象和注册表
    ├── devices.py          # free 库入口
    ├── matlab.py           # `.cir` 到 MATLAB 源码
    └── device_library/     # 内置 Python 器件实现

base.py、devices.py 和 implementer 是使用入口；dsl、cir 和 implementer/device_library 分别承担内部前端、格式处理和后端器件实现。.cir 是 DSL 与 implementer 之间唯一的交接边界。

示例和测试

完整 DSL 示例：

PYTHONPATH=. python examples/all_syntax.py

生成按 EPHIC 论文公开参数构造的 PhotonCir v1 稳态扫描示例：

PYTHONPATH=. python examples/ephic_static_linear.py
PYTHONPATH=. python examples/ephic_thermal_control.py
PYTHONPATH=. python examples/wang2022_ptdm.py
PYTHONPATH=. python examples/xie2025_pwm.py

随后可在 MATLAB 中运行统一波长扫描：

run('examples/reproduce_ephic_device_scans.m')
run('examples/reproduce_ephic_fig17_spectrum.m')
run('examples/reproduce_wang2022_ring_scan.m')
run('examples/reproduce_xie2025_ring_scan.m')

该脚本直接调用生成的 .m，检查论文参数下的器件输出、解析关系和外部功率平衡，不生成新的 CSV。完整仓库中的文章、扫描图和 Simulink Fig.17 LTM 功能模型位于 docs/PhotonCir_EPHIC复现.md 与 simulink/reproduction/。

该示例中 Fig.10--12 使用论文列出的半径、耦合、折射率和损耗参数。MRM、MZI、MZM 示例验证公开方程形式与组合拓扑；论文未给出的 PDK 多项式、尺寸和热参数只能由用户数据补齐，示例值不能当作论文数值复现。

在源码目录 PhotonCir/ 中运行测试：

PYTHONPATH=. python -m unittest discover -s tests -q

PhotonCir 光学包本身不实现激光器、PD 电路、加热器、热 RC、载流子状态、Kerr/TPA/FCA/FCD、偏振展开、时间步进、依赖未知内部光场的非线性方程迭代、SPICE 方言或有限元求解。激励与观测统一由 Input 和 Probe 表达；吸收功率经 Probe 输出到 MATLAB/Simulink 热系统，温度再作为 Input 反馈，因此自热闭环属于当前完整系统能力。未来的双偏振 implementer 仍复用一个物理 Oport 和同一个 | 连接，只在后端展开模式；动态、非线性和偏振能力都不应改变 DSL 的基本连接语法。

License

MIT，见 LICENSE。