PhysicsOS

AI-native CAE workspace for paper-style TAPS simulation workflows.
From a physics problem to derivation, case-local code, verification evidence, and cloud-ready artifacts.

English · 中文

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

Architecture In One Screen

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:

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:

python -m pip install .
physicsos --version
physicsos

For development utilities and installation regression tests:

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

macOS/Linux:

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

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:

$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.

{
  "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

physicsos

Run a single request:

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:

physicsos --resume

Use a specific model through DeepAgents:

physicsos --model openai:gpt-5.4

Local CLI

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:

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

Pseudopotential helpers:

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

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.

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:

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.

中文

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。

一屏理解架构

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

安装

从 PyPI 安装：

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。

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

python -m pip install .
physicsos --version
physicsos

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

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 账号

配置模型

macOS/Linux：

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

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：

$env:PHYSICSOS_OPENAI_USE_RESPONSES_API="true"

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

启动

physicsos

单次请求：

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

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

恢复会话：

physicsos --resume

指定模型：

physicsos --model openai:gpt-5.4

常用命令

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

几何辅助：

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

赝势辅助：

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 工作流实验。它不是认证工程软件，也不会绕过人工检查。这里的核心价值不是“自动给出一个神奇答案”，而是把推导、实现、验证和假设完整摊开，让用户能看见每一步。