<appendix id="creatingplugins">
<title
>Crear extensiones adicionales</title>
<para
>&kst; posee una interfaz simple y estándar que facilita la creación de extensiones adicionales. Además de detallar los requerimientos básicos para desarrollar extensiones, las secciones siguientes describen como hacer uso de archivos de cabecera ya escritos para crear ciertos tipos de extensión. </para>
<sect1 id="creatingbasicplugin">
<title
>Crear una extensión básica</title>
<para
>Una extensión de &kst; está formado por dos archivos: un archivo XML y un archivo de biblioteca dinámica. </para>
<sect2 id="creatingbasicpluginxmlfile">
<title
>El archivo XML</title>
<para
>El archivo XML proporciona información sobre la extensión y describe sus entradas y salidas. Éste es un ejemplo de un archivo XML usado como extensión 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="extensiondeprueba"/> <!-- El nombre del módulo -->
<author name="Rick Chern"/> <!-- El nombre del autor -->
<description text="Una extensión 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 desarrollo del módulo (opcional)-->
</intro>
<interface>
<!--La entradas aquí-->
<input>
<table type="float" name="Vector de entrada 1" descr="El primer vector de entrada" />
</input>
<input>
<float name="Escalar de entrada 1" descr="El primer escalar de entrada" />
</input>
<!--Las salidas aquí->
<output>
<table type="float" name="Vector de salida1" descr="El primer vector de salida" />
</output>
<output>
<float name="Escalar de salida 1" descr="El primer vector de salida" />
</output>
</interface>
</module>
</screen>
</informalexample>
<para
>En general, puede usar el ejemplo anterior como plantilla y modificar sus secciones para ajustarse a sus necesidades. Como puede verse en el ejemplo, el archivo XML está formado por 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
> se corresponda con el nombre de la biblioteca dinámica que va a usar. </para>
<para
>El nodo <literal
>interface</literal
> describe las entradas y salidas actuales de la extensión. 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
>. Tenga en cuenta que el orden de las entradas y de las salidas es importante: tal orden se usa para determinar los valores del índice 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 la extensión de &kst;. </para>
<para
>Una vez que haya completado el archivo XML, guardelo como <filename
> [modulename].xml</filename
>, donde <filename
>[nombremodulo]</filename
> es el valor dado al atributo <literal
>name</literal
> del nodo <literal
>nombremodulo</literal
>. </para>
</sect2>
<sect2 id="creatingbasicpluginobjectfile">
<title
>La biblioteca dinámica</title>
<para
>La biblioteca dinámica contiene la funcionalidad actual de la extensión. En otras palabras, determina cómo derivar las salidas de unas entradas dadas. A continuación se muestran los requerimientos para una biblioteca dinámica: </para>
<itemizedlist>
<listitem>
<para
>El objeto debe exportar el siguiente enlace simbólico en C: <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. Ésta es la única función que será llamada por &kst; (aunque usted pueda tener otras funciones en su extensión). 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 se corresponderá con un vector de entrada. 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 corresponde a un vector de salida, 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 devolver <literal
>0</literal
> si se ha ejecutado con éxito, y <literal
>-1</literal
> si no. </para>
</listitem>
<listitem>
<para
>El código de la biblioteca 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 biblioteca dinámica que es una extensión 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
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
>Compilar la extensión</title>
<para
>Si usa &gcc; para compilar su extensión, simplemente compile para obtener el archivo objeto: <screen
><userinput
><command
>cc -Wall -c -o miextension.o miextension.c -fPIC -DPIC</command
></userinput
></screen>
</para>
<para
>y entonces, cree la biblioteca dinámica: <screen
><userinput
><command
>ld -o miextension.so -shared miextension.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 administrador de extensiones de &kst; para cargar el archivo XML, buscará automáticamente la librería dinámica en el mismo directorio. </para>
</sect2>
</sect1>
<sect1 id="creatinglinearfittingplugins">
<title
>Crear extensiones para ajustes lineales</title>
<para
>Para crear una extensión para un ajuste lineal, podría implementar sus propios algoritmos de ajuste y devolver los vectores apropiados. Sin embargo, &kst; ya viene con archivos de cabecera que le facilitan la implementación de extensiones 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; dentro del directorio <filename
>kst/plugins/fits/</filename
>. Para usar dichos archivos, incluya solo uno de ellos en el código fuente de su extensión:<screen>
#include <../linear.h>
</screen
> o <screen>
#include <../linear_weighted.h>
</screen
> (por convención, vamos a situar el código fuente de la extensión en un directorio más abajo que el que contiene los archivos de cabecera). </para>
</sect2>
<sect2 id="reqfunctionsfittingplugins">
<title
>Implementar 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 de la extensión: <literallayout
><function
><returnvalue
>double</returnvalue
> calculate_matrix_entry( double <parameter
>dX</parameter
>, int <parameter
>iPos</parameter
> )</function
></literallayout>
</para>
<para
>Esta función debe devolver 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 extensión 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 a las funciones de ajuste</title>
<para
>Una vez que se han incluído los archivos de cabecera y que se ha implementado la función <function
>calculate_matrix_entry</function
>, se deberá llamar a la función de ajuste apropiada incluída 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 devolverá <literal
>0</literal
> si hay éxito, y <literal
>-1</literal
> en error, así que es una buena idea que el valor que devuelve la función C exportada sea igual al valor de devuleto por la función de ajuste. Para mantener la simplicidad, el código para la extensión puede simplemente pasar los argumentos dados a la función C exportada a la función de ajuste. Observe, 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 en el archivo XML para la extensión. </para>
<para
><varname
>iNumParams</varname
> es el número 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 de llamar a la función de ajuste. </para>
<para
>Después de llamar a <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 devuelta 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 una extensión para un ajuste lineal. </para>
<informalexample>
<screen
>/*
* Extensión de ajuste polinomial para KST.
* Derechos de autor. 2004. La universidad de British Columbia
* Liberado bajo los términos de la licencia 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
>Crear extensiones para ajustes no lineales</title>
<para
>&kst; proporciona archivos de cabecera diseñados para simplificar la creación de extensiones para ajustes no lineales por mínimos cuadrados. La sección siguiente detalla cómo 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 extensión:<screen>
#include <../non_linear.h>
</screen
> o <screen>
#include <../non_linear_weighted.h>
</screen
> (por convención, vamos a poner el código fuente de la extensión 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
>Implementar 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 a continuación. </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 parámetros <varname
>pdParameters</varname
> pasado a la función. El orden de los parámetros 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 devolverse en <varname
>pdDerivatives</varname
>. El orden de las derivadas 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 a 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 incluído: <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 de si se implementa un ajuste normal o ponderado. </para>
<para
>Cada función devolverá <literal
>0</literal
> si hay éxito, y <literal
>-1</literal
> en caso de error, así que es una buena idea que el valor de devolución 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 la extensión puede simplemente pasar los argumentos dados a la función C exportada a la función de ajuste. Observe, 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 en el archivo XML para la extensión. </para>
<para
>Después de llamar a <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 devuelta por la función de ajuste). </para>
</sect2>
<sect2 id="nonlinearfittingpluginexample">
<title
>Ejemplo</title>
<para
>Lo que sigue es un ejemplo de una extensión para ajustes no lineales que hace un ajuste según un modelo exponencial.</para>
<informalexample>
<screen
>/*
* Extensión de ajuste exponencial para KST.
* Derecheos de autor. 2004. La universidad de British Columbia
* Liberado bajo los términos de la 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
>Crear extensiones de filtro de pasos</title>
<para
>&kst; proporciona archivos de cabecera diseñados para simplificar la creación de extensiones 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, inclúyalo en el código de su extensión:<screen>
#include <../filters.h>
</screen
> (por convención, vamos a poner el código fuente de la extensión 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 de la extensión: </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 a 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
>/*
* Extensión de filtro de paso bajo de Butterworth para KST.
* Derechos de autor. 2004. La universidad de British Columbia
* Liberado bajo los términos de la licencia 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>
<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-omittag:nil
sgml-shorttag:nil
sgml-namecase-general:nil
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:0
sgml-indent-data:true
sgml-parent-document:("index.docbook" "book" "appendix")
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
