Debugger GX-TXT · Modulo 07 — Dati scientifici e API GX-TXT
Il debugger di GX-TXT · Corso in 10 moduli
Quando il calcolo dipende dalla Session, il codice visibile è solo una parte della diagnosi. Controlliamo il parametro ricevuto, l’API e l’operazione disponibili, l’identità delle variabili e le unità. Seguiamo quindi il passaggio da un Dataset letto a un risultato pubblicato, verificando cosa è avvenuto a ogni confine.
Scarica gli esempi Python e GNU Octave (ZIP). Estrai tutte le cartelle dell’archivio e mantieni insieme i file degli esempi multifile.
D37 — Contesto e parametri
Uno script gestito da GX-TXT può ricevere parametri attraverso il proprio contesto. Prima di attribuire un risultato inatteso a una formula, controlliamo quale valore è arrivato allo script.
Frequenza e periodo
Importa e registra period.m in Octave
Scripts. Lo script dichiara un parametro frequency con
valore predefinito 5 Hz, legge ctx.parameters.frequency,
verifica che sia positivo e calcola
period = 1 / frequency.
Imposta un breakpoint sulla verifica
assert(frequency > 0, ...) e avvia il debug. Nella prova
il pannello mostra frequency = 5 e ctx come
struttura:
Con il valore predefinito il periodo atteso è 0,20 s. La
dichiarazione ammette valori fino a zero incluso, ma la formula richiede
frequenza positiva: per questo lo script controlla esplicitamente
frequency > 0 prima di dividere. ctx è un
riepilogo di contesto; per osservare il parametro con chiarezza lo
script lo assegna alla variabile intermedia frequency.
La prova di debug usa il valore disponibile nel contesto del Job. Per un’esecuzione con un diverso valore, usa il Runner e controlla i parametri proposti prima dell’avvio; confronta le impostazioni effettive del Job con la revisione dello script.
Esercizio
Quale periodo ti aspetti con 2 Hz? Perché il valore zero va gestito prima della divisione?
Soluzione ragionata
Il periodo è 0,5 s. A zero la formula 1 / frequency non
rappresenta un periodo finito valido per questa analisi, quindi lo
script lo rifiuta.
Indice del corso · Lezione precedente
D38 — Disponibilità di API e operazioni
Un nome API riconosciuto non basta a garantire che una specifica operazione sia disponibile nella versione e nel contesto in uso. Prima di diagnosticare un calcolo, verifichiamo i requisiti dichiarati.
Controllare due operazioni
Importa e registra api_check.m. Lo
script richiede CANONICAL_DATASET_API_v2@2 e
NUMERIC_API_v1@1, poi controlla le operazioni
read_range e statistics con
gxtxt_api_has_operation.
Imposta un breakpoint sulla stampa, dopo i due controlli, e avvia il
debug. Nella copia usata per la prova, has_read e
has_statistics sono entrambi logici con valore 1:
Continua per stampare READ_RANGE 1 e
STATISTICS 1. Se un’operazione fosse assente, lo script la
segnalerebbe con l’asserzione; se mancasse già un requisito API,
gxtxt_api_require potrebbe fermarsi prima dei due
controlli. Verifica sempre il contratto e la versione effettiva: un
esito in questa Session non garantisce lo stesso inventario su tutte le
installazioni.
Il pannello può mostrare anche variabili dell’ambiente di esecuzione o riepiloghi limitati. Per la diagnosi osserva i due valori espliciti preparati dallo script.
Esercizio
Che cosa significa has_read = 1? Significa anche che un
Dataset con qualunque ID esiste?
Soluzione ragionata
Indica che l’operazione richiesta risulta disponibile nel contesto della prova. Non prova che un particolare Dataset o una variabile esistano: occorre controllare anche gli input della chiamata.
Indice del corso · Lezione precedente
D39 — Lettura di Dataset e variabili
Quando un’analisi legge dati da GX-TXT, controlla il Dataset, i Variable ID richiesti, il numero di elementi e le unità prima di interpretare il risultato.
Preparare i dati
In una Session di prova crea il Dataset sintetico
debug_sensor_series con publish_series.m,
seguendo la D41. La
serie contiene tempi 0, 1, 2 s e tensioni
1, 2, 3 V. L’ID è create-only: per ripetere la
pubblicazione usa una Session nuova o cambia l’ID in entrambi gli
script.
Importa e registra read_series.m.
Imposta un breakpoint sulla chiamata read_range e avvia il
debug. Prima della chiamata puoi verificare
dataset_id = debug_sensor_series, gli ID
time_s e voltage_v, l’inizio 0 e il numero
richiesto 3.
Premi Step Over per completare la chiamata, poi
altri due passi per estrarre i vettori dalla struttura restituita.
Scorri Locals / Globals: nella prova time_s e
voltage_v hanno forma 3 1 e valori
rispettivamente 0 1 2 e 1 2 3.
L’asserzione successiva controlla che entrambi abbiano tre elementi. I nomi delle variabili e le unità devono essere coerenti con il Dataset pubblicato; un’operazione disponibile, da sola, non garantisce che un ID richiesto sia corretto.
Esercizio
Perché il controllo delle dimensioni è utile prima di confrontare tempo e tensione?
Soluzione ragionata
Aiuta a rilevare letture incomplete o vettori di lunghezza incompatibile. Non dimostra da solo che unità e associazione fra campioni siano corrette: anche quelle vanno verificate.
Indice del corso · Lezione precedente
D40 — Trasformazioni e unità
Un valore numerico può essere calcolato correttamente e interpretato male se perdiamo l’unità. Prima di una trasformazione, rendiamo espliciti grandezza, unità di ingresso e unità del risultato.
Seguire una conversione
Usa temperature_fixed.m
nella Session di prova. Lo script parte da celsius = 20,
aggiunge offset = 273.15 e ottiene
kelvin = 293.15. Metti un breakpoint sulla stampa e avvia
il debugger.
Nella prova il pannello mostra i tre scalari. Il valore numerico
293.15 va interpretato come kelvin perché lo specificano la
formula, i nomi e la stampa: il tipo numerico da solo non contiene
automaticamente questa spiegazione.
Quando questi valori provengono da un Dataset, verifica anche unità e
Variable ID dichiarati alla fonte. Nella D39, time_s e
voltage_v rappresentano grandezze diverse: non basta che i
vettori abbiano la stessa lunghezza per poterli scambiare.
Esercizio
Se interpreti 20 °C come 20 K senza conversione, il programma deve necessariamente dare un errore di sintassi?
Soluzione ragionata
No. Entrambi sono numeri validi; è l’interpretazione fisica a essere errata. Occorrono unità esplicite e controlli con valori attesi indipendenti.
Indice del corso · Lezione precedente
D41 — Pubblicazione e creazione di risultati
Un calcolo in memoria e la pubblicazione di un Dataset sono due momenti distinti. Un breakpoint prima della chiamata consente di controllare gli input prima che la Session riceva un risultato.
Preparare dati sintetici
Usa una Session di prova e importa publish_series.m in Octave Scripts.
Il codice prepara tre tempi 0, 1, 2 s e tre tensioni
1, 2, 3 V. La richiesta assegna l’ID
debug_sensor_series e le variabili time_s e
voltage_v.
Il Dataset è create-only: se esiste già, usa una nuova Session o cambia l’ID nello script e in quelli che lo leggono. Salva prima della prova.
Fermarsi prima della pubblicazione
Imposta un breakpoint sulla costruzione di request, dopo
la definizione dei due vettori. Avvia il debug e verifica i dati nel
sorgente e nei riepiloghi disponibili. La richiesta e la chiamata a
publish_series devono ancora essere eseguite:
Premi Continue. Nella prova il Job arriva a
COMPLETED; il Dataset sintetico è disponibile nella Session
e può essere letto dall’esempio della D39.
Se ripeti l’esecuzione con lo stesso ID nella stessa Session, non presumere che la pubblicazione sovrascriva il Dataset: scegli un ID nuovo o una Session di prova nuova.
Esercizio
Il programma è in pausa prima della costruzione della richiesta. Il Dataset è già stato pubblicato da questa esecuzione?
Soluzione ragionata
No. La chiamata a publish_series viene dopo la riga in
pausa. Dopo Continue, controlla l’esito del Job e verifica il Dataset
nella Session.
D42 — Errori del Bridge e del programma
Una chiamata attraverso Script Bridge può fallire perché la richiesta non corrisponde ai dati disponibili. Il messaggio va interpretato insieme agli argomenti preparati dallo script, senza confonderlo con un errore di indicizzazione locale.
Un Dataset intenzionalmente assente
In una Session di prova che non contenga
debug_missing_dataset_example, importa missing_dataset.m. Lo script
richiede un ID volutamente inesistente tramite
CANONICAL_DATASET_API_v2/read_range. Metti un breakpoint
sulla chiamata e avvia il debug.
Premi Continue. Nella prova il Job termina con
FAILED e segnala
Unknown dataset: debug_missing_dataset_example:
Il messaggio identifica l’operazione e l’ID richiesto. La traccia attraversa anche funzioni del Bridge: per trovare l’errore nel nostro esempio, torna agli argomenti della chiamata nel sorgente. L’indicazione last paused si riferisce all’ultima fotografia osservata, non a variabili vive dopo il fallimento.
Confronta la D35, dove l’errore era un indice Octave fuori intervallo su un vettore già in memoria. Qui la richiesta punta deliberatamente a un Dataset assente: non è un difetto del framework. Per una lettura valida prepara la serie della D41 e usa lo script della D39.
Esercizio
Un messaggio dice che un Dataset è sconosciuto. Che cosa controlli prima di modificare la formula numerica?
Soluzione ragionata
Controlla Session aperta, esistenza del Dataset e corrispondenza esatta dell’ID richiesto. Poi verifica le variabili e i parametri della lettura.
Indice del corso · Lezione precedente
Per ritrovare la stessa situazione in un’altra esecuzione occorre identificare anche sorgente, revisione, Session e risorse del progetto.
Modulo 06 precedente · Indice dei 10 moduli · Modulo 08 successivo
Altre tappe del progetto
- Debugger GNU Octave in GX-TXT: breakpoint, variabili e API pubbliche
- Debugger GX-TXT · Modulo 09 — Casi pratici integrati
- Debugger GX-TXT · Modulo 10 — Autonomia e progetto conclusivo
- Debugger GX-TXT · Modulo 05 — Python: casi fondamentali
- Debugger GX-TXT · Modulo 01 — Fondamenti e primo Debug Job
- Debugger GX-TXT · Modulo 02 — Breakpoint e sorgente