.. _troubleshooting:

===============
Troubleshooting
===============

Solutions to common issues encountered when using NeurEco. For the issues known in this
release, see :ref:`known-issues`.

.. contents:: On this page
   :local:
   :depth: 2

Installation Issues
===================

"NeurEco binaries not found"
----------------------------

**Symptoms:**

- ``BinaryNotFoundError`` when creating a model
- "DLL not found" or "shared library not found" errors

**Solutions:**

1. **Python package installed with pip:** leave ``dll_path`` unset: the package uses
   the binaries it includes. If the error remains, reinstall the package with the
   PyTorch version and build it requires (see :ref:`installation`). A GPU edition
   needs a CUDA build of PyTorch; on Windows, the PyTorch on PyPI is CPU-only.

2. **Installed NeurEco used from Python:** set ``dll_path`` to the folder that contains
   the NeurEco libraries, not to a library file. With the default installation folders:

   .. code-block:: python

      from NeurEco import NeurEcoTabular as tab

      # Windows
      model = tab.Regressor(dll_path="C:/Program Files/Adagos/NeurEco-5.0/bin")

      # Linux
      model = tab.Regressor(dll_path="/opt/neureco/lib")

"No matching distribution found for neureco~=5.0"
-------------------------------------------------

**Symptoms:**

- The pip command of your edition stops with ``No matching distribution found for neureco~=5.0``.
  The line before it may list ``from versions: 0.0.1``: that is a placeholder package on
  PyPI, not a NeurEco version

**Solutions:**

1. Check the Adagos package index in the command against :ref:`installation`.
2. Check that pip can reach ``adagos.com``, through your proxy if you use one.
3. Check that your system is supported: the Python library needs Windows or Linux on
   x86-64, a 64-bit Python 3.10 or newer, and, on Linux, glibc 2.35 or newer (see
   :ref:`installation`).
   If pip also prints ``Ignored the following versions that require a different python
   version``, your Python version is too old.

"No matching distribution found for torch<2.9,>=2.8"
----------------------------------------------------

**Cause:**

The PyTorch version of your edition has no build for your Python version: PyTorch 2.9
supports Python 3.10 to 3.14, and PyTorch 2.7 and 2.8 support Python 3.10 to 3.13. The
message gives the PyTorch versions of your edition, for example ``torch<2.8,>=2.7`` for
the PyTorch 2.7 edition.

**Solution:**

Install NeurEco with a Python version that the PyTorch version of your edition supports,
for example in a new virtual environment, or choose the PyTorch 2.9 edition.

"No module named 'NeurEco'" after ``pip install neureco``
---------------------------------------------------------

**Cause:**

pip installed the placeholder package ``neureco`` 0.0.1 from PyPI instead of NeurEco:
``pip show neureco`` shows that version. pip does so when the command has no Adagos
package index, or when pip cannot use it.

**Solution:**

Run the pip command of your edition given in :ref:`installation`: it replaces the
placeholder. If it stops with ``No matching distribution found for neureco~=5.0``, see
that message above.

Python still loads NeurEco 4.x
------------------------------

**Symptoms:**

- After you install NeurEco 5.0 with pip, ``import NeurEco`` still loads NeurEco 4.x:
  features of NeurEco 5.0 are missing, or scripts behave as with NeurEco 4.x

**Solution:**

The ``INSTALL.py`` script of NeurEco 4.x copied the library into Python's standard-library
folder, which Python searches before the packages that pip installs, even in a virtual
environment created from that Python. Find and delete that copy as described in
:ref:`Upgrading from the NeurEco 4.x Python Library <installation-python-4x>`.

"libgomp not found" (Linux)
---------------------------

**Solution:**

The ``neureco`` package (DEB or RPM) and the Python package include their OpenMP
runtime, so no system OpenMP package is needed. This message points to an incomplete
installation: reinstall NeurEco or the Python package (see :ref:`installation`).

.. _troubleshooting-openmp:

"More than one OpenMP runtime"
------------------------------

**Symptoms:**

- A warning at the start of a build that says ``OpenMP runtimes are loaded in this
  process`` (build log, GUI build output, console), or a Python warning that says
  ``More than one OpenMP runtime in this process``, followed by the runtime files, for
  example ``libiomp5md.dll`` and ``libomp.dll`` from two folders (Windows), or
  ``libgomp.so.1`` and ``libomp.so`` (Linux)
- Builds much slower than usual, or results that change from one run to the next

**Cause:**

OpenMP runs NeurEco's computations on several cores, and each OpenMP runtime manages
its own threads. When a second runtime is loaded in the same process, the two compete
for the cores, or two copies of the same runtime conflict. The usual source is another
library loaded in the same Python session that brings its own OpenMP runtime, such as
PyTorch, an MKL-based NumPy or scikit-learn. NeurEco lists MSVC's ``vcomp140.dll``
when it is loaded, but does not count it.

**Solutions:**

1. **Python package installed with pip:** install the PyTorch version that matches
   your NeurEco package (see :ref:`installation`).
2. **Installed NeurEco used from Python** (``dll_path``): create the first NeurEco
   model before importing ``torch`` or an MKL-based ``numpy``.
3. **GUI or neureco command:** the warning points to an installation problem.
   Reinstall NeurEco, and do not copy other OpenMP libraries into its folders.
4. If the warning remains, send its full text to support@adagos.com.

.. note::

   On Windows, the NeurEco Python package sets ``KMP_DUPLICATE_LIB_OK=TRUE`` so that
   a second copy of the Intel or LLVM OpenMP runtime does not stop the process. This
   hides the conflict but does not solve it: results can then differ between runs.
   Fix the cause instead.

License Issues
==============

"License not found"
-------------------

**Solutions:**

1. Set the ``ADAGOS_LICENSE_FILE`` environment variable to the full path of the license file,
   so that the program you start sees it (see :ref:`licensing`). On Linux, for example:

   .. code-block:: shell

      export ADAGOS_LICENSE_FILE="$HOME/adagos.lic"

2. On Windows, you can instead copy the license file, with its ``.lic`` extension, to your user
   folder (``C:\Users\your_username``). On Linux, NeurEco does not look in your home directory:
   without the variable, it finds a license file only in the current folder.

"Feature not licensed"
----------------------

You're trying to use a feature not included in your license (e.g., export formats require an embed license).

**Solution:** Contact support@adagos.com to upgrade your license.

"License file does not support this version"
--------------------------------------------

Or, with a license server: "License server system does not support this version of this
feature".

The license was issued for NeurEco 4.5 or 4.6. NeurEco 5.0 needs a license issued for
NeurEco 5.0.

**Solution:** Contact support@adagos.com to replace your license file. If a license
server hands out your licenses, its license file must be replaced too.

A "FLEXible License Manager" window opens (Windows)
---------------------------------------------------

On Windows, when a license request is refused, FlexNet, the licensing software that
NeurEco uses, shows its own message in a window titled "FLEXible License Manager".
NeurEco waits until you close the window, then shows its own error message.

**Solution:** Read the message, close the window, and solve the license problem it
reports (see the other entries in this section).

"Hardware mismatch"
-------------------

Your hardware has changed since the license was generated.

**Solution:** Generate a new ``hardware_info.txt`` in the desktop app (**Help** menu >
**Hardware id generator**), with the command ``neureco hardwareinfo``, or, with the
Python package only, with ``python -m NeurEco.hardware_info``, and send it to
support@adagos.com to request a new license.

Data Issues
===========

"Data contains NaN values"
--------------------------

**Symptoms:** ``DataContainsNaNError``

**Solutions:**

.. code-block:: python

   import numpy as np

   # Check for NaN
   print(f"NaN in X: {np.any(np.isnan(X))}")
   print(f"NaN in Y: {np.any(np.isnan(Y))}")

   # Option 1: Remove rows with NaN
   mask = ~np.isnan(X).any(axis=1) & ~np.isnan(Y).any(axis=1)
   X_clean = X[mask]
   Y_clean = Y[mask]

   # Option 2: Replace NaN with values
   X_clean = np.nan_to_num(X, nan=0.0)

"Shape mismatch"
----------------

**Symptoms:** ``ArrayShapeMismatchError``

**Common causes:**

- Input/output sample counts don't match
- Wrong number of features for a loaded model
- Data not properly reshaped to 2D

**Solutions:**

.. code-block:: python

   # Ensure 2D arrays
   if len(X.shape) == 1:
       X = X.reshape(-1, 1)

   # Check shapes match
   print(f"X shape: {X.shape}")
   print(f"Y shape: {Y.shape}")
   assert X.shape[0] == Y.shape[0], "Sample count mismatch"

   # For evaluation, check model expectations
   print(f"Model expects {model.get_input_count()} inputs")
   print(f"Data has {X.shape[1]} features")

"Empty data"
------------

**Symptoms:** ``DataValidationError`` mentioning empty arrays

**Solution:** Verify your data has content:

.. code-block:: python

   print(f"X samples: {X.shape[0]}")
   assert X.shape[0] > 0, "No samples in input data"

Build Issues
============

Build runs indefinitely
-----------------------

**Possible causes:**

- Very large dataset
- Very complex problem (high-dimensional data)
- No stopping criteria set

**Solutions:**

1. **Set maximum neurons:**

   .. code-block:: python

      config = tab.RegressorBuildConfig(
          input_data=X,
          output_data=Y,
          links_maximum_number=100,  # Limit model size
      )

2. **Use checkpointing:**

   .. code-block:: python

      config = tab.RegressorBuildConfig(
          input_data=X,
          output_data=Y,
          checkpoint_address="./checkpoints/model",
      )

   You can stop training and load an intermediate model from the checkpoint.

3. **Reduce data size:** Start with a subset to verify the workflow works.

Build produces poor results
---------------------------

**Possible causes:**

- Insufficient or noisy data
- Inappropriate normalization
- Problem not suited for NeurEco

**Solutions:**

1. **Check data quality:** Remove outliers, handle missing values

2. **Try different normalization:**

   .. code-block:: python

      config = tab.RegressorBuildConfig(
          input_data=X,
          output_data=Y,
          inputs_shifting="min_centered",  # or "none", "auto", "mean"
          inputs_scaling="max_centered",   # or "none", "auto", "max", "std"
      )

3. **Provide validation data:** Explicit validation helps prevent overfitting

   .. code-block:: python

      config = tab.RegressorBuildConfig(
          input_data=X_train,
          output_data=Y_train,
          validation_input_data=X_val,
          validation_output_data=Y_val,
      )

Evaluation Issues
=================

"Model not ready"
-----------------

**Symptoms:** ``ModelNotReadyError``

**Cause:** Trying to evaluate before building or loading a model.

**Solution:**

.. code-block:: python

   from NeurEco import NeurEcoTabular as tab

   model = tab.Regressor()

   # Either build a new model
   model.build(config)

   # Or load an existing one
   model.load("path/to/model.ednn")

   # Now evaluate
   predictions = model.evaluate(X)

Wrong output shape (Dynamic)
----------------------------

**Symptoms:** Output array has fewer samples than expected

**For ConvolutiveDynamic:**

Output starts at time step ``window_size - 1``:

.. code-block:: python

   # eval_exc has time in its first column; predictions are returned time-first.
   predictions = model.evaluate(eval_exc)
   w_size = model.get_window_size()

   # Align reference with predictions, and drop the prediction's leading time
   # column for compute_error (which takes outputs only).
   aligned_reference = Y[w_size - 1:]
   error = model.compute_error(predictions[:, 1:], aligned_reference)

**For ODE with initialization:**

The last init point is the first prediction point:

.. code-block:: python

   n_init = model.get_number_of_init_tsteps()

   # Build time-first arrays (time in the first column).
   eval_exc = np.column_stack([time_full, exc_full])
   init_exc = np.column_stack([time_full[:n_init], exc_full[:n_init]])
   init_out = np.column_stack([time_full[:n_init], out_full[:n_init]])

   predictions = model.evaluate(
       eval_exc[n_init - 1:],              # Start from n_init-1; predictions are time-first
       init_excitations=init_exc,
       init_outputs=init_out,
   )

Export Issues
=============

"Export failed"
---------------

**Common causes:**

- Missing embed license
- Invalid export path
- Incompatible model for format

**Solutions:**

1. **Check license:** Export requires an embed license (e.g., ``neureco_embed_tabular``)

2. **Verify path:** Ensure the directory exists and you have write permissions

3. **Check format compatibility:**

   .. list-table::
      :header-rows: 1

      * - Format
        - Tabular
        - Dynamic
        - PFS
      * - ONNX
        - Yes
        - No
        - No
      * - FMU
        - Yes
        - Yes
        - Yes
      * - C Header
        - Yes
        - No
        - No
      * - VBA
        - Yes
        - No
        - No

CLI Issues
==========

"Invalid configuration"
-----------------------

**Common causes:**

- JSON syntax error
- Wrong root key
- Missing required parameters

**Solutions:**

1. **Validate JSON:** Use a JSON validator to check syntax

2. **Check root key format:** Must match template and command, for example
   ``neureco Regression build`` reads:

   .. code-block:: text

      {
          "neurecoRegression_build": { ... }
      }

3. **Verify required parameters:** See :ref:`cli-reference` for required fields

"File not found"
----------------

**Solutions:**

1. **Use correct path format:**

   - Forward slashes: ``data/train.csv``
   - Or escaped backslashes: ``data\\train.csv``

2. **Check relative paths:** they are relative to the folder of the configuration
   file, not to the folder where the command runs. Use absolute paths if in doubt

3. **Verify files exist** before running the command

Memory Issues
=============

Out of memory during build
--------------------------

**Solutions:**

1. **Reduce batch size** (if applicable)

2. **Use CPU instead of GPU** for very large datasets

3. **Reduce data size:** Sample your dataset

4. **Set model size limits:**

   .. code-block:: python

      config = tab.RegressorBuildConfig(
          input_data=X,
          output_data=Y,
          links_maximum_number=50,
      )

Memory not released after delete
--------------------------------

**Solution:** Always call ``delete()`` when done:

.. code-block:: python

   model = tab.Regressor()
   model.build(config)
   predictions = model.evaluate(X_test)

   # Free native memory
   model.delete()

Getting Help
============

If you can't resolve your issue:

1. **Check the error message:** NeurEco provides descriptive error messages
2. **Review the documentation:** See the relevant API reference
3. **Contact support:** Email support@adagos.com with:

   - NeurEco version
   - Operating system
   - Complete error message
   - Minimal code to reproduce the issue