pycodemath

Schreiben Sie Mathematik in wenigen Zeichen und erhalten Sie eine exakte Antwort oder eigenständigen, optimierten Python/NumPy-Code – statt ein Sprachmodell zu bitten, „im Kopf zu rechnen" oder numerische Schleifen von Hand zu schreiben.

Neu bei Begriffen wie „MCP", „symbolisch" oder „ODE"? Springen Sie zum Glossar.

Als dünne, disziplinierte Schicht über SymPy + NumPy gebaut:

1. Tokens sparen – ein kurzer Befehl rein, ein exaktes Ergebnis raus. Perfekt als Agenten-Werkzeug (MCP-Server inklusive).

2. Besserer Code als naives Python – der Generator wendet symbolische Vereinfachung + Beseitigung gemeinsamer Teilausdrücke (CSE) an, bevor er Code ausgibt (gemessen ~1,7x schneller als naive Expansion bei wiederholten Teilausdrücken).

text → [parser] → IR (expression tree) → [engine]     evaluate / simplify / solve
                                       → [generator]  IR → CSE → Python/NumPy source

Installation

pip install pycodemath            # core: sympy + numpy
pip install pycodemath[mcp]       # + MCP server for AI agents

Aus einem Klon, für die Entwicklung (editierbare Installation):

pip install -e .[dev]             # editable + pytest + mypy

Erfordert Python ≥ 3.11.

Related MCP server: SymKit

Schnellstart

Einmaliger CLI-Aufruf (skriptfähig)

Jeder Befehl unten ist ein echter Aufruf mit seiner echten Ausgabe.

$ python -m pycodemath "diff sin(x)*x dx"
x*cos(x) + sin(x)

$ python -m pycodemath "integrate 2*x dx"
x**2

$ python -m pycodemath "solve x^2 - 4 for x"
-2, 2

$ python -m pycodemath "sin(x)^2 + cos(x)^2"
1

$ python -m pycodemath "eig [[2,1],[1,2]]"
3, 1

$ python -m pycodemath "solve_nd x^2+y^2-4; x-y for x,y at 1,1"
x = 1.4142135623746899, y = 1.4142135623746899

Fehler gehen nach stderr mit Exit-Code 1, Ergebnisse nach stdout mit Exit-Code 0 – sicher für Skripte und Agenten-Werkzeuge. Auf Windows-Konsolen PYTHONUTF8=1 setzen.

REPL

python -m pycodemath        # or just: pycodemath

Tippen Sie help für die vollständige Befehlstabelle (Ableitungen, Integrale, Gleichungslösen, Matrizen, Nullstellensuche, Optimierung, die gesamte ODE-Suite und Codegenerierung).

MCP-Server (Mathematik für jeden KI-Agenten)

pip install -e .[mcp]
claude mcp add pycodemath -- python -m pycodemath.cli.mcp_server

Stellt ein Werkzeug bereit, math_eval, das dieselben Befehle wie die REPL akzeptiert – ein Agent sendet diff sin(x)*x dx und erhält x*cos(x) + sin(x) exakt, ohne mentale Arithmetik.

Als Claude-Code-Skill verwenden

Der MCP-Server oben ist der portable Weg – er passt in jeden MCP-Client. Wenn Sie speziell Claude Code verwenden, können Sie Pycodemath auch als Skill einbinden, sodass Claude von selbst auf die Engine zugreift, wann immer eine Eingabeaufforderung echte Mathematik braucht (kein MCP-Prozess, der laufen muss).

Was sich ändert: Statt „im Kopf" zu rechnen – wo ein großes Modell leise Arithmetik, ein Integral oder einen Eigenwert falsch berechnen kann – reicht Claude die Aufgabe an die Engine weiter und fügt ein exaktes SymPy/NumPy- Ergebnis ein. Ein kurzer Befehl rein, eine exakte Zeile raus: weniger Tokens, keine stillen Fehler.

Bereitstellen (einmalig):

pip install pycodemath          # or: pip install -e .   (from a clone)
mkdir -p ~/.claude/skills/pycodemath

Speichern Sie Folgendes als ~/.claude/skills/pycodemath/SKILL.md:

---
name: pycodemath
description: Compute math with the local Pycodemath engine (SymPy+NumPy) instead
  of in your head — derivatives, integrals, solving equations and systems
  (linear and nonlinear), determinants/inverses/eigenvalues, gradients/Jacobians/
  Hessians, function minima, ODEs, and optimized Python/NumPy code generation
  (CSE). Use whenever the user asks to compute or verify symbolic/numerical math,
  or to generate code from a formula.
---

# Pycodemath — local math engine

One command = one call (the package is pip-installed, so any working directory):

    python -m pycodemath "<command>"

Result goes to stdout (exit 0); errors to stderr (exit 1). Power notation: `^` or `**`.
On Windows consoles, set `PYTHONUTF8=1`.

## Commands

| Command | Example |
|---|---|
| `<expression>` — simplify | `python -m pycodemath "sin(x)^2 + cos(x)^2"` → `1` |
| `diff <expr> d<var>` — derivative | `"diff sin(x)*x dx"` → `x*cos(x) + sin(x)` |
| `integrate <expr> d<var>` — symbolic integral | `"integrate 2*x dx"` → `x**2` |
| `solve <expr> for <var>` — solve = 0 | `"solve x^2-4 for x"` → `-2, 2` |
| `code <expr>` — CSE-optimized NumPy code | `"code (sin(x)+cos(x))^2"` |
| `det / inv / transpose / eig <A>` | `"eig [[2,1],[1,2]]"` → `3, 1` |
| `solve_system <A> = <b>` — linear system | `"solve_system [[2,1],[1,3]] = [3,5]"` |
| `root <expr> for <var> at <x0>` — numeric root | `"root x^2-2 for x at 1"` |
| `min <expr> for <var> at <x0> [method newton|bfgs]` — 1D minimum | `"min (x-3)^2 for x at 0"` |
| `grad <expr> for <x,y,...>` — symbolic gradient | `"grad x^2*y for x,y"` |
| `solve_nd <f1>; <f2> for <x,y> at <x0,y0>` — nonlinear system | `"solve_nd x^2+y^2-4; x-y for x,y at 1,1"` |
| `min_nd <expr> for <x,y> at <x0,y0> [method newton|bfgs]` — N-D minimum | `"min_nd (1-x)^2+100*(y-x^2)^2 for x,y at -1.2,1 method bfgs"` |
| limits / series / sums / ODEs | `"limit sin(x)/x for x to 0"`, `"sum 1/k^2 for k from 1 to oo"` |

Type `help` in the REPL (`python -m pycodemath`) for the full command table.

## Rules

- **When to use:** the user wants a concrete math result (derivative, integral,
  equation, matrix, minimum, ODE) or optimized code from a formula. The engine is
  exact — trust its output over mental arithmetic.
- **When not to use:** trivial arithmetic or conceptual questions with no compute.
- A `error: ...` line on stderr (exit 1) usually means a typo in the command, a
  numerical method that did not converge, or no real solution — read the message,
  it is specific.

Starten Sie Claude Code neu (oder öffnen Sie eine neue Sitzung) und es wird den Skill automatisch aufrufen, wenn eine Aufgabe exakte Mathematik erfordert. Um zu bestätigen, dass er registriert wurde, führen Sie /help aus und suchen Sie in der Skill-Liste nach pycodemath.

Grenzwerte, Reihen und symbolische Summen

Über diff/integrate/solve hinaus verarbeitet die Engine Grenzwerte (einschließlich einseitiger und im Unendlichen), Taylor-/Laurent-Entwicklungen und symbolische Summation – endlich oder unendlich. Alles echte Aufrufe mit echten Ausgaben:

$ python -m pycodemath "limit (1+1/n)^n for n to oo"
E

$ python -m pycodemath "series exp(x) for x n 4"
x**3/6 + x**2/2 + x + 1

$ python -m pycodemath "sum k for k from 1 to n"
n**2/2 + n/2

$ python -m pycodemath "sum 1/k^2 for k from 1 to oo"
pi**2/6

Eine divergente Summe oder ein nicht existierender Grenzwert verweigert mit einer lesbaren Fehlermeldung, statt ein symbolisches Echo zurückzugeben.

Optimierung: Newton und BFGS, wo Gradientenabstieg stockt

min / min_nd verwenden standardmäßig einfachen Gradientenabstieg; method newton|bfgs wechselt zu Verfahren zweiter Ordnung mit Armijo-Backtracking-Liniensuche. Im Rosenbrock-Tal (Start (-1.2, 1)) verweigert der Gradientenabstieg nach 10 000 Iterationen, während BFGS in 36 konvergiert:

$ python -m pycodemath "min_nd (1-x)^2 + 100*(y-x^2)^2 for x,y at -1.2,1 method bfgs"
x = 0.999999999999454, y = 0.9999999999989762

ODE-Suite

Symbolisch (dsolve) plus eine vollständige numerische Werkzeugkiste – skalar und für Systeme, vorwärts und rückwärts in der Zeit (t1 < t0), alle weigern sich, Singularitäten still zu überspringen (eine lesbare Fehlermeldung statt Müll):

Adaptive Integration eines glatten Problems braucht 41 Schritte bei rtol 1e-8:

$ python -m pycodemath "ode_adaptive y*cos(t) for y(t) from 0 to 5 at 1 rtol 1e-8"
y(5) = 0.3833049965035854  (41 adaptive steps)

Beim steifen Klassiker y' = -1000(y - cos t) wird das explizite Paar durch Stabilität begrenzt (378 Schritte bei rtol 1e-6; mit demselben Budget liefert festes RK4 astronomisch falsche endliche Werte). Das adaptive BDF schafft es in 313 Schritten – und startet man auf der langsamen Mannigfaltigkeit, wo die Steifheit rein ist, in 58 Schritten statt 357:

$ python -m pycodemath "odestiff_adaptive -1000*(y-cos(t)) for y(t) from 0 to 1 at 0"
y(1) = 0.5411432587540607  (adaptive BDF, 313 implicit steps)

Die Systemvariante behandelt den Van-der-Pol-Oszillator mit μ=1000 über [0, 2000] in 5 332 Schritten (~1 s) – ein explizites Verfahren bräuchte ≥ 2 000 000.

Codegenerierung

code <expr> erzeugt eigenständigen, CSE-optimierten NumPy-Quellcode (echte Ausgabe):

$ python -m pycodemath "code (sin(x)+cos(x))^2 + (sin(x)+cos(x))^3"
import numpy as np


def f(x):
    """Pycodemath: f(x) — NumPy code."""
    _c0 = np.sin(x + (1/4)*np.pi)
    return 2*_c0**2*(np.sqrt(2)*_c0 + 1)

Die Python-API erzeugt auch eigenständige ODE-Integratoren – einschließlich eines adaptiven und eines mit dichter Ausgabe, dessen erzeugter Interpolant bitweise identisch mit der Engine ist (gemessene maximale Abweichung: 0.0 auf Knoten- und Off-Knoten-Gittern, vorwärts und rückwärts):

from pycodemath import parse, generate_ode_dense

art = generate_ode_dense(parse("y*cos(t)"), "t", "y")
sol = art(1.0, 0.0, 5.0, 1e-8)   # standalone DOPRI5, returns an interpolant
sol(2.5)                          # -> 1.8193369962907706
len(sol.ts)                       # -> 42 accepted nodes

Ereigniserkennung über die API:

from pycodemath import parse, solve_ode_events

ev = solve_ode_events(parse("cos(t)"), "t", 0.0, (0.0, 10.0), parse("y"), rtol=1e-8)
ev.event_times   # -> [3.141593, 6.283185, 9.424778]   (π, 2π, 3π)

Strukturierte Ergebnisse: die Belege hinter der Antwort

Jeder Solver in diesem Paket hat jetzt eine full_result=True-Form, die Belege statt einer nackten Zahl zurückgibt – ein eingefrorenes SolveResult (Wert, Iterationen, Residuum, konvergiert, Status) für root_find / root_find_nd / minimize / minimize_nd und ein QuadratureResult (ergänzt um error_estimate) für integrate_num. Standardaufrufe sind unverändert, bitweise identisch zu vorher.

>>> from pycodemath import root_find, minimize, integrate_num, parse
>>> root_find(parse("x^2 - 2"), "x", 1.0, full_result=True)
SolveResult(value=1.4142135623746899, iterations=5, residual=4.510614104447086e-12, converged=True, status='converged')

>>> minimize(parse("-x^2"), "x", 1.0, full_result=True)
SolveResult(value=1085298990978.309, iterations=152, residual=2170597981956.618, converged=False, status='diverged')

>>> integrate_num(parse("sqrt(x)"), "x", 0.0, 1.0, tol=1e-10, full_result=True)
QuadratureResult(value=0.6666666666666469, error_estimate=2.4271240969151142e-11, evaluations=1005, refinements=201, converged=True, status='converged')

converged ist das einzige Feld, auf das man verzweigen sollte, und es ist bestätigt, nicht nur „der Toleranztest hat ausgelöst": Ein verschwindender Gradient an einem Sattelpunkt oder Maximum meldet status='not_a_minimum' statt einer falschen Konvergenz.

Der MCP-Server überträgt dieselbe Struktur über das Kabel als structuredContent (text / solve / quadrature / error-Felder), nicht nur als Prosa – ein Client validiert sie gegen das deklarierte Schema, statt Text zu parsen.

Nachgestellte Optionen bringen dieselben Stellschrauben in die REPL-/Einmal-Grammatik:

$ python -m pycodemath "min x^4 for x at 1 tol 1e-5"
0.029229144526165384

$ python -m pycodemath "nintegrate sqrt(x) dx from 0 to 1 tol 1e-10"
0.6666666666666469

tol <t> (bei min / min_nd / nintegrate), max_iter <k> (bei min / min_nd) und budget <s> (bei den symbolischen Befehlen, die einen Aufruf genauso begrenzen wie pycodemath.time_budget(seconds) in Python) sind key value-Paare am Ende eines Befehls, in beliebiger Reihenfolge.

Ein symbolischer Aufruf, der verweigert, sagt, welcher von zwei Fällen eingetreten ist: NoClosedFormError (die Engine hat gesucht und nichts gefunden – versuchen Sie es numerisch) oder UnsupportedFormError (es existiert keine Methode für diese Form).

Designverträge

• Eine IR (Expr/Matrix), geteilt von Engine und Generator.

• Numerische Schleifen laufen auf kompilierten Funktionen (lambdify + LRU-Cache) – null SymPy-Aufrufe pro Iteration.

• Divergenz oder ein Definitionsbereichsproblem wirft einen lesbaren PycodemathError – niemals NaN/Müll in einem Ergebnis.

• Der Parser löst nur eine Whitelist mathematischer Funktionen auf – unbekannte Namen werden zu Symbolen, nicht zu Python-Code; String-Literale und Attributzugriffe werden rundweg abgelehnt, und die Auswertungskosten sind begrenzt, sodass ein einzelner Ausdruck (z. B. 9**9**9) den Speicher nicht erschöpfen kann.

• Tests messen zuerst reale Zahlen und bestätigen sie dann mit einer Toleranz – 668 Tests, alle grün, auf Ubuntu und Windows (CI + mypy inklusive).

• Jeder Fehler ist eine spezifische PycodemathError-Unterklasse (ParseError, DomainError, DivergenceError, StagnationError, NonConvergenceError, NoClosedFormError, UnsupportedFormError, TimeBudgetError) – ein Aufrufer kann das mathematische Ergebnis abfangen, statt eine Nachricht per String-Vergleich zu prüfen.

• time_budget ist Best-Effort, keine harte Garantie. Es unterbricht einen Hänger, indem es eine Ausnahme in den laufenden Thread injiziert, über CPythons eigenes ctypes.PyThreadState_SetAsyncExc – der einzige Mechanismus, der plattformübergreifend ohne Subprozess pro Aufruf verfügbar ist (kein SIGALRM unter Windows, und selbst unter POSIX feuert es nur auf dem Hauptthread eines Prozesses). Unter starker oder virtualisierter Planung kann die Zustellung dieser Injektion gelegentlich vom Interpreter verpasst werden, in welchem Fall der Aufruf über sein Budget hinaus weiterläuft, statt rechtzeitig TimeBudgetError zu werfen – direkt auf einer solchen Umgebung gemessen (Python 3.13, WSL2). Dies betrifft nicht den schnellen Pfad – die überwältigende Mehrheit der Aufrufe, die in Millisekunden fertig sind und nie ein Budget erreichen – und es erzeugt keine falsche Antwort; die einzige Fehlerart ist „hat nicht so schnell abgelehnt wie gebeten." Eine harte Garantie braucht eine Subprozess-basierte Absicherung, die auf der Roadmap steht, aber noch nicht gebaut ist.

Glossar

Verständliche Definitionen für das oben verwendete Fachvokabular – für alle, die dieses Repository lesen und keine Programmierer sind.

Lizenz

MIT — siehe LICENSE.