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

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.

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:

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

配置模型

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

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

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：

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