Metadata-Version: 2.4
Name: photoncir
Version: 0.1.0a4
Summary: PhotonCir topology DSL and flat static-model CIR interchange
Author: 李墨林
License-Expression: MIT
Project-URL: Homepage, https://github.com/limolin234/EPHIC_simulation/tree/main/PhotonCir
Project-URL: Documentation, https://github.com/limolin234/EPHIC_simulation/blob/main/PhotonCir/README.md
Project-URL: Source, https://github.com/limolin234/EPHIC_simulation/tree/main/PhotonCir
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 声明器件、输入和观测，生成平坦 CIR，再用独立器件实现库生成 MATLAB 函数。当前光网络为静态、单模式、复线性；时间推进、热状态和控制器由调用方承担。

```text
Python DSL → build → .cir → compile_matlab + 实现库 → .m
```

## 安装与文档

需要 Python 3.11 或更高版本。从本目录安装当前源码：

```bash
python -m pip install -e .
```

核心包没有第三方运行时依赖，MATLAB 只用于执行生成函数。发布包与工作区版本的内容以各自源码为准。

- [DSL 用法与设计](https://github.com/limolin234/EPHIC_simulation/blob/main/docs/PhotonCir_DSL.md)：Input/Probe 的声明、默认值、层次接口和 CIR。
- [Implementor](https://github.com/limolin234/EPHIC_simulation/blob/main/docs/PhotonCir_implementor.md)：自包含模型文件、自定义库接入、表达式、求解和运行边界。
- [自定义包示例说明](examples/custom_library/README.md)：文件职责、运行方法、新增器件及三个返回值的含义；[demo.py](examples/custom_library/demo.py) 是可执行入口。
- [物理复现](https://github.com/limolin234/EPHIC_simulation/blob/main/docs/PhotonCir_EPHIC%E5%A4%8D%E7%8E%B0.md)：物理模型、实验依据和验证范围。

## 接口

只使用三种端口语义：

- `Oport(default=0)`：双向光端口，默认值是入射复场。
- `Input(default=...)`：类中声明外部确定的普通数值输入。
- `Probe()`：类中声明可逐层导出的纯观测接口。

电路中用 `Input("name")` 创建整个电路的外部输入，用 `Probe("name", port)` 选择返回值。普通输入、参数和观测直接支持实数与复数，不按温度、电压等物理量分类；单位和物理检查由器件作者负责。

```python
from photoncir.base import Circuit, Input, Probe, build
from photoncir.devices import WaveGuide

with Circuit("demo") as circuit:
    wg = WaveGuide(length=1e-3)
    wg.o_left = Input("field")
    wg.t_temperature = Input("temperature")
    wg.r_wavelength.default = 1550e-9
    Probe("field_out", wg.o_right)
    Probe("heat", wg.p_absorbed_power)

build(circuit, "demo.cir")

from photoncir.implementer import compile_matlab, free_linear_library

compile_matlab("demo.cir", free_linear_library(), path="demo.m")
```

将以上代码保存为 `demo.py`，安装包后运行 `python demo.py`，会在当前目录生成 `demo.cir` 和 `demo.m`。在该目录启动 MATLAB：

```matlab
[field_out, heat] = demo(1, 300);
power_out = abs(field_out)^2;
```

函数实参按顶层 Input 创建顺序排列，返回值按 Probe 创建顺序排列。本例波长固定在 CIR 中，温度由每次 MATLAB 调用传入。修改固定参数或默认值后需要重新 build 和编译；扫描外部输入只需重复调用 `.m`。生成、读取 CIR 和生成 MATLAB 源码均不要求安装 MATLAB；执行 `.m` 才需要 MATLAB。

输入光场 `1` 是归一化复振幅；只有所选模型约定 `abs(field)^2` 的单位为 W 时，`heat` 才能直接作为瓦特量输入热模型。`power_out` 是该出射端口的功率，双向端口上的净功率还要考虑入射场。

有效连接优先于默认值；无连接时使用 CIR 中的 `default_<端口名>`；两者都没有则报错。Probe 不提供输入。固定参数按 `name=value` 识别，端口按声明顺序排列。类型、有限数值和连接结构由框架检查，物理范围使用器件自己的 `check()`，在构造和 build 时自动执行。

Module 用同一套接口连接内部器件，build 时递归展开。类内 Probe 可以逐层转接，同一 Probe net 的多个叶观测求和；不把观测变成反馈输入。

## 自定义器件与模型

前端直接 import 即可，无需注册：

```python
from my_devices import CustomWaveGuide
```

后端每个文件声明 `name`、`ports`、`parameters`、`code`、`s_matrix`、`observations`。端口是 `("temperature", "input")` 等二元组。模型文件无需导入框架对象；局部变量自动加实例前缀，功率等观测表达式由作者自行定义。

显式选择实现库：

```python
import my_models
from photoncir.implementer import compile_matlab

compile_matlab("demo.cir", my_models.library(), path="demo.m")
```

`my_models.library()` 可以用 `load_linear_library(目录)` 扫描自包含文件。新增模型文件即被发现；也可 `library.register(已 import 的模型模块)`。前端 import 不隐式改变全局后端模型。包布局、与内置库混用和信任边界详见 Implementor 文档。

## 内置模型

叶器件包括 WaveGuide、DirectionalCoupler、MMICoupler、YJunction、VoltageTunableWaveguide；组合器件包括 SingleBusRing、AddDropRing、SecondOrderRing、MicroringModulator、MachZehnderInterferometer、MachZehnderModulator。

MMI 为理想互易四端口，支持分光比与功率效率；效率为 1 时与相同分光比的理想方向耦合器矩阵一致。YJunction 保留完整反向关系；有源波导使用电压多项式并导出电容观测。实现库可替换为适合具体器件的数据模型，不改变前端组织方式。

当前包不实现传播动态、内部场非线性迭代、偏振展开或热状态积分。输出吸收功率并由外部热系统回传温度可形成系统光热闭环，但不把这一能力等同于内部全时域多物理求解。

“复线性”指固定外部输入后对未知光场的求解：折射率随温度或电压非线性变化、Probe 计算模平方都可以。依赖本轮未知腔内光强的 Kerr 等自洽关系需要额外求解机制。热状态由外部推进时，整个闭环仍可表现出非线性；接口允许实现这种闭环，具体工况的准确度需要验证。

当前每次函数调用重新构造稠密矩阵并求解，没有分解缓存、自动批量扫参或时间积分。每次传入标量实数/复数；数组输入不是保证的批量接口。加载成功和编译成功不保证矩阵可逆、模型无源或能量守恒，详见 [运行与错误边界](https://github.com/limolin234/EPHIC_simulation/blob/main/docs/PhotonCir_implementor.md#7-%E9%AA%8C%E8%AF%81%E4%B8%8E%E9%94%99%E8%AF%AF%E8%BE%B9%E7%95%8C)。

## 运行示例与测试

从仓库根目录：

```bash
PYTHONPATH=PhotonCir python PhotonCir/examples/custom_library/demo.py /tmp/photoncir-custom
PYTHONPATH=PhotonCir python -m unittest discover -s PhotonCir/tests -q
```

从本目录运行 EPHIC 示例：

```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
```

`examples/all_syntax.py` 展示完整前端语法；`examples/reproduce_*.m` 为对应 MATLAB 扫描。论文未公开的 PDK 或尺寸参数不可当作论文定量复现数据，具体证据边界见物理复现文档。

## License

MIT，见 [LICENSE](LICENSE)。
