426 lines
19 KiB
Markdown
426 lines
19 KiB
Markdown
# Guía de Desarrollo - Calculadora MAV CAS Híbrido
|
|
|
|
## Visión General
|
|
|
|
Este documento describe el estado actual y los objetivos de desarrollo para la **Calculadora MAV**, un **Sistema de Álgebra Computacional (CAS) híbrido**. El proyecto busca combinar la potencia de SymPy como motor algebraico central con capacidades especializadas (IP4, Hex, etc.) integradas de forma nativa.
|
|
|
|
## Objetivos Principales
|
|
|
|
### 1. **SymPy como Motor Central**
|
|
- ✅ Integrar todas las funciones de SymPy directamente
|
|
- ✅ SymPy maneja toda la evaluación algebraica y ecuaciones
|
|
- ✅ Cada línea de ingreso corresponde a una sola línea de resultados
|
|
- ✅ **CONTEXTO LIMPIO POR EVALUACIÓN**: Cada vez que se hace una evaluación se comienza con el contexto completamente limpio y se evalúa desde arriba hacia abajo, línea por línea. Esto garantiza comportamiento predecible sin "memoria" de evaluaciones anteriores.
|
|
- ✅ La interfaz de usuario se divide en 2 columnas, a la izquierda el área de ingreso de datos y ecuaciones a ser evaluadas, a la derecha el área de resultados que se colorean según cada tipo de respuesta.
|
|
|
|
### 2. **Sistema de Tokenización Automática** ⭐ **ACTUALIZADO**
|
|
- ❌ ~~Usar **exclusivamente** `Class[args]` en lugar de `Class("args")`~~ **ELIMINADO**
|
|
- ✅ **Tokenización automática de patrones específicos**:
|
|
- `16#FF` → `IntBase('FF', 16)` automáticamente
|
|
- `192.168.1.1` → `FourBytes('192.168.1.1')` automáticamente
|
|
- ✅ **Sistema distribuido**: Cada clase define sus propios patrones de tokenización
|
|
- ✅ **Precedencia automática**: Patrones más específicos tienen mayor prioridad
|
|
- ✅ **Parser genérico**: No hardcodea lógica específica de tipos
|
|
|
|
### 3. **Detección Automática y Manejo de Ecuaciones**
|
|
- ✅ Ecuaciones ingresadas directamente (ej. `3+b=5+c`) se detectan y añaden al sistema interno de SymPy.
|
|
- ✅ Soporte para comparaciones SymPy (ej. `x > 5`, `a == b`, `x <= 10`) como expresiones evaluables.
|
|
- ✅ Sintaxis de atajo para solve: `variable=?` equivale a `solve(variable)`
|
|
|
|
### 4. **Evaluación Híbrida con Variables SymPy Puras**
|
|
- ✅ Resultado simbólico (siempre disponible)
|
|
- ✅ Evaluación numérica con `.evalf()` (cuando sea aplicable y las variables estén definidas). Esta evaluación se muestra a la derecha del resultado simbólico.
|
|
- ✅ Las asignaciones son siempre simbólicas, solo los resultados se muestra la evaluación numérica.
|
|
- ✅ **Todas las variables son símbolos SymPy**: Sin variables Python tradicionales
|
|
- 🔄 **Conversión perezosa a SymPy**: Objetos nativos hasta que se necesite álgebra compleja
|
|
|
|
### 5. **Resultados Interactivos**
|
|
- ✅ **Tags clickeables** en el widget Text para resultados complejos que necesitan más de una línea de resultado como Plot, Matrices y Listas.
|
|
- ✅ **Detección automática** de tipos que requieren visualización especial:
|
|
- ✅ Plots de SymPy → "📊 Ver Plot" (abre ventana matplotlib).
|
|
- ✅ Matrices → "📋 Ver Matriz" (muestra matriz formateada).
|
|
- ✅ Listas largas → "📋 Ver Lista" (muestra contenido expandido).
|
|
- ✅ Objetos complejos → "🔍 Ver Detalles" (representación completa).
|
|
- ✅ **Implementación con tags**: Usar `text.tag_bind()` en widget existente
|
|
- ✅ **Ventanas popup** para contenido que no cabe en línea.
|
|
|
|
### 6. **Sistema de Tipos Auto-Descubrible** ⭐ **NUEVO**
|
|
- ✅ **Directorio unificado**: Todos los tipos en `custom_types/`
|
|
- ✅ **Auto-registro**: Sistema automático de descubrimiento de clases
|
|
- ✅ **Función de registro**: Cada módulo tiene `register_classes_in_module()`
|
|
- ✅ **Metadatos**: Categorías, opciones y descripciones por tipo
|
|
- ✅ **Helpers dinámicos**: Sistema de ayuda contextual distribuido
|
|
|
|
### 7. **Clases Base Universales** ⭐ **NUEVO**
|
|
- ✅ **IntBase**: Representación universal de números en cualquier base
|
|
- ✅ **FourBytes**: Representación universal de patrones x.x.x.x
|
|
- ✅ **Manejo interno de símbolos**: Sin conversión prematura a SymPy
|
|
- ✅ **Aritmética nativa**: Operaciones que mantienen el tipo original
|
|
- ✅ **Conversión explícita**: `.to_sympy()` cuando se necesite álgebra compleja
|
|
|
|
## Arquitectura Actual ⭐ **ACTUALIZADA**
|
|
|
|
### Estructura de archivos
|
|
```
|
|
/
|
|
├── logs/ # Subcarpeta de logs
|
|
├── docs/ # Documentación técnica
|
|
├── custom_types/ # ⭐ NUEVO: Sistema de tipos unificado
|
|
│ ├── intbase_type.py # IntBase + tokenización + registro
|
|
│ ├── fourbytes_type.py # FourBytes + tokenización + registro
|
|
│ ├── hex_type.py # Hex (usa IntBase)
|
|
│ ├── bin_type.py # Bin (usa IntBase)
|
|
│ ├── dec_type.py # Dec
|
|
│ ├── chr_type.py # Chr
|
|
│ ├── ip4_type.py # IP4 + IP4Mask (usa FourBytes)
|
|
│ └── latex_type.py # LaTeX
|
|
├── calc.py # Launcher principal
|
|
├── main_calc_app.py # Aplicación principal
|
|
├── main_evaluation.py # Motor de evaluación híbrido
|
|
├── type_registry.py # ⭐ NUEVO: Auto-descubrimiento de tipos
|
|
├── tl_popup.py # Motor de ventanas emergentes
|
|
├── tl_bracket_parser.py # ⭐ ACTUALIZADO: Tokenizador universal
|
|
├── class_base.py # Clases base
|
|
├── sympy_Base.py # Base para integración SymPy
|
|
└── sympy_helper.py # Helpers para SymPy
|
|
```
|
|
|
|
### Flujo de Procesamiento ⭐ **ACTUALIZADO**
|
|
```
|
|
Entrada Usuario → [Universal Tokenizer] → [Evaluación Híbrida] → {
|
|
1. Resultado Nativo (FourBytes, IntBase, etc.)
|
|
2. Conversión a SymPy (solo si es necesario)
|
|
3. Evaluación numérica (evalf si aplica)
|
|
4. Métodos especializados disponibles
|
|
}
|
|
```
|
|
|
|
### Transformación de Sintaxis ⭐ **ACTUALIZADA**
|
|
```python
|
|
# Tokenización automática (NUEVO):
|
|
16#FF + 2#1010 → IntBase("FF", 16) + IntBase("1010", 2)
|
|
192.168.1.1 + 5 → FourBytes("192.168.1.1") + 5
|
|
IP4(10.1.1.1, 255.255.0.0) → IP4(FourBytes("10.1.1.1"), FourBytes("255.255.0.0"))
|
|
|
|
# Detección contextual de ecuaciones (EXISTENTE):
|
|
3+b=5+c → Se detecta como ecuación standalone (agregar al sistema SymPy)
|
|
"x > 5" → Se procesa como desigualdad SymPy
|
|
x**2 + 2*x == 0 → Se detecta como igualdad lógica standalone
|
|
|
|
# Sintaxis de atajo para solve (EXISTENTE):
|
|
x=? → solve(x)
|
|
```
|
|
|
|
## Componentes Técnicos ⭐ **ACTUALIZADOS**
|
|
|
|
### 1. **Sistema de Auto-Descubrimiento de Tipos**
|
|
```python
|
|
# type_registry.py
|
|
class TypeRegistry:
|
|
def discover_and_register_all(self):
|
|
"""Descubre y registra todas las clases en custom_types/"""
|
|
for type_file in self.types_directory.glob("*_type.py"):
|
|
self._process_type_file(type_file)
|
|
|
|
def _register_classes_from_info(self, class_info_list):
|
|
"""Registra clases basándose en metadatos"""
|
|
for name, class_obj, category, options in class_info_list:
|
|
self._register_single_class(name, class_obj, category, options)
|
|
```
|
|
|
|
### 2. **Tokenizador Universal Distribuido**
|
|
```python
|
|
# tl_bracket_parser.py
|
|
class UniversalTokenizer:
|
|
def _discover_tokenization_rules(self):
|
|
"""Auto-descubre reglas desde todas las clases registradas"""
|
|
for class_name, class_obj in registered_classes.items():
|
|
if hasattr(class_obj, 'get_tokenization_patterns'):
|
|
patterns = class_obj.get_tokenization_patterns()
|
|
for pattern_info in patterns:
|
|
self.tokenization_rules.append({
|
|
'class_name': class_name,
|
|
'class_obj': class_obj,
|
|
**pattern_info
|
|
})
|
|
```
|
|
|
|
### 3. **Clases con Tokenización Propia**
|
|
```python
|
|
# custom_types/intbase_type.py
|
|
class IntBase(ClassBase):
|
|
@staticmethod
|
|
def get_tokenization_patterns():
|
|
return [
|
|
{
|
|
'pattern': r'(\d+)#([0-9A-Fa-fx]+)',
|
|
'replacement': lambda match: f'IntBase("{match.group(2)}", {match.group(1)})',
|
|
'priority': 5,
|
|
'description': 'Números con base: 16#FF, 2#1010'
|
|
}
|
|
]
|
|
```
|
|
|
|
### 4. **Conversión Perezosa a SymPy** ⭐ **NUEVO CONCEPTO**
|
|
```python
|
|
class FourBytes(ClassBase): # No SympyClassBase
|
|
def substitute(self, **kwargs):
|
|
"""Sustitución interna sin involucrar SymPy"""
|
|
# Lógica nativa
|
|
|
|
def to_sympy(self):
|
|
"""Conversión EXPLÍCITA cuando se necesite álgebra"""
|
|
# Solo convertir cuando se requiera
|
|
```
|
|
|
|
### 5. **Sistema de Evaluación Integrado**
|
|
```python
|
|
# main_evaluation.py
|
|
class HybridEvaluationEngine:
|
|
def __init__(self, auto_discover_types=True):
|
|
# Auto-descubrir tipos dinámicamente
|
|
self.registered_types_info = discover_and_register_types()
|
|
|
|
# Configurar parser con tokenización distribuida
|
|
self.parser = BracketParser(enable_tokenization=True)
|
|
|
|
# Configurar contexto con tipos descubiertos
|
|
self._setup_base_context()
|
|
```
|
|
|
|
## Capacidades Expandidas ⭐ **ACTUALIZADAS**
|
|
|
|
### 1. **Funciones SymPy Completas con Objetos Nativos**
|
|
```python
|
|
# Objetos nativos en álgebra (conversión automática cuando es necesario):
|
|
diff(IP4(192.168.x.1) + offset, x) # FourBytes → SymPy automático
|
|
integrate(Hex(16#x0) * sin(x), x) # IntBase → SymPy automático
|
|
solve([IP4(192.168.x.y) == IP4(192.168.1.10)], [x, y])
|
|
|
|
# Aritmética nativa (mantiene tipos):
|
|
base_ip = 192.168.1.1 # → FourBytes automático
|
|
next_ip = base_ip + 5 # → FourBytes('192.168.1.6')
|
|
hex_val = 16#FF + 16#10 # → IntBase('10F', 16)
|
|
```
|
|
|
|
### 2. **Conversiones Automáticas Bidireccionales**
|
|
```python
|
|
# Conversiones fluidas entre tipos:
|
|
ip = 192.168.1.1 # → FourBytes automático
|
|
ip_hex = ip.ToHex() # → "16#C0.16#A8.16#1.16#1"
|
|
mask = 255.255.255.0 # → FourBytes automático
|
|
mask_cidr = IP4Mask(mask) # → /24 automático
|
|
|
|
# Constructores inteligentes:
|
|
IP4(192.168.1.1, 16#ffffff00) # FourBytes + IntBase → IP4
|
|
Hex(192.168.1.1) # FourBytes → Hex automático
|
|
```
|
|
|
|
### 3. **Sistema de Ayuda Dinámico**
|
|
```python
|
|
# Helpers auto-descubiertos:
|
|
help_functions = get_registered_helper_functions() # De todas las clases
|
|
help_context = obtener_ayuda("16#FF") # Helper de IntBase
|
|
autocompletado = obj.PopupFunctionList() # Métodos disponibles
|
|
```
|
|
|
|
## Ejemplos de Uso Objetivo ⭐ **ACTUALIZADOS**
|
|
|
|
```python
|
|
# Tokenización automática de patrones:
|
|
16#FF + 2#1010 # → IntBase('FF', 16) + IntBase('1010', 2)
|
|
192.168.1.1 + 5 # → FourBytes('192.168.1.6')
|
|
10.x.1.y # → FourBytes('10.x.1.y') simbólico
|
|
|
|
# Constructores inteligentes:
|
|
IP4(192.168.1.1, 24) # → IP4(FourBytes('192.168.1.1'), 24)
|
|
IP4(10.1.1.1, 255.255.0.0) # → Ambos FourBytes automáticamente
|
|
Hex(192.168.1.1) # → Conversión FourBytes → Hex
|
|
|
|
# Conversiones fluidas:
|
|
mask = 255.255.255.0 # → FourBytes automático
|
|
mask.ToHex() # → "16#FF.16#FF.16#FF.16#0"
|
|
mask.ToBase(2) # → "2#11111111.2#11111111.2#11111111.2#0"
|
|
|
|
# Álgebra con objetos nativos:
|
|
network = 10.x.0.0 # → FourBytes simbólico
|
|
solve(network + 256 == 10.5.0.0, x) # → x = 5
|
|
|
|
# Aritmética que preserva tipos:
|
|
base = 192.168.0.0 # → FourBytes
|
|
for i in range(4):
|
|
subnet = base + (i * 256) # → Cada resultado es FourBytes
|
|
print(f"Red {i}: {subnet}")
|
|
|
|
# Evaluación directa con SymPy:
|
|
solve(x + 10 - 15, x) # → [5]
|
|
diff(16#x0, x) # → 16*log(16) (conversión automática)
|
|
|
|
# Variables puras SymPy:
|
|
x = 5 # → x es Symbol('x') con valor 5
|
|
y = x + 2 # → y es expresión simbólica: Symbol('x') + 2
|
|
|
|
# Funciones avanzadas con resultados interactivos:
|
|
plot(sin(2*pi*16#x/256), (x, 0, 255)) # → "📊 Ver Plot"
|
|
Matrix([[1, 2, 3], [4, 5, 6]]) # → "📋 Ver Matriz"
|
|
```
|
|
|
|
## Beneficios Logrados ⭐ **ACTUALIZADOS**
|
|
|
|
### 1. **Usabilidad Mejorada**
|
|
- ✅ Sintaxis natural sin artificios (no más `Class[args]`)
|
|
- ✅ Tokenización invisible al usuario
|
|
- ✅ Acceso completo a capacidades de CAS
|
|
- ✅ Evaluación automática simbólica + numérica
|
|
|
|
### 2. **Potencia Matemática Expandida**
|
|
- ✅ Todas las funciones de SymPy disponibles
|
|
- ✅ Objetos especializados participan en álgebra cuando es necesario
|
|
- ✅ Aritmética nativa que preserva tipos
|
|
- ✅ Conversiones automáticas bidireccionales
|
|
|
|
### 3. **Extensibilidad Real**
|
|
- ✅ Sistema verdaderamente modular sin hardcoding
|
|
- ✅ Fácil agregar nuevos tipos sin modificar código core
|
|
- ✅ Tokenización distribuida y auto-descubrible
|
|
- ✅ Compatible con ecosystem SymPy completo
|
|
|
|
### 4. **Arquitectura Limpia**
|
|
- ✅ Responsabilidad única: cada clase maneja su tokenización
|
|
- ✅ Parser genérico sin conocimiento específico de tipos
|
|
- ✅ Auto-descubrimiento completo del sistema de tipos
|
|
- ✅ Manejo unificado de errores
|
|
|
|
## Sistema de Autocompletado y Ayuda Contextual ⭐ **IMPLEMENTADO**
|
|
|
|
### 1. **Helpers Dinámicos**
|
|
- ✅ **Auto-descubrimiento**: Sistema obtiene helpers de todas las clases registradas
|
|
- ✅ **Ayuda contextual**: Cada tipo define su propio `Helper(input_str)`
|
|
- ✅ **Integración con SymPy**: Helper especializado para funciones SymPy
|
|
- ✅ **Manejo centralizado**: Lista dinámica de helpers disponibles
|
|
|
|
### 2. **Autocompletado Inteligente**
|
|
- ✅ **Popup tras punto**: Evaluación automática del objeto para métodos disponibles
|
|
- ✅ **PopupFunctionList()**: Cada clase define sus métodos sugeridos
|
|
- ✅ **Filtrado inteligente**: Solo métodos útiles y públicos
|
|
- ✅ **No invasivo**: Solo aparece cuando el usuario lo solicita
|
|
|
|
### 3. **Ejemplos de Integración**
|
|
```python
|
|
# Sistema distribuido:
|
|
HELPERS = get_registered_helper_functions() # Auto-descubierto
|
|
|
|
# Ayuda contextual:
|
|
16#FF. # → Popup con métodos de IntBase
|
|
192.168.1.1. # → Popup con métodos de FourBytes
|
|
IP4(10.1.1.1). # → Popup con métodos de IP4
|
|
|
|
# Helpers específicos:
|
|
ayuda = obtener_ayuda("16#FF") # → "Números con base: 16#FF, 2#1010..."
|
|
```
|
|
|
|
## Estado de Implementación ⭐ **ACTUALIZADO**
|
|
|
|
### ✅ **Completamente Implementado**
|
|
- **Sistema de auto-descubrimiento**: `type_registry.py`
|
|
- **Tokenizador universal**: `tl_bracket_parser.py` refactorizado
|
|
- **Clases base universales**: `intbase_type.py`, `fourbytes_type.py`
|
|
- **Motor híbrido integrado**: `main_evaluation.py` con auto-descubrimiento
|
|
- **Tipos en custom_types/**: Todos los tipos migrados al sistema unificado
|
|
- **Helpers dinámicos**: Sistema de ayuda contextual distribuido
|
|
- **Resultados interactivos**: Tags clickeables y ventanas popup
|
|
- **Contexto limpio**: Evaluación completa desde cero en cada cambio
|
|
|
|
### 🔄 **En Progreso**
|
|
- **Conversión perezosa a SymPy**: Algunos objetos aún se convierten prematuramente
|
|
- **Aritmética que preserva tipos**: Necesita refinamiento para todos los casos
|
|
- **Optimización de precedencia**: Ajuste fino de prioridades de tokenización
|
|
|
|
### 📋 **Pendiente**
|
|
- **Tipos adicionales**: MAC addresses, timestamps, coordenadas
|
|
- **Performance optimization**: Caching y evaluación lazy
|
|
- **Documentación de usuario**: Guías y ejemplos actualizados
|
|
|
|
## Métricas de Éxito ⭐ **ACTUALIZADAS**
|
|
|
|
- ✅ **Sistema de tokenización automática funcional**:
|
|
- ✅ Patrones `16#FF`, `2#1010` → IntBase automático
|
|
- ✅ Patrones `192.168.1.1` → FourBytes automático
|
|
- ✅ Precedencia automática por especificidad
|
|
- ✅ Parser genérico sin hardcoding
|
|
|
|
- ✅ **Sistema de tipos auto-descubrible**:
|
|
- ✅ Todas las clases en `custom_types/`
|
|
- ✅ Función `register_classes_in_module()` en cada módulo
|
|
- ✅ Auto-registro con metadatos y opciones
|
|
- ✅ Helpers dinámicos desde todas las clases
|
|
|
|
- ✅ **Clases base universales funcionales**:
|
|
- ✅ IntBase con aritmética nativa y tokenización propia
|
|
- ✅ FourBytes con aritmética nativa y tokenización propia
|
|
- ✅ Conversión explícita `.to_sympy()` cuando sea necesario
|
|
- ✅ Operadores que mantienen tipos nativos
|
|
|
|
- ✅ **Motor híbrido integrado**:
|
|
- ✅ Auto-descubrimiento de tipos al inicializar
|
|
- ✅ Tokenización distribuida automática
|
|
- ✅ Contexto limpio por evaluación
|
|
- ✅ Evaluación simbólica + numérica
|
|
|
|
- 🔄 **Conversión perezosa optimizada**:
|
|
- ✅ Objetos nativos por defecto
|
|
- 🔄 Conversión solo cuando se necesite álgebra compleja
|
|
- 🔄 Aritmética preservando tipos en todos los casos
|
|
|
|
- ✅ **Detección contextual de ecuaciones**:
|
|
- ✅ Ecuaciones standalone detectadas y agregadas al sistema
|
|
- ✅ Sintaxis de atajo `variable=?` → `solve(variable)`
|
|
- ✅ Protección contra detección en argumentos de función
|
|
|
|
- ✅ **Resultados interactivos**:
|
|
- ✅ Tags clickeables para plots, matrices, listas
|
|
- ✅ Ventanas popup con posicionamiento inteligente
|
|
- ✅ Detección automática de tipos complejos
|
|
|
|
- ✅ **Sistema de ayuda avanzado**:
|
|
- ✅ Helpers auto-descubiertos desde todas las clases
|
|
- ✅ Autocompletado tras punto con métodos disponibles
|
|
- ✅ Ayuda contextual no invasiva
|
|
|
|
- ✅ **Performance aceptable**: Debounce y evaluación optimizada
|
|
- ✅ **Manejo robusto de errores**: Logging centralizado y presentación clara
|
|
- ✅ **Documentación actualizada**: Guías técnicas y de desarrollo
|
|
|
|
## Consideraciones Futuras
|
|
|
|
### **Tipos Adicionales Planeados**
|
|
```python
|
|
custom_types/
|
|
├── mac_type.py # Direcciones MAC: AA:BB:CC:DD:EE:FF
|
|
├── time_type.py # Timestamps: HH:MM:SS, ISO format
|
|
├── coordinate_type.py # Coordenadas: lat,lon
|
|
├── ipv6_type.py # IPv6: 2001:db8::1
|
|
└── range_type.py # Rangos: 1..100, a..z
|
|
```
|
|
|
|
### **Optimizaciones de Performance**
|
|
- Caching de patrones de tokenización frecuentes
|
|
- Evaluación lazy de `evalf()` solo cuando se muestre
|
|
- Memoización de conversiones SymPy costosas
|
|
|
|
### **Extensiones del Parser**
|
|
- Soporte para sintaxis de múltiples líneas
|
|
- Macros y templates definidos por usuario
|
|
- Validación contextual más sofisticada
|
|
|
|
## Conclusión
|
|
|
|
La calculadora MAV ha evolucionado hacia un **sistema verdaderamente híbrido y extensible** que combina:
|
|
|
|
1. **Potencia algebraica completa** de SymPy
|
|
2. **Objetos nativos especializados** con aritmética propia
|
|
3. **Tokenización automática invisible** al usuario
|
|
4. **Arquitectura modular** sin hardcoding
|
|
5. **Auto-descubrimiento completo** del sistema de tipos
|
|
|
|
El resultado es una herramienta que es **más simple para el usuario** (sintaxis natural) pero **más poderosa internamente** (álgebra simbólica + tipos especializados), con una **arquitectura limpia y extensible** que facilita agregar nuevas capacidades sin modificar código existente. |