Metadata-Version: 2.4
Name: photoncir
Version: 0.1.0a3
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 声明器件、输入和观测，生成平坦 CIR，再用独立器件实现库生成 MATLAB 函数。当前光网络为静态、单模式、复线性；时间推进、热状态和控制器由调用方承担。

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

## 安装与文档

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

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

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

- [DSL 用法与设计](../docs/PhotonCir_DSL.md)：Input/Probe 的声明与使用、默认值、层次接口和 CIR。
- [Implementor](../docs/PhotonCir_implementor.md)：自包含模型文件、自定义库接入、表达式和求解边界。
- [自定义包示例](examples/custom_library/demo.py)：直接 import 第三方器件，显式选择后端库。
- [物理复现](../docs/PhotonCir_EPHIC复现.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")
```

有效连接优先于默认值；无连接时使用 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 保留完整反向关系；有源波导使用电压多项式并导出电容观测。实现库可替换为适合具体器件的数据模型，不改变前端组织方式。

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

## 运行示例与测试

从仓库根目录：

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