photokinetics 2.0.0__tar.gz

photokinetics-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cogito Lin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

photokinetics-2.0.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: photokinetics
+Version: 2.0.0
+Summary: Photokinetics V2.0 — 可微光学物理引擎 (Differentiable Optics Engine in PyTorch)
+Author-email: Cogito Lin <noreply@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/XxLCFLXx/photokinetics
+Project-URL: Repository, https://github.com/XxLCFLXx/photokinetics
+Project-URL: Documentation, https://github.com/XxLCFLXx/photokinetics#readme
+Project-URL: Bug Tracker, https://github.com/XxLCFLXx/photokinetics/issues
+Project-URL: Online Calculator, https://xxlcflxx.github.io/photokinetics/calculator/photokinetics_calculator.html
+Keywords: optics,photonics,photothermal,differentiable-physics,pytorch,ai-for-science,laser,optical-tweezer,physics-engine
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=1.10.0
+Requires-Dist: numpy>=1.20.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: build>=0.8.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Provides-Extra: examples
+Requires-Dist: matplotlib>=3.5.0; extra == "examples"
+Dynamic: license-file
+
+# Photokinetics V2.0
+
+**可微光学物理引擎 (Differentiable Optics Engine in PyTorch)**
+
+基于光子动能传递的光学统一计算框架，使用 PyTorch 实现，天然支持自动微分、批量计算和逆向设计。
+
+## 核心特性
+
+- **可微分** — 所有公式返回 `torch.Tensor`，支持 `requires_grad=True` 自动求导
+- **批量化** — 参数可以是张量，自动向量化（如批量光强扫描）
+- **纯解析** — 没有数值积分，没有训练数据，直接公式计算
+- **极速** — 比 1D-FDTD 快 10²~10³x，比 3D-FDTD 理论快 10⁶~10⁹x
+- **统一框架** — 8 个光学模块从同一套光子动能传递公设推导
+
+## 安装
+
+```bash
+pip install photokinetics
+```
+
+## 快速开始
+
+### 基本计算
+
+```python
+from photokinetics import calc_photothermal
+
+# 计算水在 1064nm 激光下的温升
+result = calc_photothermal(
+    n=1.33, kappa=0.00012, wavelength_nm=1064,
+    I0=1e7, rho=1000, Cp=4186, depth_mm=1.0, time_s=1.0
+)
+print(f"温升: {result['dT'].item():.2f} K")
+# 输出: 温升: 877.02 K
+```
+
+### 自动微分
+
+```python
+import torch
+from photokinetics import calc_photothermal
+
+I0 = torch.tensor(1e7, requires_grad=True)
+result = calc_photothermal(1.33, 0.00012, 1064, I0, 1000, 4186, 1.0, 1.0)
+result['dT'].backward()
+
+print(f"d(ΔT)/d(I₀) = {I0.grad.item():.2e}")
+# 输出: 8.77e-05
+```
+
+### 逆向设计（梯度下降求光强）
+
+```python
+import torch
+from photokinetics import calc_photothermal
+
+target_dT = 100.0
+I0 = torch.tensor(1e5, requires_grad=True)
+optimizer = torch.optim.Adam([I0], lr=5e4)
+
+for i in range(100):
+    optimizer.zero_grad()
+    result = calc_photothermal(1.33, 0.00012, 1064, I0, 1000, 4186, 1.0, 1.0)
+    loss = (result['dT'] - target_dT) ** 2
+    loss.backward()
+    optimizer.step()
+
+print(f"I₀ = {I0.item():.2e}, ΔT = {result['dT'].item():.2f} K")
+# 输出: I₀ = 1.15e+06, ΔT = 100.52 K
+```
+
+### 批量计算
+
+```python
+import torch
+from photokinetics import calc_photothermal
+
+I0_batch = torch.logspace(4, 8, 1000)  # 1000 个光强
+result = calc_photothermal(1.33, 0.00012, 1064, I0_batch, 1000, 4186, 1.0, 1.0)
+print(result['dT'].shape)  # torch.Size([1000])
+```
+
+## 8 个模块速查表
+
+| 模块 | 函数 | 核心参数 |
+|------|------|---------|
+| 光电效应 | `calc_photoelectric(phi_ev, lambda_nm)` | 逸出功, 波长 |
+| 黑体辐射 | `calc_blackbody(T, lambda_nm=None)` | 温度, 波长 |
+| 康普顿散射 | `calc_compton(E0_keV, theta_deg)` | 入射能量, 散射角 |
+| 多普勒效应 | `calc_doppler(nu0, v_km_s, receding)` | 频率, 速度 |
+| 引力红移 | `calc_gravitational_redshift(M, r1, r2)` | 质量, 半径 |
+| **光热模型** | `calc_photothermal(n, kappa, λ, I0, ρ, Cp, z, t)` | 8 个参数 |
+| 非线性光学 | `calc_nonlinear_order(Eg_eV, lambda_nm)` | 禁带, 波长 |
+| 光镊力 | `calc_tweezer_force(a, n_p, n_m, λ, grad_I)` | 半径, 折射率 |
+
+## 物理常数
+
+所有常数使用 CODATA 2018 推荐值，定义为 `torch.tensor`。
+
+## 性能对比
+
+与 1D-FDTD 数值仿真对比（绝热近似适用域内）：
+
+| 材料 | ΔT 误差 | 加速比 |
+|------|---------|--------|
+| 水 @ 1064nm | 3.49% | 1125x |
+| 硅 @ 532nm | 0.98% | 97x |
+| 锗 @ 532nm | 1.15% | 385x |
+
+详见 [benchmarks/](https://github.com/XxLCFLXx/photokinetics/tree/main/benchmarks)。
+
+## 应用场景
+
+- **AI for Science** — 嵌入 PyTorch 做物理驱动机器学习
+- **逆向设计** — 已知目标温升，梯度下降反推光强/波长
+- **灵敏度分析** — 计算各参数对输出的梯度
+- **参数扫描** — 批量计算数千组参数
+- **实时仿真** — 解析公式微秒级计算
+- **教学/科普** — 在线计算器 [在线体验](https://xxlcflxx.github.io/photokinetics/calculator/photokinetics_calculator.html)
+
+## 限制
+
+- 光热模型采用绝热近似，适用条件 `t ≪ L²/D`
+- 目前支持平面波入射 + 均匀介质
+- 光镊力使用瑞利近似（小颗粒，a ≪ λ）
+
+## 引用
+
+如果本项目对您的研究有帮助，请引用：
+
+```bibtex
+@misc{photokinetics2026,
+  title={Photokinetics V2.0: A Differentiable Optics Engine},
+  author={Cogito Lin},
+  year={2026},
+  url={https://github.com/XxLCFLXx/photokinetics}
+}
+```
+
+## License
+
+MIT

photokinetics-2.0.0/README.md

@@ -0,0 +1,142 @@
+# Photokinetics V2.0
+
+**可微光学物理引擎 (Differentiable Optics Engine in PyTorch)**
+
+基于光子动能传递的光学统一计算框架，使用 PyTorch 实现，天然支持自动微分、批量计算和逆向设计。
+
+## 核心特性
+
+- **可微分** — 所有公式返回 `torch.Tensor`，支持 `requires_grad=True` 自动求导
+- **批量化** — 参数可以是张量，自动向量化（如批量光强扫描）
+- **纯解析** — 没有数值积分，没有训练数据，直接公式计算
+- **极速** — 比 1D-FDTD 快 10²~10³x，比 3D-FDTD 理论快 10⁶~10⁹x
+- **统一框架** — 8 个光学模块从同一套光子动能传递公设推导
+
+## 安装
+
+```bash
+pip install photokinetics
+```
+
+## 快速开始
+
+### 基本计算
+
+```python
+from photokinetics import calc_photothermal
+
+# 计算水在 1064nm 激光下的温升
+result = calc_photothermal(
+    n=1.33, kappa=0.00012, wavelength_nm=1064,
+    I0=1e7, rho=1000, Cp=4186, depth_mm=1.0, time_s=1.0
+)
+print(f"温升: {result['dT'].item():.2f} K")
+# 输出: 温升: 877.02 K
+```
+
+### 自动微分
+
+```python
+import torch
+from photokinetics import calc_photothermal
+
+I0 = torch.tensor(1e7, requires_grad=True)
+result = calc_photothermal(1.33, 0.00012, 1064, I0, 1000, 4186, 1.0, 1.0)
+result['dT'].backward()
+
+print(f"d(ΔT)/d(I₀) = {I0.grad.item():.2e}")
+# 输出: 8.77e-05
+```
+
+### 逆向设计（梯度下降求光强）
+
+```python
+import torch
+from photokinetics import calc_photothermal
+
+target_dT = 100.0
+I0 = torch.tensor(1e5, requires_grad=True)
+optimizer = torch.optim.Adam([I0], lr=5e4)
+
+for i in range(100):
+    optimizer.zero_grad()
+    result = calc_photothermal(1.33, 0.00012, 1064, I0, 1000, 4186, 1.0, 1.0)
+    loss = (result['dT'] - target_dT) ** 2
+    loss.backward()
+    optimizer.step()
+
+print(f"I₀ = {I0.item():.2e}, ΔT = {result['dT'].item():.2f} K")
+# 输出: I₀ = 1.15e+06, ΔT = 100.52 K
+```
+
+### 批量计算
+
+```python
+import torch
+from photokinetics import calc_photothermal
+
+I0_batch = torch.logspace(4, 8, 1000)  # 1000 个光强
+result = calc_photothermal(1.33, 0.00012, 1064, I0_batch, 1000, 4186, 1.0, 1.0)
+print(result['dT'].shape)  # torch.Size([1000])
+```
+
+## 8 个模块速查表
+
+| 模块 | 函数 | 核心参数 |
+|------|------|---------|
+| 光电效应 | `calc_photoelectric(phi_ev, lambda_nm)` | 逸出功, 波长 |
+| 黑体辐射 | `calc_blackbody(T, lambda_nm=None)` | 温度, 波长 |
+| 康普顿散射 | `calc_compton(E0_keV, theta_deg)` | 入射能量, 散射角 |
+| 多普勒效应 | `calc_doppler(nu0, v_km_s, receding)` | 频率, 速度 |
+| 引力红移 | `calc_gravitational_redshift(M, r1, r2)` | 质量, 半径 |
+| **光热模型** | `calc_photothermal(n, kappa, λ, I0, ρ, Cp, z, t)` | 8 个参数 |
+| 非线性光学 | `calc_nonlinear_order(Eg_eV, lambda_nm)` | 禁带, 波长 |
+| 光镊力 | `calc_tweezer_force(a, n_p, n_m, λ, grad_I)` | 半径, 折射率 |
+
+## 物理常数
+
+所有常数使用 CODATA 2018 推荐值，定义为 `torch.tensor`。
+
+## 性能对比
+
+与 1D-FDTD 数值仿真对比（绝热近似适用域内）：
+
+| 材料 | ΔT 误差 | 加速比 |
+|------|---------|--------|
+| 水 @ 1064nm | 3.49% | 1125x |
+| 硅 @ 532nm | 0.98% | 97x |
+| 锗 @ 532nm | 1.15% | 385x |
+
+详见 [benchmarks/](https://github.com/XxLCFLXx/photokinetics/tree/main/benchmarks)。
+
+## 应用场景
+
+- **AI for Science** — 嵌入 PyTorch 做物理驱动机器学习
+- **逆向设计** — 已知目标温升，梯度下降反推光强/波长
+- **灵敏度分析** — 计算各参数对输出的梯度
+- **参数扫描** — 批量计算数千组参数
+- **实时仿真** — 解析公式微秒级计算
+- **教学/科普** — 在线计算器 [在线体验](https://xxlcflxx.github.io/photokinetics/calculator/photokinetics_calculator.html)
+
+## 限制
+
+- 光热模型采用绝热近似，适用条件 `t ≪ L²/D`
+- 目前支持平面波入射 + 均匀介质
+- 光镊力使用瑞利近似（小颗粒，a ≪ λ）
+
+## 引用
+
+如果本项目对您的研究有帮助，请引用：
+
+```bibtex
+@misc{photokinetics2026,
+  title={Photokinetics V2.0: A Differentiable Optics Engine},
+  author={Cogito Lin},
+  year={2026},
+  url={https://github.com/XxLCFLXx/photokinetics}
+}
+```
+
+## License
+
+MIT

photokinetics-2.0.0/photokinetics/__init__.py

@@ -0,0 +1,40 @@
+"""
+Photokinetics V2.0 — 可微光学物理引擎 (Differentiable Optics Engine)
+
+基于光子动能传递的光学统一计算框架，使用 PyTorch 实现，天然支持自动微分。
+
+8个核心模块:
+    - 光电效应 (photoelectric)
+    - 黑体辐射 (blackbody)
+    - 康普顿散射 (compton)
+    - 多普勒效应 (doppler)
+    - 引力红移 (gravitational)
+    - 光热模型 (photothermal)  — 核心应用
+    - 非线性光学 (nonlinear)
+    - 光镊力 (tweezer)
+
+快速开始:
+    >>> import torch
+    >>> from photokinetics import calc_photothermal
+    >>> I0 = torch.tensor(1e7, requires_grad=True)
+    >>> result = calc_photothermal(1.33, 0.00012, 1064, I0, 1000, 4186, 1.0, 1.0)
+    >>> result['dT'].backward()
+    >>> print(I0.grad)  # d(ΔT)/d(I₀)
+"""
+
+from photokinetics.constants import *
+from photokinetics.utils import *
+from photokinetics.modules.photoelectric import calc_photoelectric
+from photokinetics.modules.blackbody import calc_blackbody
+from photokinetics.modules.compton import calc_compton
+from photokinetics.modules.doppler import calc_doppler
+from photokinetics.modules.gravitational import calc_gravitational_redshift
+from photokinetics.modules.photothermal import calc_photothermal
+from photokinetics.modules.nonlinear import calc_nonlinear_order
+from photokinetics.modules.tweezer import calc_tweezer_force
+
+__version__ = "2.0.0"
+__description__ = "Photokinetics V2.0 - Differentiable optics simulation in PyTorch"
+__author__ = "Cogito Lin"
+__email__ = "noreply@example.com"
+__license__ = "MIT"

photokinetics-2.0.0/photokinetics/constants.py

@@ -0,0 +1,19 @@
+import torch
+
+# CODATA 2018 推荐值
+H         = torch.tensor(6.62607015e-34)     # 普朗克常数 (J·s) — 精确值
+H_EV      = torch.tensor(4.135667696e-15)    # 普朗克常数 (eV·s)
+C         = torch.tensor(2.99792458e8)       # 真空光速 (m/s) — 精确值
+K_B       = torch.tensor(1.380649e-23)       # 玻尔兹曼常数 (J/K) — 精确值
+SIGMA     = torch.tensor(5.670374419e-8)     # 斯特藩-玻尔兹曼常数 W/(m²·K⁴)
+B_WIEN    = torch.tensor(2.897771955e-3)     # 维恩位移常数 (m·K)
+E_C       = torch.tensor(1.602176634e-19)    # 电子电荷 (C) — 精确值
+M_E       = torch.tensor(9.1093837015e-31)   # 电子静止质量 (kg)
+EPSILON_0 = torch.tensor(8.8541878128e-12)   # 真空介电常数 (F/m)
+G         = torch.tensor(6.67430e-11)        # 万有引力常数 m³/(kg·s²)
+M_EARTH   = torch.tensor(5.9722e24)          # 地球质量 (kg)
+R_EARTH   = torch.tensor(6.371e6)            # 地球平均半径 (m)
+
+# 常用组合常数
+HC_EV_NM  = torch.tensor(1239.841984)        # hc (eV·nm)
+LAMBDA_C  = torch.tensor(2.4263102389e-12)   # 电子康普顿波长 λ_c = h/(m_e·c) (m)

photokinetics-2.0.0/photokinetics/modules/__init__.py

@@ -0,0 +1 @@
+"""Photokinetics 物理模块集合。"""

photokinetics-2.0.0/photokinetics/modules/blackbody.py

@@ -0,0 +1,38 @@
+"""黑体辐射模块。"""
+import torch
+from photokinetics.constants import B_WIEN, SIGMA, H, C, K_B
+
+
+def calc_blackbody(T, lambda_nm=None):
+    """
+    黑体辐射计算。
+
+    公式:
+        维恩位移定律:  λ_max·T = b  →  λ_max = b/T
+        斯特藩-玻尔兹曼定律:  j = σ·T⁴
+        普朗克公式(光谱辐射出射度):
+            B(λ,T) = (2πhc²/λ⁵) / [exp(hc/(λkT)) − 1]
+
+    参数:
+        T          — 黑体温度 (K), scalar or tensor
+        lambda_nm  — 指定波长 (nm), scalar or tensor, optional
+
+    返回: (λ_max, j, B_lambda) — 全部为 torch.Tensor
+    """
+    T = torch.as_tensor(T, dtype=torch.float32)
+
+    lambda_max_m = B_WIEN / T
+    lambda_max_nm = lambda_max_m * 1e9
+
+    j = SIGMA * T**4
+
+    B_lambda = None
+    if lambda_nm is not None:
+        lam = torch.as_tensor(lambda_nm, dtype=torch.float32) * 1e-9
+        exponent = H * C / (lam * K_B * T)
+        safe_exp = torch.where(exponent > 500, torch.tensor(500.0), exponent)
+        numerator = 2.0 * torch.pi * H * C**2 / lam**5
+        denominator = torch.exp(safe_exp) - 1.0
+        B_lambda = numerator / denominator
+
+    return lambda_max_nm, j, B_lambda

photokinetics-2.0.0/photokinetics/modules/compton.py

@@ -0,0 +1,39 @@
+"""康普顿散射模块。"""
+import torch
+from photokinetics.constants import H, C, E_C, LAMBDA_C
+
+
+def calc_compton(E0_keV, theta_deg):
+    """
+    康普顿散射计算。
+
+    公式:
+        波长位移:  Δλ = λ_c (1 − cosθ),  λ_c = h/(m_e·c) ≈ 2.426 pm
+        入射波长:  λ₀ = hc/E₀
+        散射波长:  λ' = λ₀ + Δλ
+        散射光子能量:  E' = hc/λ'
+        电子反冲动能:  E_e = E₀ − E'
+
+    参数:
+        E0_keV    — 入射光子能量 (keV), scalar or tensor
+        theta_deg — 散射角 (度), scalar or tensor
+
+    返回: (delta_lambda_pm, E_prime_keV, E_electron_keV) — 全部为 torch.Tensor
+    """
+    E0 = torch.as_tensor(E0_keV, dtype=torch.float32)
+    theta = torch.as_tensor(theta_deg, dtype=torch.float32)
+
+    theta_rad = torch.deg2rad(theta)
+    delta_lambda = LAMBDA_C * (1.0 - torch.cos(theta_rad))
+    delta_lambda_pm = delta_lambda * 1e12
+
+    E0_J = E0 * 1e3 * E_C
+    lambda_0 = H * C / E0_J
+
+    lambda_prime = lambda_0 + delta_lambda
+    E_prime_J = H * C / lambda_prime
+    E_prime_keV = E_prime_J / (1e3 * E_C)
+
+    E_electron_keV = E0 - E_prime_keV
+
+    return delta_lambda_pm, E_prime_keV, E_electron_keV

photokinetics-2.0.0/photokinetics/modules/doppler.py

@@ -0,0 +1,41 @@
+"""多普勒效应模块。"""
+import torch
+from photokinetics.constants import C
+
+
+def calc_doppler(nu0, v_km_s, receding=True):
+    """
+    多普勒效应计算（同时给出经典与相对论结果）。
+
+    公式:
+        β = v/c
+        经典:  ν_obs = ν₀(1 ± v/c)  (+靠近, −远离)
+        相对论:  ν_obs = ν₀ √((1∓β)/(1±β))  (+靠近用+, −远离用−)
+        红移参数:  z = ν₀/ν_obs − 1 (天文标准定义, 远离为正)
+
+    参数:
+        nu0      — 光源静止频率 (Hz), scalar or tensor
+        v_km_s   — 光源速度 (km/s), scalar or tensor
+        receding — True=远离, False=靠近
+
+    返回: (nu_classical, nu_relativistic, z_classical, z_relativistic)
+    """
+    nu0 = torch.as_tensor(nu0, dtype=torch.float32)
+    v = torch.as_tensor(v_km_s, dtype=torch.float32) * 1e3
+    beta = v / C
+
+    if receding:
+        nu_cl = nu0 * (1.0 - beta)
+        nu_rel = nu0 * torch.sqrt((1.0 - beta) / (1.0 + beta))
+    else:
+        nu_cl = nu0 * (1.0 + beta)
+        nu_rel = nu0 * torch.sqrt((1.0 + beta) / (1.0 - beta))
+
+    z_cl = (nu_cl - nu0) / nu0
+
+    if receding:
+        z_rel = (nu0 - nu_rel) / nu_rel
+    else:
+        z_rel = (nu_rel - nu0) / nu0
+
+    return nu_cl, nu_rel, z_cl, z_rel

photokinetics-2.0.0/photokinetics/modules/gravitational.py

@@ -0,0 +1,27 @@
+"""引力红移模块。"""
+import torch
+from photokinetics.constants import G, C
+
+
+def calc_gravitational_redshift(M, r1, r2):
+    """
+    引力红移计算（广义相对论）。
+
+    公式:
+        Δν/ν₀ = GM(1/r₁ - 1/r₂)/c²
+
+    参数:
+        M   — 质量 (kg), scalar or tensor
+        r1  — 发射半径 (m), scalar or tensor
+        r2  — 观测半径 (m), scalar or tensor
+
+    返回: (delta_nu_over_nu0, z) — 相对频移和红移参数
+    """
+    M = torch.as_tensor(M, dtype=torch.float32)
+    r1 = torch.as_tensor(r1, dtype=torch.float32)
+    r2 = torch.as_tensor(r2, dtype=torch.float32)
+
+    delta_nu_over_nu0 = G * M * (1.0 / r1 - 1.0 / r2) / C**2
+    z = delta_nu_over_nu0
+
+    return delta_nu_over_nu0, z

photokinetics-2.0.0/photokinetics/modules/nonlinear.py

@@ -0,0 +1,27 @@
+"""非线性光学模块。"""
+import torch
+from photokinetics.constants import HC_EV_NM
+
+
+def calc_nonlinear_order(Eg_eV, wavelength_nm):
+    """
+    非线性光学多光子吸收阶数判定。
+
+    公式:
+        N = ceil(Eg / hν)
+        其中 hν = hc/λ (eV)
+
+    参数:
+        Eg_eV         — 禁带宽度 (eV), scalar or tensor
+        wavelength_nm — 入射波长 (nm), scalar or tensor
+
+    返回: (N, hv_eV) — 吸收阶数和光子能量
+    """
+    Eg = torch.as_tensor(Eg_eV, dtype=torch.float32)
+    lam = torch.as_tensor(wavelength_nm, dtype=torch.float32)
+
+    hv_eV = HC_EV_NM / lam
+    N = torch.ceil(Eg / hv_eV)
+    N = torch.clamp(N, min=1)
+
+    return N, hv_eV

photokinetics-2.0.0/photokinetics/modules/photoelectric.py

@@ -0,0 +1,29 @@
+"""光电效应模块。"""
+import torch
+from photokinetics.constants import HC_EV_NM
+
+
+def calc_photoelectric(phi_ev, lambda_nm):
+    """
+    光电效应计算（爱因斯坦光电方程）。
+
+    公式:
+        hν  = hc / λ           光子能量
+        E_k = hν - Φ           最大动能（发生光电效应时）
+        V_s = E_k / e          遏止电压（数值上等于 E_k(eV)）
+
+    参数:
+        phi_ev    — 材料逸出功 Φ (eV), scalar or tensor
+        lambda_nm — 入射波长 λ (nm), scalar or tensor
+
+    返回: (hν, occurs, E_k, V_s) — 全部为 torch.Tensor
+    """
+    phi = torch.as_tensor(phi_ev, dtype=torch.float32)
+    lam = torch.as_tensor(lambda_nm, dtype=torch.float32)
+
+    hv = HC_EV_NM / lam
+    occurs = hv > phi
+    ek = torch.where(occurs, hv - phi, torch.tensor(0.0))
+    vs = ek
+
+    return hv, occurs, vs, ek

photokinetics-2.0.0/photokinetics/modules/photothermal.py

@@ -0,0 +1,42 @@
+"""光热模型模块（光动论四步解析模型）。"""
+import torch
+from photokinetics.constants import C
+
+
+def calc_photothermal(n, kappa, wavelength_nm, I0, rho, Cp, depth_mm, time_s):
+    """
+    光动论四步光热解析模型（绝热近似）。
+
+    公式:
+        Step 1: α = 4πκ / (nλ)           吸收系数
+        Step 2: I(z) = I₀·exp(-αz)       光强衰减
+        Step 3: q(z) = α·I(z)            热源密度
+        Step 4: ΔT = q·t / (ρCp)         温升（绝热近似）
+
+    参数:
+        n              — 折射率, scalar or tensor
+        kappa          — 消光系数, scalar or tensor
+        wavelength_nm  — 波长 (nm), scalar or tensor
+        I0             — 入射光强 (W/m²), scalar or tensor
+        rho            — 密度 (kg/m³), scalar or tensor
+        Cp             — 比热 (J/(kg·K)), scalar or tensor
+        depth_mm       — 深度 (mm), scalar or tensor
+        time_s         — 照射时间 (s), scalar or tensor
+
+    返回: dict with keys: alpha, I_z, q_z, dT
+    """
+    n = torch.as_tensor(n, dtype=torch.float32)
+    kappa = torch.as_tensor(kappa, dtype=torch.float32)
+    lam = torch.as_tensor(wavelength_nm, dtype=torch.float32) * 1e-9
+    I0 = torch.as_tensor(I0, dtype=torch.float32)
+    rho = torch.as_tensor(rho, dtype=torch.float32)
+    Cp = torch.as_tensor(Cp, dtype=torch.float32)
+    z = torch.as_tensor(depth_mm, dtype=torch.float32) * 1e-3
+    time_s = torch.as_tensor(time_s, dtype=torch.float32)
+
+    alpha = 4.0 * torch.pi * kappa / (n * lam)
+    I_z = I0 * torch.exp(-alpha * z)
+    q_z = alpha * I_z
+    dT = q_z * time_s / (rho * Cp)
+
+    return {'alpha': alpha, 'I_z': I_z, 'q_z': q_z, 'dT': dT}

photokinetics-2.0.0/photokinetics/modules/tweezer.py

@@ -0,0 +1,37 @@
+"""光镊力模块（瑞利近似）。"""
+import torch
+from photokinetics.constants import C
+
+
+def calc_tweezer_force(a_m, n_particle, n_medium, wavelength_nm, grad_I):
+    """
+    光镊力计算（瑞利近似）。
+
+    公式:
+        α = 4πa³ (m²-1)/(m²+2)     极化率, m = n_particle/n_medium
+        F_grad = n_medium · α · ∇I / c    梯度力
+        F_scat = n_medium · α · ∇I / (2c)  散射力（近似）
+
+    参数:
+        a_m           — 颗粒半径 (m), scalar or tensor
+        n_particle    — 颗粒折射率, scalar or tensor
+        n_medium      — 介质折射率, scalar or tensor
+        wavelength_nm — 波长 (nm), scalar or tensor
+        grad_I        — 光强梯度 (W/m³), scalar or tensor
+
+    返回: dict with keys: alpha, F_grad, F_scat, F_total
+    """
+    a = torch.as_tensor(a_m, dtype=torch.float32)
+    n_p = torch.as_tensor(n_particle, dtype=torch.float32)
+    n_m = torch.as_tensor(n_medium, dtype=torch.float32)
+    grad_I = torch.as_tensor(grad_I, dtype=torch.float32)
+
+    m = n_p / n_m
+    m2 = m**2
+
+    alpha = 4.0 * torch.pi * a**3 * (m2 - 1.0) / (m2 + 2.0)
+    F_grad = n_m * alpha * grad_I / C
+    F_scat = n_m * alpha * grad_I / (2.0 * C)
+    F_total = F_grad + F_scat
+
+    return {'alpha': alpha, 'F_grad': F_grad, 'F_scat': F_scat, 'F_total': F_total}

photokinetics-2.0.0/photokinetics/utils.py

@@ -0,0 +1,27 @@
+"""Photokinetics 工具函数。"""
+import torch
+
+
+def fmt_sci(value, sig=4):
+    """将数值格式化为科学计数法字符串。"""
+    if isinstance(value, torch.Tensor):
+        value = value.item()
+    if value == 0:
+        return "0"
+    return "{:.{}e}".format(value, sig - 1)
+
+
+def fmt_fix(value, sig=4):
+    """将数值格式化为定点数。"""
+    if isinstance(value, torch.Tensor):
+        value = value.item()
+    if abs(value) < 1e-4 or abs(value) >= 1e6:
+        return fmt_sci(value, sig)
+    return "{:.{}g}".format(value, sig)
+
+
+def to_tensor(x, dtype=torch.float32, device=None):
+    """将输入转换为 torch.Tensor。"""
+    if isinstance(x, torch.Tensor):
+        return x.to(dtype=dtype, device=device)
+    return torch.tensor(x, dtype=dtype, device=device)

photokinetics-2.0.0/photokinetics.egg-info/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: photokinetics
+Version: 2.0.0
+Summary: Photokinetics V2.0 — 可微光学物理引擎 (Differentiable Optics Engine in PyTorch)
+Author-email: Cogito Lin <noreply@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/XxLCFLXx/photokinetics
+Project-URL: Repository, https://github.com/XxLCFLXx/photokinetics
+Project-URL: Documentation, https://github.com/XxLCFLXx/photokinetics#readme
+Project-URL: Bug Tracker, https://github.com/XxLCFLXx/photokinetics/issues
+Project-URL: Online Calculator, https://xxlcflxx.github.io/photokinetics/calculator/photokinetics_calculator.html
+Keywords: optics,photonics,photothermal,differentiable-physics,pytorch,ai-for-science,laser,optical-tweezer,physics-engine
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=1.10.0
+Requires-Dist: numpy>=1.20.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: build>=0.8.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Provides-Extra: examples
+Requires-Dist: matplotlib>=3.5.0; extra == "examples"
+Dynamic: license-file
+
+# Photokinetics V2.0
+
+**可微光学物理引擎 (Differentiable Optics Engine in PyTorch)**
+
+基于光子动能传递的光学统一计算框架，使用 PyTorch 实现，天然支持自动微分、批量计算和逆向设计。
+
+## 核心特性
+
+- **可微分** — 所有公式返回 `torch.Tensor`，支持 `requires_grad=True` 自动求导
+- **批量化** — 参数可以是张量，自动向量化（如批量光强扫描）
+- **纯解析** — 没有数值积分，没有训练数据，直接公式计算
+- **极速** — 比 1D-FDTD 快 10²~10³x，比 3D-FDTD 理论快 10⁶~10⁹x
+- **统一框架** — 8 个光学模块从同一套光子动能传递公设推导
+
+## 安装
+
+```bash
+pip install photokinetics
+```
+
+## 快速开始
+
+### 基本计算
+
+```python
+from photokinetics import calc_photothermal
+
+# 计算水在 1064nm 激光下的温升
+result = calc_photothermal(
+    n=1.33, kappa=0.00012, wavelength_nm=1064,
+    I0=1e7, rho=1000, Cp=4186, depth_mm=1.0, time_s=1.0
+)
+print(f"温升: {result['dT'].item():.2f} K")
+# 输出: 温升: 877.02 K
+```
+
+### 自动微分
+
+```python
+import torch
+from photokinetics import calc_photothermal
+
+I0 = torch.tensor(1e7, requires_grad=True)
+result = calc_photothermal(1.33, 0.00012, 1064, I0, 1000, 4186, 1.0, 1.0)
+result['dT'].backward()
+
+print(f"d(ΔT)/d(I₀) = {I0.grad.item():.2e}")
+# 输出: 8.77e-05
+```
+
+### 逆向设计（梯度下降求光强）
+
+```python
+import torch
+from photokinetics import calc_photothermal
+
+target_dT = 100.0
+I0 = torch.tensor(1e5, requires_grad=True)
+optimizer = torch.optim.Adam([I0], lr=5e4)
+
+for i in range(100):
+    optimizer.zero_grad()
+    result = calc_photothermal(1.33, 0.00012, 1064, I0, 1000, 4186, 1.0, 1.0)
+    loss = (result['dT'] - target_dT) ** 2
+    loss.backward()
+    optimizer.step()
+
+print(f"I₀ = {I0.item():.2e}, ΔT = {result['dT'].item():.2f} K")
+# 输出: I₀ = 1.15e+06, ΔT = 100.52 K
+```
+
+### 批量计算
+
+```python
+import torch
+from photokinetics import calc_photothermal
+
+I0_batch = torch.logspace(4, 8, 1000)  # 1000 个光强
+result = calc_photothermal(1.33, 0.00012, 1064, I0_batch, 1000, 4186, 1.0, 1.0)
+print(result['dT'].shape)  # torch.Size([1000])
+```
+
+## 8 个模块速查表
+
+| 模块 | 函数 | 核心参数 |
+|------|------|---------|
+| 光电效应 | `calc_photoelectric(phi_ev, lambda_nm)` | 逸出功, 波长 |
+| 黑体辐射 | `calc_blackbody(T, lambda_nm=None)` | 温度, 波长 |
+| 康普顿散射 | `calc_compton(E0_keV, theta_deg)` | 入射能量, 散射角 |
+| 多普勒效应 | `calc_doppler(nu0, v_km_s, receding)` | 频率, 速度 |
+| 引力红移 | `calc_gravitational_redshift(M, r1, r2)` | 质量, 半径 |
+| **光热模型** | `calc_photothermal(n, kappa, λ, I0, ρ, Cp, z, t)` | 8 个参数 |
+| 非线性光学 | `calc_nonlinear_order(Eg_eV, lambda_nm)` | 禁带, 波长 |
+| 光镊力 | `calc_tweezer_force(a, n_p, n_m, λ, grad_I)` | 半径, 折射率 |
+
+## 物理常数
+
+所有常数使用 CODATA 2018 推荐值，定义为 `torch.tensor`。
+
+## 性能对比
+
+与 1D-FDTD 数值仿真对比（绝热近似适用域内）：
+
+| 材料 | ΔT 误差 | 加速比 |
+|------|---------|--------|
+| 水 @ 1064nm | 3.49% | 1125x |
+| 硅 @ 532nm | 0.98% | 97x |
+| 锗 @ 532nm | 1.15% | 385x |
+
+详见 [benchmarks/](https://github.com/XxLCFLXx/photokinetics/tree/main/benchmarks)。
+
+## 应用场景
+
+- **AI for Science** — 嵌入 PyTorch 做物理驱动机器学习
+- **逆向设计** — 已知目标温升，梯度下降反推光强/波长
+- **灵敏度分析** — 计算各参数对输出的梯度
+- **参数扫描** — 批量计算数千组参数
+- **实时仿真** — 解析公式微秒级计算
+- **教学/科普** — 在线计算器 [在线体验](https://xxlcflxx.github.io/photokinetics/calculator/photokinetics_calculator.html)
+
+## 限制
+
+- 光热模型采用绝热近似，适用条件 `t ≪ L²/D`
+- 目前支持平面波入射 + 均匀介质
+- 光镊力使用瑞利近似（小颗粒，a ≪ λ）
+
+## 引用
+
+如果本项目对您的研究有帮助，请引用：
+
+```bibtex
+@misc{photokinetics2026,
+  title={Photokinetics V2.0: A Differentiable Optics Engine},
+  author={Cogito Lin},
+  year={2026},
+  url={https://github.com/XxLCFLXx/photokinetics}
+}
+```
+
+## License
+
+MIT

photokinetics-2.0.0/photokinetics.egg-info/SOURCES.txt

@@ -0,0 +1,21 @@
+LICENSE
+README.md
+pyproject.toml
+photokinetics/__init__.py
+photokinetics/constants.py
+photokinetics/utils.py
+photokinetics.egg-info/PKG-INFO
+photokinetics.egg-info/SOURCES.txt
+photokinetics.egg-info/dependency_links.txt
+photokinetics.egg-info/requires.txt
+photokinetics.egg-info/top_level.txt
+photokinetics/modules/__init__.py
+photokinetics/modules/blackbody.py
+photokinetics/modules/compton.py
+photokinetics/modules/doppler.py
+photokinetics/modules/gravitational.py
+photokinetics/modules/nonlinear.py
+photokinetics/modules/photoelectric.py
+photokinetics/modules/photothermal.py
+photokinetics/modules/tweezer.py
+tests/test_all.py

photokinetics-2.0.0/photokinetics.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

photokinetics-2.0.0/photokinetics.egg-info/requires.txt

@@ -0,0 +1,10 @@
+torch>=1.10.0
+numpy>=1.20.0
+
+[dev]
+pytest>=7.0
+build>=0.8.0
+twine>=4.0.0
+
+[examples]
+matplotlib>=3.5.0

photokinetics-2.0.0/photokinetics.egg-info/top_level.txt

@@ -0,0 +1 @@
+photokinetics

photokinetics-2.0.0/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "photokinetics"
+version = "2.0.0"
+description = "Photokinetics V2.0 — 可微光学物理引擎 (Differentiable Optics Engine in PyTorch)"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.8"
+authors = [
+    {name = "Cogito Lin", email = "noreply@example.com"}
+]
+keywords = [
+    "optics",
+    "photonics",
+    "photothermal",
+    "differentiable-physics",
+    "pytorch",
+    "ai-for-science",
+    "laser",
+    "optical-tweezer",
+    "physics-engine"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Physics",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "torch>=1.10.0",
+    "numpy>=1.20.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "build>=0.8.0",
+    "twine>=4.0.0",
+]
+examples = [
+    "matplotlib>=3.5.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/XxLCFLXx/photokinetics"
+Repository = "https://github.com/XxLCFLXx/photokinetics"
+Documentation = "https://github.com/XxLCFLXx/photokinetics#readme"
+"Bug Tracker" = "https://github.com/XxLCFLXx/photokinetics/issues"
+"Online Calculator" = "https://xxlcflxx.github.io/photokinetics/calculator/photokinetics_calculator.html"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["photokinetics*"]
+
+[tool.setuptools.package-data]
+photokinetics = ["*.md", "*.txt"]

photokinetics-2.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

photokinetics-2.0.0/tests/test_all.py

@@ -0,0 +1,77 @@
+"""Photokinetics 单元测试。"""
+import torch
+from photokinetics import (
+    calc_photoelectric,
+    calc_blackbody,
+    calc_compton,
+    calc_doppler,
+    calc_gravitational_redshift,
+    calc_photothermal,
+    calc_nonlinear_order,
+    calc_tweezer_force,
+)
+
+
+def test_photoelectric():
+    phi = torch.tensor(2.28, requires_grad=True)
+    lam = torch.tensor(400.0, requires_grad=True)
+    hv, occurs, vs, ek = calc_photoelectric(phi, lam)
+    ek.backward()
+    assert torch.isclose(hv, torch.tensor(3.0996), rtol=1e-4)
+    assert occurs.item() == True
+    assert torch.isclose(vs, torch.tensor(0.8196), rtol=1e-4)
+
+
+def test_blackbody():
+    T = torch.tensor(5778.0, requires_grad=True)
+    lambda_max, j, _ = calc_blackbody(T, 500.0)
+    j.backward()
+    assert torch.isclose(lambda_max, torch.tensor(501.52), rtol=1e-3)
+    assert torch.isclose(j, torch.tensor(6.312e7), rtol=1e-2)
+
+
+def test_compton():
+    E0 = torch.tensor(17.4, requires_grad=True)
+    dl, Ep, Ee = calc_compton(E0, 90.0)
+    Ee.backward()
+    assert torch.isclose(dl, torch.tensor(2.426), rtol=1e-3)
+
+
+def test_doppler():
+    nu0 = torch.tensor(5e14, requires_grad=True)
+    _, _, _, z_rel = calc_doppler(nu0, 30000.0, receding=True)
+    z_rel.backward()
+    assert torch.isclose(z_rel, torch.tensor(0.1056), rtol=1e-3)
+
+
+def test_gravitational():
+    r1 = torch.tensor(6.371e6, requires_grad=True)
+    dnu, z = calc_gravitational_redshift(5.9722e24, r1, 1e9)
+    z.backward()
+    assert torch.isclose(dnu, torch.tensor(6.95e-10), rtol=1e-2)
+
+
+def test_photothermal():
+    I0 = torch.tensor(1e7, requires_grad=True)
+    result = calc_photothermal(1.33, 0.00012, 1064, I0, 1000, 4186, 1.0, 1.0)
+    result['dT'].backward()
+    assert torch.isclose(result['dT'], torch.tensor(877.02), rtol=1e-2)
+
+
+def test_nonlinear():
+    N, hv = calc_nonlinear_order(1.12, 800.0)
+    assert N.item() == 1
+
+
+def test_tweezer():
+    a = torch.tensor(1e-6, requires_grad=True)
+    result = calc_tweezer_force(a, 1.59, 1.33, 1064.0, 5e17)
+    result['F_grad'].backward()
+    assert a.grad is not None
+
+
+def test_batch():
+    I0_batch = torch.tensor([1e6, 1e7, 1e8], requires_grad=True)
+    result = calc_photothermal(1.33, 0.00012, 1064, I0_batch, 1000, 4186, 1.0, 1.0)
+    result['dT'].sum().backward()
+    assert I0_batch.grad is not None