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:

Frequenza letta dal contesto dello script Octave.
Debugger Octave con frequenza cinque letta dal contesto.

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:

Risultati logici delle verifiche di due operazioni API.
Risultati dei controlli di disponibilità delle operazioni API.

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.

Richiesta Dataset prima della chiamata.
Pausa prima della lettura del Dataset e controllo dell’identificativo.

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.

Vettori tempo e tensione letti dal Dataset.
Valori e forma dei vettori letti dal Dataset.

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.

Conversione di temperatura osservata nel debugger.
Valori celsius, offset e kelvin nel debugger Octave.

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:

Pausa prima della richiesta di pubblicazione.
Pausa prima della costruzione della richiesta di pubblicazione.

Premi Continue. Nella prova il Job arriva a COMPLETED; il Dataset sintetico è disponibile nella Session e può essere letto dall’esempio della D39.

Pubblicazione completata nella Session di prova.
Debug Job completato dopo la pubblicazione del Dataset sintetico.

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.

Indice del corso

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.

Richiesta Bridge con Dataset intenzionalmente assente.
Argomenti della richiesta al Bridge prima della lettura.

Premi Continue. Nella prova il Job termina con FAILED e segnala Unknown dataset: debug_missing_dataset_example:

Messaggio Unknown dataset dopo la richiesta.
Errore restituito dalla lettura di un Dataset assente.

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

#debugger #GNU Octave #GX-TXT #Python

Altre tappe del progetto

Lascia un commento

Il tuo indirizzo email non sarà pubblicato. I campi obbligatori sono contrassegnati *