pycodemath

Escribe matemáticas en pocos caracteres y obtén una respuesta exacta o código Python/NumPy independiente y optimizado, en lugar de pedirle a un modelo de lenguaje que «haga aritmética mental» o que escriba bucles numéricos a mano.

¿Nuevo con términos como «MCP», «simbólico» u «ODE»? Salta al Glosario.

Construido como una capa fina y disciplinada sobre SymPy + NumPy:

1. Reduce tokens — un comando corto, un resultado exacto. Perfecto como herramienta de agente (servidor MCP incluido).

2. Mejor código que Python ingenuo — el generador aplica simplificación simbólica + eliminación de subexpresiones comunes (CSE) antes de emitir código (medido ~1.7x más rápido que la expansión ingenua en subexpresiones repetidas).

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

Instalación

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

Desde un clon, para desarrollo (instalación editable):

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

Requiere Python ≥ 3.11.

Related MCP server: SymKit

Inicio rápido

CLI de un solo uso (scriptable)

Cada comando a continuación es una invocación real con su salida real.

$ 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

Los errores van a stderr con código de salida 1, los resultados a stdout con código de salida 0 — seguro para llamar desde scripts y herramientas de agente. En consolas de Windows, establece PYTHONUTF8=1.

REPL

python -m pycodemath        # or just: pycodemath

Escribe help para la tabla completa de comandos (derivadas, integrales, resolución de ecuaciones, matrices, búsqueda de raíces, optimización, toda la suite de EDO y generación de código).

Servidor MCP (matemáticas para cualquier agente de IA)

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

Expone una herramienta, math_eval, que acepta los mismos comandos que el REPL — un agente envía diff sin(x)*x dx y recibe x*cos(x) + sin(x) exactamente, sin aritmética mental.

Úsalo como una habilidad de Claude Code

El servidor MCP anterior es la vía portátil: se conecta a cualquier cliente MCP. Si usas específicamente Claude Code, también puedes integrar Pycodemath como una habilidad, para que Claude recurra al motor por sí solo siempre que un prompt necesite matemáticas reales (sin necesidad de mantener un proceso MCP en ejecución).

Qué cambia: en lugar de calcular «de cabeza» — donde un modelo grande puede equivocarse silenciosamente en aritmética, una integral o un valor propio — Claude recurre al motor y pega un resultado exacto de SymPy/NumPy. Un comando corto, una línea exacta: menos tokens, sin errores silenciosos.

Despliegue (una vez):

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

Guarda lo siguiente como ~/.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.

Reinicia Claude Code (o abre una nueva sesión) y invocará la habilidad automáticamente cuando una tarea necesite matemáticas exactas. Para confirmar que se registró, ejecuta /help y busca pycodemath en la lista de habilidades.

Límites, series y sumas simbólicas

Más allá de diff/integrate/solve, el motor maneja límites (incluyendo unilaterales y en el infinito), expansiones de Taylor/Laurent y sumas simbólicas — finitas o infinitas. Todas las invocaciones reales con salidas reales:

$ 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

Una suma divergente o un límite inexistente se rechaza con un error legible en lugar de devolver un eco simbólico.

Optimización: Newton y BFGS donde el descenso de gradiente se estanca

min / min_nd usan por defecto descenso de gradiente simple; method newton|bfgs cambia a métodos de segundo orden con búsqueda de línea de retroceso de Armijo. En el valle de Rosenbrock (inicio (-1.2, 1)) el descenso de gradiente se niega después de 10 000 iteraciones, mientras que BFGS converge en 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

Suite de EDO

Simbólico (dsolve) más un toolbox numérico completo — escalar y sistemas, hacia adelante y hacia atrás en el tiempo (t1 < t0), todos se niegan a saltar silenciosamente sobre singularidades (un error legible en lugar de basura):

La integración adaptativa de un problema suave toma 41 pasos con 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)

En el clásico rígido y' = -1000(y - cos t) el par explícito está limitado por la estabilidad (378 pasos con rtol 1e-6; con el mismo presupuesto, RK4 de paso fijo devuelve valores finitos astronómicamente incorrectos). El BDF adaptativo llega en 313 pasos — y comenzando en la variedad lenta, donde la rigidez es pura, en 58 pasos frente a 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)

La variante de sistema maneja el oscilador de Van der Pol con μ=1000 en [0, 2000] en 5 332 pasos (~1 s) — un método explícito necesitaría ≥ 2 000 000.

Generación de código

code <expr> emite código fuente NumPy independiente y optimizado con CSE (salida real):

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

La API de Python también genera integradores de EDO independientes — incluyendo uno adaptativo y uno con salida densa cuyo interpolante emitido es idéntico bit a bit al del motor (diferencia máxima medida: 0.0 en nodos y en rejillas fuera de nodos, hacia adelante y hacia atrás):

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

Detección de eventos desde la 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π)

Resultados estructurados: la evidencia detrás de la respuesta

Cada solucionador de este paquete ahora tiene una forma full_result=True que devuelve evidencia en lugar de un número desnudo — un SolveResult congelado (valor, iteraciones, residual, convergido, estado) para root_find / root_find_nd / minimize / minimize_nd, y un QuadratureResult (añade error_estimate) para integrate_num. Las llamadas por defecto no cambian, idénticas bit a bit a las anteriores.

>>> 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 es el único campo en el que vale la pena ramificar, y está corroborado, no solo «la prueba de tolerancia se disparó»: un gradiente que se desvanece en un punto de silla o un máximo reporta status='not_a_minimum' en lugar de una convergencia falsa.

El servidor MCP lleva la misma estructura por el cable como structuredContent (campos text / solve / quadrature / error), no solo prosa — un cliente lo valida contra el esquema declarado en lugar de analizar texto.

Opciones finales ponen esos mismos controles en la gramática del REPL/de un solo uso:

$ 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> (en min / min_nd / nintegrate), max_iter <k> (en min / min_nd) y budget <s> (en los comandos simbólicos, limitando una llamada de la misma manera que pycodemath.time_budget(seconds) en Python) son pares clave valor al final de un comando, en cualquier orden.

Una llamada simbólica que se niega dice cuál de dos cosas sucedió: NoClosedFormError (el motor buscó y no encontró nada — prueba numéricamente) o UnsupportedFormError (no existe ningún método para esta forma en absoluto).

Contratos de diseño

• Un IR (Expr/Matrix) compartido por el motor y el generador.

• Los bucles numéricos se ejecutan en funciones compiladas (lambdify + caché LRU) — cero llamadas a SymPy por iteración.

• La divergencia o un problema de dominio lanza un PycodemathError legible — nunca NaN/basura en un resultado.

• El analizador resuelve solo una lista blanca de funciones matemáticas — los nombres desconocidos se convierten en símbolos, no en código Python; las cadenas literales y el acceso a atributos se rechazan de plano, y el costo de evaluación está limitado para que una sola expresión (por ejemplo, 9**9**9) no pueda agotar la memoria.

• Las pruebas miden números reales primero, luego los afirman con un margen — 668 pruebas, todas en verde, en Ubuntu y Windows (CI + mypy incluidos).

• Cada fallo es una subclase específica de PycodemathError (ParseError, DomainError, DivergenceError, StagnationError, NonConvergenceError, NoClosedFormError, UnsupportedFormError, TimeBudgetError) — un llamador puede capturar el resultado matemático, no hacer coincidir una cadena de mensaje.

• time_budget es de mejor esfuerzo, no una garantía dura. Interrumpe un cuelgue inyectando una excepción en el hilo en ejecución a través del propio ctypes.PyThreadState_SetAsyncExc de CPython — el único mecanismo disponible entre plataformas sin un subproceso por llamada (no hay SIGALRM en Windows, y solo se dispara en el hilo principal de un proceso incluso en POSIX). Bajo programación pesada o virtualizada, la entrega de esa inyección puede ser ocasionalmente omitida por el intérprete, en cuyo caso la llamada continúa ejecutándose más allá de su presupuesto en lugar de lanzar TimeBudgetError a tiempo — medido directamente en uno de esos entornos (Python 3.13, WSL2). Esto no afecta la ruta rápida — la gran mayoría de las llamadas, que terminan en milisegundos y nunca se acercan a un presupuesto — y no produce una respuesta incorrecta; el único modo de fallo es «no se negó tan pronto como se pidió». Una garantía dura necesita un respaldo basado en subprocesos, que está en la hoja de ruta pero aún no está construido.

Glosario

Definiciones en lenguaje sencillo para la jerga utilizada anteriormente — para cualquiera que lea este repositorio y no sea programador.

Licencia

MIT — consulta LICENSE.