Residual Harmonic Network

This page documents the hybrid TE model that combines a structured harmonic branch with a learned neural residual branch.

Residual harmonic TE model combining structured and neural branches.

class scripts.models.residual_harmonic_network.ResidualHarmonicNetwork(input_size, output_size=1, harmonic_order=12, coefficient_mode='static', residual_hidden_size=None, residual_activation_name='GELU', residual_dropout_probability=0.10, residual_use_layer_norm=True, freeze_structured_branch=False)[source]

Hybrid TE model with harmonic prior plus neural residual correction.

Parameters:

  • input_size (int)

  • output_size (int)

  • harmonic_order (int)

  • coefficient_mode (str)

  • residual_hidden_size (list[int] | None)

  • residual_activation_name (str)

  • residual_dropout_probability (float)

  • residual_use_layer_norm (bool)

  • freeze_structured_branch (bool)

__init__(input_size, output_size=1, harmonic_order=12, coefficient_mode='static', residual_hidden_size=None, residual_activation_name='GELU', residual_dropout_probability=0.10, residual_use_layer_norm=True, freeze_structured_branch=False)[source]

Initialize the residual harmonic TE model.

Parameters:

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

  • output_size (int) – Regression target count.

  • harmonic_order (int) – Highest harmonic order used by the structured branch.

  • coefficient_mode (str) – Harmonic coefficient parameterization mode passed to the structured branch.

  • residual_hidden_size (list[int] | None) – Hidden-layer widths for the residual neural branch.

  • residual_activation_name (str) – Activation function used by the residual branch.

  • residual_dropout_probability (float) – Dropout probability in the residual branch.

  • residual_use_layer_norm (bool) – Whether the residual branch uses layer normalization.

  • freeze_structured_branch (bool) – Whether to freeze the structured branch parameters during optimization.

Return type:

None

forward_with_input_context(input_tensor, normalized_input_tensor)[source]

Predict TE as structured harmonic output plus residual correction.

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 by the residual branch and structured conditioning path.

Returns:

Final TE prediction tensor combining both branches.

Return type:

torch.Tensor

compute_auxiliary_output_dictionary(input_tensor, normalized_input_tensor)[source]

Expose branch-level outputs for diagnostics and metric logging.

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 by both branches.

Returns:

Structured branch output, residual branch output, and final combined prediction tensor.

Return type:

dict[str, torch.Tensor]