.. _python-api-overview: =================== Python API Overview =================== This page provides an overview of the NeurEco Python API, including installation, imports, and common usage patterns. .. contents:: On this page :local: :depth: 2 Installation ============ The Python library is the ``neureco`` package. It does not need the desktop app. Its editions are hosted by Adagos under ``https://adagos.com/downloads/neureco5/whl/``, one package index per edition, and pip installs them with ``--extra-index-url``, together with PyTorch from the PyTorch package index. For example, the CPU-only edition (PyTorch 2.9): .. code-block:: bash pip install "neureco~=5.0" --extra-index-url https://download.pytorch.org/whl/cpu --extra-index-url https://adagos.com/downloads/neureco5/whl/cpu/ See :ref:`installation` for the requirements and the commands of the NVIDIA GPU editions. If you do not have a license yet, create the license request file ``hardware_info.txt`` with ``python -m NeurEco.hardware_info`` (see :ref:`licensing`). Verify Installation ------------------- .. code-block:: python from NeurEco import NeurEcoTabular as tab model = tab.Regressor() print(model.__version__()) Module Structure ================ NeurEco organizes its API into solution-specific submodules: .. code-block:: python from NeurEco import NeurEcoTabular # Tabular models (Regression, Classification, Compression) from NeurEco import NeurEcoDynamic # Dynamic models (ODE, Convolutional Dynamic) from NeurEco import NeurEcoFrequential # Frequency domain models (PFS) Recommended Import Aliases -------------------------- .. code-block:: python from NeurEco import NeurEcoTabular as tab from NeurEco import NeurEcoDynamic as dyn from NeurEco import NeurEcoFrequential as freq Available Classes ================= Tabular Solution ---------------- .. code-block:: python from NeurEco import NeurEcoTabular as tab # Model classes tab.Regressor # Regression models tab.Classifier # Classification models tab.Compressor # Dimensionality reduction (autoencoder) # Configuration classes tab.RegressorBuildConfig tab.ClassifierBuildConfig tab.CompressorBuildConfig Dynamic Solution ---------------- .. code-block:: python from NeurEco import NeurEcoDynamic as dyn # Model classes dyn.ODE # ODE-based time series models dyn.ConvolutiveDynamic # Sliding window models # Configuration classes dyn.ODEBuildConfig dyn.ConvolutiveDynamicBuildConfig PFS Solution ------------ .. code-block:: python from NeurEco import NeurEcoFrequential as freq # Model class freq.PFS # Parametric Frequency Sweep # Configuration class freq.PFSBuildConfig Common Usage Pattern ==================== All NeurEco models follow the same basic pattern: .. code-block:: python # 1. Import from NeurEco import NeurEcoTabular as tab # 2. Create model instance model = tab.Regressor() # 3. Create build configuration config = tab.RegressorBuildConfig( input_data=X_train, output_data=Y_train, validation_input_data=X_valid, validation_output_data=Y_valid, write_model_to="./model/regressor.ednn", ) # 4. Build (train) the model status = model.build(config) # 5. Evaluate on new data predictions = model.evaluate(X_test) # 6. Compute error error = model.compute_error(predictions, Y_test) # 7. Save/Export model.save("./model/regressor.ednn") model.export_onnx("./model/regressor.onnx") # 8. Cleanup model.delete() Loading Existing Models ----------------------- .. code-block:: python # Create new instance and load model = tab.Regressor() model.load("./model/regressor.ednn") # Now ready to use predictions = model.evaluate(X_new) Data Format Requirements ======================== Input Data ---------- All NeurEco models expect NumPy arrays: .. code-block:: python import numpy as np # Single array: (n_samples, n_features) X = np.array([[1.0, 2.0], [3.0, 4.0], [5.0, 6.0]]) # List of arrays (for Dynamic models with multiple trajectories) X_list = [array1, array2, array3] Output Data ----------- - **Regression**: Real-valued arrays ``(n_samples, n_outputs)`` - **Classification**: One-hot encoded arrays ``(n_samples, n_classes)`` - **PFS**: Complex-valued arrays ``(n_samples, n_outputs)``, dtype ``complex128`` Data Types ---------- .. list-table:: :header-rows: 1 :widths: 30 30 40 * - Solution - Inputs - Outputs * - Tabular - ``float64`` - ``float64`` * - Dynamic - ``float64`` - ``float64`` * - PFS - ``float64`` - ``complex128`` Exception Handling ================== NeurEco provides specific exceptions for different error types: .. code-block:: python from NeurEco import ( NeurEcoError, # Base exception ModelNotReadyError, # No model loaded/built ModelOperationError, # Operation failed DataValidationError, # Invalid data ConfigurationError, # Invalid configuration ArrayShapeMismatchError,# Shape mismatch DataContainsNaNError, # NaN values detected ) try: model.evaluate(X_test) except ModelNotReadyError: print("Load or build a model first!") except ArrayShapeMismatchError as e: print(f"Shape error: {e}") See :ref:`exceptions-ref` for complete exception reference. Memory Management ================= NeurEco models allocate native memory that must be explicitly freed: .. code-block:: python model = tab.Regressor() model.build(config) # ... use model ... # Always call delete() when done model.delete() .. warning:: Always call ``model.delete()`` when finished to avoid memory leaks. Environment Variables ===================== NeurEco respects the following environment variables: .. list-table:: :header-rows: 1 :widths: 30 70 * - Variable - Description * - ``ADAGOS_LICENSE_FILE`` - Full path of the license file (see :ref:`licensing`) * - ``MKL_CBWR`` - CPU math mode. Unset (default): MKL's AVX2 code path on Intel processors, MKL's automatic mode on AMD processors (``COMPATIBLE`` with the PyTorch 2.7 package on Windows). ``COMPATIBLE``: MKL's results do not depend on the processor type, but builds are slower. Set it before importing NeurEco. See :ref:`cpu-performance` Next Steps ========== - :ref:`Tabular API Reference ` - :ref:`Dynamic API Reference ` - :ref:`PFS API Reference ` - :ref:`Exceptions Reference `