Classify all error messages as WARN, ERR, or CRIT in error.hpp

[davidfillmore]

Is your feature request related to a problem? Please describe.
Currently, error messages in include/micm/util/error.hpp do not explicitly classify the severity of errors. This makes it harder to distinguish between warnings, errors, and critical failures for both developers and users relying on error logging.

Describe the solution you'd like
Update the error handling mechanism (and related message formatting) so that every error message includes a classification: WARN, ERR, or CRIT. This could be implemented as an enum or tagged string, and should be clearly visible in all error outputs, logs, or exceptions.

Describe alternatives you've considered

• Use only two levels of error (warning/error), but this does not allow for differentiation of critical failures.
• Rely on message text to infer severity, but this is less reliable and harder to automate.

Additional context
This change will improve debugging and automated error analysis. Please see include/micm/util/error.hpp for the current error message implementation.

[K20shores]

Additionally, generating this errors requires us to inject some templates into the standard library. Maybe we should consider refactoring how we generate these errors so we can remove this

micm/include/micm/process/process_error.hpp

Lines 10 to 25 in 37cb894

	enum class MicmProcessErrc
	{
	ReactantDoesNotExist = MICM_PROCESS_ERROR_CODE_REACTANT_DOES_NOT_EXIST,
	ProductDoesNotExist = MICM_PROCESS_ERROR_CODE_PRODUCT_DOES_NOT_EXIST,
	RateConstantIsNotSet = MICM_PROCESS_ERROR_CODE_RATE_CONSTANT_IS_NOT_SET,
	TransferCoefficientIsNotSet = MICM_PROCESS_ERROR_CODE_TRANSFER_COEFFICIENT_IS_NOT_SET,
	SurfaceReactionRequiresSingleReactant = MICM_PROCESS_ERROR_CODE_TOO_MANY_REACTANTS_FOR_SURFACE_REACTION,
	};
	namespace std
	{
	template<>
	struct is_error_code_enum<MicmProcessErrc> : true_type
	{
	};
	} // namespace std

[K20shores]

Copilot suggests something like this for errors. We would be able to drop the weird stuff we do that injects error messages into the standard library, but we lose the error code/category aspect. I'm going to keep reading and thinking, but something like this could work.

throw micm::MicmError::Error(micm::ErrorCategory::Species, micm::ErrorCode::PropertyNotFound, 
                            "Species: '" + name_ + "' Property: '" + key + "'");

throw micm::MicmError::Critical(micm::ErrorCategory::JIT, micm::ErrorCode::FailedToBuild, 
                               "JIT compilation failed");

throw micm::MicmError::Internal("Unexpected null pointer", __FILE__, __LINE__);

#pragma once
#include <stdexcept>
#include <string>

namespace micm {

enum class ErrorSeverity {
  WARN,  // Non-fatal issues that can be handled
  ERR,   // Errors that prevent normal operation
  CRIT   // Critical errors that require immediate termination
};

enum class ErrorCategory {
  Configuration,
  JIT,
  Process,
  RateConstant,
  Species,
  Matrix,
  State,
  Solver,
  Internal
};

enum class ErrorCode {
  // Configuration errors
  InvalidKey = 1,
  UnknownKey = 2,
  InvalidFilePath = 3,
  NoConfigFilesFound = 4,
  
  // JIT errors  
  InvalidMatrix = 101,
  MissingJitFunction = 102,
  FailedToBuild = 103,
  
  // Process errors
  ReactantDoesNotExist = 201,
  ProductDoesNotExist = 202,
  RateConstantNotSet = 203,
  
  // Matrix errors
  RowSizeMismatch = 301,
  ElementOutOfRange = 302,
  
  // Species errors
  PropertyNotFound = 401,
  InvalidTypeForProperty = 402,
  
  // State errors
  UnknownSpecies = 501,
  UnknownRateConstantParameter = 502,
  
  // Solver errors
  UnusedSpecies = 601,
  MissingChemicalSystem = 602,
  
  // Internal errors
  GeneralInternal = 701,
  CudaError = 702,
  CublasError = 703
};

class MicmError : public std::runtime_error {
public:
  MicmError(ErrorSeverity severity, ErrorCategory category, ErrorCode code, const std::string& message)
    : std::runtime_error(FormatMessage(severity, category, code, message)),
      severity_(severity), category_(category), code_(code), user_message_(message) {}

  ErrorSeverity severity() const { return severity_; }
  ErrorCategory category() const { return category_; }
  ErrorCode code() const { return code_; }
  const std::string& user_message() const { return user_message_; }

  // Static factory functions instead of macros
  static MicmError Warn(ErrorCategory category, ErrorCode code, const std::string& message) {
    return MicmError(ErrorSeverity::WARN, category, code, message);
  }

  static MicmError Error(ErrorCategory category, ErrorCode code, const std::string& message) {
    return MicmError(ErrorSeverity::ERR, category, code, message);
  }

  static MicmError Critical(ErrorCategory category, ErrorCode code, const std::string& message) {
    return MicmError(ErrorSeverity::CRIT, category, code, message);
  }

  // Special helper for internal errors with file/line info
  static MicmError Internal(const std::string& message, const char* file, int line) {
    std::string detailed_message = "Please file a bug report at https://github.com/NCAR/micm. Error detail: (" + 
                                  std::string(file) + ":" + std::to_string(line) + ") " + message;
    return MicmError(ErrorSeverity::CRIT, ErrorCategory::Internal, ErrorCode::GeneralInternal, detailed_message);
  }

private:
  ErrorSeverity severity_;
  ErrorCategory category_;
  ErrorCode code_;
  std::string user_message_;

  static std::string FormatMessage(ErrorSeverity severity, ErrorCategory category, 
                                 ErrorCode code, const std::string& message);
};

} // namespace micm

[K20shores]

As far as excpetions, there are very vew that fit into things that are warnings that we can continue on. The first that comes to mind are MICM_SOLVER_ERROR_CODE_UNUSED_SPECIES and MICM_SOLVER_ERROR_CODE_INVALID_TOLERANCE_SIZE. The first won't affect solving, it only adds extra memory. The second one we could just use a sensible default. However, right now we throw them as errors, but there's no way to continue on. If we want to have these as warnings, there needs to be a way to continue configuration but still somehow throw these? Perhaps we need a more c-like error system where there's a way to get a last error code. The problem then is threading...

[K20shores]

Also, doing something like fully removing our error codes and categories will break the integration with fortran since our error file is #included in our fortran interface. Definitely something we can work around. Another option

1. Remove all throwing of exceptions within micm
2. Every function that could error has a return code
   • maybe combined with the use of std::expected
   • would allow us to return something like a code, category, and message struct
   • I guess a problem with std::expected is really that some exceptions are recoverable and we still need to return an object. So its almost like we need a way to indicate an error happened without actually returning an error
3. Each error code would still correspond to something in error.hpp, and maybe that wouldn't even need to change
4. All downstream code would need to adapt to check the return types, but our c-fortran interfaces might not end up needing to change

[K20shores]

Maybe it's best to list the requirements we have on errors

1. Identifiable

• I guess, after a grep we could find out where the error might have happened
• Maybe even including line and file. not required

2. Classifiable - Can be identified as WARN, ERR, or CRIT

• We don't need to do this identification in micm necessarily, since these are MPAS categories.

3. Easily translated to other languages, like python, fortran, javascript, through the interfaces in musica. This is already doable now, but we don't have a way to classify the errors that we have.
4. Termination of the application is left up to whatever alls micm, or, std::terminate should never be called by micm. std::terminate is called on an uncaught exception, so any library using micm must be able to catch all exceptions so that it may call std::terminate, or in case of models in fortran, error states can be reported to fortan and the host model can figure out if execution needs to be halted or not

[K20shores]

Another point, it's possible that we are mixing two things:

1. Errors
2. Logging

If we are just being asked to classify errors so that log messages can be properly written, maybe what we need to do is come up with a design that allows you to pass in an error code, and get back a message and a category. At the same time, we can ensure that anything that is an error but still allows us to run (like species that exist but aren't in a reaciton) does not throw an exception, but gets written into a log file. That would mean we need to have some logging interface that by default goes to stdout, stderr, but can be overriden so that something like the musica library can configure micm to write directly into the mpas logs, or cam-sima, or whatever

[K20shores]

To that point,

1. Throw exceptions for anything that truly isn't recoverable. Libraries that use micm (meaning musica) will catch and report as approriate for whatever model it is being used int
2. Anything that is unusual but still leaves us in runnable state gets written to something (log file, stdout, whatever), so long as whatever we choose can be override in some way by musica to redirect appropriatley

[K20shores]

• Great talk on c++ excpetions
• And all exceptions described in that talk were implemented here