<appendix id="creatingplugins">
<title
>Skapa ytterligare insticksprogram</title>
<para
>&kst; har ett enkelt och standardiserat gränssnitt som tillåter att enkelt skapa ytterligare insticksprogram. Förutom att ge detaljer om grundläggande krav för insticksprogram, beskriver följande avsnitt hur färdigskrivna deklarationsfiler kan användas för att skapa vissa sorters insticksprogram. </para>

<sect1 id="creatingbasicplugin">
<title
>Skapa ett enkelt insticksprogram</title>
<para
>Ett &kst;-insticksprogram består av två filer: en XML-fil och en delad objektfil. </para>

<sect2 id="creatingbasicpluginxmlfile">
<title
>XML-filen</title>
<para
>XML-filen tillhandahåller information om insticksprogrammet och beskriver dess indata och utdata. Det följande är ett exempel på en XML-fil för ett &kst;-insticksprogram: </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="testplugin"/&gt;    &lt;!-- Modulens namn --&gt;
&lt;author name="Rick Chern"/&gt; &lt;!-- Författarens namn --&gt;
&lt;description text="Ett testinsticksprogram för mig"/&gt; &lt;!-- En beskrivning av modulen --&gt;
&lt;version minor="1" major="0"/&gt;  &lt;!-- Modulens versionsnummer --&gt;
&lt;state devstate="release"/&gt;     &lt;!-- Utvecklingstillståndet för modulen (valfritt)--&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örsta indatavektorn" /&gt;
&lt;/input&gt;

&lt;input&gt;
&lt;float name="Input Scalar 1" descr="Den första indataskalären" /&gt;
&lt;/input&gt;

&lt;!--outputs here--&gt;
&lt;output&gt;
&lt;table type="float" name="Output Vector 1" descr="Den första utdatavektorn" /&gt;
&lt;/output&gt;

&lt;output&gt;
&lt;float name="Output Scalar 1" descr="Den första utdataskalären" /&gt;
&lt;/output&gt;

&lt;/interface&gt;

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

<para
>I allmänhet kan du använda exemplet ovan som en mall och ändra delar för att passa dina behov. Som syns i exemplet, består 
XML-filen av noden <literal
>module</literal
>. Noden <literal
>module</literal
> innehåller noderna <literal
>intro</literal
> och <literal
>interface</literal
>. Du måste ändra noden <literal
>intro</literal
> på lämpligt sätt genom att använda kommentarerna i XML-filen ovan som guider. Det är viktigt att <literal
>modulename</literal
> har egenskapen <literal
>name</literal
> satt till samma namn som den delade objektfilen kommer att använda. </para>

<para
>Noden <literal
>interface</literal
> beskriver insticksprogrammets verkliga indata och utdata. Varje indatavärde beskrivs av noden <literal
>input</literal
>, och varje utdatavärde beskrivs av noden <literal
>output</literal
>. Varje indatavärde eller utdatavärde ska antingen ha delnoden <literal
>table</literal
> eller <literal
>float</literal
>. Egenskapen <literal
>type</literal
> i en <literal
>table</literal
> måste vara satt till <literal
>&quot;float&quot;</literal
>. Observera att ordningen för indata och utdata spelar roll: Ordningen används för att avgöra indexvärdet för varje indatavärde och utdatavärde i objektfilen, och är samma ordning som indatafälten och utdatafälten visas i gränssnittet för insticksprogram i &kst;. </para>

<para
>När du väl är klar med XML-filen, spara den som <filename
>[modulnamn].xml</filename
>, där <filename
>[modulnamn]</filename
> är värdet på egenskapen <literal
>name</literal
> i noden <literal
>modulename</literal
>. </para>

</sect2>

<sect2 id="creatingbasicpluginobjectfile">
<title
>Den delade objektfilen</title>
<para
>Den delade objektfilen innehåller insticksprogrammets själva funktion. Med andra ord avgör den hur utdata ska skapas från given indata. Följande krav gäller för den delade objektfilen: </para>

<itemizedlist>

<listitem>
<para
>Objektet måste exportera följande C-länksymboler: <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
>där <replaceable
>symbol</replaceable
> måste vara värdet på egenskapen <literal
>name</literal
> i noden <literal
>modulename</literal
> i XML-filen. Det här är den enda funktionen som kommer att anropas av &kst; (även om du kan ha flera funktioner). Det följande beskriver varje argument till funktionen: </para>

<variablelist>
<varlistentry>
<term
><varname
>const double *const inArrays[]</varname
></term>
<listitem>
<para
>Fältet med indatafält. Varje indatafält motsvarar en indatavektor. Fälten är i samma ordning som vektorerna listas i XML-filen, så <literal
>inArrays[0]</literal
> är fältet som representerar den första indatavektorn, <literal
>inArrays[1]</literal
> är fältet som representerar den andra indatavektorn, och så vidare. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><varname
>const int inArraysLens[]</varname
></term>
<listitem>
<para
>Fältet som innehåller fältlängderna för varje indatafält. Längderna lagras i samma ordning som fälten i <literal
>inArrays[]</literal
> (t.ex. är <literal
>inArrayLens[0]</literal
> längden på <literal
>inArrays[0]</literal
>). </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><varname
>const double inScalars[]</varname
></term>
<listitem>
<para
>Fältet med indataskalärer. Skalärerna lagras i samma ordning som de listas i XML-filen. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><varname
>double *outArrays[]</varname
></term>
<listitem>
<para
>Fältet med utdatafält. Varje utdatafält motsvarar en utdatavektor, och fälten ska vara i samma ordning som utdatavektorerna listas i XML-filen. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><varname
>int outArrayLens[]</varname
></term>
<listitem>
<para
>Fältet som ska innehålla längderna för utdatafälten. Längderna ska lagras i samma ordning som i fälten i <literal
>outArrays[]</literal
>. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><varname
>double outScalars[]</varname
></term>
<listitem>
<para
>Fältet med utdataskalärer. Skalärerna ska vara i samma ordning som de listas i XML-filen. </para>
</listitem>
</varlistentry>
</variablelist>


</listitem>

<listitem>
<para
>Funktionen måste returnera <literal
>0</literal
> om den utfördes med lyckat resultat, och <literal
>-1</literal
> annars. </para>
</listitem>

<listitem>
<para
>Koden i objektfilen måste hantera oväntad indata, som tomma indatafält (i de flesta fall är returvärdet <literal
>-1</literal
> tillräckligt när sådana situationer uppstår). </para>
</listitem>

<listitem>
<para
>Antal och typ av utdata måste vara exakt som det anges i XML-filen. </para>
</listitem>

<listitem>
<para
>Du måste troligen ändra storlek på fälten i <varname
>outArrays[]</varname
>. För att göra det, använd funktionen <function
>realloc()</function
>. Till exempel </para>
<informalexample>
<screen
>outArrays[0]=(double*)realloc(outArrays[0], 5*sizeof(double));
</screen>
</informalexample>
<para
>allokerar utrymme för fem dubbla flyttal i <varname
>outArrays[0]</varname
>. Använd inte någon annan minnesallokering än <function
>realloc()</function
>. </para>
</listitem>

<listitem>
<para
>Indataargumenten måste förbli konstanta. Konvertera dem inte till icke-konstanta typer. </para>
</listitem>

</itemizedlist>

<para
>Följande är ett exempel på den delade objektfilens källkod för ett enkelt insticksprogram: </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
>Kompilera insticksprogrammet</title>
<para
>Om du använder &gcc; för att kompilera insticksprogrammet, kompilera helt enkelt objektfilen: <screen
><userinput
><command
>cc -Wall -c -o myplugin.o myplugin.c -fPIC -DPIC</command
></userinput
></screen>
</para>
<para
>och skapa därefter det delade biblioteket: <screen
><userinput
><command
>ld -o myplugin.so -shared myplugin.o</command
></userinput
></screen>
</para>
<para
>Resulterande filerna <filename
>*.so</filename
> och <filename
>*.xml</filename
> måste placeras i samma katalog. När du använder instickshanteringen i &kst; för att ladda XML-filen, letar den automatiskt efter den delade objektfilen i samma katalog. </para>

</sect2>
</sect1>

<sect1 id="creatinglinearfittingplugins">
<title
>Skapa insticksprogram för linjäranpassning</title>
<para
>För att skapa ett insticksprogram för linjäranpassning, skulle du kunna implementera dina egna anpassningsalgoritmer och ge lämpliga vektorer som utdata. &kst; levereras dock redan med deklarationsfiler som gör det enkelt för dig att implementera insticksprogram för linjär minsta kvadratanpassning genom att bara tillhandahålla några få funktioner. Det här avsnittet beskriver hur man drar nytta av dessa filer. </para>

<sect2 id="headerslinearfittingplugins">
<title
>Deklarationsfiler</title>
<para
>Två deklarationsfiler tillhandahålls för att utföra linjäranpassningar, <filename
>linear.h</filename
> (för oviktade linjäranpassningar) och <filename
>linear_weighted.h</filename
> (för viktade linjäranpassningar). Båda finns under <filename
>kst(plugins/fits/ </filename
> i källkodsarkivet för &kst;. För att använda filerna, inkludera bara en av dem i ditt insticksprograms källkod: <screen>
#include &lt;../linear.h&gt;
</screen
> eller <screen>
#include &lt;../linear_weighted.h&gt;
</screen
> (som konvention placerar vi källkoden för insticksprogrammet en katalognivå under platsen där deklarationsfilerna finns). </para>

</sect2>

<sect2 id="reqfunctionsfittingplugins">
<title
>Implementera nödvändiga funktioner</title>
<para
>Given en allmän linjär modell: </para>
<para>
<inlinemediaobject>
<imageobject>
<imagedata fileref="Formula-kst-generallinearmodel.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</para>
<para
>där <literal
>y</literal
> är en vektor med <literal
>n</literal
> observationer, <literal
>X</literal
> är en matris med storleken <literal
>n</literal
> gånger <literal
>p</literal
> med prediktorvariabler, och <literal
>c</literal
> är vektorn med <literal
>p</literal
> parametrar för bästa anpassning som ska uppskattas. Deklarationsfilen tillhandahåller funktioner för att uppskatta <literal
>c</literal
> för ett givet <literal
>y</literal
> och <literal
>X</literal
>. För att tillhandahålla <literal
>X</literal
>, måste följande funktion implementeras i insticksprogrammets källkod: <literallayout
><function
><returnvalue
>double</returnvalue
> calculate_matrix_entry( double <parameter
>dX</parameter
>, int <parameter
>iPos</parameter
> )</function
></literallayout>
</para>
<para
>Funktionen ska returnera värdet på resultatet i kolumn <literal
>iPos</literal
> från matrisen med prediktorvariabler, genom att använda <literal
>x</literal
>-värdet <literal
>dX</literal
>. Funktionen anropas av linear.h eller linear_weighted.h. Implementeringen av funktionen beror på modellen du vill använda för anpassningen, och är unik för varje insticksprogram för linjäranpassning. För att till exempel anpassa till en polynommodell, skulle funktionen <function
>calculate_matrix_entry</function
> kunna implementeras på följande sätt: <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
>Anropa anpassningsfunktionerna</title>
<para
>När lämplig deklarationsfil har inkluderats och funktionen <function
>calculate_matrix_entry</function
> har implementerats, anropa lämplig anpassningsfunktion som inkluderats från 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
>Varje funktion returnerar <literal
>0</literal
> när de lyckas, eller <literal
>-1</literal
> vid fel, så det är en god idé att låta returvärdet för den exporterade C-funktionen vara samma som returvärdet för anpassningsfunktionen. För att hålla det enkelt, kan koden för insticksprogrammet helt enkelt skicka vidare argumenten som ges till den exporterade C-funktionen till anpassningsfunktionen. Observera dock att inArrays måste ha följande struktur: </para>
<itemizedlist>
<listitem>
<para
><varname
>inArrays[0]</varname
> måste innehålla fältet med x-koordinater för datapunkterna </para>
</listitem>

<listitem>
<para
><varname
>inArrays[1]</varname
> måste innehålla fältet med y-koordinater för datapunkterna </para>
</listitem>

<listitem>
<para
><varname
>inArrays[2]</varname
> finns bara om <function
>kstfit_linear_weighted</function
> anropas, och måste innehålla fältet med viktningar för anpassningen. </para>
</listitem>
</itemizedlist>
<para
>Det enklaste sättet att försäkra att inArrays är riktigt strukturerad är att ange rätt ordning för indatavektorer i insticksprogrammets XML-fil. </para>
<para
><varname
>iNumParams</varname
> är antalet parametrar som ingår i den använda anpassningsmodellen, vilket ska vara lika med antal kolumner i matrisen <literal
>X</literal
> med prediktorvariabler. <varname
>iNumParams</varname
> måste anges riktigt innan anpassningsfunktionen anropas. </para>
<para
>Efter funktionen <function
>kstfit_linear_unweighted</function
> eller <function
>kstfit_linear_weighted</function
> anropas, har <varname
>outArrays</varname
> och <varname
>outScalars</varname
> tilldelats följande: </para>
<itemizedlist>
<listitem>
<para
><varname
>outArrays[0]</varname
> kommer att innehålla fältet med anpassade y-värden. </para>
</listitem>

<listitem>
<para
><varname
>outArrays[1]</varname
> kommer att innehålla fältet med rester. </para>
</listitem>

<listitem>
<para
><varname
>outArrays[2]</varname
> kommer att innehålla fältet med uppskattade parametrar för bästa anpassning. </para>
</listitem>

<listitem>
<para
><varname
>outArrays[3]</varname
> kommer att innehålla kovariansmatrisen, returnerad rad för rad i fältet. </para>
</listitem>

<listitem>
<para
><varname
>outScalars[0]</varname
> kommer att innehålla χ²/ν, där χ² är viktad summa av resternas kvadrater, och ν är frihetsgraden. </para>
</listitem>
</itemizedlist>
<para
><varname
>outArrayLens</varname
> kommer att har rätt värde för att ange längden för varje utdatafält. </para>

<para
>Försäkra dig om att angiven utdata i XML-filen passar ihop med den som de exporterade C-funktionerna returnerar (vilket i de flesta fall helt enkelt är utdata från anpassningsfunktionen). </para>


</sect2>

<sect2 id="examplelinearfittingplugins">
<title
>Exempel</title>
<para
>Det följande är ett exempel på källkoden för ett insticksprogram för linjäranpassning. </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
>Skapa insticksprogram för icke-linjär anpassning</title>
<para
>&kst; tillhandahåller deklarationsfiler för att förenkla implementeringen av insticksprogram med icke-linjära minsta kvadrat anpassning. Användningen av deklarationsfilerna beskrivs nedan. </para>

<sect2 id="headersnonlinearfittingplugins">
<title
>Deklarationsfiler och definitioner</title>
<para
>Deklarationsfilerna för icke-linjär anpassning finns under <filename
>kst(plugins/fits_nonlinear/</filename
> i källkodsarkivet för &kst;. Filerna heter <filename
>non_linear.h</filename
> och <filename
>non_linear_weighted.h</filename
> för respektive oviktade och viktade anpassningar. För att använda filerna, inkludera bara en av dem i ditt insticksprograms källkod: <screen>
#include &lt;../non_linear.h&gt;
</screen
> eller <screen>
#include &lt;../non_linear_weighted.h&gt;
</screen
> (som konvention placerar vi källkoden för insticksprogrammet en katalognivå under platsen där deklarationsfilerna finns). </para>

<para
>Eftersom icke-linjär anpassning är en iterativ process, måste du också definiera maximalt antal iterationer som ska utföras. Algoritmen för icke-linjär anpassning stoppar när minst ett av följande villkor är sant: </para>
<itemizedlist>
<listitem>
<para
>Maximalt antal iterationer har uppnåtts. </para>
</listitem>
<listitem>
<para
>Precisionen 10<superscript
>-4</superscript
> har uppnåtts. </para>
</listitem>
</itemizedlist>
<para
>Dessutom måste du definiera antal parametrar i modellen, eftersom det inte explicit skickas till anpassningsfunktionen. För att definiera dessa två värden, inkludera följande längst upp i din källkod: </para>
<screen
>#define NUM_PARAMS [num1]
#define MAX_NUM_ITERATIONS [num2]
</screen>
<para
>som ersätter <literal
>[num1]</literal
> med antal parametrar i modellen, och <literal
>[num2]</literal
> med maximalt antal iterationer att utföra. </para>
</sect2>

<sect2 id="reqfunctionsnonlinearfittingplugins">
<title
>Implementera nödvändiga funktioner</title>
<para
>För att använda deklarationsfilen för icke-linjär anpassning, måste du tillhandahålla funktionen som ska användas som modell, partiella derivatorna för funktionen med avseende på varje parameter och ursprungliga uppskattningar för parametrarna för bästa anpassning. För att göra det måste tre funktioner implementeras. Dessa funktioner beskrivs nedan. </para>
<variablelist>
<varlistentry>
<term
><function
><returnvalue
>double</returnvalue
> function_calculate( double <parameter
>dX</parameter
>, double* <parameter
>pdParameters</parameter
> )</function
></term>
<listitem>
<para
>Den här funktionen beräknar Y-värdet för anpassningsmodellen för ett givet X-värde <literal
>dX</literal
>, med det tillhandahållna fältet med parametrar <varname
>pdParameters</varname
>. Parametrarnas ordning i <varname
>pdParameters</varname
> är godtycklig, men måste stämma med de två andra implementerade funktionerna. Till exempel för en exponentiell modell, skulle <function
>function_calculate</function
> kunna implementeras på följande sätt: </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
>Den här funktionen beräknar partiella derivatorna för modellfunktionen för ett givet X-värde <literal
>dX</literal
>. De partiella derivatorna ska returneras i <varname
>pdDerivatives</varname
>. Ordningen av de partiella derivatorna i fältet <varname
>pdDerivatives</varname
> ska motsvara ordningen av parametrarna i <varname
>pdParameters</varname
> (dvs. om <varname
>pdParameters[0]</varname
> innehåller parametern lambda för en exponentialmodell, ska <varname
>pdDerivatives[0]</varname
> innehålla derivatan för modellen med avseende på 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
>Den här funktionen tillhandahåller en ursprunglig uppskattning av parametrarna för bästa anpassning till anpassningsfunktionen. Fälten med X- och Y-värden för datapunkterna tillhandahålls i respektive <varname
>pdX</varname
> och <varname
>pdY</varname
>, och antal datapunkter anges av <varname
>iLength</varname
>. Du kan använda alla eller ingen av parametrarna enligt eget tycke för att beräkna den ursprungliga uppskattningen. Funktionen ska placera de beräknade ursprungliga uppskattningarna i <varname
>pdParameterEstimates</varname
>, och låta uppskattningarnas ordning stämma med ordningen för parametrarna i <varname
>pdParameters</varname
> i <function
>function_calculate</function
> och <function
>function_derivative</function
>. Kom ihåg att den ursprungliga uppskattningen är viktig för att avgöra om anpassningsfunktionen konvergerar till en lösning. </para>
</listitem>
</varlistentry>

</variablelist>

</sect2>

<sect2 id="callingnonlinearfittingplugins">
<title
>Anropa anpassningsfunktionerna</title>
<para
>När alla nödvändiga funktioner har implementerats, kan anpassningsfunktionen från den inkluderade deklarationsfilen anropas: <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
> beroende på om du implementerar en oviktad anpassning eller en viktad anpassning. </para>

<para
>Funktionen returnerar <literal
>0</literal
> när den lyckas, eller <literal
>-1</literal
> vid ett fel, så det är enklast att låta returvärdet för den exporterade C-funktionen vara samma som returvärdet för anpassningsfunktionen. För att hålla det enkelt, kan koden för insticksprogrammet helt enkelt skicka vidare argumenten som ges till den exporterade C-funktionen till anpassningsfunktionen. Observera dock att inArrays måste ha följande struktur: </para>
<itemizedlist>
<listitem>
<para
><varname
>inArrays[0]</varname
> måste innehålla fältet med x-koordinater för datapunkterna </para>
</listitem>

<listitem>
<para
><varname
>inArrays[1]</varname
> måste innehålla fältet med y-koordinater för datapunkterna </para>
</listitem>

<listitem>
<para
><varname
>inArrays[2]</varname
> finns bara om <function
>kstfit_linear_weighted</function
> anropas, och måste innehålla fältet med viktningar för anpassningen. </para>
</listitem>
</itemizedlist>
<para
>Det enklaste sättet att försäkra att inArrays är riktigt strukturerad är att ange rätt ordning för indatavektorer i insticksprogrammets XML-fil. </para>
<para
>Efter funktionen <function
>kstfit_linear_unweighted</function
> eller <function
>kstfit_linear_weighted</function
> anropas, har <varname
>outArrays</varname
> och <varname
>outScalars</varname
> tilldelats följande: </para>
<itemizedlist>
<listitem>
<para
><varname
>outArrays[0]</varname
> kommer att innehålla fältet med anpassade y-värden. </para>
</listitem>

<listitem>
<para
><varname
>outArrays[1]</varname
> kommer att innehålla fältet med rester. </para>
</listitem>

<listitem>
<para
><varname
>outArrays[2]</varname
> kommer att innehålla fältet med uppskattade parametrar för bästa anpassning. </para>
</listitem>

<listitem>
<para
><varname
>outArrays[3]</varname
> kommer att innehålla kovariansmatrisen, returnerad rad för rad i fältet. </para>
</listitem>

<listitem>
<para
><varname
>outScalars[0]</varname
> kommer att innehålla χ²/ν, där χ² är viktad summa av resternas kvadrater, och ν är frihetsgraden. </para>
</listitem>
</itemizedlist>
<para
><varname
>outArrayLens</varname
> kommer att har rätt värde för att ange längden för varje utdatafält. </para>

<para
>Försäkra dig om att angiven utdata i XML-filen passar ihop med den som de exporterade C-funktionerna returnerar (vilket i de flesta fall helt enkelt är utdata från anpassningsfunktionen). </para>

</sect2>

<sect2 id="nonlinearfittingpluginexample">
<title
>Exempel</title>
<para
>Det följande är ett exempel på ett icke-linjärt anpassningsinsticksprogram som utför en anpassning till en exponentiell modell.</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_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
>Skapa insticksprogram för passfilter</title>
<para
>&kst; tillhandahåller deklarationsfiler för att förenkla implementeringen av insticksprogram med passfilter. Användningen av deklarationsfilerna beskrivs nedan. </para>
<sect2 id="creatingpassfilterpluginsheaderfiles">
<title
>Deklarationsfiler</title>
<para
>Deklarationsfilen för passfiltret finns i <filename
>kst/plugins/pass_filters</filename
> i källkodsarkivet för &kst;. Filen heter <filename
>filters.h</filename
>. För att använda filen, inkludera den i ditt insticksprograms källkod: <screen>
#include &lt;../filters.h&gt;
</screen
> (som konvention placerar vi källkoden för insticksprogrammet en katalognivå under platsen där deklarationsfilerna finns). </para>
</sect2>

<sect2 id="creatingpassfilterpluginsrequirements">
<title
>Nödvändiga funktioner</title>
<para
>Deklarationsfilen <filename
>filters.h</filename
> innehåller en enda funktion som beräknar Fouriertransformen för en tillhandahållen funktion, tillämpar det tillhandahållna filtret på Fouriertransformen och beräknar därefter den inversa Fouriertransformen för den filtrerade transformen. För att tillhandahålla filtret, måste följande funktion implementeras i ditt insticksprograms källkod: </para>
<para
><function
><returnvalue
>double</returnvalue
> filter_calculate( double <parameter
>dFreqValue</parameter
>, const double <parameter
>inScalars[]</parameter
> )</function
></para>
<para
>Funktionen ska beräkna filtrerad amplitud för frekvensen <literal
>dFreqValue</literal
>. <literal
>inScalars[]</literal
> innehåller de oförändrade indataskalärerna för insticksprogrammet, som anges i XML-filen. Troligen innehåller <literal
>inScalars[]</literal
> skärningsfrekvenser eller andra egenskaper för filtret. För att till exempel implementera ett Butterworth högpassfilter, skulle funktionen <function
>filter_calculate</function
> kunna implementeras som följer: </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
>Anropa filterfunktionen</title>
<para
>Så fort den nödvändiga <function
>filter_calculate</function
> har implementerats, kan filterfunktionen från deklarationsfilen anropas: </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
>Argumenten som skickas till den exporterade C-funktionen kan oftast skickas till <function
>kst_pass_filter</function
> utan ändringar. Det finns dock några bekränsningar för argumenten: </para>
<itemizedlist>
<listitem>
<para
><varname
>inArrays[0]</varname
> måste innehålla fältet med data att filtrera. </para>
</listitem>

<listitem>
<para
><varname
>inScalars</varname
> ska innehålla filterspecifika parametrar som ska användas av funktionen <function
>filter_calculate</function
>. </para>
</listitem>
</itemizedlist>
<para
>Efter funktionsanropet kommer <varname
>outArrays[0]</varname
> att innehålla det filtrerade datafältet, och <varname
>outArrayLens</varname
> kommer att vara lämpligt tilldelat. Funktionen <function
>kst_pass_filter</function
> använder inte <varname
>outScalars</varname
>. </para>
</sect2>

<sect2 id="creatingpassfilterpluginsexample">
<title
>Exempel</title>
<para
>Det följande är ett exempel på ett insticksprogram med ett passfilter som implementerar Butterworth högpassfiltrering. </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>