GNU Octave e GX-TXT: calcolo complesso e diagrammi di Bode con Numeric API v1
Nella Lezione 15 del corso GNU Octave con GX-TXT abbiamo calcolato la risposta in frequenza di un circuito RLC serie usando principalmente le funzioni native del linguaggio. Le API pubbliche del framework servivano a leggere e pubblicare Dataset e a visualizzarli. Questo approfondimento riprende lo stesso modello fisico, ma sposta l’attenzione sulle operazioni numeriche pubbliche del modulo math.numeric: scopriamo come si invocano, che cosa restituiscono, quali errori controllano e quando non sono intercambiabili con le funzioni di Octave o con lo Script Bridge.
1. Che cosa aggiunge una Numeric API alle funzioni native di Octave?
GNU Octave permette già di scrivere abs(z), angle(z), log10(x) e di dividere numeri complessi. GX-TXT non sostituisce queste capacità: la NUMERIC_API_v1 espone un servizio matematico pubblico con nomi di operazione, argomenti e risultati espliciti. Lo scopo è permettere ai componenti del framework di condividere calcoli e controlli documentati, senza ricorrere a comandi privati o manipolare file interni.
Questo non significa che l’API produca necessariamente una precisione maggiore di Octave. La sua utilità è soprattutto contrattuale: forma degli array, politiche sui valori non finiti, separazione delle parti complesse, struttura del risultato e gestione degli errori. Anche usando il framework, Octave rimane il linguaggio con cui costruiamo l’esperimento, selezioniamo i campioni ed eseguiamo controlli indipendenti.
Il percorso si collega alle lezioni già pubblicate: Lezione 02 — variabili e operatori, Lezione 07 — Dataset e Numeric API, Lezione 13 — FFT e fase e Lezione 15 — circuiti RLC e diagrammi di Bode.
2. La versione e il confine tra le due interfacce pubbliche
| Riferimento | Versione utilizzata |
|---|---|
| Framework GX-TXT | 0.9.8.10-dev-112, Release 2, P011 |
| Release GitHub | v0.9.8.10-dev-112-r2-p011 |
| Commit sorgente | 9f79a30661d6a3fe4a05d723be66aabd06ef2ebe |
| Modulo scientifico | math.numeric, NUMERIC_API_v1 |
| Linguaggio eseguito | GNU Octave 9.4.0 |
| Licenza del codice | GPL-3.0-or-later |
È fondamentale distinguere due punti di accesso.
- Il binding Octave pubblico del modulo Numeric si invoca con
gxtxt_numeric_v1('operazione', ...). Riceve gli array previsti dal contratto del modulo e restituisce strutture Octave. - Il managed Octave Script Bridge si invoca con
gxtxt_api_call('NUMERIC_API_v1','operazione',{...})e richiede che l’operazione sia effettivamente registrata nel catalogo Script Bridge. Per alcune operazioni sui reali, gli operandi sono descrittori conkindevalue.
Nel commit P011, array_unary e array_binary risultano esposte da entrambi i percorsi, ma complex_unary, complex_binary e unwrap non compaiono come operazioni omonime nel binding dello Script Bridge verificato. Sono presenti nell’interfaccia Octave diretta del modulo Numeric. Non è quindi corretto convertire automaticamente una chiamata gxtxt_numeric_v1('complex_binary',...) in gxtxt_api_call('NUMERIC_API_v1','complex_binary',...).
L’esperimento completo qui allegato utilizza l’interfaccia Octave pubblica diretta: è stato eseguito sulla copia isolata del framework P011 e anche con il file del binding prelevato senza modifiche dal commit GitHub indicato. Non lo presentiamo come un Job Script Workspace collaudato con queste operazioni complesse. La lettura e la pubblicazione di Dataset rimangono gli argomenti delle lezioni precedenti.
3. Il circuito RLC: dalla legge fisica ai numeri complessi
Consideriamo una resistenza \(R=20\ \Omega\), un’induttanza \(L=10\ \mathrm{mH}=0{,}010\ \mathrm H\) e una capacità \(C=1\ \mu\mathrm F=10^{-6}\ \mathrm F\), collegate in serie. Applichiamo una tensione sinusoidale e misuriamo l’uscita ai capi della resistenza, mantenendo la stessa convenzione di polarità dell’ingresso.
Con pulsazione \(\omega=2\pi f\), le impedenze sono:
\[ Z_R=R,\qquad Z_L=j\omega L,\qquad Z_C=\frac{1}{j\omega C}. \]
In regime sinusoidale stazionario tutti i componenti sono attraversati dalla stessa corrente. Applicando la legge di Kirchhoff e dividendo il fasore della tensione resistiva per quello d’ingresso otteniamo:
\[ H(j\omega)=\frac{\widehat V_R}{\widehat V_{\mathrm{in}}} =\frac{R}{R+jX(\omega)},\qquad X(\omega)=\omega L-\frac{1}{\omega C}. \]
La funzione di trasferimento complessa contiene due informazioni: \(|H|\) è il rapporto delle ampiezze di tensione e \(\arg H\) è lo sfasamento dell’uscita rispetto all’ingresso. Una diversa scelta dei morsetti di uscita cambierebbe la funzione. Il modello è ideale: non contiene perdite parassite né incertezze dei componenti.
4. La struttura dei risultati: values, real e imaginary
La funzione pubblica non restituisce sempre un semplice vettore: il risultato è una struttura con campi documentati. Per le operazioni reali troviamo generalmente values; per un risultato complesso ottenuto con complex_binary troviamo real e imaginary.
| Operazione pubblica | Scopo | Risultato da leggere |
|---|---|---|
array_binary('multiply',a,b) | Moltiplicazione reale elemento per elemento | .values |
array_binary('divide',a,b) | Divisione reale | .values |
array_binary('subtract',a,b) | Differenza reale | .values |
array_unary('log10',x) | Logaritmo decimale reale | .values |
complex_binary('divide',reA,imA,reB,imB) | Divisione fra numeri complessi | .real, .imaginary |
complex_unary('magnitude',re,im) | Modulo complesso | .values |
complex_unary('phase_rad',re,im) | Fase in radianti | .values |
complex_unary('phase_deg',re,im) | Fase in gradi | .values |
unwrap(phase, options) | Rimozione dei salti di periodo | .values, .period |
Per esempio, transfer.imaginary è corretto, mentre transfer.imag non è un campo del risultato di complex_binary. La rappresentazione a parti separate (split-complex) è un contratto dati, non un’approssimazione matematica: possiamo sempre ricostruire concettualmente \(z=\mathrm{real}+j\,\mathrm{imaginary}\).
Le operazioni elementari trattano esplicitamente la compatibilità di forma. Uno scalare può essere espanso per operare con un vettore; due array non scalari devono essere compatibili. Per impostazione predefinita i dati non finiti e i risultati fuori dominio reale vengono rifiutati. Queste API non convertono automaticamente mH in H o radianti in gradi se non è richiesta l’operazione appropriata: le unità fisiche devono essere coerenti prima del calcolo.
5. Esperimento: costruire la reattanza con array_binary
Generiamo un vettore logaritmico di 401 frequenze e inseriamo il valore teorico esatto della risonanza, ottenendo 402 campioni. logspace e sort costruiscono il vettore in Octave; le operazioni numeriche sulla pulsazione e sulle reattanze usano il servizio GX-TXT.
R_ohm = 20;
L_h = 10e-3;
C_f = 1e-6;
f0_hz = 1/(2*pi*sqrt(L_h*C_f));
frequency_hz = sort([logspace(2,4.5,401)'; f0_hz]);
omega_result = gxtxt_numeric_v1('array_binary', ...
'multiply',2*pi,frequency_hz);
omega = omega_result.values;
XL = gxtxt_numeric_v1('array_binary','multiply',L_h,omega);
omega_C = gxtxt_numeric_v1('array_binary','multiply',C_f,omega);
XC_mag = gxtxt_numeric_v1('array_binary','divide',1,omega_C.values);
reactance = gxtxt_numeric_v1('array_binary', ...
'subtract',XL.values,XC_mag.values);
X_ohm = reactance.values;
Le operazioni riproducono direttamente \(\omega=2\pi f\), \(X_L=\omega L\), \(|X_C|=1/(\omega C)\) e \(X=X_L-|X_C|\). Poiché il condensatore richiede una divisione per \(\omega\), la nostra griglia non contiene \(f=0\). Il segno di \(X\) indica se prevale il comportamento capacitivo (negativo) oppure induttivo (positivo).
6. complex_binary: divisione fra impedenze
Calcoliamo ora la funzione di trasferimento \(H=R/(R+jX)\). Il contratto complex_binary riceve quattro array che rappresentano le parti reali e immaginarie dei due operandi, oltre al nome dell’azione richiesta:
denominator_real = R_ohm*ones(size(X_ohm));
transfer = gxtxt_numeric_v1('complex_binary','divide', ...
R_ohm,0,denominator_real,X_ohm);
Il numeratore ha parte reale \(R\) e parte immaginaria zero. Il denominatore ha parte reale \(R\) e parte immaginaria \(X\). Possiamo capire il risultato con un controllo a mano: scegliendo \(R=20\ \Omega\) e \(X=10\ \Omega\),
\[ \frac{20}{20+j10}=\frac{20(20-j10)}{20^2+10^2}=0{,}8-j0{,}4. \]
Non basta conservare il numero reale 0,8: la parte immaginaria −0,4 è necessaria per ricostruire il modulo (circa 0,8944) e il ritardo di fase dell’uscita.
7. complex_unary, decibel e unwrap
Per ogni frequenza richiediamo due proiezioni fisiche della stessa funzione complessa: il modulo \(|H|\) e la fase \(\varphi=\arg H\).
magnitude = gxtxt_numeric_v1('complex_unary','magnitude', ...
transfer.real,transfer.imaginary);
phase_degrees = gxtxt_numeric_v1('complex_unary','phase_deg', ...
transfer.real,transfer.imaginary);
log_magnitude = gxtxt_numeric_v1('array_unary','log10', ...
magnitude.values);
decibels = gxtxt_numeric_v1('array_binary','multiply', ...
20,log_magnitude.values);
gain_db = decibels.values;
phase_deg = phase_degrees.values;
Il guadagno del diagramma di Bode si calcola come
\[ G_{\mathrm{dB}}(f)=20\log_{10}|H(j2\pi f)|. \]
Il fattore 20 si usa perché stiamo confrontando ampiezze di tensione, non direttamente potenze. Un valore negativo in dB significa attenuazione e non tensione negativa. Il grafico del modulo ha asse X logaritmico in Hz e asse Y numericamente lineare in dB.
La fase è una differenza di fase tra uscita e ingresso. Il metodo phase_deg la restituisce direttamente in gradi. Per comprendere anche unwrap, chiediamo separatamente la fase in radianti:
phase_radians = gxtxt_numeric_v1('complex_unary','phase_rad', ...
transfer.real,transfer.imaginary);
unwrapped = gxtxt_numeric_v1('unwrap',phase_radians.values, ...
struct('period',2*pi));
phase_deg_check = unwrapped.values*180/pi;
unwrap corregge eventuali salti di un periodo completo nella sequenza angolare. Non converte le unità: il fattore \(180/\pi\) è ancora necessario. Nel nostro RLC ideale la fase resta compresa fra circa +90° e −90° e non attraversa un salto di 360°; l’operazione serve a illustrare una capacità generale. Se la fase fosse già espressa in gradi, il periodo coerente sarebbe 360, non \(2\pi\).

8. Validazione indipendente e risultati sulla P011
La stessa soluzione fisica può essere ricavata senza eseguire una divisione di array complessi:
\[ |H|=\frac{R}{\sqrt{R^2+X^2}},\qquad \varphi=-\operatorname{atan2}(X,R). \]
Utilizziamo queste formule con le funzioni native Octave come riferimento indipendente, non come sostituzione della Numeric API nei calcoli principali:
gain_reference_db = 20*log10(R_ohm ./ ...
sqrt(R_ohm^2+X_ohm.^2));
phase_reference_deg = -atan2(X_ohm,R_ohm)*180/pi;
max_error_gain_db = max(abs(gain_db-gain_reference_db));
max_error_phase_deg = max(abs(phase_deg-phase_reference_deg));
assert(max_error_gain_db < 1e-10);
assert(max_error_phase_deg < 1e-10);
Risultati dell’esecuzione con il binding pubblico P011, confermati anche dal sorgente esatto GitHub:
| Risultato | Valore |
|---|---|
| Campioni | 402 |
| Frequenza di risonanza | 1591,549431 Hz |
| Fattore di qualità \(Q\) | 5,000000 |
| Frequenza inferiore a mezza potenza | 1440,332439 Hz |
| Frequenza superiore a mezza potenza | 1758,642326 Hz |
| Banda passante | 318,309886 Hz |
| Massima differenza sul guadagno | \(7{,}11\times10^{-15}\) dB |
| Massima differenza sulla fase | \(2{,}84\times10^{-14}\) gradi |
Per un controllo fisico puntuale, a 1000 Hz abbiamo calcolato \(-13{,}83732\ \mathrm{dB}\) e \(+78{,}27009^\circ\); a 2500 Hz, \(-13{,}58261\ \mathrm{dB}\) e \(-77{,}91584^\circ\). La fase cambia segno alla risonanza. L’accordo dei due metodi è compatibile con l’arrotondamento in doppia precisione: non dimostra una precisione strumentale di quattordici cifre e non quantifica tolleranze o rumore dei componenti reali.

9. Un errore intenzionale: il dominio reale non può diventare complesso in silenzio
L’API array_unary è dedicata agli array reali. Chiedere la radice quadrata di un numero reale negativo dovrebbe essere respinto. Lo script esegue questo test in modo esplicito:
invalid_input_rejected = false;
try
gxtxt_numeric_v1('array_unary','sqrt',[-4;1]);
catch
invalid_input_rejected = true;
end_try_catch
assert(invalid_input_rejected);
Il rifiuto è il risultato atteso. In questo esempio intercettiamo l’eccezione esclusivamente per verificare il contratto; in una normale elaborazione non dobbiamo nascondere l’errore e proseguire con dati scientificamente invalidi. Analogamente dobbiamo controllare denominatori nulli, valori non finiti, forme incompatibili, unità e allineamento dei campioni.
10. Come cambia la chiamata nell’Octave Script Workspace
Nel Job gestito da GX-TXT la via pubblica è lo Script Bridge, che non usa la stessa forma degli argomenti. Qui mostriamo un’operazione realmente dichiarata dal binding Bridge di P011: la moltiplicazione di un vettore reale per uno scalare.
gxtxt_api_require({'NUMERIC_API_v1'});
assert(gxtxt_api_has_operation('NUMERIC_API_v1','array_binary'));
a = struct('kind','vector','value',[1;2;3]);
b = struct('kind','scalar','value',4);
result = gxtxt_api_call('NUMERIC_API_v1', ...
'array_binary',{'multiply',a,b});
assert(isequal(result.values,[4;8;12]));
Le parentesi graffe costruiscono una cell array di argomenti posizionali. Il campo kind descrive lo scalare o vettore; value ne contiene i dati. Nel binding diretto, invece, la stessa azione si esprime come gxtxt_numeric_v1('array_binary','multiply',[1;2;3],4), senza descrittori. Sono due contratti distinti.
Questo frammento illustra il contratto Script Bridge documentato, mentre lo script completo allegato è stato eseguito mediante il binding Octave diretto. Non attribuiamo al frammento Bridge un collaudo separato in una Session P011. Per usare complex_binary e complex_unary dentro un Job Bridge occorre una capacità pubblica registrata che le esponga; non si devono sostituire tali chiamate con procedure private del CORE.
11. Riproduzione dell’esperimento ed esercizi
Per eseguire l’esperimento servono GNU Octave e il modulo Numeric pubblico della P011, con il binding gxtxt_numeric_v1 reso disponibile nel percorso API Octave dichiarato dal modulo. È possibile verificarlo mediante exist('gxtxt_numeric_v1','file') e which('gxtxt_numeric_v1'). Non è necessario aprire i file dei Dataset, modificare il CORE o configurare alcuna scorciatoia verso le directory private del framework.
Lo script completo L15A_01_Public_Numeric_API_RLC.m include le formule, i controlli, il rifiuto dell’input non valido e la stampa dei risultati. Termina con il messaggio PASS: public Numeric API operations match independent reference.. Essendo un approfondimento sulle API numeriche, non pubblica Dataset e non costruisce grafici persistenti: queste operazioni sono documentate nel corso, attraverso DATASET_PUBLICATION_API_v2 e PLOT_DATASET_API_v4.
Per verificare di aver capito, proviamo a raddoppiare \(R\) e prevedere la variazione di \(Q\) e della banda passante; a sostituire phase_deg con phase_rad e convertire correttamente; a forzare un denominatore nullo e a osservare il rifiuto del calcolo; infine a introdurre array complessi di dimensioni incompatibili e spiegare perché non possono essere combinati elemento per elemento.
12. Riferimenti ai sorgenti pubblici
- NUMERIC_API_v1 — contratto del modulo
math.numeric - Binding Octave pubblico
gxtxt_numeric_v1.m - Binding
math.numericper lo Script Bridge - OCTAVE_SCRIPT_BRIDGE_API_v1
L’obiettivo di questo approfondimento è imparare a separare il contratto numerico dal problema fisico e dal meccanismo di esecuzione. Se l’esperimento è riproducibile, sappiamo non soltanto che il risultato è corretto, ma anche quali API lo hanno prodotto e quali condizioni ne delimitano la validità.
Script completo scaricabile
Il sorgente integrale è riportato nel riquadro espandibile qui sotto. Commenti e intestazioni del codice sono in inglese; licenza GPL-3.0-or-later.
Script GNU Octave completo — L15A_01_Public_Numeric_API_RLC.m
% L15A_01_Public_Numeric_API_RLC.m
% Educational deep dive into GX-TXT Numeric API v1.
% Framework reference: GX-TXT DEV112 R2 P011.
% GitHub commit: 9f79a30661d6a3fe4a05d723be66aabd06ef2ebe
% SPDX-License-Identifier: GPL-3.0-or-later
%
% Run in a GNU Octave module context that exposes the public math.numeric
% binding gxtxt_numeric_v1 on Octave's documented module API path.
% No private CORE functions, data files, or storage providers are accessed.
%
% This script tests the public Octave Numeric binding. It does not claim
% that complex_unary/complex_binary are exposed by the Script Bridge.
if exist('gxtxt_numeric_v1','file') != 2
error(['Missing gxtxt_numeric_v1 public Octave binding. ', ...
'Enable the registered math.numeric module API path.']);
endif
R_ohm = 20;
L_h = 10e-3;
C_f = 1e-6;
f0_hz = 1/(2*pi*sqrt(L_h*C_f));
Q_ideal = sqrt(L_h/C_f)/R_ohm;
% Keep one sample at the exact analytical resonance.
frequency_hz = sort([logspace(2, 4.5, 401)'; f0_hz]);
assert(numel(frequency_hz) == 402);
assert(all(isfinite(frequency_hz)) && all(diff(frequency_hz) > 0));
% The real-array operations use values directly through the Octave binding.
% array_binary returns a struct whose values field is a numeric array.
omega_result = gxtxt_numeric_v1('array_binary', ...
'multiply', 2*pi, frequency_hz);
omega = omega_result.values;
XL = gxtxt_numeric_v1('array_binary', 'multiply', L_h, omega);
omega_C = gxtxt_numeric_v1('array_binary', 'multiply', C_f, omega);
XC_mag = gxtxt_numeric_v1('array_binary', 'divide', 1, omega_C.values);
reactance = gxtxt_numeric_v1('array_binary', ...
'subtract', XL.values, XC_mag.values);
X_ohm = reactance.values;
assert(isequal(size(X_ohm), size(frequency_hz)));
% Compute H = R / (R + 1i*X) using the public split-complex interface.
% A complex number is transported as separate real/imaginary arrays.
denominator_real = R_ohm * ones(size(X_ohm));
transfer = gxtxt_numeric_v1('complex_binary', 'divide', ...
R_ohm, 0, denominator_real, X_ohm);
assert(all(isfinite(transfer.real(:))));
assert(all(isfinite(transfer.imaginary(:))));
magnitude = gxtxt_numeric_v1('complex_unary', 'magnitude', ...
transfer.real, transfer.imaginary);
phase_radians = gxtxt_numeric_v1('complex_unary', 'phase_rad', ...
transfer.real, transfer.imaginary);
phase_degrees = gxtxt_numeric_v1('complex_unary', 'phase_deg', ...
transfer.real, transfer.imaginary);
assert(isequal(size(magnitude.values), size(frequency_hz)));
% Apply logarithm and scaling with the public real-array operations.
log_magnitude = gxtxt_numeric_v1('array_unary', ...
'log10', magnitude.values);
decibels = gxtxt_numeric_v1('array_binary', ...
'multiply', 20, log_magnitude.values);
gain_db = decibels.values;
% unwrap works on phase measured in radians; it does not convert units.
unwrapped = gxtxt_numeric_v1('unwrap', phase_radians.values, ...
struct('period', 2*pi));
phase_deg = phase_degrees.values;
assert(max(abs(unwrapped.values*180/pi - phase_deg)) < 1e-11);
% Independently derive the same ideal circuit response with native Octave.
gain_reference_db = 20*log10(R_ohm ./ sqrt(R_ohm^2 + X_ohm.^2));
phase_reference_deg = -atan2(X_ohm,R_ohm)*180/pi;
error_gain_db = gain_db - gain_reference_db;
error_phase_deg = phase_deg - phase_reference_deg;
max_error_gain_db = max(abs(error_gain_db));
max_error_phase_deg = max(abs(error_phase_deg));
assert(max_error_gain_db < 1e-10);
assert(max_error_phase_deg < 1e-10);
assert(all(gain_db <= 1e-10));
% The exact resonance sample must yield 0 dB and 0 degrees.
[~,res_idx] = min(abs(frequency_hz-f0_hz));
assert(abs(frequency_hz(res_idx)-f0_hz) < 1e-9);
assert(abs(gain_db(res_idx)) < 1e-10);
assert(abs(phase_deg(res_idx)) < 1e-10);
omega_1 = (-R_ohm + sqrt(R_ohm^2+4*L_h/C_f))/(2*L_h);
omega_2 = ( R_ohm + sqrt(R_ohm^2+4*L_h/C_f))/(2*L_h);
f1_hz = omega_1/(2*pi);
f2_hz = omega_2/(2*pi);
bandwidth_hz = f2_hz-f1_hz;
assert(abs(Q_ideal-f0_hz/bandwidth_hz) < 1e-10);
% Demonstrate explicit error handling rather than silently hiding it.
invalid_input_rejected = false;
try
gxtxt_numeric_v1('array_unary','sqrt',[-4;1]);
catch
invalid_input_rejected = true;
end_try_catch
assert(invalid_input_rejected);
% Print only scientifically relevant measurements and validation facts.
fprintf('GX-TXT DEV112 R2 P011 - Numeric API v1 RLC demonstration\n');
fprintf('Samples: %d | R=%.1f Ohm | L=%.4f H | C=%.9f F\n', ...
numel(frequency_hz), R_ohm, L_h, C_f);
fprintf('Resonance: %.6f Hz | Q=%.6f | bandwidth=%.6f Hz\n', ...
f0_hz, Q_ideal, bandwidth_hz);
fprintf('Cutoffs: %.6f Hz and %.6f Hz\n', f1_hz, f2_hz);
fprintf('Max difference vs analytical reference: %.3g dB, %.3g deg\n', ...
max_error_gain_db, max_error_phase_deg);
for f_sample = [1000, 2500]
w = 2*pi*f_sample;
xx = w*L_h-1/(w*C_f);
hh = R_ohm/(R_ohm+1i*xx);
fprintf('%g Hz: gain %.5f dB, phase %+.5f deg\n', ...
f_sample, 20*log10(abs(hh)), angle(hh)*180/pi);
endfor
fprintf('Invalid real-domain input rejected: %d\n',invalid_input_rejected);
fprintf('PASS: public Numeric API operations match independent reference.\n');
Dalla stessa categoria
- Lezione 16 – Dal segnale UV-Vis alla costante cinetica: un progetto scientifico completo con GNU Octave e GX-TXT
- Lezione 15 — Circuiti RLC e Diagrammi di Bode
- Lezione 14 — Equazioni differenziali: cinetica chimica con GNU Octave e GX-TXT
- Lezione 13 – Analisi spettrale: FFT, campionamento e finestre con GNU Octave e GX-TXT
- Lezione 12 – Algebra lineare: analisi di una miscela spettrofotometrica con GNU Octave e GX-TXT
- GX-TXT Temporal Set API: intervalli e finestre temporali con GNU Octave e Python