.. _dynamic-exporting:

========================
Exporting Dynamic Models
========================

This page explains how to export NeurEco Dynamic models (both ODE and Convolutional Dynamic) as FMUs for deployment and integration, and how to save them in the native NeurEco format.

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

Export Formats
==============

NeurEco Dynamic models can be exported to:

.. list-table::
   :header-rows: 1
   :widths: 20 40 40

   * - Format
     - Use Case
     - Compatibility
   * - **FMU**
     - Simulation tools, digital twins
     - MATLAB/Simulink, Dymola, OpenModelica, any FMI-compatible tool
   * - **Native**
     - NeurEco Python API
     - ``.ernn`` (ODE) or ``.ecnn`` (Convolutional Dynamic)

There is no C source or ONNX export for Dynamic models.

FMU Export
==========

Functional Mock-up Units (FMU) are the standard for model exchange in simulation environments. NeurEco exports FMU 2.0 compliant packages.

.. tabs::

   .. tab:: GUI

      1. Open your trained model and click **Export**
      2. Click **FMI for Co-Simulation 2.0**
      3. In the save dialog, choose the name and folder of the ``.fmu`` file
      4. The ``.fmu`` file is created in the chosen folder

   .. tab:: Python API (ODE)

      .. code-block:: python

         from NeurEco import NeurEcoDynamic as Dynamic

         # Load trained model
         model = Dynamic.ODE()
         model.load("path/to/model.ernn")

         # Export to FMU
         model.export_fmu("./export/my_ode_model.fmu")

         print("FMU exported successfully!")

   .. tab:: Python API (Convolutional Dynamic)

      .. code-block:: python

         from NeurEco import NeurEcoDynamic as Dynamic

         # Load trained model
         model = Dynamic.ConvolutiveDynamic()
         model.load("path/to/model.ecnn")

         # Export to FMU
         model.export_fmu("./export/my_convolutive_model.fmu")

         print("FMU exported successfully!")

   .. tab:: CLI (ODE)

      .. code-block:: shell

         neureco ODE exportFMU ./model/ode_model.ernn ./model/ode_model.fmu 3

      The arguments are the model file, the ``.fmu`` file to write and the platform
      flag: use ``3`` (Windows and Linux).

   .. tab:: CLI (Convolutional Dynamic)

      .. code-block:: shell

         neureco ConvolutiveDynamic exportFMU ./model/convolutive_model.ecnn ./model/convolutive_model.fmu 3

      The arguments are the model file, the ``.fmu`` file to write and the platform
      flag: use ``3`` (Windows and Linux).

FMU Export Parameters
---------------------

In Python, ``export_fmu`` takes one argument, ``fmu_path``: the path of the
``.fmu`` file to write (the ``.fmu`` extension is added when missing). On the
command line, ``exportFMU`` takes the model file, the ``.fmu`` file and the
platform flag ``3``.

Using Exported FMUs
-------------------

**In MATLAB/Simulink:**

1. Use the FMU Import block from the Simscape library
2. Point to your exported ``.fmu`` file
3. Connect inputs and outputs to your simulation

**In Dymola/OpenModelica:**

1. Import the FMU using the standard FMU import function
2. The model appears as a component with defined inputs/outputs
3. Connect to your system model

**In Python (FMPy):**

.. code-block:: python

   from fmpy import simulate_fmu
   import numpy as np

   # Simulate the FMU
   result = simulate_fmu(
       'my_model.fmu',
       start_time=0,
       stop_time=10,
       step_size=0.01,
       input=input_data,  # Your input trajectory
   )

Native Format
=============

The native NeurEco format preserves all model information and allows continued work in NeurEco.

**File extensions:**

- ODE models: ``.ernn``
- Convolutional Dynamic models: ``.ecnn``

**Saving a model:**

.. code-block:: python

   # During build (recommended)
   config = Dynamic.ODEBuildConfig(
       # ...
       write_model_to="./model/my_model.ernn",
   )

   # Or save explicitly
   model.save("./model/my_model.ernn")

**Loading a model:**

.. code-block:: python

   model = Dynamic.ODE()
   model.load("./model/my_model.ernn")

Export Considerations
=====================

ODE vs. Convolutional Dynamic FMUs
----------------------------------

.. list-table::
   :header-rows: 1
   :widths: 30 35 35

   * - Aspect
     - ODE FMU
     - Convolutional Dynamic FMU
   * - Initialization
     - Requires initial state or uses steady-state
     - Automatic (handles internally)
   * - State variables
     - Exposed as FMU states
     - Hidden (window buffer)
   * - Time step
     - Must match training dt
     - Must match training dt

Time Step Matching
------------------

.. warning::

   The simulation time step in the FMU environment **must match** the time step used during training. Using a different time step will produce incorrect results.

To check the training time step:

.. code-block:: python

   # The time step is determined by your training data
   # Verify it matches your simulation setup
   # Time lives in column 0 of each excitation array
   dt_training = train_exc_list[0][1, 0] - train_exc_list[0][0, 0]
   print(f"Training time step: {dt_training}")

Platform Compatibility
----------------------

FMUs contain platform-specific binaries. An FMU exported by NeurEco contains
binaries for both Windows and Linux, whichever system it was exported on:

- **Windows**: Windows DLLs in ``binaries/win64``
- **Linux**: Linux shared objects in ``binaries/linux64``

The same ``.fmu`` file can therefore be used on Windows and on Linux. The Linux
binaries need glibc 2.28 or newer, as in Red Hat Enterprise Linux 8 and later, and they
carry their own C++ runtime, so they also load in simulation tools that use an older one.

Complete Export Example
=======================

.. code-block:: python

   from NeurEco import NeurEcoDynamic as Dynamic
   import os

   # Load model
   model = Dynamic.ODE()
   model.load("./trained_model.ernn")

   # Create export directory
   os.makedirs("./export", exist_ok=True)

   # Export to FMU
   model.export_fmu("./export/model.fmu")
   print("FMU exported to ./export/model.fmu")

   # Verify exports
   print("\nExported files:")
   for root, dirs, files in os.walk("./export"):
       for file in files:
           print(f"  {os.path.join(root, file)}")

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

- :ref:`Dynamic advanced features <dynamic-advanced-features>`
- :ref:`Dynamic examples <dynamic-examples>`