Dynamic API Reference#

Complete API reference for NeurEco Dynamic models: ODE and ConvolutiveDynamic.

On this page

Import
ODE
- Constructor
- Methods
ODEBuildConfig
ConvolutiveDynamic
- Constructor
- Methods
ConvolutiveDynamicBuildConfig
Example Usage

Import #

from NeurEco import NeurEcoDynamic as dyn

ODE #

class dyn.ODE

ODE-based model for time-series prediction. Learns hidden states to capture system dynamics.

File extension: .ernn

Constructor #

model = dyn.ODE(dll_path=None)

Parameters:

dll_path (str, optional) — Path to NeurEco binaries

Methods #

build#

status = model.build(config)

Train the ODE model.

Parameters:

config (ODEBuildConfig) — Build configuration

Returns: int — Status code (0 = success)

evaluate#

predictions = model.evaluate(
    excitations=None,
    init_excitations=None,
    init_outputs=None,
    *,
    time=None,
    init_time=None,
)

Run inference on time-series data.

Parameters:

excitations (ndarray or list) — Input/excitation arrays with time in the first column (shape (n_samples, 1 + n_inputs) or a list of such arrays)
init_excitations (ndarray or list, optional) — Initialization inputs, time in the first column
init_outputs (ndarray or list, optional) — Initialization outputs, time in the first column (required for explicit init)
time (ndarray or list, optional, keyword-only) — Deprecated. Separate time array(s); emits a DeprecatedParameterWarning and returns predictions without a leading time column
init_time (ndarray or list, optional, keyword-only) — Deprecated. Separate initialization time values

Returns: ndarray or list — Predicted outputs, time-first (time in column 0) when excitations carries the time column

Note: If initialization not provided, uses steady-state initialization. The deprecated separate-time form returns predictions without a leading time column.

The 4.x positional call evaluate(time, excitations, init_time, init_excitations, init_outputs) is still accepted for backward compatibility. It emits a DeprecatedParameterWarning and, like the time= keyword form, returns predictions without a leading time column.

compute_error#

error = dyn.ODE.compute_error(predictions, targets)

Compute L2 relative error. Static method.

Parameters:

predictions (ndarray) — Model predictions
targets (ndarray) — Ground truth

Returns: float — L2 relative error

load / save#

model.load(path)
model.save(path)

Load or save model.

Parameters:

path (str) — File path

Returns: int — Status code

get_input_count / get_output_count#

n_inputs = model.get_input_count()
n_outputs = model.get_output_count()

Get number of input (excitation) and output features.

Returns: int

get_state_count#

n_states = model.get_state_count()

Get number of hidden states learned by the model.

Returns: int

get_number_of_init_tsteps#

n_init = model.get_number_of_init_tsteps()

Get number of time steps required for initialization.

Returns: int

get_steady_input / get_steady_output#

steady_in = model.get_steady_input()
steady_out = model.get_steady_output()

Get steady-state input/output values.

Returns: ndarray

sensitivity#

sens = model.sensitivity(
    time,
    excitations,
    id_output,
    initialization_time=None,
    initialization_excitations=None,
    initialization_outputs=None,
)

Compute sensitivity of output with respect to inputs.

Note

Unlike evaluate, sensitivity takes the time as a separate time argument (it does not use the combined time-in-first-column form).

Parameters:

time (ndarray) — Time array
excitations (ndarray) — Excitation (input) array
id_output (int) — Output index to analyze
initialization_time / initialization_excitations / initialization_outputs — Optional initialization arrays

Returns: ndarray — Sensitivity values

export_fmu#

status = model.export_fmu(path)

Export to FMU format.

Parameters:

path (str) — Output .fmu file path

Returns: int — Status code

Note

Requires NeurEco Embed license.

get_number_of_networks_from_checkpoint#

n = model.get_number_of_networks_from_checkpoint(path)

Get number of models saved in a checkpoint.

Parameters:

path (str) — Checkpoint path

Returns: int — Number of checkpointed models

load_model_from_checkpoint#

model.load_model_from_checkpoint(path, model_index)

Load a specific model from checkpoint.

Parameters:

path (str) — Checkpoint path
model_index (int) — Model index (0-based)

The build log and the GUI number checkpoints from 1: “Checkpoint N” there is model_index N - 1 here.

delete#

model.delete()

Free native memory. Always call when done.

ODEBuildConfig #

# Each array: column 0 = time, remaining columns = excitations / outputs.
config = dyn.ODEBuildConfig(
    # Required (time-first arrays)
    train_exc_list,
    train_out_list,
    # Optional (time-first arrays)
    valid_exc_list=None,
    valid_out_list=None,
    test_exc_list=None,
    test_out_list=None,
    valid_percentage=30,
    write_model_to="model",
    checkpoint_address="ckpt",
    inputs_shifting="mean",
    inputs_scaling="l2",
    outputs_shifting="mean",
    outputs_scaling="l2",
    inputs_normalize_per_feature=True,
    outputs_normalize_per_feature=True,
    steady_state_exc=None,
    steady_state_out=None,
    min_hidden_states=1,
    max_hidden_states=0,
    resume=False,
)

Parameters:

Parameter	Default	Description
`train_exc_list`	(required)	List of excitation (input) arrays; column 0 is time, remaining columns are inputs
`train_out_list`	(required)	List of output arrays; column 0 is time, remaining columns are outputs
`valid_exc_list`	`None`	Validation excitation arrays (time in the first column)
`valid_out_list`	`None`	Validation output arrays (time in the first column)
`valid_percentage`	`30`	Validation split (if no validation data)
`steady_state_exc`	`None`	Steady-state input values (1D array)
`steady_state_out`	`None`	Steady-state output values (1D array)
`min_hidden_states`	`1`	Minimum hidden states
`max_hidden_states`	`0`	Maximum hidden states (0 = no limit)
`inputs_shifting`	`"mean"`	Input shift: `"none"`, `"mean"`
`inputs_scaling`	`"l2"`	Input scale: `"none"`, `"l2"`, `"max"`
`outputs_shifting`	`"mean"`	Output shift (same options as `inputs_shifting`)
`outputs_scaling`	`"l2"`	Output scale (same options as `inputs_scaling`)
`inputs_normalize_per_feature`	`True`	Normalize each input feature independently
`outputs_normalize_per_feature`	`True`	Normalize each output feature independently
`resume`	`False`	`True`: continue the build stored in `checkpoint_address` where it stopped. A resumed build gives the same models as a build without pause (see Resuming from Checkpoint)

Note

Deprecated separate-time parameters. train_time_list, valid_time_list and test_time_list (lists of 1-D time arrays passed alongside pure excitation/output arrays) remain accepted for backward compatibility but emit a DeprecatedParameterWarning. Prefer placing the time in the first column of each excitation and output array.

ConvolutiveDynamic #

class dyn.ConvolutiveDynamic

Convolutional Dynamic model for time-series prediction: a convolutional neural network applied to a sliding window of past inputs. In the GUI, this is the CNN Dynamic template.

File extension: .ecnn

Constructor #

model = dyn.ConvolutiveDynamic(dll_path=None)

Methods #

Same methods as ODE, with these additions/differences:

get_window_size#

w_size = model.get_window_size()

Get the window size: the number of time steps the network reads to make one prediction.

Returns: int

Note: Predictions start at time step window_size - 1 (the window provides context for the first prediction).

evaluate#

Same as ODE, but no initialization parameters needed. excitations carries the time in its first column and predictions are returned time-first:

predictions = model.evaluate(excitations)

The model predicts every time step from the window_size-th one on, whatever the window_stride used for training.

ConvolutiveDynamicBuildConfig #

# Each array: column 0 = time, remaining columns = excitations / outputs.
config = dyn.ConvolutiveDynamicBuildConfig(
    # Required (time-first arrays)
    train_exc_list,
    train_out_list,
    # Optional (same as ODE plus:)
    window_size=32,
    # ... other parameters same as ODEBuildConfig
)

Additional Parameters:

window_size (int) — Convolution window size, at least 3 (default: 32)
window_stride (int) — Training data only: step between two consecutive training windows (default: 1). The model still predicts every time step.
resume (bool) — True: continue the build stored in checkpoint_address instead of starting a new one (default: False). See Resuming from Checkpoint.

The network architecture parameters (hidden_layer_number, layer_multiplier, last_layer_grid_number, tol_last_layer) and the padding parameters are described in Building Convolutional Dynamic Models.

The deprecated train_time_list / valid_time_list / test_time_list separate-time parameters behave the same way as for ODEBuildConfig.

Important

ConvolutiveDynamic requires uniformly spaced time steps within and across all trajectories. ODE does not have this requirement — its time arrays only need to be sorted in strictly increasing order (non-uniform spacing is allowed).

Example Usage #

ODE Model #

from NeurEco import NeurEcoDynamic as dyn
import numpy as np

# Prepare data (lists of arrays for multiple trajectories, time in column 0)
t = np.arange(0, 10, 0.01)
train_exc = [np.column_stack([t, np.random.randn(1000, 3)])]   # time + 3 inputs
train_out = [np.column_stack([t, np.random.randn(1000, 2)])]   # time + 2 outputs

# Build
# Each array: column 0 = time, remaining columns = excitations / outputs.
model = dyn.ODE()
config = dyn.ODEBuildConfig(
    train_exc_list=train_exc,
    train_out_list=train_out,
    write_model_to="./ode_model.ernn"
)
model.build(config)

# Evaluate (steady-state init)
# test_exc has time in its first column; predictions are returned time-first.
predictions = model.evaluate(test_exc)

# Evaluate with explicit initialization
n_init = model.get_number_of_init_tsteps()
predictions = model.evaluate(
    test_exc[n_init-1:],
    init_excitations=test_exc[:n_init],
    init_outputs=test_out[:n_init]
)

model.delete()

Convolutional Dynamic Model #

from NeurEco import NeurEcoDynamic as dyn
import numpy as np

# Build
# Each array: column 0 = time, remaining columns = excitations / outputs.
model = dyn.ConvolutiveDynamic()
config = dyn.ConvolutiveDynamicBuildConfig(
    train_exc_list=train_exc,
    train_out_list=train_out,
    window_size=32,
    write_model_to="./conv_model.ecnn"
)
model.build(config)

# Evaluate
# test_exc has time in its first column; predictions are returned time-first.
predictions = model.evaluate(test_exc)

# Note: predictions start at time step (window_size - 1)
w_size = model.get_window_size()
aligned_ref = test_out[w_size - 1:]
# compute_error takes outputs only, so drop the leading time column from both.
error = model.compute_error(predictions[:, 1:], aligned_ref[:, 1:])

model.delete()

Parametric ODE Model #

For parameters that stay constant within a trajectory but vary between experiments:

# Replicate constant parameter across all time steps
k_value = 2.5  # Constant parameter
n_steps = 1000

# Create excitation with parametric input (time in column 0)
time_column = np.linspace(0, 10, n_steps)
k_column = np.full(n_steps, k_value)
force_column = np.sin(np.linspace(0, 10, n_steps))
excitation = np.column_stack([time_column, k_column, force_column])

# Build and evaluate as normal

NeurEco User Manual

Dynamic API Reference

Contents

Dynamic API Reference#

Import #

ODE #

Constructor #

Methods #

build#

evaluate#

compute_error#

load / save#

get_input_count / get_output_count#

get_state_count#

get_number_of_init_tsteps#

get_steady_input / get_steady_output#

sensitivity#

export_fmu#

get_number_of_networks_from_checkpoint#

load_model_from_checkpoint#

delete#

ODEBuildConfig #

ConvolutiveDynamic #

Constructor #

Methods #

get_window_size#

evaluate#

ConvolutiveDynamicBuildConfig #

Example Usage #

ODE Model #

Convolutional Dynamic Model #

Parametric ODE Model #