Harmonic Residual Offset Network

Harmonic shape plus causal residual-offset network for Wave 3.2.

class scripts.models.harmonic_residual_offset_network.HarmonicResidualOffsetNetwork(input_size, output_size=1, harmonic_order=12, coefficient_mode='linear_conditioned', harmonic_index_list=None, offset_hidden_size=96, offset_num_layers=2, offset_dropout_probability=0.10, offset_bidirectional=False, offset_readout_position='center', offset_scale=1.0, freeze_structured_branch=False)[source]

Bases: Module

TE model with structured harmonic shape plus causal offset correction.

Parameters:

  • input_size (int)

  • output_size (int)

  • harmonic_order (int)

  • coefficient_mode (str)

  • harmonic_index_list (list[int] | None)

  • offset_hidden_size (int)

  • offset_num_layers (int)

  • offset_dropout_probability (float)

  • offset_bidirectional (bool)

  • offset_readout_position (str)

  • offset_scale (float)

  • freeze_structured_branch (bool)

__init__(input_size, output_size=1, harmonic_order=12, coefficient_mode='linear_conditioned', harmonic_index_list=None, offset_hidden_size=96, offset_num_layers=2, offset_dropout_probability=0.10, offset_bidirectional=False, offset_readout_position='center', offset_scale=1.0, freeze_structured_branch=False)[source]

Initialize the harmonic residual-offset probe.

Parameters:

  • input_size (int) – Raw sequence feature count, including angular position as the first feature.

  • output_size (int) – Regression target count. Scalar output is used for deterministic runs; probabilistic Wave 4 series heads use multiple output channels while still selecting one deterministic curve in the training module.

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

  • coefficient_mode (str) – Harmonic coefficient parameterization mode.

  • harmonic_index_list (list[int] | None) – Optional explicit harmonic list. 0 keeps the existing DC convention and positive entries create sine/cosine pairs.

  • offset_hidden_size (int) – Recurrent hidden size for the residual-offset branch.

  • offset_num_layers (int) – Recurrent layer count for the residual-offset branch.

  • offset_dropout_probability (float) – Dropout probability used by the residual-offset branch.

  • offset_bidirectional (bool) – Whether the residual-offset branch is bidirectional. Deployable Wave 3.2 runs should keep this disabled.

  • offset_readout_position (str) – Sequence readout position used by both branches.

  • offset_scale (float) – Multiplicative scale applied to the residual-offset branch before summing with the harmonic prediction.

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

Return type:

None

resolve_readout_feature_tensor(sequence_tensor)[source]

Extract the point feature tensor used by the harmonic branch.

Parameters:

sequence_tensor (Tensor)

Return type:

Tensor

compute_auxiliary_output_dictionary(input_tensor, normalized_input_tensor)[source]

Expose harmonic, residual-offset, and final prediction tensors.

Parameters:

  • input_tensor (Tensor)

  • normalized_input_tensor (Tensor)

Return type:

dict[str, Tensor]

forward_with_input_context(input_tensor, normalized_input_tensor)[source]

Predict normalized TE from harmonic shape plus causal offset.

Parameters:

  • input_tensor (Tensor)

  • normalized_input_tensor (Tensor)

Return type:

Tensor

forward(normalized_input_tensor)[source]

Run inference from normalized sequence inputs only.

Parameters:

normalized_input_tensor (Tensor)

Return type:

Tensor