NSSDN

class cultivars.experimental.spectral.NSSDN(endog, *, exog=None, time=None, k=16, state_dim=128, alignment='filtered', transition='gru', positive_frequency=True, ordered_frequency=False, gating=True, objective='mse', delta=_HUBER_DELTA, penalties=None, schedule=None, scaling='minmax', seed=None, device='cpu')

Non-Stationary Spectral Decomposition Network specification.

The immutable statement of the model, validated at construction and estimated by fit(). The defaults are the configuration of the IEEE-ORSS DGS10 experiments: sixteen components, a 128-dimensional GRU state, positive frequencies, gating, the filtered alignment, mean squared error on a min-max scaled series, and the two-stage Adam schedule with amplitude and frequency drift penalties. With no covariates that network has 58,849 trainable parameters, the count of the published run.

Parameters:

• endog (ArrayLike) – The series, one-dimensional, at least three observations.

• exog (ArrayLike | None) – Optional (n, p) covariates known at each t, used as given (no scaling). A fit with covariates needs them again at forecast time.

• time (ArrayLike | None) – Optional strictly increasing grid; defaults to 0 .. n - 1. Irregular spacing enters the phase recursion and, under the time-aware transition, the dynamics.

• k (int) – Number of sinusoidal components.

• state_dim (int) – Latent dimension d.

• alignment (str) – "filtered" (the published run: the emission at t conditions on y_t) or "predicted" (it conditions on y_{t-1}, so the network trains as a one-step forecaster).

• transition (str) – "gru" or "timeaware".

• positive_frequency (bool) – Softplus the frequency head so phase always advances.

• ordered_frequency (bool) – Parameterize frequencies as cumulative positive gaps inside the Nyquist band, so omega_{t,1} < ... < omega_{t,K} at every t and the components are identified without permutation. Off by default to reproduce the published run.

• gating (bool) – Add the sigmoid gate head.

• objective (str) – "mse" or "huber".

• delta (float) – Huber threshold on the scaled residual.

• penalties (Penalties | None) – Penalties for stages that carry none.

• schedule (tuple[Stage, ...] | None) – Tuple of Stage; the published two stages by default.

• scaling (str) – "minmax" or "none".

• seed (int | None) – Initialization seed; None leaves the fit unreproducible.

• device (str) – Torch device string.

Raises:

• SpecificationError – If any option is outside its admissible set.

• DimensionError – If the data are mis-shaped or misaligned.

• NumericalError – If the data contain non-finite values, or training diverges.

Note

Training is one full-sequence gradient per step through the whole sample, so cost scales with n times the schedule length; the published run is 3,000 steps over 9,186 daily observations. Under the GRU transition the teacher-forced pass is a single recurrent call rather than a Python loop.

See also

• NSSDNResult – what fit() returns.

• Stage, Penalties – the schedule records.

Example

>>> import numpy as np
>>> y = np.sin(0.3 * np.arange(200.0)) + 0.01 * np.arange(200.0)
>>> model = NSSDN(y, k=2, state_dim=8, schedule=(Stage(1e-2, 30),), seed=0)
>>> model.k, model.alignment, model.transition, len(model.schedule)
(2, 'filtered', 'gru', 1)
>>> NSSDN(y, transition="lstm")
Traceback (most recent call last):
    ...
ns_sdn.exceptions.SpecificationError: transition must be one of 'gru', 'timeaware'; ...

Attributes

alignment	What the emission at t conditions on.
device	The torch device.
endog	The validated series.
exog	The validated covariates, or None.
exog_dim	Number of covariate columns.
gating	Whether the gate head is present.
k	Number of components.
nobs_total	Observations in the sample, before the one-step shift.
objective	The prediction loss.
ordered_frequency	Whether frequencies are strictly increasing in k.
penalties	Model-level penalty weights.
positive_frequency	Whether frequencies are constrained positive.
scaling	The scaling choice.
schedule	The training stages.
seed	The initialization seed.
state_dim	Latent dimension.
time	The time grid.
transition	The transition kind.

Methods

fit()

Train the network on the sample and return the fitted result.