Harmonic Regression

This page documents the structured harmonic baseline used to model periodic TE components directly from angular position and operating-condition context.

Harmonic regression baseline for TE prediction over angular position.

class scripts.models.harmonic_regression.HarmonicRegression(input_size, output_size=1, harmonic_order=12, coefficient_mode='static', harmonic_index_list=None)[source]

Structured harmonic regressor for periodic TE components.

Parameters:

  • input_size (int)

  • output_size (int)

  • harmonic_order (int)

  • coefficient_mode (str)

  • harmonic_index_list (Sequence[int] | None)

__init__(input_size, output_size=1, harmonic_order=12, coefficient_mode='static', harmonic_index_list=None)[source]

Initialize the harmonic regression baseline.

Parameters:

  • input_size (int) – Total input feature count including angular position and operating-condition features.

  • output_size (int) – Regression target count. Scalar output keeps the legacy parameter layout for checkpoint compatibility; larger values use one harmonic coefficient set per output channel.

  • harmonic_order (int) – Highest harmonic order used in the Fourier-style expansion of the angular position.

  • coefficient_mode (str) – Coefficient parameterization mode. Supported values are static and linear_conditioned.

  • harmonic_index_list (Sequence[int] | None) – Optional explicit harmonic list. When omitted, the model uses the backward-compatible contiguous basis 1..harmonic_order. When provided, 0 represents the DC/bias term and positive values create sine/cosine feature pairs.

Return type:

None

static resolve_harmonic_index_list(harmonic_order, harmonic_index_list)[source]

Resolve and validate the configured harmonic basis indices.

Parameters:

  • harmonic_order (int) – Contiguous harmonic order used when no explicit harmonic index list is provided.

  • harmonic_index_list (Sequence[int] | None) – Optional explicit harmonic index sequence.

Returns:

Sorted unique harmonic indices used by the model.

Return type:

list[int]

build_harmonic_feature_tensor(angular_position_deg)[source]

Build the harmonic basis evaluated at the given angular positions.

Parameters:

angular_position_deg (Tensor) – Angular position tensor in degrees with shape (batch_size, 1).

Returns:

Harmonic design matrix containing the bias term plus sine and cosine features for each configured harmonic order.

Return type:

torch.Tensor

resolve_coefficient_tensor(normalized_condition_tensor)[source]

Resolve the harmonic coefficient tensor for each batch item.

Parameters:

normalized_condition_tensor (Tensor) – Normalized operating-condition feature tensor excluding the raw angle column.

Returns:

Batch-aligned coefficient tensor used to weight the harmonic basis.

Return type:

torch.Tensor

forward_with_input_context(input_tensor, normalized_input_tensor)[source]

Predict TE using raw angle context plus normalized conditions.

Parameters:

  • input_tensor (Tensor) – Raw input tensor whose first column is the physical angular position in degrees.

  • normalized_input_tensor (Tensor) – Normalized input tensor used for the conditioning features.

Returns:

TE prediction tensor with shape (batch_size, output_size).

Return type:

torch.Tensor