potential.h

Vá para a documentação deste arquivo.
00001 /*
00002 * Copyright 2007, 2008 Ernesto Coutinho Colla
00003 *
00004 * "BN Parallel Package" é um nome que identifica o conjunto de programas 
00005 * que forma uma biblioteca de rotinas que foram desenvolvidas como parte da 
00006 * dissertação de mestrado do autor em Ciências da Computação.
00007 *
00008 * O conjunto de programas foi integralmente desenvolvido pelo autor e está
00009 * disponível sob a licença GPL (GNU General Public License). O entendimento
00010 * integral dos termos da licença GPL é condição necessária para a utilização
00011 * parcial ou integral de qualquer parte deste conjunto de programas.
00012 *
00013 * This file is part of BN Parallel Package.
00014 * 
00015 * BN Parallel Package is free software: you can redistribute it and/or modify
00016 * it under the terms of the GNU General Public License as published by
00017 * the Free Software Foundation, either version 3 of the License.
00018 *
00019 * BN Parallel Package is distributed in the hope that it will be useful,
00020 * but WITHOUT ANY WARRANTY; without even the implied warranty of
00021 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00022 * GNU General Public License for more details.
00023 *
00024 * You should have received a copy of the GNU General Public License
00025 * along with BN Parallel Package. If not, see <http://www.gnu.org/licenses/>.
00026 */
00027 
00028 
00029 /*!
00030  * @file        potential.h
00031  * @author      Ernesto Colla (ernesto@gmail.com)
00032  * @version     0.0.1
00033  * @date        Abril/2007
00034  * @brief       Implementação da estrutura de dados e operações com variáveis e potenciais.
00035  *
00036  * Implementação de uma biblioteca genérica que define as estruturas de uma variável de 
00037  * um potencial e as principais operações com potenciais.
00038  */
00039 
00040 #ifndef DBGOUT
00041 #define DBGOUT stdout
00042 #endif
00043 
00044 #ifndef POTENTIAL_H
00045 #define POTENTIAL_H
00046 
00047 /* Includes */
00048 #include <errno.h>
00049 #include <stdio.h>
00050 #include <stdlib.h>
00051 
00052 /* Defines  e constantes */
00053 
00054 // Tipos de Variáveis
00055 #define VARIABLE_TYPE_DISCRETE 0        //!< Tipo de variável discreta. Esta biblioteca suporta apenas variáveis DISCRETAS.
00056 #define VARIABLE_TYPE_CONTINUOUS 1      //!< Tipo de variável continua. Esta biblioteca suporta apenas variáveis DISCRETAS.
00057 
00058 // Tamanhos máximos
00059 #define VARIABLE_NAME_LENGTH 50                 //!< Tamanho máximo do nome da variável.
00060 #define VARIABLE_STATE_NAME_LENGTH 50   //!< Tamanho máximo do nome que identifica o estado de uma variável.
00061 
00062 /* Definição dos tipos de dados */
00063 
00064 /*! Estrutura de dados de uma Variável */
00065 typedef struct struct_Variable {
00066         int id;                 //!< \e id que identifica a variável. Atenção: Não há verificação da unicidade do \e id da variável.
00067         int type;               //!< Tipo da variável. Tipos válidos: VARIABLE_TYPE_DISCRETE e VARIABLE_TYPE_CONTINUOUS. Esta biblioteca suporta apenas variáveis DISCRETAS.
00068         char* name;             //!< Nome da variável.
00069         int nstates;    //!< Número de estados possíveis para a variável.
00070         char** states;  //!< Nome dos estados possíveis para a variável.
00071 } Variable;
00072 
00073 /*! Estrutura de dados de um Potencial */
00074 typedef struct struct_Potential {
00075         int id;                                 //!< \e id que identifica o potencial. Atenção: Não há verificação da unicidade do \e id do potencial
00076         int nvars;                              //!< Número de variáveis totais do potencial.
00077         Variable** vars;                //!< Lista de todas as variáveis do potencial.
00078         int nvalues;                    //!< Número total de combinações de estados possíveis das variáveis.
00079         double* values;                 //!< Valores da tabela de potencial.
00080 } Potential;
00081 
00082 /* Funções */
00083 
00084 /*!
00085  * @brief Constrói uma variável.
00086  *
00087  * O \e id deve ser único e um número maior ou igual a zero. Não há verificação da unicidade do \e id da variável, cabendo esta responsabilidade.
00088  * @param[in] id \e id da variável a ser criada. O \e id deve ser único e um número maior ou igual a zero, mas não há checagem da unicidade do \e id;
00089  * @param[in] name Nome a ser atribuído à variável.
00090  * @param[in] type Tipo da variável a ser criada. Tipos válidos: VARIABLE_TYPE_DISCRETE e VARIABLE_TYPE_CONTINUOUS. Esta biblioteca suporta apenas variáveis DISCRETAS.
00091  * @param[in] nstates Número total de estados possíveis para a variável.
00092  * @param[in] states Nomes dos estados possíveis para a variável.
00093  * @return Variável cronstruída a partir dos dados de entrada.
00094  */
00095 
00096 Variable* buildVariable(int id, char* name, int type, int nstates, char** states);
00097 
00098 /*!
00099  * @brief Dump do conteúdo da variável.
00100  * @param[in] var Variável da qual se deseja fazer o dump.
00101  */
00102 
00103 void dumpVariable(Variable* var);
00104 
00105 /*!
00106  * @brief Destrói uma variável e desaloca os recursos que estavam alocados para a mesma.
00107  * @param[out] refVariable Referência para a variável a ser destruída.
00108  */
00109 
00110 void destroyVariable(Variable** refVariable);
00111 
00112 /*!
00113  * @brief Constrói um potencial.
00114  *
00115  * O \e id deve ser único e um número maior ou igual a zero. Não há verificação da unicidade do potencial, cabendo esta responsabilidade
00116  * ao desenvolvedor. É importante observar a perfeita correspondência entre os valores e a ordem com que as variáveis estão dispostas
00117  * o array \e vars.
00118  * @param[in] id \e id do potencial. O \e id deve ser único e um número maior ou igual a zero. Não há verificação da unicidade do potencial.
00119  * @param[in] nvars Número de variáveis do potencial.
00120  * @param[in] vars Variáveis do potencial.
00121  * @param[in] values Valores do potencial.
00122  * @return Potencial criado a partir dos dados de entrada.
00123  */
00124 Potential* buildPotential (int id, int nvars, Variable** vars, double* values);
00125 
00126 /*!
00127  * @brief Dump do conteúdo do potencial.
00128  * @param[in] pot Potencial da qual se deseja fazer o dump.
00129  */
00130 
00131 void dumpPotential(Potential* pot);
00132 
00133 /*!
00134  * @brief Destrói um potencial e desaloca os recursos que estavam alocados para o mesmo.
00135  * @param[out] refPotential Referência para o potencial a ser destruído.
00136  */
00137 
00138 void destroyPotential(Potential** refPotential);
00139 
00140 /*!
00141  * @brief Executa o produto entre dois potenciais.
00142  *
00143  * Esta função executa a operação de multiplicação SEM permutar, ou seja, sem alterar os potenciais originais
00144  * as operações são feitas apenas com o mapeamento dos índices.
00145  * @param[in] pot_1 Primeiro potencial.
00146  * @param[in] pot_2 Segundo potencial.
00147  * @return Potencial resultante do produto de potenciais.
00148  */
00149 
00150 Potential* multPotentials (Potential* pot_1, Potential* pot_2);
00151 
00152 /*!
00153  * @brief Marginaliza o potencial para uma dada variável.
00154  *
00155  * Esta função executa a operação de marginalização SEM permutar, ou seja, sem alterar os potenciais originais
00156  * as operações são feitas apenas com o mapeamento dos índices.
00157  * @param[in] variable Variável a ser marginalizada do potencial.
00158  * @param[in] pot Potencial envolvido na operaçãoo de marginalização.
00159  * @return Potencial resultante da marginalização da variável.
00160  */
00161 
00162 Potential* marginalizePotential (Variable* variable, Potential* pot);
00163 
00164 /*!
00165  * @brief Permuta as variáveis e os valores de um potencial de acordo com um vetor de referência.
00166  *
00167  * A permutação altera a ordem dos valores e das variáveis no potencial. Esta operação pode ser utilizada para
00168  * compatibilizar a ordem das variáveis de um potencial para executar operações como marginalização e produto.
00169  * Observe no entanto que é mais eficiente ao invés de permutar os potenciais fazer as operações sem a operação
00170  * de permutação. Veja as funções: \e multPotentials e \e marginalizePotential.
00171  * @param[in] from_to Array de referência com os \e ids dos potenciais.
00172  * @param[out] refPotential Referência para o potencial a ser permutado.
00173  */
00174 void permutePotential (int* from_to, Potential** refPotential);
00175 
00176 /*!
00177  * @brief Compatibiliza a ordem das variáveis em dois potenciais para executar operações de produto.
00178  *
00179  * A compatiliza através da permutação a ordem dos valores e das variáveis de dois potenciais. Esta operação pode ser 
00180  * utilizada para compatibilizar a ordem das variáveis de um potencial para executar operações de produto.
00181  * Observe no entanto que é mais eficiente ao invés de permutar os potenciais fazer as operações sem a operação
00182  * de permutação. Veja as funções: \e multPotentials e \e marginalizePotential.
00183  * @param[in] first Variável que dever ser a primeira  nos potenciais após a sincronização.
00184  * @param[out] refPotential_1 Referência para o primeiro potencial envolvido na sincronização.
00185  * @param[out] refPotential_2 Referência para o segundo potencial envolvido na sincronização.
00186  */
00187 
00188 void syncPotentials (Variable* first, Potential** refPotential_1, Potential** refPotential_2);
00189 
00190 /*!
00191  * @brief Executa o produto entre dois potenciais permutando os potenciais.
00192  *
00193  * Esta função executa a operação de multiplicação PERMUTANDO a ordem do dos potenciais, ou seja, alterando os potenciais
00194  * originais. Esta funcão faz parte de um conjunto de funções que foram utilizadas para desenvolvimento para checar os valores.
00195  * Observe no entanto que é mais eficiente ao invés de permutar os potenciais fazer as operações sem a operação
00196  * de permutação. Veja as funções: \e multPotentials e \e marginalizePotential.
00197  * @param[in] first Variável que deve ser a primeira após a sincronização dos vetores, para acelera futuras a operações do produto.
00198  * @param[out] refPotential_1 Referência para o primeiro potencial envolvido no produto.
00199  * @param[out] refPotential_2 Referência para o segundo potencial envolvido no produto.
00200  * @return Potencial resultante do produto de potenciais.
00201  */
00202 
00203 Potential* permuteMultPotentials (Variable* first, Potential** refPotential_1, Potential** refPotential_2);
00204 
00205 /*!
00206  * @brief Marginaliza um variável de um potencial permutando o potencial para excutar a operação.
00207  *
00208  * Esta função executa a operação de marginalização PERMUTANDO a ordem do do potencial, ou seja, alterando o potencial original.
00209  * Esta funcão faz parte de um conjunto de funções que foram utilizadas para desenvolvimento para checar os valores.
00210  * Observe no entanto que é mais eficiente ao invés de permutar os potenciais fazer as operações sem a operação
00211  * de permutação. Veja as funções: \e multPotentials e \e marginalizePotential.
00212  * @param[in] variable Variável que deve ser marginalizada.
00213  * @param[out] refPotential Referência para o potencial envolvido na marginalização.
00214  * @return Potencial resultante da marginalização da variável.
00215  */
00216 
00217 
00218 Potential* permuteMarginalizePotential (Variable* variable, Potential** refPotential);
00219 
00220 /*!
00221  * @brief Função auxiliar para criar um conjunto de variáveis a ser utilizado para testes.
00222  *
00223  * @param[in] nvars Númerode variáveis.
00224  * @param[in] nstates Array com o número de estados das variáveis.
00225  * @return Array de variáveis criado com base nos dados de entrada.
00226  */
00227 
00228 Variable** fakeVariables (int nvars, int* nstates);
00229 
00230 /*!
00231  * @brief Função auxiliar que cria um potencial \e fake para testes.
00232  * @param[in] id \e id do potencial a ser criado.
00233  * @param[in] first Primeira variável que será parte do potencial.
00234  * @param[in] offset Número de variáveis a serem incorporadas no potencial.
00235  * @param[in] vars Array de variáveis que serão utilizadas para criar o potencial
00236  * @return Potencial criado.
00237  */
00238 
00239 Potential* fakePotential (int id, int first, int offset, Variable** vars);
00240 
00241 #endif

Gerado em Fri Feb 15 19:50:41 2008 para IME-Dissertação por  doxygen 1.5.1