Salvare e caricare un Dataset di parametri

Uno script GNU Octave può utilizzare una configurazione di parametri più volte senza doverla ricostruire manualmente. In GX-TXT Script Runner, Save parameters as Dataset salva i valori correnti in un Dataset canonico tipizzato; Load parameters li ricarica in una successiva apertura del Runner, comprese le eventuali definizioni aggiunte soltanto all’invocazione.

Il Dataset di parametri non è il risultato di un calcolo e non è un nuovo script: conserva una configurazione da riesaminare prima di un futuro Run Job. La procedura mostrata utilizza GX-TXT DEV112-P005, Octave Script Workspace 1.8.3, e valori sintetici.

1. Preparare una configurazione mista nel Runner

Partire da uno script Octave salvato che contiene alcune dichiarazioni gxtxt_parameter_declare. Per esempio, possono essere dichiarati un coefficiente numerico, un numero di campioni e una modalità enumerata:

gxtxt_parameter_declare('gain', 'double', 'default', 2.0, ...
                        'min', 0.0, 'max', 5.0);
gxtxt_parameter_declare('samples', 'integer', 'default', 5, ...
                        'min', 1, 'max', 20);
gxtxt_parameter_declare('mode', 'choice', 'default', 'linear', ...
                        'values', {'linear', 'robust'});

Il salvataggio del Source rende questi parametri parte delle definizioni registrate, senza eseguire il codice.

Octave Script Workspace con le dichiarazioni gxtxt_parameter_declare di gain, samples e mode nel sorgente salvato.
Figura 1 — Le dichiarazioni del sorgente salvato sono disponibili nell’Octave Script Workspace.

Aprire Run → Open Script Runner…. I parametri del Source appaiono nella sezione Invocation parameters, inizialmente con i default dichiarati.

Sezione Invocation parameters di Script Runner con i parametri del sorgente ai valori di default.
Figura 2 — I parametri tipizzati dello script vengono mostrati nel Runner.

Impostare gain = 3.5, samples = 9, mode = robust. Nella sezione Additional parameters for this invocation, aggiungere offset_V (double, valore 0.25) e use_reference (boolean, selezionato). Validate review deve confermare i valori. Si ottiene così una configurazione mista di cinque parametri.

Script Runner con gain, samples e mode modificati e i parametri aggiuntivi offset_V e use_reference.
Figura 3 — La configurazione include parametri del sorgente e due parametri aggiunti nel Runner.

2. Indicare il Dataset ID e l’etichetta

Nella sezione Parameter Dataset sono presenti Dataset ID, Save label (optional) e i pulsanti Load parameters e Save parameters as Dataset. Il Dataset ID deve essere una nuova identità canonica valida nella Session.

Se si tenta Save parameters as Dataset lasciando vuoto l’ID, la GUI rifiuta l’operazione e segnala che manca dataset_id.

Sezione Parameter Dataset di Script Runner che rifiuta il salvataggio senza Dataset ID.
Figura 4 — Il salvataggio di un preset richiede un Dataset ID esplicito.

Per l’esempio è possibile usare o17_temperature_preset come Dataset ID e Synthetic temperature calibration settings come etichetta descrittiva. L’etichetta è destinata alla lettura umana; l’ID resta il riferimento canonico per il caricamento.

3. Salvare la configurazione senza eseguire Octave

Premere Save parameters as Dataset. Dopo la validazione, il Runner presenta il messaggio Parameter Dataset … committed. No Job submitted. Ciò conferma la pubblicazione del Dataset di parametri, non l’invio del calcolo scientifico.

Script Runner con il messaggio Parameter Dataset committed. No Job submitted dopo Save parameters as Dataset.
Figura 5 — Il Runner conferma il salvataggio canonico della configurazione.

Il Dataset creato utilizza il contratto gxtxt.script_parameters.v1. GX-TXT memorizza anche l’identità dello script, la sua revisione e l’impronta SHA-256 del sorgente, oltre ai parametri tipizzati e alle definizioni che erano state aggiunte alla singola invocazione.

4. Capire che cosa contiene il Dataset di parametri

Il preset è un Dataset canonico con una sola riga di valori, non una tabella di misurazioni sperimentali. Per la configurazione di esempio la struttura è:

Variabile canonicaTipoValore salvato
p_gainfloat643.5
p_modestringrobust
p_samplesint649
p_offset_Vfloat640.25
p_use_referencebooltrue
preset_markerbooltrue

Le variabili con prefisso p_ rappresentano i parametri salvati. preset_marker è il marcatore che consente al sistema di mantenere una riga canonica anche in casi particolari di valori stringa vuoti. Non è un sesto parametro scientifico dello script.

Le informazioni di provenienza collegano il preset alle dichiarazioni registrate e alle definizioni aggiuntive. Una modifica dell’identità o dello schema dello script non rende automaticamente compatibile un vecchio preset.

5. Evitare di sovrascrivere un Dataset già esistente

Save parameters as Dataset crea un nuovo Dataset, ma non sovrascrive in modo implicito un ID esistente. Ripetendo il salvataggio con lo stesso Dataset ID, il Runner risponde Dataset ID … already exists.

Script Runner che rifiuta il salvataggio con il messaggio Dataset ID already exists.
Figura 6 — Un Dataset ID già presente viene rifiutato senza sostituire il preset.

Per conservare una seconda configurazione, usare un ID nuovo. Per modificare i valori correnti del Runner non è necessario riscrivere il Dataset precedentemente salvato.

6. Riaprire il Runner prima di caricare un preset

Chiudere la finestra con Close, mantenendo lo script registrato. Riaprire Run → Open Script Runner…. Le definizioni temporanee aggiunte soltanto alla precedente invocazione non sono presenti: rimangono i parametri dichiarati nel Source con i loro default.

Script Runner riaperto con i soli parametri del Source ai valori di default, prima di caricare il preset.
Figura 7 — Dopo la riapertura, il Runner mostra i parametri del Source prima di caricare il preset.

Questo non significa che il preset sia andato perso. Il Dataset è stato pubblicato separatamente e può essere richiamato attraverso il proprio ID.

7. Caricare e ripristinare l’intera configurazione

Nel campo Parameter Dataset → Dataset ID, inserire l’identità del preset, quindi premere Load parameters. Il Runner risponde Loaded … Review values before Run Job.

Script Runner dopo Load parameters, con i valori salvati e le righe aggiuntive offset_V e use_reference ricreate.
Figura 8 — Load parameters ricrea i valori del Source e le righe aggiuntive di offset_V e use_reference.

Nel nostro esempio tornano gain = 3.5, mode = robust, samples = 9, offset_V = 0.25 e use_reference = true. Le righe dei parametri temporanei riappaiono con i controlli Edit, Remove e Reset.

Il caricamento controlla la compatibilità delle dichiarazioni, dei tipi e delle variabili canoniche. La riuscita del caricamento non avvia il codice Octave: i valori devono essere comunque riesaminati.

8. Modificare i valori caricati e ricaricarli

Una volta caricati, i valori rimangono modificabili: è possibile, ad esempio, passare a gain = 4.0, offset_V = 0.5 e disattivare use_reference. Validate review controlla la nuova configurazione senza sovrascrivere il preset salvato.

Script Runner con i valori caricati dal preset modificati e convalidati.
Figura 9 — I campi caricati possono essere modificati e convalidati senza alterare il Dataset canonico.

Premendo nuovamente Load parameters con lo stesso ID, il Runner ripristina i cinque valori originariamente salvati. Questa operazione è una sostituzione dei valori nella schermata di preparazione, non una nuova pubblicazione.

Script Runner dopo un nuovo Load parameters, con i cinque valori originali del preset ripristinati.
Figura 10 — Ricaricando il preset vengono recuperati i valori della configurazione canonica.

9. Gestire namespace e revisioni senza usare dati non aggiornati

Il preset nasce nel namespace del produttore dello script. Load parameters può accettare anche un Dataset compatibile collocato in un diverso namespace della stessa Session.

La selezione conserva un riferimento alla revisione del Dataset. Se il Dataset viene spostato o modificato dopo il caricamento, Validate review può rifiutare la preparazione indicando Parameter Dataset changed; load it again.

Validate review che rifiuta la preparazione con Parameter Dataset changed; load it again.
Figura 11 — Un cambiamento nella revisione canonica del preset richiede una nuova verifica.

Per proseguire, utilizzare Load parameters ancora una volta: GX-TXT rilegge il Dataset, ne acquisisce la revisione corrente e lascia riesaminare i valori. Nell’esempio il caricamento da un namespace diverso ha avuto esito positivo dopo la nuova selezione.

Script Runner dopo un nuovo caricamento del preset, con il riferimento aggiornato convalidato.
Figura 12 — Dopo un nuovo caricamento, il Runner può validare il riferimento aggiornato.

10. Rifiutare preset incompatibili e concludere il controllo

Un Parameter Dataset non è una configurazione universale per qualsiasi script. Se viene selezionato in un Runner associato a un altro script registrato, GX-TXT verifica il riferimento e può rifiutare il caricamento con Parameter Dataset has incompatible reference. I parametri del secondo script non vengono modificati parzialmente.

Script Runner di un altro script che rifiuta il preset con Parameter Dataset has incompatible reference.
Figura 13 — Il Runner non applica il preset a uno script incompatibile.

Riaprendo il Runner dello script originale, Load parameters ripristina invece il preset valido. Premere Validate review e controllare il messaggio Review valid. No Job submitted prima di decidere qualunque esecuzione.

Script Runner con il preset compatibile ricaricato e il messaggio Review valid. No Job submitted.
Figura 14 — La configurazione compatibile è stata ricaricata e convalidata, senza inviare un Job Octave.

Da ricordare: Save parameters as Dataset pubblica un Dataset canonico di configurazione; Load parameters ne ricostruisce definizioni aggiuntive e valori tipizzati; Validate review controlla la preparazione, mentre soltanto un successivo Run Job può avviare lo script Octave. Conviene usare un nuovo Dataset ID per ogni configurazione da conservare e ricaricare il preset quando la sua revisione cambia.