Python API Overview#

This page provides an overview of the NeurEco Python API, including installation, imports, and common usage patterns.

On this page

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):

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 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 Licensing).

Verify Installation#

from NeurEco import NeurEcoTabular as tab
model = tab.Regressor()
print(model.__version__())

Module Structure#

NeurEco organizes its API into solution-specific submodules:

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)

Available Classes#

Tabular Solution#

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#

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#

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:

# 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#

# 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:

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#

Solution

Inputs

Outputs

Tabular

float64

float64

Dynamic

float64

float64

PFS

float64

complex128

Exception Handling#

NeurEco provides specific exceptions for different error types:

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 Exceptions Reference for complete exception reference.

Memory Management#

NeurEco models allocate native memory that must be explicitly freed:

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:

Variable

Description

ADAGOS_LICENSE_FILE

Full path of the license file (see 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 CPU Performance and Reproducibility

Next Steps#