pycodemath

Записывайте математику в несколько символов и получайте точный ответ или самостоятельный оптимизированный код на Python/NumPy — вместо того чтобы просить языковую модель «считать в уме» или вручную писать численные циклы.

Впервые встречаете такие термины, как «MCP», «символьный» или «ОДУ»? Перейдите к Глоссарию.

Создан как тонкий, дисциплинированный слой поверх SymPy + NumPy:

1. Экономия токенов — одна короткая команда на входе, один точный результат на выходе. Идеально подходит как инструмент для агентов (MCP-сервер включён).

2. Код лучше наивного Python — генератор применяет символьное упрощение и устранение общих подвыражений (CSE) перед генерацией кода (измерено: ~в 1.7 раза быстрее наивного раскрытия на повторяющихся подвыражениях).

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

Установка

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

Из клона, для разработки (редактируемая установка):

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

Требуется Python ≥ 3.11.

Related MCP server: SymKit

Быстрый старт

Однокомандный CLI (для скриптов)

Каждая команда ниже — реальный вызов с реальным выводом.

$ 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

Ошибки идут в stderr с кодом выхода 1, результаты — в stdout с кодом выхода 0 — безопасно вызывать из скриптов и инструментов агентов. На консолях Windows установите PYTHONUTF8=1.

REPL

python -m pycodemath        # or just: pycodemath

Введите help для полной таблицы команд (производные, интегралы, решение уравнений, матрицы, поиск корней, оптимизация, весь набор ОДУ и генерация кода).

MCP-сервер (математика для любого ИИ-агента)

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

Предоставляет один инструмент, math_eval, который принимает те же команды, что и REPL — агент отправляет diff sin(x)*x dx и получает x*cos(x) + sin(x) точно, без каких-либо вычислений в уме.

Использование как навык Claude Code

MCP-сервер выше — это переносимый путь: он подключается к любому MCP-клиенту. Если вы используете именно Claude Code, вы также можете подключить Pycodemath как навык, чтобы Claude сам обращался к движку всякий раз, когда задаче нужна настоящая математика (без необходимости держать MCP-процесс запущенным).

Что это меняет: вместо вычислений «в уме» — где большая модель может незаметно ошибиться в арифметике, интеграле или собственном значении — Claude обращается к движку и вставляет обратно точный результат SymPy/NumPy. Одна короткая команда на входе, одна точная строка на выходе: меньше токенов, никаких тихих ошибок.

Развёртывание (один раз):

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

Сохраните следующее как ~/.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.

Перезапустите Claude Code (или откройте новую сессию), и он будет автоматически вызывать навык, когда задаче нужна точная математика. Чтобы убедиться, что он зарегистрирован, выполните /help и найдите pycodemath в списке навыков.

Пределы, ряды и символьные суммы

Помимо diff/integrate/solve, движок обрабатывает пределы (включая односторонние и на бесконечности), разложения Тейлора/Лорана и символьное суммирование — конечное или бесконечное. Все реальные вызовы с реальными результатами:

$ 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

Расходящаяся сумма или несуществующий предел отклоняются с понятной ошибкой вместо возврата символьного эха.

Оптимизация: Ньютон и BFGS там, где градиентный спуск буксует

min / min_nd по умолчанию используют обычный градиентный спуск; method newton|bfgs переключает на методы второго порядка с поиском шага с возвратом по Армихо. На овраге Розенброка (старт (-1.2, 1)) градиентный спуск отказывается работать после 10 000 итераций, а BFGS сходится за 36:

$ 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

Набор ОДУ

Символьный (dsolve) плюс полный численный инструментарий — скалярные уравнения и системы, вперёд и назад по времени (t1 < t0), все отказываются молча перепрыгивать через особенности (понятная ошибка вместо мусора):

Адаптивное интегрирование гладкой задачи занимает 41 шаг при 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)

На жёсткой классической задаче y' = -1000(y - cos t) явная пара ограничена устойчивостью (378 шагов при rtol 1e-6; при том же бюджете фиксированный шаг RK4 возвращает астрономически неверные конечные значения). Адаптивный BDF добирается за 313 шагов — а при старте на медленном многообразии, где жёсткость чистая, за 58 шагов против 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)

Системный вариант обрабатывает осциллятор Ван дер Поля с μ=1000 на [0, 2000] за 5 332 шага (~1 с) — явному методу потребовалось бы ≥ 2 000 000.

Генерация кода

code <expr> генерирует самостоятельный исходный код NumPy с оптимизацией CSE (реальный вывод):

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

Python API также генерирует самостоятельные интеграторы ОДУ — включая адаптивный и с плотным выводом, чей сгенерированный интерполянт побитово идентичен движку (измеренная максимальная разница: 0.0 на узлах и вне узлов, вперёд и назад):

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

Обнаружение событий из 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π)

Структурированные результаты: доказательства за ответом

Каждый решатель в этом пакете теперь имеет форму full_result=True, которая возвращает доказательства вместо голого числа — замороженный SolveResult (значение, итерации, невязка, сходимость, статус) для root_find / root_find_nd / minimize / minimize_nd и QuadratureResult (добавляет error_estimate) для integrate_num. Вызовы по умолчанию не изменились, побитово идентичны прежним.

>>> 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 — единственное поле, по которому стоит ветвиться, и оно подтверждено, а не просто «сработал тест допуска»: исчезающий градиент в седловой точке или максимуме сообщает status='not_a_minimum' вместо ложной сходимости.

MCP-сервер передаёт ту же структуру по сети как structuredContent (поля text / solve / quadrature / error), а не просто прозу — клиент проверяет её по объявленной схеме вместо разбора текста.

Хвостовые опции выносят те же ручки в грамматику REPL/однокомандного режима:

$ 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> (для min / min_nd / nintegrate), max_iter <k> (для min / min_nd) и budget <s> (для символьных команд, ограничивающий вызов так же, как pycodemath.time_budget(seconds) в Python) — это пары ключ значение в конце команды, в любом порядке.

Символьный вызов, который отказывается, сообщает, что именно произошло: NoClosedFormError (движок искал и ничего не нашёл — попробуйте численно) или UnsupportedFormError (для такой формы вообще не существует метода).

Контракты проектирования

• Одно промежуточное представление (Expr/Matrix), общее для движка и генератора.

• Численные циклы выполняются на скомпилированных функциях (lambdify + LRU-кэш) — ноль вызовов SymPy на итерацию.

• Расходимость или проблема с областью определения вызывает понятную PycodemathError — никогда NaN/мусор в результате.

• Парсер разрешает только белый список математических функций — неизвестные имена становятся символами, а не кодом Python; строковые литералы и доступ к атрибутам отклоняются outright, а стоимость вычисления ограничена, чтобы одно выражение (например, 9**9**9) не могло исчерпать память.

• Тесты сначала измеряют реальные числа, затем проверяют их с запасом — 668 тестов, все зелёные, на Ubuntu и Windows (CI + mypy включены).

• Каждый сбой — это конкретный подкласс PycodemathError (ParseError, DomainError, DivergenceError, StagnationError, NonConvergenceError, NoClosedFormError, UnsupportedFormError, TimeBudgetError) — вызывающий код может перехватить математический исход, а не сопоставлять строку сообщения.

• time_budget — это best-effort, а не жёсткая гарантия. Он прерывает зависание, внедряя исключение в работающий поток через собственный ctypes.PyThreadState_SetAsyncExc из CPython — единственный доступный механизм на всех платформах без отдельного подпроцесса на вызов (нет SIGALRM в Windows, и даже в POSIX он срабатывает только на главном потоке процесса). При интенсивном или виртуализированном планировании доставка этого внедрения иногда может быть пропущена интерпретатором, и в этом случае вызов продолжает работать сверх бюджета вместо того, чтобы вовремя поднять TimeBudgetError — измерено непосредственно в такой среде (Python 3.13, WSL2). Это не влияет на быстрый путь — подавляющее большинство вызовов, которые завершаются за миллисекунды и никогда не приближаются к бюджету — и не даёт неверного ответа; единственный режим отказа — «не отказался так быстро, как просили». Жёсткая гарантия требует подстраховки на основе подпроцесса, которая в планах, но ещё не реализована.

Глоссарий

Определения простым языком для жаргона, использованного выше — для тех, кто читает этот репозиторий и не является программистом.

Лицензия

MIT — см. LICENSE.