.. _exceptions-ref: ==================== Exceptions Reference ==================== Complete reference for NeurEco exceptions and error handling. .. contents:: On this page :local: :depth: 2 Import ====== .. code-block:: python from NeurEco import ( NeurEcoError, NeurEcoWarning, ModelNotReadyError, ModelOperationError, DataValidationError, ConfigurationError, ArrayShapeMismatchError, DataContainsNaNError, ) Exception Hierarchy =================== .. code-block:: text Exception `-- NeurEcoError (base for all NeurEco exceptions) |-- ModelNotReadyError |-- ModelOperationError |-- DataValidationError (also inherits ValueError) | |-- ArrayShapeMismatchError | `-- DataContainsNaNError |-- ConfigurationError (also inherits ValueError) |-- BinaryNotFoundError (also inherits FileNotFoundError) |-- BinDirectoryNotFoundError (also inherits FileNotFoundError) |-- UnsupportedOSError (also inherits OSError) `-- ApplyError UserWarning `-- NeurEcoWarning (base for all NeurEco warnings) |-- DeprecatedParameterWarning `-- DeprecatedMethodWarning Exception Reference =================== NeurEcoError ------------ .. code-block:: python class NeurEcoError(Exception) Base exception for all NeurEco errors. Catch this to handle any NeurEco-specific exception. .. code-block:: python try: model.build(config) except NeurEcoError as e: print(f"NeurEco error: {e}") ModelNotReadyError ------------------ .. code-block:: python class ModelNotReadyError(NeurEcoError) Raised when an operation requires a built or loaded model, but none exists. **Common causes:** - Calling ``evaluate()`` before ``build()`` or ``load()`` - Calling ``export_onnx()`` on an uninitialized model - Calling ``get_weights()`` before training **Example:** .. code-block:: python from NeurEco import NeurEcoTabular as tab, ModelNotReadyError model = tab.Regressor() try: predictions = model.evaluate(X) # Fails - no model loaded except ModelNotReadyError: print("Load or build a model first!") model.load("saved_model.ednn") predictions = model.evaluate(X) ModelOperationError ------------------- .. code-block:: python class ModelOperationError(NeurEcoError) Raised when a model operation (build, load, save, export) fails. **Common causes:** - Build failed due to data issues - File I/O errors during save/load - Export failed (missing license, invalid format) - Native library returned an error **Example:** .. code-block:: python from NeurEco import ModelOperationError try: model.export_fmu("model.fmu") except ModelOperationError as e: print(f"Export failed: {e}") # Check if you have the required license DataValidationError ------------------- .. code-block:: python class DataValidationError(NeurEcoError, ValueError) Raised when input data fails validation checks. **Common causes:** - Empty data arrays - Invalid data types - Data doesn't match expected format **Example:** .. code-block:: python from NeurEco import DataValidationError try: model.evaluate(invalid_data) except DataValidationError as e: print(f"Data validation failed: {e}") ArrayShapeMismatchError ----------------------- .. code-block:: python class ArrayShapeMismatchError(DataValidationError) Raised when array shapes don't match expected dimensions. **Common causes:** - Input has wrong number of features - Weights shape doesn't match model - Mismatch between input and output sample counts **Example:** .. code-block:: python from NeurEco import ArrayShapeMismatchError model.load("model.ednn") # Model expects 5 inputs try: X = np.random.randn(100, 3) # Only 3 features! model.evaluate(X) except ArrayShapeMismatchError as e: print(f"Shape error: {e}") # Fix: ensure X has 5 columns DataContainsNaNError -------------------- .. code-block:: python class DataContainsNaNError(DataValidationError) Raised when data contains NaN (Not a Number) values. **Common causes:** - Missing values in input data - Division by zero in preprocessing - Corrupted data files **Example:** .. code-block:: python from NeurEco import DataContainsNaNError import numpy as np X = np.array([[1.0, np.nan], [3.0, 4.0]]) # Contains NaN! try: model.evaluate(X) except DataContainsNaNError: print("Data contains NaN values!") # Fix: clean your data X = np.nan_to_num(X) # Replace NaN with 0 # or mask = ~np.isnan(X).any(axis=1) X_clean = X[mask] ConfigurationError ------------------ .. code-block:: python class ConfigurationError(NeurEcoError, ValueError) Raised when configuration parameters are invalid. **Common causes:** - Invalid parameter values (e.g., negative percentage) - Missing required parameters - Incompatible parameter combinations - Invalid file paths in configuration **Example:** .. code-block:: python from NeurEco import ConfigurationError try: config = tab.RegressorBuildConfig( input_data=X, output_data=Y, valid_percentage=75 # Invalid! Max is 50 ) except ConfigurationError as e: print(f"Configuration error: {e}") BinaryNotFoundError ------------------- .. code-block:: python class BinaryNotFoundError(NeurEcoError, FileNotFoundError) Raised when a NeurEco binary file (DLL/SO) cannot be found. **Common causes:** - NeurEco not properly installed - Binary directory not in path - Missing platform-specific binaries **Example:** .. code-block:: python from NeurEco.utils import BinaryNotFoundError try: model = tab.Regressor() except BinaryNotFoundError: print("NeurEco binaries not found!") print("Check your installation or pass dll_path, the folder of the NeurEco libraries") UnsupportedOSError ------------------ .. code-block:: python class UnsupportedOSError(NeurEcoError, OSError) Raised when running on an unsupported operating system. **Supported platforms:** - Windows - Linux Warning Reference ================= NeurEcoWarning -------------- .. code-block:: python class NeurEcoWarning(UserWarning) Base warning for all NeurEco warnings. DeprecatedMethodWarning ----------------------- .. code-block:: python class DeprecatedMethodWarning(NeurEcoWarning) Issued when using deprecated methods that will be removed in future versions. **Example:** .. code-block:: python import warnings # Show all NeurEco warnings warnings.filterwarnings("always", category=NeurEcoWarning) # Or suppress deprecation warnings warnings.filterwarnings("ignore", category=DeprecatedMethodWarning) DeprecatedParameterWarning -------------------------- .. code-block:: python class DeprecatedParameterWarning(NeurEcoWarning) Issued when using deprecated parameters. Error Handling Best Practices ============================= Basic Error Handling -------------------- .. code-block:: python from NeurEco import NeurEcoTabular as tab from NeurEco import ( ModelNotReadyError, DataValidationError, ConfigurationError, ) def train_model(X, Y, output_path): model = tab.Regressor() try: config = tab.RegressorBuildConfig( input_data=X, output_data=Y, write_model_to=output_path, ) model.build(config) return model except ConfigurationError as e: print(f"Invalid configuration: {e}") raise except DataValidationError as e: print(f"Data validation failed: {e}") raise finally: # Ensure cleanup on error if not model.vec_updated: model.delete() Catching All NeurEco Errors --------------------------- .. code-block:: python from NeurEco import NeurEcoError try: # Any NeurEco operation model.build(config) predictions = model.evaluate(X_test) model.export_onnx("model.onnx") except NeurEcoError as e: print(f"NeurEco error occurred: {type(e).__name__}: {e}") Data Validation Before Training ------------------------------- .. code-block:: python import numpy as np def validate_data(X, Y): """Validate data before passing to NeurEco.""" # Check for NaN if np.any(np.isnan(X)): raise ValueError("Input contains NaN values") if np.any(np.isnan(Y)): raise ValueError("Output contains NaN values") # Check shapes if len(X.shape) != 2: raise ValueError(f"Input must be 2D, got {len(X.shape)}D") if len(Y.shape) != 2: raise ValueError(f"Output must be 2D, got {len(Y.shape)}D") # Check sample count match if X.shape[0] != Y.shape[0]: raise ValueError( f"Sample count mismatch: X has {X.shape[0]}, Y has {Y.shape[0]}" ) return True # Use before training validate_data(X_train, Y_train) model.build(config)