.. _cli-reference:

=============
CLI Reference
=============

Complete reference for the NeurEco command-line interface (CLI).

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

Overview
========

The ``neureco`` command builds and evaluates models from JSON configuration files,
and exports models to other formats:

.. code-block:: shell

   neureco <Template> build <configuration file>
   neureco <Template> evaluate <configuration file>
   neureco <Template> <export command> <model file> <output file> <option>

**Templates:**

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

   * - Template
     - Model
     - Model file
   * - ``Regression``
     - Tabular regression
     - ``.ednn``
   * - ``Classification``
     - Tabular classification
     - ``.ednn``
   * - ``Compression``
     - Tabular compression
     - ``.ednn``
   * - ``PFS``
     - Parametric Frequency Sweep
     - ``.efnn``
   * - ``ODE``
     - Dynamic ODE
     - ``.ernn``
   * - ``ConvolutiveDynamic``
     - Convolutional Dynamic
     - ``.ecnn``

Template names are not case-sensitive, and ``ConvolutionalDynamic`` is accepted as
well as ``ConvolutiveDynamic``. The backend names of earlier releases (``DNN``,
``FNN``, ``RNN`` and ``CNN``) are also accepted, see :ref:`cli-backend-names`.

**Commands:**

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

   * - Command
     - Templates
   * - ``build``
     - All templates: train a model
   * - ``evaluate``
     - All templates: run a model on data files
   * - ``exportC``, ``exportONNX``, ``exportVBA``
     - Regression, Classification, Compression
   * - ``exportFMU``
     - All templates

**Help and license:**

- ``neureco -h`` lists the templates and their commands. ``neureco <Template> -h``
  lists the commands of one template, and ``neureco <Template> -v`` prints the
  version of its backend.
- ``neureco hardwareinfo`` asks for your contact details and writes
  ``hardware_info.txt``, the file that Adagos needs to create your license, to the
  current folder. The desktop app writes the same file from
  **Help > Hardware id generator** (see :ref:`licensing`).

Quick Start
===========

In a folder that holds ``x_train.csv``, ``y_train.csv``, ``x_test.csv`` and
``y_test.csv`` (for example the folder where you extracted the example
``EnergyConsumption.zip``, see :ref:`Tabular examples <tabular-examples>`), write
the :ref:`Tabular build configuration <cli-tabular-build>` to ``build.conf`` and the
:ref:`Tabular evaluate configuration <cli-tabular-evaluate>` to ``eval.conf``, then
run:

.. code-block:: shell

   # Build a regression model
   neureco Regression build build.conf

   # Evaluate it on the test data
   neureco Regression evaluate eval.conf

   # Export it to ONNX
   neureco Regression exportONNX ./model/regressor.ednn ./model/regressor.onnx float32

Configuration Files
===================

A configuration file is a JSON object with one root key,
``neureco<Template>_<command>``, that holds the settings:

.. code-block:: json

   {
       "neurecoRegression_build": {
           "exc_filenames": ["x_train.csv"],
           "output_filenames": ["y_train.csv"]
       }
   }

**Root keys:**

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

   * - Template
     - ``build``
     - ``evaluate``
   * - Regression
     - ``neurecoRegression_build``
     - ``neurecoRegression_evaluate``
   * - Classification
     - ``neurecoClassification_build``
     - ``neurecoClassification_evaluate``
   * - Compression
     - ``neurecoCompression_build``
     - ``neurecoCompression_evaluate``
   * - PFS
     - ``neurecoPFS_build``
     - ``neurecoPFS_evaluate``
   * - ODE
     - ``neurecoODE_build``
     - ``neurecoODE_evaluate``
   * - Convolutional Dynamic
     - ``neurecoConvolutiveDynamic_build``
     - ``neurecoConvolutiveDynamic_evaluate``

The export commands take their arguments on the command line and need no
configuration file.

**Rules:**

- Use the same template in the command and in the root key, for example
  ``neureco ODE build`` with ``neurecoODE_build``. Otherwise ``neureco`` stops with
  an error that names both.
- The Tabular root keys select the mode, so ``classification`` and
  ``build_compress`` need not be set. A file that also sets one of them against
  its root key (for example ``"classification": false`` under
  ``neurecoClassification_build``) is rejected with an error.
- ``neurecoConvolutionalDynamic_build`` and ``neurecoConvolutionalDynamic_evaluate``
  are accepted as well.
- Relative paths are relative to the folder that contains the configuration file,
  not to the folder where the command runs.
- NeurEco ignores the fields it does not know, so a misspelled field name silently
  keeps the default value. Check each field name against the tables below.

.. _cli-backend-names:

Backend Names
-------------

Earlier releases name the backend instead of the template, in the command and in
the root key. These names still work, and the tutorial configuration files use
them:

.. list-table::
   :header-rows: 1
   :widths: 15 35 50

   * - Backend
     - Templates
     - Root keys
   * - ``DNN``
     - Regression, Classification, Compression
     - ``neurecoDNN_build``, ``neurecoDNN_evaluate``
   * - ``FNN``
     - PFS
     - ``neurecoFNN_build``, ``neurecoFNN_evaluate``
   * - ``RNN``
     - ODE
     - ``neurecoRNN_build``, ``neurecoRNN_evaluate``
   * - ``CNN``
     - Convolutional Dynamic
     - ``neurecoCNN_build``, ``neurecoCNN_evaluate``

For example, ``neureco DNN build build.conf`` with a ``neurecoDNN_build`` root key
builds a Tabular model. With ``neurecoDNN_build``, the mode comes from two fields:
``"classification": true`` for a classification, ``"build_compress": true`` for a
compression, and neither for a regression.

Tabular Configuration
=====================

.. _cli-tabular-build:

Build Configuration
-------------------

**Root keys:** ``neurecoRegression_build``, ``neurecoClassification_build`` or
``neurecoCompression_build``

.. code-block:: json

   {
       "neurecoRegression_build": {
           "exc_filenames": ["x_train.csv"],
           "output_filenames": ["y_train.csv"],
           "test_exc_filenames": ["x_test.csv"],
           "test_output_filenames": ["y_test.csv"],
           "DevSettings": {
               "valid_percentage": 33.33,
               "parameter_number_limit": 0,
               "initial_beta_reg": 0.1,
               "final_learning": true,
               "disconnect_inputs_if_possible": true
           },
           "UserSettings": {
               "use_gpu": false,
               "gpu_id": 0
           },
           "input_normalization": {
               "shift_type": "auto",
               "scale_type": "auto",
               "normalize_per_feature": true
           },
           "output_normalization": {
               "shift_type": "auto",
               "scale_type": "auto",
               "normalize_per_feature": false
           },
           "write_model_to": "./model/regressor.ednn",
           "checkpoint_address": "./model/regressor.checkpoint",
           "write_model_output_to_directory": "./model/BuildingResults"
       }
   }

For a classification, use ``neurecoClassification_build`` and one-hot encoded
output files. For a compression, use ``neurecoCompression_build``, leave out the
output files and add the compression fields below.

**Parameters:**

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

   * - Parameter
     - Description
   * - ``exc_filenames``
     - List of training input files
   * - ``output_filenames``
     - List of training output files, one per input file (not used by Compression)
   * - ``validation_exc_filenames``
     - List of validation input files (optional). When set, ``valid_percentage`` is ignored
   * - ``validation_output_filenames``
     - List of validation output files (optional)
   * - ``test_exc_filenames``
     - List of test input files (optional; monitored during the build, never used for training)
   * - ``test_output_filenames``
     - List of test output files (optional)
   * - ``write_model_to``
     - Path of the final model (``.ednn``)
   * - ``checkpoint_address``
     - Path of the checkpoint file written during the build
   * - ``write_model_output_to_directory``
     - Folder for the output files of the build
   * - ``DevSettings.valid_percentage``
     - Percentage of the training data kept for validation when no validation files are given
   * - ``DevSettings.parameter_number_limit``
     - Maximum number of links in the network (``0`` = no limit)
   * - ``DevSettings.initial_beta_reg``
     - Initial regularization coefficient (see :ref:`regularization-coefficient`)
   * - ``DevSettings.final_learning``
     - ``true`` or ``false``: run the final learning steps (see :ref:`final-learning`)
   * - ``DevSettings.disconnect_inputs_if_possible``
     - ``true`` or ``false``: let NeurEco disconnect the inputs it does not need
   * - ``UserSettings.use_gpu``, ``UserSettings.gpu_id``
     - Build on a GPU, and the id of the GPU to use
   * - ``input_normalization.shift_type``
     - ``"none"``, ``"auto"``, ``"min_centered"`` or ``"mean"``
   * - ``input_normalization.scale_type``
     - ``"none"``, ``"auto"``, ``"max_centered"``, ``"max"`` or ``"std"``
   * - ``input_normalization.normalize_per_feature``
     - ``true``: normalize each input separately; ``false``: normalize all inputs together
   * - ``output_normalization``
     - Same three fields, for the outputs
   * - ``field_output``
     - ``true`` when the outputs form one physical field (see :ref:`field-output-vs-normalization`)

**Compression parameters:**

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

   * - Parameter
     - Description
   * - ``write_compression_model_to``
     - Path of the compressor (encoder) model
   * - ``write_decompression_model_to``
     - Path of the decompressor (decoder) model
   * - ``compress_tolerance``
     - Maximum acceptable relative reconstruction error
   * - ``minimum_compression_coefficients``
     - Minimum number of compression coefficients
   * - ``DevSettings.compressor_decompressor_ratio``
     - Ratio of the compressor size to the decompressor size, in (0, 1]

**Resume parameters:**

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

   * - Parameter
     - Description
   * - ``resume``
     - ``true``: continue the build stored in ``checkpoint_address``
   * - ``starting_from_checkpoint_address``
     - Start the build from a model of this checkpoint (or from this ``.ednn`` model)
   * - ``start_build_from_model_number``
     - Index of that model in the checkpoint, from 0 (``-1`` = last). "Checkpoint N" in the build log and the GUI is index N - 1
   * - ``freeze_structure``
     - ``true``: keep the structure of the starting model and retrain only its weights

.. _cli-tabular-evaluate:

Evaluate Configuration
----------------------

**Root keys:** ``neurecoRegression_evaluate``, ``neurecoClassification_evaluate``
or ``neurecoCompression_evaluate``

.. code-block:: json

   {
       "neurecoRegression_evaluate": {
           "neureco_filename": "./model/regressor.ednn",
           "exc_filenames": ["x_test.csv"],
           "optional_output_reference": ["y_test.csv"],
           "write_model_output_to_directory": "./EvaluationResults"
       }
   }

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

   * - Parameter
     - Description
   * - ``neureco_filename``
     - The model to evaluate: an ``.ednn`` file, or a ``.checkpoint`` file
   * - ``id_neural_network_checkpoint``
     - With a checkpoint file: index of the model, from 0 (``-1`` = last, the default)
   * - ``exc_filenames``
     - List of input files to evaluate
   * - ``optional_output_reference``
     - List of reference output files, one per input file (optional)
   * - ``write_model_output_to_directory``
     - Folder for the predictions: one ``<input name>_output_neureco`` file per input file
   * - ``model_output_format``
     - Format of the prediction files: ``"csv"`` (default), ``"npy"`` or ``"mat"``

Export Commands
---------------

.. code-block:: shell

   neureco Regression exportC ./model/regressor.ednn ./model/regressor.h float64
   neureco Regression exportONNX ./model/regressor.ednn ./model/regressor.onnx float32
   neureco Regression exportVBA ./model/regressor.ednn ./model/regressor.bas float32
   neureco Regression exportFMU ./model/regressor.ednn ./model/regressor.fmu 3

The third argument is the precision: ``float64`` or ``float32``, and also
``float16`` for ONNX. ``exportFMU`` takes a platform flag instead: use ``3``
(Windows and Linux). Exporting requires an *embed* license.

PFS Configuration
=================

Build Configuration
-------------------

**Root key:** ``neurecoPFS_build``

.. code-block:: json

   {
       "neurecoPFS_build": {
           "input_filenames": ["inputs_train.npy"],
           "output_filenames": ["targets_train.npy"],
           "validation_input_filenames": ["inputs_valid.npy"],
           "validation_output_filenames": ["targets_valid.npy"],
           "test_input_filenames": ["inputs_test.npy"],
           "test_output_filenames": ["targets_test.npy"],
           "settings": {
               "validation_percentage": 30,
               "compressed_space_size": 5,
               "min_number_of_enrichments": 10,
               "max_number_of_enrichments": 200,
               "unsuccessful_enrichments": 4,
               "enrichment_rate": 0.2
           },
           "write_model_to": "./model/pfs_model.efnn",
           "checkpoint_address": "./model/pfs_model.checkpoint",
           "write_model_output_to_directory": "./model/BuildingResults"
       }
   }

**PFS parameters:**

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

   * - Parameter
     - Description
   * - ``input_filenames``, ``output_filenames``
     - Lists of training input and output files
   * - ``validation_input_filenames``, ``validation_output_filenames``
     - Lists of validation files (optional)
   * - ``test_input_filenames``, ``test_output_filenames``
     - Lists of test files (optional)
   * - ``settings.validation_percentage``
     - Percentage of the training data kept for validation when no validation files are given
   * - ``settings.compressed_space_size``
     - Dimension of the compressed output space (``reduced_space_dimension`` in Python)
   * - ``settings.min_number_of_enrichments``
     - Minimum number of enrichment steps (``min_enrichment_steps`` in Python)
   * - ``settings.max_number_of_enrichments``
     - Maximum number of enrichment steps (``max_enrichment_steps`` in Python)
   * - ``settings.unsuccessful_enrichments``
     - Unsuccessful enrichment steps before the build stops (``unsuccessful_enrichment_steps`` in Python)
   * - ``settings.enrichment_rate``
     - Parameter addition rate, in (0, 1]
   * - ``resume``
     - ``true``: continue the build stored in ``checkpoint_address``

Evaluate Configuration
----------------------

**Root key:** ``neurecoPFS_evaluate``

.. code-block:: json

   {
       "neurecoPFS_evaluate": {
           "neureco_filename": "./model/pfs_model.efnn",
           "input_filenames": ["inputs_test.npy"],
           "write_model_output_to_directory": "./EvaluationResults"
       }
   }

``neureco_filename`` is the model, ``input_filenames`` the list of input files, and
the predictions are written to ``write_model_output_to_directory``.

Export Command
--------------

.. code-block:: shell

   neureco PFS exportFMU ./model/pfs_model.efnn ./model/pfs_model.fmu 3

The last argument is the platform flag: use ``3`` (Windows and Linux).

Dynamic Configuration
=====================

For both Dynamic templates, the first column of every input and output file is the
time (see :ref:`dynamic-data-preparation`). The examples below use the file layout
of the example ``NonLinearOscillator.zip`` (one excitation, one output), so they run
in the folder where you extract it.

ODE Build Configuration
-----------------------

**Root key:** ``neurecoODE_build``

.. code-block:: json

   {
       "neurecoODE_build": {
           "exc_filenames": [
               "data/train/train_exc_1.csv",
               "data/train/train_exc_2.csv"
           ],
           "output_filenames": [
               "data/train/train_out_1.csv",
               "data/train/train_out_2.csv"
           ],
           "validation_exc_filenames": ["data/valid/valid_exc_1.csv"],
           "validation_output_filenames": ["data/valid/valid_out_1.csv"],
           "test_exc_filenames": ["data/test/test_exc_1.csv"],
           "test_output_filenames": ["data/test/test_out_1.csv"],
           "settings": {
               "valid_percentage": 30,
               "min_hidden_states": 1,
               "max_hidden_states": 3,
               "steady_state_exc": [0.0],
               "steady_state_out": [0.0],
               "input_normalization": {
                   "shift_type": "mean",
                   "scale_type": "l2",
                   "normalize_per_feature": true
               },
               "output_normalization": {
                   "shift_type": "mean",
                   "scale_type": "l2",
                   "normalize_per_feature": true
               }
           },
           "write_model_to": "./model/ode_model.ernn",
           "checkpoint_address": "./model/ode_model.checkpoint",
           "write_model_output_to_directory": "./model/BuildingResults"
       }
   }

**ODE parameters:**

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

   * - Parameter
     - Description
   * - ``exc_filenames``, ``output_filenames``
     - Lists of training excitation (input) and output files, one output file per excitation file
   * - ``validation_exc_filenames``, ``validation_output_filenames``
     - Lists of validation files (optional)
   * - ``test_exc_filenames``, ``test_output_filenames``
     - Lists of test files (optional)
   * - ``settings.valid_percentage``
     - Percentage of the training data kept for validation when no validation files are given
   * - ``settings.min_hidden_states``
     - Minimum number of hidden states
   * - ``settings.max_hidden_states``
     - Maximum number of hidden states (``0`` = no limit)
   * - ``settings.steady_state_exc``
     - Steady-state excitation values, one per excitation, for example ``[0.0]`` (optional; ``[]`` = none)
   * - ``settings.steady_state_out``
     - Steady-state output values, one per output (optional; set both or neither)
   * - ``settings.input_normalization``, ``settings.output_normalization``
     - ``shift_type``, ``scale_type`` and ``normalize_per_feature`` of the excitations and of the outputs
   * - ``resume``
     - ``true``: reload the checkpoint at ``checkpoint_address`` and continue the build where it stopped. A resumed build gives the same models as a build without pause (see :ref:`dynamic-resume`)

The normalization and the steady state sit inside ``settings``.

ODE Evaluate Configuration
--------------------------

**Root key:** ``neurecoODE_evaluate``

.. code-block:: json

   {
       "neurecoODE_evaluate": {
           "ernn_filename": "./model/ode_model.ernn",
           "exc_filenames": ["data/test/test_exc_1.csv"],
           "write_model_output_to_directory": "./EvaluationResults"
       }
   }

``ernn_filename`` is the model, ``exc_filenames`` the list of excitation files to
evaluate, and the predictions are written to ``write_model_output_to_directory``.
Each evaluation uses the steady-state initialization described in
:ref:`ode-evaluating`.

Convolutional Dynamic Build Configuration
-----------------------------------------

**Root key:** ``neurecoConvolutiveDynamic_build``

.. code-block:: json

   {
       "neurecoConvolutiveDynamic_build": {
           "data": {
               "training": {
                   "inputs": [
                       "data/train/train_exc_1.csv",
                       "data/train/train_exc_2.csv"
                   ],
                   "targets": [
                       "data/train/train_out_1.csv",
                       "data/train/train_out_2.csv"
                   ]
               },
               "validation": {
                   "inputs": ["data/valid/valid_exc_1.csv"],
                   "targets": ["data/valid/valid_out_1.csv"]
               },
               "test": {
                   "inputs": ["data/test/test_exc_1.csv"],
                   "targets": ["data/test/test_out_1.csv"]
               },
               "validation_percentage": 30
           },
           "normalizers": {
               "inputs": {
                   "shift_type": "min",
                   "scale_type": "minmax",
                   "normalize_per_feature": true
               },
               "targets": {
                   "shift_type": "min",
                   "scale_type": "minmax",
                   "normalize_per_feature": true
               }
           },
           "settings": {
               "window_size": 32,
               "window_stride": 1,
               "hidden_layer_number": 2,
               "layer_multiplier": 2.0,
               "last_layer_grid_number": 0,
               "tol_last_layer": 0.1,
               "activation_function": "Tanh",
               "padding_mode": "CONSTANT",
               "padding_value": 0.0,
               "use_gpu": false,
               "gpu_id": 0
           },
           "write_model_to": "./model/cnn_model.ecnn",
           "checkpoint_address": "./model/cnn_model.checkpoint",
           "write_model_output_to_directory": "./model/BuildingResults",
           "resume": false
       }
   }

The layout differs from the ODE file: the data files sit under ``data``, as
``inputs`` (excitations) and ``targets`` (outputs) of the ``training``,
``validation`` and ``test`` sets, and the normalization sits under ``normalizers``.

**Convolutional Dynamic parameters:**

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

   * - Parameter
     - Description
   * - ``data.training.inputs``, ``data.training.targets``
     - Lists of training excitation and output files
   * - ``data.validation``, ``data.test``
     - Validation and test files, same layout (optional)
   * - ``data.validation_percentage``
     - Percentage of the training data kept for validation when no validation files are given
   * - ``normalizers.inputs``, ``normalizers.targets``
     - ``shift_type`` (``"none"``, ``"mean"`` or ``"min"``), ``scale_type`` (``"none"``, ``"max"``, ``"minmax"`` or ``"std"``) and ``normalize_per_feature``
   * - ``settings.window_size``, ``settings.window_stride``
     - Window size (at least 3) and training window stride (see :ref:`convolutive-window-stride`)
   * - ``settings.hidden_layer_number``, ``settings.layer_multiplier``, ``settings.last_layer_grid_number``, ``settings.tol_last_layer``
     - Convolutional network settings (see :ref:`convolutive-building`)
   * - ``settings.activation_function``, ``settings.padding_mode``, ``settings.padding_value``
     - Activation function and padding of the convolutional layers
   * - ``settings.use_gpu``, ``settings.gpu_id``
     - Build on a GPU, and the id of the GPU to use
   * - ``resume``
     - ``true``: continue the build stored in ``checkpoint_address`` (see :ref:`dynamic-resume`)

Convolutional Dynamic Evaluate Configuration
--------------------------------------------

**Root key:** ``neurecoConvolutiveDynamic_evaluate``

.. code-block:: json

   {
       "neurecoConvolutiveDynamic_evaluate": {
           "ecnn_filename": "./model/cnn_model.ecnn",
           "exc_filenames": ["data/test/test_exc_1.csv"],
           "write_model_output_to_directory": "./model",
           "model_output_format": "csv"
       }
   }

``ecnn_filename`` is the model and ``exc_filenames`` the list of excitation files to
evaluate. The predictions are written to ``write_model_output_to_directory`` as
``<input name>_ecnn`` files, in the ``model_output_format`` format (``"npy"`` by
default, or ``"csv"``). This folder is created if it does not exist.

Export Commands (Dynamic)
-------------------------

.. code-block:: shell

   neureco ODE exportFMU ./model/ode_model.ernn ./model/ode_model.fmu 3
   neureco ConvolutiveDynamic exportFMU ./model/cnn_model.ecnn ./model/cnn_model.fmu 3

The last argument is the platform flag: use ``3`` (Windows and Linux).

File Formats
============

Supported data file formats:

- **CSV**: comma or semicolon delimited (``.csv``)
- **NumPy**: binary array format (``.npy``)
- **MATLAB**: MAT-files (``.mat``)

CSV Format
----------

.. code-block:: text

   feature1;feature2;feature3
   1.0;2.0;3.0
   4.0;5.0;6.0
   7.0;8.0;9.0

- The first row can be a header (optional)
- Delimiter: ``;`` or ``,``

Complex Values in CSV (PFS)
---------------------------

For PFS output files, complex numbers can be written as:

- ``0.1+0.2j``
- ``(0.1+0.2j)``
- ``(0.1,0.2)``

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

Common Issues
-------------

**"File not found" error:**

- Check that the file paths are correct
- Use forward slashes (``/``) or escaped backslashes (``\\``)
- Relative paths are relative to the folder of the configuration file

**Configuration error:**

- Verify the JSON syntax (use a JSON validator)
- Check that the root key matches the template and the command
- Check the spelling of every field name: unknown fields are ignored

**"Shape mismatch" error:**

- Input and output files must have the same number of samples
- Check that the data dimensions match the model