# Preparación común de resultados

`preparar-resultados` pertenece al paquete `tabular`. Aplica a una tabla el pedido que Slex interpretó en el DAT. Siru lo invoca antes de publicar resultados, aunque se ejecute con `-nosimplot`; cualquier consumidor de tablas puede usarlo sin cargar Siru, Calcula ni un motor gráfico. El programa coordina la operación en Python; los formatos numéricos y las conversiones se delegan a `interpola --exportar-simul` y Unidades/GNU units.

## Uso

```sh
preparar-resultados --dato caso.dat --tabla caso.simul
cat caso.simul | preparar-resultados --dato caso.dat --tabla -
preparar-resultados --dato caso.dat --tabla caso.simul --formato csv
```

El resultado va a stdout; los errores, a stderr y devuelven estado distinto de cero. No se modifica el archivo de entrada. Sin `--formato csv`, produce SIMUL con nombres, magnitudes y unidades. CSV conserva nombres y números, pero no transporta las filas de metadatos ni la marca de preparación: para encadenar consumidores conservando unidades, usar SIMUL. `--interpola RUTA` o `TABULAR_INTERPOLA` permiten elegir otra instalación.

## Contrato del DAT

La sintaxis `.ds` se define únicamente en [Gramática .ds, §3.9](../../slex/d2datdinc/doc/GRAMATICA.md#39-unidades-y-resultados-comunes-paraplot-para-el-dibujo). Este comando no vuelve a analizar ese lenguaje.

| Campo de `GLOBAL` | Uso |
|---|---|
| `resultados.series` | Lista ordenada de pedidos; cada uno tiene `columna.nombre` o `columna.indice` (desde 1), y opcionalmente `leyenda`, `magnitud`, `unidad`. |
| `unidades_entrada` | Unidad y magnitud de una variable, usadas cuando la tabla no trae esos metadatos. No reemplazan la unidad de una tabla ya calculada. |
| `unidades_calculo` | Magnitudes del modelo ya normalizado. Siru escribe las unidades SI en la tabla antes de entregar sus valores. No se supone que una tabla externa sin metadatos esté en las unidades del resolvedor. |
| `resultados.defectos` | Adaptador de DAT antiguos: declaraciones por nombre o alias exacto. Las contradicciones se rechazan; no se elige por coincidencias parciales de prefijos. |

Sin `RESULTADOS`, conserva las columnas. Con un pedido selecciona y ordena las columnas solicitadas; mantiene delante el tiempo si la primera columna se llama `T`, `TIME` o `tiempo`. No inventa tiempo para un cálculo estático. Una variable inexistente o repetida se rechaza. El nombre original permanece en `sceptrevars`; el nombre solicitado se escribe en `variables`. Las magnitudes son descriptivas: escribir «temperatura» no convierte coulomb en grados.

## Encadenamiento y coordinación con el dibujante

| Metadato | Significado |
|---|---|
| `# RESULTADOS_APLICADOS HASH` | Identifica el contrato ya aplicado a ese bloque. Repetir exactamente el mismo contrato conserva el bloque sin volver a seleccionar ni convertir. |
| `# RESULTADOS_COLUMNAS [1,3]` | La primera columna resultante proviene de la 1 de entrada y la segunda de la 3. Permite adaptar referencias numéricas antiguas. |
| `sceptrevars` / `variables` | Identidad original / nombre solicitado, respectivamente. Se recomienda referenciar columnas por nombre. |

El consumidor recibe una tabla **ya seleccionada**. No puede seguir usando el índice 3 de la tabla anterior si el resultado tiene dos columnas: debe usar la correspondencia o el nombre original. Si PARAPLOT pide una variable excluida por RESULTADOS, debe informar la ausencia, no volver a inventarla ni recuperarla silenciosamente. El dibujante agrupa y dibuja usando los metadatos recibidos; no reaplica las conversiones de RESULTADOS.

La marca se examina por bloque: un bloque preparado no autoriza a omitir los demás. Las conversiones se hacen sobre copias internas; un fallo no escribe un resultado parcial por stdout. Los temporales se eliminan al terminar. No se usan archivos compartidos entre productores y consumidores.

## Pruebas y límites

```sh
python3 tests/t_resultados.py
```

Las pruebas cubren selección, nombres, temperaturas absolutas, prioridad de metadatos, stdin, punto sin tiempo, varios bloques, CSV, errores sin salida parcial e idempotencia por nombres e índices. Siru añade `tests/resultados_comunes.t`; Slex prueba el recorrido real hasta Calcula en `pruebas/probar-unidades-entrada.py` cuando los árboles hermanos están disponibles.

Se aplican los formatos y límites del exportador de Tabular2: filas numéricas finitas y nombres originales sin espacios. La preparación carga la tabla en memoria; no es aún un filtro de memoria acotada para tablas enormes. No evalúa fórmulas nuevas, no hace análisis dimensional simbólico y no interpreta `RESULTADO GRAFICO`, que sigue siendo una propuesta futura.