inferenceEngine.h

Go to the documentation of this file.

/****************************************************************************
 *   This file is part of the aGrUM/pyAgrum library.                        *
 *                                                                          *
 *   Copyright (c) 2005-2026 by                                             *
 *       - Pierre-Henri WUILLEMIN(_at_LIP6)                                 *
 *       - Christophe GONZALES(_at_AMU)                                     *
 *                                                                          *
 *   The aGrUM/pyAgrum library is free software; you can redistribute it    *
 *   and/or modify it under the terms of either :                           *
 *                                                                          *
 *    - the GNU Lesser General Public License as published by               *
 *      the Free Software Foundation, either version 3 of the License,      *
 *      or (at your option) any later version,                              *
 *    - the MIT license (MIT),                                              *
 *    - or both in dual license, as here.                                   *
 *                                                                          *
 *   (see https://agrum.gitlab.io/articles/dual-licenses-lgplv3mit.html)    *
 *                                                                          *
 *   This aGrUM/pyAgrum library is distributed in the hope that it will be  *
 *   useful, but WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,          *
 *   INCLUDING BUT NOT LIMITED TO THE WARRANTIES MERCHANTABILITY or FITNESS *
 *   FOR A PARTICULAR PURPOSE  AND NONINFRINGEMENT. IN NO EVENT SHALL THE   *
 *   AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER *
 *   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,        *
 *   ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR  *
 *   OTHER DEALINGS IN THE SOFTWARE.                                        *
 *                                                                          *
 *   See LICENCES for more details.                                         *
 *                                                                          *
 *   SPDX-FileCopyrightText: Copyright 2005-2026                            *
 *       - Pierre-Henri WUILLEMIN(_at_LIP6)                                 *
 *       - Christophe GONZALES(_at_AMU)                                     *
 *   SPDX-License-Identifier: LGPL-3.0-or-later OR MIT                      *
 *                                                                          *
 *   Contact  : info_at_agrum_dot_org                                       *
 *   homepage : http://agrum.gitlab.io                                      *
 *   gitlab   : https://gitlab.com/agrumery/agrum                           *
 *                                                                          *
 ****************************************************************************/
 
 
#ifndef GUM_INFERENCE_ENGINE_H
#define GUM_INFERENCE_ENGINE_H

#include <map>
 
#include <agrum/base/core/approximations/approximationScheme.h>
#include <agrum/base/core/threads/threadData.h>
#include <agrum/base/core/threads/threadNumberManager.h>
#include <agrum/CN/tools/varMod2BNsMap.h>
 
#include <string_view>
 
namespace gum {
  namespace credal {

    template < GUM_Numeric GUM_SCALAR >
    class PYGUM_PUBLIC InferenceEngine: public ApproximationScheme, public ThreadNumberManager {
      using credalSet = NodeProperty< std::vector< std::vector< GUM_SCALAR > > >;
      using margi     = NodeProperty< std::vector< GUM_SCALAR > >;
      using expe      = NodeProperty< GUM_SCALAR >;
 
      using dynExpe = typename gum::HashTable< std::string, std::vector< GUM_SCALAR > >;
 
      using query   = NodeProperty< std::vector< bool > >;
      using cluster = NodeProperty< std::vector< NodeId > >;
 
      protected:
      const CredalNet< GUM_SCALAR >* credalNet_;

      margi oldMarginalMin_;
      margi oldMarginalMax_;

      margi marginalMin_;
      margi marginalMax_;

      credalSet marginalSets_;

      expe expectationMin_;
      expe expectationMax_;

      dynExpe dynamicExpMin_;
      dynExpe dynamicExpMax_;

      dynExpe modal_;

      margi evidence_;
      query query_;

      cluster t0_;
      cluster t1_;

      bool storeVertices_;
      bool repetitiveInd_;

      bool storeBNOpt_;

      VarMod2BNsMap< GUM_SCALAR > dbnOpt_;

      std::vector< std::pair< NodeId, Idx > > threadRanges_;

      int timeSteps_;
 
      // the minimal number of operations that a thread should execute
      Size threadMinimalNbOps_{Size(20)};


      void repetitiveInit_();

      void initExpectations_();

      void initMarginals_();

      void dispatchMarginalsToThreads_();

      void initMarginalSets_();



      virtual const GUM_SCALAR computeEpsilon_();

      inline void updateExpectations_(const NodeId& id, const std::vector< GUM_SCALAR >& vertex);

      inline void updateCredalSets_(const NodeId&                    id,
                                    const std::vector< GUM_SCALAR >& vertex,
                                    const bool&                      elimRedund = false);



      void dynamicExpectations_();
 
      public:
 
      // InferenceEngine ();
      explicit InferenceEngine(const CredalNet< GUM_SCALAR >& credalNet);
      ~InferenceEngine() override;



      virtual void makeInference() = 0;


      VarMod2BNsMap< GUM_SCALAR >* getVarMod2BNsMap();

      const CredalNet< GUM_SCALAR >& credalNet() const;

      const NodeProperty< std::vector< NodeId > >& getT0Cluster() const;

      const NodeProperty< std::vector< NodeId > >& getT1Cluster() const;

      void setRepetitiveInd(const bool repetitive);

      void storeVertices(const bool value);
      void storeBNOpt(const bool value);

      bool repetitiveInd() const;

      bool storeVertices() const;
      bool storeBNOpt() const;


      virtual void addEvidence(NodeId id, const Idx val) final;


      virtual void addEvidence(std::string_view nodeName, const Idx val) final;


      virtual void addEvidence(NodeId id, std::string_view label) final;


      virtual void addEvidence(std::string_view nodeName, std::string_view label) final;


      virtual void addEvidence(NodeId id, const std::vector< GUM_SCALAR >& vals) final;


      virtual void addEvidence(std::string_view                 nodeName,
                               const std::vector< GUM_SCALAR >& vals) final;


      virtual void addEvidence(const Tensor< GUM_SCALAR >& pot) final;
 

      virtual void eraseAllEvidence();


      void insertModalsFile(std::string_view path);

      void insertModals(const std::map< std::string, std::vector< GUM_SCALAR > >& modals);

      virtual void insertEvidenceFile(std::string_view path);

      void insertEvidence(const std::map< std::string, std::vector< GUM_SCALAR > >& eviMap);

      void insertEvidence(const NodeProperty< std::vector< GUM_SCALAR > >& evidence);

      void insertQueryFile(std::string_view path);

      void insertQuery(const NodeProperty< std::vector< bool > >& query);



      Tensor< GUM_SCALAR > marginalMin(const NodeId id) const;

      Tensor< GUM_SCALAR > marginalMax(const NodeId id) const;

      Tensor< GUM_SCALAR > marginalMin(std::string_view varName) const;

      Tensor< GUM_SCALAR > marginalMax(std::string_view varName) const;

      const GUM_SCALAR& expectationMin(const NodeId id) const;

      const GUM_SCALAR& expectationMax(const NodeId id) const;

      const GUM_SCALAR& expectationMin(std::string_view varName) const;

      const GUM_SCALAR& expectationMax(std::string_view varName) const;

      const std::vector< GUM_SCALAR >& dynamicExpMin(std::string_view varName) const;

      const std::vector< GUM_SCALAR >& dynamicExpMax(std::string_view varName) const;

      const std::vector< std::vector< GUM_SCALAR > >& vertices(const NodeId id) const;

      void saveMarginals(std::string_view path) const;

      void saveExpectations(std::string_view path) const;

      void saveVertices(std::string_view path) const;

      void dynamicExpectations();   // if someone forgets the protected call at
                                    // the end
                                    // of its own algorithm, the user can call it

      std::string toString() const;

      const std::string getApproximationSchemeMsg();

    };
 
 
#ifndef GUM_NO_EXTERN_TEMPLATE_CLASS
    extern template class InferenceEngine< double >;
#endif
  }   // namespace credal
}   // namespace gum
 
#include <agrum/CN/inference/inferenceEngine_tpl.h>
 
#endif