.. _tabular-building-models:

===============
Building Models
===============

This section covers how to build NeurEco Tabular models. Choose the template that matches your problem type.

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

Build Workflow Overview
=======================

Regardless of which template you use, the build process follows these steps:

1. **Configure parameters** — Set data paths, normalization, and training options
2. **Start the build** — NeurEco automatically constructs the optimal neural network
3. **Monitor progress** — Watch training metrics and checkpoint creation
4. **Select final model** — Choose from checkpoints or use the final model

During the build, NeurEco:

- Starts from the smallest possible network
- Enriches it step by step, adding neurons and connections
- Uses validation data to detect overfitting
- Saves intermediate models to checkpoints
- Stops when no further improvement is possible

Common Build Parameters
=======================

These parameters are shared across all Tabular templates:

**Data Parameters**

.. list-table::
   :header-rows: 1
   :widths: 30 15 55

   * - Parameter
     - Default
     - Description
   * - ``input_data``
     - Required
     - Training input data (array or file path)
   * - ``output_data``
     - Required\*
     - Training output data (not required for Compression)
   * - ``valid_percentage``
     - 33.33
     - Percentage of training data for validation (if not providing separate validation data)

**Normalization Parameters**

.. list-table::
   :header-rows: 1
   :widths: 30 15 55

   * - Parameter
     - Default
     - Description
   * - ``inputs_shifting``
     - "auto"
     - Shift method for inputs: "mean", "min_centered", "auto", "none"
   * - ``inputs_scaling``
     - "auto"
     - Scale method for inputs: "max", "max_centered", "std", "auto", "none"
   * - ``inputs_normalize_per_feature``
     - True
     - Apply normalization independently to each input feature
   * - ``outputs_shifting``
     - "auto"
     - Shift method for outputs (Regression/Classification only)
   * - ``outputs_scaling``
     - "auto"
     - Scale method for outputs (Regression/Classification only)
   * - ``outputs_normalize_per_feature``
     - False
     - Normalize each output feature independently (``True``) or all together (``False``); distinct from ``field_output`` (see :ref:`field-output-vs-normalization`)

**Training Parameters**

.. list-table::
   :header-rows: 1
   :widths: 30 15 55

   * - Parameter
     - Default
     - Description
   * - ``initial_beta_reg``
     - 0.1
     - Initial value of the regularization coefficient (see :ref:`regularization-coefficient`)
   * - ``final_learning``
     - True
     - Final steps: pruning, a last pass that disconnects the unused inputs (if ``disconnect_inputs_if_possible`` is True) and a training pass that also uses the validation data; ``False`` skips all three (Compression: only the training pass; see :ref:`final-learning`)
   * - ``disconnect_inputs_if_possible``
     - True
     - Allow NeurEco to prune the links from the inputs each time it changes the network structure and, when ``final_learning`` is True, to disconnect the unused inputs in the final steps; with ``False``, no link from an input is ever pruned (Regression/Classification only)

**Architecture Parameters**

.. list-table::
   :header-rows: 1
   :widths: 30 15 55

   * - Parameter
     - Default
     - Description
   * - ``links_maximum_number``
     - 0
     - Maximum connections in network (0 = unlimited)
   * - ``field_output``
     - False
     - Flag the outputs as a single physical field, not independent scalars (see :ref:`field-output-vs-normalization`)

**GPU Parameters**

.. list-table::
   :header-rows: 1
   :widths: 30 15 55

   * - Parameter
     - Default
     - Description
   * - ``use_gpu``
     - False
     - Enable GPU acceleration
   * - ``gpu_id``
     - 0
     - GPU device ID to use

**Output Parameters**

.. list-table::
   :header-rows: 1
   :widths: 30 15 55

   * - Parameter
     - Default
     - Description
   * - ``write_model_to``
     - Required
     - Path to save the final model (.ednn)
   * - ``checkpoint_address``
     - Optional
     - Path for checkpoint files

.. _regularization-coefficient:

The Regularization Coefficient
==============================

The ``initial_beta_reg`` parameter (listed under *Training Parameters* above, and
shown as **Regularization coefficient** in the GUI) sets the **initial** value of
NeurEco's regularization coefficient. It is a non-negative float and defaults to
``0.1``.

In NeurEco, the main source of regularization is **parsimony** — the model is kept
as small as possible. The regularization coefficient complements this. At the
**beginning** of the learning process, when several weight configurations give the
same error, it steers the learning towards the one with the smallest weights. By
the **end** of the learning process the model is already parsimonious, so this
coefficient is no longer needed and it decays to zero.

Because the coefficient anneals to zero on its own, the default of ``0.1`` is
appropriate for most builds and rarely needs to be changed. It applies to all
Tabular templates — Regression, Classification, and Compression.

.. _final-learning:

Final Learning
==============

The ``final_learning`` parameter (labelled **Final learning** in the GUI; boolean,
default ``True``) lets NeurEco push the training to its limit once the network is
built.

During the build, NeurEco progressively enriches the network topology. When
``final_learning`` is ``True``, once NeurEco has settled on the optimal topology it
runs the final steps: it prunes the network, disconnects the unused inputs (if
``disconnect_inputs_if_possible`` is ``True``), then runs an additional optimization
pass that pushes the weight optimization as far as it can, **smartly using the
validation data to drive the training to the edge**. This typically produces the
most accurate model NeurEco can reach for that topology.

When the build starts from a checkpoint with ``freeze_structure=True``, the structure
is kept: a training of the parameters replaces the pruning and the disconnection. A
frozen Regression or Classification build therefore needs ``final_learning=True``.

Set it to ``False`` to skip all the final steps — for instance to shorten the build
when a quick, approximate model is enough. The build then keeps the network it has at
the end of the topology optimization; ``disconnect_inputs_if_possible`` still acts
during that optimization. For Compression, ``final_learning`` controls only the pass
that uses the validation data.

.. _field-output-vs-normalization:

Field Output vs. Per-Feature Normalization
==========================================

``field_output`` and ``outputs_normalize_per_feature`` are easy to confuse because
both come up when the outputs represent a *field*, but they control different
things and are set independently.

``outputs_normalize_per_feature`` is a **normalization** setting — it decides how the
outputs are scaled before training:

- ``True`` — each output feature (column) is shifted and scaled **independently**.
  Use this when the outputs are quantities of different natures or magnitudes (for
  example a temperature around 300 K together with a pressure around 1e5 Pa), so
  that one does not dominate the others.
- ``False`` — all output features are normalized **together**, preserving their
  relative magnitudes. Use this when the outputs are quantities of the same nature
  — a set of temperatures, the coefficients of an SVD, or the values of a single
  physical field.

``field_output`` is a separate **modeling flag**. It tells NeurEco that the outputs
are a single physical field — a set of related values sampled over a grid or domain
(for example the temperature at every node of a mesh) — rather than a handful of
independent scalar outputs.

.. note::

   These are distinct settings, but they are not entirely independent: because a
   field is normalized as a whole, ``field_output=True`` **requires**
   ``outputs_normalize_per_feature=False``. If you set both to ``True``, NeurEco
   emits a warning and forces ``outputs_normalize_per_feature`` to ``False``.
   Setting ``outputs_normalize_per_feature=False`` on its own, however, does **not**
   turn on ``field_output``.

Template-Specific Documentation
===============================

Each template has some unique parameters and considerations. Choose your template:

.. toctree::
   :maxdepth: 1

   regression
   classification
   compression

Working with Checkpoints
========================

NeurEco saves intermediate models during training. These checkpoints are valuable for:

- **Early access:** Start using models before training completes
- **Avoiding overfitting:** Earlier checkpoints may generalize better
- **Model selection:** Choose the best size/accuracy tradeoff

Selecting a Checkpoint Model
----------------------------

.. tabs::

   .. tab:: GUI

      Use the checkpoint slider in the **Training** panel to browse available models. You can evaluate and export any checkpoint model.

   .. tab:: Python API

      .. code-block:: python

         # Load a specific checkpoint model (index 5 = "Checkpoint 6" in the log and the GUI)
         model = Tabular.Regressor()
         model.load_model_from_checkpoint("./model/regression.checkpoint", model_index=5)

      Indices start at 0: "Checkpoint N" in the build log and the GUI is
      ``model_index`` N - 1. Use ``get_number_of_networks_from_checkpoint(path)`` to
      get the number of models in the checkpoint.

   .. tab:: CLI

      To evaluate a checkpoint model, give the checkpoint file as ``neureco_filename``
      and the model index as ``id_neural_network_checkpoint`` (from 0; ``-1`` = last):

      .. code-block:: json

         {
             "neurecoRegression_evaluate": {
                 "neureco_filename": "./model/regression.checkpoint",
                 "id_neural_network_checkpoint": 5,
                 "exc_filenames": ["x_test.csv"],
                 "write_model_output_to_directory": "./evaluation_results"
             }
         }

      To start a new build from a checkpoint model, set
      ``starting_from_checkpoint_address`` and ``start_build_from_model_number`` in
      the build configuration (see :ref:`cli-tabular-build`).

Limiting Model Size
===================

To constrain the network size, use the ``links_maximum_number`` parameter:

.. tabs::

   .. tab:: GUI

      In **Advanced Settings**, set **Links maximum number** to your desired limit.

   .. tab:: Python API

      .. code-block:: python

         config = Tabular.RegressorBuildConfig(
             # ... other parameters
             links_maximum_number=100,  # Limit to 100 connections
         )

   .. tab:: CLI

      .. code-block:: json

         {
             "neurecoRegression_build": {
                 "DevSettings": {
                     "parameter_number_limit": 100
                 }
             }
         }

This is useful for:

- Embedded systems with memory constraints
- Faster inference requirements
- Simpler, more interpretable models

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

After building your model:

1. :ref:`Evaluate the model <tabular-evaluating-models>` on test data
2. :ref:`Export the model <tabular-exporting-models>` for deployment