dsh-complex

dsh-complex ➗➕

Complex-number math toolbox for DeepSeek Harness (dsh). Seven pure-math tools that do complex arithmetic correctly on the principal branch, so the agent never has to hand-track i² = -1 bookkeeping, Euler formulas, polar conversions, branch cuts, or polynomial roots.

中文简介：dsh-complex 是 DeepSeek Harness 的复数数学工具箱插件，提供 7 个纯计算工具（复数解析、四则运算与任意复幂、极坐标↔直角坐标互转、初等与反函数主值、n 次方根全集、复系数二次方程求解、多项式求值与全部根），零运行时依赖、纯本地算术。适合让 Agent 直接完成「复数乘除、极坐标转换、欧拉公式、n 次方根、反三角/反双曲主值、分支切割、复系数二次方程」等手算极易出错的计算。

Why

LLMs reliably botch complex arithmetic: (3+4i)(1-2i), exp(iπ), log(-1), √-4, i^i, asin(2), the four fourth roots of 1, the roots of z² + iz + 1 = 0. This plugin computes them exactly (IEEE double, output rounded to 10 decimals by default) with deterministic closed-form formulas, anchored by the Python stdlib cmath reference implementation in tests.

Tools

Every value is deterministic: computations keep raw IEEE doubles and round/snap floating-point dust only at the output boundary (10 decimal places by default, configurable via plugins.complex.roundPlaces).

Install

dsh plugin --profile web add github:TYEclipse/dsh-complex

Pin a specific version:

dsh plugin --profile web add github:TYEclipse/dsh-complex#v0.2.0

Or install through the DSH web GUI plugin browser / any dsh plugin marketplace by searching dsh-complex (topic dsh-plugin).

Requires Node ≥ 20. Zero runtime dependencies.

Usage

Parse and convert

complex_parse("3+4i")
→ 3+4i  (rectangular; |z| = 5, arg = 53.1301023542°, conjugate 3-4i)

complex_convert(input="3+4i", operation="to_polar")
→ |z| = 5, arg = 0.927295218 rad = 53.1301023542°  (5∠53.1301023542°; exponential 5·e^(i·0.927295218))

complex_convert(input="2∠270°", operation="to_rect")
→ -2i

Arithmetic and complex powers

complex_calc(a="3+4i", b="1-2i", operation="multiply")   → 11-2i
complex_calc(a="3+4i", b="1-2i", operation="divide")     → -1+2i
complex_calc(a="1+i", exponent=8, operation="power")     → 16
complex_calc(a="i", b="i", operation="pow")              → 0.2078795764   (i^i = e^(-π/2))
complex_calc(a="2", b="1+i", operation="pow")            → 1.5384778027+1.2779225526i
complex_calc(a="-1", b="0.5", operation="pow")           → i              (principal branch)

Principal values, inverses and roots

complex_functions(input="3.141592653589793i", operation="exp")  → -1        (Euler identity)
complex_functions(input="-1", operation="log")                  → 3.1415926536i  (iπ, principal branch)
complex_functions(input="-4", operation="sqrt")                 → 2i
complex_functions(input="1+i", operation="asin")                → 0.6662394325+1.0612750619i
complex_functions(input="2", operation="asin")                  → 1.5707963268+1.3169578969i  (on the real cut)
complex_functions(input="2i", operation="atan")                 → 1.5707963268+0.5493061443i
complex_functions(input="2", operation="atanh")                 → 0.5493061443+1.5707963268i

complex_roots(input="1", n=4)   → 1, i, -1, -i
complex_roots(input="-8", n=3)  → 1+1.7320508076i, -2, 1-1.7320508076i

Quadratic equations with complex coefficients

complex_quadratic(a="1", b="-2", c="2")
→ discriminant -4, sum 2, product 2; roots 1+1i, 1-1i

complex_quadratic(a="1", b="i", c="1")
→ discriminant -5, sum -i, product 1; roots 0.6180339887i, -1.6180339887i   (golden-ratio pair)

complex_quadratic(a="0", b="2", c="-4")
→ degree 1 (linear): root 2

Polynomials and their roots

complex_poly(coefficients=["1","0","-1"], operation="evaluate", z="1+i")
→ p(1+1i) = -1+2i, p'(1+1i) = 2+2i

complex_poly(coefficients=["1","0","0","-1"], operation="roots")
→ 3 roots: 1, -0.5+0.8660254038i, -0.5-0.8660254038i   (converged, max residual 0)

complex_poly(coefficients=["1","-2","1"], operation="roots")
→ 1 root: 1  (×2)   — (z − 1)², multiplicity 2, not two near-identical numbers

complex_poly(coefficients=["1","-1","1","-4"], operation="roots")
→ 1, i, -i, -1                                    (z⁴ − 1)

Conventions

• Input grammar: a+bi (or a-bi, bi, a, bare i; j also accepted; whitespace around the operator and the suffix is tolerated; scientific notation works; the imaginary coefficient may be omitted — 1+i is 1+1i).
• Polar input: r∠θ° with θ in degrees (the ° or deg suffix is optional; negative angles accepted; r must be ≥ 0).
• Principal branch: arg ∈ (-π, π]; every function reports its branch convention in the result note.
• Inverse functions follow CPython's cmath (C99) exactly, including on the branch cuts, where the naive principal-square-root identity would silently return the conjugate value: asin(x) = sign(x)·π/2 + i·acosh|x| for real |x| > 1, atan(iy) = π/2 + i·sign(y)·atanh(1/|y|) for |y| > 1, asinh(iy) = acosh|y| + i·sign(y)·π/2, atanh(x) = atanh(1/x) + iπ/2, and acos = π/2 − asin.
• log(0), division by zero, 0^0, and the genuinely undefined atan(±i) / atanh(±1) return an honest valid: false with an explanation instead of guessing.

Configuration

plugins:
  complex:
    roundPlaces: 10   # decimal places for every output number (1–15)

Development

pnpm install
pnpm build
pnpm test
pnpm lint

181 tests, all anchored by an independent Python cmath oracle (test/oracle/anchors.py — the reference implementation, which prints every anchor over a grid that includes all four branch cuts), plus schema-level enum rejection and recursive no-undefined (lossless-JSON) assertions on every tool result.

License

MIT