API numeriche e algebra su array
Corso Python scientifico in GX-TXT · Modulo 5 · Lezione 25
In questa lezione mettiamo a confronto due modi di calcolare con le matrici: NumPy nel processo Python e il servizio numerico di GX-TXT, raggiunto attraverso il Bridge. Lavoriamo con numeri sintetici e senza unità fisiche, scelti per rendere il risultato verificabile a mano.
Cosa imparerai
- Riconoscere forma e tipo di un array.
- Distinguere il prodotto elemento per elemento dal prodotto matriciale.
- Richiedere una funzionalità dell’API numerica e leggere il risultato.
- Confrontare risultati numerici con una tolleranza.
Matrici e forme
Una matrice è una tabella rettangolare. Un array di forma
(2, 2) ha due righe e due colonne. La forma, o
shape, fa parte del contratto di un’operazione: nel prodotto
matriciale il numero di colonne della prima matrice deve coincidere con
il numero di righe della seconda. Il risultato ha le righe della prima e
le colonne della seconda.
Nell’esempio usiamo
A = [[1, 2], B = [[2, 0],
[3, 4]] [1, 2]]
L’elemento in alto a sinistra di A @ B è
1×2 + 2×1 = 4; il risultato completo è
[[4, 4], [10, 8]]. In Python, A @ B indica il
prodotto matriciale NumPy. Invece A * B moltiplica gli
elementi corrispondenti e A ** 2 eleva al quadrato ogni
elemento. Le tre operazioni rispondono a domande diverse.
Un’operazione elemento per elemento può usare il
broadcasting di NumPy: ad esempio A + 2 aggiunge
lo scalare a ogni elemento. NumPy può anche combinare forme compatibili
più generali, ma non bisogna supporre che un servizio esterno adotti le
stesse regole. Per le operazioni array_binary di questa API
uno scalare può espandersi su un array; due operandi non scalari devono
avere forma identica. Le operazioni array descritte dall’API accettano
valori reali con al massimo due dimensioni; i domini non validi e i
valori non finiti richiedono attenzione. linear_matrix ha
un contratto distinto e accetta matrici reali o complesse non vuote e
finite.
Lo script completo
Apri la Sessione corso_python, importa algebra_array.py nel Python Script
Workspace, assegnagli un ID e salvalo. Apri Run → Open Script
Runner e scegli Run Job.

import numpy as np
from gxtxt import gxtxt_api_call, gxtxt_api_require
gxtxt_api_require("NUMERIC_API_v1@1:math.numeric+complex_linear_algebra")
A = np.array([[1.0, 2.0], [3.0, 4.0]])
B = np.array([[2.0, 0.0], [1.0, 2.0]])
print("A × B, calcolo locale NumPy:")
atteso = A @ B
print(atteso)
risposta = gxtxt_api_call("NUMERIC_API_v1", "linear_matrix", [
"multiply", {"real": A}, {"real": B}
])
reale = np.asarray(risposta["value_real"]).reshape(2, 2)
immaginario = np.asarray(risposta["value_imaginary"]).reshape(2, 2)
print("A × B, API numerica:")
print(reale)
print("Forma:", reale.shape, "tipo:", reale.dtype)
print("Parte immaginaria nulla:", np.allclose(immaginario, 0))
print("Accordo con NumPy:", np.allclose(reale, atteso))
print("Quadrato elemento per elemento:")
print(A ** 2)
gxtxt_api_require controlla che il provider richiesto
esponga la capacità di algebra lineare complessa. È una verifica
preventiva: non calcola il prodotto. gxtxt_api_call invia
invece la richiesta al servizio NUMERIC_API_v1,
specificando l’operazione linear_matrix, l’azione
multiply e i due operandi. I dizionari
{"real": A} e {"real": B} rappresentano
matrici reali; il contratto può anche rappresentare la parte
immaginaria.
La risposta separa value_real e
value_imaginary. Qui rimettiamo ciascuna parte nella forma
attesa (2, 2), specifica di questo esempio. In un programma
generale la forma va ricavata e verificata secondo il contratto e le
dimensioni degli ingressi, senza fissare sempre 2×2. Stampiamo anche il
dtype, cioè il tipo numerico degli elementi:
nell’esecuzione mostrata è float64.
Leggere e verificare il risultato

Il Job stampa [[4, 4], [10, 8]] per entrambi i calcoli.
La parte immaginaria è nulla e np.allclose restituisce
True. Questo confronto usa tolleranze, appropriate perché
due implementazioni in virgola mobile possono differire di una piccola
quantità. Per un’applicazione reale scegli rtol e
atol in base alla precisione richiesta e alla scala dei
dati; l’uguaglianza approssimata non sostituisce il controllo delle
unità.
Il calcolo NumPy avviene nello script Python; la richiesta al Bridge usa il provider numerico di GX-TXT. Anche quando i risultati coincidono, i contratti di ingresso, il contesto e i costi possono essere diversi. La chiamata matriciale tratta i numeri come valori matematici: se rappresentano grandezze fisiche, spetta a chi scrive il programma controllare che le unità siano compatibili e attribuire quelle corrette al risultato.
Prova tu
- Prima di eseguire, calcola a mano
A ** 2eA @ B. Perché sono diversi? - Sostituisci
Bcon la matrice identità[[1.0, 0.0], [0.0, 1.0]]e verifica che il prodotto restituiscaA. - Immagina una matrice
Ccon forma(3, 2): puoi calcolareA @ C? EC @ A? Indica la forma del risultato ammesso.
Soluzione ragionata
A ** 2produce[[1, 4], [9, 16]]: ogni elemento è elevato al quadrato.A @ Bcombina invece righe e colonne e produce[[4, 4], [10, 8]].- La matrice identità lascia invariato il prodotto: con
np.allclose(reale, A)ottieniTrue, entro la tolleranza usata. A @ Cnon è definito perché le due dimensioni interne sono 2 e 3.C @ Aè definito: le dimensioni interne sono entrambe 2 e il risultato ha forma(3, 2).
Nella prossima lezione useremo una griglia per stimare valori intermedi di una curva, distinguendo le stime dai dati osservati.