Metadata-Version: 2.4
Name: physicsos
Version: 0.1.29
Summary: AI-native physics simulation OS with TAPS-first physics IR, solver planning, and cloud runner tooling.
Project-URL: Homepage, https://github.com/fzj1214/PhysicsOS
Project-URL: Repository, https://github.com/fzj1214/PhysicsOS
Project-URL: Documentation, https://github.com/fzj1214/PhysicsOS#readme
Keywords: physics,simulation,pde,fem,agents,neural-operator
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.7
Requires-Dist: numpy>=1.26
Requires-Dist: deepagents
Requires-Dist: deepagents-cli==0.0.46
Requires-Dist: langgraph
Requires-Dist: langchain-openai
Requires-Dist: rich>=13.7
Requires-Dist: textual<9,>=8
Requires-Dist: httpx<1,>=0.28
Requires-Dist: gmsh>=4.13
Requires-Dist: meshio>=5.3
Requires-Dist: pymatgen>=2025.6
Requires-Dist: seekpath>=2.1
Requires-Dist: spglib>=2.5
Provides-Extra: agents
Provides-Extra: geometry
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Provides-Extra: all

# PhysicsOS

<p align="center">
  <strong>AI-native CAE workspace for paper-style TAPS simulation workflows.</strong><br />
  <span>From a physics problem to derivation, case-local code, verification evidence, and cloud-ready artifacts.</span>
</p>

<p align="center">
  <a href="#english">English</a>
  ·
  <a href="#中文">中文</a>
</p>

<p align="center">
  <img alt="Python" src="https://img.shields.io/badge/python-3.12%2B-3776AB?style=flat-square&logo=python&logoColor=white" />
  <img alt="Status" src="https://img.shields.io/badge/status-alpha-orange?style=flat-square" />
  <img alt="Workflow" src="https://img.shields.io/badge/workflow-TAPS--first-4B8BBE?style=flat-square" />
  <img alt="Runtime" src="https://img.shields.io/badge/runtime-DeepAgents-111827?style=flat-square" />
</p>

---

<a id="english"></a>

## English

PhysicsOS is not another black-box solver wrapper. It is a research-grade CAE agent
workspace that makes simulation work inspectable: the agent reads the problem, prepares
analysis files, builds a compact context window, derives a TAPS formulation, writes
case-local code, runs verification steps, and leaves the full evidence trail on disk.

The current system is built around three ideas:

- **Paper-style TAPS workflows**: derivations are generated from explicit templates,
  matrix definitions, and verification routines instead of silently jumping to a solver.
- **Case-local artifacts**: every run writes a structured `cases/<case_id>/` workspace
  with problem statements, derivations, generated kernels, metadata, plots, and reports.
- **Agent orchestration with deterministic tools**: DeepAgents handles interaction and
  delegation; PhysicsOS tools handle geometry, materials, pseudopotentials, context
  assembly, runner commands, and verification contracts.

### Why It Matters

CAE and scientific computing workflows usually fail in places that are hard to audit:
ambiguous assumptions, hidden solver defaults, missing geometry provenance, unverified
generated code, or material data invented by a model. PhysicsOS is designed to keep those
decisions visible. If a problem needs geometry, materials metadata, Kohn-Sham assumptions,
pseudopotential provenance, or convergence evidence, the system turns that requirement
into a file, a tool call, or an explicit open question.

### What PhysicsOS Can Do

| Area | Capability |
| --- | --- |
| PDE/TAPS | Builds paper-style TAPS derivation prompts, derivation files, case-local kernels, implementation notes, and verification reports. |
| Geometry | Converts STL/CAD or simple generated primitives into Gmsh/SDF/voxel/background-grid artifacts, boundary samples, normals, and cut-cell metadata. |
| Materials | Uses `pymatgen`, `spglib`, and `seekpath` for structure parsing, standardization, symmetry, reciprocal lattices, k-meshes, irreducible k-points, supercells, and high-symmetry paths. |
| KS-DFT-TAPS | Prepares Kohn-Sham TAPS problem context, tensor-basis notes, SCF assumptions, band/DOS provenance checks, and verification contracts. |
| Pseudopotentials | Indexes local VASP PAW/PBE libraries by metadata, hashes, paths, and provenance. PhysicsOS does **not** copy or redistribute POTCAR contents. |
| Cloud runner | Provides PhysicsOS Cloud / foamvm login, job submission, status, logs, artifact listing, and artifact download commands. |
| Agent UX | Launches a PhysicsOS-flavored DeepAgents TUI with subagents, local tool bridges, workspace path translation, runtime events, and model configuration. |

### Architecture In One Screen

```text
user request / files / geometry / materials
        |
        v
analysis files
  problem statement, structured inputs, open questions
        |
        v
context window
  local references, tool outputs, templates, geometry/materials notes
        |
        v
TAPS derivation
  weak form, C-HiDeNN-TD approximation, axis matrices, subspace iterations
        |
        v
case-local implementation
  generated kernel.py, execution plan, runtime metadata
        |
        v
verification
  exact/manufactured solution, convergence, physics checks, plots, reports
        |
        v
revise or package runner artifacts
```

DeepAgents is the interactive harness. PhysicsOS is the domain layer: prompts, tools,
schemas, case files, verification contracts, materials processing, and cloud runner
integration.

### Install

Install from PyPI:

```bash
python -m pip install --upgrade physicsos
physicsos
```

Use Python 3.12 or newer. If your system Python is managed by the OS, create and
activate a virtual environment first (`python3.12 -m venv .venv`, then
`source .venv/bin/activate` on macOS/Linux, or `.venv\Scripts\Activate.ps1` in
PowerShell).

Install the current code from this checkout:

```bash
python -m pip install .
physicsos --version
physicsos
```

For development utilities and installation regression tests:

```bash
python -m pip install -e ".[dev]"
python -m pytest
```

`physicsos` is installed into the same Python environment as pip. If the shell
cannot find the command, activate that environment or use `python -m physicsos`.
The DeepAgents CLI version is pinned because PhysicsOS integrates with its
internal TUI/server interfaces; installing a different version separately can
break startup. Its automatic update checks are disabled inside PhysicsOS; upgrade
PhysicsOS itself with pip. TAPS and KS-DFT reference files are bundled in the Python package.

Requirements:

- Python 3.12+
- An OpenAI-compatible chat model endpoint
- Optional local geometry/materials data depending on the workflow
- Optional PhysicsOS Cloud / foamvm account for remote runner commands

### Configure A Model

On the first interactive launch, PhysicsOS opens a setup screen before starting
the agent if no API key is configured. Choose OpenAI, DeepSeek, or a custom
OpenAI-compatible service, enter its API base URL and API key, and select or type
the model ID. Choose Chat Completions or Responses as required by your provider.
Save to continue into the agent.

The home screen always has a **模型设置 / F2** button. Press **F2**, enter
`/settings` (or bare `/model`), or run `physicsos config` from the shell to reopen
the same screen. It also works after a server startup failure. Saving applies the
new configuration and reconnects the local backend while retaining the conversation.
"检测连接" checks the provider's `/models` endpoint and populates the model list;
providers without that endpoint can be configured manually.

```bash
physicsos config          # Open model, endpoint, API key, and API type settings
physicsos config --show   # Show current configuration status without exposing keys
```

API keys are hidden while typing. Configurations are stored in
`~/.physicsos/config.json` (or `PHYSICSOS_CONFIG`), with owner-only permissions on
Unix. New configurations default to the official OpenAI endpoint; existing custom
endpoints are preserved. `OPENAI_API_KEY` and `OPENAI_BASE_URL` are also supported.
Non-interactive runs without a key exit with a configuration instruction.

Environment variables remain available for scripts and one-off runs:

macOS/Linux:

```bash
export PHYSICSOS_OPENAI_API_KEY="..."
export PHYSICSOS_OPENAI_BASE_URL="https://api.example.com/v1"
export PHYSICSOS_OPENAI_MODEL="gpt-5.4"
```

PowerShell:

```powershell
$env:PHYSICSOS_OPENAI_API_KEY="..."
$env:PHYSICSOS_OPENAI_BASE_URL="https://api.example.com/v1"
$env:PHYSICSOS_OPENAI_MODEL="gpt-5.4"
```

If your provider uses the OpenAI Responses API:

```powershell
$env:PHYSICSOS_OPENAI_USE_RESPONSES_API="true"
```

PhysicsOS also writes a local config file under the active PhysicsOS home directory.
Environment variables override config values for one-off runs. You can also put
the `PHYSICSOS_*` settings in a `.env` file in the directory where you launch
`physicsos`; existing environment variables take precedence. A model API key is
needed for agent requests, but not for `physicsos paths` or `physicsos --help`.

```json
{
  "model": {
    "provider": "openai",
    "name": "gpt-5.4",
    "api_key": "",
    "base_url": "https://api.example.com/v1",
    "use_responses_api": false
  },
  "cloud": {
    "runner_url": "https://foamvm.vercel.app",
    "access_token": ""
  }
}
```

### Start The Agent

```bash
physicsos
```

Run a single request:

```bash
physicsos --non-interactive "derive and verify a 1D steady heat conduction TAPS case"
```

Use `--message` instead to start the interactive UI with an initial request.

Resume a previous interactive session:

```bash
physicsos --resume
```

Use a specific model through DeepAgents:

```bash
physicsos --model openai:gpt-5.4
```

### Local CLI

```bash
physicsos paths
physicsos auth login
physicsos account
physicsos runner submit path/to/manifest.json
physicsos runner status JOB_ID
physicsos runner logs JOB_ID
physicsos runner artifacts JOB_ID
physicsos runner download JOB_ID ARTIFACT_ID
physicsos runner download-all JOB_ID
```

Geometry helper:

```bash
physicsos geometry apply-boundary-labels geometry.json labeling_artifact.json --output confirmed.json
```

Pseudopotential helpers:

```bash
physicsos pseudopotentials config
physicsos pseudopotentials set-root "D:\path\to\vasp_paw_pbe" --library-id vasp-paw-pbe
physicsos pseudopotentials index --case-id pp-index
physicsos pseudopotentials select --case-id si-case --structure-ref cases/si/structure.json
```

`physicsos pp ...` is the short alias for `physicsos pseudopotentials ...`.

### What A Case Produces

```text
cases/<case_id>/
  problem/
  context/
  references/
  geometry/
  materials/
  pseudopotentials/
  taps/
  verification/
  report/
  execution_plan.md
  manifest.json
```

The exact tree depends on the request. Geometry cases include SDF/voxel/boundary
artifacts. Materials cases include standardized structures, symmetry, reciprocal lattice,
k-point, and pseudopotential-provenance artifacts. TAPS cases include derivations,
implementation notes, generated kernels, and verification outputs.

### Runtime Data

Set `PHYSICSOS_HOME` to control where configuration is stored (default:
`~/.physicsos/`). Installed usage writes case artifacts and runtime data to the
current workspace; set `PHYSICSOS_WORKSPACE` to use another directory. Source-checkout
local commands default to the repository workspace; the interactive agent uses the
directory where it was launched.

```text
config        ~/.physicsos/config.json
sessions      <workspace>/sessions/
history       <workspace>/history.jsonl
scratch       <workspace>/scratch/
case memory   <workspace>/data/case_memory.jsonl
knowledge DB  <workspace>/data/knowledge/physicsos_knowledge.sqlite
```

Print the exact active paths:

```bash
physicsos paths
```

### Project Status

PhysicsOS is alpha-stage research infrastructure. It is intentionally transparent and
file-heavy. Expect inspectable intermediate artifacts, explicit assumptions, local
generated code, and verification evidence. It is not a certified solver, not a hidden
VASP/QE/CP2K wrapper, and not a promise that every generated case is correct without
review.

---

<a id="中文"></a>

## 中文

PhysicsOS 不是又一个黑盒求解器封装。它是一个面向 CAE 和科学计算的 AI 原生工作台：从用户给出的物理问题、几何、材料结构或脚本出发，自动组织分析文件，构建上下文窗口，推导 TAPS 公式，生成当前 case 专属代码，执行验证链，并把所有证据留在本地文件中。

它的定位很明确：**让仿真代理的每一步都可检查、可复现、可追责。**

### 核心特点

- **TAPS-first**：以论文式 TAPS / C-HiDeNN-TD 推导为主线，不把问题偷偷塞进固定求解器。
- **case-local**：每个任务都有独立的 `cases/<case_id>/` 工作区，包含问题、推导、代码、验证、图和报告。
- **多 Agent 协作**：DeepAgents 负责交互、子代理和工具调用；PhysicsOS 提供物理、几何、材料、验证和云 runner 工具。
- **几何可追溯**：STL/CAD 或简单几何会被转成 Gmsh、SDF、体素、边界采样、法向和 cut-cell 元数据。
- **材料确定性处理**：晶体结构、空间群、倒格矢、k 点、seekpath 高对称路径由 `pymatgen` / `spglib` / `seekpath` 工具生成，不靠模型硬猜。
- **KS-DFT-TAPS 扩展**：支持 Kohn-Sham TAPS 上下文、张量基、SCF 假设、能带/DOS provenance、赝势元数据和验证契约。
- **赝势不搬运**：PhysicsOS 只记录本地 POTCAR 的 metadata、hash、路径和 provenance，不复制、不分发 POTCAR 正文。

### 它解决什么问题

传统 CAE/DFT/AI 代码生成工作流经常在这些地方失控：假设写不清、默认参数藏起来、几何来源不明、材料结构被模型猜错、生成代码没有验证、结果图无法追溯。PhysicsOS 的做法是把这些关键点变成明确的文件、工具输出、验证报告或 open question。

### 一屏理解架构

```text
用户问题 / 文件 / 几何 / 材料
        |
        v
分析文件
  问题陈述、结构化输入、未决问题
        |
        v
上下文窗口
  本地参考、工具输出、模板、几何/材料说明
        |
        v
TAPS 推导
  弱形式、C-HiDeNN-TD、矩阵定义、子空间迭代
        |
        v
当前 case 专属实现
  kernel.py、执行计划、运行元数据
        |
        v
验证
  精确/制造解、收敛性、物理一致性、图和报告
        |
        v
修正或打包云端 runner 产物
```

### 安装

从 PyPI 安装：

```bash
python -m pip install --upgrade physicsos
physicsos
```

需要 Python 3.12 或更新版本。如果系统 Python 不允许直接安装包，先运行
`python3.12 -m venv .venv` 创建虚拟环境，然后在 macOS/Linux 上运行
`source .venv/bin/activate`，或在 PowerShell 中运行 `.venv\Scripts\Activate.ps1`。

从当前源码目录安装最新代码：

```bash
python -m pip install .
physicsos --version
physicsos
```

开发工具与安装回归测试：

```bash
python -m pip install -e ".[dev]"
python -m pytest
```

命令安装在 pip 所属的 Python 环境中。如果提示找不到 `physicsos`，请先激活
对应环境，或者运行 `python -m physicsos`。PhysicsOS 依赖 DeepAgents CLI 的内部
TUI/服务端接口，因此固定了兼容版本；单独升级 DeepAgents CLI 可能导致启动失败。
PhysicsOS 启动时禁用内嵌 CLI 的自动更新检查，后续请通过 pip 升级 PhysicsOS。
TAPS 和 KS-DFT 参考文件已包含在 Python 安装包中。

需要：

- Python 3.12+
- OpenAI-compatible 模型接口
- 视任务需要准备本地几何/材料/赝势数据
- 如需远端运行，准备 PhysicsOS Cloud / foamvm 账号

### 配置模型

首次运行 `physicsos` 时，如果还没有配置 API Key，会先打开配置向导，再启动 Agent。
选择 OpenAI、DeepSeek 或自定义 OpenAI-compatible 服务，填写 API 地址和 Key，
选择或直接输入模型 ID，并按服务商要求选择 Chat Completions 或 Responses，保存后即可继续。

首页顶部固定显示 **模型设置 / F2** 按钮，也可以按 **F2**、输入 `/settings` 或不带参数的
`/model` 打开设置。即使后台服务启动失败，设置仍然可用。保存后自动重新连接，并保留当前会话。
“检测连接”会读取服务商的 `/models` 接口并填充模型列表；不支持该接口的服务也可手动填写。

```bash
physicsos config          # 独立打开模型、API 地址、Key 和 API 类型设置
physicsos config --show   # 查看配置状态，不显示 Key
```

Key 输入时隐藏，保存到 `~/.physicsos/config.json`（或 `PHYSICSOS_CONFIG` 指定的位置），
Unix 上仅当前用户可读写。新配置默认使用 OpenAI 官方地址，已有自定义地址保持有效。
也支持 `OPENAI_API_KEY` 和 `OPENAI_BASE_URL`。无 Key 的非交互请求会给出配置提示并退出。

脚本或单次运行仍可使用环境变量：

macOS/Linux：

```bash
export PHYSICSOS_OPENAI_API_KEY="..."
export PHYSICSOS_OPENAI_BASE_URL="https://api.example.com/v1"
export PHYSICSOS_OPENAI_MODEL="gpt-5.4"
```

PowerShell:

```powershell
$env:PHYSICSOS_OPENAI_API_KEY="..."
$env:PHYSICSOS_OPENAI_BASE_URL="https://api.example.com/v1"
$env:PHYSICSOS_OPENAI_MODEL="gpt-5.4"
```

如果你的模型服务使用 OpenAI Responses API：

```powershell
$env:PHYSICSOS_OPENAI_USE_RESPONSES_API="true"
```

也可以在启动 `physicsos` 的目录放置 `.env` 文件，填写上述 `PHYSICSOS_*` 配置。
已有环境变量优先于 `.env`，两者都优先于 `~/.physicsos/config.json`。
Agent 请求需要模型 API Key；`physicsos paths`、`physicsos --help` 不需要。

### 启动

```bash
physicsos
```

单次请求：

```bash
physicsos --non-interactive "为一维稳态热传导问题推导并验证 TAPS case"
```

如果要打开交互界面并自动提交首条请求，请使用 `--message`。

恢复会话：

```bash
physicsos --resume
```

指定模型：

```bash
physicsos --model openai:gpt-5.4
```

### 常用命令

```bash
physicsos paths
physicsos auth login
physicsos account
physicsos runner submit path/to/manifest.json
physicsos runner status JOB_ID
physicsos runner logs JOB_ID
physicsos runner artifacts JOB_ID
physicsos runner download JOB_ID ARTIFACT_ID
physicsos runner download-all JOB_ID
```

几何辅助：

```bash
physicsos geometry apply-boundary-labels geometry.json labeling_artifact.json --output confirmed.json
```

赝势辅助：

```bash
physicsos pseudopotentials config
physicsos pseudopotentials set-root "D:\path\to\vasp_paw_pbe" --library-id vasp-paw-pbe
physicsos pseudopotentials index --case-id pp-index
physicsos pseudopotentials select --case-id si-case --structure-ref cases/si/structure.json
```

### 当前状态

PhysicsOS 仍处于 alpha 阶段。它适合研究、原型、方法验证和可审计的 AI-CAE 工作流实验。它不是认证工程软件，也不会绕过人工检查。这里的核心价值不是“自动给出一个神奇答案”，而是把推导、实现、验证和假设完整摊开，让用户能看见每一步。
