Il primo script Octave: da Celsius a Kelvin
Con Octave Script Workspace è possibile scrivere un programma GNU Octave, salvarlo come sorgente scientifico nella Session, verificarne la richiesta di esecuzione e leggerne i risultati. Questo primo esempio esegue una conversione molto semplice ma verificabile: cinque temperature espresse in gradi Celsius vengono convertite in kelvin (K).
La procedura utilizza GX-TXT DEV112-P005, con il modulo Octave Script Workspace 1.8.3, mantenendo le etichette inglesi effettive della GUI. Il sorgente appare con il tema High Contrast Dark; gli altri controlli possono conservare i colori nativi Tk/ttk.
1. Obiettivo scientifico e requisiti
La scala kelvin è la scala di temperatura termodinamica assoluta. Per convertire una temperatura espressa in gradi Celsius si applica:
T(K) = T(°C) + 273,15
Il risultato si esprime in K, non in “°K”. Useremo cinque valori sintetici: −20, 0, 20, 37 e 100 °C. Non occorrono strumenti, file esterni o Dataset già pubblicati.
Prima di iniziare, aprire GX-TXT e attivare una Session di lavoro. Aprire quindi Octave Script Workspace. Il programma sarà associato alla Session corrente e, dopo l’esecuzione, sarà possibile ritrovarne il Job nello storico.
2. Creare un nuovo sorgente GNU Octave
Nel Viewer selezionare File → New Script. Nelle proprietà scegliere Scope: session, assegnare un identificativo riconoscibile, per esempio celsius_kelvin_five_points, un nome descrittivo e la versione 1.0.0.
Inserire questo programma nell’editor; i commenti sono in lingua inglese:
% Celsius-to-Kelvin conversion: five synthetic scientific measurements.
% This standalone GNU Octave script does not access external files or instruments.
celsius_C = [-20; 0; 20; 37; 100];
kelvin_K = celsius_C + 273.15;
expected_K = [253.15; 273.15; 293.15; 310.15; 373.15];
assert(numel(celsius_C) == 5);
assert(all(abs(kelvin_K - expected_K) < 1e-10));
fprintf('CELSIUS_TO_KELVIN_CONVERSION\n');
fprintf('Point Celsius_degC Kelvin_K\n');
for i = 1:numel(celsius_C)
fprintf('%d %+7.2f %7.2f\n', i, celsius_C(i), kelvin_K(i));
endfor
fprintf('TOTAL_POINTS=%d\n', numel(celsius_C));

Il file utilizza soltanto istruzioni GNU Octave standard. Non impiega chiamate specifiche alle API GX-TXT: in questo esempio il framework fornisce l’editor, il Registry dei sorgenti, il Runner e lo storico dei Job.
3. Comprendere il codice e salvarne la revisione
La riga celsius_C definisce un vettore colonna con cinque elementi. L’istruzione kelvin_K = celsius_C + 273.15 somma la stessa costante a ogni valore, senza bisogno di un ciclo esplicito.
Il vettore expected_K contiene i risultati numerici attesi. Le due istruzioni assert controllano rispettivamente il numero di misure e la differenza fra valori calcolati e attesi, usando una tolleranza numerica di 10⁻¹⁰. Il ciclo for e fprintf servono soltanto a scrivere un riepilogo leggibile nello stdout.
Scegliere File → Save. La modifica non salvata diventa una revisione registrata della sorgente session. Salvare il codice non avvia alcuna esecuzione.
Per dedicare spazio alla lettura delle righe, utilizzare View → Focus source / restore panes e lasciare chiusi i pannelli opzionali che non servono.

Lo Script Registry conserva il documento e la sua revisione. Le eventuali modifiche successive all’editor sono un buffer locale finché non vengono nuovamente salvate.
4. Convalidare la richiesta nel Runner
Aprire Run → Open Script Runner… dalla sorgente registrata. Il Runner mostra l’identità dello script e le opzioni dell’invocazione. Per questa conversione non sono necessari input Dataset, parametri manuali o una richiesta di pubblicazione numerica.
Premere Validate review. La risposta corretta è Review valid. No Job submitted; Run Job performs fresh admission checks.

La distinzione è essenziale: Validate review verifica che la richiesta sia ammissibile, ma non produce risultati. È il successivo pulsante Run Job che invia il programma al supervisore di esecuzione.
5. Eseguire lo script una sola volta
Dopo la convalida scegliere Run Job. GX-TXT esegue lo script salvato tramite GNU Octave e registra un nuovo Job, con il proprio identificativo, stato e copia della revisione effettivamente eseguita.
Aprire Run → Script Jobs Manager…. Nella tabella il Job, dopo aver terminato, deve risultare COMPLETED. Uno stato FAILED richiederebbe invece di esaminare i messaggi di errore e il sorgente, senza assumere che siano stati calcolati tutti i valori.

Non è necessario premere più volte Run Job per ottenere lo stato finale: un Job può attraversare gli stati di preparazione ed esecuzione prima del completamento. Una nuova pressione avvierebbe un’esecuzione distinta.
6. Leggere e interpretare i cinque risultati
Selezionare il Job completato e scegliere Jobs → Open execution details. Nel selettore dei flussi scegliere Program output. Il testo emesso da GNU Octave è:
CELSIUS_TO_KELVIN_CONVERSION
Point Celsius_degC Kelvin_K
1 -20.00 253.15
2 +0.00 273.15
3 +20.00 293.15
4 +37.00 310.15
5 +100.00 373.15
TOTAL_POINTS=5

Riassumendo i valori con la virgola decimale italiana:
| Punto | Celsius (°C) | Kelvin (K) |
|---|---|---|
| 1 | −20,00 | 253,15 |
| 2 | 0,00 | 273,15 |
| 3 | 20,00 | 293,15 |
| 4 | 37,00 | 310,15 |
| 5 | 100,00 | 373,15 |
Le conversioni sono coerenti con la formula iniziale. Il controllo assert garantisce che il programma interrompa l’esecuzione se una differenza eccede la tolleranza specificata. Nel caso illustrato tutti i controlli sono superati e il Job termina con exit code 0.
Dalla finestra dei dettagli è possibile utilizzare Copy entire source per copiare tutto il flusso visualizzato, distinto dalla funzione di copia della sola pagina. In questo primo esperimento la sorgente di output è breve, ma nei Job più complessi può essere suddivisa in pagine.
Attenzione: ciò che si legge qui è lo stdout del Job, non un Dataset scientifico pubblicato. In questa lezione non viene effettuata una pubblicazione canonica di dati.
7. Esportare un file .m utilizzabile anche fuori GX-TXT
Tornare all’editor con il sorgente salvato e scegliere File → Export .m…. Nel selettore file nativo scegliere una cartella adatta e un nome con estensione .m, per esempio celsius_kelvin_five_points.m.

Il comando esporta una copia del sorgente, non l’output del Job. Il file può essere eseguito anche direttamente in GNU Octave, perché contiene soltanto funzionalità standard del linguaggio.
Il file esportato e il sorgente registrato hanno il medesimo contenuto. Una seconda esecuzione indipendente con GNU Octave produce gli stessi cinque risultati testuali. L’esportazione non crea una nuova revisione del Registry né un nuovo Job gestito.
8. Chiudere e riaprire Octave Script Workspace
Dopo aver concluso l’esecuzione, scegliere File → Close. Chiudere la finestra del Viewer non equivale a cancellare il sorgente né il Job completato.
Aprire nuovamente Octave Script Workspace nella medesima Session. Se il sorgente non viene mostrato subito, rendere visibile Registered scripts e selezionare il documento salvato. Quindi ritornare a View → Focus source / restore panes per dare spazio al codice.

L’editor mostra la revisione salvata con gli stessi valori Celsius, la formula e il controllo numerico. Non è necessario ricreare il file o importare nuovamente il programma esportato.
9. Recuperare il Job storico senza eseguirlo di nuovo
Dal Viewer riaperto scegliere Run → Script Jobs Manager…. Nello storico è presente lo stesso Job COMPLETED: non è stato avviato un secondo calcolo per recuperare i dati.

Aprire di nuovo Jobs → Open execution details e consultare Program output. Le cinque righe scientifiche sono ancora disponibili e non hanno cambiato valori.

Questa verifica distingue tre oggetti: il sorgente registrato, il Job che lo ha eseguito e una copia .m esportata. L’esportazione e la riapertura del Viewer non modificano automaticamente i risultati di un Job già concluso.
10. Problemi frequenti e riepilogo
Se il Runner non si apre, verificare che il documento abbia un Script ID, l’ambito corretto e una revisione salvata. Se il risultato sembra mancare, controllare prima lo stato del Job e poi Program output e Program stderr: il messaggio di convalida non è un risultato numerico.
Se l’editor è troppo stretto, utilizzare Focus source; se dopo la chiusura una scheda non compare, ritrovare la sorgente da Registered scripts. Lo Script Jobs Manager permette di recuperare le esecuzioni senza rifarle.
Nel workflow completo abbiamo eseguito una sequenza riproducibile: File → New Script → Save → Validate review → Run Job → Program output → Export .m → Close → Reopen. I cinque valori sono corretti, la sorgente esportata è portabile e il Job gestito rimane consultabile. Nei workflow successivi potremo usare anche le API pubbliche GX-TXT per leggere Dataset strutturati e pubblicare veri risultati scientifici, invece del solo testo stampato.