Metadata-Version: 2.4
Name: photoncir
Version: 0.1.0a2
Summary: PhotonCir topology DSL and flat static-model CIR interchange
Author: 李墨林
License-Expression: MIT
Keywords: photonics,circuit,DSL,MATLAB,S-parameters
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# PhotonCir

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

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

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

## 安装

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

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

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

从源码开发：

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

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

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

## 前端：Python DSL 到 `.cir`

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

```python
from photoncir.base import *
from photoncir.devices import *
```

最小电路：

```python
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` 和显式实现库：

```python
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 和外部输入，最后生成静态线性求解：

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

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

## 包内结构

```text
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 示例：

```bash
PYTHONPATH=. python examples/all_syntax.py
```

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

```bash
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 中运行统一波长扫描：

```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/` 中运行测试：

```bash
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](LICENSE)。
