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

RiferimentoVersione utilizzata
Framework GX-TXT0.9.8.10-dev-112, Release 2, P011
Release GitHubv0.9.8.10-dev-112-r2-p011
Commit sorgente9f79a30661d6a3fe4a05d723be66aabd06ef2ebe
Modulo scientificomath.numeric, NUMERIC_API_v1
Linguaggio eseguitoGNU Octave 9.4.0
Licenza del codiceGPL-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 con kind e value.

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 pubblicaScopoRisultato 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\).

Editor GNU Octave con lo script del circuito RLC che invoca array_binary, complex_binary, complex_unary e unwrap della Numeric API v1.
Il codice del circuito RLC utilizza il binding numerico pubblico GX-TXT per impedenza complessa, modulo, fase e decibel.

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:

RisultatoValore
Campioni402
Frequenza di risonanza1591,549431 Hz
Fattore di qualità \(Q\)5,000000
Frequenza inferiore a mezza potenza1440,332439 Hz
Frequenza superiore a mezza potenza1758,642326 Hz
Banda passante318,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.

Finestra dei comandi GNU Octave con frequenza di risonanza a 1591,549 Hz, fattore Q pari a 5 e verifica PASS delle API numeriche GX-TXT.
Risultati ottenuti con GX-TXT P011: 402 campioni, risonanza a 1591,549 Hz e confronto analitico superato.

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

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');

#analisi numerica #Calcolo numerico #circuiti RLC #diagrammi di Bode #elaborazione dati #GNU Octave #GX-TXT #impedenza complessa #numeri complessi #Numeric API v1 #programmazione scientifica #Script Bridge

Dalla stessa categoria

Lascia un commento

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