# Plan de ampliación del motor de integración

Fecha original: 2026-10-04. Actualización: 2026-10-06. Estado: plan acordado con los avances explícitos de la tabla siguiente; no se da por terminado el plan completo.

| Bloque | Implementado al 2026-10-06 | Continuación |
| --- | --- | --- |
| Corrección previa | Historia del predictor igual al resultado aceptado de dos medios pasos; extrapolación con el paso solicitado, e invalidación al cambiar configuración. | Conservar las regresiones específicas. |
| M1 | `Siru::Paso` en GLM y en el conductor RK/PGLM/ROS; ramas aisladas; `ControlPaso`; estadísticas de intentos, descartes y consultas en el informe. | Extender los contratos de modelo/proveedor cuando se incorporen capacidades nuevas; no confundir reinicio con inicialización consistente. |
| M2 inicial | `Historia` dimensionable, separada de memoria GLM; ramas de comparación independientes; adaptación de Euler, BDF2 efectivo/directo y AB2 con estimador declarado, rechazos y rearranques. | Órdenes superiores/variables, coeficientes con más pasos previos, Nordsieck y conversión de memoria para listas. |
| M3 inicial | `ServiciosNumericos` sobre campo EVAL/SENS1 y LU densa; claves de caché completas, varios segundos miembros y `EtapasROS` usado por ROS2. | Otro método de más etapas con coeficientes y orden verificados; operadores dispersos, productos J·v y otras capacidades cuando se necesiten. |
| M4 inicial | SPLIT: dos subflujos autónomos exactos declarados, composición Lie–Trotter/Strang, mapas generados en C y ejecución de `.din` aislado. | Subflujos aproximados, dependencia temporal, particiones más generales y adaptación. |
| M5–M8 | Sin nuevas implementaciones en este bloque. | Mantener la secuencia de capacidades descrita abajo. |

Contratos y alcance en [CONTRATO_PASO.md](CONTRATO_PASO.md), [GLM_CONTRATO.md](GLM_CONTRATO.md) y [ROS.md](ROS.md). Las listas de cada etapa describen el objetivo completo, no solo lo entregado.

## Objetivo y prioridad

Ampliar primero las operaciones y los contratos que necesita el motor, y después incorporar los métodos que los utilizan. No organizar el trabajo como una sucesión de números nuevos en los catálogos. Cada capacidad se verificará con un método mínimo antes de generalizarla: infraestructura y demostración numérica se entregan juntas.

Este documento fija la prioridad global de continuación. Complementa los contratos vigentes y reemplaza el orden de ampliaciones futuras de [PLAN_MOTORES_IMEX.md](PLAN_MOTORES_IMEX.md); no altera las fórmulas ni los selectores actuales. [CATALOGO_INTEGRADORES.md](CATALOGO_INTEGRADORES.md) conserva el inventario de familias. Cubrir esas familias no significa implementar todas las tablas y variantes posibles.

## Base que se conserva

| Pieza | Base disponible | Límite que no debe confundirse con soporte general |
| --- | --- | --- |
| RK | Etapas explícitas e implícitas; adaptación existente | Una tabla de Butcher no describe todas las operaciones de otros motores. |
| GLM | Euler, BDF2 efectivo/directo y AB2, fijos/adaptativos; memoria separada de la historia física | Estimador inicial conservador de orden de error 2; faltan orden variable y memoria general. Los dos BDF2 son representaciones de un mismo método. |
| PGLM | Euler IMEX y ARS222 desde tablas aditivas | No equivale a cualquier partición de variables o composición de subflujos. |
| ROS | ROS2 fijo/adaptativo; campo por evaluaciones y Jacobiano por diferencias o sensibilidades | SENS1 no aporta por sí solo derivadas de orden superior ni un integrador DAE general. |
| Eventos y topología | Caminos existentes para llaves/mdin y tratamiento de quiebres conocidos; GLM tiene rearranques en quiebres | No todos los motores admiten esos caminos ni existe todavía localización general de eventos. |

Las llaves se siguen evaluando al comienzo del paso, como está decidido y documentado en el README. Incorporar localización de eventos no cambiará silenciosamente esa semántica: será una capacidad distinta, explícitamente solicitada y habilitada por motor.

## Responsabilidades y compatibilidad

| Componente | Responsabilidad |
| --- | --- |
| `libdin` / `d2datdinc`, en C | Único armador de ecuaciones: modelo, particiones, sistemas ampliados y descriptores. |
| siru, en Perl | Conducción temporal, intentos, historia, adaptación, coordinación de eventos y salida; lógica propia de cada método. |
| Calcula persistente | Resolución y evaluación de sistemas, residuos y sensibilidades; ampliar su protocolo cuando una operación nueva lo justifique. |
| `.din` | Artefacto autosuficiente con ecuaciones, método, coeficientes, controles y declaraciones necesarias para ejecutar. |

Reglas permanentes:

- Conservar la separación `.d/.ds → .din → simulación`, sin requerir `.dat` ni catálogo externo durante la ejecución desde `.din`.
- Mantener los caminos y selectores RK, GLM, PGLM y ROS. Los IDs son arbitrarios dentro de cada catálogo; no indican orden ni equivalencia entre familias.
- No reintroducir el selector histórico `INTEGRADOR`. EXP, TAYLOR y EXTRAP siguen siendo propuestas; SPLIT tiene el contrato inicial implementado de M4.
- Distinguir capacidades requeridas por el método y ofrecidas por el modelo/proveedor. Rechazar incompatibilidades antes de simular; nunca sustituir silenciosamente por RK0.
- Versionar los descriptores y negociar las operaciones de Calcula, conservando lectura de artefactos anteriores cuando sea posible.
- No mover toda el álgebra lineal a Calcula por principio: reutilizar lo existente y decidir su ubicación por dependencia, costo y verificabilidad.
- No hacer una reescritura total. Extraer interfaces progresivamente con pruebas de regresión y sin tocar cambios ajenos de otras sesiones.

## Secuencia de capacidades

### M1. Intentos transaccionales y conducción común

1. Definir `preparar`, `intentar_paso`, `aceptar_paso`, `descartar_intento` y `reiniciar`; los nombres concretos se fijarán al revisar las interfaces actuales.
2. Separar el estado confirmado del candidato: tiempo, estados, memoria, parámetros, contadores de selección y cachés dependientes del intento. Registrar por separado el costo de intentos descartados.
3. Hacer que cada motor entregue candidato, estimación de error cuando exista, diagnóstico y datos propios para confirmar. La historia solo se modifica al aceptar.
4. Centralizar límites, tolerancias, salida y estadísticas sin imponer el mismo estimador, controlador o política de recuperación a todas las familias. Separar tolerancia temporal y tolerancia del resolvedor.
5. Revisar también la semilla y el estado mutable de la sesión de Calcula: descartar un intento en Perl no basta si una consulta fallida deja efectos que cambian la rama de solución. Definir qué se restaura, invalida o vuelve a establecer.

**Demostración mínima:** adaptar progresivamente un camino existente; forzar aceptación, rechazo y fallo de consulta, comprobar que no se publica un candidato rechazado y que el siguiente intento parte del estado confirmado. Mantener las regresiones de RK, GLM, PGLM y ROS.

### M2. Historia general y memoria de métodos

1. Proveer un anillo de estados, derivadas disponibles, tiempos y pasos aceptados, dimensionado por las necesidades declaradas, no por un máximo fijo arbitrario.
2. Mantener separada la memoria externa de un GLM; explicitar escalas, datos faltantes, arranque y reconstrucción. Añadir otras representaciones, como Nordsieck, solo con transformaciones verificadas.
3. Permitir ramas independientes de historia para pruebas por subdivisión. No aplicar mecánicamente el ensayo de dos medios pasos de RK a un multipaso.
4. Admitir coeficientes que dependan de varios pasos previos, no solo de `h/h_anterior`; fijar límites de razón de pasos y políticas de cambio de orden.
5. Definir transporte o reinicio de memoria al cambiar de método; tener un anillo grande no demuestra que una lista mixta sea válida.

**Demostración mínima:** BDF2 y AB2 con intentos de pasos desiguales, rechazo y rearranque, seguidos de adaptación con estimador validado. Después ampliar a BDF de órdenes 1–5, Adams y predictor–corrector. BDF6, NDF y otras variantes requieren validación propia; el número de correcciones de un predictor–corrector debe quedar declarado.

### M3. Servicios de evaluación y operaciones numéricas

1. Describir explícitamente qué proveedor ofrece campo reducido, residuos, Jacobiano del campo, sensibilidades del residuo y resolución lineal. No confundir esos Jacobianos entre sí.
2. Encapsular escalado, factorización, resolución con varios segundos miembros y diagnóstico de singularidad; preparar extensiones dispersas o productos Jacobiano-vector cuando sean necesarias.
3. Identificar las condiciones de validez de cada caché: estado, tiempo, paso, parámetros, modelo y topología. Reutilizar solo cuando lo permita el método.
4. Incorporar al protocolo de Calcula únicamente las operaciones que falten; aprovechar EVAL/SENS1 y verificar precisión, fallos y sesiones persistentes.

**Demostración mínima:** conservar ROS2 con ambos proveedores y convertir sus etapas en un contrato extensible; añadir posteriormente un Rosenbrock de más etapas para verificar que la interfaz no está ligada a ROS2. No habilitar variantes W sin revisar sus condiciones particulares.

### M4. Particiones y subflujos declarados

#### Primer contrato SPLIT (implementado)

| Pieza | Decisión |
| --- | --- |
| Selector | `SPLIT=[1]` Lie–Trotter: A(h), B(h); `SPLIT=[2]` Strang: A(h/2), B(h), A(h/2), en orden de ejecución. IDs propios y excluyentes con RK/GLM/PGLM/ROS. |
| Declaración | `SPLIT_A=[estado,expresion,...]` y `SPLIT_B=[estado,expresion,...]`, con todos los estados, incluso los que no cambian. Son mapas de avance, no derivadas; `SPLIT_H` es la duración del subavance. |
| Modelo inicial | `SPLIT_AUTONOMO=[1]` y `SPLIT_EXACTOS=[1]` son declaraciones obligatorias. Mapas aritméticos de estados, parámetros constantes y duración; no tiempo, derivadas, algebraicas, funciones ni efectos externos. Que sean flujos exactos del modelo es responsabilidad del autor, no una propiedad que el lector demuestre. |
| Transporte | C genera ecuaciones para evaluar el mapa seleccionado en Calcula y un descriptor comentado con mapas, estados y secuencia. Un `.din` aislado es suficiente. |
| Conducción | Perl compone subavances por una interfaz genérica; solo el paso completo confirma estado, reloj y salida mediante `Siru::Paso`/`Integrador`. Fallar un subavance aborta sin publicar una trayectoria parcial. |
| Límites | Paso fijo positivo y último paso acortado; sin adaptación, tiempos no autónomos, `.mdin`, eventos, convoluciones, DC, RERUN/CONTINUE ni aproximadores internos de subflujo. No se declara terminado todo M4. |
| Verificación | Oscilador con flujos de deriva/impulso exactos, recurrencias independientes, órdenes 1/2, reversibilidad de Strang, fallos entre subavances y equivalencia fuente/din. No se infiere que cualquier composición sea simpléctica. |

Referencia de diseño: [Blanes, Casas y Murua, Splitting and composition methods](https://arxiv.org/abs/0812.0377). La distinción entre subflujos y su composición guía este contrato; el alcance inicial autónomo es una decisión de Siru.

| Declaración | Significado | Primera demostración |
| --- | --- | --- |
| Partición aditiva | Varias contribuciones a la misma derivada | Reproducir Euler IMEX y ARS222; preparar adaptación propia. |
| Partición de variables | Grupos de estados con ecuaciones y acoplamientos diferenciados | Euler–Cromer y Verlet sobre un sistema separable apropiado. |
| Subflujos | Avances de subproblemas que se componen en un orden definido | Lie–Trotter y Strang, verificando órdenes uno y dos. |

Las particiones se declaran en el modelo, se validan en el generador y viajan en el `.din`; no se infieren de nombres de ramas. Precisar tratamiento del tiempo no autónomo, intercambio de datos y error de subavances aproximados. Algunos métodos de composición requieren pasos negativos: no admitirlos si el subproblema no los soporta.

### M5. Interpolación temporal, eventos y avances anidados

#### Primera entrega: muestreo de Euler (contrato de implementación)

| Pieza | Alcance inicial |
| --- | --- |
| Entrada | `RK=[0]`, `SIRU_ADAPT=[0]`, `SIRU_SALIDA_PASO=[delta]`; en `.d`, `SIRU OUTPUT STEP = delta`. No es otro método de integración. |
| Interpolación | Extensión lineal entre los extremos de cada paso Euler aceptado; orden global uno en modelos suaves. No se extrapola ni se aplica a otros RK. |
| Grilla | `desde + k*delta`, con fila inicial y final aunque el final no pertenezca a la grilla. No se fuerza al integrador a detenerse en cada salida. |
| Separación | Objeto de intervalo copiado e independiente del proveedor; muestreador sin consultas a Calcula ni modificaciones del estado, historia o reloj. Sólo se publica un intervalo aceptado. |
| Transporte | Descriptor `# muestreo` v1 en el `.din`, con método de interpolación, orden, espaciado y columnas/nombres. Fuente y `.din` aislado producen la misma tabla. |
| Límites | Salidas de estados, modelo suave, un Euler explícito fijo verificado por su tabla; sin algebraicas de salida, adaptación, rescate por subdivisión, llaves/mdin, paradas, convolución, DC/AC, RERUN/CONTINUE, tablas ni funciones propias/externas. Se rechazan quiebres detectados; la suavidad general es responsabilidad del modelo. |
| Pruebas | Igual trayectoria de extremos e igual número de consultas al variar delta; orden también en puntos interiores; inicio no nulo, final acortado, precisión de tiempos, datos no finitos y fallo sin salida parcial. |

Esta entrega no implementa eventos. Después se agregará localización optativa de raíces sobre intervalos con interpolación válida, con un contrato explícito de parada/reinicio. No se cambiará la semántica actual de las llaves.

1. Dar a cada motor una interfaz de interpolación dentro de pasos aceptados, con orden y dominio de validez declarados. Una interpolación lineal universal no conserva el orden de cualquier integrador.
2. Separar salida en una grilla, quiebres conocidos, condiciones revisadas al comienzo del paso y eventos que requieren localizar una raíz.
3. Definir después de cada discontinuidad qué estado cambia, qué restricciones se resuelven y qué historia/cachés se invalidan. Habilitar `.mdin` por motor, con pruebas específicas.
4. Permitir subintegradores con tiempos, tolerancias e historia propios; coordinar el error de los acoplamientos y las consultas intermedias.

**Demostración mínima:** salida interpolada de orden comprobado y un evento optativo localizado, conservando el comportamiento de llaves actual. Luego un sistema rápido/lento con subpasos para abrir multirate RK, MIS y MRI-GARK.

La extracción de los ganchos de eventos comienza en M1; esta etapa completa sus operaciones numéricas. M4 y M5 se complementan para multirritmo, pero splitting sencillo no debe esperar a que todo M5 esté implementado.

### M6. Operadores lineales y funciones matriciales

1. Declarar una descomposición apropiada, por ejemplo `y' = L*y + N(t,y)`, con dimensiones, dependencia temporal y forma de aplicar L.
2. Proveer acciones de exponencial y funciones phi, con tratamiento estable del caso singular o próximo a cero: no definirlas mediante inversión ingenua de L.
3. Comenzar con matrices pequeñas y control de precisión; evaluar métodos de Krylov para sistemas grandes, sin obligar a formar matrices densas.

**Demostración mínima:** Euler exponencial y ETD2 en problemas lineales, semilineales y con L singular. Después ETDRK, Lawson y Rosenbrock exponenciales según las operaciones requeridas por cada uno.

### M7. Derivadas superiores y series truncadas

1. Definir representación, orden y propagación de series o derivadas, incluyendo la dependencia temporal.
2. Determinar qué expresiones, tablas y funciones del modelo son diferenciables y qué proveedor puede tratarlas. Para campos definidos implícitamente, especificar la diferenciación adicional necesaria.
3. Rechazar operaciones no soportadas; SENS1 no se presenta como diferenciación automática de cualquier orden.

**Demostración mínima:** Taylor de orden bajo en un modelo suave con derivadas conocidas, comprobando convergencia; ampliar después a orden adaptativo.

### M8. Contratos específicos de modelo

| Capacidad | Operaciones adicionales | Primera demostración y límite |
| --- | --- | --- |
| Restricciones / DAE | Residuo `F(t,y,y')`, inicialización consistente, Jacobianos adecuados y diagnóstico | DAE de índice 1 con solución conocida; no prometer índice arbitrario. |
| Restricciones geométricas | Proyección de posiciones/momentos y estructura mecánica declarada | Un problema restringido para SHAKE/RATTLE; no inferir estructura hamiltoniana de un `.din` genérico. |
| Retardos | Historia inicial continua, consulta del pasado e identificación de discontinuidades propagadas | DDE de retardo constante por método de pasos; estado dependiente u otros tipos, después. |
| Ruido | Proceso aleatorio, semilla, incrementos y preservación de trayectoria al rechazar/subdividir | Euler–Maruyama con convergencia fuerte/débil apropiada; Milstein exige operaciones adicionales. |

Son subproyectos separados sobre la infraestructura anterior, no cuatro banderas que vuelven universal a un integrador ODE.

## Familias que se incorporan aprovechando las capacidades

| Familia pendiente | Infraestructura principal | Trabajo que sigue siendo propio de la familia |
| --- | --- | --- |
| Más RK, DIRK, SDIRK, ESDIRK, Gauss, Radau, Lobatto y SSPRK | Generador existente, M1 y M3 cuando corresponda | Coeficientes, estimadores, propiedades y pruebas; TR–BDF2 puede representarse con una formulación RK adecuada. |
| Adams, BDF, NDF y otros multipaso lineales | M1–M3 | Arranque, coeficientes variables, orden, estabilidad y estimador. |
| ROS/ROW/W/RODAS | M1 y M3 | Tablas de etapas, derivadas temporales, estimadores y condiciones sobre el Jacobiano. |
| PGLM general, IMEX y simplécticos particionados | M1, M3 y M4 | Acoplamiento entre particiones y propiedades de cada método. |
| Splitting y composiciones | M1 y M4 | Secuencia, coeficientes, tiempos y error de subflujos. |
| Extrapolación / Bulirsch–Stoer | M1 y avances anidados | Secuencia de subdivisiones, tabla de extrapolación y control de error/orden. |
| SDC | M1, M3 y avances anidados | Nodos de colocación, cuadraturas y barridos de corrección; no es infraestructura Taylor. |
| Multirritmo | M1, M4 y M5 | Acoplamiento rápido/lento y presupuesto de error. |
| Exponenciales | M1 y M6 | Acciones phi y fórmulas particulares de cada método. |
| Taylor | M1 y M7 | Propagación de coeficientes y selección de orden/paso. |
| Selección automática tipo Adams/BDF | M1–M3, con métodos ya validados | Detección, histéresis y conversión/reinicio de memoria; no equivale a recorrer una lista. |
| DAE, DDE y SDE | M8 y sus dependencias | Validación específica del tipo de problema, no solo de la fórmula de avance. |

## Cierre de cada ampliación

- [ ] Contrato, capacidades, límites y compatibilidad escritos antes de habilitar el selector.
- [ ] Ejemplo mínimo persistente en el corpus y generación desde `.d/.ds`.
- [ ] Ejecución equivalente desde `.din` aislado, sin depender del dato ni del catálogo usados para generarlo.
- [ ] Pruebas de recurrencia o solución independiente y del orden de convergencia; no basta una trayectoria visualmente plausible.
- [ ] Casos no autónomos, escalas distintas, último paso, rechazo, rearranque y errores pertinentes a la capacidad.
- [ ] Pruebas específicas de estructura: restricciones, historia, conservación o error estadístico, según corresponda.
- [ ] Regresiones de los motores existentes y medición separada del costo de resolución y de integración.
- [ ] Documentación actualizada con lo efectivamente soportado y lo que aún se rechaza.
- [ ] Revisar cambios concurrentes y versionar entregas acotadas cuando esté autorizado, sin incluir archivos ajenos.

## Secuencia original del primer bloque

Los puntos 1–3 se realizaron; de los puntos 4–5 se entregó el alcance inicial indicado al comienzo del documento. No se da por terminada toda la ampliación de M2–M4.

1. Inventariar las interfaces reales de `Integrador.pm`, `IntegradorGLM.pm`, `PGLM.pm`, `ROS.pm`, `Campo.pm` y `Calcula.pm`, junto con los descriptores de `libdin`; determinar qué ya se puede reutilizar.
2. Escribir el contrato M1 y pruebas de confirmación/descarte con un proveedor controlado, incluyendo efectos de la sesión persistente.
3. Migrar un camino existente sin cambiar su fórmula ni sus decisiones temporales y verificar sus regresiones; extender después a los demás.
4. Continuar con M2 y M3, usando métodos existentes para probar las capacidades. La adaptación GLM ya utiliza el contrato de intentos, la historia y el controlador compartidos; las siguientes ampliaciones deben conservar esa separación.
5. Abordar M4 como primera ampliación de las operaciones matemáticas de avance más allá de los motores actuales.

Ninguna etapa se considera terminada por reconocer su sintaxis. El criterio es capacidad implementada, método de demostración, artefacto autosuficiente y pruebas reproducibles.