refactor: Log level documentation on SolverBase and children

src/coreComponents/common/CMakeLists.txt

@@ -16,6 +16,7 @@ set( common_headers
      GEOS_RAJA_Interface.hpp
      GeosxMacros.hpp
      MemoryInfos.hpp
+     logger/Logger.hpp
      MpiWrapper.hpp
      Path.hpp
      Span.hpp

src/coreComponents/common/logger/Logger.hpp

@@ -79,6 +79,21 @@
     } \
   } while( false )
 
+/**
+ * @brief Conditionally log a message on screen on rank 0 without line breaking.
+ * @param EXP an expression that will be evaluated as a predicate
+ * @param msg a message to log (any expression that can be stream inserted)
+ */
+#define GEOS_LOG_RANK_0_IF_NLR( EXP, msg ) \
+  do { \
+    if( ::geos::logger::internal::rank == 0 && EXP ) \
+    { \
+      std::ostringstream oss; \
+      oss << msg; \
+      std::cout << oss.str(); \
+    } \
+  } while( false )
+
 /**
  * @brief Log a message on screen on rank 0.
  * @param msg a message to log (any expression that can be stream inserted)
@@ -456,20 +471,23 @@
  * @brief Output messages based on current Group's log level.
  * @param[in] minLevel minimum log level
  * @param[in] msg a message to log (any expression that can be stream inserted)
+ * @deprecated Will be replaced by GEOS_LOG_LEVEL_INFO
  */
 #define GEOS_LOG_LEVEL( minLevel, msg ) GEOS_LOG_IF( this->getLogLevel() >= minLevel, msg );
 
 /**
  * @brief Output messages (only on rank 0) based on current Group's log level.
  * @param[in] minLevel minimum log level
  * @param[in] msg a message to log (any expression that can be stream inserted)
+ * @deprecated Will be replaced by GEOS_LOG_LEVEL_INFO_RANK_0
  */
 #define GEOS_LOG_LEVEL_RANK_0( minLevel, msg ) GEOS_LOG_RANK_0_IF( this->getLogLevel() >= minLevel, msg )
 
 /**
  * @brief Output messages (with one line per rank) based on current Group's log level.
  * @param[in] minLevel minimum log level
  * @param[in] msg a message to log (any expression that can be stream inserted)
+ * @deprecated Will be replaced by GEOS_LOG_LEVEL_INFO_BY_RANK
  */
 #define GEOS_LOG_LEVEL_BY_RANK( minLevel, msg ) GEOS_LOG_RANK_IF( this->getLogLevel() >= minLevel, msg )
 

src/coreComponents/dataRepository/CMakeLists.txt

@@ -11,6 +11,8 @@ set( dataRepository_headers
      InputFlags.hpp
      KeyIndexT.hpp
      KeyNames.hpp
+     LogLevelsInfo.hpp
+     LogLevelsRegistry.hpp
      MappedVector.hpp
      ObjectCatalog.hpp
      ReferenceWrapper.hpp
@@ -35,6 +37,7 @@ set( dataRepository_sources
      xmlWrapper.cpp
      DataContext.cpp
      GroupContext.cpp
+     LogLevelsRegistry.cpp
      WrapperContext.cpp )
 
 set( dependencyList ${parallelDeps} codingUtilities )

src/coreComponents/dataRepository/Group.cpp

@@ -50,6 +50,7 @@ Group::Group( string const & name,
   m_restart_flags( RestartFlags::WRITE_AND_READ ),
   m_input_flags( InputFlags::INVALID ),
   m_conduitNode( rootNode[ name ] ),
+  m_logLevelsRegistry( std::make_unique< LogLevelsRegistry >() ),
   m_dataContext( std::make_unique< GroupContext >( *this ) )
 {}
 
@@ -80,7 +81,6 @@ void Group::deregisterWrapper( string const & name )
   m_conduitNode.remove( name );
 }
 
-
 void Group::resize( indexType const newSize )
 {
   forWrappers( [newSize] ( WrapperBase & wrapper )
@@ -245,6 +245,7 @@ void Group::processInputFile( xmlWrapper::xmlNode const & targetNode,
 
 void Group::postInputInitializationRecursive()
 {
+  m_logLevelsRegistry = nullptr;
   for( auto const & subGroupIter : m_subGroups )
   {
     subGroupIter.second->postInputInitializationRecursive();

src/coreComponents/dataRepository/Group.hpp

@@ -27,6 +27,8 @@
 #include "RestartFlags.hpp"
 #include "Wrapper.hpp"
 #include "xmlWrapper.hpp"
+#include "LogLevelsInfo.hpp"
+#include "LogLevelsRegistry.hpp"
 
 
 #include <iostream>
@@ -863,6 +865,16 @@ class Group
   ///@}
   //END_SPHINX_INCLUDE_REGISTER_WRAPPER
 
+  /**
+   * @brief Append a levelCondition and a log description to the description of the wrapped object given a log info struct.
+   * Must be called in constructor.
+   * @tparam LOG_LEVEL_INFO The log documentation to add.
+   * @return void if the trait is verified.
+   */
+  template< typename LOG_LEVEL_INFO >
+  std::enable_if_t< geos::is_log_level_info< LOG_LEVEL_INFO >, void >
+  addLogLevel();
+
   /**
    * @name Schema generation methods
    */
@@ -1478,7 +1490,9 @@ class Group
    */
   void loadFromConduit();
 
-  /// Enable verbosity input for object
+  /**
+   * @deprecated will be remove and replace by addLogLevel
+   */
   void enableLogLevelInput();
 
   /**
@@ -1615,6 +1629,8 @@ class Group
 
   /// Verbosity flag for group logs
   integer m_logLevel;
+
+
   //END_SPHINX_INCLUDE_02
 
   /// Restart flag for this group... and subsequently all wrappers in this group.
@@ -1626,6 +1642,9 @@ class Group
   /// Reference to the conduit::Node that mirrors this group
   conduit::Node & m_conduitNode;
 
+  // Keep track of log levels & descriptions
+  std::unique_ptr< LogLevelsRegistry > m_logLevelsRegistry;
+
   /// A DataContext object used to provide contextual information on this Group,
   /// if it is created from an input XML file, the line or offset in that file.
   std::unique_ptr< DataContext > m_dataContext;
@@ -1712,6 +1731,24 @@ Wrapper< T > & Group::registerWrapper( string const & name,
   return rval;
 }
 
+template< typename LOG_LEVEL_INFO >
+std::enable_if_t< geos::is_log_level_info< LOG_LEVEL_INFO >, void >
+Group::addLogLevel()
+{
+  GEOS_ERROR_IF( m_logLevelsRegistry == nullptr, "You cannot call addLogLevel after schema generation" );
+
+  Wrapper< integer > * wrapper = getWrapperPointer< integer >( viewKeyStruct::logLevelString() );
+  if( wrapper == nullptr )
+  {
+    wrapper = &registerWrapper( viewKeyStruct::logLevelString(), &m_logLevel );
+    wrapper->setApplyDefaultValue( 0 );
+    wrapper->setInputFlag( InputFlags::OPTIONAL );
+  }
+  m_logLevelsRegistry->addEntry( LOG_LEVEL_INFO::getMinLogLevel(),
+                                 LOG_LEVEL_INFO::getDescription() );
+  wrapper->setDescription( m_logLevelsRegistry->buildLogLevelDescription());
+}
+
 } /* end namespace dataRepository */
 } /* end namespace geos */
 

src/coreComponents/dataRepository/LogLevelsInfo.hpp

@@ -0,0 +1,90 @@
+/*
+ * ------------------------------------------------------------------------------------------------------------
+ * SPDX-License-Identifier: LGPL-2.1-only
+ *
+ * Copyright (c) 2018-2020 Lawrence Livermore National Security LLC
+ * Copyright (c) 2018-2020 The Board of Trustees of the Leland Stanford Junior University
+ * Copyright (c) 2018-2020 TotalEnergies
+ * Copyright (c) 2019-     GEOSX Contributors
+ * All rights reserved
+ *
+ * See top level LICENSE, COPYRIGHT, CONTRIBUTORS, NOTICE, and ACKNOWLEDGEMENTS files for details.
+ * ------------------------------------------------------------------------------------------------------------
+ */
+
+/**
+ * @file LogLevelsInfo.hpp
+ * This file contains log level information infrastructure and the mecanism to ensure LOG_LEVEL_INFO structure is valid
+ */
+#ifndef GEOS_COMMON_LOGLEVELSINFO_HPP
+#define GEOS_COMMON_LOGLEVELSINFO_HPP
+
+#include "common/DataTypes.hpp"
+#include "common/format/Format.hpp"
+
+namespace geos
+{
+
+/**
+ * @brief Trait used to check whether a LOG_LEVEL_INFO structure is valid.
+ * @tparam LOG_LEVEL_INFO The log level structure to check.
+ *
+ *  A log level structure must have this following
+ *  struct LogName
+ *  {
+ *    static constexpr int getMinLogLevel() { return 1; }
+ *    static constexpr std::string_view getDescription() { return "Log level description"; }
+ *  };
+ */
+template< typename LOG_LEVEL_INFO >
+static constexpr bool is_log_level_info =
+  std::is_same_v< integer, decltype(LOG_LEVEL_INFO::getMinLogLevel()) > &&
+  std::is_same_v< std::string_view, decltype(LOG_LEVEL_INFO::getDescription()) >;
+
+/**
+ * @brief Verify if a log level is active
+ * @tparam LOG_LEVEL_INFO The structure containing log level information.
+ * @param level Log level to be checked.
+ * @return `true` if the log level is active, `false` otherwise.
+ * @pre `LOG_LEVEL_INFO` must satisfy `logInfo::is_log_level_info`.
+ *
+ */
+template< typename LOG_LEVEL_INFO >
+std::enable_if_t< is_log_level_info< LOG_LEVEL_INFO >, bool >
+isLogLevelActive( integer level )
+{
+  return level >= LOG_LEVEL_INFO::getMinLogLevel();
+}
+
+/** ThOSE 3 macros would replace the ones in Logger.hpp  */
+/**
+ * @brief Output messages based on current Group's log level.
+ * @param[in] logInfoStruct Strut containing log level desscription
+ * @param[in] msg a message to log (any expression that can be stream inserted)
+ */
+#define GEOS_LOG_LEVEL_INFO( logInfoStruct, msg ) GEOS_LOG_IF( isLogLevelActive< logInfoStruct >( this->getLogLevel() ), msg );
+
+/**
+ * @brief Output messages (only on rank 0) based on current Group's log level.
+ * @param[in] logInfoStruct Strut containing log level desscription
+ * @param[in] msg a message to log (any expression that can be stream inserted)
+ */
+#define GEOS_LOG_LEVEL_INFO_RANK_0( logInfoStruct, msg ) GEOS_LOG_RANK_0_IF( isLogLevelActive< logInfoStruct >( this->getLogLevel() ), msg );
+
+/**
+ * @brief Output messages (with one line per rank) based on current Group's log level.
+ * @param[in] logInfoStruct Strut containing log level desscription
+ * @param[in] msg a message to log (any expression that can be stream inserted)
+ */
+#define GEOS_LOG_LEVEL_INFO_BY_RANK( logInfoStruct, msg ) GEOS_LOG_RANK_IF( isLogLevelActive< logInfoStruct >( this->getLogLevel() ), msg );
+
+/**
+ * @brief Output messages (only on rank 0) based on current Group's log level without the line return.
+ * @param[in] logInfoStruct Strut containing log level desscription
+ * @param[in] msg a message to log (any expression that can be stream inserted)
+ */
+#define GEOS_LOG_LEVEL_INFO_RANK_0_NLR( logInfoStruct, msg ) GEOS_LOG_RANK_0_IF_NLR( isLogLevelActive< logInfoStruct >( this->getLogLevel() ), msg );
+
+}
+
+#endif // GEOS_COMMON_LOGLEVELSINFO_HPP

src/coreComponents/dataRepository/LogLevelsRegistry.cpp

@@ -0,0 +1,43 @@
+/*
+ * ------------------------------------------------------------------------------------------------------------
+ * SPDX-License-Identifier: LGPL-2.1-only
+ *
+ * Copyright (c) 2018-2020 Lawrence Livermore National Security LLC
+ * Copyright (c) 2018-2020 The Board of Trustees of the Leland Stanford Junior University
+ * Copyright (c) 2018-2020 TotalEnergies
+ * Copyright (c) 2019-     GEOSX Contributors
+ * All rights reserved
+ *
+ * See top level LICENSE, COPYRIGHT, CONTRIBUTORS, NOTICE, and ACKNOWLEDGEMENTS files for details.
+ * ------------------------------------------------------------------------------------------------------------
+ */
+
+#include "LogLevelsRegistry.hpp"
+
+namespace geos
+{
+
+void LogLevelsRegistry::addEntry( integer condition, std::string_view description )
+{
+  m_logLevelsDescriptions[condition].push_back( string( description ) );
+}
+
+string LogLevelsRegistry::buildLogLevelDescription() const
+{
+  std::ostringstream description;
+  description << "Sets the level of information to write in the standard output (the console typically).\n"
+                 "Level 0 outputs no specific information for this solver. Higher levels require more outputs.";
+  for( auto const & [logLevel, logDescriptions] : m_logLevelsDescriptions )
+  {
+    description << GEOS_FMT( "\n{}\n", logLevel );
+    for( size_t idxDesc = 0; idxDesc < logDescriptions.size(); idxDesc++ )
+    {
+      description << " - " << logDescriptions[idxDesc];
+      if( idxDesc != logDescriptions.size() - 1 )
+        description << '\n';
+    }
+  }
+  return description.str();
+}
+
+}

src/coreComponents/dataRepository/LogLevelsRegistry.hpp

@@ -0,0 +1,60 @@
+/*
+ * ------------------------------------------------------------------------------------------------------------
+ * SPDX-License-Identifier: LGPL-2.1-only
+ *
+ * Copyright (c) 2018-2020 Lawrence Livermore National Security LLC
+ * Copyright (c) 2018-2020 The Board of Trustees of the Leland Stanford Junior University
+ * Copyright (c) 2018-2020 TotalEnergies
+ * Copyright (c) 2019-     GEOSX Contributors
+ * All rights reserved
+ *
+ * See top level LICENSE, COPYRIGHT, CONTRIBUTORS, NOTICE, and ACKNOWLEDGEMENTS files for details.
+ * ------------------------------------------------------------------------------------------------------------
+ */
+
+/**
+ * @file LogLevelsRegistry.hpp
+ */
+
+#ifndef GEOS_COMMON_LOGLEVELSREGISTRY_HPP
+#define GEOS_COMMON_LOGLEVELSREGISTRY_HPP
+
+#include "common/DataTypes.hpp"
+#include "common/format/Format.hpp"
+
+namespace geos
+{
+
+/**
+ * @brief Keep track of log level documention for a group
+ */
+class LogLevelsRegistry
+{
+public:
+
+  /**
+   * @brief Add a log description for a wrapper
+   * @param level The minimum log level
+   * @param description The description for the log level
+   */
+  void addEntry( integer level, std::string_view description );
+
+  /**
+   * @brief Construct the log level string description for a wrapper
+   * @return The log level string description
+   */
+  string buildLogLevelDescription() const;
+
+private:
+
+  /**
+   * @brief Map for building the log level string for each wrapper.
+   *        key : a logLevel condition, values : a set of description for a corresponding loglevel.
+   */
+  std::map< integer, std::vector< std::string > > m_logLevelsDescriptions;
+
+};
+
+}
+
+#endif

src/coreComponents/physicsSolvers/CMakeLists.txt

@@ -6,7 +6,8 @@ set( physicsSolvers_headers
      SolverBase.hpp
      SolverBaseKernels.hpp
      SolverStatistics.hpp
-     FieldStatisticsBase.hpp )
+     FieldStatisticsBase.hpp
+     LogLevelsInfo.hpp )
 
 # Specify solver sources
 set( physicsSolvers_sources