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));
Nuovo sorgente Octave, con i cinque valori Celsius e le proprietà del documento.
Figura 1 — Nuovo sorgente Octave, con i cinque valori Celsius e le proprietà del documento.

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.

Sorgente salvato e visualizzato nel vero editor High Contrast Dark con spazio sufficiente per il codice.
Figura 2 — Sorgente salvato e visualizzato nel vero editor High Contrast Dark con spazio sufficiente per il codice.

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.

Runner con la richiesta convalidata: non è stato ancora avviato alcun Job.
Figura 3 — Runner con la richiesta convalidata: non è stato ancora avviato alcun Job.

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.

Script Jobs Manager con la prima esecuzione scientifica conclusa nello stato COMPLETED.
Figura 4 — Script Jobs Manager con la prima esecuzione scientifica conclusa nello stato COMPLETED.

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
Program output mostra le cinque temperature convertite e il conteggio finale.
Figura 5 — Program output mostra le cinque temperature convertite e il conteggio finale.

Riassumendo i valori con la virgola decimale italiana:

PuntoCelsius (°C)Kelvin (K)
1−20,00253,15
20,00273,15
320,00293,15
437,00310,15
5100,00373,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.

Nel menu File, Export .m... permette di salvare una copia portabile del sorgente GNU Octave.
Figura 6 — Nel menu File, Export .m… permette di salvare una copia portabile del sorgente GNU Octave.

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.

Il documento viene ritrovato in Registered scripts dopo la riapertura dello Workspace.
Figura 7 — Il documento viene ritrovato in Registered scripts dopo la riapertura dello Workspace.

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.

Lo storico del Job rimane disponibile dopo la chiusura e riapertura del Viewer.
Figura 8 — Lo storico del Job rimane disponibile dopo la chiusura e riapertura del Viewer.

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

Lo storico conserva esattamente lo stesso stdout della conversione dopo la riapertura.
Figura 9 — Lo storico conserva esattamente lo stesso stdout della conversione dopo la riapertura.

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.

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.