Metadata-Version: 2.4
Name: cps-twin
Version: 0.1.2
Summary: Nereus (同衡) — deterministic digital-twin simulation kernels (warehouse + factory), layout validator, and headless CLI — CPS standard edition
Author: CPS Contributors
License: MIT
Project-URL: Homepage, https://cps.123aiot.com
Project-URL: Source, https://github.com/123aiot/CPS
Project-URL: Documentation, https://github.com/123aiot/CPS/tree/main/docs
Keywords: digital-twin,simulation,warehouse,amr,factory,deterministic,discrete-event,throughput,what-if,wcs
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Manufacturing
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2
Requires-Dist: pyyaml>=6
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"

# cps-twin — Nereus 同衡（CPS 标准版）

> **万物同衡，虚实相应** —— 海神双芯，智造同频。

可嵌入的**确定性**仿真内核：仓储（AMR/提升机/输送线）与产线（工位/输送带/返修/AMR）双域引擎、
布局权威校验器、headless CLI。同 seed 同输入 → **逐位一致**的结果，可直接用于
容量验证、what-if 对比、CI 管道内的回归仿真。

> **标准版 vs 专业版**：本包只含可嵌入内核（无 UI / 无服务 / 无 LLM）。
> 3D 设计器、AI Copilot（HITL 审批）、多租户、OPC UA/Modbus/MQTT 网关、TimescaleDB
> 属专业版（Docker 镜像 + docker compose 本地部署），见 [仓库](https://github.com/123aiot/CPS)。

## 安装

```bash
pip install cps-twin
```

## 快速开始

```bash
# 仓储引擎：内置样例布局，推 3600 拍（= 6 分钟仿真时长）
cps-twin simulate-warehouse --ticks 3600 --seed 42

# 产线引擎：参数样例见仓库 config/simulation_parameters.yaml
cps-twin simulate-factory --params simulation_parameters.yaml --ticks 3600

# 布局权威校验（越界/重叠/接入点被封/不连通）
cps-twin validate --layout warehouse_layout.json
```

## 作为库使用

```python
from warehouse_twin.sim.engine import SimEngine
from warehouse_twin.sim.navgrid import load_layout

eng = SimEngine(load_layout("warehouse_layout.json"), seed=42)
for _ in range(3600):
    eng.step()
print(eng.state["kpi"]["operation"]["throughput_per_min"])
```

```python
from domain_factory.engine import FactoryEngine
from domain_factory.params import load_params

eng = FactoryEngine(run_id="R1", seed=42, params=load_params())
eng.run_ticks(3600)
print(eng.kpis()["oee"]["oee"])
```

## 确定性的机制（为什么可以信）

- 固定 tick（100ms）驱动，墙钟只出现在 `generated_at`；
- 具名 RNG 流（`RngService`），`dump_state`/`load_state` 覆盖内部态——what-if 分支靠**复制状态**而非 re-seed；
- `state_hash` / `parameter_hash` 进 provenance，运行数据可溯源到精确引擎+参数组合；
- 引擎行为由多 seed 分域哈希对拍基线（黄金快照）持续验证，比对失败可定位到子系统。

详见仓库 `docs/adr/0001`（确定性内核）、`0008`（物料守恒）、`0009`（参数指纹）。

## License

MIT
