GX-TXT Python Script Workspace: il primo script scientifico, da Celsius a kelvin
Un esperimento completo e riproducibile: cinque misure sintetiche, un’operazione numerica tramite l’API pubblica GX-TXT, la media delle temperature, uno Script salvato e un Job verificato dal suo output. Non occorrono strumenti di laboratorio né Dataset di input.
1. Che cosa impareremo
In questa esercitazione creiamo un programma Python direttamente in Python Script Workspace, lo salviamo come Script di Session, ne controlliamo la configurazione con Script Runner, eseguiamo un Job e leggiamo lo stdout da Script Jobs. Concludiamo chiudendo e riaprendo la scheda del sorgente. L’intero percorso usa l’interfaccia ordinaria del Viewer.
2. I dati dell’esperimento
Le cinque temperature Celsius sono 18, 20, 22, 21 e 19 °C. Sono valori creati per scopi didattici, non misure strumentali. La conversione è T_K = T_°C + 273.15. La media aritmetica delle cinque misure è 20 °C, quindi la media dopo la conversione deve essere 293,15 K. Kelvin si indica con K, senza simbolo di grado.
| Misura | Temperatura (°C) | Temperatura attesa (K) |
|---|---|---|
| 1 | 18 | 291,15 |
| 2 | 20 | 293,15 |
| 3 | 22 | 295,15 |
| 4 | 21 | 294,15 |
| 5 | 19 | 292,15 |
| Media | 20 | 293,15 |
3. Preparare una Session e aprire l’editor
Aprire una propria Session e, dall’elenco dei Viewer, scegliere Python Script Workspace. In questo caso lo Script è conservato nello scope Session: il suo identificativo è associato al lavoro scientifico corrente. Lo scope User ha una persistenza diversa e non va confuso con il contenuto della Session. Non occorre creare un Project per questo primo esempio.
4. Creare un nuovo sorgente
Nel menu File, scegliere New Script. Si apre una scheda di sorgente non ancora registrata; la creazione della scheda non equivale a un salvataggio. Utilizzare un identificativo semplice, ad esempio w01_temperature_kelvin, e un nome leggibile come Temperature conversion C to K. La figura mostra il comando originale.

5. Identificativo, versione e descrizione
Nelle proprietà dello Script impostare Script ID, Script name, Version e Description. Per questo esercizio la versione semantica è 1.0.0. La versione scelta dall’autore e la revisione assegnata dal Registry sono concetti distinti: salvando di nuovo il sorgente si crea una revisione successiva senza dover incrementare automaticamente la versione semantica. Il codice resta Python e lo scope resta Session.
6. Scrivere nell’editor ad alto contrasto
Inserire il programma nel riquadro centrale. La modalità High Contrast Dark rende il testo del codice chiaro su sfondo scuro e applica la colorazione sintattica; non è necessario aprire Explorer, Snippets o Debugger durante la scrittura. La modifica del buffer è visibile immediatamente, ma non sostituisce Save.

7. Il programma completo
Copiare il programma seguente nella scheda. I commenti sono in inglese e il sorgente non richiede file esterni.
# First Python example: five synthetic temperature measurements.
# Use the public GX-TXT numerical service for vector-plus-scalar arithmetic.
from gxtxt import gxtxt_api_call, gxtxt_api_require
gxtxt_api_require("NUMERIC_API_v1@1:math.numeric")
celsius = [18.0, 20.0, 22.0, 21.0, 19.0]
vector_c = {"kind": "vector", "value": celsius}
offset_k = {"kind": "scalar", "value": 273.15}
response = gxtxt_api_call(
"NUMERIC_API_v1", "array_binary", ["add", vector_c, offset_k]
)
kelvin = [
float(value.item() if hasattr(value, "item") else value)
for value in response["values"]
]
if len(kelvin) != 5:
raise ValueError("Expected five converted temperatures")
for c, k in zip(celsius, kelvin):
print(f"C_TO_K {c:.2f} {k:.2f}")
mean_kelvin = sum(kelvin) / len(kelvin)
print(f"MEAN_K {mean_kelvin:.2f}")
8. Importare il client pubblico GX-TXT
L’istruzione from gxtxt import gxtxt_api_call, gxtxt_api_require importa due funzioni rese disponibili dallo Script Bridge del runtime gestito. gxtxt_api_require dichiara un requisito, non installa un pacchetto. gxtxt_api_call invoca un’operazione esposta da un modulo tramite un contratto pubblico. Queste funzioni non devono essere sostituite con chiamate a procedure interne del CORE.
9. Il requisito NUMERIC_API_v1
gxtxt_api_require("NUMERIC_API_v1@1:math.numeric") richiede il contratto pubblico NUMERIC_API_v1, versione 1, con proprietario math.numeric. È un prerequisito all’esecuzione: se il runtime non rende disponibile l’API richiesta, non si deve proseguire fingendo di avere calcolato i dati. Lo Script Runner conserva l’identità del sorgente e la dipendenza verificata per il Job.
10. Preparare operandi numerici tipizzati
L’API array_binary riceve due operandi: vector_c è un vettore di cinque valori finiti; offset_k è uno scalare pari a 273.15. Ogni operando è descritto con le chiavi kind e value. Nelle operazioni di somma, uno scalare può essere applicato a ciascun elemento del vettore. I valori sono numerici; le unità non vengono dedotte automaticamente dal servizio.
11. Invocare l’operazione array_binary
La chiamata gxtxt_api_call("NUMERIC_API_v1", "array_binary", ["add", vector_c, offset_k]) seleziona l’operazione add nel servizio numerico. Gli argomenti sono un elenco ordinato: nome dell’operazione, operando sinistro e operando destro. Il risultato è una struttura dalla quale recuperiamo la chiave values. È il programma dell’utente a stabilire che 273.15 rappresenta il corretto offset fisico Celsius→kelvin; l’API esegue l’aritmetica, non inventa una conversione di unità.
12. Perché estrarre uno scalare da ogni elemento
Il trasporto numerico può fornire valori come scalari o come contenitori NumPy a un solo elemento. L’espressione value.item() if hasattr(value, "item") else value recupera lo scalare quando è disponibile il metodo item, e poi lo trasforma in float. Così il codice non tenta di convertire direttamente un array multidimensionale in un singolo numero. Il passaggio è utile anche per evitare avvisi di deprecazione nelle versioni moderne di NumPy.
13. Controllare cardinalità e media
Il controllo len(kelvin) != 5 interrompe l’esecuzione se non vengono restituiti cinque risultati: un valore di lunghezza inattesa non dovrebbe essere accettato silenziosamente. Il ciclo zip(celsius, kelvin) affianca ogni ingresso alla conversione corrispondente. Infine, sum(kelvin) / len(kelvin) calcola la media aritmetica. Il formato :.2f rende visibili due cifre decimali senza cambiare i dati originali.
14. Salvare il sorgente nel Registry
Usare File → Save. Il salvataggio registra identità, contenuto e revisione dello Script: non esegue il programma e non crea un Dataset. La figura mostra il sorgente salvato. Prima di avviare un Job è importante che il buffer non contenga modifiche non salvate; il Runner deve poter associare l’esecuzione a uno snapshot definito.

15. Aprire Script Runner
Dal menu Run scegliere Open Script Runner…. La finestra identifica lo Script scelto, la sua versione, la revisione e l’impronta del sorgente. Per questo esperimento non ci sono Dataset di input, parametri dichiarati o file da leggere. Le sezioni avanzate del Runner restano disponibili, ma non vanno riempite con valori non richiesti.

16. Input, parametri e output opzionale
Il pannello dei Dataset di input può rimanere vuoto: le temperature sono definite nel codice Python. Non serve nemmeno un Parameter Dataset, perché non sono presenti dichiarazioni di parametri di invocazione. Lasciare vuoto l’Output Dataset ID. Questo Job scriverà un resoconto testuale in Program output; stampare del testo non equivale a pubblicare un Dataset canonico.
17. Validare senza eseguire
Premere Validate review. Il messaggio Review valid. No Job submitted significa che la configurazione è stata esaminata, ma nessun Job è stato ancora avviato. Il controllo di ammissione viene ripetuto al momento della vera esecuzione. È normale distinguere il salvataggio del codice, la validazione e il successivo Job: sono tre eventi differenti.

18. Avviare il Job Python
Solo dopo aver verificato revisione e configurazione premere Run Job. GX-TXT invia uno Job gestito e ne conserva lo stato e l’identità. L’avvio non garantisce automaticamente il successo: bisogna attendere uno stato terminale e controllare eventuali errori. Non è necessario aprire il Debugger per questo calcolo breve.
19. Verificare lo stato in Script Jobs
Aprire la vista Script Jobs Manager e individuare l’esecuzione dello Script. Lo stato atteso è COMPLETED, con codice di uscita 0. Un Job fallito o annullato non fornisce la stessa evidenza di completamento. La lista può contenere altri Job storici: scegliere quello associato alla revisione e all’identità del sorgente effettivamente eseguito.

20. Leggere Program output
Aprire Job Details e selezionare lo stream Program output. Le cinque righe C_TO_K indicano il valore Celsius e quello in kelvin; la riga MEAN_K è la media. Program stderr è un flusso distinto da stdout: non interpretare la presenza di uno stato COMPLETED come prova che entrambi siano sempre vuoti o corretti.

21. L’output atteso e la prova numerica
Il testo dell’esecuzione corretta è:
C_TO_K 18.00 291.15
C_TO_K 20.00 293.15
C_TO_K 22.00 295.15
C_TO_K 21.00 294.15
C_TO_K 19.00 292.15
MEAN_K 293.15
Confrontare ognuno dei sei valori attesi con il proprio Job. Un numero corretto a schermo deve comunque riferirsi a uno Script salvato e a un’esecuzione conclusa. Qui non viene generato alcun nuovo Dataset: il prodotto del Job è un log testuale.
22. Sorgente salvato e snapshot eseguito
Il Registry conserva lo Script corrente e le sue revisioni; il Job conserva la propria copia immutabile del codice eseguito. Una successiva modifica dello Script non riscrive retroattivamente il sorgente dei Job già eseguiti. La versione semantica (1.0.0) e la revisione (incrementata a ogni nuovo salvataggio) aiutano a interpretare correttamente la provenienza del risultato.
23. Chiudere e riaprire la scheda
Una volta salvato e terminata l’esecuzione, chiudere la scheda del sorgente, non eliminare lo Script dal Registry. Riaprire quindi lo Script dalla navigazione degli Script registrati. Il testo dovrebbe tornare identico e senza modifiche pendenti. Si può infine ripristinare il normale spazio di lavoro con l’editor centrale in evidenza.

24. Errori comuni e conclusione
Se Run Job non è disponibile, verificare che esista una Session attiva, che lo Script sia salvato e che il controllo del Runner sia valido. Se la richiesta numerica fallisce, controllare l’identificativo NUMERIC_API_v1, il proprietario math.numeric, i tipi degli operandi e la presenza di cinque valori finiti. Un avviso NumPy sugli array convertiti in scalari si risolve estraendo prima l’elemento, come fa item() nel programma. Infine, non scambiare lo stdout con un Dataset pubblicato: la pubblicazione numerica richiede operazioni esplicite affrontate in un esperimento successivo.
Abbiamo completato il percorso New Script → Edit → Save → Script Runner → Validate review → Run Job → Jobs → Program output → Close/Reopen con risultati numerici controllabili e un sorgente riutilizzabile.