<appendix id="creatingplugins">
<title
>Creare plugin aggiuntivi</title>
<para
>&kst; ha un'interfaccia semplice e intuitiva che facilita la creazione facile di plugin aggiuntivi. In aggiunta a specificare i requisiti fondamentali dei plugin, le sezioni seguenti descrivono come fare uso dei file di intestazione preimpostati per creare certi tipi di plugin. </para>

<sect1 id="creatingbasicplugin">
<title
>Creare un plugin di base</title>
<para
>Un plugin di &kst; consiste di due file: un file XML e un file oggetto condiviso. </para>

<sect2 id="creatingbasicpluginxmlfile">
<title
>Il file XML</title>
<para
>Il file XML fornisce le informazioni sul plugin e descrive i suoi input e output. Quello che segue è un esempio di file XML per un plugin di &kst;: </para>

<informalexample>
<screen
>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE Module SYSTEM "file:/Repository/Level2/Soft/ProC/moduledef.dtd"&gt;

&lt;module&gt;

&lt;intro&gt;
&lt;modulename name="plugindiprova"/&gt;    &lt;!-- Il nome del modulo --&gt;
&lt;author name="Rick Chern"/&gt; &lt;!-- Il nome dell'autore --&gt;
&lt;description text="Un plugin di prova per me"/&gt; &lt;!-- Una descrizione del modulo --&gt;
&lt;version minor="1" major="0"/&gt;  &lt;!-- Il numero di versione del modulo --&gt;
&lt;state devstate="release"/&gt;     &lt;!-- Lo stato dello sviluppo del modulo (opzionale)--&gt;
&lt;/intro&gt;

&lt;interface&gt;

&lt;!--qui gli input--&gt;
&lt;input&gt;
&lt;table type="float" name="Vettore di input 1" descr="Il primo vettore di input" /&gt;
&lt;/input&gt;

&lt;input&gt;
&lt;float name="Scalare di input 1" descr="Il primo scalare di input" /&gt;
&lt;/input&gt;

&lt;!--gli output qui--&gt;
&lt;output&gt;
&lt;table type="float" name="Vettore di output 1" descr="Il primo vettore di output" /&gt;
&lt;/output&gt;

&lt;output&gt;
&lt;float name="Scalare di output 1" descr="Il primo scalare di output" /&gt;
&lt;/output&gt;

&lt;/interface&gt;

&lt;/module&gt;
</screen>
</informalexample>

<para
>Generalmente, puoi usare l'esempio qui sopra come modello e modificarne le sezioni a seconda dei tuoi bisogni. Come si può vedere dall'esempio, il file XML consiste di un nodo <literal
>module</literal
>. Il nodo <literal
>module</literal
> ha un nodo <literal
>intro</literal
> e un nodo <literal
>interface</literal
>. Dovresti modificare il nodo <literal
>intro</literal
> appropriatamente usando i commenti nel file XML sopra come guida. È importante che <literal
>modulename</literal
> abbia l'attributo <literal
>name</literal
> impostato allo stesso nome che sarà usato dal tuo file oggetto condiviso. </para>

<para
>Il nodo <literal
>interface</literal
> descrive gli input e gli output del plugin. Ogni input è descritto da un nodo <literal
>input</literal
>, e ogni output da un nodo <literal
>output</literal
>. Ogni input o output dovrebbe avere un nodo o <literal
>table</literal
> o <literal
>float</literal
> come figlio. L'attributo <literal
>type</literal
> di un nodo <literal
>table</literal
> deve essere impostato a <literal
>&quot;float&quot;</literal
>. Nota come l'ordine degli input e degli output sia importante: l'ordine è usato per determinare i valori degli indici per ogni array di input e output del file oggetto, ed è lo stesso ordine usato per visualizzare i campi di input e output nell'interfaccia dei plugin di &kst;. </para>

<para
>Una volta che hai completato il file XML, salvalo come <filename
>[nomemodulo].xml</filename
>, dove <filename
>[nomemodulo]</filename
> è il valore dell'attributo <literal
>name</literal
> del nodo <literal
>modulename</literal
>. </para>

</sect2>

<sect2 id="creatingbasicpluginobjectfile">
<title
>Il file oggetto condiviso</title>
<para
>Il file oggetto condiviso contiene la funzionalità vera e propria del plugin. In parole povere, determina come ottenere gli output dagli input dati. I requisiti del file oggetto condiviso sono i seguenti: </para>

<itemizedlist>

<listitem>
<para
>L'oggetto deve esportare il seguente simbolo di collegamento C: <literallayout
><function
><returnvalue
>int</returnvalue
> simbolo(const double *const <parameter
>inArrays[]</parameter
>,
           const int <parameter
>inArrayLens[]</parameter
>,
           const double <parameter
>inScalars[]</parameter
>,
           double *<parameter
>outArrays[]</parameter
>,
           int <parameter
>outArrayLens[]</parameter
>,
           double <parameter
>outScalars[]</parameter
>)</function
></literallayout>
</para>
<para
>dove <replaceable
>simbolo</replaceable
> deve essere il valore dell'attributo <literal
>name</literal
> del nodo <literal
>modulename</literal
> nel file XML. Questa è la sola funzione che sarà chiamata da &kst; (sebbene tu possa avere altre funzioni). Il seguito descrive ogni argomento di questa funzione: </para>

<variablelist>
<varlistentry>
<term
><varname
>const double *const inArrays[]</varname
></term>
<listitem>
<para
>L'array degli array di input. Ogni array di input corrisponde a un vettore di input. Gli array sono nello stesso ordine dei vettori elencati nel file XML, quindi <literal
>inArrays[0]</literal
> è l'array che rappresenta il primo vettore di input, <literal
>inArrays[1]</literal
> è l'array che rappresenta il secondo vettore di input, e così via. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><varname
>const int inArraysLens[]</varname
></term>
<listitem>
<para
>L'array contenente le lunghezze degli array per ogni array di input. Le lunghezze sono conservate nello stesso ordine degli array in <literal
>inArrays[]</literal
> (per esempio <literal
>inArrayLens[0]</literal
> è la lunghezza di <literal
>inArray[0]</literal
>). </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><varname
>const double inScalars[]</varname
></term>
<listitem>
<para
>L'array degli scalari di input. Gli scalari sono conservati nello stesso ordine in cui sono elencati nel file XML. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><varname
>double *outArrays[]</varname
></term>
<listitem>
<para
>L'array degli array di output. Ogni array di output corrisponde a un vettore di output, e gli array dovrebbero essere nello stesso ordine in cui i vettori di output sono elencati nel file XML. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><varname
>int outArrayLens[]</varname
></term>
<listitem>
<para
>L'array che dovrebbe contenere le lunghezze degli array di output. Le lunghezze dovrebbero essere conservate nello stesso ordine degli array in <literal
>outArrays[]</literal
>. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><varname
>double outScalars[]</varname
></term>
<listitem>
<para
>L'array degli scalari di output. Gli scalari dovrebbero essere nello stesso ordine in cui sono elencati nel file XML. </para>
</listitem>
</varlistentry>
</variablelist>


</listitem>

<listitem>
<para
>La funzione deve restituire <literal
>0</literal
> se è eseguita con successo, e <literal
>-1</literal
> altrimenti. </para>
</listitem>

<listitem>
<para
>Il codice per il file oggetto deve poter gestire degli input inattesi, come vettori di input vuoti (nella maggior parte dei casi restituire un valore di <literal
>-1</literal
> dovrebbe essere sufficiente quando si incontra una situazione del genere). </para>
</listitem>

<listitem>
<para
>Il numero e il tipo di output deve essere esattamente come specificato dal file XML. </para>
</listitem>

<listitem>
<para
>Avrai probabilmente bisogno di ridimensionare gli array in <varname
>outArrays[]</varname
>. Per farlo, usa la funzione <function
>realloc()</function
>. Per esempio, </para>
<informalexample>
<screen
>outArrays[0]=(double*)realloc(outArrays[0], 5*sizeof(double));
</screen>
</informalexample>
<para
>allocherà spazio per cinque double per <varname
>outArrays[0]</varname
>. Non usare nessun allocatore di memoria che non sia <function
>realloc()</function
>. </para>
</listitem>

<listitem>
<para
>Gli argomenti di input devono rimanere costanti. Non farli diventare tipi non costanti. </para>
</listitem>

</itemizedlist>

<para
>Quello che segue è un esempio del codice sorgente del file oggetto condiviso per un plugin semplice: </para>
<informalexample>
<screen
>#include &lt;stdlib.h&gt;

extern "C" int testplugin(const double *const inArrays[], const int inArrayLens[],
                const double is[],
                double *outArrays[], int outArrayLens[],
                double outScalars[]);

int testplugin(const double *const inArrays[], const int inArrayLens[],
                const double is[],
                double *outArrays[], int outArrayLens[],
                double outScalars[])

//Accetta 1 vettore e 1 scalare. Moltiplica tutti gli elementi del vettore per lo
//scalare, e restituisci il vettore risultante. Restituisci anche lo scalare originale.
{
        //Imposta gli output
        outArrayLens[0]=inArrayLens[0];

        //ridimensiona gli array di output
        outArrays[0]=(double*)realloc(outArrays[0], inArrayLens[0]*sizeof(double));

        //moltiplica ogni elemento del vettore di input
        //per lo scalare
        for (int i=0; i&lt;inArrayLens[0]; i++)
        {
                outArrays[0][i]=inArrays[0][i] * is[0];
        }

        //ora imposta lo scalare di output 
        outScalars[0]=is[0];

        return 0;
}
</screen>
</informalexample>
</sect2>


<sect2 id="compilingplugin">
<title
>Compilare il plugin</title>
<para
>Se usi &gcc; per compilare il tuo plugin, compila semplicemente il tuo file oggetto: <screen
><userinput
><command
>cc -Wall -c -o ilmioplugin.o ilmioplugin.c -fPIC -DPIC</command
></userinput
></screen>
</para>
<para
>e quindi crea la libreria condivisa: <screen
><userinput
><command
>ld -o ilmioplugin.so -shared ilmioplugin.o</command
></userinput
></screen>
</para>
<para
>Il file <filename
>.so</filename
> risultante e il file <filename
>.xml</filename
> devono essere messi nella stessa cartella. Quando usi il gestore dei plugin di &kst; per caricare il file XML, esso cercherà automaticamente l'oggetto condiviso nella stessa cartella. </para>

</sect2>
</sect1>

<sect1 id="creatinglinearfittingplugins">
<title
>Creare plugin di regressione lineare</title>
<para
>Per creare plugin di regressione lineare, potresti implementare da te degli algoritmi di regressione e restituire i vettori appropriati. Tuttavia, &kst; è già equipaggiato con dei file di intestazione che ti facilitano l'implementazione di plugin di regressione lineare con il metodo dei minimi quadrati fornendo solo poche funzioni. Questa sezione descriverà come usare a tuo vantaggio questi file. </para>

<sect2 id="headerslinearfittingplugins">
<title
>File di intestazione</title>
<para
>Sono forniti due file di intestazione per effettuare regressioni lineari, <filename
>linear.h</filename
> (per le regressioni lineari non pesate) e <filename
>linear_weighted.h</filename
> (per le regressioni lineari pesate). Sono entrambi situati sotto <filename
>kst/plugins/fits/</filename
> nel pacchetto sorgente di &kst;. Per usare questi file, includi solo uno di loro nel codice sorgente del tuo plugin: <screen>
#include &lt;../linear.h&gt;
</screen
> o <screen>
#include &lt;../linear_weighted.h&gt;
</screen
> (per convenzione, metteremo il codice sorgente del plugin una cartella sotto dove si trovano i file di intestazione). </para>

</sect2>

<sect2 id="reqfunctionsfittingplugins">
<title
>Implementazione delle funzioni richieste</title>
<para
>Dato un modello lineare generico: </para>
<para>
<inlinemediaobject>
<imageobject>
<imagedata fileref="Formula-kst-generallinearmodel.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</para>
<para
>dove <literal
>y</literal
> è un vettore di <literal
>n</literal
> osservazioni, <literal
>X</literal
> è una matrice di <literal
>n</literal
> per <literal
>p</literal
> variabili di predizione, e <literal
>c</literal
> è il vettore di <literal
>p</literal
> parametri di regressione ottimale che devono essere stimati, i file di intestazione forniscono delle funzioni per stimare <literal
>c</literal
> per dei dati <literal
>y</literal
> e <literal
>X</literal
>. Per fornire <literal
>X</literal
>, deve essere implementata la funzione seguente nel codice sorgente del plugin: <literallayout
><function
><returnvalue
>double</returnvalue
> calculate_matrix_entry( double <parameter
>dX</parameter
>, int <parameter
>iPos</parameter
> )</function
></literallayout>
</para>
<para
>Questa funzione dovrebbe restituire il valore della voce nella colonna <literal
>iPos</literal
> della matrice delle variabili di predizione, usando il valore <literal
>dX</literal
> per <literal
>x</literal
>. Questa funzione sarà chiamata da linear.h o linear_weighted.h. L'implementazione di questa funzione dipende dal modello che vuoi usare per la regressione, ed è unico per ogni plugin di regressione regressione lineare. Per esempio, per regredire a un modello polinomiale, <function
>calculate_matrix_entry</function
> potrebbe essere implementata come segue: <informalexample
> <screen
>double calculate_matrix_entry( double dX, int iPos ) {
  double dY;
  dY = pow( dX, (double)iPos );
  return dY;
}
</screen>
</informalexample>
</para>

</sect2>

<sect2 id="callingfittingfunctionslinearfittingplugins">
<title
>Chiamare le funzioni di regressione</title>
<para
>Una volta che il file di intestazione appropriato è stato incluso e <function
>calculate_matrix_entry</function
> è stata implementata, chiama la funzione di regressione appropriata inclusa dal file di intestazione: <screen>
<function
>kstfit_linear_unweighted( <parameter
>inArrays</parameter
>, <parameter
>inArrayLens</parameter
>,
                          <parameter
>outArrays</parameter
>, <parameter
>outArrayLens</parameter
>,
                          <parameter
>outScalars</parameter
>, <parameter
>iNumParams</parameter
> )</function
>;
</screen
> o <screen
><function
>kstfit_linear_weighted( <parameter
>inArrays</parameter
>, <parameter
>inArrayLens</parameter
>,
                        <parameter
>outArrays</parameter
>, <parameter
>outArrayLens</parameter
>,
                        <parameter
>outScalars</parameter
>, <parameter
>iNumParams</parameter
> )</function
>;
</screen>
</para>
<para
>Ogni funzione restituirà <literal
>0</literal
> in caso di successo, o <literal
>-1</literal
> in caso d'errore, quindi è una buona idea impostare il valore restituito della funzione C esportata uguale al valore restituito dalla funzione di regressione. Per tenere le cose semplici, il codice del plugin può semplicemente passare gli argomenti dati alla funzione C esportata alla funzione di regressione. Nota, comunque, che inArrays deve essere strutturato come segue: </para>
<itemizedlist>
<listitem>
<para
><varname
>inArrays[0]</varname
> deve contenere l'array delle coordinate x dei punti dei dati </para>
</listitem>

<listitem>
<para
><varname
>inArrays[1]</varname
> deve contenere l'array delle coordinate y dei punti dei dati </para>
</listitem>

<listitem>
<para
><varname
>inArrays[2]</varname
> esiste solo se viene chiamata <function
>kstfit_linear_weighted</function
>, e deve contenerel'array di pesi da usare per la regressione. </para>
</listitem>
</itemizedlist>
<para
>Il modo più semplice di assicurarsi che inArrays sia strutturato correttamente è specificare l'ordine giusto di vettori di input nel file XML del plugin. </para>
<para
><varname
>iNumParams</varname
> è il numero di parametri usati nel modello di regressione, che dovrebbe essere uguale al numero di colonne nella matrice <literal
>X</literal
> delle variabili di predizione. <varname
>iNumParams</varname
> deve essere impostata correttamente prima che sia chiamata la funzione di regressione. </para>
<para
>Dopo che è stata chiamata <function
>kstfit_linear_unweighted</function
> o <function
>kstfit_linear_weighted</function
>, <varname
>outArrays</varname
> e <varname
>outScalars</varname
> saranno impostate come segue: </para>
<itemizedlist>
<listitem>
<para
><varname
>outArrays[0]</varname
> conterrà l'array dei valori y regrediti. </para>
</listitem>

<listitem>
<para
><varname
>outArrays[1]</varname
> conterrà l'array dei residui. </para>
</listitem>

<listitem>
<para
><varname
>outArrays[2]</varname
> conterrà l'array dei parametri di regressione ottimale che sono stati stimati. </para>
</listitem>

<listitem>
<para
><varname
>outArrays[3]</varname
> conterrà la matrice di covarianza, restituita riga dopo riga in un array. </para>
</listitem>

<listitem>
<para
><varname
>outScalars[0]</varname
> conterrà chi²/nu, dove chi² è la somma pesata dei residui, e nu sono i gradi di libertà. </para>
</listitem>
</itemizedlist>
<para
><varname
>outArrayLens</varname
> sarà impostata correttamente per indicare la lunghezza di ciascun array di output. </para>

<para
>Assicurati che gli output specificati nel file XML corrispondano a quelli che la funzione C esportata restituisce (che nella maggior parte dei casi saranno semplicemente gli output restituiti dalla funzione di regressione). </para>


</sect2>

<sect2 id="examplelinearfittingplugins">
<title
>Esempio</title>
<para
>Quello che segue è un esempio del codice sorgente di un plugin di regressione lineare. </para>
<informalexample>
<screen
>/*
 *  Plugin di regressione polinomiale per KST.
 *  Copyright 2004, Università della Columbia Britannica
 *  Distribuito sotto le condizioni della GPL.
 */

#include "../linear.h"

double calculate_matrix_entry( double dX, int iPos ) {
  double dY;

  dY = pow( dX, (double)iPos );

  return dY;
}

extern "C" int kstfit_polynomial_unweighted(
  const double *const inArrays[],
  const int inArrayLens[],
  const double inScalars[],
  double *outArrays[], int outArrayLens[],
  double outScalars[]);

int kstfit_polynomial_unweighted(
  const double *const inArrays[],
  const int inArrayLens[],
        const double inScalars[],
        double *outArrays[], int outArrayLens[],
        double outScalars[])
{
  int iRetVal = -1;
  int iNumParams;

  iNumParams = 1 + (int)floor( inScalars[0] );
  if( iNumParams &gt; 0 ) {
    iRetVal = kstfit_linear_unweighted( inArrays, inArrayLens,
                                        outArrays, outArrayLens,
                                        outScalars, iNumParams );
  }

  return iRetVal;
}
</screen>
</informalexample>
</sect2>

</sect1>

<sect1 id="creatingnonlinearfitplugin">
<title
>Creare plugin di regressione non lineare</title>
<para
>&kst; fornisce file di intestazione progettati per semplificare la creazione di plugin di regressione non lineare con il metodo dei minimi quadrati. Le sezioni seguenti descrivono in dettaglio l'uso dei file di intestazione. </para>

<sect2 id="headersnonlinearfittingplugins">
<title
>File di intestazione e definizioni</title>
<para
>I file di intestazione per le regressioni non lineari sono situati in <filename
>kst/plugins/fits_nonlinear</filename
> nel pacchetto sorgente di &kst;. I file sono chiamati <filename
>non_linear.h</filename
> e <filename
>non_linear_weighted.h</filename
> rispettivamente per le regressioni pesate e non. Per usare questi file, includi solo uno di loro nel codice sorgente del tuo plugin: <screen>
#include &lt;../non_linear.h&gt;
</screen
> o <screen>
#include &lt;../non_linear_weighted.h&gt;
</screen
> (per convenzione, metteremo il codice sorgente del plugin una cartella sotto dove sono i file di intestazione). </para>

<para
>Siccome ogni regressione non lineare è un processo iterativo, devi anche definire il numero massimo di iterazioni che dovrebbero essere effettuate. L'algoritmo di regressione non lineare si fermerà quando almeno una delle condizioni seguenti sarà vera: </para>
<itemizedlist>
<listitem>
<para
>È stato raggiunto il numero massimo di iterazioni. </para>
</listitem>
<listitem>
<para
>È stata raggiunta una precisione di 10<superscript
>-4</superscript
>. </para>
</listitem>
</itemizedlist>
<para
>Inoltre, devi definire il numero di parametri nel modello, perché non è passato esplicitamente alla funzione di regressione. Per definire questi due valori, includi ciò che segue in cima al tuo codice sorgente: </para>
<screen
>#define NUM_PARAMS [num1]
#define MAX_NUM_ITERATIONS [num2]
</screen>
<para
>sostituendo <literal
>[num1]</literal
> con il numero di parametri nel modello, e <literal
>[num2]</literal
> con il numero massimo di iterazioni da eseguire. </para>
</sect2>

<sect2 id="reqfunctionsnonlinearfittingplugins">
<title
>Implementazione delle funzioni richieste</title>
<para
>Per usare i file di intestazione per le regressioni non lineari, devi fornire la funzione da usare come modello, le derivate parziali della funzione rispetto a ogni parametro, e le stime iniziali dei parametri di regressione ottimale. Per farlo, devono essere implementate tre funzioni. Queste funzioni sono descritte sotto. </para>
<variablelist>
<varlistentry>
<term
><function
><returnvalue
>double</returnvalue
> function_calculate( double <parameter
>dX</parameter
>, double* <parameter
>pdParameters</parameter
> )</function
></term>
<listitem>
<para
>Questa funzione calcola il valore y del modello di regressione per un dato valore <literal
>dX</literal
> per x, usando l'array di parametri dato <varname
>pdParameters</varname
>. L'ordine dei parametri in <varname
>pdParameters</varname
> è arbitrario, ma dovrebbe essere consistente con le altre due funzioni implementate. Per esempio, per un modello esponenziale, <function
>function_calculate</function
> potrebbe essere implementata come segue: </para>
<informalexample>
<screen
>double function_calculate( double dX, double* pdParameters ) {
  double dScale         = pdParameters[0];
  double dLambda = pdParameters[1];
  double dOffset = pdParameters[2];
  double dY;

  dY  = ( dScale * exp( -dLambda * dX ) ) + dOffset;

  return dY;
}
</screen>
</informalexample>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
><returnvalue
>void</returnvalue
> function_derivative( double <parameter
>dX</parameter
>, double* <parameter
>pdParameters</parameter
>, double* <parameter
>pdDerivatives</parameter
> )</function
></term>
<listitem>
<para
>Questa funzione calcola le derivate parziali della funzione modello per un dato valore <literal
>dX</literal
> di x. Le derivate parziali dovrebbero essere restituite in <varname
>pdDerivatives</varname
>. L'ordine delle derivate parziali nell'array <varname
>pdDerivatives</varname
> dovrebbe corrispondere all'ordine dei parametri in <varname
>pdParameters</varname
> (cioè se <varname
>pdParameters[0]</varname
> contiene il parametro lambda per un modello esponenziale, <varname
>pdDerivatives[0]</varname
> dovrebbe contenere la derivata del modello rispetto a lambda. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
><returnvalue
>void</returnvalue
> function_initial_estimate( const double* <parameter
>pdX</parameter
>, const double* <parameter
>pdY</parameter
>, int <parameter
>iLength</parameter
>, double* <parameter
>pdParameterEstimates</parameter
> )</function
></term>
<listitem>
<para
>Questa funzione dà una stima iniziale dei parametri di regressione ottimale alla funzione di regressione. Gli array dei valori x e y dei punti dei dati sono dati rispettivamente in <varname
>pdX</varname
> e <varname
>pdY</varname
>, e il numero di punti di dati è dato da <varname
>iLength</varname
>. Puoi usare uno qualsiasi o tutti questi parametri a tua discrezione per calcolare la stima iniziale. La funzione dovrebbe mettere le stime iniziali calcolate in <varname
>pdParameterEstimates</varname
>, con l'ordine delle stime corrispondente all'ordine dei parametri in <varname
>pdParameters</varname
> di <function
>function_calculate</function
> e <function
>function_derivative</function
>. Tieni a mente che la stima iniziale è importante per determinare se la funzione di regressione converge a una soluzione o meno. </para>
</listitem>
</varlistentry>

</variablelist>

</sect2>

<sect2 id="callingnonlinearfittingplugins">
<title
>Chiamare le funzioni di regressione</title>
<para
>Una volta che sono state implementate tutte le funzioni necessarie, può essere chiamata la funzione di regressione dal file di intestazione incluso: <screen>
kstfit_nonlinear( <parameter
>inArrays</parameter
>, <parameter
>inArrayLens</parameter
>,
                  <parameter
>inScalars</parameter
>, <parameter
>outArrays</parameter
>,
                  <parameter
>outArrayLens</parameter
>, <parameter
>outScalars</parameter
> );
</screen
> o <screen>
kstfit_nonlinear_weighted( <parameter
>inArrays</parameter
>, <parameter
>inArrayLens</parameter
>,
                           <parameter
>inScalars</parameter
>, <parameter
>outArrays</parameter
>,
                           <parameter
>outArrayLens</parameter
>, <parameter
>outScalars</parameter
> );
</screen
> a seconda che tu stia implementando una regressione non pesata o pesata. </para>

<para
>La funzione restituirà <literal
>0</literal
> in caso di successo, o <literal
>-1</literal
> in caso d'errore, quindi la cosa più semplice è impostare il valore restituito dalla funzione C come uguale al valore restituito dalla funzione di regressione. Per tenere le cose semplici, il codice per il plugin può semplicemente passare gli argomenti dati alla funzione C esportata alla funzione di regressione. Nota, comunque, che inArrays deve essere strutturata come segue: </para>
<itemizedlist>
<listitem>
<para
><varname
>inArrays[0]</varname
> deve contenere l'array delle coordinate x dei punti dei dati </para>
</listitem>

<listitem>
<para
><varname
>inArrays[1]</varname
> deve contenere l'array delle coordinate y dei punti dei dati </para>
</listitem>

<listitem>
<para
><varname
>inArrays[2]</varname
> esiste solo se viene chiamata <function
>kstfit_linear_weighted</function
>, e deve contenerel'array di pesi da usare per la regressione. </para>
</listitem>
</itemizedlist>
<para
>Il modo più semplice di assicurarsi che inArrays sia strutturato correttamente è specificare l'ordine giusto di vettori di input nel file XML del plugin. </para>
<para
>Dopo che è stata chiamata <function
>kstfit_linear_unweighted</function
> o <function
>kstfit_linear_weighted</function
>, <varname
>outArrays</varname
> e <varname
>outScalars</varname
> saranno impostate come segue: </para>
<itemizedlist>
<listitem>
<para
><varname
>outArrays[0]</varname
> conterrà l'array dei valori y regrediti. </para>
</listitem>

<listitem>
<para
><varname
>outArrays[1]</varname
> conterrà l'array dei residui. </para>
</listitem>

<listitem>
<para
><varname
>outArrays[2]</varname
> conterrà l'array dei parametri di regressione ottimale che sono stati stimati. </para>
</listitem>

<listitem>
<para
><varname
>outArrays[3]</varname
> conterrà la matrice di covarianza, restituita riga dopo riga in un array. </para>
</listitem>

<listitem>
<para
><varname
>outScalars[0]</varname
> conterrà chi²/nu, dove chi² è la somma pesata dei residui, e nu sono i gradi di libertà. </para>
</listitem>
</itemizedlist>
<para
><varname
>outArrayLens</varname
> sarà impostata correttamente per indicare la lunghezza di ciascun array di output. </para>

<para
>Assicurati che gli output specificati nel file XML corrispondano a quelli che la funzione C esportata restituisce (che nella maggior parte dei casi saranno semplicemente gli output restituiti dalla funzione di regressione). </para>

</sect2>

<sect2 id="nonlinearfittingpluginexample">
<title
>Esempio</title>
<para
>Quello che segue è un esempio di un plugin di regressione non lineare che effettua una regressione a un modello esponenziale.</para>
<informalexample>
<screen
>/*
 *  Plugin di regressione esponenziale per KST.
 *  Copyright 2004, Università della Columbia Britannica
 *  Rilasciato sotto le condizioni della GPL.
 */

#define NUM_PARAMS 3
#define MAX_NUM_ITERATIONS 500

#include "../non_linear.h"

void function_initial_estimate( const double* pdX, const double* pdY,
                                int iLength, double* pdParameterEstimates ) {
  KST_UNUSED( pdX )
  KST_UNUSED( pdY )
  KST_UNUSED( iLength )

  pdParameterEstimates[0] =  1.0;
  pdParameterEstimates[1] =  0.0;
  pdParameterEstimates[2] =  0.0;
}

double function_calculate( double dX, double* pdParameters ) {
  double dScale         = pdParameters[0];
  double dLambda = pdParameters[1];
  double dOffset = pdParameters[2];
  double dY;

  dY  = ( dScale * exp( -dLambda * dX ) ) + dOffset;

  return dY;
}

void function_derivative( double dX, double* pdParameters, double* pdDerivatives ) {
  double dScale         = pdParameters[0];
  double dLambda = pdParameters[1];
  double dExp;  
  double ddScale;
  double ddLambda;
  double ddOffset;
  
  dExp     = exp( -dLambda * dX );
  ddScale  = dExp;
  ddLambda = -dX * dScale * dExp;
  ddOffset = 1.0;

  pdDerivatives[0] = ddScale;
  pdDerivatives[1] = ddLambda;
  pdDerivatives[2] = ddOffset;
}

extern "C" int kstfit_exponential(const double *const inArrays[], const int inArrayLens[],
                const double inScalars[],
                double *outArrays[], int outArrayLens[],
                double outScalars[]);

int kstfit_exponential(const double *const inArrays[], const int inArrayLens[],
                const double inScalars[],
                double *outArrays[], int outArrayLens[],
                double outScalars[])
{
  return kstfit_nonlinear( inArrays, inArrayLens,
                           inScalars, outArrays,
                           outArrayLens, outScalars );
}
</screen>
</informalexample>

</sect2>
</sect1>

<sect1 id="creatingpassfilterplugins">
<title
>Creare plugin per filtri di passaggio</title>
<para
>&kst; fornisce dei file di intestazione per semplificare l'implementazione dei plugin per filtri di passaggio. L'uso di questi file di intestazione è descritto sotto. </para>
<sect2 id="creatingpassfilterpluginsheaderfiles">
<title
>File di intestazione</title>
<para
>Il file di intestazione dei filtri di passaggio è situato in <filename
>kst/plugins/pass_filters</filename
> del pacchetto sorgente di &kst;. Il file è chiamato <filename
>filters.h</filename
>. Per usare questo file, includilo nel codice sorgente del tuo plugin: <screen>
#include &lt;../filters.h&gt;
</screen
> (per convenzione, metteremo il codice sorgente del plugin una cartella sotto dove si trovano i file di intestazione). </para>
</sect2>

<sect2 id="creatingpassfilterpluginsrequirements">
<title
>Funzioni richieste</title>
<para
>Il file di intestazione <filename
>filters.h</filename
> contiene una sola funzione che calcola la trasformata di Fourier di una funzione data, applica il filtro dato alla trasformata di Fourier, e quindi calcola la trasformata di Fourier inversa della trasformata di Fourier filtrata. Per fornire il filtro, la seguente funzione deve essere implementata nel codice sorgente del tuo plugin: </para>
<para
><function
><returnvalue
>double</returnvalue
> filter_calculate( double <parameter
>dFreqValue</parameter
>, const double <parameter
>inScalars[]</parameter
> )</function
></para>
<para
>Questa funzione dovrebbe calcolare l'ampiezza filtrata per la frequenza <literal
>dFreqValue</literal
>. <literal
>inScalars[]</literal
> conterrà gli scalari di input inalterati per il plugin, specificati nel file XML. Molto probabilmente <literal
>inScalars[]</literal
> conterrà frequenze di taglio o altre proprietà del filtro. Per esempio, un'implementazione di un filtro passa-alto di Butterworth, <function
>filter_calculate</function
> potrebbe essere implementata come segue: </para>
<informalexample>
<screen
>double filter_calculate( double dFreqValue, const double inScalars[] ) {
  double dValue;
  if( dFreqValue 
> 0.0 ) {
    dValue = 1.0 / ( 1.0 +
                    pow( inScalars[1] / dFreqValue, 2.0 * (double)inScalars[0] ) );
  } else {
    dValue = 0.0;
  }
  return dValue;
}
</screen>
</informalexample>
</sect2>

<sect2 id="creatingpassfilterpluginscallingfunction">
<title
>Chiamare la funzione di filtro</title>
<para
>Una volta che la <function
>filter_calculate</function
> richiesta sarà stata implementata, potrà essere chiamata la funzione di filtraggio dal file di intestazione: </para>
<literallayout
><function
>kst_pass_filter( <parameter
>inArrays</parameter
>,
                 <parameter
>inArrayLens</parameter
>,
                 <parameter
>inScalars</parameter
>,
                 <parameter
>outArrays</parameter
>,
                 <parameter
>outArrayLens</parameter
>,
                 <parameter
>outScalars</parameter
> );</function
></literallayout>
<para
>Gli argomenti dati alla funzione C esportata possono normalmente essere passati a <function
>kst_pass_filter</function
> senza modifiche. Tuttavia, ci sono delle restrizioni sugli argomenti: </para>
<itemizedlist>
<listitem>
<para
><varname
>inArrays[0]</varname
> deve contenere l'array di dati da filtrare. </para>
</listitem>

<listitem>
<para
><varname
>inScalars</varname
> dovrebbe contenere i parametri specifici del filtro che la funzione <function
>filter_calculate</function
> deve usare. </para>
</listitem>
</itemizedlist>
<para
>Dopo la chiamata della funzione, <varname
>outArrays[0]</varname
> conterrà l'array di dati filtrati, e <varname
>outArrayLens</varname
> sarà impostato appropriatamente. La funzione <function
>kst_pass_filter</function
> non usa <varname
>outScalars</varname
>. </para>
</sect2>

<sect2 id="creatingpassfilterpluginsexample">
<title
>Esempio</title>
<para
>Quello che segue è un esempio di plugin di filtro di passaggio che implementa il filtro passa-alto di Butterworth. </para>
<informalexample>
<screen
>/*
 *  Plugin per il filtro passa-basso di Butterworth per KST.
 *  Copyright 2004, Università della Columbia Britannica
 *  Rilasciato sotto le condizioni della GPL.
 */

#include &lt;stdlib.h&gt;
#include &lt;math.h&gt;
#include "../filters.h"

extern "C" int butterworth_highpass(const double *const inArrays[], const int inArrayLens[],
                const double inScalars[],
                double *outArrays[], int outArrayLens[],
                double outScalars[]);

int butterworth_highpass(const double *const inArrays[], const int inArrayLens[],
                const double inScalars[],
                double *outArrays[], int outArrayLens[],
                double outScalars[])
{
  int iReturn;

  iReturn = kst_pass_filter( inArrays,
                             inArrayLens,
                             inScalars,
                             outArrays,
                             outArrayLens,
                             outScalars );

  return iReturn;
}

double filter_calculate( double dFreqValue, const double inScalars[] ) {
  double dValue;

  if( dFreqValue &gt; 0.0 ) {
    dValue = 1.0 / ( 1.0 + pow( inScalars[1] / dFreqValue, 2.0 * (double)inScalars[0] ) );
  } else {
    dValue = 0.0;
  }

  return dValue;
}</screen>
</informalexample>
</sect2>

</sect1>
</appendix>


<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-omittag:nil
sgml-shorttag:nil
sgml-namecase-general:nil
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:0
sgml-indent-data:true
sgml-parent-document:("index.docbook" "book" "appendix")
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->