Lezione 16 – Dal segnale UV-Vis alla costante cinetica: un progetto scientifico completo con GNU Octave e GX-TXT

di Giux debug-it, GX-TXT, octave-it, scripts-it 38 min di lettura

Nelle lezioni precedenti abbiamo imparato a rappresentare dati, risolvere sistemi lineari, eseguire regressioni, integrare equazioni differenziali e pubblicare Dataset. Ora riuniamo queste tecniche in un esperimento: osserviamo una trasformazione chimica mediante spettrofotometria UV-Vis a due lunghezze d’onda, ricostruiamo le concentrazioni delle specie e verifichiamo la legge cinetica. L’intero percorso si svolge in una Session GX-TXT utilizzando GNU Octave e le API pubbliche del framework.

Versione di riferimento: GX-TXT 0.9.8.10-dev-112 Release 2 P009 — release ufficiale GitHub, sorgenti al commit 059ff073eb43770292b6609f7c0cc3cbc811710d. Gli script sono distribuiti con licenza GPL-3.0-or-later; tutti i commenti nel codice sono in inglese.

Natura dei dati. Le assorbanze di questa lezione sono sintetiche e deterministiche: simulano un esperimento coerente con la legge di Beer-Lambert, aggiungendo piccole perturbazioni definite matematicamente. Non sono misure di laboratorio né una validazione sperimentale di un meccanismo chimico.

Cosa impareremo

Al termine saremo in grado di collegare misure, modello fisico e risultati persistenti. Riprenderemo l’organizzazione di un programma in fasi, la forma matriciale di un modello di misura, la soluzione di più sistemi con una sola chiamata, il fitting con controllo dei residui, l’integrazione con ode45, il debugger nativo e la conservazione dei risultati scientifici come Dataset e Plot Dataset.

Collegamento con il percorso: che cosa cambia nella Lezione 16

Le Lezioni 10–15 hanno già spiegato i singoli strumenti. Qui impariamo soprattutto a farli collaborare senza perdere il significato fisico dei dati.

Conoscenza già acquisitaUtilizzo nuovo nel progetto finale
Lezione 10 — regressione e residuiStimare un parametro cinetico a partire da concentrazioni che prima devono essere ricavate da segnali ottici
Lezione 11 — calcolo numerico su serie temporaliMantenere allineate le osservazioni e controllare le unità durante più elaborazioni successive
Lezione 12 — rango, condizionamento e soluzione di matriciRisolvere 31 sistemi con la stessa matrice, usando 31 colonne di termini noti in una singola operazione
Lezione 13 — rappresentazione e campionamento dei segnaliTrattare due canali strumentali come misure sincronizzate dello stesso fenomeno
Lezione 14 — funzioni anonime, ode45 e conservazioneAlimentare un modello dinamico con parametri stimati, invece di fissarli tutti prima della simulazione
Lezione 15 — controlli fisici, unità e verifiche indipendentiOrganizzare verifiche prima, durante e dopo l’elaborazione, fino alla pubblicazione dei risultati

È anche un esercizio di progettazione del software: passeremo da programmi che eseguono un calcolo a un flusso di lavoro con precondizioni, postcondizioni e risorse scientifiche persistenti.

1. Il problema scientifico: seguire una reazione A → B

Consideriamo una reazione irreversibile del primo ordine:

\[
A \xrightarrow{k} B,\qquad
\frac{d[A]}{dt}=-k[A],\qquad
\frac{d[B]}{dt}=k[A].
\]

Partendo da \([A]_0=2{,}0\ \mathrm{mmol/L}\) e \([B]_0=0\), con una costante cinetica di riferimento \(k=0{,}045\ \mathrm{min}^{-1}\), la soluzione esatta è

\[
[A](t)=[A]_0e^{-kt}, \qquad [B](t)=[A]_0-[A](t).
\]

La somma \([A](t)+[B](t)\) resta costante per conservazione della materia. Registriamo 31 istanti, da 0 a 60 minuti a intervalli di 2 minuti. In questa lezione non utilizziamo la costante impiegata per generare i dati durante la regressione: la stimiamo dalle assorbanze, per poi confrontarla con il valore noto.

Perché due lunghezze d’onda?

Una singola assorbanza è la somma dei contributi delle specie presenti. Se entrambe assorbono, non possiamo ricavare separatamente le due concentrazioni da una sola osservazione. Con misure a 430 nm e 520 nm otteniamo invece due equazioni indipendenti.

Per un cammino ottico \(\ell=1\ \mathrm{cm}\) imponiamo la matrice delle assorbività molari

\[
E=\begin{bmatrix}0{,}75&0{,}20\\0{,}12&0{,}62\end{bmatrix}
\quad\mathrm{L/(mmol\cdot cm)}.
\]

La legge di Beer-Lambert diventa

\[ \begin{bmatrix} A_{430}(t) \\ A_{520}(t) \end{bmatrix} = \ell\, E \begin{bmatrix} \left[A\right](t) \\ \left[B\right](t) \end{bmatrix} \]

Le righe rappresentano le lunghezze d’onda, le colonne le specie chimiche; mantenere quest’ordine è fondamentale. Le assorbanze sono adimensionali (unità dichiarata 1). L’esperimento funziona perché la matrice è di rango 2 e permette di distinguere le specie.

Il concetto scientifico nuovo: un problema inverso dipendente dal tempo

Lo strumento misura due assorbanze; le concentrazioni di A e B non sono osservate direttamente. Ricostruirle significa risolvere un problema inverso: partire dagli effetti misurabili per risalire alle grandezze che li hanno prodotti. La stessa relazione di Beer-Lambert, usata in avanti, permette poi di ricostruire le assorbanze e controllare il risultato.

Se indichiamo con \(Y\) i segnali, con \(C\) le concentrazioni e con \(\Delta Y\) le piccole perturbazioni, il modello generativo è

\[
Y=(\ell E)C+\Delta Y.
\]

Per ricavare \(C\), il programma utilizza \(\ell E\) e i valori di \(Y\); non legge le concentrazioni di riferimento come input della soluzione inversa. I Dataset reference sono disponibili soltanto per il confronto con la soluzione ottenuta. In questo esperimento assumiamo note le assorbività delle due specie e il cammino ottico; non stimiamo tali coefficienti, né la loro incertezza.

Una difficoltà specifica compare perché la misura è una serie temporale multicanale: tutte le colonne devono riferirsi agli stessi istanti. Due vettori contenenti 31 valori non sono necessariamente sincronizzati. Per questo il terzo script verifica anche l’uguaglianza delle coordinate temporali, non soltanto il numero di osservazioni.

2. Preparare il primo script: vettori, matrici e Dataset

Il programma L16_00_Prepare_UVVis_Kinetics.m costruisce il vettore dei tempi con (0:2:60)'; l’apostrofo crea un vettore colonna. Le concentrazioni di riferimento si ottengono usando exp e la moltiplicazione elemento per elemento .*. Con il punto davanti all’operatore chiediamo a Octave di elaborare ogni campione separatamente, non di effettuare una moltiplicazione matriciale.

Il programma calcola quindi le due assorbanze e aggiunge piccoli termini sinusoidali riproducibili. Queste perturbazioni simulano le imperfezioni di un segnale, ma non rappresentano un modello statistico con incertezza strumentale stimata.

Ogni serie viene associata a una definizione esplicita della variabile orizzontale time_min, a un variable_id per la variabile misurata, alle unità, alla provenienza sintetica e a metadati scientifici. Lo script pubblica in una sola operazione cinque Dataset:

DatasetSignificato
lesson16_uvvis_430nmAssorbanza sintetica a 430 nm
lesson16_uvvis_520nmAssorbanza sintetica a 520 nm
lesson16_reference_AConcentrazione analitica di A
lesson16_reference_BConcentrazione analitica di B
lesson16_reference_totalSomma teorica conservata

Quando la pubblicazione termina, lo script usa read_range per leggere nuovamente i cinque Dataset e confrontarli con le serie originali. Il risultato non è solo un messaggio numerico: le risorse restano collegate alla Session e consultabili dai Viewer GX-TXT.

Session scientifica attiva nel Viewer GX-TXT della Lezione 16
Una Session dedicata contiene l’esperimento, gli script e i Dataset generati.
Job di preparazione completato in GX-TXT
La preparazione ha pubblicato i cinque Dataset di ingresso prima dell’analisi cinetica.

3. Imparare a ragionare con le dimensioni delle matrici

Nel programma finale, le assorbanze vengono organizzate in una matrice \(\mathbf{Y}\) di dimensioni \(2\times31\). Ogni riga corrisponde a una lunghezza d’onda; ogni colonna a un istante di misura.

\[
E\ (2\times2)\ \cdot\ C\ (2\times31)=Y\ (2\times31).
\]

L’obiettivo è determinare \(C\), dove la prima riga contiene le concentrazioni di A e la seconda quelle di B. GNU Octave distingue la trasposizione semplice .' dalla trasposizione coniugata ': con dati reali coincidono, ma su matrici complesse il risultato sarebbe differente. Qui [abs430.'; abs520.'] trasforma due colonne da 31 osservazioni nella matrice \(2\times31\) richiesta dal problema.

Non calcoliamo esplicitamente l’inversa di \(E\). Attraverso NUMERIC_API_v1/linear_matrix chiediamo al CORE di controllarne rango e condizionamento e poi di risolvere il sistema con più termini noti. Una sola chiamata elabora quindi tutte le 31 osservazioni.

E = [0.75, 0.20; 0.12, 0.62];
Y = [abs430.'; abs520.'];
envelope_E = struct('real', E, 'imaginary', zeros(size(E)));
envelope_Y = struct('real', Y, 'imaginary', zeros(size(Y)));

check = gxtxt_api_call('NUMERIC_API_v1', 'linear_matrix', ...
  {'inspect', envelope_E, []});
solution = gxtxt_api_call('NUMERIC_API_v1', 'linear_matrix', ...
  {'solve', envelope_E, envelope_Y});
recovered_A = solution.value_real(1,:).';
recovered_B = solution.value_real(2,:).';

L’envelope real/imaginary è il formato dichiarato dal contratto pubblico per il trasporto di matrici attraverso lo Script Bridge. Non serve conoscere la rappresentazione interna del CORE. Il risultato è ricondotto a normali array Octave.

Programmazione Octave: cell array, strutture e campi dinamici

Le lezioni precedenti hanno introdotto vettori, struct e cell array singolarmente. Il passo ulteriore è usarli insieme per gestire un insieme di Dataset senza duplicare il codice di lettura. Nel terzo script troviamo lo schema seguente (estratto con le variabili già dichiarate):

source_values = cell(1,numel(source_ids));
for j = 1:numel(source_ids)
  node = gxtxt_api_call(dataset_api,'read_range', ...
    {source_ids{j},{'time_min',source_y_ids{j}},0,n});
  source_values{j} = node.(source_y_ids{j}).values(:);
endfor

È importante comprendere precisamente la sintassi:

Istruzione OctaveSignificato
cell(1,numel(source_ids))Prealloca una cell array con una cella per ogni Dataset
source_ids{j}Estrae il contenuto della cella j, qui una stringa; source_ids(j) restituirebbe invece una cell array
node.(source_y_ids{j})Accede a un campo dinamico della struttura, usando il Variable ID letto dalla cella
.values(:)Estrae i valori e li normalizza in un vettore colonna, qualunque fosse l’orientamento iniziale
[abs430.'; abs520.']Trasforma due vettori colonna in due righe e le concatena verticalmente
result.value_real(1,:).'Seleziona la prima riga della soluzione e la riporta a vettore colonna

Il programma costruisce anche tabelle di configurazione sotto forma di cell array bidimensionali: required{j,1} è il nome di un’API, mentre required{j,2} identifica l’operazione da controllare; rows(required) fornisce il numero delle righe da percorrere. Lo stesso schema è impiegato per definire i cinque grafici in plot_defs, separando i dati delle specifiche grafiche dal ciclo che le crea.

Un dettaglio più avanzato riguarda il batch di pubblicazione:

publish = gxtxt_api_call(publication_api,'publish_series_batch', ...
  {struct('series',{derived})});

Qui derived è una cell array di sette specifiche. Le parentesi graffe interne {derived} fanno sì che il campo series contenga l’intera raccolta, invece di costruire una struttura per ciascuna cella; quelle esterne racchiudono l’argomento posizionale della chiamata pubblica. Capire questo livello di annidamento è essenziale quando si passano strutture complesse attraverso lo Script Bridge.

4. Debugger: l’errore scientifico delle lunghezze d’onda invertite

Lo script L16_01_Debug_Swapped_Wavelengths.m contiene deliberatamente una riga sbagliata:

wrong_absorbances = [A520.'; A430.'];

L’algoritmo è matematicamente eseguibile, ma i dati vengono associati alle righe sbagliate di \(E\): una risposta a 520 nm viene interpretata come se fosse a 430 nm, e viceversa. Il programma produce così concentrazioni impossibili, anche negative. È un esempio concreto del perché un Job eseguito senza errori sintattici non costituisca automaticamente un risultato scientificamente valido.

Nel Viewer Octave Scripts, apriamo Run → Debug Session script, scegliamo lo script, inseriamo un breakpoint alla riga 60 e avviamo il debugger. A quel punto ispezioniamo c_A_bad e c_B_bad, oltre alla matrice wrong_absorbances. La concentrazione iniziale di A ricostruita in modo errato è circa −0,3414 mmol/L, mentre quella di B supera 2,48 mmol/L: violano le condizioni fisiche del modello scelto.

Debugger Octave arrestato sull’errore di assegnazione delle lunghezze d’onda
L’ispezione delle variabili permette di riconoscere il problema scientifico prima della pubblicazione.

Con Continue il controllo delle concentrazioni provoca il fallimento intenzionale del Job. È il comportamento corretto: non vengono pubblicati Dataset derivati da un’assegnazione strumentale incoerente.

Errore fisico intenzionale segnalato dal debugger GX-TXT
Un errore riconosciuto esplicitamente è preferibile alla pubblicazione silenziosa di dati privi di significato.

5. Stimare la costante cinetica con una regressione

Dopo aver ricostruito correttamente le concentrazioni, possiamo testare la cinetica del primo ordine. Applicando il logaritmo naturale:

\[
\ln[A](t)=\ln[A]_0-kt.
\]

Il grafico di \(\ln[A]\) contro \(t\) dovrebbe essere approssimativamente lineare. La sua pendenza è \(-k\), mentre l’intercetta stima \(\ln[A]_0\). Utilizziamo la regressione lineare pubblica di GX-TXT:

fit = gxtxt_api_call('NUMERIC_API_v1', 'linear_regression', ...
  {time_min, log(recovered_A), [], struct('intercept', true)});
k_estimated = -fit.slope;
A0_estimated = exp(fit.intercept);
R2 = fit.r_squared;

Il vettore vuoto [] occupa la posizione dei pesi: stiamo eseguendo una regressione ordinaria non pesata. struct('intercept',true) richiede di stimare anche l’intercetta. Octave fornisce log ed exp; la stima dei coefficienti è svolta dall’API numerica pubblica.

La trasformazione logaritmica cambia il significato delle deviazioni: un rumore additivo nello spazio delle assorbanze non diventa automaticamente un errore omoscedastico in \(\ln[A]\). Per questo motivo consideriamo qui la regressione uno strumento didattico e riportiamo esplicitamente tale limite, senza attribuire intervalli di confidenza non calcolati.

Una distinzione nuova: errore di misura, errore di stima, errore del modello

In questa catena di calcolo compaiono tre confronti diversi, da non confondere:

  1. Le perturbazioni sono aggiunte alle assorbanze \(A_{430}\) e \(A_{520}\): appartengono allo spazio dei segnali.
  2. La regressione minimizza le deviazioni di \(\ln[A]\) da una retta: il coefficiente \(R^2\) si riferisce allo spazio logaritmico della concentrazione.
  3. I residui finali confrontano concentrazioni ricostruite e previste dall’ODE: il loro RMS è espresso in mmol/L.

Un valore \(R^2\) molto vicino a 1 non garantisce, da solo, che il bilancio di materia sia rispettato o che le due assorbanze siano state assegnate alla lunghezza d’onda corretta. I tre controlli rispondono a domande differenti.

La regressione stima sia \(\hat{k}\) sia \(\widehat{[A]_0}\); la condizione iniziale \([B]_0=0\) è invece imposta dal modello scelto, non stimata da un ulteriore fitting. Il valore di riferimento 0.045 compare nella generazione e nel confronto finale dei dati sintetici, non come parametro fornito alla regressione. In una misura reale, il valore vero di \(k\) sarebbe normalmente ignoto e occorrerebbe un’analisi dell’incertezza e dell’adeguatezza del modello.

6. Integrare le equazioni differenziali con ode45

Riprendiamo la Lezione 14. Usando i parametri ricavati dalla regressione, definiamo una funzione anonima in Octave:

rhs = @(t, y) [-k_estimated*y(1); k_estimated*y(1)];
options = odeset('RelTol',1e-10,'AbsTol',1e-11);
[t_model, state_model] = ode45(rhs, time_min, ...
  [A0_estimated; 0], options);

Il vettore y contiene \([A]\) e \([B]\). La funzione rhs restituisce le due derivate nel medesimo ordine. ode45 è una funzione nativa GNU Octave, non un’API GX-TXT: l’integrazione numerica viene insegnata come parte del linguaggio. Il framework gestisce, tramite le proprie API, l’ingresso dei Dataset e la persistenza dei risultati.

Il programma confronta la soluzione numerica per A con la formula esatta \(A_0e^{-kt}\) e controlla che \(A+B\) rimanga costante. Questo doppio controllo individua errori nel modello differenziale, nelle condizioni iniziali e nell’allineamento degli array.

7. Verificare modello, residui e conservazione della materia

Non basta ottenere una curva sovrapposta a quella osservata. Il programma verifica separatamente la qualità della ricostruzione e la coerenza delle equazioni:

  • Positività: le concentrazioni di A devono essere positive per poter applicare il logaritmo.
  • Rango: la matrice delle assorbività deve permettere di separare le due specie.
  • Conservazione: \([A]_{\mathrm{rec}}+[B]_{\mathrm{rec}}\) deve restare vicina a \(2\ \mathrm{mmol/L}\).
  • Residui: per ciascuna specie calcoliamo differenze osservato–previsto e scarto quadratico medio (RMS).
  • Riferimento sintetico: il valore stimato di \(k\) viene confrontato con quello impiegato per produrre i dati.

Per il caso incluso negli script sono stati ottenuti:

QuantitàRisultato
Costante di riferimento \(k\)\(0,045000\ \mathrm{min}^{-1}\)
Costante stimata \(\hat{k}\)\(0,04495570\ \mathrm{min}^{-1}\)
\([A]_0\) stimata\(1,99884590\ \mathrm{mmol/L}\)
Coefficiente \(R^2\) della regressione log-lineare\(0,99996245\)
RMS residui della specie A\(0,00184381\ \mathrm{mmol/L}\)
RMS residui della specie B\(0,00198044\ \mathrm{mmol/L}\)
Massima deviazione dal bilancio totale\(0,00334298\ \mathrm{mmol/L}\)

Questi valori sono relativi esclusivamente al modello sintetico scelto, e non possono essere interpretati come accuratezza garantita su dati sperimentali.

Elenco dei Dataset scientifici disponibili dopo l’analisi
I cinque Dataset iniziali e i sette derivati restano accessibili nella Session GX-TXT.

Programmazione difensiva: precondizioni, invarianti e postcondizioni

Uno script scientifico affidabile non controlla soltanto l’esistenza dei Dataset. Deve verificare che cosa significa il dato ricevuto e quale forma ha. Il terzo programma applica controlli su più livelli:

LivelloControllo effettuatoConseguenza di un errore
IngressoDataset e Variable ID presenti; tempo strettamente crescente; assi temporali ugualiIl calcolo viene interrotto prima di combinare serie incompatibili
Struttura numericaMatrice di rango 2, condizionamento accettabile, risposta di dimensioni \(2\times31\)Non si interpretano componenti o colonne sbagliate
Significato fisicoConcentrazioni finite e fisicamente ammissibili, \(\hat{k}>0\), conservazioneNon si trasformano soluzioni matematiche in risultati scientifici non plausibili
ModelloConcordanza ODE–soluzione analitica; residui, \(R^2\), scostamento dal riferimento sinteticoSi distinguono errori del calcolo da limiti della ricostruzione
PersistenzaRicevuta di pubblicazione e rilettura dei Dataset attraverso read_rangeSi controlla che il risultato registrato corrisponda a quello calcolato

Ecco un controllo sulle dimensioni presente nello script corretto:

if !isequal(size(result.value_real),[2,n]) || ...
   max(abs(result.value_imaginary(:))) > 1e-12
  error('Unexpected complex concentration result or response dimensions.');
endif

size restituisce le dimensioni dell’array; isequal verifica che siano esattamente quelle attese. (:) permette di controllare tutte le componenti immaginarie come un unico vettore. L’operatore || è un OR con valutazione breve: se il primo controllo segnala un problema, Octave non deve valutare il secondo. Altri costrutti già incontrati nel corso, come numel, any, diff, isfinite, assert ed error, diventano qui parte di una strategia unitaria di validazione.

Le soglie del programma sono criteri didattici, non standard metrologici universali. Per esempio, il limite al numero di condizionamento (< 100), \(R^2>0{,}99\), il limite di \(0{,}02\ \mathrm{mmol/L}\) per alcuni scarti e il confronto di \(\hat{k}\) con il riferimento sintetico servono a verificare questo esempio. Non costituiscono intervalli di confidenza o una propagazione dell’incertezza. Inoltre il controllo numerico della conservazione della soluzione ODE è distinto dal controllo del totale ricostruito dalle misure: il primo verifica il modello, il secondo i dati elaborati.

8. Le API pubbliche GX-TXT: come e perché le utilizziamo

Questa lezione distingue con precisione tra operazioni del linguaggio Octave e servizi scientifici del framework. Tutte le operazioni sui Dataset e sui grafici utilizzano solo API pubbliche, senza aprire file di registri o percorsi di storage del CORE.

API pubblicaOperazioneFunzione didattica
OCTAVE_SCRIPT_BRIDGE_API_v1gxtxt_api_requireVerifica la disponibilità delle API richieste prima dell’elaborazione
Script Bridgegxtxt_api_has_operationControlla se il provider espone una singola operazione
Script Bridgegxtxt_api_callEsegue una chiamata pubblica con argomenti posizionali racchiusi in una cell array
CANONICAL_DATASET_API_v2listIndividua i Dataset identificati da ID logici stabili
Canonical Dataset v2read_rangeLegge Variable ID selezionati con riga iniziale zero-based e numero di righe esplicito
NUMERIC_API_v1linear_matrix('inspect')Verifica rango e condizionamento della matrice di Beer-Lambert
Numeric v1linear_matrix('solve')Risolve il sistema per 31 colonne di dati in un’unica chiamata
Numeric v1linear_regressionCalcola pendenza, intercetta e \(R^2\) della regressione cinetica
DATASET_PUBLICATION_API_v2publish_series_batchPubblica più serie in modo atomico, con unità, metadati e provenienza
PLOT_DATASET_API_v4new_spec, validate_specCrea e valida una specifica grafica riferita ai Dataset
Plot Dataset v4upsert_plot, render, artifactsRegistra, rappresenta e rende rintracciabili i grafici persistenti

read_range riceve per esempio {'lesson16_uvvis_430nm', {'time_min','absorbance_430_au'},0,31}. Il primo valore è il Dataset ID; la cell array interna elenca i Variable ID; 0 rappresenta la prima riga e 31 il numero di osservazioni. Non passiamo percorsi CSV, riferimenti HDF5 o handle interni. Il Script Bridge traduce la risposta in strutture Octave convenzionali.

Con publish_series_batch forniamo una serie di strutture contenenti dataset_id, x_values, y_values, x_variable, y_variable, unità, origine e structured_metadata. Atomico significa che la pubblicazione dei Dataset di quel batch viene trattata come una singola operazione coerente, anziché creare risultati parziali uno a uno. Il programma controlla la ricevuta e poi legge di nuovo i Dataset pubblicati.

Per i grafici, una curva si identifica attraverso dataset_id, x_variable_id e y_variable_id. Non salviamo PNG generati da Octave al posto dei grafici scientifici: utilizziamo la famiglia nativa Plot Dataset v4, che conserva i riferimenti ai dati.

Architettura dell’esperimento: dal Dataset di ingresso alla prova del risultato

La novità di integrazione con GX-TXT è rendere espliciti i confini tra le fasi del programma:

  1. Acquisizione logica. list e read_range recuperano serie identificate da Dataset ID e Variable ID, non tramite nomi di file. Il programma verifica l’allineamento temporale e i valori finiti.
  2. Problema inverso. linear_matrix('inspect') verifica la matrice; linear_matrix('solve') ricostruisce 31 coppie di concentrazioni a partire dalle assorbanze.
  3. Identificazione e previsione. linear_regression stima i parametri; ode45 di Octave calcola una previsione del modello distinta dalla ricostruzione puntuale delle assorbanze, ma basata sui parametri stimati dalle stesse osservazioni.
  4. Validazione e pubblicazione. Solo dopo i controlli lo script invoca publish_series_batch. La ricevuta conferma il batch e read_range verifica i sette Dataset derivati.
  5. Visualizzazione persistente. new_spec, validate_spec, upsert_plot, render e artifacts collegano le curve ai Dataset pubblicati, senza trasformarle in immagini scollegate dai dati.

Il codice distingue anche identificativi, contenuti e provenienza. Per i sette Dataset derivati, source_dataset_ids indica esplicitamente i due Dataset delle assorbanze utilizzati come sorgenti della ricostruzione. structured_metadata conserva, fra le altre informazioni, \(\hat{k}\), \(\widehat{[A]_0}\), \(R^2\) e gli RMS; non è necessario inserire questi numeri nel nome del file o accedere agli archivi interni del CORE.

Un ultimo principio riguarda la ripetibilità controllata: i due script che pubblicano Dataset verificano prima che gli ID da creare non esistano già. Se si riesegue l’esperimento nella stessa Session, si rischia un conflitto di ID; per una ripetizione completa si crea quindi una nuova Session, conservando intatta la precedente. upsert_plot gestisce invece la registrazione o l’aggiornamento della specifica del grafico identificato dal suo Plot ID. Queste semantiche sono diverse e devono rimanere chiare allo studente.

9. Cinque grafici scientifici persistenti

Il terzo script L16_02_UVVis_Kinetics_Correct.m crea cinque grafici diversi, tutti consultabili tramite la scheda Plots del framework. La distinzione tra figure è intenzionale: confrontare assorbanze, concentrazioni e residui richiede scale e interpretazioni differenti.

Assorbanze a 430 e 520 nm

Assorbanze UV-Vis sintetiche alle due lunghezze d’onda
Le due assorbanze variano in modo differente perché A e B contribuiscono con coefficienti diversi.

Ricostruzione della specie A

Concentrazione di A: riferimento, ricostruzione e soluzione ODE
Le curve del riferimento analitico, delle concentrazioni ricavate dalle assorbanze e della soluzione differenziale risultano vicine.

Ricostruzione della specie B

Concentrazione di B: riferimento, ricostruzione e soluzione ODE
La crescita di B accompagna il consumo di A secondo il modello di reazione adottato.

Residui del modello

Residui cinetici delle concentrazioni di A e B
I residui mettono in evidenza differenze che diventerebbero quasi invisibili nel grafico delle concentrazioni.

Bilancio di materia

Conservazione della concentrazione totale durante la trasformazione
La somma ricostruita oscilla lievemente intorno al valore teorico costante di 2 mmol/L a causa delle perturbazioni introdotte nei segnali.

10. Eseguire l’esperimento nel Viewer Octave Scripts

  1. Aprire una nuova Session dentro un Project GX-TXT. Gli script preparatori usano ID a creazione unica, quindi per ripetere l’intero esercizio occorre una Session nuova.
  2. In Viewers → Octave Scripts, importare L16_00_Prepare_UVVis_Kinetics.m, attribuirgli uno Script ID univoco, salvarlo ed eseguirlo da Run → Open Script Runner. Controllare lo stato COMPLETED e i cinque Dataset d’ingresso.
  3. Importare L16_01_Debug_Swapped_Wavelengths.m con un altro Script ID. Aprire Run → Debug Session script, impostare un breakpoint alla riga 60, ispezionare le variabili e premere Continue. Il Job FAILED è atteso: dimostra il controllo fisico.
  4. Importare L16_02_UVVis_Kinetics_Correct.m, assegnare un terzo Script ID, salvare ed eseguire. Verificare che il Job termini in COMPLETED.
  5. Aprire Dataset per controllare i dodici Dataset e Plots per esplorare le cinque figure native e le rispettive legende.

Nella procedura si utilizzano i servizi di Session, Dataset e Plot già esposti dalla GUI e dallo Script Bridge; nessuna operazione richiede di modificare file interni del framework.

11. Esercizi di approfondimento

  1. Portare \(k\) a \(0{,}030\ \mathrm{min}^{-1}\) nello script preparatorio e confrontare le curve e la nuova stima della regressione in una Session differente.
  2. Modificare le due righe della matrice di assorbività rendendole quasi proporzionali. Studiare il numero di condizionamento e spiegare perché la separazione delle specie diventa meno affidabile.
  3. Aumentare l’ampiezza delle perturbazioni sintetiche; controllare come cambiano \(R^2\), RMS dei residui e bilancio della materia.
  4. Modificare la griglia temporale: quali righe read_range e quali attese su numero di campioni devono essere aggiornate?
  5. Confrontare l’approccio log-lineare con un fit non lineare direttamente nello spazio delle assorbanze. Quali ipotesi sul rumore cambiano?

Esercizi finali di programmazione Octave

  1. Orientamento degli array. Nel debugger confrontare size(abs430), size(abs430.') e size(measurements). Invertire intenzionalmente una trasposizione, identificare il messaggio diagnostico e ripristinare l’orientamento \(2\times31\).
  2. Cell array e campi dinamici. Spiegare perché source_y_ids{j} non è equivalente a source_y_ids(j) e perché l’accesso node.(source_y_ids{j}).values(:) consente di riutilizzare lo stesso ciclo per cinque variabili differenti.
  3. Controlli anticipati. Creare una copia dello script e introdurre una verifica per gli assi temporali prima del problema inverso. Spiegare la differenza tra fermare un input incoerente e rilevare un residuo eccessivo dopo il fitting.
  4. Modularizzazione. Come estensione, estrarre il controllo di coerenza di due assi temporali in una funzione Octave riutilizzabile, specificandone input, output e condizione di errore; conservare l’accesso ai Dataset esclusivamente attraverso le API pubbliche.

12. Conclusione: dal calcolo a un risultato riproducibile

Questo esperimento riunisce il percorso didattico: la matrice collega i segnali strumentali alle concentrazioni, la regressione fornisce un parametro cinetico, l’integrazione differenziale ne ricostruisce l’andamento nel tempo e i controlli di coerenza impediscono la pubblicazione di risultati fisicamente impossibili.

L’elemento caratteristico dell’integrazione con GX-TXT è che Dataset, unità, provenienza e grafici rimangono risorse scientifiche della Session, non semplici numeri stampati da uno script. Le funzioni del linguaggio Octave e le API pubbliche svolgono ruoli complementari e ben identificabili.

Bilancio conclusivo del corso

Con questa lezione si conclude il percorso introduttivo di 16 lezioni: dalla sintassi e dai vettori Octave siamo arrivati a un’applicazione che collega strumenti di misura simulati, algebra lineare, regressione, modelli dinamici, verifica fisica, gestione degli errori e pubblicazione di risultati tracciabili. Il risultato più importante non è una singola costante cinetica, ma la capacità di spiegare e verificare ogni passaggio che collega l’osservazione a quella costante.

Il progetto didattico resta estendibile con esercizi e studi di caso successivi; la Lezione 16 chiude il ciclo previsto senza implicare la fine dello sviluppo di GX-TXT o delle applicazioni scientifiche con GNU Octave.

Versione GX-TXT e documentazione pubblica

Framework utilizzato: GX-TXT 0.9.8.10-dev-112 Release 2 P009, versione disponibile su GitHub al momento della lezione. Commit sorgente verificato: 059ff073eb43770292b6609f7c0cc3cbc811710d. Data di riferimento: 15 novembre 2026.

Materiali didattici

Gli script GNU Octave completi, commentati in inglese, sono inclusi nel pacchetto scaricabile della Lezione 16: L16_00_Prepare_UVVis_Kinetics.m, L16_01_Debug_Swapped_Wavelengths.m e L16_02_UVVis_Kinetics_Correct.m. I sorgenti sono inoltre consultabili nei riquadri espandibili dell’articolo.

Script GNU Octave completi

Espandi ogni riquadro per leggere e copiare il sorgente completo.

Programma 00 — L16_00_Prepare_UVVis_Kinetics.m
% Lesson 16 - Publish deterministic UV-Vis measurements and exact kinetic references.
% Course: GNU Octave with GX-TXT | DEV112 Release 2 + P009
% GitHub source commit: 059ff073eb43770292b6609f7c0cc3cbc811710d
% SPDX-License-Identifier: GPL-3.0-or-later
%
% Run this create-only preparation script in a fresh managed GX-TXT Session.
% All Datasets are created and verified through public GX-TXT APIs.
% The signals are synthetic, not experimental observations.

dataset_api = 'CANONICAL_DATASET_API_v2';
publication_api = 'DATASET_PUBLICATION_API_v2';
gxtxt_api_require({dataset_api, publication_api});
required = {dataset_api, 'list'; dataset_api, 'read_range'; ...
            publication_api, 'publish_series_batch'};
for j = 1:rows(required)
  if !gxtxt_api_has_operation(required{j,1}, required{j,2})
    error('Required public operation unavailable: %s/%s.', ...
          required{j,1}, required{j,2});
  endif
endfor

% A -> B first-order reaction. Concentrations are in mmol/L and time in min.
time_min = (0:2:60)';
initial_A_mmol_L = 2.0;
rate_min_inverse = 0.045;
path_length_cm = 1.0;
epsilon_L_mmol_cm = [0.75, 0.20; 0.12, 0.62];
n = numel(time_min);
assert(n == 31 && all(diff(time_min) > 0));
assert(rank(epsilon_L_mmol_cm) == 2);

% Exact analytical reference serves as ground truth for this synthetic example.
reference_A = initial_A_mmol_L .* exp(-rate_min_inverse .* time_min);
reference_B = initial_A_mmol_L - reference_A;
reference_total = reference_A + reference_B;

% Beer-Lambert absorbance at 430 and 520 nm, with fixed instrumental deviations.
% The deterministic perturbations make the example repeatable without a PRNG.
absorbance_430 = path_length_cm .* ...
  (epsilon_L_mmol_cm(1,1).*reference_A + epsilon_L_mmol_cm(1,2).*reference_B) ...
  + 0.0015 .* sin(0.40.*time_min) + 0.0008 .* cos(0.13.*time_min);
absorbance_520 = path_length_cm .* ...
  (epsilon_L_mmol_cm(2,1).*reference_A + epsilon_L_mmol_cm(2,2).*reference_B) ...
  + 0.0013 .* cos(0.37.*time_min + 0.2) - 0.0006 .* sin(0.16.*time_min);
assert(all(absorbance_430 > 0) && all(absorbance_520 > 0));
assert(max(abs(reference_total - initial_A_mmol_L)) < 1e-12);

dataset_ids = {'lesson16_uvvis_430nm','lesson16_uvvis_520nm', ...
               'lesson16_reference_A','lesson16_reference_B', ...
               'lesson16_reference_total'};
existing_ids = gxtxt_api_call(dataset_api, 'list', {});
for j = 1:numel(dataset_ids)
  if any(strcmp(existing_ids, dataset_ids{j}))
    error('Dataset already exists: %s. Use a fresh Session.', dataset_ids{j});
  endif
endfor

% Stable Variable IDs, explicit units and compatible dataset contracts.
time_variable = struct('variable_id','time_min','name','time_min', ...
  'display_label','Elapsed time','unit','min','dtype','float64', ...
  'value_kind','number','semantic_source','generator');
abs430_variable = struct('variable_id','absorbance_430_au', ...
  'name','absorbance_430_au','display_label','Absorbance at 430 nm', ...
  'unit','1','dtype','float64','value_kind','number', ...
  'semantic_source','generator');
abs520_variable = struct('variable_id','absorbance_520_au', ...
  'name','absorbance_520_au','display_label','Absorbance at 520 nm', ...
  'unit','1','dtype','float64','value_kind','number', ...
  'semantic_source','generator');
refA_variable = struct('variable_id','concentration_A_mmol_L', ...
  'name','concentration_A_mmol_L','display_label','Reference concentration A', ...
  'unit','mmol/L','dtype','float64','value_kind','number', ...
  'semantic_source','generator');
refB_variable = struct('variable_id','concentration_B_mmol_L', ...
  'name','concentration_B_mmol_L','display_label','Reference concentration B', ...
  'unit','mmol/L','dtype','float64','value_kind','number', ...
  'semantic_source','generator');
total_variable = struct('variable_id','total_mmol_L', ...
  'name','total_mmol_L','display_label','Reference total concentration', ...
  'unit','mmol/L','dtype','float64','value_kind','number', ...
  'semantic_source','generator');
values = {absorbance_430, absorbance_520, reference_A, reference_B, reference_total};
y_variables = {abs430_variable, abs520_variable, refA_variable, refB_variable, total_variable};
descriptions = {'Synthetic UV-Vis absorbance at 430 nm', ...
  'Synthetic UV-Vis absorbance at 520 nm', ...
  'Exact first-order analytical concentration of A', ...
  'Exact first-order analytical concentration of B', ...
  'Exact conserved molar concentration'};

series = cell(1,numel(dataset_ids));
for j = 1:numel(dataset_ids)
  metadata = struct();
  metadata.('lesson16.synthetic') = true;
  metadata.('lesson16.reaction') = 'A_to_B_first_order';
  metadata.('lesson16.rate_min_inverse') = rate_min_inverse;
  metadata.('lesson16.initial_A_mmol_L') = initial_A_mmol_L;
  metadata.('lesson16.path_length_cm') = path_length_cm;
  metadata.('lesson16.epsilon430_A') = epsilon_L_mmol_cm(1,1);
  metadata.('lesson16.epsilon430_B') = epsilon_L_mmol_cm(1,2);
  metadata.('lesson16.epsilon520_A') = epsilon_L_mmol_cm(2,1);
  metadata.('lesson16.epsilon520_B') = epsilon_L_mmol_cm(2,2);
  metadata.('lesson16.series_kind') = descriptions{j};
  series{j} = struct('dataset_id',dataset_ids{j}, ...
    'contract','table.generic','storage','auto', ...
    'x_values',time_min,'y_values',values{j}, ...
    'x_variable',time_variable,'y_variable',y_variables{j}, ...
    'source','GX-TXT GNU Octave Lesson 16','producer_version','1.0.0', ...
    'provenance','Deterministic first-order and Beer-Lambert synthetic generator', ...
    'notes',descriptions{j},'structured_metadata',metadata);
endfor
receipt = gxtxt_api_call(publication_api,'publish_series_batch', ...
  {struct('series',{series})});
if !receipt.atomic || receipt.output_count != numel(dataset_ids)
  error('Atomic publication did not confirm all five source Datasets.');
endif
for j = 1:numel(dataset_ids)
  check = gxtxt_api_call(dataset_api, 'read_range', ...
    {dataset_ids{j},{'time_min',y_variables{j}.variable_id},0,n});
  observed_time = check.time_min.values(:);
  observed_values = check.(y_variables{j}.variable_id).values(:);
  if numel(observed_values) != n || ...
     max(abs(observed_time-time_min)) > 1e-10 || ...
     max(abs(observed_values-values{j})) > 1e-10
    error('Public Dataset read-back failed for %s.',dataset_ids{j});
  endif
endfor
fprintf('PASS: 5 synthetic UV-Vis and analytical reference Datasets published.\n');
fprintf('Ground-truth first-order rate k=%.6f min^-1, initial A=%.3f mmol/L.\n', ...
  rate_min_inverse, initial_A_mmol_L);
fprintf('Measurement grid: %d points, from %.0f to %.0f min.\n', ...
  n,time_min(1),time_min(end));
Programma 01 — L16_01_Debug_Swapped_Wavelengths.m
% Lesson 16 - Deliberately swap the wavelengths to debug a scientific error.
% Course: GNU Octave with GX-TXT | DEV112 Release 2 + P009
% GitHub source commit: 059ff073eb43770292b6609f7c0cc3cbc811710d
% SPDX-License-Identifier: GPL-3.0-or-later
%
% Run after L16_00 using Run > Debug Session script.
% Add a breakpoint before the physical consistency check and inspect c_A_bad.
% Expected outcome: FAILED, without publishing any new Dataset.

dataset_api = 'CANONICAL_DATASET_API_v2';
numeric_api = 'NUMERIC_API_v1';
gxtxt_api_require({dataset_api, ...
  'NUMERIC_API_v1@1:math.numeric+complex_linear_algebra'});
required = {dataset_api,'list'; dataset_api,'read_range'; ...
            numeric_api,'linear_matrix'};
for j = 1:rows(required)
  if !gxtxt_api_has_operation(required{j,1},required{j,2})
    error('Required public operation unavailable: %s/%s.', ...
      required{j,1},required{j,2});
  endif
endfor

source_ids = {'lesson16_uvvis_430nm','lesson16_uvvis_520nm'};
available_ids = gxtxt_api_call(dataset_api,'list',{});
for j = 1:numel(source_ids)
  if !any(strcmp(available_ids,source_ids{j}))
    error('Missing source Dataset %s. Run L16_00 first.',source_ids{j});
  endif
endfor
n = 31;
data430 = gxtxt_api_call(dataset_api,'read_range', ...
  {source_ids{1},{'time_min','absorbance_430_au'},0,n});
data520 = gxtxt_api_call(dataset_api,'read_range', ...
  {source_ids{2},{'time_min','absorbance_520_au'},0,n});
time_min = data430.time_min.values(:);
A430 = data430.absorbance_430_au.values(:);
A520 = data520.absorbance_520_au.values(:);
if numel(time_min) != n || ...
   max(abs(data520.time_min.values(:)-time_min)) > 1e-12
  error('Time axes are not aligned.');
endif

% Correct molar absorptivities, with rows in the order 430 nm and 520 nm.
epsilon = [0.75,0.20;0.12,0.62];
matrix_node = struct('real',epsilon,'imaginary',zeros(size(epsilon)));

% BUG: the measured 520 nm signal is placed in the 430 nm row, and vice versa.
wrong_absorbances = [A520.'; A430.'];
bad_rhs = struct('real',wrong_absorbances, ...
                 'imaginary',zeros(size(wrong_absorbances)));
result = gxtxt_api_call(numeric_api,'linear_matrix', ...
  {'solve',matrix_node,bad_rhs});
c_A_bad = result.value_real(1,:).';
c_B_bad = result.value_real(2,:).';

% BREAKPOINT: inspect wrong_absorbances, c_A_bad(1), min(c_A_bad), c_B_bad.
% A negative concentration is not an acceptable result of this model.
fprintf('Swapped wavelengths: initial reconstructed A=%.6f mmol/L.\n', ...
  c_A_bad(1));
if any(c_A_bad < -1e-9) || any(c_B_bad < -1e-9)
  error('Physical validation failed: swapped UV-Vis wavelengths yield negative concentrations.');
endif
error('Expected the deliberate wavelength swap to fail physical validation.');
Programma 02 — L16_02_UVVis_Kinetics_Correct.m
% Lesson 16 - Complete synthetic UV-Vis kinetics analysis with GX-TXT.
% Course: GNU Octave with GX-TXT | DEV112 Release 2 + P009
% GitHub source commit: 059ff073eb43770292b6609f7c0cc3cbc811710d
% SPDX-License-Identifier: GPL-3.0-or-later
%
% Run after L16_00 in a managed GX-TXT Session.
% The Dataset, numerical linear/regression, publication and plot operations
% all use versioned public GX-TXT APIs through the Octave Script Bridge.
% ode45 and the array expressions are GNU Octave language operations.

dataset_api = 'CANONICAL_DATASET_API_v2';
numeric_api = 'NUMERIC_API_v1';
publication_api = 'DATASET_PUBLICATION_API_v2';
plot_api = 'PLOT_DATASET_API_v4';
gxtxt_api_require({dataset_api, ...
  'NUMERIC_API_v1@1:math.numeric+complex_linear_algebra', ...
  publication_api,plot_api});
required = {dataset_api,'list';dataset_api,'read_range'; ...
  numeric_api,'linear_matrix';numeric_api,'linear_regression'; ...
  publication_api,'publish_series_batch'; ...
  plot_api,'new_spec';plot_api,'validate_spec'; ...
  plot_api,'upsert_plot';plot_api,'render';plot_api,'artifacts'};
for j=1:rows(required)
  if !gxtxt_api_has_operation(required{j,1},required{j,2})
    error('Missing public GX-TXT operation: %s/%s.',required{j,1},required{j,2});
  endif
endfor

% 1. Read five canonical source Datasets by stable Dataset and Variable IDs.
source_ids={'lesson16_uvvis_430nm','lesson16_uvvis_520nm', ...
            'lesson16_reference_A','lesson16_reference_B', ...
            'lesson16_reference_total'};
source_y_ids={'absorbance_430_au','absorbance_520_au', ...
              'concentration_A_mmol_L','concentration_B_mmol_L','total_mmol_L'};
existing_ids=gxtxt_api_call(dataset_api,'list',{});
for j=1:numel(source_ids)
  if !any(strcmp(existing_ids,source_ids{j}))
    error('Missing source Dataset %s. Run L16_00 first.',source_ids{j});
  endif
endfor
n=31;
source_values=cell(1,numel(source_ids));
for j=1:numel(source_ids)
  node=gxtxt_api_call(dataset_api,'read_range', ...
    {source_ids{j},{'time_min',source_y_ids{j}},0,n});
  tx=node.time_min.values(:);
  if j==1
    time_min=tx;
  elseif numel(tx)!=n || max(abs(tx-time_min))>1e-12
    error('Source time axes differ; the kinetic model needs aligned observations.');
  endif
  source_values{j}=node.(source_y_ids{j}).values(:);
  if numel(source_values{j})!=n || any(!isfinite(source_values{j}))
    error('Nonfinite or incomplete source values in %s.',source_ids{j});
  endif
endfor
if numel(time_min)!=n || any(diff(time_min)<=0)
  error('The time grid is not strictly increasing.');
endif
abs430=source_values{1};
abs520=source_values{2};
reference_A=source_values{3};
reference_B=source_values{4};
reference_total=source_values{5};
assert(max(abs(reference_A+reference_B-reference_total))<1e-12);

% 2. Beer-Lambert matrix: rows are wavelengths, columns are compounds A and B.
% E has units L/(mmol*cm), path length has cm and concentrations are mmol/L.
path_length_cm=1.0;
epsilon_L_mmol_cm=[0.75,0.20;0.12,0.62];
design=epsilon_L_mmol_cm*path_length_cm;
measurements=[abs430.';abs520.'];
design_node=struct('real',design,'imaginary',zeros(size(design)));
rhs_node=struct('real',measurements,'imaginary',zeros(size(measurements)));
matrix_info=gxtxt_api_call(numeric_api,'linear_matrix', ...
  {'inspect',design_node,[]});
if matrix_info.rank!=2 || matrix_info.condition_number>=100
  error('The Beer-Lambert matrix is rank-deficient or poorly conditioned.');
endif

% 3. Solve the two-by-two system for all times in a single multi-RHS call.
result=gxtxt_api_call(numeric_api,'linear_matrix', ...
  {'solve',design_node,rhs_node});
if !isequal(size(result.value_real),[2,n]) || ...
   max(abs(result.value_imaginary(:)))>1e-12
  error('Unexpected complex concentration result or response dimensions.');
endif
recovered_A=result.value_real(1,:).';
recovered_B=result.value_real(2,:).';
if any(recovered_A<=0) || any(recovered_B<0)
  error('Negative or zero physical concentrations: check wavelength ordering.');
endif
reconstruction=design*[recovered_A.';recovered_B.'];
if max(abs(reconstruction(:)-measurements(:)))>1e-10
  error('Beer-Lambert algebraic reconstruction failed.');
endif
total_recovered=recovered_A+recovered_B;
max_mass_error=max(abs(total_recovered-reference_total));

% 4. Estimate first-order rate by public regression of ln([A]) vs time.
% The log-linear approximation is educational; noise is in absorbance space.
fit=gxtxt_api_call(numeric_api,'linear_regression', ...
  {time_min,log(recovered_A),[],struct('intercept',true)});
estimated_k_min_inverse=-fit.slope;
estimated_A0_mmol_L=exp(fit.intercept);
if estimated_k_min_inverse<=0 || estimated_A0_mmol_L<=0 || ...
   !isfinite(estimated_k_min_inverse) || fit.r_squared<0.99
  error('Regression did not yield a plausible first-order kinetic law.');
endif

% 5. Integrate the coupled kinetic system with GNU Octave ode45.
% dnA/dt = -k*A, dnB/dt = k*A; initial B is zero in the chosen model.
rhs=@(t,y) [-estimated_k_min_inverse*y(1);estimated_k_min_inverse*y(1)];
ode_options=odeset('RelTol',1e-10,'AbsTol',1e-11);
[time_solution,state_solution]=ode45(rhs,time_min, ...
  [estimated_A0_mmol_L;0],ode_options);
if numel(time_solution)!=n || max(abs(time_solution-time_min))>1e-8
  error('ode45 did not return the requested observation grid.');
endif
model_A=state_solution(:,1);
model_B=state_solution(:,2);
analytic_A=estimated_A0_mmol_L.*exp(-estimated_k_min_inverse.*time_min);
if max(abs(model_A-analytic_A))>1e-7 || ...
   max(abs(model_A+model_B-estimated_A0_mmol_L))>1e-8
  error('ODE solution violates the independent analytical or mass-balance test.');
endif

% 6. Quantify model residuals and compare with synthetic ground truth.
residual_A=recovered_A-model_A;
residual_B=recovered_B-model_B;
rms_A=sqrt(mean(residual_A.^2));
rms_B=sqrt(mean(residual_B.^2));
true_k_min_inverse=0.045;
max_reference_error=max([abs(recovered_A-reference_A); ...
                         abs(recovered_B-reference_B)]);
if max_mass_error>0.02 || max_reference_error>0.02 || ...
   rms_A>0.02 || rms_B>0.02 || ...
   abs(estimated_k_min_inverse-true_k_min_inverse)>0.005
  error('Kinetic reconstruction failed the specified scientific validation.');
endif
fprintf('Estimated k=%.8f min^-1; A(0)=%.6f mmol/L; R^2=%.8f.\n', ...
  estimated_k_min_inverse,estimated_A0_mmol_L,fit.r_squared);
fprintf('Residual RMS A=%.8f, B=%.8f mmol/L; max mass error=%.8f mmol/L.\n', ...
  rms_A,rms_B,max_mass_error);
fprintf('Design rank=%d; condition number=%.6f.\n', ...
  matrix_info.rank,matrix_info.condition_number);

% 7. Publish seven derived canonical series as one atomic GX-TXT operation.
derived_ids={'lesson16_recovered_A','lesson16_recovered_B', ...
  'lesson16_model_A','lesson16_model_B', ...
  'lesson16_residual_A','lesson16_residual_B', ...
  'lesson16_total_recovered'};
for j=1:numel(derived_ids)
  if any(strcmp(existing_ids,derived_ids{j}))
    error('Derived Dataset already exists: %s. Use a new Session.',derived_ids{j});
  endif
endfor
time_var=struct('variable_id','time_min','name','time_min', ...
  'display_label','Elapsed time','unit','min','dtype','float64', ...
  'value_kind','number','semantic_source','plugin');
A_var=struct('variable_id','concentration_A_mmol_L', ...
  'name','concentration_A_mmol_L','display_label','Concentration of A', ...
  'unit','mmol/L','dtype','float64','value_kind','number', ...
  'semantic_source','plugin');
B_var=struct('variable_id','concentration_B_mmol_L', ...
  'name','concentration_B_mmol_L','display_label','Concentration of B', ...
  'unit','mmol/L','dtype','float64','value_kind','number', ...
  'semantic_source','plugin');
resA_var=struct('variable_id','residual_A_mmol_L', ...
  'name','residual_A_mmol_L','display_label','Residual of A', ...
  'unit','mmol/L','dtype','float64','value_kind','number', ...
  'semantic_source','plugin');
resB_var=struct('variable_id','residual_B_mmol_L', ...
  'name','residual_B_mmol_L','display_label','Residual of B', ...
  'unit','mmol/L','dtype','float64','value_kind','number', ...
  'semantic_source','plugin');
total_var=struct('variable_id','total_mmol_L', ...
  'name','total_mmol_L','display_label','Total recovered concentration', ...
  'unit','mmol/L','dtype','float64','value_kind','number', ...
  'semantic_source','plugin');
derived_y={recovered_A,recovered_B,model_A,model_B,residual_A,residual_B, ...
  total_recovered};
derived_vars={A_var,B_var,A_var,B_var,resA_var,resB_var,total_var};
notes={'Reconstructed A from the two UV-Vis wavelengths', ...
       'Reconstructed B from the two UV-Vis wavelengths', ...
       'Coupled first-order ODE prediction for A', ...
       'Coupled first-order ODE prediction for B', ...
       'Reconstructed minus predicted A concentration', ...
       'Reconstructed minus predicted B concentration', ...
       'Recovered A+B mass-balance trace'};
derived=cell(1,numel(derived_ids));
for j=1:numel(derived_ids)
  meta=struct();
  meta.('lesson16.synthetic_inputs')=true;
  meta.('lesson16.analysis')='BeerLambert_linear_solve_log_regression_ode45';
  meta.('lesson16.k_fit_min_inverse')=estimated_k_min_inverse;
  meta.('lesson16.initial_fit_mmol_L')=estimated_A0_mmol_L;
  meta.('lesson16.fit_r_squared')=fit.r_squared;
  meta.('lesson16.max_mass_error_mmol_L')=max_mass_error;
  meta.('lesson16.rms_A_mmol_L')=rms_A;
  meta.('lesson16.rms_B_mmol_L')=rms_B;
  meta.('lesson16.output_role')=notes{j};
  derived{j}=struct('dataset_id',derived_ids{j}, ...
    'contract','table.generic','storage','auto', ...
    'x_values',time_min,'y_values',derived_y{j}, ...
    'x_variable',time_var,'y_variable',derived_vars{j}, ...
    'source','GX-TXT GNU Octave Lesson 16', ...
    'producer_version','1.0.0', ...
    'source_dataset_ids',{source_ids(1:2)}, ...
    'provenance','Public linear_matrix, linear_regression and GNU Octave ode45', ...
    'notes',notes{j},'structured_metadata',meta);
endfor
publish=gxtxt_api_call(publication_api,'publish_series_batch', ...
  {struct('series',{derived})});
if !publish.atomic || publish.output_count!=numel(derived_ids)
  error('Atomic publication did not confirm seven derived Datasets.');
endif
for j=1:numel(derived_ids)
  check=gxtxt_api_call(dataset_api,'read_range', ...
    {derived_ids{j},{'time_min',derived_vars{j}.variable_id},0,n});
  yy=check.(derived_vars{j}.variable_id).values(:);
  if numel(yy)!=n || max(abs(yy-derived_y{j}))>1e-9 || ...
     max(abs(check.time_min.values(:)-time_min))>1e-9
    error('Canonical read-back mismatch for Dataset %s.',derived_ids{j});
  endif
endfor

% 8. Create five persistent native GX-TXT Plot Dataset v4 figures.
% All visible traces resolve stable Dataset IDs and Variable IDs.
plot_defs={
 'lesson16_absorbances','Synthetic UV-Vis absorbances', ...
 {'430 nm','520 nm'}, ...
 {'lesson16_uvvis_430nm','lesson16_uvvis_520nm'}, ...
 {'absorbance_430_au','absorbance_520_au'},'Absorbance [1]';
 'lesson16_kinetics_A','First-order kinetics: compound A', ...
 {'Analytical reference','UV-Vis reconstruction','ODE prediction'}, ...
 {'lesson16_reference_A','lesson16_recovered_A','lesson16_model_A'}, ...
 {'concentration_A_mmol_L','concentration_A_mmol_L','concentration_A_mmol_L'}, ...
 'Concentration of A [mmol/L]';
 'lesson16_kinetics_B','First-order kinetics: compound B', ...
 {'Analytical reference','UV-Vis reconstruction','ODE prediction'}, ...
 {'lesson16_reference_B','lesson16_recovered_B','lesson16_model_B'}, ...
 {'concentration_B_mmol_L','concentration_B_mmol_L','concentration_B_mmol_L'}, ...
 'Concentration of B [mmol/L]';
 'lesson16_concentration_residuals','First-order kinetic residuals', ...
 {'Compound A','Compound B'}, ...
 {'lesson16_residual_A','lesson16_residual_B'}, ...
 {'residual_A_mmol_L','residual_B_mmol_L'},'Measured - predicted [mmol/L]';
 'lesson16_mass_balance','Mass balance throughout reaction', ...
 {'Recovered total','Analytical total'}, ...
 {'lesson16_total_recovered','lesson16_reference_total'}, ...
 {'total_mmol_L','total_mmol_L'},'Total concentration [mmol/L]'
};
for p=1:rows(plot_defs)
  plot_id=plot_defs{p,1};
  plot_title=plot_defs{p,2};
  labels=plot_defs{p,3};
  dataset_list=plot_defs{p,4};
  variable_list=plot_defs{p,5};
  plot_spec=gxtxt_api_call(plot_api,'new_spec',{'plot.dataset.xy',plot_title});
  panel=plot_spec.panels{1};
  panel.id=['kinetic_panel_',num2str(p)];
  panel.title=plot_title;
  panel.axes=struct('x',struct('label','Elapsed time [min]','scale','linear'), ...
    'y_left',struct('label',plot_defs{p,6},'scale','linear'));
  curves=cell(1,numel(labels));
  for j=1:numel(labels)
    curves{j}=struct('id',['trace_',num2str(j)],'label',labels{j}, ...
      'dataset_id',dataset_list{j},'x_variable_id','time_min', ...
      'y_variable_id',variable_list{j},'axis','left','kind','line');
  endfor
  panel.series=curves;
  plot_spec.panels={panel};
  if !gxtxt_api_call(plot_api,'validate_spec',{plot_spec})
    error('Plot Dataset specification invalid: %s.',plot_id);
  endif
  plot_ref=gxtxt_api_call(plot_api,'upsert_plot',{plot_id,plot_spec});
  gxtxt_api_call(plot_api,'render',{plot_ref});
  artifacts=gxtxt_api_call(plot_api,'artifacts',{plot_ref});
  fprintf('Created persistent GX-TXT plot: %s.\n',plot_id);
endfor
fprintf('PASS: 7 derived canonical Datasets, 5 native plots, 1 validated kinetic model.\n');

#algebra lineare #Beer-Lambert #cinetica chimica #Dataset #debugger #GNU Octave #GX-TXT #ode45 #Plot Dataset #regressione #Script Bridge #spettrofotometria #UV-Vis

Altre tappe del progetto

Lascia un commento

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