# Motores de integracion e inicio de IMEX

La prioridad global de continuación se actualizó en [PLAN_CAPACIDADES_MOTOR.md](PLAN_CAPACIDADES_MOTOR.md): ampliar primero las capacidades del motor y verificar cada una con un método mínimo. Ese plan reemplaza el orden de ampliaciones futuras de este documento; se conserva aquí el diseño y el registro de los hitos IMEX.

Estado del 2026-10-04: implementados Euler IMEX (ID 1) y ARS222 (ID 2), ambos desde un generador comun de tablas aditivas. Contrato y uso en [IMEX.md](IMEX.md) y [ARS222.md](ARS222.md). Los pasos 1-5 estan cumplidos para el primer hito. El paso 7 esta parcialmente cumplido: tablas RK aditivas con c comun, orden 1/2 y descriptor v2, conservando lectura de din Euler v1. Siguen pendientes el conductor comun (paso 6), estimadores, adaptacion y PGLM matricial general. Posteriormente se implemento ROS=[1], ROS2 con Jacobiano del campo reducido y algebra lineal propia: ver [ROS.md](ROS.md). EXP, TAYLOR, SPLIT y EXTRAP siguen siendo propuestas de sintaxis, no selectores habilitados.

## Conclusiones y decisiones

GLM clasico unifica RK y multipaso lineales, pero no representa por si solo las operaciones de todos los integradores. Se mantienen RK y GLM; no se restaura el selector historico INTEGRADOR. Los numeros son identificadores arbitrarios dentro del catalogo de cada familia, no ordenes ni equivalencias entre familias.

| Selector | Alcance | Estado al comenzar este trabajo |
| --- | --- | --- |
| RK | Motor historico | Existente; conservar sus resultados y listas. |
| GLM | Etapas e historia mediante A,U,B,V | Existente; conservar IDs y artefactos. |
| PGLM | Particionado/aditivo, incluido IMEX | Primer caso a implementar: Euler IMEX, ID 1. |
| ROS | Rosenbrock y variantes | ROS=[1] implementado: ROS2 fijo o adaptativo, Jacobiano del campo y LU. Otras variantes pendientes. |
| EXP | Exponenciales | Propuesta; necesita operadores y funciones matriciales. |
| TAYLOR | Derivadas superiores | Propuesta; necesita diferenciacion. |
| SPLIT | Composicion de subavances | Propuesta; necesita subproblemas definidos. |
| EXTRAP | Subdivisiones y extrapolacion | Propuesta; necesita orquestacion y estimador propios. |

Los nombres propuestos no anuncian soporte. Una familia o capacidad no disponible debe producir error, nunca caer silenciosamente en RK0. Ser simplectico no define otra familia: algunos RK ya tienen esa propiedad. Las ecuaciones con retardo, ruido y cambios de topologia requieren infraestructura especifica adicional.

## Arquitectura objetivo

| Pieza | Responsabilidad |
| --- | --- |
| Generador C, libdin | Modelo, particiones, ecuaciones de las etapas y metadatos. |
| Conductor | Tiempo, intentos, aceptacion/rechazo, salida y coordinacion de eventos. |
| Motor | Etapas, memoria, estimacion de error y politica de paso propias. |
| Calcula persistente | Resolver/evaluar los sistemas; futuras operaciones especializadas si hacen falta. |

El contrato futuro de cada motor distingue preparar, intentar_paso, aceptar_paso, descartar_intento y reiniciar. Un intento no modifica el estado confirmado. La historia fisica y la memoria de un metodo no son lo mismo. No todos los motores necesitan un anillo ni todos pueden reducirse a una sola resolucion ampliada.

Se conserva la cadena independiente `.d/.ds -> .din -> simulacion`: el artefacto lleva ecuaciones y descriptor en comentarios, sin necesitar el `.dat` ni un catalogo externo al correr. El Jacobiano interno del resolvedor de Calcula no se presume equivalente al del campo diferencial que necesita Rosenbrock.

## Primer hito IMEX (cumplido; especificacion original)

Se implementa solo Euler IMEX aditivo sobre un sistema que define un campo diferencial univoco. No es aun un generador de cualquier tabla PGLM. La parte explicita se declara por estado; la implicita es la derivada total menos esa contribucion. No se infiere una particion a partir de las ramas del circuito.

Ejemplo propuesto para `.ds`:

```text
RUN_CONTROLS
PGLM=[1]
IMEX_EXPLICITA=[X,-X]
SIRU_PASO=[0.1]
SIRU_ADAPT=[0]
```

IMEX_EXPLICITA es una lista de pares estado,expresion; debe cubrir exactamente los estados del modelo, en cualquier orden. La expresion inicial admite numeros, estados, tiempo, parametros y aritmetica `+ - * / ^ ( )`; no variables algebraicas, derivadas, DT, asignaciones, funciones ni separadores internos. Para `.d`, el control equivalente se escribe `IMEX EXPLICITA = [X,-X]`. La sintaxis limitada evita atribuir caracter explicito a una expresion que dependa de incognitas de la etapa. Ampliar expresiones y particiones es un hito posterior.

Con `F = E + I`, las ecuaciones son:

```text
y_nuevo = y + h*(E(t,y) + I(t+h,y_nuevo))
        = y + h*(E(t,y) + F(t+h,y_nuevo) - E(t+h,y_nuevo))
```

Calcula resuelve el modelo completo en el tiempo futuro y la ecuacion ampliada. E(t,y) solo usa datos del paso; las contribuciones de todos los estados futuros se resuelven juntas. Es Euler IMEX aditivo, no Lie-Trotter ni dos Euler completos consecutivos. El archivo resultante conserva la identidad PGLM y la particion.

| Condicion | Primer hito |
| --- | --- |
| Paso | Fijo; ultimo paso acortado para llegar al final. |
| Adaptacion, listas y RERUN | Rechazar. |
| Llaves, lazos/cortes con mdin, convoluciones | Rechazar. |
| DAE general o indice alto | No se promete soporte; el modelo debe determinar las derivadas dados tiempo y estados. |
| Motor temporal | Reutilizar la conduccion de un paso existente mediante un adaptador, sin cambiar RK. |
| Coeficientes de usuario | No habilitados para PGLM en este hito. |

## Orden de trabajo y comprobacion

1. Documentar decisiones y primer contrato; crear casos persistentes del corpus.
2. Reconocer PGLM e IMEX_EXPLICITA en el lector C, con exclusiones y errores precisos.
3. Generar Euler IMEX en libdin y transportar el descriptor completo al `.din`.
4. Seleccionar el adaptador PGLM desde fuente o `.din`; validar metadatos antes de arrancar Calcula.
5. Verificar recurrencia independiente, orden uno, rigidez, acoplamiento, no linealidad, tiempos distintos E/I, ultimo paso acortado y equivalencia fuente/din; probar entradas incompatibles y las suites RK/GLM existentes.
6. Posteriormente extraer la interfaz comun intento/aceptacion y adaptar GLM, con pruebas de regresion. No mezclar ese refactor amplio con la primera formula IMEX.
7. Generalizar a tablas aditivas con coeficientes por particion y estimador propio; luego splitting, Rosenbrock y las demas familias segun sus capacidades.

## Referencias

- [Zhang y Sandu, GLM particionados e IMEX](https://arxiv.org/abs/1302.2689): extensiones de GLM para tratar particiones diferentes.
- [SUNDIALS ARKODE](https://sundials.readthedocs.io/en/latest/arkode/Mathematics_link.html): modulos de avance y servicios compartidos; no implica que su infraestructura sea directamente nuestro conductor multipaso.