dsh-sci

Readme

# dsh-sci 🔬

> Zero-dependency scientific computing tools for DeepSeek Harness: physical-unit conversion, CODATA physical constants, and Runge–Kutta ODE/dynamical-system simulation. No core changes.

[English](./README.md) | [简体中文](./README.zh.md)

A **DeepSeek Harness (DSH)** pure tool plugin registering three model tools that scientists reach for daily — all implemented as **zero-dependency pure functions**: no network, no external software, fully unit-tested.

| Tool | Purpose | Example |
|---|---|---|
| `units_convert` | Physical unit conversion (length/mass/time/temperature/energy/pressure/frequency/force/angle/volume/area/electric, 70+ units) | `1 eV → J`, `0 ℃ → K`, `1 kWh → J` |
| `physical_constants` | Look up CODATA physical constants (c, h, e, k, G, N_A, …) | `physical_constants("h")` |
| `ode_solve` | 4th-order Runge–Kutta integration of common dynamical systems (the **simulation engine**) | exponential / logistic / harmonic / damped / pendulum / predator-prey / SIR / Lorenz / Van der Pol |

## ✨ Features

- **Zero dependencies**: unit conversion, physical constants, and the RK4 integrator are hand-written pure functions — no runtime `node_modules`, no network.
- **Safe simulation**: `ode_solve` uses a curated **model library** (9 dynamical systems) with parameters, not arbitrary code execution — safe for the model to call.
- **Verified accuracy**: the RK4 integrator is checked against analytic solutions (`e^-t`, `cos t`) in unit tests.
- **Zero core changes**: pure `ctx.tools.register`, no client bundle.

## 📦 Install

Prereqs: DSH (`dsh web` works), Node ≥ 22.19, pnpm.

```bash
# From GitHub (prebuilt lib/ committed)
dsh plugin --profile web add "github:Blaczz/dsh-sci#main"

# Local directory
cd dsh-sci && npm install --legacy-peer-deps && npm run build
dsh plugin --profile web add ./dsh-sci
```

**Restart `dsh web` after install**, then ask the agent: "convert 5 eV to joules", "look up the Planck constant", or "simulate a damped oscillator with ω=2, ζ=0.1 out to t=20".

## 🔬 Usage

```
User: simulate the Lotka-Volterra predator-prey model, alpha=1, beta=0.1, gamma=1, delta=0.02, to t=50
agent → ode_solve(model="lotka-volterra", params={...}, tEnd=50)
       → returns the time series + final state [prey, predator]

User: how many joules is 1 electron-volt?
agent → units_convert(value=1, from="eV", to="J") → 1.602176634e-19

User: list all physical constants
agent → physical_constants() → c, h, e, k, G, N_A, … all
```

## 🛠️ Development

```bash
npm install --legacy-peer-deps
$env:DSH_NODE_MODULES = "$env:USERPROFILE\.dsh\profiles\node_modules"
npm run setup:dsh-workspace
npm run verify                          # ★ one-shot gate: clean + typecheck + test + build
npm test                                # vitest (24 tests: units / constants / ODE accuracy + manifest)
```

## Layout

```
dsh-sci/
├── package.json            # dsh.bundle.patch (pure tool plugin)
├── cordis.patch.yml        # bundle patch layer
├── scripts/                # build (tsc only) / clean / setup-dsh-workspace / verify
├── src/
│   ├── units.ts            # ★ unit conversion (70+ units, dimension + factor + offset)
│   ├── constants.ts        # ★ CODATA 2018 physical constants
│   ├── ode.ts              # ★ RK4 integrator + 9-model dynamical-system library
│   └── index.ts            # host half: registers the 3 tools
└── tests/                  # units / constants / ode / manifest
```

## 🧩 Ecosystem positioning

- **Fills a gap**: the DSH ecosystem previously had **zero** `physics` / `ode` / `numerical` / `fft` plugins, and the `units` hits were all "unit-test / unit-economics" false positives — no physical unit conversion. The existing `dsh-science` projects are reproducible Python/R workbenches (not numerical tools), and `dsh-robotic-harness` is MuJoCo robotics (a heavy dependency).
- **Technical route**: follows the zero-dependency pure-tool pattern of `omdsh-dev/dsh-tool-*`, with pure functions under test.
- **Zero core changes**: pure `ctx.tools.register`, no external software, no network.

## ⚖️ License

MIT © 2026 Blaczz. An independent community plugin, not affiliated with [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).