oomph_definitions.h

Go to the documentation of this file.

// LIC// ====================================================================
// LIC// This file forms part of oomph-lib, the object-oriented,
// LIC// multi-physics finite-element library, available
// LIC// at http://www.oomph-lib.org.
// LIC//
// LIC// Copyright (C) 2006-2026 Matthias Heil and Andrew Hazel
// LIC//
// LIC// This library is free software; you can redistribute it and/or
// LIC// modify it under the terms of the GNU Lesser General Public
// LIC// License as published by the Free Software Foundation; either
// LIC// version 2.1 of the License, or (at your option) any later version.
// LIC//
// LIC// This library is distributed in the hope that it will be useful,
// LIC// but WITHOUT ANY WARRANTY; without even the implied warranty of
// LIC// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
// LIC// Lesser General Public License for more details.
// LIC//
// LIC// You should have received a copy of the GNU Lesser General Public
// LIC// License along with this library; if not, write to the Free Software
// LIC// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
// LIC// 02110-1301  USA.
// LIC//
// LIC// The authors may be contacted at oomph-lib@maths.man.ac.uk.
// LIC//
// LIC//====================================================================
// A header containing the definition of the Oomph run-time
// exception classes and our standard (info) output stream
//(essentially a wrapper to cout but it can be customised,
// e.g. for mpi runs.
 
// Include guard to prevent multiple inclusions of the header
#ifndef OOMPH_DEFINITIONS_HEADER
#define OOMPH_DEFINITIONS_HEADER
 
// Config header
#ifdef HAVE_CONFIG_H
#include <oomph-lib-config.h>
#endif
 
// Standard libray headers
#include <stdexcept>
#include <iostream>
#include <string>
#include <vector>
 
 
namespace oomph
{
// Pre-processor magic for error reporting
// Macro that converts argument to string
#define OOMPH_MAKE_STRING(x) #x
 
// Macro wrapper to MAKE_STRING, required because calling
// OOMPH_MAKE_STRING(__LINE__) directly returns __LINE__
// i.e. the conversion of __LINE__ into a number must be performed before
// its conversion into a string
#define OOMPH_TO_STRING(x) OOMPH_MAKE_STRING(x)
 
// Combine the FILE and LINE built-in macros into a string that can
// be used in erorr messages.
#define OOMPH_EXCEPTION_LOCATION __FILE__ ":" OOMPH_TO_STRING(__LINE__)
 
// Get the current function name. All the mess is due to different
// compilers naming the macro we need differently.
#if defined(__GNUC__) || (defined(__MWERKS__) && (__MWERKS__ >= 0x3000)) || \
  (defined(__ICC) && (__ICC >= 600)) || defined(__ghs__)
#define OOMPH_CURRENT_FUNCTION __PRETTY_FUNCTION__
 
#elif defined(__DMC__) && (__DMC__ >= 0x810)
#define OOMPH_CURRENT_FUNCTION __PRETTY_FUNCTION__
 
#elif defined(__FUNCSIG__)
#define OOMPH_CURRENT_FUNCTION __FUNCSIG__
 
#elif (defined(__INTEL_COMPILER) && (__INTEL_COMPILER >= 600)) || \
  (defined(__IBMCPP__) && (__IBMCPP__ >= 500))
#define OOMPH_CURRENT_FUNCTION __FUNCTION__
 
#elif defined(__BORLANDC__) && (__BORLANDC__ >= 0x550)
#define OOMPH_CURRENT_FUNCTION __FUNC__
 
#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901)
#define OOMPH_CURRENT_FUNCTION __func__
 
#else
#define OOMPH_CURRENT_FUNCTION "[Unknown function -- unrecognised compiler]"
 
#endif
 
// Helper macro to throw an oomph-lib error
#define OOMPH_ERROR(msg) \
  throw OomphLibError(msg, OOMPH_CURRENT_FUNCTION, OOMPH_EXCEPTION_LOCATION);
 
// Helper macro to provide an oomph-lib warning
#define OOMPH_WARNING(msg) \
  OomphLibWarning(msg, OOMPH_CURRENT_FUNCTION, OOMPH_EXCEPTION_LOCATION);
 
 
  //==================================================================
  /// Compile-time test to determine if a type T has a notion of
  /// "magnitude", i.e. if std::abs(T) is a valid expression.
  ///
  /// The primary template defaults to "false".
  ///
  /// A partial specialisation (below) is selected automatically via
  /// SFINAE ("Substitution Failure Is Not An Error") if the expression
  ///
  ///   std::abs(std::declval<T>())
  ///
  /// is valid. In that case HasMagnitude<T>::value evaluates to true.
  ///
  /// This facility is used to prevent compilation failures in generic
  /// code where operations involving std::abs() only make sense for
  /// numerical types.
  ///
  /// Example:
  ///   HasMagnitude<double>::value            -> true
  ///   HasMagnitude<std::complex<double>>::value -> true
  ///   HasMagnitude<Vector<double>>::value    -> false
  //==================================================================
  template<class T, class = void>
  struct HasMagnitude : std::false_type
  {
  };
 
 
  //==================================================================
  /// Partial specialisation of HasMagnitude<T> which is selected
  /// when std::abs(T) is a valid expression. In that case
  /// HasMagnitude<T>::value is true.
  /// std::declval<T>() creates a fictitious object of type T for use in
  /// unevaluated expressions (decltype in this case) without requiring
  /// construction of an actual object.
  ///
  /// Example:
  ///   HasMagnitude<double>::value            -> true
  ///   HasMagnitude<std::complex<double>>::value -> true
  ///   HasMagnitude<Vector<double>>::value    -> false
  //==================================================================
  template<class T>
  struct HasMagnitude<T, std::void_t<decltype(std::abs(std::declval<T>()))>>
    : std::true_type
  {
  };
 
 
  ///////////////////////////////////////////////////////////////////////
  ///////////////////////////////////////////////////////////////////////
  ///////////////////////////////////////////////////////////////////////
 
 
  /// =====================================================================
  /// Namespace to control level of comprehensive timings
  //======================================================================
  namespace Global_timings
  {
    /// Global boolean to switch on comprehensive timing -- can
    /// probably be declared const false when development on hector
    /// is complete
    extern bool Doc_comprehensive_timings;
 
  }; // namespace Global_timings
 
 
  /////////////////////////////////////////////////////////////////////
  /////////////////////////////////////////////////////////////////////
  /////////////////////////////////////////////////////////////////////
 
  //=======================================================================
  /// Helper namespace for set_terminate function -- used to spawn
  /// messages from uncaught errors (their destructor may not be called)
  /// =======================================================================
  namespace TerminateHelper
  {
    /// Setup terminate helper
    extern void setup();
 
    /// Suppress error messages (e.g. because error has been caught)
    extern void suppress_exception_error_messages();
 
    /// Function to spawn messages from uncaught errors
    extern void spawn_errors_from_uncaught_errors();
 
    /// Clean up function that deletes anything dynamically allocated
    /// in this namespace
    extern void clean_up_memory();
 
    /// Stream to output error messages
    extern std::ostream* Error_message_stream_pt;
 
    /// String stream that records the error message
    extern std::stringstream* Exception_stringstream_pt;
 
  } // namespace TerminateHelper
 
  ///////////////////////////////////////////////////////////////////////
  ///////////////////////////////////////////////////////////////////////
  ///////////////////////////////////////////////////////////////////////
 
 
  /// =====================================================================
  /// A class for handling oomph-lib run-time exceptions quietly.
  //======================================================================
  class OomphLibQuietException : public std::runtime_error
  {
  public:
    /// Constructor
    OomphLibQuietException();
 
    /// The destructor cannot throw an exception (C++ STL standard)
    ~OomphLibQuietException() throw() {}
  };
 
  ///////////////////////////////////////////////////////////////////////
  ///////////////////////////////////////////////////////////////////////
  ///////////////////////////////////////////////////////////////////////
 
 
  /// =====================================================================
  /// A Base class for oomph-lib run-time exception (error and warning)
  /// handling.
  ///
  /// The class can only be instantiated by the derived classes
  /// OomphLibError and OomphLibWarning. The (protected) constructor
  /// combines its string arguments into a standard format
  /// for uniform exception reports which are written to the specified
  /// output stream.
  //======================================================================
  class OomphLibException : public std::runtime_error
  {
  public:
    /// Suppress issueing of the error message in destructor
    /// (useful if error is caught successfully!)
    void disable_error_message()
    {
      // Suppress output of message in destructor...
      Suppress_error_message = true;
 
      // ...and in the big cleanup operation at the end
      TerminateHelper::suppress_exception_error_messages();
    }
 
  protected:
    /// Constructor takes the error description, function name
    /// and a location string provided by the OOMPH_EXCEPTION_LOCATION
    /// macro and combines them into a standard header. The exception type
    /// will be the string "WARNING" or "ERROR" and the message is written to
    /// the exception_stream, with a specified output_width. Optionally
    /// provide a traceback of the function calls.
    OomphLibException(const std::string& error_description,
                      const std::string& function_name,
                      const char* location,
                      const std::string& exception_type,
                      std::ostream& exception_stream,
                      const unsigned& output_width,
                      bool list_trace_back);
 
    /// The destructor cannot throw an exception (C++ STL standard)
    ~OomphLibException() throw();
 
    /// Exception stream to which we write message in destructor
    std::ostream* Exception_stream_pt;
 
    /// String stream that records the error message
    std::stringstream* Exception_stringstream_pt;
 
    /// Boolean to suppress issuing of the error message in destructor
    /// (useful if error is caught successfully!)
    bool Suppress_error_message;
  };
 
  //====================================================================
  /// An OomphLibError object which should be thrown when an run-time
  /// error is encountered. The error stream and stream width can be
  /// specified. The default is cerr with a width of 70 characters.
  //====================================================================
  class OomphLibError : public OomphLibException
  {
    /// Output stream that is used to write the errors
    static std::ostream* Stream_pt;
 
    /// Width in characters of the output report
    static unsigned Output_width;
 
  public:
    /// Constructor requires the error description and the function
    /// in which the error occured and the location provided by the
    /// OOMPH_EXCEPTION_LOCATION macro
    OomphLibError(const std::string& error_description,
                  const std::string& function_name,
                  const char* location)
      : OomphLibException(error_description,
                          function_name,
                          location,
                          "ERROR",
                          *Stream_pt,
                          Output_width,
                          true)
    {
    }
 
    /// Static member function used to specify the error stream,
    /// which must be passed as a pointer because streams cannot be copied.
    static inline void set_stream_pt(std::ostream* const& stream_pt)
    {
      Stream_pt = stream_pt;
    }
 
    /// Static member function used to specify the width (in characters)
    /// of the error stream
    static inline void set_output_width(const unsigned& output_width)
    {
      Output_width = output_width;
    }
  };
 
  //====================================================================
  /// An OomphLibWarning object which should be created as a temporary
  /// object to issue a warning. The warning stream and stream width can be
  /// specified. The default is cerr with a width of 70 characters.
  //====================================================================
  class OomphLibWarning : public OomphLibException
  {
    /// Output stream that is used to write the errors
    static std::ostream* Stream_pt;
 
    /// Width of output
    static unsigned Output_width;
 
  public:
    /// Constructor requires the warning description and the function
    /// in which the warning occurred.
    OomphLibWarning(const std::string& warning_description,
                    const std::string& function_name,
                    const char* location)
      : OomphLibException(warning_description,
                          function_name,
                          location,
                          "WARNING",
                          *Stream_pt,
                          Output_width,
                          false)
    {
    }
 
    /// Static member function used to specify the error stream,
    /// which must be passed as a pointer because streams cannot be copied.
    static inline void set_stream_pt(std::ostream* const& stream_pt)
    {
      Stream_pt = stream_pt;
    }
 
    /// Static member function used to specify the width (in characters)
    /// of the error stream
    static inline void set_output_width(const unsigned& output_width)
    {
      Output_width = output_width;
    }
  };
 
 
  ////////////////////////////////////////////////////////////////////////
  ////////////////////////////////////////////////////////////////////////
  ////////////////////////////////////////////////////////////////////////
 
 
  //=====================================================================
  /// A small nullstream class that throws away everything sent to it.
  //=====================================================================
  class Nullstream : public std::ostream
  {
  public:
    /// Constructor sets the buffer sizes to zero, suppressing all output
    Nullstream() : std::ios(0), std::ostream(0) {}
  };
 
 
  //========================================================================
  /// Single (global) instantiation of the Nullstream
  //========================================================================
  extern Nullstream oomph_nullstream;
 
 
  ////////////////////////////////////////////////////////////////////////
  ////////////////////////////////////////////////////////////////////////
  ////////////////////////////////////////////////////////////////////////
 
 
  //========================================================================
  /// A base class that contains a single virtual member function:
  /// The () operator that may be used to modify the output in
  /// OomphOutput objects. The default implementation
  /// =======================================================================
  class OutputModifier
  {
  public:
    /// Empty constructor
    OutputModifier() {}
 
    /// Empty virtual destructor
    virtual ~OutputModifier() {}
 
    /// Function that will be called before output from an
    /// OomphOutput object. It returns a bool (true in this default
    /// implementation) to indicate that output should be continued.
    virtual bool operator()(std::ostream& stream)
    {
      return true;
    }
  };
 
 
  //========================================================================
  /// Single global instatiation of the default output modifier.
  //========================================================================
  extern OutputModifier default_output_modifier;
 
 
  ////////////////////////////////////////////////////////////////////////
  ////////////////////////////////////////////////////////////////////////
  ////////////////////////////////////////////////////////////////////////
 
 
  //=======================================================================
  /// Namespace containing an output stream that can be used for
  /// debugging. Use at your own risk -- global data is evil!
  //=======================================================================
  namespace Global_output_stream
  {
    /// Output stream
    extern std::ofstream* Outfile;
 
  } // namespace Global_output_stream
 
 
  ////////////////////////////////////////////////////////////////////////
  ////////////////////////////////////////////////////////////////////////
  ////////////////////////////////////////////////////////////////////////
 
 
  //=======================================================================
  /// Namespace containing a number that can be used to annotate things for
  /// debugging. Use at your own risk -- global data is evil!
  //=======================================================================
  namespace Global_unsigned
  {
    /// The unsigned
    extern unsigned Number;
 
  } // namespace Global_unsigned
 
 
  ////////////////////////////////////////////////////////////////////////
  ////////////////////////////////////////////////////////////////////////
  ////////////////////////////////////////////////////////////////////////
 
 
  //=======================================================================
  /// Namespace containing a vector of strings that can be used to
  /// to store global output modifiers. This is global data
  /// and you use it at your own risk!
  //=======================================================================
  namespace Global_string_for_annotation
  {
    /// Return the i-th string or "" if the relevant string hasn't
    /// been defined
    extern std::string string(const unsigned& i);
 
    /// Storage for strings that may be used for global annotations.
    /// This is global data and you use it at your own risk!
    extern std::vector<std::string> String;
  } // namespace Global_string_for_annotation
 
 
  ////////////////////////////////////////////////////////////////////////
  ////////////////////////////////////////////////////////////////////////
  ////////////////////////////////////////////////////////////////////////
 
 
  //=======================================================================
  /// This class is a wrapper to a stream and an output modifier that is
  /// used to control the "info" output from OomphLib. Its instationiation
  /// can be used like std::cout.
  //=======================================================================
  class OomphInfo
  {
  private:
    /// Pointer to the output stream -- defaults to std::cout
    std::ostream* Stream_pt;
 
    /// Pointer to the output modifier object -- defaults to no modification
    OutputModifier* Output_modifier_pt;
 
  public:
    /// Set default values for the output stream (cout)
    /// and modifier (no modification)
    OomphInfo()
      : Stream_pt(&std::cout), Output_modifier_pt(&default_output_modifier)
    {
    }
 
    /// Overload the << operator, writing output to the stream addressed
    /// by Stream_pt and calling the function defined by the object addressed by
    /// Output_modifier_pt
    template<class _Tp>
    std::ostream& operator<<(_Tp argument)
    {
      // If the Output_modifer function returns true
      // echo the argument to the stream and return the (vanilla) stream
      if ((*Output_modifier_pt)(*Stream_pt))
      {
        *Stream_pt << argument;
        return (*Stream_pt);
      }
      // Otherwise return the null stream (suppress all future output)
      return oomph_nullstream;
    }
 
    /// Access function for the stream pointer
    std::ostream*& stream_pt()
    {
      return Stream_pt;
    }
 
    /// Overload insertor to handle stream modifiers
    std::ostream& operator<<(std::ostream& (*f)(std::ostream&))
    {
      return f(*Stream_pt);
    }
 
    /// Access function for the output modifier pointer
    OutputModifier*& output_modifier_pt()
    {
      return Output_modifier_pt;
    }
  };
 
 
  //========================================================================
  /// Single (global) instantiation of the OomphInfo object -- this
  /// is used throughout the library as a "replacement" for std::cout
  //========================================================================
  extern OomphInfo oomph_info;
 
 
} // namespace oomph
 
#endif