.. _ode-template:

============
ODE Template
============

The ODE (Ordinary Differential Equation) template creates neural network models that learn the underlying differential equations governing a dynamic system. These models are ideal for physical systems with continuous dynamics.

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

Overview
========

ODE models learn to represent systems of the form:

.. math::

   \frac{dx}{dt} = f(x, u, t)

   y = g(x, u)

where:

- :math:`x` is the internal state vector
- :math:`u` is the input (excitation) vector
- :math:`y` is the output vector
- :math:`f` and :math:`g` are learned functions

**Key capabilities:**

- Automatically discovers hidden states needed to model the dynamics
- Supports steady-state constraints for physically meaningful behavior
- Allows initialization from known states for accurate simulation
- Exports to FMU format for integration with simulation tools

When to Use ODE
===============

The ODE template is ideal for:

- **Physical systems**: Mechanical, thermal, electrical, hydraulic systems
- **Continuous dynamics**: Systems governed by differential equations
- **State-based modeling**: When the system has well-defined physical states
- **Long-term simulation**: When prediction accuracy over extended time is critical
- **Digital twins**: Creating virtual replicas of real-world systems

**Example applications:**

- Mass-spring-damper systems
- Heat transfer and thermal dynamics
- Electric motor modeling
- Vehicle dynamics
- Process control systems

Model Architecture
==================

NeurEco ODE models consist of:

1. **State network**: Learns the state dynamics :math:`f(x, u, t)`
2. **Output network**: Maps states to outputs :math:`g(x, u)`
3. **Hidden states**: Internal variables discovered during training

The number of hidden states is determined automatically during training, starting from ``min_hidden_states`` and growing as needed (up to ``max_hidden_states`` if specified).

Native File Format
==================

ODE models use the ``.ernn`` extension:

- Preserves complete model information
- Supports loading and continued training
- Can be exported to FMU format

Workflow
========

1. **Prepare data**: Format time-series data with time, inputs, and outputs
2. **Build model**: Train the ODE model on your data
3. **Evaluate**: Run simulations with optional state initialization
4. **Export**: Save in native format or export to FMU

.. toctree::
   :maxdepth: 1
   :caption: ODE Template

   building
   evaluating