Esempio di una gsUDF: speed.gsf
In letteratura, è spesso riportato questo esempio pratico di una gsUDF, la funzione speed, che reimplementa la funzione intrinseca mag per calcolare la velocità del vento. Tuttavia, sicuramente non funziona nella versione di OpenGrADS per Windows. L'errore macroscopico è quello di voler far trattare dalla funzione speed.gsf un'array di dati come se fossero valori scalari.
1. Creazione del file script GrADS (speed.gsf)
La funzione speed deve essere definita in un file di testo con estensione .gsf, ad esempio speed.gsf. Questo file conterrà la logica della funzione:
function speed ( u, v )
expr = 'sqrt(' u '*' u '+' v '*' v ')'
return expr
expr = 'sqrt(' u '*' u '+' v '*' v ')'
return expr
In questo esempio, sbagliato, la funzione speed prende come input le componenti u e v del vento. Il suo compito è costruire una stringa che rappresenti l'espressione GrADS per calcolare la magnitudine del vettore (sqrt(u*u+v*v)) e restituire questa stringa. GrADS valuterà questa stringa come una normale espressione.
Questo il codice corretto, costruito sulla base di una funzione consolidata e corretta (dewpt.gsf):
*
* Speed (wind magnitude) calculation in gsUDF style
* -----------------------------------------------
*
function speed(u,v)
if (u='u'|u='' | v='v'|v='' )
say 'Purpose: Wind speed [m/s]'
say 'Usage: display speed(u,v)'
say ' u = zonal wind component'
say ' v = meridional wind component'
return
else
uu = u
vv = v
endif
* Define these to minimize I/O
* ----------------------------
'define xxxu = ' uu
'define xxxv = ' vv
'define gsudf = sqrt(xxxu*xxxu + xxxv*xxxv)'
* Release defined variables
* -------------------------
'undefine xxxu'
'undefine xxxv'
return 'gsudf'
In questa tabella, sono stati evidenziati errori e soluzioni adottate.
2. Aggiunta della funzione alla tabella UDXT (User Defined eXtension Table)
Affinché GrADS riconosca speed.gsf come una funzione di espressione, è necessario aggiungere una voce nella tabella delle estensioni definite dall'utente (UDXT). Questa tabella, solitamente posta nella cartella GEX e priva di estensione, indica a GrADS come caricare ed eseguire le gsUDFs. Una voce tipica per speed nella tabella UDXT sarebbe:
udf 0 speed f_gsudf gsudf.gex.so Questa riga informa GrADS che speed è una User Defined Function (udf) gestita dal generico gestore f_gsudf presente nella libreria condivisa gsudf.gex.so (o ^gsudf.gex).
3. Utilizzo della funzione in GrADS
Una volta che la gsUDF è stata definita e la tabella UDXT è configurata, è possibile richiamare la funzione speed direttamente dalla riga di comando di GrADS o all'interno di uno script, proprio come qualsiasi altra funzione intrinseca:
ga-> open model.ctl
ga-> display speed(ua,va)
Questo comando visualizzerà la velocità del vento calcolata dalle variabili ua e va.
Concetti chiave:
- Restituzione di una stringa: Le gsUDF devono sempre restituire una stringa che contiene un'espressione GrADS valida. Questa espressione verrà poi elaborata dal parser di GrADS.
- Minimizzazione dell'I/O: Le gsUDF possono definire variabili temporanee per memorizzare risultati intermedi, riducendo l'Input/Output e migliorando l'efficienza. È buona pratica "rilasciare" queste variabili al termine della funzione per mantenere pulito l'ambiente di lavoro di GrADS.
- Flessibilità: Questo approccio permette di implementare calcoli complessi o specifici dell'utente direttamente nell'ambiente GrADS, estendendone le capacità.