Metadata-Version: 2.4
Name: analisis_numerico
Version: 1.1.1
Summary: Libreria de Python para analisis numerico
Author: Alejo012G
License: MIT
Keywords: numerical analysis,python,math
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"

<!-- Production documentation: concise, navigable, badges at top -->
# analisis_numerico — Documentación

[![Python Versions](https://img.shields.io/pypi/pyversions/analisis-numerico)](https://pypi.org/project/analisis-numerico/)

`analisis_numerico` es una librería enfocada en interpolación e integración numérica. Proporciona implementaciones claras de Newton, Lagrange, la regla del trapecio y la regla de Simpson 1/3, con una API pensada para lectura, evaluación y formateo de resultados.

## Contenido

- 1. Introducción
- 2. Instalación
- 3. Quick Start
- 4. Conceptos principales
- 5. API Reference
- 6. Integración numérica
- 7. Notas avanzadas
- 8. FAQ

---

## 1. Introducción

### Qué es
Librería para construir, evaluar y presentar polinomios interpoladores mediante Newton y Lagrange, además de aproximar integrales definidas con reglas clásicas de cuadratura.

### Qué problema resuelve
Simplifica el trabajo con interpolación numérica al ofrecer:
- validación automática de nodos;
- ordenamiento interno de `x_k`;
- generación de parciales `p_0..p_n`;
- formateo en forma numérica o expandida;
- aproximación de integrales por trapecio o Simpson.

### Principales ventajas
- API coherente y fácil de memorizar.
- Salidas legibles para depuración y documentación.
- Sin dependencias externas obligatorias.
- Clases de integración disponibles en `analisis_numerico.core`.

### Casos de uso
- Docencia en análisis numérico.
- Validación de datos experimentales.
- Generación de interpoladores para scripts y notebooks.
- Aproximación rápida de integrales con reglas compuestas.

### Ejemplo rápido
```python
from analisis_numerico import Newton

n = Newton(function=lambda x: x**2, table=[1.0, 2.0, 2.5])
print(n.formatear(position=2, operar=False))
```

---

## 2. Instalación

### Requisitos
- Python 3.8 o superior.

### Instalación básica
```bash
pip install analisis_numerico
```

### Instalación para desarrollo
```bash
python -m venv .venv
# macOS / Linux
source .venv/bin/activate
# Windows PowerShell
.venv\Scripts\Activate.ps1
pip install -e .[dev]
```

### Dependencias
- No requiere dependencias en tiempo de ejecución.

### Versiones compatibles
- Python 3.8+.

---

## 3. Quick Start

### Ejemplo mínimo funcional
```python
from analisis_numerico import Newton, Lagrange

# tabla como lista de x_k
n = Newton(function=lambda x: x**3, table=[0.0, 1.0, 2.0])
print(n.formatear(position=2, operar=False))

# tabla como pares (x_k, y_k)
l = Lagrange(function=lambda x: x**2, table=[(0.0, 0.0), (1.0, 1.0), (2.0, 8.0)])
print(l.formatear(position=2, operar=True))
```

### Explicación paso a paso
1. Crear una instancia con `function` y `table`.
2. Usar `interpolador(position)` para obtener una función parcial.
3. Usar `evaluar(i, x)` para evaluar una parcial específica.
4. Usar `formatear(...)` para inspección numérica o expansión algebraica.

### Resultado esperado
- `operar=False` devuelve la forma numérica del polinomio.
- `operar=True` devuelve el polinomio expandido en base de potencias.

---

## 4. Conceptos principales

### Componentes principales
- `Interpolacion`: validación y normalización de entrada.
- `Newton`: diferencias divididas y polinomios parciales acumulativos.
- `Lagrange`: suma de términos de Lagrange sobre subconjuntos de nodos.
- `Trapecio`: aproximación por regla compuesta del trapecio.
- `Simpson`: aproximación por regla compuesta de Simpson 1/3.

### Flujo de trabajo
1. La tabla se valida y se transforma a nodos `(x_k, y_k)`.
2. Los nodos se ordenan por `x_k` de menor a mayor.
3. Se construyen parciales o se configura la cuadratura.
4. El usuario evalúa, integra o formatea según la necesidad.

### Objetos importantes
- `p_i(x)`: parcial i-ésimo del interpolador.
- `tabla`: tabla ASCII con nodos y valores evaluados.
- `integrar()` y `integrar_tabla()`: puntos de entrada de integración.

### Ciclo de vida
1. Instanciación.
2. Validación de entradas.
3. Construcción interna.
4. Uso de resultados: evaluación, formateo o integración.

### Patrones usados
- Separación entre validación y cálculo numérico.
- Representación interna por coeficientes para expansión algebraica.
- API predecible con nombres consistentes en todas las clases.

---

## 5. API Reference

### Interpolacion(function, table)

Clase base para interpolación. Encapsula validación, normalización y utilidades compartidas.

#### Parámetros
| Nombre | Tipo | Descripción |
|---|---|---|
| function | Callable[[float], float] | Función usada para calcular `y_k` cuando `table` solo contiene `x_k`. |
| table | Iterable[float] \| Iterable[tuple] | Secuencia de `x_k` o pares `(x_k, y_k)`. No incluir índices `k`. |

#### Retorna
Instancia normalizada con nodos ordenados por `x_k`.

#### Excepciones posibles
- `TypeError` si `function` no es callable o la tabla contiene datos no numéricos.
- `ValueError` si la tabla está vacía o contiene `x_k` repetidos.

#### Notas importantes
- Si la tabla contiene solo `x_k`, la librería calcula `y_k = function(x_k)`.
- La normalización reindexa internamente los nodos.

---

### Newton(function, table)

Interpolación por diferencias divididas.

#### Parámetros
| Nombre | Tipo | Descripción |
|---|---|---|
| function | Callable[[float], float] | Función para generar `y_k` si no se pasan pares. |
| table | Iterable[float] \| Iterable[tuple] | Lista de nodos o pares `(x_k, y_k)`. |

#### Retorna
Instancia de `Newton` lista para construir parciales y diferencias divididas.

#### Métodos
| Método | Descripción |
|---|---|
| `interpolador(position: int | None = None)` | Devuelve lista de funciones `[p_0, ..., p_n]` o una parcial específica. |
| `evaluar(i: int, x: float)` | Evalúa `p_i(x)`. Si `i == -1`, devuelve todas las evaluaciones en un diccionario. |
| `dif_dividas()` | Devuelve un diccionario con diferencias divididas indexadas por expresión. |
| `formatear_dif_dividas(precision: int = 6)` | Devuelve una tabla ASCII con las diferencias divididas. |
| `formatear(position: int | None = None, operar: bool = True, precision: int = 6)` | Formatea la representación numérica o expandida. |

#### Excepciones posibles
- `TypeError` si `position`, `p_i` u `operar` tienen tipo inválido.
- `ValueError` si `position` o `p_i` están fuera de rango.

#### Ejemplo
```python
from analisis_numerico import Newton

n = Newton(lambda x: x**2, [1.0, 2.0, 3.0])
print(n.formatear(position=2, operar=False))
print(n.formatear(position=2, operar=True))
```

#### Buenas prácticas
- Usa `operar=False` para revisar la forma de Newton y `operar=True` para obtener el polinomio expandido.
- Trabaja con pocos nodos cuando necesites coeficientes simbólicamente legibles.

---

### Lagrange(function, table)

Interpolación por base de Lagrange con la misma interfaz pública que `Newton`.

#### Parámetros
| Nombre | Tipo | Descripción |
|---|---|---|
| function | Callable[[float], float] | Función para calcular `y_k` si la tabla solo contiene nodos. |
| table | Iterable[float] \| Iterable[tuple] | Lista de `x_k` o pares `(x_k, y_k)`. |

#### Retorna
Instancia de `Lagrange`.

#### Métodos
| Método | Descripción |
|---|---|
| `interpolador(position: int | None = None)` | Devuelve funciones parciales de Lagrange. |
| `evaluar(i: int, x: float)` | Evalúa `p_i(x)` o devuelve todas las evaluaciones si `i == -1`. |
| `formatear(position: int | None = None, operar: bool = True, precision: int = 6)` | Devuelve la forma numérica o expandida. |

#### Excepciones posibles
- `TypeError` si `position`, `p_i` u `operar` tienen tipo inválido.
- `ValueError` si `position` o `p_i` están fuera de rango.

#### Ejemplo
```python
from analisis_numerico import Lagrange

l = Lagrange(lambda x: x**2, [(1.0, 1.0), (2.0, 4.0), (3.0, 9.0)])
print(l.formatear(position=2, operar=False))
```

#### Notas importantes
- La forma numérica muestra cada término con su numerador y denominador explícitos.
- La expansión puede ser costosa para muchos nodos.

---

### Trapecio(function, a, b, n)

Regla compuesta del trapecio para integración numérica.

#### Parámetros
| Nombre | Tipo | Descripción |
|---|---|---|
| function | Callable[[float], float] | Función a integrar. |
| a | float | Límite inferior. |
| b | float | Límite superior. |
| n | int | Número de subintervalos; debe ser mayor o igual a 1. |

#### Retorna
Instancia de `Trapecio` lista para integrar o generar tablas ASCII.

#### Métodos
| Método | Descripción |
|---|---|
| `integrar()` | Calcula la integral aproximada con la regla compuesta del trapecio. |
| `tabla(precision: int = 6)` | Devuelve una tabla ASCII con nodos `x_i` y valores `f(x_i)`. |
| `integrar_tabla(table)` | Calcula la integral a partir de una tabla de valores. |

#### Excepciones posibles
- `TypeError` si la función no es callable o devuelve valores no numéricos.
- `ValueError` si `a >= b`, si `n` no es válido o si la tabla no cumple el espaciado uniforme.

#### Ejemplo
```python
from analisis_numerico import Trapecio

t = Trapecio(lambda x: x**2, 0.0, 1.0, 4)
print(t.integrar())
print(t.tabla())
```

#### Buenas prácticas
- Usa una partición uniforme cuando llames `integrar_tabla` con nodos explícitos.
- Prefiere `tabla()` para depurar valores intermedios.

---

### Simpson(function, a, b, n)

Regla compuesta de Simpson 1/3 para integración numérica.

#### Parámetros
| Nombre | Tipo | Descripción |
|---|---|---|
| function | Callable[[float], float] | Función a integrar. |
| a | float | Límite inferior. |
| b | float | Límite superior. |
| n | int | Número de subintervalos; debe ser par y mayor o igual a 2. |

#### Retorna
Instancia de `Simpson` lista para integrar o generar tablas ASCII.

#### Métodos
| Método | Descripción |
|---|---|
| `integrar()` | Calcula la integral aproximada con Simpson 1/3 compuesta. |
| `tabla(precision: int = 6)` | Devuelve una tabla ASCII con nodos `x_i` y valores `f(x_i)`. |
| `integrar_tabla(table)` | Calcula la integral a partir de una tabla de valores. |

#### Excepciones posibles
- `TypeError` si la función no es callable o devuelve valores no numéricos.
- `ValueError` si `n` no es par, si `a >= b` o si la tabla no cumple las condiciones de Simpson.

#### Ejemplo
```python
from analisis_numerico import Simpson

s = Simpson(lambda x: x**2, 0.0, 1.0, 4)
print(s.integrar())
print(s.tabla())
```

#### Notas importantes
- `n` debe ser par para Simpson 1/3.
- La tabla debe contener al menos tres puntos y espaciamiento uniforme.

---

### identity(value)

#### Parámetros
| Nombre | Tipo | Descripción |
|---|---|---|
| value | Any | Valor a devolver. |

#### Retorna
El mismo valor recibido.

#### Ejemplo
```python
from analisis_numerico import identity

assert identity(3) == 3
```

---

## 6. Integración numérica

Las clases `Trapecio` y `Simpson` están disponibles en `analisis_numerico.core`.

### Cuándo usar cada una
- `Trapecio`: útil cuando quieres una aproximación simple, rápida y fácil de inspeccionar.
- `Simpson`: preferible cuando necesitas mayor precisión y puedes trabajar con un número par de subintervalos.

### Recomendaciones
- Verifica siempre que la función sea evaluable en los extremos `a` y `b`.
- Usa tablas uniformes para `integrar_tabla`.
- Para funciones muy curvadas, incrementa `n` antes de confiar en una sola aproximación.

---

## 7. Notas avanzadas

- Evita nodos `x_k` demasiado cercanos cuando uses interpolación polinómica.
- `formatear(..., operar=True)` puede crecer rápidamente en coste para grados altos.
- Las tablas ASCII de `Trapecio` y `Simpson` son útiles para auditoría manual y validación.

---

## 8. FAQ

### ¿Puedo pasar índices `k` en `table`?
No. La API actual acepta `x_k` o `(x_k, y_k)`. El indexado interno se genera automáticamente.

### ¿Cómo obtengo el polinomio completo?
El polinomio completo corresponde al último parcial `p_n`: usa `interpolador()[-1]` o `interpolador(n)`.

### ¿Las clases de integración están exportadas desde la raíz del paquete?
No en el estado actual. Se usan desde `analisis_numerico.core`.

### ¿Qué forma de `formatear` conviene usar?
- `operar=False` para inspección de la forma numérica.
- `operar=True` para obtener el polinomio expandido.

---

Para navegación rápida, este documento cubre lo que hoy expone `core.py` y está orientado a uso en producción.

