CLI Reference#

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

On this page

Overview #

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

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

Templates:

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 Backend Names.

Commands:

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 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 Tabular examples), write the Tabular build configuration to build.conf and the Tabular evaluate configuration to eval.conf, then run:

# 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:

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

Root keys:

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.

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:

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 #

Build Configuration #

Root keys: neurecoRegression_build, neurecoClassification_build or neurecoCompression_build

{
    "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:

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 The Regularization Coefficient)
`DevSettings.final_learning`	`true` or `false`: run the final learning steps (see 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 Field Output vs. Per-Feature Normalization)

Compression parameters:

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:

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

Evaluate Configuration #

Root keys: neurecoRegression_evaluate, neurecoClassification_evaluate or neurecoCompression_evaluate

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

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 #

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

{
    "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:

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

{
    "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 #

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 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

{
    "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:

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 Resuming from Checkpoint)

The normalization and the steady state sit inside settings.

ODE Evaluate Configuration #

Root key: neurecoODE_evaluate

{
    "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 Evaluating ODE Models.

Convolutional Dynamic Build Configuration #

Root key: neurecoConvolutiveDynamic_build

{
    "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:

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 Window Size and Stride)
`settings.hidden_layer_number`, `settings.layer_multiplier`, `settings.last_layer_grid_number`, `settings.tol_last_layer`	Convolutional network settings (see Building Convolutional Dynamic Models)
`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 Resuming from Checkpoint)

Convolutional Dynamic Evaluate Configuration #

Root key: neurecoConvolutiveDynamic_evaluate

{
    "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)#

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 #

feature1;feature2;feature3
0;2.0;3.0
0;5.0;6.0
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

NeurEco User Manual

CLI Reference

Contents

CLI Reference#

Overview #

Quick Start #

Configuration Files #

Backend Names #

Tabular Configuration #

Build Configuration #

Evaluate Configuration #

Export Commands #

PFS Configuration #

Build Configuration #

Evaluate Configuration #

Export Command #

Dynamic Configuration #

ODE Build Configuration #

ODE Evaluate Configuration #

Convolutional Dynamic Build Configuration #

Convolutional Dynamic Evaluate Configuration #

Export Commands (Dynamic)#

File Formats #

CSV Format #

Complex Values in CSV (PFS)#

Troubleshooting #

Common Issues #