<appendix id="creatingplugins">
<title
>Lav yderligere plugin</title>
<para
>&kst; har en enkel og standardiseret grænseflade som tillader nemt at lave  oprette yderligere plugin. Udover at give detaljer om grundlæggende krav for plugin, beskriver følgende afsnit hvordan færdigskrevne deklarationsfiler kan bruges til at lave visse slags plugin. </para>

<sect1 id="creatingbasicplugin">
<title
>Lav et basalt plugin</title>
<para
>Et &kst;-plugin består af to filer: en XML-fil og en delt objektfil. </para>

<sect2 id="creatingbasicpluginxmlfile">
<title
>XML-filen</title>
<para
>XML-filen sørger for information om plugin og beskriver dets inddata og uddata. Det følgende er et eksempel på en XML-fil for et &kst;-plugin: </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;moduletame name="testplugin"/&gt;    &lt;!-- Modulets navn --&gt;
&lt;author name="Rick Chern"/&gt; &lt;!-- Forfatterens navn --&gt;
&lt;description text="Et testplugin for mig"/&gt; &lt;!-- En beskrivelse af modulet --&gt;
&lt;version minor="1" major="0"/&gt;  &lt;!-- Modulets versionsnummer --&gt;
&lt;state devstate="release"/&gt;     &lt;!-- Udviklingstilstanden for modulet (valgfrit)--&gt;
&lt;/intro&gt;

&lt;interface&gt;

&lt;!--inputs here--&gt;
&lt;input&gt;
&lt;table type="float" name="Input Vector 1" descr="Den første inddatavektor" /&gt;
&lt;/input&gt;

&lt;input&gt;
&lt;float name="Input Scalar 1" descr="Den første inddataskalar" /&gt;
&lt;/input&gt;

&lt;!--outputs here--&gt;
&lt;output&gt;
&lt;table type="float" name="Output Vector 1" descr="Den første uddatavektor" /&gt;
&lt;/output&gt;

&lt;output&gt;
&lt;float name="Output Scalar 1" descr="Den første uddataskalar" /&gt;
&lt;/output&gt;

&lt;/interface&gt;

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

<para
>I almindelighed kan du bruge eksemplet ovenfor som en skabelon og ændre dele af det til at passe med dine behov. Som det ses i eksemplet, består 
XML-filen af knuden <literal
>module</literal
>. Knuden <literal
>module</literal
> indeholder knuderne <literal
>intro</literal
> og <literal
>interface</literal
>. Du skal ændre knuden <literal
>intro</literal
> på passende måde ved at bruge kommentarerne i XML-filen ovenfor som guider. Det er vigtigt at <literal
>moduletame</literal
> har egenskaben <literal
>name</literal
> sat til det samme navn som din delte objektfil vil bruge. </para>

<para
>Knuden <literal
>interface</literal
> beskriver pluginnets egentlige inddata og uddata. Hver inddataværdi beskrives af knuden <literal
>input</literal
>, og hver uddataværdi beskrives af knuden <literal
>output</literal
>. Hver inddataværdi eller uddataværdi skal enten have delknuden <literal
>table</literal
> eller <literal
>float</literal
>. Egenskaben <literal
>type</literal
> i en <literal
>table</literal
> skal være sat til <literal
>&quot;float&quot;</literal
>. Bemærk at rækkefølgen for inddata og uddata spiller en rolle: Rækkefølgen bruges til at afgøre indelsværdien for hver inddataværdi og uddataværdi i objektfilen, og er samme rækkefølge som de inddatafelter og uddatafelter der burges til at vise grænsefladen for plugin i &kst;. </para>

<para
>Når du er klar med XML-filen, gemmes den som <filename
>[modulnavn].xml</filename
>, hvor <filename
>[modulnavn]</filename
> er værdien for egenskaben <literal
>name</literal
> i knuden <literal
>moduletame</literal
>. </para>

</sect2>

<sect2 id="creatingbasicpluginobjectfile">
<title
>Den delte objektfil</title>
<para
>Den delte objektfil indeholder selve pluginnets funktion. Med andre ord afgør den hvordan uddata skal laves ud fra givne inddata. Følgende krav gælder for den delte objektfil: </para>

<itemizedlist>

<listitem>
<para
>Objektet skal eksportere følgende C-link-symboler: <literallayout
><function
><returnvalue
>int</returnvalue
> symbol(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
>hvor <replaceable
>symbol</replaceable
> skal være værdien på egenskaben <literal
>name</literal
> i knuden <literal
>moduletame</literal
> i XML-filen. Dette er den eneste funktion som vil blive kaldet af &kst; (selv om du kan have flere funktioner). Det følgende beskriver hvert argument for funktionen: </para>

<variablelist>
<varlistentry>
<term
><varname
>const double *const inArrays[]</varname
></term>
<listitem>
<para
>Feltet med inddatafelt. Hvert inddatafelt svarer til en inddatavektor. Felterne er i samme rækkefølge som vektorerne på listen i XML-filen, så <literal
>inArrays[0]</literal
> er feltet som representerer den første inddatavektor, <literal
>inArrays[1]</literal
> er feltet som representerer den andre inddatavektor, og så videre. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><varname
>const int inArraysLens[]</varname
></term>
<listitem>
<para
>Feltet som indeholder feltlængderne for hvert inddatafelt. Længderne opbevares i samme rækkefølge som felterne i <literal
>inArrays[]</literal
> (f.eks. er <literal
>inArrayLens[0]</literal
> længden på <literal
>inArrays[0]</literal
>). </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><varname
>const double inScalars[]</varname
></term>
<listitem>
<para
>Feltet med inddataskalarer. Skalarerne opbevares i samme rækkefølge som de er på listen i XML-filen. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><varname
>double *outArrays[]</varname
></term>
<listitem>
<para
>Feltet med uddatafelt. Hvert uddatafelt svarer til en uddatavektor, og felterne skal være i samme rækkefølge som uddatavektorerne er på listen i XML-filen. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><varname
>int outArrayLens[]</varname
></term>
<listitem>
<para
>Feltet som skal indeholde længderne på uddatafelterne. Længderne skal opbevares i samme rækkefølge som i felterne i <literal
>outArrays[]</literal
>. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><varname
>double outScalars[]</varname
></term>
<listitem>
<para
>Feltet med uddataskalarer. Skalarerne skal være i samme rækkefølge som de er på listen i XML-filen. </para>
</listitem>
</varlistentry>
</variablelist>


</listitem>

<listitem>
<para
>Funktionen skal returnere <literal
>0</literal
> hvis det lykkes at udføre den, og <literal
>-1</literal
> ellers. </para>
</listitem>

<listitem>
<para
>Koden i objektfilen skal håndtere uventede inddata, såsom tomme inddatafelter (i de fleste tilfælde er returværdien <literal
>-1</literal
> tilstrækkelig når sådanne situationer opstår). </para>
</listitem>

<listitem>
<para
>Antal og type af uddata skal være nøjagtigt som det angives i XML-filen. </para>
</listitem>

<listitem>
<para
>Du skal formodentlig ændre størrelse på felterne i <varname
>outArrays[]</varname
>. For at gøre det, bruges funktionen <function
>realloc()</function
>. For eksempel </para>
<informalexample>
<screen
>outArrays[0]=(double*)realloc(outArrays[0], 5*sizeof(double));
</screen>
</informalexample>
<para
>allokerer plads til fem dobbelte decimaltal i <varname
>outArrays[0]</varname
>. Brug ikke anden hukommelsesallokering end <function
>realloc()</function
>. </para>
</listitem>

<listitem>
<para
>Inddataargumenterne skal forblive konstante. Konvertér dem ikke til ikke-konstante typer. </para>
</listitem>

</itemizedlist>

<para
>Følgende er et eksempel på den delte objektfils kildekode for et enkelt plugin: </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[])

//Accept 1 vector and 1 scalar. Multiply all elements of the vector by the
//scalar, and output the resulting vector. Also output the original scalar.
{
        //Set the outputs
        outArrayLens[0]=inArrayLens[0];

        //resize the output arrays
        outArrays[0]=(double*)realloc(outArrays[0], inArrayLens[0]*sizeof(double));

        //multiply each element of the input vector
        //by the scalar
        for (int i=0; i&lt;inArrayLens[0]; i++)
        {
                outArrays[0][i]=inArrays[0][i] * is[0];
        }

        //now set the output scalar
        outScalars[0]=is[0];

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


<sect2 id="compilingplugin">
<title
>Kompilér pluginnet</title>
<para
>Hvis du bruger &gcc; til at kompilere pluginnet, kompileres objektfilen blot: <screen
><userinput
><command
>cc -Wall -c -o myplugin.o myplugin.c -fPIC -DPIC</command
></userinput
></screen>
</para>
<para
>og derefter oprettes det delte bibliotek: <screen
><userinput
><command
>ld -o myplugin.so -shared myplugin.o</command
></userinput
></screen>
</para>
<para
>De resulterende filer <filename
>*.so</filename
> og <filename
>*.xml</filename
> skal placeres i samme mappe. Når du bruger plugin-håndteringen i &kst; til at indlæse XML-filen, kigger den automatisk efter den delte objektfil i samme mappe. </para>

</sect2>
</sect1>

<sect1 id="creatinglinearfittingplugins">
<title
>Lav et plugin for lineærindstilling</title>
<para
>For at lave et plugin for lineærindstilling, kan du  implementere dine egne indstillingsalgoritmer og give passende vektorer som uddata. &kst; levereres dog allerede med deklarationsfiler som gør det enkelt for dig at implementere plugin for lineær mindste kvadratindstilling ved kun at sørge for nogle få funktioner. Dette afsnit beskriver hvordan man får nytte af disse filer. </para>

<sect2 id="headerslinearfittingplugins">
<title
>Deklarationsfiler</title>
<para
>Der sørges for to deklarationsfiler til at udføre lineærindstillinger, <filename
>linear.h</filename
> (for uvægtede lineærindstillinger) og <filename
>linear_weighted.h</filename
> (for vægtede lineærindstillinger). Begge findes under <filename
>kst(plugins/fits/ </filename
> i kildekodearkivet for &kst;. For at bruge filerne, inkluderes blot en af dem i dit plugins kildekode: <screen>
#include &lt;../linear.h&gt;
</screen
> eller <screen>
#include &lt;../linear_weighted.h&gt;
</screen
> (pr konvention placerer vi kildekoden for pluginnet et mappeniveau under stedet hvor deklarationsfilerne er). </para>

</sect2>

<sect2 id="reqfunctionsfittingplugins">
<title
>Implementér nødvendige funktioner</title>
<para
>Givet en generel lineær model: </para>
<para>
<inlinemediaobject>
<imageobject>
<imagedata fileref="Formula-kst-generallinearmodel.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</para>
<para
>hvor <literal
>y</literal
> er en vektor med <literal
>n</literal
> observationer, <literal
>X</literal
> er en matrix med størrelsen <literal
>n</literal
> gange <literal
>p</literal
> med prediktorvariabler, og <literal
>c</literal
> er vektoren med <literal
>p</literal
> parametre for bedste indstilling som skal estimeres. Deklarationsfilen sørger for funktioner til at estimere <literal
>c</literal
> for et givet <literal
>y</literal
> og <literal
>X</literal
>. For at sørge for <literal
>X</literal
>, skal følgende funktion implementeres i pluginnets kildekode: <literallayout
><function
><returnvalue
>double</returnvalue
> calculate_matrix_entry( double <parameter
>dX</parameter
>, int <parameter
>iPos</parameter
> )</function
></literallayout>
</para>
<para
>Funktionen skal returnere værdien af resultatet i søjle <literal
>iPos</literal
> fra matricen med prediktorvariabler, ved at bruge <literal
>x</literal
>-værdien <literal
>dX</literal
>. Funktionen kaldes af linear.h eller linear_weighted.h. Implementeringen af funktionen afhænger af modellen du vil bruge til indstillingen, og er entydig for hvert plugin for lineærindstilling. For eksempel for at tilpasse en polynommodel, vil funktionen <function
>calculate_matrix_entry</function
> kunne implementeres på følgende måde: <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
>Kalde tilpasningfunktionerne</title>
<para
>Når en passende deklarationsfil er inkluderet og funktionen <function
>calculate_matrix_entry</function
> er implementeret, kaldes en passende indstillingsfunktion som inkluderes fra deklarationsfilen: <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
> eller <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
>Hver funktion returnerer <literal
>0</literal
> når det lykkes, eller <literal
>-1</literal
> ved fejl, så det er en god idé at lade returværdien for den eksporterede C-funktion være den samme som returværdien for indstillingsfunktionen. For at holde det enkelt, kan koden for pluginnet blot sende argumenterne videre som gives til den eksporterede C-funktion til tilpasningsfunktionen. Bemærk dog at inArrays skal have følgende struktur: </para>
<itemizedlist>
<listitem>
<para
><varname
>inArrays[0]</varname
> skal indeholde feltet med x-koordinater for datapunkterne </para>
</listitem>

<listitem>
<para
><varname
>inArrays[1]</varname
> skal indeholde feltet med y-koordinater for datapunkterne </para>
</listitem>

<listitem>
<para
><varname
>inArrays[2]</varname
> er der kun hvis <function
>kstfit_linear_weighted</function
> kaldes, og skal indeholde feltet med vægtninger for tilpasningen. </para>
</listitem>
</itemizedlist>
<para
>Den nemmeste måde at sikre at inArrays er rigtigt struktureret er at angive de n rigtige rækkefølge for inddatavektorer i pluginnets XML-fil. </para>
<para
><varname
>iNumParams</varname
> er antal parametre som indgår i den brugte tilpasningsmodel, hvilket skal være lig med antal søjler i matricen <literal
>X</literal
> med prediktorvariabler. <varname
>iNumParams</varname
> skal angives rigtigt før tilpasningsfunktionen kaldes. </para>
<para
>Efter funktionen <function
>kstfit_linear_unweighted</function
> eller <function
>kstfit_linear_weighted</function
> er kaldet, er <varname
>outArrays</varname
> og <varname
>outScalars</varname
> blevet tildelt følgende: </para>
<itemizedlist>
<listitem>
<para
><varname
>outArrays[0]</varname
> vil indeholde feltet med tilpassede y-værdier. </para>
</listitem>

<listitem>
<para
><varname
>outArrays[1]</varname
> vil indeholde feltet med rester. </para>
</listitem>

<listitem>
<para
><varname
>outArrays[2]</varname
> vil indeholde feltet med estimerede parametre for bedste tilpasning. </para>
</listitem>

<listitem>
<para
><varname
>outArrays[3]</varname
> vil indeholde kovariansmatricen, returneret linje for linje i feltet. </para>
</listitem>

<listitem>
<para
><varname
>outScalars[0]</varname
> vil indeholde chi^2/nu, hvor chi^2 er den vægtede sum af kvadratresternes, og nu frihedsgraderne. </para>
</listitem>
</itemizedlist>
<para
><varname
>outArrayLens</varname
> vil have den rigtige værdi til at angive længden for hvert uddatafelt. </para>

<para
>Sørg for at angiven uddata i XML-filen passer sammen med dem som de eksporterede C-funktioner returnerer (hvilket i de fleste tilfælde simpelthen er uddata fra tilpasningsfunktionen). </para>


</sect2>

<sect2 id="examplelinearfittingplugins">
<title
>Eksempel</title>
<para
>Det følgende er et eksempel på kildekoden for et plugin for lineærindstilling. </para>
<informalexample>
<screen
>/*
 *  Polynomial fitting plugin for KST.
 *  Copyright 2004, The University of British Columbia
 *  Released under the terms of the 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
>Lav plugin for ikke-lineær indstilling</title>
<para
>&kst; sørger for deklarationsfiler for at forenkle implementeringen af plugin med ikke-lineære mindste kvadrat tilpasning. Brugen af deklarationsfilerne beskrives nedenfor. </para>

<sect2 id="headersnonlinearfittingplugins">
<title
>Deklarationsfiler og definitioner</title>
<para
>Deklarationsfilerne for ikke-lineær indstilling er under <filename
>kst(plugins/fits_nonlinear/</filename
> i kildekodearkivet for &kst;. Filerne hedder <filename
>non_linear.h</filename
> og <filename
>non_linear_weighted.h</filename
> for henholdsvis uvægtede og vægtede tilpasninger. For at bruge filerne, inkluderes kun en af dem i dit plugins kildekode: <screen>
#include &lt;../non_linear.h&gt;
</screen
> eller <screen>
#include &lt;../non_linear_weighted.h&gt;
</screen
> (pr konvention placerer vi kildekoden for pluginnet et mappeniveau under stedet hvor deklarationsfilerne er). </para>

<para
>Eftersom ikke-lineær tilpasning er en iterativ proces, skal du også definere et maksimalt antal iterationer som skal udføres. Algoritmen for ikke-lineær indstilling stopper når mindst en af følgende betingelser er sand: </para>
<itemizedlist>
<listitem>
<para
>Maksimalt antal iterationer er opnået. </para>
</listitem>
<listitem>
<para
>Præcisionen 10<superscript
>-4</superscript
> er opnået. </para>
</listitem>
</itemizedlist>
<para
>Desuden skal du definere antal parametre i modellen, eftersom de ikke eksplicit sendes til tilpasningsfunktionen. For at definere disse to værdier, inkluderes følgende længst oppe i din kildekode: </para>
<screen
>#define NUM_PARAMS [num1]
#define MAX_NUM_ITERATIONS [num2]
</screen>
<para
>som erstatter <literal
>[num1]</literal
> med antal parametre i modellen, og <literal
>[num2]</literal
> med maksimalt antal iterationer at udføre. </para>
</sect2>

<sect2 id="reqfunctionsnonlinearfittingplugins">
<title
>Implementér nødvendige funktioner</title>
<para
>For at bruge deklarationsfilen for ikke-lineær tilpasning, skal du sørge for funktionen som skal bruges som model, partielle afledede for funktionen med hensyn til hver parameter og de oprindelige estimater for parametrene for bedste tilpasning. For at gøre dette skal tre funktioner implementeres. Disse funktioner beskrives nedenfor. </para>
<variablelist>
<varlistentry>
<term
><function
><returnvalue
>double</returnvalue
> function_calculate( double <parameter
>dX</parameter
>, double* <parameter
>pdParameters</parameter
> )</function
></term>
<listitem>
<para
>Denne funktion beregner Y-værdien for tilpasningsmodellen for en given X-værdi <literal
>dX</literal
>, med det felt der sørges for med parametre <varname
>pdParameters</varname
>. Parametrenes rækkefølge i <varname
>pdParameters</varname
> er vilkårlig, men skal stemme overens med de to andre implementerede funktioner. For eksempel for en eksponentiel model, vil <function
>function_calculate</function
> kunne implementeres på følgende måde: </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
>Denne funktion beregner partielle afledede for modelfunktionen for en givet X-værdi <literal
>dX</literal
>. De partielle afledede skal returneres i <varname
>pdDerivatives</varname
>. Rækkefølgen af de partielle afledede i feltet <varname
>pdDerivatives</varname
> skal svare til rækkefølgen af parametrene i <varname
>pdParameters</varname
> (dvs. hvis <varname
>pdParameters[0]</varname
> indeholder parameteren lambda for en eksponentialmodel, skal <varname
>pdDerivatives[0]</varname
> indeholde den afledede for modellen med hensyn til 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
>Denne funktion sørger for et oprindelig estimat af parametrene for bedste tilpasning for tilpasningsfunktionen. Feltet med X- og Y-værdier for datapunkterne er henholdsvis i <varname
>pdX</varname
> og <varname
>pdY</varname
>, og antal datapunkter angives af <varname
>iLength</varname
>. Du kan bruge alle eller ingen af parametrene efter behag til at beregne det oprindelige estimat. Funktionen skal placere de beregnede oprindelige estimater i <varname
>pdParameterEstimates</varname
>, og lade estimaternes rækkefølge stemme med rækkefølgen for parametrene i <varname
>pdParameters</varname
> i <function
>function_calculate</function
> og <function
>function_derivative</function
>. Husk at det oprindelige estimat er vigtigt for at afgøre om tilpasningsfunktionen konvergerer mod en løsning. </para>
</listitem>
</varlistentry>

</variablelist>

</sect2>

<sect2 id="callingnonlinearfittingplugins">
<title
>Kalde tilpasningfunktionerne</title>
<para
>Når alle nødvendige funktioner er implementeret, kan tilpasningsfunktionen fra den inkluderede deklarationsfil kaldes: <screen>
kstfit_nonlinear( <parameter
>inArrays</parameter
>, <parameter
>inArrayLens</parameter
>,
                  <parameter
>inScalars</parameter
>, <parameter
>outArrays</parameter
>,
                  <parameter
>outArrayLens</parameter
>, <parameter
>outScalars</parameter
> );
</screen
> eller <screen>
kstfit_nonlinear_weighted( <parameter
>inArrays</parameter
>, <parameter
>inArrayLens</parameter
>,
                           <parameter
>inScalars</parameter
>, <parameter
>outArrays</parameter
>,
                           <parameter
>outArrayLens</parameter
>, <parameter
>outScalars</parameter
> );
</screen
> afhængig af om du implementerer en uvægtet tilpasning eller en vægtet tilpasning. </para>

<para
>Funktionen returnerer <literal
>0</literal
> når det lykkes, eller <literal
>-1</literal
> ved en fejl, så det er nemmest at lade returværdien for den eksporterede C-funktion være den samme som returværdien for tilpasningsfunktionen. For at holde det enkelt, kan koden for pluginnet blot sende argumenterne som gives videre til den eksporterede C-funktion til tilpasningsfunktionen. Bemærk dog at inArrays skal have følgende struktur: </para>
<itemizedlist>
<listitem>
<para
><varname
>inArrays[0]</varname
> skal indeholde feltet med x-koordinater for datapunkterne </para>
</listitem>

<listitem>
<para
><varname
>inArrays[1]</varname
> skal indeholde feltet med y-koordinater for datapunkterne </para>
</listitem>

<listitem>
<para
><varname
>inArrays[2]</varname
> er der kun hvis <function
>kstfit_linear_weighted</function
> kaldes, og skal indeholde feltet med vægtninger for tilpasningen. </para>
</listitem>
</itemizedlist>
<para
>Den nemmeste måde at sikre at inArrays er rigtigt struktureret er at angive de n rigtige rækkefølge for inddatavektorer i pluginnets XML-fil. </para>
<para
>Efter funktionen <function
>kstfit_linear_unweighted</function
> eller <function
>kstfit_linear_weighted</function
> er kaldet, er <varname
>outArrays</varname
> og <varname
>outScalars</varname
> blevet tildelt følgende: </para>
<itemizedlist>
<listitem>
<para
><varname
>outArrays[0]</varname
> vil indeholde feltet med tilpassede y-værdier. </para>
</listitem>

<listitem>
<para
><varname
>outArrays[1]</varname
> vil indeholde feltet med rester. </para>
</listitem>

<listitem>
<para
><varname
>outArrays[2]</varname
> vil indeholde feltet med estimerede parametre for bedste tilpasning. </para>
</listitem>

<listitem>
<para
><varname
>outArrays[3]</varname
> vil indeholde kovariansmatricen, returneret linje for linje i feltet. </para>
</listitem>

<listitem>
<para
><varname
>outScalars[0]</varname
> vil indeholde chi^2/nu, hvor chi^2 er den vægtede sum af kvadratresternes, og nu frihedsgraderne. </para>
</listitem>
</itemizedlist>
<para
><varname
>outArrayLens</varname
> vil have den rigtige værdi til at angive længden for hvert uddatafelt. </para>

<para
>Sørg for at angiven uddata i XML-filen passer sammen med dem som de eksporterede C-funktioner returnerer (hvilket i de fleste tilfælde simpelthen er uddata fra tilpasningsfunktionen). </para>

</sect2>

<sect2 id="nonlinearfittingpluginexample">
<title
>Eksempel</title>
<para
>Det følgende er et eksempel på et ikke-lineært tilpasningsplugin som udfører en tilpasning til en eksponentiel model.</para>
<informalexample>
<screen
>/*
 *  Exponential fit plugin for KST.
 *  Copyright 2004, The University of British Columbia
 *  Released under the terms of the 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_eksponential(const double *const inArrays[], const int inArrayLens[],
                const double inScalars[],
                double *outArrays[], int outArrayLens[],
                double outScalars[]);

int kstfit_eksponential(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
>Lav plugin for passfilter</title>
<para
>&kst; sørger for deklarationsfiler for at forenkle implementeringen af plugin med passfilter. Brugen af deklarationsfilerne beskrives nedenfor. </para>
<sect2 id="creatingpassfilterpluginsheaderfiles">
<title
>Deklarationsfiler</title>
<para
>Deklarationsfilen for passfiltret er i <filename
>kst/plugins/pass_filters</filename
> i kildekodearkivet for &kst;. Filen hedder <filename
>filters.h</filename
>. For at bruge filen, inkluderes den i dit plugins kildekode: <screen>
#include &lt;../filters.h&gt;
</screen
> (pr konvention placerer vi kildekoden for pluginnet et mappeniveau under stedet hvor deklarationsfilerne er). </para>
</sect2>

<sect2 id="creatingpassfilterpluginsrequirements">
<title
>Nødvendige funktioner</title>
<para
>Deklarationsfilen <filename
>filters.h</filename
> indeholder en enkelt funktion som beregner Fouriertransformationen for en funktion der sørges for, anvender det filter der er sørget for på Fouriertransformationen og derefter beregner den inverse Fouriertransformation for den filtrerede transformen. For at sørge for filtret, skal følgende funktion implementeres i dit plugins kildekode: </para>
<para
><function
><returnvalue
>double</returnvalue
> filter_calculate( double <parameter
>dFreqValue</parameter
>, const double <parameter
>inScalars[]</parameter
> )</function
></para>
<para
>Funktionen skal beregne filtreret amplitude for frekvensen <literal
>dFreqValue</literal
>. <literal
>inScalars[]</literal
> indeholder de uændrede inddataskalarer for pluginnet, som angives i XML-filen. Sandsynligvis indeholder <literal
>inScalars[]</literal
> afskæringsfrekvenser eller andre egenskaber for filtret. For eksempel for at implementere et Butterworth højpassfilter, kan funktionen <function
>filter_calculate</function
> implementeres som følger: </para>
<informalexample>
<screen
>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>

<sect2 id="creatingpassfilterpluginscallingfunction">
<title
>Kald filterfunktionen</title>
<para
>Så snart den nødvendige <function
>filter_calculate</function
> er implementeret, kan filterfunktionen fra deklarationsfilen kaldes: </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
>Argumenterne som sendes til den eksporterede C-funktion kan sædvanligvis sendes til <function
>kst_pass_filter</function
> uden ændringer. Der er dog nogle begrænsninger for argumenterne: </para>
<itemizedlist>
<listitem>
<para
><varname
>inArrays[0]</varname
> skal indeholde feltet med data der skal filtreres. </para>
</listitem>

<listitem>
<para
><varname
>inScalars</varname
> skal indeholde filterspecifikke parametre som skal bruges af funktionen <function
>filter_calculate</function
>. </para>
</listitem>
</itemizedlist>
<para
>Efter funktionskaldet kommer <varname
>outArrays[0]</varname
> til at indeholde det filtrerede datafelt, og <varname
>outArrayLens</varname
> vil blive sat passende. Funktionen <function
>kst_pass_filter</function
> bruger ikke <varname
>outScalars</varname
>. </para>
</sect2>

<sect2 id="creatingpassfilterpluginsexample">
<title
>Eksempel</title>
<para
>Det følgende er et eksempel på et plugin med et passfilter som implementerer Butterworth højpassfiltrering. </para>
<informalexample>
<screen
>/*
 *  Butterworth low pass filter plugin for KST.
 *  Copyright 2004, The University of British Columbia
 *  Released under the terms of the 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>