plugins.h

Go to the documentation of this file.

// ------------------------------------------------------
//
// SPDX-License-Identifier: GPL-2.0-or-later
//
// SPDX-FileCopyrightText: Copyright (C) 2011-2026 by the ASPECT authors.
//
// This file is part of ASPECT.
//
// Detailed license information governing the source code and
// contributions can be found in the folder LICENSES and in
// LICENSE and CONTRIBUTING.md at the top level directory.
//
// ------------------------------------------------------


#ifndef _aspect_plugins_h
#define _aspect_plugins_h

#include <aspect/global.h>

#include <deal.II/base/utilities.h>
#include <deal.II/base/parameter_handler.h>
#include <deal.II/fe/component_mask.h>

#include <boost/core/demangle.hpp>

#include <tuple>
#include <string>
#include <list>
#include <set>
#include <map>
#include <iostream>
#include <typeinfo>
#include <type_traits>

#include <mpi.h>


namespace aspect
{
  template <int dim> class SimulatorAccess;

  namespace Plugins
  {
    template <typename TestType, typename PluginType,
              typename = typename std::enable_if_t<std::is_base_of<PluginType,TestType>::value>>
    inline
    bool
    plugin_type_matches (const PluginType &object)
    {
      return (dynamic_cast<const TestType *> (&object) != nullptr);
    }

    template <typename TestType, typename PluginType,
              typename = typename std::enable_if_t<std::is_base_of<PluginType,TestType>::value>>
    inline
    TestType &
    get_plugin_as_type (PluginType &object)
    {
      AssertThrow(plugin_type_matches<TestType>(object),
                  ExcMessage("You have requested to convert a plugin of type <"
                             + boost::core::demangle(typeid(PluginType).name())
                             + "> into type <"
                             + boost::core::demangle(typeid(TestType).name()) +
                             ">, but this cast cannot be performed."));

      // We can safely dereference the pointer, because we checked above that
      // the object is actually of type TestType, and so the result
      // is not a nullptr.
      return *dynamic_cast<TestType *> (&object);
    }
  }

  namespace Plugins
  {
    class InterfaceBase
    {
      public:
        virtual ~InterfaceBase() = default;

        virtual
        void
        initialize ();

        virtual
        void
        update ();

        static
        void
        declare_parameters (ParameterHandler &prm);

        virtual
        void
        parse_parameters (ParameterHandler &prm);

        virtual
        void save (std::map<std::string, std::string> &status_strings) const;

        virtual
        void load (const std::map<std::string, std::string> &status_strings);
    };



    template <typename InterfaceType>
    class ManagerBase : public InterfaceBase
    {
      public:
        ~ManagerBase () override;

        void
        update () override;

        template <typename PluginType,
                  typename = typename std::enable_if_t<std::is_base_of<InterfaceType,PluginType>::value>>
        bool
        has_matching_active_plugin () const;

        template <typename PluginType,
                  typename = typename std::enable_if_t<std::is_base_of<InterfaceType,PluginType>::value>>
        const PluginType &
        get_matching_active_plugin () const;

        const std::list<std::unique_ptr<InterfaceType>> &
        get_active_plugins () const;

        const std::vector<std::string> &
        get_active_plugin_names () const;

        template <class Archive>
        void save (Archive &ar,
                   const unsigned int version) const;

        using InterfaceBase::save;

        template <class Archive>
        void load (Archive &ar,
                   const unsigned int version);

        using InterfaceBase::load;

        BOOST_SERIALIZATION_SPLIT_MEMBER()

      protected:
        std::list<std::unique_ptr<InterfaceType>> plugin_objects;

        std::vector<std::string> plugin_names;
    };



    template <typename InterfaceType>
    ManagerBase<InterfaceType>::~ManagerBase()
    {
      // only check and throw if we are not unwinding the stack due
      // to an active exception
#ifdef DEAL_II_HAVE_CXX17
      if (std::uncaught_exceptions() == 0)
#else
      if (std::uncaught_exception() == false)
#endif
        {
          Assert (plugin_names.size() == plugin_objects.size(), ExcInternalError());
        }
    }


    template <typename InterfaceType>
    void ManagerBase<InterfaceType>::update()
    {
      // call the update() functions of all plugins:
      for (const auto &p : plugin_objects)
        {
          try
            {
              p->update ();
            }

          // plugins that throw exceptions usually do not result in
          // anything good because they result in an unwinding of the stack
          // and, if only one processor triggers an exception, the
          // destruction of objects often causes a deadlock. thus, if
          // an exception is generated, catch it, print an error message,
          // and abort the program
          catch (std::exception &exc)
            {
              std::cerr << std::endl << std::endl
                        << "----------------------------------------------------"
                        << std::endl;
              std::cerr << "Exception on MPI process <"
                        << ::Utilities::MPI::this_mpi_process(MPI_COMM_WORLD)
                        << "> while running plugin <"
                        << typeid(*p).name()
                        << ">: " << std::endl
                        << exc.what() << std::endl
                        << "Aborting!" << std::endl
                        << "----------------------------------------------------"
                        << std::endl;

              // terminate the program!
              MPI_Abort (MPI_COMM_WORLD, 1);
            }
          catch (...)
            {
              std::cerr << std::endl << std::endl
                        << "----------------------------------------------------"
                        << std::endl;
              std::cerr << "Exception on MPI process <"
                        << ::Utilities::MPI::this_mpi_process(MPI_COMM_WORLD)
                        << "> while running plugin <"
                        << typeid(*p).name()
                        << ">: " << std::endl;
              std::cerr << "Unknown exception!" << std::endl
                        << "Aborting!" << std::endl
                        << "----------------------------------------------------"
                        << std::endl;

              // terminate the program!
              MPI_Abort (MPI_COMM_WORLD, 1);
            }
        }
    }



    template <typename InterfaceType>
    template <class Archive>
    void ManagerBase<InterfaceType>::save (Archive &ar,
                                           const unsigned int) const
    {
      // let all the postprocessors save their data in a map and then
      // serialize that
      std::map<std::string,std::string> saved_text;
      for (const auto &p : plugin_objects)
        p->save (saved_text);

      ar &saved_text;
    }


    template <typename InterfaceType>
    template <class Archive>
    void ManagerBase<InterfaceType>::load (Archive &ar,
                                           const unsigned int)
    {
      // get the map back out of the stream; then let the postprocessors
      // that we currently have get their data from there. note that this
      // may not be the same set of postprocessors we had when we saved
      // their data
      std::map<std::string,std::string> saved_text;
      ar &saved_text;

      for (auto &p : plugin_objects)
        p->load (saved_text);
    }



    template <typename InterfaceType>
    template <typename PluginType, typename>
    inline
    bool
    ManagerBase<InterfaceType>::has_matching_active_plugin () const
    {
      for (const auto &p : plugin_objects)
        if (Plugins::plugin_type_matches<PluginType>(*p))
          return true;
      return false;
    }


    template <typename InterfaceType>
    template <typename PluginType, typename>
    inline
    const PluginType &
    ManagerBase<InterfaceType>::get_matching_active_plugin () const
    {
      AssertThrow(has_matching_active_plugin<PluginType> (),
                  ExcMessage("You asked the object managing a collection of plugins for a "
                             "plugin object of type <" + boost::core::demangle(typeid(PluginType).name()) + "> "
                             "that could not be found in the current model. You need to "
                             "activate this plugin in the input file for it to be "
                             "available."));

      for (const auto &p : plugin_objects)
        if (Plugins::plugin_type_matches<PluginType>(*p))
          return Plugins::get_plugin_as_type<PluginType>(*p);

      // We will never get here, because we had the Assert above. Just to avoid warnings.
      return Plugins::get_plugin_as_type<PluginType>(**(plugin_objects.begin()));
    }



    template <typename InterfaceType>
    const std::list<std::unique_ptr<InterfaceType>> &
    ManagerBase<InterfaceType>::get_active_plugins () const
    {
      return plugin_objects;
    }



    template <typename InterfaceType>
    const std::vector<std::string> &
    ManagerBase<InterfaceType>::get_active_plugin_names () const
    {
      return plugin_names;
    }

  }

  namespace internal
  {
    namespace Plugins
    {
      template <typename InterfaceClass,
                typename ModelClass>
      struct RegisterHelper
      {
        RegisterHelper (void (*register_function) (const std::string &,
                                                   const std::string &,
                                                   void ( *)(ParameterHandler &),
                                                   std::unique_ptr<InterfaceClass> ( *)()),
                        const char *name,
                        const char *description)
        {
          register_function (name,
                             description,
                             &ModelClass::declare_parameters,
                             &factory);
        }

        static
        std::unique_ptr<InterfaceClass> factory ()
        {
          return std::make_unique<ModelClass>();
        }
      };


      template <typename InterfaceClass>
      struct PluginList
      {
        using PluginInfo
        = std::tuple<std::string,
        std::string,
        void ( *) (ParameterHandler &),
        std::unique_ptr<InterfaceClass>( *) ()>;

        static std::list<PluginInfo> *plugins;

        ~PluginList ();

        static
        void register_plugin (const std::string &name,
                              const std::string &description,
                              void (*declare_parameters_function) (ParameterHandler &),
                              std::unique_ptr<InterfaceClass> (*factory_function) ());

        static
        std::string get_pattern_of_names ();

        static
        std::string get_description_string ();

        static
        void declare_parameters (ParameterHandler &prm);

        static
        std::unique_ptr<InterfaceClass>
        create_plugin (const std::string  &name,
                       const std::string &documentation);

        static
        std::unique_ptr<InterfaceClass>
        create_plugin (const std::string  &name,
                       const std::string &documentation,
                       ParameterHandler &prm);

        static
        void
        write_plugin_graph (const std::string &plugin_system_name,
                            std::ostream      &output_stream,
                            const std::string &attachment_point = "Simulator");

        DeclException1 (ExcUnknownPlugin,
                        std::string,
                        << "Can't create a plugin of name <" << arg1
                        << "> because such a plugin hasn't been declared.");
      };


      /* ------------------------ template and inline functions --------------------- */

      template <typename InterfaceClass>
      PluginList<InterfaceClass>::
      ~PluginList ()
      {
        // if any plugins have been registered, then delete
        // the list
        if (plugins != nullptr)
          delete plugins;
        plugins = nullptr;
      }



      template <typename InterfaceClass>
      void
      PluginList<InterfaceClass>::
      register_plugin (const std::string &name,
                       const std::string &description,
                       void (*declare_parameters_function) (ParameterHandler &),
                       std::unique_ptr<InterfaceClass> (*factory_function) ())
      {
        // see if this is the first time we get into this
        // function and if so initialize the static member variable
        if (plugins == nullptr)
          plugins = new std::list<PluginInfo>();

        // verify that the same name has not previously been
        // used to register a plugin, since we would then no
        // longer be able to identify the plugin
        for (const auto &p : *plugins)
          {
            Assert (std::get<0>(p) != name,
                    ExcMessage ("A plugin with name <" + name + "> has "
                                "already been registered!"));
            (void)p;
          }


        // now add one record to the list
        plugins->emplace_back (name,
                               description,
                               declare_parameters_function,
                               factory_function);
      }



      template <typename InterfaceClass>
      std::string
      PluginList<InterfaceClass>::
      get_pattern_of_names ()
      {
        Assert (plugins != nullptr,
                ExcMessage ("No plugins registered!?"));

        // get all names and put them into a data structure that keeps
        // them sorted
        std::set<std::string> names;
        for (typename std::list<PluginInfo>::const_iterator
             p = plugins->begin();
             p != plugins->end(); ++p)
          names.insert (std::get<0>(*p));

        // now create a pattern from all of these sorted names
        std::string pattern_of_names;
        for (const auto &name : names)
          {
            if (pattern_of_names.size() > 0)
              pattern_of_names += "|";
            pattern_of_names += name;
          }

        return pattern_of_names;
      }



      template <typename InterfaceClass>
      std::string
      PluginList<InterfaceClass>::
      get_description_string ()
      {
        std::string description;

        // get all names_and_descriptions and put them into a data structure that keeps
        // them sorted
        std::map<std::string,std::string> names_and_descriptions;
        for (typename std::list<PluginInfo>::const_iterator
             p = plugins->begin();
             p != plugins->end(); ++p)
          names_and_descriptions[std::get<0>(*p)] = std::get<1>(*p);

        // then output it all
        std::map<std::string,std::string>::const_iterator
        p = names_and_descriptions.begin();
        while (true)
          {
            // write the name and
            // description of the
            // parameter
            description += "`";
            description += p->first;
            description += "': ";
            description += p->second;

            // increment the pointer
            // by one. if we are not
            // at the end yet then
            // add an empty line
            ++p;
            if (p != names_and_descriptions.end())
              description += "\n\n";
            else
              break;
          }

        return description;
      }




      template <typename InterfaceClass>
      void
      PluginList<InterfaceClass>::
      declare_parameters (ParameterHandler &prm)
      {
        Assert (plugins != nullptr,
                ExcMessage ("No postprocessors registered!?"));

        for (typename std::list<PluginInfo>::const_iterator
             p = plugins->begin();
             p != plugins->end(); ++p)
          (std::get<2>(*p))(prm);
      }



      template <typename InterfaceClass>
      std::unique_ptr<InterfaceClass>
      PluginList<InterfaceClass>::
      create_plugin (const std::string &name,
                     const std::string &documentation)
      {
        (void)documentation;
        Assert (plugins != nullptr,
                ExcMessage ("No postprocessors registered!?"));
        AssertThrow (name != "unspecified",
                     ExcMessage(std::string("A plugin must have a name!\n\n"
                                            "This function was asked to create a plugin but no name for the "
                                            "plugin was provided. This may be due to the fact that you did not "
                                            "explicitly specify a name for this plugin in your input file and "
                                            "ASPECT does not provide a default for this kind of plugin, for "
                                            "example because no generally useful plugin exists. An example "
                                            "is that there is no default geometry: You need to explicitly "
                                            "provide one in the input file, and it seems like you have not "
                                            "done so.\n\n"
                                            "To find out which kind of plugin this function tries to create, "
                                            "take a look at the backtrace of this error message.\n\n"
                                            "The place that called this function also provided as "
                                            "additional information this:\n\n"
                                            "   <")
                                + documentation + ">"));

        for (typename std::list<PluginInfo>::const_iterator p = plugins->begin();
             p != plugins->end(); ++p)
          if (std::get<0>(*p) == name)
            {
              std::unique_ptr<InterfaceClass> i = std::get<3>(*p)();
              return i;
            }

        AssertThrow (false, ExcUnknownPlugin(name));
        return nullptr;
      }



      template <typename InterfaceClass>
      std::unique_ptr<InterfaceClass>
      PluginList<InterfaceClass>::
      create_plugin (const std::string &name,
                     const std::string &documentation,
                     ParameterHandler  &prm)
      {
        std::unique_ptr<InterfaceClass> i = create_plugin(name, documentation);
        i->parse_parameters (prm);
        return i;
      }



      template <typename InterfaceClass>
      void
      PluginList<InterfaceClass>::
      write_plugin_graph (const std::string &plugin_system_name,
                          std::ostream      &output_stream,
                          const std::string &attachment_point)
      {
        // first output a graph node for the interface class as the central
        // hub of this plugin system, plotted as a square.
        //
        // we use the typeid name of the interface class to label
        // nodes within this plugin system, as they are unique among
        // all other plugin systems
        output_stream << std::string(typeid(InterfaceClass).name())
                      << " [label=\""
                      << plugin_system_name
                      << "\", height=.8,width=.8,shape=\"rect\",fillcolor=\"lightgreen\"]"
                      << std::endl;

        // then output the graph nodes for each plugin, with links to the
        // interface class and, as appropriate, from the SimulatorAccess class
        //
        // we would like to establish a predictable order of output here, but
        // plugins self-register via static global variables, and their
        // initialization order is not deterministic. consequently, let us
        // loop over all plugins first and put pointers to them into a
        // map with deterministic keys. as key, we use the declared name
        // of the plugin by which it is referred in the .prm file
        std::map<std::string, typename std::list<PluginInfo>::const_iterator>
        plugin_map;
        for (typename std::list<PluginInfo>::const_iterator p = plugins->begin();
             p != plugins->end(); ++p)
          plugin_map[std::get<0>(*p)] = p;

        // now output the information sorted by the plugin names
        for (typename std::map<std::string, typename std::list<PluginInfo>::const_iterator>::const_iterator
             p = plugin_map.begin();
             p != plugin_map.end(); ++p)
          {
            // take the name of the plugin and split it into strings of
            // 15 characters at most; then combine them
            // again using \n to make dot/neato show these parts of
            // the name on separate lines
            const std::vector<std::string> plugin_label_parts
              = ::Utilities::break_text_into_lines(p->first, 15);
            Assert (plugin_label_parts.size()>0, ExcInternalError());
            std::string plugin_name = plugin_label_parts[0];
            for (unsigned int i=1; i<plugin_label_parts.size(); ++i)
              plugin_name += "\\n" + plugin_label_parts[i];

            // next create a (symbolic) node name for this plugin. because
            // each plugin corresponds to a particular class, use the mangled
            // name of the class
            std::unique_ptr<InterfaceClass> instance (create_plugin (p->first, ""));
            const std::string node_name = typeid(*instance).name();

            // then output the whole shebang describing this node
            output_stream << node_name
                          << " [label=\""
                          << plugin_name
                          << "\", height=.8,width=.8,shape=\"circle\",fillcolor=\"lightblue\"];"
                          << std::endl;

            // next build connections from this plugin to the
            // interface class
            output_stream << node_name
                          << " -> "
                          << std::string(typeid(InterfaceClass).name())
                          << " [len=3, weight=50]"
                          << ';'
                          << std::endl;

            // finally see if this plugin is derived from
            // SimulatorAccess; if so, draw an arrow from SimulatorAccess
            // also to the plugin's name
            if (dynamic_cast<const SimulatorAccess<2>*>(instance.get()) != nullptr
                ||
                dynamic_cast<const SimulatorAccess<3>*>(instance.get()) != nullptr)
              output_stream << "SimulatorAccess"
                            << " -> "
                            << node_name
                            << " [style=\"dotted\", arrowhead=\"empty\", constraint=false, color=\"gray\", len=20, weight=0.1];"
                            << std::endl;
          }

        // as a last step, also draw a connection from the interface class
        // to the Simulator class, or whatever the calling function indicates
        // as the attachment point
        output_stream << std::string(typeid(InterfaceClass).name())
                      << " -> "
                      << attachment_point
                      << " [len=15, weight=50]"
                      << ';'
                      << std::endl;

        // end it with an empty line to make things easier to
        // read when looking over stuff visually
        output_stream << std::endl;
      }



      // Add definition for plugins member:
      template <typename InterfaceClass>
      inline std::list<typename PluginList<InterfaceClass>::PluginInfo> *PluginList<InterfaceClass>::plugins = nullptr;



      class UnusablePluginList {};
    }
  }
}


#endif