GX-TXT — Guida completa agli script Octave/MATLAB nel viewer dedicato

Indice

1. Scopo e modello mentale

Il modulo analysis.octave_script permette di scrivere ed eseguire programmi .m direttamente dentro GX-TXT senza trasformare subito il lavoro in un plugin di analisi completo. È pensato per calcoli di ricerca, esplorazioni numeriche, prototipi scientifici e procedure che devono accedere ai dati della Sessione tramite API pubbliche.

Il principio centrale è semplice: uno script non deve conoscere la struttura privata della Sessione. Non deve costruire percorsi verso file Dataset, leggere registri interni o accedere a namespace Tcl privati. Deve invece:

1. ottenere il contesto con gxtxt_context();
2. scoprire le API disponibili con gxtxt_api_list() e gxtxt_api_describe();
3. verificare i requisiti con gxtxt_api_require();
4. leggere o modificare dati attraverso gxtxt_api_call();
5. pubblicare risultati tramite le API di Dataset, Plot o Sessione previste dal framework.

2. Architettura del sistema di scripting

La catena di esecuzione è composta da quattro elementi distinti.

La registrazione di uno script non è un semplice collegamento a un file. L’identità pubblica è un riferimento come session:mio_script oppure user:mio_script. Per gli script registrati, il percorso fisico non costituisce l’identità.

3. Octave Script Workspace

Con una Sessione aperta:

1. abilitare il modulo Octave Script;
2. aprire Viewers → Octave Script Workspace;
3. selezionare New;
4. scegliere scope Session o User;
5. assegnare uno Script ID stabile, un nome e una descrizione;
6. scrivere il sorgente e salvarlo.

L’editor fornisce numeri di riga, syntax highlighting, undo/redo, ricerca, vai-a-riga, UTF-8, import/export .m, template del bridge e snippet.

3.1 Scope Session

Uno script salvato come Session diventa immediatamente visibile come session:<script_id> nel selettore del modulo di analisi, nella Script Library e nel Session Script Explorer. È la scelta normale per un’analisi riproducibile legata a quella Sessione.

3.2 Scope User

Uno script User è riutilizzabile fra Sessioni. Quando deve diventare parte riproducibile di una Sessione, viene assegnato alla Sessione: GX-TXT copia i byte del sorgente in un record Session separato. Modifiche successive alla copia User non modificano silenziosamente quella Session.

3.3 Legacy documents

I vecchi documenti Workspace basati su Interactive Document rimangono leggibili con riferimento legacy:. Prima di essere usati come input eseguibile normale devono essere esplicitamente registrati come Session Script o User Script.

4. Primo script: contesto e discovery

Il primo programma utile non elabora dati: interroga l’ambiente in cui sta girando.

% GX-TXT: first inspection script

info = gxtxt_bridge_info();
disp(info);

ctx = gxtxt_context();
disp(ctx);

apis = gxtxt_api_list();
fprintf('API pubbliche richiamabili dallo script: %d\n', numel(apis));

for k = 1:numel(apis)
  disp(apis{k});
endfor

Questo script insegna tre cose fondamentali: il bridge è attivo solo durante l’esecuzione; il contesto viene fornito dal framework; l’elenco delle API deve essere scoperto invece di essere ricostruito a mano dal filesystem.

5. Script Registry: identità, revisione e requisiti

Ogni record registrato contiene almeno identità stabile, nome, linguaggio, versione semantica, revisione, SHA-256, descrizione, API richieste, schema di parametri tipizzati, scope e provenance del sorgente.

Le API richieste possono essere dichiarate in forma semplice o vincolata:

CANONICAL_DATASET_API_v2
PLOT_DATASET_API_v3@3
PLOT_DATASET_API_v3@3:plot.dataset+plotspec|render

La forma estesa permette di richiedere versione esatta dell’API, provider e capability. Il preflight avviene prima dell’esecuzione scientifica.

6. Script Bridge: funzioni fondamentali

6.1 Discovery prima della chiamata

api_id = 'CANONICAL_DATASET_API_v2';

if (!gxtxt_api_has(api_id))
  error('API non disponibile: %s', api_id);
endif

desc = gxtxt_api_describe(api_id);
disp(desc);

if (!gxtxt_api_has_operation(api_id, 'read_range'))
  error('read_range non disponibile');
endif

6.2 Perché usare gxtxt_api_describe()

La descrizione restituisce metadati macchina, compresi nome dell’operazione, argomenti, tipi, obbligatorietà, risultato, versione API, provider e capability. È quindi il primo strumento di debug quando un esempio scritto per una release precedente non corrisponde più all’installazione corrente.

7. Contesto, alias e Dataset ID

gxtxt_context() contiene informazioni come:

• module_id, run_id, operation;
• script_name e script_sha256;
• arguments_raw;
• output_dir;
• inputs, cioè gli alias configurati nella pagina Analysis.

Ogni input espone l’alias/source ID e, quando presente, il dataset_id selezionato. Il contesto non espone il percorso privato del Dataset.

7.1 Leggere l’alias primary

Poiché la struttura esatta di ctx.inputs è trasportata come struttura Octave, durante lo sviluppo conviene prima ispezionarla:

ctx = gxtxt_context();
disp(ctx.inputs);

Poi si usa il Dataset ID ottenuto dall’alias selezionato come identità per le API Dataset. Lo script non deve ricostruire metadata/datasets.ini né percorsi relativi alla Sessione.

8. Leggere Dataset canonici

L’API di lettura corrente è CANONICAL_DATASET_API_v2. Le operazioni disponibili al bridge sono:

8.1 Elencare i Dataset

gxtxt_api_require('CANONICAL_DATASET_API_v2@2');

ids = gxtxt_api_call('CANONICAL_DATASET_API_v2', 'list', {});
for k = 1:numel(ids)
  fprintf('%s\n', ids{k});
endfor

8.2 Descrivere un Dataset

dataset_id = 'sample';
meta = gxtxt_api_call('CANONICAL_DATASET_API_v2', 'describe', {dataset_id});
disp(meta);

8.3 Leggere due variabili

vars = {'v0001', 'v0002'};
block = gxtxt_api_call('CANONICAL_DATASET_API_v2', 'read_range', ...
                       {dataset_id, vars, 0, 1000});
disp(block);

start è zero-based perché descrive un range del contratto Dataset, anche se gli indici ordinari di Octave sono one-based. Per Dataset grandi usare sempre un count limitato.

8.4 Dati multidimensionali

Il range generico non appiattisce silenziosamente variabili multidimensionali. La struttura logica conserva rank e shape. Per flussi multidimensionali o streaming avanzato usare i servizi previsti dalla specifica del Dataset o TABLE_STREAM_API_v3 quando appropriato.

9. Schema delle variabili

DATASET_VARIABLE_SCHEMA_API_v3 consente di interrogare l’identità e la struttura delle variabili senza interpretare header fisici o colonne.

vars = gxtxt_api_call('DATASET_VARIABLE_SCHEMA_API_v3', 'list', {dataset_id});
disp(vars);

v = gxtxt_api_call('DATASET_VARIABLE_SCHEMA_API_v3', 'get', ...
                   {dataset_id, 'v0001'});
disp(v);

I descrittori possono contenere dtype, rank, shape, dimensioni, coordinate, ruolo della coordinata, asse uniforme, componenti e group ID.

10. Calcolo numerico tramite NUMERIC_API_v1

NUMERIC_API_v1, fornita da math.numeric, raccoglie primitive numeriche riutilizzabili. Il bridge espone operazioni generiche su array, algebra lineare, statistica Dataset-aware, fitting e la Mathematical Foundation.

10.1 Operandi tipizzati per array

a = struct('kind', 'vector', 'value', [1; 2; 3]);
b = struct('kind', 'scalar', 'value', 4);

r = gxtxt_api_call('NUMERIC_API_v1', 'array_binary', ...
                   {'multiply', a, b});

disp(r.values);

Per le operazioni generiche, gli operandi sono struct con kind=scalar|vector|matrix e campo value.

10.2 Operazione unaria

x = struct('kind', 'vector', 'value', [-2; -1; 0; 1; 2]);

r = gxtxt_api_call('NUMERIC_API_v1', 'array_unary', ...
                   {'abs', x});

disp(r.values);

10.3 Algebra lineare

A = struct('real', [2 1; 1 3]);
B = struct('real', [1; 2]);

r = gxtxt_api_call('NUMERIC_API_v1', 'linear_matrix', ...
                   {'solve', A, B});

x = r.value_real;
disp(x);

10.4 Mathematical Foundation

Le primitive avanzate usano nodi tipizzati, per esempio:

gxtxt_api_require('NUMERIC_API_v1@1:math.numeric+mathematical_foundation');

a = struct('kind','array','shape',[2 1],'real',[1 2]);
b = struct('kind','array','shape',[2 1],'real',[3 4]);
empty = struct('kind','empty');

r = gxtxt_api_call('NUMERIC_API_v1', 'foundation', ...
                   {'vector','dot',a,b,empty});

disp(r);

La Foundation include famiglie per vettori, tensori, griglie, interpolazione scattered, famiglie di curve, calcolo differenziale/integrale, ODE, ottimizzazione vincolata, geometria, sparse, statistica e funzioni speciali.

10.5 Callback

Alcune operazioni supportano callback di esecuzione. In questi casi lo script registra una function handle tramite gxtxt_callback_register(), passa il token all’API prevista e infine lo rilascia. La callback vive solo nell’esecuzione corrente.

11. Unità di misura

UNIT_REGISTRY_API_v1 evita conversioni hardcoded nello script.

ok = gxtxt_api_call('UNIT_REGISTRY_API_v1', 'compatible', {'mV', 'V'});
if (!ok)
  error('Unità incompatibili');
endif

v = [1000; 2500; 5000];
v_volt = gxtxt_api_call('UNIT_REGISTRY_API_v1', 'convert', {v, 'mV', 'V'});
disp(v_volt);

GX-TXT non inventa relazioni fisiche: unità opache restano opache e non vengono create conversioni implicite come ppm→mg/L o pH→concentrazione.

12. Pubblicare un nuovo Dataset

Per produrre un risultato scientifico persistente usare DATASET_PUBLICATION_API_v2. Non scrivere direttamente dentro la cartella Dataset e non aggiornare registri interni.

12.1 Lifecycle

1. begin — crea un writer transazionale;
2. declare_dimension — dichiara le dimensioni;
3. declare_variable — dichiara variabili e schema;
4. write_variable o append — scrive dati;
5. finalize — valida, calcola SHA-256, posiziona atomicamente e registra;
6. abort — annulla in caso di errore.

12.2 Esempio tabellare minimale

gxtxt_api_require('DATASET_PUBLICATION_API_v2@2');

definition = struct();
definition.dataset_id = 'derived_example';
definition.contract = 'table.generic';
definition.storage = 'auto';
definition.producer_version = '1.0.0';

writer = gxtxt_api_call('DATASET_PUBLICATION_API_v2', 'begin', {definition});

try
  dimopt = struct();
  gxtxt_api_call('DATASET_PUBLICATION_API_v2', 'declare_dimension', ...
                 {writer, 'row', 5, dimopt});

  sx = struct('dtype','float64', 'rank',1, ...
              'dimension_ids',{{'row'}}, ...
              'coordinate_role','data');
  sy = sx;

  gxtxt_api_call('DATASET_PUBLICATION_API_v2', 'declare_variable', ...
                 {writer, 'x', sx});
  gxtxt_api_call('DATASET_PUBLICATION_API_v2', 'declare_variable', ...
                 {writer, 'y', sy});

  x = [0;1;2;3;4];
  y = x.^2;

  gxtxt_api_call('DATASET_PUBLICATION_API_v2', 'write_variable', ...
                 {writer, 'x', x, [5]});
  gxtxt_api_call('DATASET_PUBLICATION_API_v2', 'write_variable', ...
                 {writer, 'y', y, [5]});

  result = gxtxt_api_call('DATASET_PUBLICATION_API_v2', 'finalize', {writer});
  disp(result);

catch err
  gxtxt_api_call('DATASET_PUBLICATION_API_v2', 'abort', {writer});
  rethrow(err);
end_try_catch

13. Creare e aggiornare grafici con Plot Dataset

La facciata corrente è PLOT_DATASET_API_v3, fornita da plot.dataset 3.12.0 nella release verificata.

Operazioni bridge principali:

13.1 Creare la base di un PlotSpec

gxtxt_api_require('PLOT_DATASET_API_v3@3:plot.dataset');

spec = gxtxt_api_call('PLOT_DATASET_API_v3', 'new_spec', ...
                      {'plot.dataset.xy', 'Risultato dello script'});

disp(spec);

Il PlotSpec usa identità Dataset/Variable stabili. Durante lo sviluppo è consigliato creare il template con new_spec, ispezionarlo, compilare i campi documentati dal PlotSpec e validarlo prima di persisterlo.

ok = gxtxt_api_call('PLOT_DATASET_API_v3', 'validate_spec', {spec});
if (!ok)
  error('PlotSpec non valido');
endif

plot_ref = gxtxt_api_call('PLOT_DATASET_API_v3', 'upsert_plot', ...
                          {'main_result', spec});

render_result = gxtxt_api_call('PLOT_DATASET_API_v3', 'render', {plot_ref});
artifacts = gxtxt_api_call('PLOT_DATASET_API_v3', 'artifacts', {plot_ref});

disp(render_result);
disp(artifacts);

14. Dataset grandi e lettura a blocchi

Il bridge trasporta automaticamente array numerici grandi con blocchi binari tipizzati oltre la soglia interna prevista; lo script riceve normali valori Octave. Non deve gestire file di trasporto.

Questo non significa però che sia opportuno caricare sempre un Dataset intero.

chunk = 50000;
start0 = 0;

while true
  block = gxtxt_api_call('CANONICAL_DATASET_API_v2', 'read_range', ...
                         {dataset_id, {'v0001','v0002'}, start0, chunk});

  % La logica di arresto dipende dai metadati restituiti.
  % Elaborare il blocco qui.

  start0 = start0 + chunk;

  % Uscire quando il range restituito indica esaurimento dati.
endwhile

Per flussi tabellari iterativi è disponibile anche TABLE_STREAM_API_v3 con operazioni open_dataset, metadata, next, diagnostics e close.

15. Altri servizi pubblici disponibili

La disponibilità runtime deve sempre essere verificata con gxtxt_api_list(). Nella build dev-023 il bridge comprende, fra gli altri:

Alcune API restano intenzionalmente host-only: per esempio registrazione delle sorgenti Analysis, configurazione del runtime, provider GUI e protocolli privati. Il bridge non permette di eseguire Tcl arbitrario o chiamare funzioni private ::GX::*.

16. Tutorial passo passo

Tutorial A — Inventario delle API disponibili

1. Creare un nuovo Session Script.
2. Inserire il codice seguente.
3. Salvarlo e avviarlo dal modulo Octave Script.
4. Usare l’output come fotografia delle API effettivamente installate.

apis = gxtxt_api_list();

fprintf('Totale API: %d\n\n', numel(apis));

for k = 1:numel(apis)
  a = apis{k};
  disp(a);
  fprintf('\n');
endfor

Tutorial B — Individuare un Dataset e leggerne 20 righe

gxtxt_api_require({
  'CANONICAL_DATASET_API_v2@2',
  'DATASET_VARIABLE_SCHEMA_API_v3@3'
});

ids = gxtxt_api_call('CANONICAL_DATASET_API_v2', 'list', {});
disp(ids);

dataset_id = ids{1};

meta = gxtxt_api_call('CANONICAL_DATASET_API_v2', 'describe', {dataset_id});
disp(meta);

vars = gxtxt_api_call('DATASET_VARIABLE_SCHEMA_API_v3', 'list', {dataset_id});
disp(vars);

% Sostituire con Variable ID realmente presenti:
selected = {'v0001','v0002'};

data = gxtxt_api_call('CANONICAL_DATASET_API_v2', 'read_range', ...
                      {dataset_id, selected, 0, 20});
disp(data);

Tutorial C — Calcolare il valore assoluto di una variabile

Dopo aver estratto un vettore numerico dal risultato di read_range, passarlo a NUMERIC_API_v1:

operand = struct('kind','vector','value', values);

result = gxtxt_api_call('NUMERIC_API_v1', 'array_unary', ...
                        {'abs', operand});

abs_values = result.values;

Tutorial D — Convertire unità

source_unit = 'mA';
target_unit = 'A';

if (!gxtxt_api_call('UNIT_REGISTRY_API_v1', 'compatible', ...
                    {source_unit, target_unit}))
  error('Conversione non disponibile');
endif

converted = gxtxt_api_call('UNIT_REGISTRY_API_v1', 'convert', ...
                           {values, source_unit, target_unit});

Tutorial E — Pubblicare un Dataset derivato

Flusso consigliato:

1. leggere Dataset e Variable Schema;
2. calcolare il risultato;
3. definire un nuovo Dataset ID;
4. aprire il writer;
5. dichiarare dimensioni e variabili;
6. scrivere i valori;
7. finalizzare;
8. solo dopo il finalize usare il nuovo Dataset per grafici o ulteriori analisi.

Il codice completo è quello del capitolo 12. La parte essenziale è il try/catch con abort in caso di errore.

Tutorial F — Creare un grafico persistente

1. richiedere PLOT_DATASET_API_v3;
2. creare un template con new_spec;
3. ispezionarlo;
4. impostare Dataset ID e Variable ID secondo il PlotSpec corrente;
5. validare;
6. usare upsert_plot con una chiave stabile;
7. renderizzare;
8. leggere gli artifact prodotti.

api = gxtxt_api_describe('PLOT_DATASET_API_v3');
disp(api);

spec = gxtxt_api_call('PLOT_DATASET_API_v3', 'new_spec', ...
                      {'plot.dataset.xy','Derived result'});

disp(spec);

% Compilare il PlotSpec usando le identità Dataset/Variable.
% Poi:
ok = gxtxt_api_call('PLOT_DATASET_API_v3','validate_spec',{spec});
if (!ok), error('PlotSpec non valido'); endif

ref = gxtxt_api_call('PLOT_DATASET_API_v3','upsert_plot', ...
                     {'derived_result',spec});
gxtxt_api_call('PLOT_DATASET_API_v3','render',{ref});
art = gxtxt_api_call('PLOT_DATASET_API_v3','artifacts',{ref});
disp(art);

Tutorial G — Script riutilizzabile e riproducibile

% 1. Requisiti
gxtxt_api_require({
  'CANONICAL_DATASET_API_v2@2',
  'DATASET_VARIABLE_SCHEMA_API_v3@3',
  'NUMERIC_API_v1@1:math.numeric'
});

% 2. Contesto
ctx = gxtxt_context();
disp(ctx.inputs);

% 3. Identità scientifiche: Dataset ID / Variable ID
%    ottenute dal contesto o dalla configurazione dello script.

% 4. Lettura attraverso API pubblica
% data = gxtxt_api_call(...);

% 5. Elaborazione
% result = gxtxt_api_call('NUMERIC_API_v1', ...);

% 6. Pubblicazione
% writer = gxtxt_api_call('DATASET_PUBLICATION_API_v2', ...);

% 7. Grafico persistente, se richiesto
% plot_ref = gxtxt_api_call('PLOT_DATASET_API_v3', ...);

17. Errori, diagnostica e troubleshooting

17.1 Script non visibile nel selettore Analysis

• verificare che lo scope sia Session;
• verificare che il linguaggio registrato sia Octave;
• verificare che analysis.octave_script sia abilitato;
• un record User non appare come Session input finché non viene assegnato alla Sessione;
• un documento legacy deve essere prima registrato.

17.2 API assente

if (!gxtxt_api_has('SOME_API_v1'))
  disp(gxtxt_api_list());
  error('SOME_API_v1 non è disponibile in questa installazione');
endif

17.3 Operazione sconosciuta

desc = gxtxt_api_describe('SOME_API_v1');
disp(desc);

Non dedurre il nome dell’operazione dal Tcl API originale: il binding script può esporre un sottoinsieme con nomi propri.

17.4 Classi di errore del bridge

Il bridge distingue almeno:

• GXTXT:ScriptBridge:NotActive;
• UnknownAPI;
• UnknownOperation;
• InvalidArguments;
• Transport;
• RemoteError.

17.5 Concorrenza nell’editor

Se il Workspace segnala che lo SHA-256 sorgente è cambiato, ricaricare il record e riapplicare la modifica. Il controllo evita di sovrascrivere una revisione aggiornata altrove.

17.6 Report di esecuzione

Ogni Analysis run produce almeno:

• executed_script.m — copia esatta eseguita;
• octave_script_run_report.txt — report del run.

18. Riproducibilità e provenance

Per un risultato destinato a essere condiviso, la riproducibilità si ottiene conservando insieme:

• riferimento registrato dello script;
• revisione e SHA-256;
• Dataset ID e Variable ID usati;
• API richieste e relative versioni/capability;
• parametri del run;
• Dataset derivati pubblicati tramite API;
• Plot reference persistenti invece dei soli file immagine.

La copia sorgente del run è immutabile. Uno script aggiornato in seguito non cambia retroattivamente l’identità del codice già eseguito.

19. Buone pratiche

1. Usare le API, non i path. L’accesso diretto alla struttura interna rende lo script fragile e può scrivere nel posto sbagliato.
2. Usare Dataset ID + Variable ID. Label e colonne fisiche sono presentazione o implementazione.
3. Fare preflight. Dichiarare e verificare le API richieste.
4. Fare discovery. In caso di dubbio interrogare gxtxt_api_describe().
5. Leggere a blocchi. Evitare di caricare milioni di righe se l’algoritmo è streaming.
6. Pubblicare transazionalmente. Per nuovi Dataset usare Publication API v2.
7. Non duplicare servizi scientifici. Se una trasformazione esiste in NUMERIC_API_v1, SIGNAL_API_v1, RF_NETWORK_API_v1 o MAGNETICS_API_v1, preferire l’API pubblica.
8. Non usare artifact come identità scientifica. PNG/PDF sono output, non Dataset o Plot identity.
9. Mantenere codice Octave-portabile. Se si vuole compatibilità MATLAB, evitare estensioni non necessarie di uno dei due linguaggi.
10. Promuovere a plugin quando serve. Quando lo script diventa stabile, condiviso e con configurazione strutturata, può essere opportuno trasformarlo in un modulo GX-TXT dedicato.

20. Riferimento rapido

20.1 Template minimo

ctx = gxtxt_context();

gxtxt_api_require({
  'CANONICAL_DATASET_API_v2@2',
  'NUMERIC_API_v1@1:math.numeric'
});

% 1) ricavare Dataset ID dagli input/configurazione
% 2) leggere schema e dati via API
% 3) elaborare
% 4) pubblicare risultati via API

20.2 Comandi da ricordare

gxtxt_bridge_info()
gxtxt_context()
gxtxt_api_list()
gxtxt_api_has(api_id)
gxtxt_api_describe(api_id)
gxtxt_api_has_operation(api_id, operation)
gxtxt_api_require(requirements)
gxtxt_api_call(api_id, operation, args)
gxtxt_callback_register(function_handle)
gxtxt_callback_release(handle)

20.3 API centrali per uno script scientifico

20.4 Riferimenti tecnici della release verificata

• plugins/modules/analysis.octave_script/MANUAL.md
• plugins/modules/analysis.octave_script/OCTAVE_SCRIPT_EDITOR_API_v1.md
• docs/api/OCTAVE_SCRIPT_BRIDGE_API_v1.md
• docs/api/SCRIPT_EXECUTION_API_v1.md
• docs/api/CANONICAL_DATASET_API_v2.md
• docs/api/DATASET_VARIABLE_SCHEMA_API_v3.md
• docs/api/DATASET_PUBLICATION_API_v2.md
• docs/api/PLOT_DATASET_API_v3.md
• plugins/modules/plot.dataset/PLOT_DATASET_API_v3.md
• plugins/modules/math.numeric/NUMERIC_API_v1.md
• docs/api/UNIT_REGISTRY_API_v1.md
• docs/api/SCRIPT_BRIDGE_COVERAGE_v1.json