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