<appendix id="creatingplugins">
<title
>Creando plugins adicionales</title>
<para
>&kst; posee una interfaz simple y estándar que facilita la creación de plugins adicionales. Además de detallar los requerimientos básicos para desarrollar plugins, las secciones siguientes describen como hacer uso de archivos de cabecera ya escritos para crear ciertos tipos de plugins. </para>
<sect1 id="creatingbasicplugin">
<title
>Creando un plugin básico</title>
<para
>Un plugin de &kst; consiste de dos archivos—un archivo XML y una librería dinámica. </para>
<sect2 id="creatingbasicpluginxmlfile">
<title
>El archivo XML</title>
<para
>El archivo XML proporciona información sobre el plugin y describe sus entradas y salidas. Este es un ejemplo de un archivo XML usado como plugin de &kst;: </para>
<informalexample>
<screen
><?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Module SYSTEM "file:/Repository/Level2/Soft/ProC/moduledef.dtd">
<module>
<intro>
<modulename name="testplugin"/> <!-- El nombre del módulo -->
<author name="Rick Chern"/> <!-- El nombre del autor -->
<description text="Un plugin de pruebas para mí"/> <!-- Descripción del módulo -->
<version minor="1" major="0"/> <!-- Número de versión del módulo -->
<state devstate="release"/> <!-- Estado de desarrolo del módulo (opcional)-->
</intro>
<interface>
<!--inputs here-->
<input>
<table type="float" name="Input Vector 1" descr="The first input vector" />
</input>
<input>
<float name="Input Scalar 1" descr="The first input scalar" />
</input>
<!--outputs here-->
<output>
<table type="float" name="Output Vector 1" descr="The first output vector" />
</output>
<output>
<float name="Output Scalar 1" descr="The first output scalar" />
</output>
</interface>
</module>
</screen>
</informalexample>
<para
>En general, puede usar el ejemplo de arriba como plantilla y modificar sus secciones para ajustarse a sus necesidades. Como puede verse en el ejemplo, el archivo XML consiste de un nodo <literal
>module</literal
>. El nodo <literal
>module</literal
> tiene un nodo <literal
>intro</literal
> y un nodo <literal
>interface</literal
>. Debería modificar el nodo <literal
>intro</literal
> usando como guía los comentarios dados en el archivo XML. Es importante que en <literal
>modulename</literal
>, el atributo <literal
>name</literal
> debe corresponderse al nombre de la librería dinámica que va a usar. </para>
<para
>El nodo <literal
>interface</literal
> describe las entradas y salidas actuales del plugin. Cada entrada se describe por un nodo <literal
>input</literal
>, y cada salida se describe con un nodo <literal
>output</literal
>. Cada input u output deberían tener como nodos hijos o bien <literal
>table</literal
> o <literal
>float</literal
>. El atributo <literal
>type</literal
> de <literal
>table</literal
> debe ponerse como <literal
>"float"</literal
>. Notar que el orden de las inputs y de las outputs es importante—tal orden se usa para determinar los valores del index para cada conjunto de datos de entrada y salida de la librería dinámica, y es el mismo orden que el utilizado para mostrar los campos de entrada y salida de la interfaz de plugin de &kst;. </para>
<para
>Una vez que haya completado el archivo XML, guardelo como <filename
> [modulename].xml</filename
>, donde <filename
>[modulename]</filename
> es el valor dado al atributo <literal
>name</literal
> del nodo <literal
>modulename</literal
>. </para>
</sect2>
<sect2 id="creatingbasicpluginobjectfile">
<title
>La librería dinámica</title>
<para
>La librería dinámica contiene la funcionalidad actual del plugin. En otras palabras, determina como derivar las salidas de unas entradas dadas. A continuación se muestran los requerimientos para una librería dinámica. </para>
<itemizedlist>
<listitem>
<para
>El objeto debe exportar el siguiente símbolo en C para el enlace: <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
>donde <replaceable
>symbol</replaceable
> debe corresponder al valor del atributo <literal
>name</literal
> del nodo <literal
>modulename</literal
> en el archivo XML. Esta es la única función que será llamada por &kst; (aunque usted pueda tener otras funciones en su plugin). A continuación se describen los argumentos de esta función: </para>
<variablelist>
<varlistentry>
<term
><varname
>const double *const inArrays[]</varname
></term>
<listitem>
<para
>El vector de vectores de entrada. Cada vector de entrada (aquí) se corresponderá con un vector de entrada (en &kst;). Los vectores deben estar en el mismo orden que los vectores definidos en el archivo XML, de tal forma que <literal
>inArrays[0]</literal
> sea el vector que represente al primer vector de entrada, <literal
>inArrays[1]</literal
> sea el vector que represente al segundo vector de entrada, y así sucesivamente. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><varname
>const int inArraysLens[]</varname
></term>
<listitem>
<para
>El vector conteniendo las longitudes de cada vector de entrada. Las longitudes se guardan en el mismo orden que los vectores en <literal
>inArrays[]</literal
> (es decir, <literal
>inArrayLens[0]</literal
> es la longitud de <literal
>inArrays[0]</literal
>). </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><varname
>const double inScalars[]</varname
></term>
<listitem>
<para
>El vector de escalares de entrada. Los escalares se guardan en el mismo orden que están definidos en el archivo XML. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><varname
>double *outArrays[]</varname
></term>
<listitem>
<para
>El vector de vectores de salida. Cada vector de salida (aquí) corresponde a un vector de salida en kst, y los vectores deben estar en el mismo orden que los vectores de salida listados en el archivo XML. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><varname
>int outArrayLens[]</varname
></term>
<listitem>
<para
>El vector que debería contener las longitudes de los vectores de salida. Tales longitudes deben almacenarse en el mismo orden que los vectores en <literal
>outArrays[]</literal
>. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><varname
>double outScalars[]</varname
></term>
<listitem>
<para
>El vector de escalares de salida. Los escalares deben estar en el mismo orden que su listado en el archivo XML. </para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
<listitem>
<para
>La función debe retornar <literal
>0</literal
> si se ha ejecutado con éxito, y <literal
>-1</literal
> si no. </para>
</listitem>
<listitem>
<para
>El código de la librería debe ser capaz de trabajar con entradas inesperadas, tales como vectores vacíos (en la mayoría de los casos, es suficiente con devolver un valor de <literal
>-1</literal
> cuando se presentan tales casos). </para>
</listitem>
<listitem>
<para
>El número y el tipo de las salidas debe ser exactamente como el especificado en en archivo XML. </para>
</listitem>
<listitem>
<para
>Probablemente necesitará redimensionar los vectores en <varname
>outArrays[]</varname
>. Para ello, use la función <function
>realloc()</function
>. Por ejemplo, </para>
<informalexample>
<screen
>outArrays[0]=(double*)realloc(outArrays[0], 5*sizeof(double));
</screen>
</informalexample>
<para
>va a reservar un espacio de 5 "doubles" para <varname
>outArrays[0]</varname
>. Use solo <function
>realloc()</function
> para reservar memoria. </para>
</listitem>
<listitem>
<para
>Los argumentos de entrada deben permanecer constantes. No haga un "cast" a tipos no constantes. </para>
</listitem>
</itemizedlist>
<para
>A continuación se muestra un ejemplo de un archivo con el código de una librería dinámica que es un plugin simple: </para>
<informalexample>
<screen
>#include <stdlib.h>
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[])
//Acepta 1 vector y 1 escalar. Multiplica todos los elementos del vector por el
//escalar, y da como salida el vector resultante. También da como salida el escalar original.
{
// Asigna las salidas (outputs)
outArrayLens[0]=inArrayLens[0];
//Redimensiona los vectores de salida
outArrays[0]=(double*)realloc(outArrays[0], inArrayLens[0]*sizeof(double));
//multiplica cada elemento del vector de entrada
//con el escalar
for (int i=0; i<inArrayLens[0]; i++)
{
outArrays[0][i]=inArrays[0][i] * is[0];
}
//ahora, asignar el escalar de salida
outScalars[0]=is[0];
return 0;
}
</screen>
</informalexample>
</sect2>
<sect2 id="compilingplugin">
<title
>Compilando el plugin</title>
<para
>Si usa &gcc; para compilar su plugin, simplemente compile para obtener el archivo objeto: <screen
><userinput
><command
>cc -Wall -c -o myplugin.o myplugin.c -fPIC -DPIC</command
></userinput
></screen>
</para>
<para
>y entonces, cree la librería dinámica: <screen
><userinput
><command
>ld -o myplugin.so -shared myplugin.o</command
></userinput
></screen>
</para>
<para
>Los archivos resultantes <filename
>*.so</filename
> y <filename
>*.xml</filename
> deben ponerse en el mismo directorio. Cuando use el gestor de plugins de &kst; para cargar el archivo XML, buscará automáticamente por la librería dinámica en el mismo directorio. </para>
</sect2>
</sect1>
<sect1 id="creatinglinearfittingplugins">
<title
>Creando plugins para ajustes lineales</title>
<para
>Para crear un plugin para un ajuste lineal, usted podría implementar sus propios algoritmos de ajuste y retornar con los vectores apropiados. Sin embargo, &kst; ya viene con archivos de cabecera que le facilitan la implementación de plugins para ajuste por mínimos cuadrados con tal de que codifique unas pocas funciones. Esta sección le muestra como sacar partido a tales archivos. </para>
<sect2 id="headerslinearfittingplugins">
<title
>Archivos de cabecera</title>
<para
>Se suministran dos archivos de cabecera para hacer ajustes lineales, <filename
>linear.h</filename
> (para ajustes sin ponderación) y <filename
>linear_weighted.h</filename
> (para ajustes ponderados). Ambos se encuentran en las fuentes de &kst; bajo el directorio <filename
>kst/plugins/fits/</filename
>. Para usar tales archivos, incluya solo uno de ellos en el código fuente de su plugin:<screen>
#include <../linear.h>
</screen
> o <screen>
#include <../linear_weighted.h>
</screen
> (por convención, vamos a poner el código fuente del plugin en un directorio más abajo que el que contiene los archivos de cabecera). </para>
</sect2>
<sect2 id="reqfunctionsfittingplugins">
<title
>Implementando las funciones requeridas</title>
<para
>Dar un modelo lineal general: </para>
<para>
<inlinemediaobject>
<imageobject>
<imagedata fileref="Formula-kst-generallinearmodel.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</para>
<para
>donde <literal
>y</literal
> es un vector de <literal
>n</literal
> observaciones, <literal
>X</literal
> es una matriz <literal
>n</literal
> por <literal
>p</literal
> de variables de predicción, y <literal
>c</literal
> es el vector de <literal
>p</literal
> parámetros de mejor ajuste que van a estimarse, los archivos de cabecera dan funciones para la estimación de <literal
>c</literal
> para un <literal
>y</literal
> y un <literal
>X</literal
> dados. Para dar <literal
>X</literal
>, esta función debe implementarse en el código del plugin: <literallayout
><function
><returnvalue
>double</returnvalue
> calculate_matrix_entry( double <parameter
>dX</parameter
>, int <parameter
>iPos</parameter
> )</function
></literallayout>
</para>
<para
>Esta función debe retornar el valor de la entrada en la columna <literal
>iPos</literal
> de la matriz de variables de predicción, usando el valor de <literal
>x</literal
> <literal
>dX</literal
>. Esta función la llamará linear.h o linear_weighted.h. La implementación de esta función depende del modelo que desee usar para el ajuste, y es única para cada plugin de ajuste lineal. Por ejemplo, para ajustar a un modelo polinomial, <function
>calculate_matrix_entry</function
> debe implementarse como sigue: <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
>Llamando las funciones de ajuste</title>
<para
>Una vez que se han incluido los archivos de cabecera y que se ha implementado la función <function
>calculate_matrix_entry</function
>, llamar la función de ajuste apropiada incluida desde el archivo de cabecera: <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
>Cada función retornará <literal
>0</literal
> en éxito, y <literal
>-1</literal
> en error, así que es una buena idea que el valor de retorno de la función C exportada sea igual al valor de retorno de la función de ajuste. Para mantener la simplicidad, el código para el plugin puede simplemente pasar los argumentos dados a la función C exportada a la función de ajuste. Notar, sin embargo, que la variable inArrays debe estructurarse de esta forma: </para>
<itemizedlist>
<listitem>
<para
><varname
>inArrays[0]</varname
> debe contener un vector de coordenadas x de puntos de datos </para>
</listitem>
<listitem>
<para
><varname
>inArrays[1]</varname
> debe contener un vector de coordenadas y de puntos de datos </para>
</listitem>
<listitem>
<para
><varname
>inArrays[2]</varname
> solo existe si se llama la función <function
>kstfit_linear_weighted</function
>, y debe contener un vector con los valores de los pesos usados para el ajuste. </para>
</listitem>
</itemizedlist>
<para
>La manera más sencilla de asegurar que inArrays está estructurado correctamente es especificando el orden correcto de vectores de entrada (input) en el archivo XML para el plugin. </para>
<para
><varname
>iNumParams</varname
> es el numero de parámetros en el modelo usado, el cual debe ser igual al número de columnas en la matriz <literal
>X</literal
> de variables de predicción. <varname
>iNumParams</varname
> debe estar correcto antes que la función de ajuste se llame. </para>
<para
>Después de llamar <function
>kstfit_linear_unweighted</function
> o <function
>kstfit_linear_weighted</function
>, las variables <varname
>outArrays</varname
> y <varname
>outScalars</varname
> serán asignadas como sigue: </para>
<itemizedlist>
<listitem>
<para
><varname
>outArrays[0]</varname
> contendrá el vector con los valores y ajustados. </para>
</listitem>
<listitem>
<para
><varname
>outArrays[1]</varname
> contendrá el vector con los residuos. </para>
</listitem>
<listitem>
<para
><varname
>outArrays[2]</varname
> contendrá el vector con los valores de los parámetros calculados de mejor ajuste. </para>
</listitem>
<listitem>
<para
><varname
>outArrays[3]</varname
> contendrá la matriz de covariancia, retornada fila a fila en un vector. </para>
</listitem>
<listitem>
<para
><varname
>outScalars[0]</varname
> contendrá chi^2/nu, donde chi^2 es la suma ponderada de los cuadrados de los residuos, y nu son los grados de libertad. </para>
</listitem>
</itemizedlist>
<para
><varname
>outArrayLens</varname
> se asignará correctamente para indicar la longitud de cada vector de salida. </para>
<para
>Asegúrese de que cada salida especificada en el archivo XML se corresponde a aquellas retornadas por la función C exportada (que en la mayoría de los casos será la salida retornada por la función de ajuste). </para>
</sect2>
<sect2 id="examplelinearfittingplugins">
<title
>Ejemplo</title>
<para
>A continuación se muestra un ejemplo de código de un plugin para un ajuste lineal. </para>
<informalexample>
<screen
>/*
* Plugin de ajuste polinomial para 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 > 0 ) {
iRetVal = kstfit_linear_unweighted( inArrays, inArrayLens,
outArrays, outArrayLens,
outScalars, iNumParams );
}
return iRetVal;
}
</screen>
</informalexample>
</sect2>
</sect1>
<sect1 id="creatingnonlinearfitplugin">
<title
>Creando plugins para ajustes no lineales</title>
<para
>&kst; proporciona archivos de cabecera diseñados para simplificar la creación de plugins para ajustes no lineales por mínimos cuadrados. La sección siguiente detalla como usar tales archivos de cabecera. </para>
<sect2 id="headersnonlinearfittingplugins">
<title
>Archivos de cabecera y definiciones</title>
<para
>Los archivos de cabecera para ajustes no lineales están situados en el directorio <filename
>kst/plugins/fits_nonlinear</filename
> de las fuentes de &kst;. Los archivos se llaman <filename
>non_linear.h</filename
> y <filename
>non_linear_weighted.h</filename
> para ajustes normales y ponderados, respectivamente. Para usar estos archivos, incluya solo uno de ellos en el código de su plugin:<screen>
#include <../non_linear.h>
</screen
> o <screen>
#include <../non_linear_weighted.h>
</screen
> (por convención, vamos a poner el código fuente del plugin en un directorio más abajo que el que contiene los archivos de cabecera). </para>
<para
>Como un ajuste no lineal es un proceso iterativo, debe definir el número máximo de iteraciones que deben hacerse. El algoritmo de ajuste no lineal se detendrá cuando al menos una de las condiciones siguientes sea verdad: </para>
<itemizedlist>
<listitem>
<para
>Se ha alcanzado el máximo número de iteraciones. </para>
</listitem>
<listitem>
<para
>Se ha alcanzado una precisión de 10<superscript
>-4</superscript
>. </para>
</listitem>
</itemizedlist>
<para
>Además, necesita definir el número de parámetros en el modelo, pues no se pasa de forma explícita a la función de ajuste. Para definir estos dos valores, incluya lo siguiente en la parte superior de su código: </para>
<screen
>#define NUM_PARAMS [num1]
#define MAX_NUM_ITERATIONS [num2]
</screen>
<para
>reemplazando <literal
>[num1]</literal
> con el número de parámetros en el modelo, y <literal
>[num2]</literal
> con el número máximo de iteraciones a realizar. </para>
</sect2>
<sect2 id="reqfunctionsnonlinearfittingplugins">
<title
>Implementando las funciones requeridas</title>
<para
>Para usar los archivos de cabecera para ajustes no lineales, debe proveer una función a usar como modelo, las derivadas parciales de la función con respecto a cada parámetro, y las estimaciones iniciales de los parámetros de mejor ajuste. Para hacer esto, deben implementarse 3 funciones. Estas funciones se describen más abajo: </para>
<variablelist>
<varlistentry>
<term
><function
><returnvalue
>double</returnvalue
> function_calculate( double <parameter
>dX</parameter
>, double* <parameter
>pdParameters</parameter
> )</function
></term>
<listitem>
<para
>Esta función calcula el valor y del modelo de ajuste para un valor x dado <literal
>dX</literal
>, usando el vector de parametros <varname
>pdParameters</varname
> pasado a la función. El orden de los parametros en <varname
>pdParameters</varname
> es arbitrario, pero debe ser consistente con el orden en las otras dos funciones implementadas. Por ejemplo, para un modelo exponencial, se puede implementar <function
>function_calculate</function
> como sigue: </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
>Esta función calcula las derivadas parciales de la función modelo para un valor de x dado <literal
>dX</literal
>. Las derivadas parciales deben retornarse en <varname
>pdDerivatives</varname
>. El orden de lasderivadas parciales en el vector <varname
>pdDerivatives</varname
> debe corresponderse al orden de los parámetros en <varname
>pdParameters</varname
> (esto es, si <varname
>pdParameters[0]</varname
> contiene el parámetro lambda para un modelo exponencial, <varname
>pdDerivatives[0]</varname
> debe contener un modelo de la derivada del modelo con respecto 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
>Esta función da una estimación inicial de los parámetros de mejor ajuste para la función de ajuste. El vector de valores x e y de puntos de datos se pasan en <varname
>pdX</varname
> y <varname
>pdY</varname
> respectivamente, y el número de puntos de datos es suministrado por <varname
>iLength</varname
>. Puede usar o no cualquiera de estos parámetros para calcular una estimación inicial. La función debe poner las estimación inicial calculada en <varname
>pdParameterEstimates</varname
>, con el orden de las estimaciones correspondiéndose al orden de los parametros en <varname
>pdParameters</varname
> de <function
>function_calculate</function
> y <function
>function_derivative</function
>. Tenga presente que la estimación inicial es importante en la determinación de si la función de ajuste converge o no a una solución. </para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="callingnonlinearfittingplugins">
<title
>Llamando las funciones de ajuste</title>
<para
>Una vez que todas las funciones requeridas están implementadas, se puede llamar a la función de ajuste del archivo de cabecera incluido: <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
> dependiendo en si se implementa un ajuste normal o ponderado. </para>
<para
>Cada función retornará <literal
>0</literal
> en éxito, y <literal
>-1</literal
> en error, así que es una buena idea que el valor de retorno de la función C exportada sea igual al valor de retorno de la función de ajuste. Para mantener la simplicidad, el código para el plugin puede simplemente pasar los argumentos dados a la función C exportada a la función de ajuste. Notar, sin embargo, que la variable inArrays debe estructurarse de esta forma: </para>
<itemizedlist>
<listitem>
<para
><varname
>inArrays[0]</varname
> debe contener un vector de coordenadas x de puntos de datos </para>
</listitem>
<listitem>
<para
><varname
>inArrays[1]</varname
> debe contener un vector de coordenadas y de puntos de datos </para>
</listitem>
<listitem>
<para
><varname
>inArrays[2]</varname
> solo existe si se llama la función <function
>kstfit_linear_weighted</function
>, y debe contener un vector con los valores de los pesos usados para el ajuste. </para>
</listitem>
</itemizedlist>
<para
>La manera más sencilla de asegurar que inArrays está estructurado correctamente es especificando el orden correcto de vectores de entrada (input) en el archivo XML para el plugin. </para>
<para
>Después de llamar <function
>kstfit_linear_unweighted</function
> o <function
>kstfit_linear_weighted</function
>, las variables <varname
>outArrays</varname
> y <varname
>outScalars</varname
> serán asignadas como sigue: </para>
<itemizedlist>
<listitem>
<para
><varname
>outArrays[0]</varname
> contendrá el vector con los valores y ajustados. </para>
</listitem>
<listitem>
<para
><varname
>outArrays[1]</varname
> contendrá el vector con los residuos. </para>
</listitem>
<listitem>
<para
><varname
>outArrays[2]</varname
> contendrá el vector con los valores de los parámetros calculados de mejor ajuste. </para>
</listitem>
<listitem>
<para
><varname
>outArrays[3]</varname
> contendrá la matriz de covariancia, retornada fila a fila en un vector. </para>
</listitem>
<listitem>
<para
><varname
>outScalars[0]</varname
> contendrá chi^2/nu, donde chi^2 es la suma ponderada de los cuadrados de los residuos, y nu son los grados de libertad. </para>
</listitem>
</itemizedlist>
<para
><varname
>outArrayLens</varname
> se asignará correctamente para indicar la longitud de cada vector de salida. </para>
<para
>Asegúrese de que cada salida especificada en el archivo XML se corresponde a aquellas retornadas por la función C exportada (que en la mayoría de los casos será la salida retornada por la función de ajuste). </para>
</sect2>
<sect2 id="nonlinearfittingpluginexample">
<title
>Ejemplo</title>
<para
>Lo que sigue es un ejemplo de un plugin para ajustes no lineales que hace un ajuste según un modelo exponencial.</para>
<informalexample>
<screen
>/*
* Plugin de ajuste exponencial para 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
>Creando plugins de filtro de pasos</title>
<para
>&kst; proporciona archivos de cabecera diseñados para simplificar la creación de plugins para filtros de paso. A continuación se detalla como usar tales archivos de cabecera. </para>
<sect2 id="creatingpassfilterpluginsheaderfiles">
<title
>Archivos de cabecera</title>
<para
>El archivo de cabecera para filtros de paso está situado en el directorio <filename
>kst/plugins/pass_filter</filename
> de las fuentes de &kst;. El archivo se llama <filename
>filters.h</filename
>. Para usar este archivo, incluyálo en el código de su plugin:<screen>
#include <../filters.h>
</screen
> (por convención, vamos a poner el código fuente del plugin en un directorio más abajo del que contiene los archivos de cabecera). </para>
</sect2>
<sect2 id="creatingpassfilterpluginsrequirements">
<title
>Funciones requeridas</title>
<para
>El archivo de cabecera <filename
>filters.h</filename
> contiene una función simple que calcula la transformada de Fourier de una función dada, aplica el filtro suministrado a la transformada de Fourier, y luego calcula la transformada inversa de Fourier en la transformada de Fourier ya filtrada. Para suministrar el filtro, se necesita implementar la función siguiente en el código del plugin: </para>
<para
><function
><returnvalue
>double</returnvalue
> filter_calculate( double <parameter
>dFreqValue</parameter
>, const double <parameter
>inScalars[]</parameter
> )</function
></para>
<para
>Esta función debe calcular la amplitud filtrada para la frecuencia <literal
>dFreqValue</literal
>. <literal
>inScalars[]</literal
> contendrá los escalares inalterados para el plugin, específicados en el archivo XML. Lo más probable es que <literal
>inScalars[]</literal
> contenga las frecuencias de corte u otras propiedades del filtro. Por ejemplo, para implementar un filtro de paso alto Butterworth, se puede implementar <function
>filter_calculate</function
> como sigue: </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
>Llamando a la función de filtrado</title>
<para
>Una vez que se ha implementado la función <function
>filter_calculate</function
>, se puede llamar la función de filtrado del archivo de cabecera: </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
>Los argumentos suministrados a la función C exportada pueden pasarse a <function
>kst_pass_filter</function
> sin modificarse. Sin embargo, hay unas cuantas restricciones en los argumentos: </para>
<itemizedlist>
<listitem>
<para
><varname
>inArrays[0]</varname
> debe contener el vector de datos a filtrar. </para>
</listitem>
<listitem>
<para
><varname
>inScalars</varname
> debe contener los parámetros específicos del filtro que se usarán por la función <function
>filter_calculate</function
>. </para>
</listitem>
</itemizedlist>
<para
>Despues de la llamada de la función, <varname
>outArrays[0]</varname
> contendrá un vector de datos filtrados, y se asignará <varname
>outArrayLens</varname
> de manera consecuente. La función <function
>kst_pass_filter</function
> no usa <varname
>outScalars</varname
>. </para>
</sect2>
<sect2 id="creatingpassfilterpluginsexample">
<title
>Ejemplo</title>
<para
>A continuación se muestra un ejemplo de un filtro de paso que implementa el filtro de paso alto de Butterworth. </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 <stdlib.h>
#include <math.h>
#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 > 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>
distrib
>
Mandriva
>
10.2
>
i586
>
media
>
contrib
>
by-pkgid
>
eb2ca3fa8cac6766aebe2c4233348281
>
files
>
239
