# Simplot: guia de uso integrada

Esta guia integra las notas antes situadas en `share/doc/simplot/es/`, contrastadas con el codigo y el corpus actuales. Los originales se conservan en [historico/](historico/README.md). Para instalar, seguir [INSTALL.txt](INSTALL.txt); para usarlo desde Perl con trabajos independientes, consultar [REENTRANCIA.md](REENTRANCIA.md).

## Que hace y que recibe

Simplot produce graficos 2D a partir de tablas existentes y descripciones de los dibujos. Usa Gnuplot, no resuelve el circuito ni necesita SCEPTRE. Las tablas pueden proceder de Simusol, Siru, Calcula, mediciones u otro programa. El procesamiento numerico general se delega a Tabular2; elegir que columnas dibujar no equivale a simularlas.

| Entrada o lenguaje | Uso actual |
|---|---|
| `.simul` o tabla numerica sin instrucciones | Dibujos automaticos: sin metadatos, columnas 2..n contra la primera; con metadatos puede agrupar por magnitud/unidad. No se presupone tiempo. |
| LISTA en RESULTADOS | Nombres de las variables que se quieren representar. |
| RESULTADOS con ternas | Variables, leyendas, magnitudes y unidades de presentacion. |
| PARAPLOT / GRAFICOS / GRAFICOS_ADICIONALES | Fuentes, curvas, ejes, rangos y combinaciones; el subconjunto admitido depende de v1/v2. |
| `.d`, `.ds`, `.ds2` o `.paraplot` | El lector slex genera el DAT grafico antes del dibujo. |
| `.dat` | No necesita el DS original, pero si sus tablas. Si solo contiene OUTPUTS, el lector puede preparar la descripcion grafica sin modificar el DAT. |
| `.caj` y archivos historicos | Compatibilidad v1; casos cubiertos en el corpus. `.hashplot` y todas las variantes antiguas de `.gra` no estan completamente verificadas. |
| Respuestas interactivas | V1: seleccion por terminal; no disponible en v2. |

El lector selecciona automáticamente el modelo estructurado para las órdenes que ya admite. Las órdenes históricas aún no traducidas conservan su recorrido anterior. Contratos: [DAT-PARAPLOT.md](DAT-PARAPLOT.md) y [DAT-SIMPLOT-V2.md](DAT-SIMPLOT-V2.md).

## RESULTADOS: nombre, leyenda, magnitud y unidad

| Pedido | Significado |
|---|---|
| `PX` | Representar PX usando sus metadatos si existen. |
| `PX(Distancia)` | Usar Distancia como leyenda. |
| `PX(Distancia,longitud,m)` | Leyenda Distancia, magnitud longitud y presentacion en metros. |
| `TEMP(Interior,temperatura,tempC)` | Presentar Celsius en v2; requiere conocer la unidad de origen. |

Las variables se separan por comas externas a los parentesis o por renglones. RESULTADOS explicito agrupa series de igual magnitud/unidad; si faltan ambas y no hay metadatos que las distingan, tambien puede agruparlas. La generacion automatica sin instrucciones conserva su comportamiento propio.

En Simplot, RESULTADOS no pide nuevos valores al simulador ni crea columnas ausentes. Los signos de flujos o tensiones son los que trae la tabla: no se deducen del dibujo Dia ni se invierten por el tipo de componente. La primera columna tampoco se convierte automaticamente en TIEMPO. Para un estado unico sin tiempo, usar `simplot --pares estado.simul` o puntos X:Y explicitos.

## PARAPLOT: fuentes y graficos son nombres diferentes

| Ejemplo | Significado |
|---|---|
| `archivo MEDIDAS = medidas.simul` | MEDIDAS identifica una fuente; medidas.simul es su archivo real. |
| `lineas EVOLUCION = MEDIDAS,T:TEMP` | EVOLUCION es un grafico de TEMP contra T. |
| `puntos MUESTRAS = MEDIDAS,1:2` | Indices de columna contados desde 1. |
| `titulo EVOLUCION = Temperatura medida` | Titulo del grafico. |
| `ejes EVOLUCION = Tiempo(s),Temperatura(tempC)` | Rotulos y unidades; v2 pide conversiones a Tabular2. |
| `rangox EVOLUCION = 0,120` | Rango con sintaxis v2. No trasladar sin revisar los rangos con dos puntos de los textos antiguos. |
| `mostrarjuntos PANEL = EVOLUCION,MUESTRAS` | Panel con ambos graficos. |

Las rutas reales respetan mayusculas/minusculas; las tablas se buscan respecto del documento. Las palabras clave se normalizan; **en v2 los identificadores simbolicos si distinguen mayusculas**. La afirmacion antigua de que todos esos nombres son indiferentes a mayusculas no se aplica a v2.

GRAFICOS/PARAPLOT reemplaza RESULTADOS salvo `ANADIR_GRAFICOS=1`; GRAFICOS_ADICIONALES conserva y agrega pedidos. `variables`, `magnitudes`, `guardar`, `nomostrar`, `funcion`, `selec` y `arch_var` pertenecen al recorrido historico: no todo ese lenguaje esta traducido a v2.

## Ejemplo completo de PARAPLOT

Guardar los datos como `medidas.simul` y la descripcion como `medidas.ds` en el mismo directorio. El encabezado declara temperaturas de origen en `tempC`, no solo la etiqueta del grafico.

<!-- ejemplo: medidas.simul -->
```text
# para Siru: sceptrevars variables magnitudes unidades
# T TEMP
# Tiempo,Temperatura
# tiempo,temperatura
# s,tempC
0 20
60 22
120 21
```

<!-- ejemplo: medidas.ds -->
```text
RUN_CONTROLS
PARAPLOT
archivo MEDIDAS = medidas.simul
lineas EVOLUCION = MEDIDAS,T:TEMP
puntos MUESTRAS = MEDIDAS,T:TEMP
titulo EVOLUCION = Temperatura medida
ejes EVOLUCION = Tiempo(s),Temperatura(tempC)
rangox EVOLUCION = 0,120
mostrarjuntos PANEL = EVOLUCION,MUESTRAS
```

```sh
simplot -graf=4 medidas.ds
```

Se generan dos graficos y un panel en un nuevo directorio `simplot-v2-*`; las entradas quedan intactas. Para trasladar el DAT equivalente hay que conservar o ajustar las rutas de sus tablas.

`tests/documentacion.t` extrae estos dos bloques del propio documento, ejecuta la orden y comprueba las tres imagenes PNG y las entradas intactas. No hay una segunda copia del ejemplo que pueda divergir de esta guia.

## Opciones, directorios y archivos producidos

| Caso | Uso |
|---|---|
| Lote sin ventanas | `simplot -graf=4 archivo.ds` |
| Interactivo v1 sin ventanas | `simplot -i -sinventana tabla.simul`; indices como `1:2` o nombres; ENTER termina la seleccion |
| Estado sin tiempo | `simplot --pares --columnas TEMP,TBH,WWW estado.simul` |
| Elegir salida en CLI | `-outdir=/ruta/salida`; en `--pares`, `--directorio /ruta/salida` |
| No clasificar por extension en v1 | `-noclas` |
| Trabajos independientes desde Perl | `SimPlot::Contexto->new(base=>..., directorio=>...)`; salida exclusiva por dibujo |

| Motor | Archivos |
|---|---|
| V1 | PNG/EPS, ordenes `.gnu`, guion de repeticion `.gra` y registros, normalmente clasificados por tipo |
| V2 | Directorio exclusivo con imagenes, tablas exportadas y `graficos.gnu`; PNG y EPS predeterminados si falta `salida`; PNG/EPS/PDF/SVG seleccionables mediante el modelo. `--pares` usa solo PNG por defecto |

`-graf=4` produce archivos sin ventanas, no omite los graficos. `-nokill` es inocuo; `-kill` se rechaza y no debe usarse para cerrar ventanas ajenas. Las ventanas X11 no se prueban automaticamente. Las opciones antiguas de traduccion Dia/SCEPTRE (`scp`, `notrad`, etc.) no son instrucciones de esta guia.

Ejecutar el motor historico en un directorio separado: genera registros y auxiliares. La API por contexto ofrece ese aislamiento sin cambiar el cwd del llamador. No se limpian directorios globales; quien consume las imagenes decide cuando retirar la salida exacta de su trabajo.

## Unidades y referencias

En v2 se usa Tabular2/libunidades/GNU units: `tempC`/`tempF` para temperaturas absolutas, `degC`/`degF` para intervalos y `K` para kelvin. `C` es coulomb y `F` es farad. `gradoC` y `gradosC` no se traducen silenciosamente. La unidad de origen procede de la tabla o de UNIDADES cuando falta, no de cambiar una leyenda.

| Consulta | Documento |
|---|---|
| Instalacion vigente | [INSTALL.txt](INSTALL.txt), [README principal](../README) |
| Contratos y limites | [v1](DAT-PARAPLOT.md), [v2](DAT-SIMPLOT-V2.md) |
| Extractos LaTeX | [manual-extraido/README.md](manual-extraido/README.md) |
| API reentrante | [REENTRANCIA.md](REENTRANCIA.md) |
| Pruebas y corpus | [PRUEBAS.md](PRUEBAS.md), [corpus](../corpus/README.md) |
| Otros graficadores | [REVISION-GRAFICADORES.md](REVISION-GRAFICADORES.md), [PLAN-FUNCIONAL.md](PLAN-FUNCIONAL.md) |