GX-TXT Python Script Workspace: dal sorgente al risultato scientifico

Una guida conclusiva per verificare un lavoro Python prima di archiviarlo, condividerlo o riutilizzarlo: controllo del sorgente, input e parametri, esecuzione, output, Dataset canonici e debugger. Le immagini mostrano le stesse funzioni esaminate nei capitoli precedenti.

1. Che cosa deve essere riproducibile

Un calcolo scientifico è riproducibile quando si possono ricostruire l’identità dei dati di ingresso, la versione esatta del programma, i parametri effettivi, l’esecuzione e il risultato. Nel Python Script Workspace di GX-TXT questi elementi non coincidono: Script o Project, Job, Dataset e Session hanno ruoli distinti. Il log del programma e il Dataset canonico non sono intercambiabili.

2. Scegliere correttamente Session e Scope

Un sorgente di scope User è distinto da quello collegato a una Session, anche quando presenta lo stesso nome breve. Le esecuzioni scientifiche descritte qui richiedono la Session appropriata e un sorgente registrato. Prima di salvare o eseguire verificare lo scope visualizzato nella GUI. Non attribuire automaticamente a una Session dati provenienti da un’altra.

3. Controllare l’editor e lo stato del sorgente

Usare Python Script Workspace con un’area di codice ampia. Il tema High Contrast Dark rende riconoscibili testo Python, selezione e riga corrente; le barre e i dialoghi nativi possono conservare il loro aspetto chiaro. Prima di iniziare un Job, assicurarsi che non ci siano modifiche pendenti e che il file mostrato corrisponda alla versione salvata.

Python Script Workspace con editor dark focalizzato sul codice originale.
Figura 1. L’editor Python lascia spazio al codice e conserva il suo reale tema High Contrast Dark.

4. Identità, versione, revisione e SHA

Stable ID identifica uno Script o Project nel relativo scope; la Version semantica è una descrizione della sua evoluzione; la revision del Registry identifica uno specifico salvataggio. L’impronta SHA-256 consente di verificare che il contenuto realmente eseguito coincida con il sorgente salvato. Nei Project multifile la revisione rappresenta un insieme coerente di file, non un unico .py arbitrario.

5. Salvare prima di eseguire

Scegliere File → Save per uno Script singolo o File → Save All per un Project con più file. Il salvataggio non crea automaticamente un Job e non produce un Dataset. Dopo una modifica, ripetere il salvataggio e verificare la nuova revisione; l’eventuale Job precedente conserva il suo snapshot storico e non cambia retroattivamente.

6. Collegare un Dataset e conservarne la revisione

In Script Runner, la sezione Inputs and output permette di usare Add input Dataset. Controllare namespace, Dataset ID, alias semantico, etichetta e revisione. L’alias è il nome con cui il codice ritrova il Dataset, mentre l’ID canonico ne identifica la registrazione. Se il Dataset sorgente viene aggiornato dopo la selezione, Validate review può richiedere una nuova selezione della revisione corrente.

Script Runner con collegamento a Dataset canonico e alias measured.
Figura 2. L’input del Runner si associa a namespace, Dataset ID, alias e revisione.

7. Dichiarare e rivedere i parametri tipizzati

Un parametro dichiarato con gxtxt_parameter_declare può avere tipo, valore predefinito, limiti e descrizione. Nel Runner si sceglie il valore effettivo per la singola invocazione. Cambiare un parametro nel Runner non equivale a modificare il sorgente. Se sono presenti valori manuali, controllare anche eventuali conflitti con i parametri dichiarati nel programma.

Script Runner Python con parametri tipizzati dal sorgente salvato.
Figura 3. I parametri dichiarati nello Script vengono presentati come valori tipizzati nel Runner.

8. I confini delle API Python pubbliche

Il client pubblico gxtxt permette al codice di ottenere il contesto del Job e chiamare le API disponibili. Ad esempio, nell’esercitazione W02 è stata usata questa sequenza essenziale:

from gxtxt import gxtxt_api_call, gxtxt_api_require, gxtxt_context

gxtxt_api_require("CANONICAL_DATASET_API_v2@2")

context = gxtxt_context()
dataset_id = context["inputs"]["measured"]["dataset_id"]
metadata = gxtxt_api_call(
    "CANONICAL_DATASET_API_v2", "describe", [dataset_id]
)

gxtxt_api_require verifica la dipendenza dall’API richiesta; gxtxt_context dà accesso a input e parametri della specifica esecuzione; describe legge lo schema del Dataset. Le operazioni di lettura, calcolo e pubblicazione rimangono separate. Non usare moduli interni del CORE come scorciatoie.

9. Validate review non è Run Job

Il pulsante Validate review controlla la configurazione. Un messaggio come Review valid. No Job submitted non significa che il programma sia stato eseguito. Prima di premere Run Job ricontrollare la revisione dello Script, la Session, gli input, i parametri e l’eventuale ID di output. Questa distinzione impedisce di confondere una configurazione ammissibile con un risultato già ottenuto.

Python Script Runner in stato Review valid, No Job submitted.
Figura 4. Validate review verifica la configurazione, ma non invia un Job.

10. Controllare lo stato terminale del Job

Dopo Run Job, aprire Script Jobs Manager. Un Job QUEUED o RUNNING non è concluso; un Job COMPLETED con exit code zero segnala la conclusione normale; FAILED e CANCELLED hanno significati diversi. Verificare sempre l’identità e la revisione eseguita, non limitarsi a leggere l’ultima riga di output.

11. Separare stdout, stderr e diagnostica

In Job Details scegliere il flusso adatto: Program output contiene i messaggi scritti su stdout, Program stderr raccoglie i messaggi del processo su stderr, mentre i log diagnostici sono informazioni di esecuzione distinte. Per un Job con flussi lunghi, le pagine visualizzate non sono l’intero contenuto: i comandi di copia/esportazione completa sono separati dalle funzioni che selezionano soltanto la pagina corrente.

Job Details Python con flusso Program stderr selezionato.
Figura 5. Program stderr è uno stream diverso dal normale Program output.

12. Primo controllo scientifico: Celsius e kelvin

Nell’esercitazione W01 il programma ha elaborato cinque temperature sintetiche 18, 20, 22, 21, 19 °C applicando K = °C + 273.15. I cinque valori in kelvin sono 291,15, 293,15, 295,15, 294,15 e 292,15. La media aritmetica è 293,15 K. Il Job definitivo ha terminato con successo e lo stdout conserva tutte le righe del calcolo.

Program output Python con cinque risultati in kelvin e media 293,15 K.
Figura 6. Il Job W01 riporta cinque conversioni Celsius–kelvin e la media 293,15 K.

13. Secondo controllo scientifico: calibrazione additiva

Nell’esercitazione W02 un Dataset canonico di temperature 18, 20, 22.5, 21, 19 °C è stato letto tramite CANONICAL_DATASET_API_v2. Il parametro tipizzato correction_degC era impostato a +0,75 °C. Il calcolo ha prodotto 18,75, 20,75, 23,25, 21,75 e 19,75 °C, con media 20,85 °C. Questi numeri derivano da dati didattici sintetici, non da misure strumentali.

Program output Python con temperature corrette e Dataset canonico pubblicato.
Figura 7. Il Job W02 mostra la correzione +0,75 °C e il nuovo Dataset di risultato.

14. Il Dataset scientifico non nasce dal solo print

print() scrive nel log, ma non crea una tabella canonica. W02 ha pubblicato esplicitamente un Dataset table.generic con due variabili, raw_c e corrected_c, entrambe di tipo float64 e unità degC. Il processo di pubblicazione usa DATASET_PUBLICATION_API_v2, con apertura del writer, dichiarazione di dimensione e variabili, aggiunta dei valori e finalizzazione. La provenienza conserva il collegamento al Dataset iniziale.

15. Verificare l’output richiesto e quello pubblicato

L’Output Dataset ID del Runner identifica una richiesta, non la certezza di una pubblicazione. In Job Details distinguere Requested output e Committed published Datasets. Un Job può terminare normalmente senza pubblicare un Dataset, se lo Script non effettua una finalizzazione. Prima di riutilizzare il risultato rileggere schema, righe, tipi, unità e valori dal catalogo canonico.

Job Details con Requested output e Committed published Datasets.
Figura 8. I dettagli del Job distinguono l’output richiesto dai Dataset effettivamente pubblicati.

16. Project Python: ingresso, helper e revisione unica

Nel lavoro W03 main.py importava calibrate da helpers/numeric.py, mentre helpers/__init__.py identificava il package. Le letture sintetiche [1, 4, 9], moltiplicate per due, hanno restituito [2, 8, 18] e la somma 28. L’intero Project è stato salvato con Save All; il Job ha conservato lo snapshot di tutti e tre i file. Un controllo del solo main.py non sarebbe sufficiente per certificare il calcolo.

17. Breakpoint e Call Stack: il punto di esecuzione è unico

Nel debugger nativo il tasto F9 inserisce un breakpoint eseguibile nel file desiderato. Start Debug, Continue, Step Into, Step Over e Step Out controllano la vera esecuzione del Job Python. Call Stack permette di selezionare un frame chiamante e osservare altri valori locali, senza cambiare la posizione dell’interprete. Le schede dei file helper sono quindi parte della normale navigazione del Project.

Debugger Python con breakpoint F9 e freccia nella funzione calibrate.
Figura 9. Il debugger sospende un Project Python alla riga eseguibile di una funzione helper.

18. Pause, Stop e sicurezza dell’esecuzione

Durante RUNNING, il comando Pause può sospendere un Job Python; la conferma è lo stato effettivo PAUSED, non il solo click. La prova W03 ha raggiunto controlled_spin alla riga 12; il successivo Stop ha prodotto CANCELLED. Il caso è distinto dal Job scientifico completato con somma 28. Se il margine dei breakpoint rimane disabilitato dopo la chiusura del debugger, chiudere e riaprire il Project tramite i normali menu: il contenuto salvato viene conservato.

Debugger Python con vera sospensione asincrona nella funzione controlled_spin.
Figura 10. Pause durante RUNNING sospende una funzione Python realmente in esecuzione.

19. Controlli prima di condividere il lavoro

Prima di archiviare o condividere una procedura, verificare che il sorgente sia salvato e privo di modifiche pendenti; che il Project includa tutti i file richiesti; che Session, input, alias, parametri e revisioni siano quelli voluti; che il Job abbia lo stato appropriato; che stderr e log siano stati consultati; e, quando è previsto un Dataset, che il risultato sia stato realmente pubblicato e riletto con tipo, unità e provenienza corretti. La presenza di una schermata rassicurante non sostituisce questi controlli.

20. Percorso di studio e limite delle esercitazioni

I capitoli P01–P14 spiegano l’interfaccia, l’editor, i Project e le note; P15–P20 trattano Runner, Dataset, parametri e Jobs; P21–P24 il debugger; P25–P29 cronologia, output, pubblicazioni e assistenza. W01–W03 mostrano le tre esercitazioni scientifiche complete. Tutti gli esempi numerici di questa serie sono sintetici: non dimostrano l’accuratezza metrologica di strumenti reali e non sostituiscono una valutazione delle incertezze sperimentali.