src/pmml/PMMLlib.hxx

   1 // Copyright (C) 2013-2024 CEA
   2 //
   3 // This program is free software: you can redistribute it and/or modify
   4 // it under the terms of the GNU Lesser General Public License as published
   5 // by the Free Software Foundation, either version 3 of the License, or any
   6 // later version.
   7 //
   8 // This program is distributed in the hope that it will be useful,
   9 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  10 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11 // GNU Lesser General Public License for more details.
  12 //
  13 // You should have received a copy of the GNU Lesser General Public License
  14 // along with this program. If not, see <http://www.gnu.org/licenses/>.
  15
  16 /*!
  17   \file   PMMLlib.hxx
  18   \author InckA
  19   \date   Wed Nov 20 11:04:17 2013
  20
  21   \brief  Header de la classe PMMLlib
  22
  23  */
  24
  25 #ifndef __PMMLLIB_H__
  26 #define __PMMLLIB_H__
  27
  28 #include "PMMLwin.hxx"
  29
  30 #include <libxml/xpathInternals.h>
  31 #include <string>
  32 #include <vector>
  33 #include <sstream>
  34
  35 namespace PMMLlib
  36 {
  37
  38 template <typename T>
  39 std::string NumberToString ( T Number )
  40 {
  41      std::ostringstream ss;
  42      ss << Number;
  43      return ss.str();
  44 }
  45
  46 /**
  47  * Enumeration to type the PMML file.
  48  * UNDEFINED: not yet defined
  49  * ANN: Artificial Neural Network
  50  * LR:  Linear Regression
  51  *
  52  * @see http://www.dmg.org/v4-1/GeneralStructure.html#xsdGroup_MODEL-ELEMENT
  53  */
  54 enum PMMLType{kUNDEFINED, kANN, kLR};
  55
  56
  57 /**
  58  * @see http://www.dmg.org/v4-1/NeuralNetwork.html#xsdType_ACTIVATION-FUNCTION
  59  */
  60 enum PMMLActivationFunction{kIDENTITY, kTANH, kLOGISTIC};
  61
  62
  63 /**
  64  * @see http://www.dmg.org/v4-1/GeneralStructure.html#xsdType_MINING-FUNCTION
  65  */
  66 enum PMMLMiningFunction{kREGRESSION};
  67
  68
  69 /**
  70  * Class PMMLlib
  71  */
  72 class PMMLlib
  73 {
  74
  75 private:
  76     bool _log;                      //!< Log Printing
  77     std::string _pmmlFile;          //!< Name of the associated PMML file
  78     xmlDocPtr _doc;                 //!< Associated DOM documents
  79     xmlNodePtr _rootNode;           //!< Root node of the document
  80     xmlNodePtr _currentNode;        //!< Pointer to the current node
  81     int _nbModels;                  //!< Number of models (all kinds)
  82     std::string _currentModelName;  //!< Name of the current model
  83     PMMLType _currentModelType;     //!< Type of the current model
  84     xmlNodePtr _currentModelNode;   //!< Pointer to the current model node
  85
  86     /** @defgroup general General methods
  87      *  Common methods to all kinds of PMML files and models
  88      *  @{
  89      */
  90 public:
  91     PMMLLIB_EXPORT PMMLlib(std::string file,
  92                            bool log=false) ;
  93     PMMLLIB_EXPORT PMMLlib(bool log=false);
  94     PMMLLIB_EXPORT ~PMMLlib();
  95     PMMLLIB_EXPORT void SetCurrentModel(std::string modelName,
  96                                         PMMLType type);
  97     PMMLLIB_EXPORT void SetCurrentModel(std::string modelName);
  98     PMMLLIB_EXPORT void SetCurrentModel();
  99     PMMLLIB_EXPORT std::string makeLog() const;
 100     PMMLLIB_EXPORT void printLog() const;
 101
 102     PMMLLIB_EXPORT void AddDataField(std::string name,
 103                                      std::string displayName,
 104                                      std::string optype,
 105                                      std::string dataType,
 106                                      std::string closure,
 107                                      double leftMargin,
 108                                      double rightMargin,
 109                                      bool interval=false);
 110     PMMLLIB_EXPORT void AddMiningSchema(std::string name,
 111                                         std::string usageType);
 112     PMMLLIB_EXPORT void SetHeader(std::string copyright,
 113                                   std::string description,
 114                                   std::string appName,
 115                                   std::string appVersion,
 116                                   std::string annotation);
 117     PMMLLIB_EXPORT void UnlinkNode();
 118     PMMLLIB_EXPORT void BackupNode();
 119     PMMLLIB_EXPORT int GetModelsNb();
 120     PMMLLIB_EXPORT void Write();
 121     PMMLLIB_EXPORT void Write(std::string file);
 122     PMMLLIB_EXPORT PMMLType GetCurrentModelType();
 123     PMMLLIB_EXPORT std::string GetCurrentModelName();
 124 private:
 125     xmlNodePtr GetChildByName(xmlNodePtr node,
 126                               std::string nodename);
 127     xmlNodePtr GetPtr(int ann_index,
 128                       std::string name);
 129     xmlNodePtr GetPtr(std::string ann_name,
 130                       std::string name);
 131     void CountModels();
 132     int CountNeuralNetModels();
 133     int CountRegressionModels();
 134     void SetRootNode();
 135     std::string GetModelName(xmlNodePtr node);
 136     std::string GetTypeString();
 137
 138     /** @} */ // end of group general
 139
 140
 141     /** @defgroup ann Methods dedicated to neural networks
 142      *  Methods dedicated to neural networks
 143      *  @{
 144      */
 145 public:
 146     PMMLLIB_EXPORT void AddNeuralNetwork(std::string modelName,
 147                                          PMMLMiningFunction functionName);
 148     PMMLLIB_EXPORT void AddNeuralInput(int id,
 149                                        std::string inputName,
 150                                        std::string optype,
 151                                        std::string dataType,
 152                                        double orig1, double norm1,
 153                                        double orig2, double norm2);
 154     PMMLLIB_EXPORT void AddNeuralLayer(PMMLActivationFunction activationFunction);
 155     PMMLLIB_EXPORT void AddNeuron(int id,
 156                                   double bias,
 157                                   int conNb,
 158                                   int firstFrom,
 159                                   std::vector<double> weights);
 160     PMMLLIB_EXPORT void AddNeuralOutput(int outputNeuron,
 161                                         std::string outputName,
 162                                         std::string optype,
 163                                         std::string dataType,
 164                                         double orig1, double norm1,
 165                                         double orig2, double norm2);
 166     PMMLLIB_EXPORT int GetNbInputs();
 167     PMMLLIB_EXPORT int GetNbOutputs();
 168     PMMLLIB_EXPORT std::string GetNameInput(int input_index);
 169     PMMLLIB_EXPORT std::string GetNameOutput(int output_index);
 170     PMMLLIB_EXPORT int GetNormalizationType();
 171     PMMLLIB_EXPORT void GetNormalisationInput(int input_index,
 172                                               double *dnorm);
 173     PMMLLIB_EXPORT void GetNormalisationOutput(int output_index,
 174                                                double *dnorm);
 175     PMMLLIB_EXPORT int GetNbHiddenLayers();
 176     PMMLLIB_EXPORT int GetNbLayers();
 177     PMMLLIB_EXPORT int GetNbNeuronsAtLayer(int layer_index);
 178     PMMLLIB_EXPORT double GetNeuronBias(int layer_index,
 179                                         int neu_index);
 180     PMMLLIB_EXPORT double GetPrecNeuronSynapse(int layer_index,
 181                                                int neu_index,
 182                                                int prec_index);
 183     PMMLLIB_EXPORT void SetNeuralNetName(int ann_index,
 184                                          std::string ann_name);
 185     PMMLLIB_EXPORT std::string ReadNetworkStructure();
 186 private:
 187     xmlNodePtr GetNeuralNetPtr(std::string ann_name);
 188     xmlNodePtr GetNeuralNetPtr(int ann_index);
 189     void CheckNeuralNetwork();
 190     /** @} */ // end of group ann
 191
 192
 193     /** @defgroup ln Methods dedicated to linear regression
 194      *  Methods dedicated to linear regression
 195      *  @{
 196      */
 197 public:
 198     PMMLLIB_EXPORT void AddRegressionModel(std::string modelName,
 199                                            PMMLMiningFunction functionName,
 200                                            std::string targetFieldName);
 201     PMMLLIB_EXPORT void AddRegressionTable();
 202     PMMLLIB_EXPORT void AddRegressionTable(double intercept);
 203     PMMLLIB_EXPORT void AddNumericPredictor(std::string neuronName,
 204                                             int exponent,
 205                                             double coefficient);
 206     PMMLLIB_EXPORT void AddPredictorTerm(double coefficient,
 207                                          std::vector<std::string> fieldRef);
 208     PMMLLIB_EXPORT bool HasIntercept();
 209     PMMLLIB_EXPORT double GetRegressionTableIntercept();
 210     PMMLLIB_EXPORT int GetNumericPredictorNb();
 211     PMMLLIB_EXPORT int GetPredictorTermNb();
 212     PMMLLIB_EXPORT std::string GetNumericPredictorName(int num_pred_index);
 213     PMMLLIB_EXPORT std::string GetPredictorTermName(int num_pred_index);
 214     PMMLLIB_EXPORT double GetNumericPredictorCoefficient(int num_pred_index);
 215     PMMLLIB_EXPORT double GetPredictorTermCoefficient(int pred_term_index);
 216     PMMLLIB_EXPORT int GetPredictorTermFieldRefNb(int pred_term_index);
 217     PMMLLIB_EXPORT std::string GetPredictorTermFieldRefName(int pred_term_index,
 218                                                             int field_index);
 219     PMMLLIB_EXPORT std::string ReadRegressionStructure();
 220 private:
 221     xmlNodePtr GetRegressionPtr(int reg_index);
 222     xmlNodePtr GetRegressionPtr(std::string reg_name);
 223     void CheckRegression();
 224
 225     /** @} */ // end of group ln
 226
 227
 228     /** @defgroup export Methods dedicated to file export
 229      *  Methods dedicated to file export
 230      *  @{
 231      */
 232 private:
 233     void fillVectorsForExport(int nInput, int nOutput, int nHidden, int normType,
 234             std::vector<double> &minInput, std::vector<double> &maxInput,
 235             std::vector<double> &minOutput, std::vector<double> &maxOutput,
 236             std::vector<double> &valW );
 237 public:
 238     PMMLLIB_EXPORT void ExportCpp(std::string file,
 239                                   std::string functionName,
 240                                   std::string header);
 241     PMMLLIB_EXPORT void ExportFortran(std::string file,
 242                                       std::string functionName,
 243                                       std::string header);
 244     PMMLLIB_EXPORT void ExportPython(std::string file,
 245                                      std::string functionName,
 246                                      std::string header);
 247     PMMLLIB_EXPORT std::string ExportPyStr(std::string functionName,
 248                                            std::string header);
 249 private:
 250     void ExportNeuralNetworkCpp(std::string file,
 251                                 std::string functionName,
 252                                 std::string header);
 253     void ExportNeuralNetworkFortran(std::string file,
 254                                     std::string functionName,
 255                                     std::string header);
 256     void ExportNeuralNetworkPython(std::string file,
 257                                    std::string functionName,
 258                                    std::string header);
 259     std::string ExportNeuralNetworkPyStr(std::string functionName,
 260                                          std::string header);
 261
 262     void ExportLinearRegressionCpp(std::string,
 263                                    std::string,
 264                                    std::string);
 265     void ExportLinearRegressionFortran(std::string,
 266                                        std::string,
 267                                        std::string);
 268     void ExportLinearRegressionPython(std::string,
 269                                       std::string,
 270                                       std::string);
 271     std::string ExportLinearRegressionPyStr(std::string functionName,
 272                                             std::string header);
 273     /** @} */ // end of group export
 274
 275   private:
 276     /*!     * Conversion from a libxml2 string (xmlChar *) to a standard C++ string.
 277      *
 278      *    \param xs a constant libxml string.
 279      *    \return a C++ std::string (contains the same text as xs).
 280      */
 281      std::string _xmlCharToString(const xmlChar *xs) const;
 282     /*!
 283     * Conversion from a standard C++ string to a libxml2 string (xmlChar *)
 284     *
 285     *    \param s a constant C++ std::string.
 286     *    \return a libxml string (contains the same text as s)
 287     *
 288     * The caller of this function must free the result when it's not needed
 289     * anymore (using xmlFree)
 290     */
 291     xmlChar * _stringToXmlChar(const std::string &s) const;
 292
 293     std::string _getProp(const xmlNodePtr node,
 294                          std::string const & prop ) const;
 295
 296 };
 297
 298 }
 299
 300 #endif  //__PMMLLIB_H__