7.0 KiB

Raw Blame History

Guía de Principios Arquitectónicos - Calculadora Algebraica Híbrida

Filosofía Central: Álgebra Simbólica con Evaluación Numérica

Concepto Fundamental

La calculadora mantiene forma simbólica como representación primaria y proporciona evaluación numérica como información complementaria cuando es posible y útil.

Principio de Evaluación Numérica: El resultado siempre se intenta calcular numéricamente y se muestra cuando la representación string del resultado numérico difiere del resultado algebraico.

Sistema de Asignaciones y Ecuaciones

Principio: Separación clara entre asignaciones y ecuaciones

# Asignación de variable
x = 5              # → Se guarda el valor simbólico (NO se agrega como ecuación)
y = x + a          # → Se guarda la expresión simbólica

# Ecuación pura (detección automática)
x**2 + 2*x = 8     # → Se agrega como ecuación Eq(x**2 + 2*x, 8)
a + b = 10         # → Se agrega como ecuación Eq(a + b, 10)
a > b + 1          # → Se agrega como desigualdad

Criterios de Detección de Ecuaciones

Se considera ecuación si:

Contiene = Y NO es una asignación simple de variable
Contiene operadores de comparación: ==, >, <, >=, <=
Tiene estructura algebraica en ambos lados del =

NO se considera ecuación:

Asignaciones simples: x = 5, y = expresión
Líneas con solo números o comentarios

Uso de `solve()` y el Atajo `=?`

Principio: `variable=?` es equivalente a `solve(variable)`

# Ambas formas son idénticas:
solve(a)    # Resuelve 'a' usando el sistema de ecuaciones
a=?         # Atajo sintáctico para solve(a)

El comando intenta resolver algebraicamente y numéricamente en paralelo cuando es posible.

Sistema de Tokenización con Prioridades

Principio: Las prioridades son números arbitrarios que determinan el orden de aplicación

Prioridad 5:  IntBase    → Patrón: 16#FF (muy específico)
Prioridad 6:  Hex/Bin    → Patrón: 0xFF, 0b1010 (específico)
Prioridad 10: FourBytes  → Patrón: x.x.x.x (general)

Regla: Menor número = se aplica primero

Esto garantiza que 16#10.10.10.10 se tokenice como IntBase antes de considerar FourBytes.

Conversión Perezosa y Tipos Especializados

Principio: Mantener el tipo especializado siempre que sea posible

Se evita convertir a SymPy al máximo. Los objetos especializados mantienen su tipo cuando pueden resolver la operación internamente.

# Operaciones que mantienen el tipo especializado:
Hex(15) + 1        → Hex(16)      # Hex maneja la suma
16#15 + 1          → 16#16        # IntBase maneja la suma
10.1.1.1 + 1       → 10.1.1.2     # FourBytes maneja la suma

# Conversión a SymPy solo cuando es necesario:
sin(16#FF)         → sin(255)     # sin() requiere SymPy
solve(x + 16#10)   → solve()      # Álgebra compleja requiere SymPy

Regla: Solo se convierte a SymPy cuando el token no es atómico o la operación requiere capacidades algebraicas avanzadas.

Contexto Limpio por Evaluación

Principio: Cada evaluación comienza desde cero

Contexto Limpio significa:

Se eliminan todas las ecuaciones previas
Se eliminan todas las variables definidas
Se re-evalúa todo el contenido línea por línea
Comportamiento idéntico a iniciar una nueva sesión

Esto garantiza resultados predecibles y sin efectos secundarios acumulados.

Resultados Interactivos

Principio: Activación mediante clicks en elementos con binding

Los resultados interactivos se crean cuando el tipo de resultado requiere visualización expandida:

plot(sin(x))       → "📊 Ver Plot"      # Click abre ventana matplotlib
Matrix([[1,2],[3,4]]) → "📋 Ver Matriz" # Click muestra matriz formateada
[1,2,3,4,5,6,7,8]  → "📋 Ver Lista"     # Click expande contenido

Activación: Click en el texto con binding dispara la ventana emergente correspondiente.

Sistema de Autocompletado

Principio: Sistema extensible con prioridades (por implementar)

Se propone usar un sistema de prioridades numéricas similar al de tokenización:

Prioridad 1: Métodos del objeto específico
Prioridad 2: Métodos de la clase base
Prioridad 3: Funciones SymPy relevantes
Prioridad 4: Helpers contextuales

Integración con SymPy

Principio: En casos de conflicto, siempre prevalece SymPy

Cuando hay ambigüedad o conflicto entre tipos personalizados y SymPy:

Funciones SymPy tienen precedencia
Símbolos SymPy (como e, pi) mantienen su significado matemático
Las conversiones fallidas retornan a comportamiento SymPy estándar

Arquitectura de Tipos Personalizados

Clases Base Universales

IntBase: Números en cualquier base

Aritmética nativa que preserva la base
Conversión a SymPy solo cuando necesario
Soporte para símbolos algebraicos

FourBytes: Patrones x.x.x.x

Aritmética de 32-bit para IPs
Soporte para elementos simbólicos
Base para tipos como IP4

Principio de Extensibilidad

Cada tipo en custom_types/ define:

Su lógica de tokenización
Sus operaciones aritméticas
Sus métodos de conversión
Su ayuda contextual
Sus sugerencias de autocompletado

Flujo de Evaluación Completo

Entrada Usuario
    ↓
[Tokenización Universal]
    ↓
¿Asignación o Ecuación?
    ├─ Asignación → Guardar valor simbólico
    └─ Ecuación → Agregar al sistema
    ↓
[Evaluación]
    ├─ Mantener tipo especializado si es posible
    └─ Convertir a SymPy si es necesario
    ↓
[Resultado]
    ├─ Forma simbólica (siempre)
    └─ Evaluación numérica (si difiere como string)

Ejemplos Integrales

# Tokenización y tipos especializados
16#FF + 2#1010     → 16#109        # IntBase preservado
192.168.1.1 + 5    → 192.168.1.6   # FourBytes preservado

# Asignaciones vs ecuaciones
x = 10             # Asignación (solo guarda valor)
x + y = 15         # Ecuación (se agrega al sistema)
y=?                # solve(y) → y = 5

# Evaluación numérica automática
4/5                → 4/5 ≈ 0.8     # Difiere como string
sqrt(2)            → √2 ≈ 1.414    # Difiere como string
2 + 3              → 5             # NO se muestra ≈ (igual string)

# Resultados interactivos
plot(sin(x))       → "📊 Ver Plot" [clickeable]
Matrix([[1,2]])    → "📋 Ver Matriz" [clickeable]

Principios de Diseño Resumidos

Álgebra primero: Mantener forma simbólica siempre
Evaluación numérica inteligente: Mostrar solo cuando agrega valor
Tipos especializados preservados: Conversión a SymPy solo cuando necesario
Tokenización ordenada: Sistema de prioridades simple y predecible
Contexto limpio: Cada evaluación desde cero
Extensibilidad: Nuevos tipos se integran automáticamente
SymPy prevalece: En conflictos, el comportamiento matemático estándar gana

Este documento ahora refleja con precisión la arquitectura implementada y sirve como guía coherente para el desarrollo futuro.

7.0 KiB Raw Blame History