.. _cpu-performance:

===================================
CPU Performance and Reproducibility
===================================

NeurEco uses the Intel MKL math library for its CPU computations. By default, MKL runs
a fast code path chosen for your processor type. This page describes the default, the
processor-independent mode, and how to switch between them.

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

Default Mode
============

By default, NeurEco chooses MKL's code path from the processor:

- **Intel processors:** MKL's AVX2 code path (``MKL_CBWR=AVX2``). MKL computes the same
  way on every Intel processor with AVX2, with or without AVX-512.
- **AMD processors:** MKL's automatic mode, the fastest code path MKL offers on these
  processors (NeurEco sets ``MKL_CBWR=AVX2``, which MKL runs as ``AUTO`` on them). On
  Windows, the Python package for PyTorch 2.7 uses the processor-independent mode
  instead (see the warning below).

On the same machine, with the same NeurEco version, data, settings and number of
threads, results are reproducible from run to run. Results can differ between an Intel
and an AMD processor, between Windows and Linux, and between runs that use a different
number of threads. Exported models (FMU, C, ONNX, VBA) do not use MKL and are not
affected.

In Python, import NeurEco before NumPy and PyTorch. PyTorch's MKL reads ``MKL_CBWR``
once, when it starts: the conda PyTorch builds start it during ``import torch``, and
a conda NumPy built on MKL shares that MKL and starts it during ``import numpy``. An
MKL that started first does not use NeurEco's mode, and convolutional results can then
differ from run to run.

Processor-Independent Mode: MKL_CBWR=COMPATIBLE
===============================================

Set the environment variable ``MKL_CBWR`` to ``COMPATIBLE`` before you start NeurEco.
MKL then uses the same code path on every Intel or AMD processor, so MKL's results do
not depend on the processor type.

**What to expect:**

- Slower builds. On an AMD Ryzen AI 9 HX PRO 370 under Linux, the default mode built
  Tabular models in about 21% less time than this mode, ODE models in 9% to 23% less
  and PFS models in about 17% less. The difference depends on the processor and on the
  problem.
- Results can still differ between Windows and Linux, and between runs that use a
  different number of threads.

.. warning::

   On Windows, the MKL release that comes with some PyTorch builds (for example the
   conda PyTorch 2.7 builds, which ship MKL 2024) has a known defect on AMD processors
   outside the processor-independent mode: it can corrupt results or crash. This is why,
   on Windows, the Python package for PyTorch 2.7 uses ``COMPATIBLE`` on AMD processors.
   On an AMD processor, when ``MKL_CBWR`` is not ``COMPATIBLE`` and PyTorch's MKL is
   older than 2025.0.1, convolutional builds print a warning that names the PyTorch and
   MKL versions. On such machines, set ``MKL_CBWR=COMPATIBLE`` or use PyTorch 2.9. The GUI
   and the ``neureco`` command include PyTorch 2.9.

   In Python, the same MKL also leaves NeurEco's mode when NumPy or PyTorch starts it
   before NeurEco while ``MKL_CBWR`` is not set, and NeurEco then warns at import.
   Import NeurEco before NumPy and PyTorch, set ``MKL_CBWR=COMPATIBLE`` before starting
   Python, or use PyTorch 2.9.

Setting MKL_CBWR
----------------

NeurEco reads the setting once, when it starts. Set the variable, then start the GUI,
the ``neureco`` command or Python from the same window. On Windows the installer does
not add ``neureco.exe`` to the ``PATH``: use its full path, as shown below. Write the
value in capitals: MKL ignores a value it does not recognize, such as ``compatible``,
and runs ``AUTO`` instead.

.. tabs::

   .. tab:: Windows (Command Prompt)

      .. code-block:: shell

         set MKL_CBWR=COMPATIBLE
         "C:\Program Files\Adagos\NeurEco-5.0\guibin\NeurEcoGui.exe"

      To build from the command line instead, from the same window:

      .. code-block:: shell

         "C:\Program Files\Adagos\NeurEco-5.0\bin\neureco.exe" Regression build build.conf

   .. tab:: Windows (PowerShell)

      .. code-block:: shell

         $env:MKL_CBWR = "COMPATIBLE"
         & "C:\Program Files\Adagos\NeurEco-5.0\guibin\NeurEcoGui.exe"

      To build from the command line instead, from the same window:

      .. code-block:: shell

         & "C:\Program Files\Adagos\NeurEco-5.0\bin\neureco.exe" Regression build build.conf

   .. tab:: Linux

      .. code-block:: shell

         export MKL_CBWR=COMPATIBLE
         neurecoGUI neurecogui.conf

      For a single command:

      .. code-block:: shell

         MKL_CBWR=COMPATIBLE neureco Regression build build.conf

   .. tab:: Python API

      Set the variable at the top of the script, before importing NeurEco, PyTorch or
      NumPy:

      .. code-block:: python

         import os
         os.environ["MKL_CBWR"] = "COMPATIBLE"

         from NeurEco import NeurEcoTabular as tab

      In a Jupyter notebook, restart the kernel after changing the setting.

.. note::

   To use this mode in every session, create a user environment variable
   ``MKL_CBWR`` with the value ``COMPATIBLE`` (Windows: search for "Edit environment
   variables for your account"; Linux: add ``export MKL_CBWR=COMPATIBLE`` to
   ``~/.profile``). The variable then applies to every program that uses MKL, not
   only to NeurEco.

Going Back to the Default
-------------------------

Remove the variable, then restart the GUI, the command or the Python session. If you created a user environment variable, delete it where you
created it (Windows: "Edit environment variables for your account"; Linux:
``~/.profile``), then open a new window or sign in again.

**Windows (Command Prompt):**

.. code-block:: shell

   set MKL_CBWR=

**Windows (PowerShell):**

.. code-block:: shell

   Remove-Item Env:MKL_CBWR

**Linux:**

.. code-block:: shell

   unset MKL_CBWR

.. note::

   ``MKL_CBWR`` also accepts MKL's other values, for example ``AUTO`` for the fastest
   code path of an Intel processor (such as AVX-512). On AMD processors MKL accepts only
   ``COMPATIBLE`` and ``AUTO``, and runs any other value as ``AUTO``.

Threads and OpenMP Runtimes
===========================

NeurEco runs its CPU computations on several cores through OpenMP. Only one OpenMP
runtime should be loaded in a process. When NeurEco finds more than one, it prints a
warning at the start of each build: see :ref:`troubleshooting-openmp`.

Next Steps
==========

- :ref:`GPU Setup <gpu-setup>` for GPU acceleration
- :ref:`Troubleshooting <troubleshooting>` for common errors