Harmonic-Kinematic PINN Network

Wave 5.2 Phase 2 introduced the first repository-owned full-PINN training surface for angular oscillator, periodic-closure, and Bauer-anchor residuals. The canonical eight-run campaign completed successfully, but the accepted periodic MLP and GRU baselines remained superior in the bounded curve-first comparison. No Phase 2 physics constraint is therefore promoted into Phase 3.

Phase 3 proceeds with independently initialized quasi-static compliance and elastic-offset formulations. The Phase 2 implementation remains available as an inspectable negative-result benchmark and as reusable automatic- differentiation infrastructure.

Harmonic and kinematic PINN components for Wave 5.2 Phase 2.

class scripts.models.harmonic_kinematic_pinn_network.HarmonicKinematicPinnNetwork(input_size, harmonic_index_list, condition_hidden_size, condition_latent_size, component_hidden_size, output_size=1, head_mode='implicit_pinn', activation_name='Tanh', dropout_probability=0.0, use_layer_norm=False, analytical_anchor_feature_mean=None, analytical_anchor_feature_scale=None, analytical_anchor_coefficient_matrix=None)[source]

Bases: Module

Direction-specific angular-oscillator PINN for TE curves.

The model separates an angle-independent offset from one component per configured output order. In explicit_fourier mode, condition-dependent sine and cosine coefficients form the parameter-matched non-PINN control. In implicit_pinn mode, each component head may depart from the exact harmonic law and is regularized through a differentiable angular oscillator residual.

Parameters:

  • input_size (int)

  • harmonic_index_list (list[int])

  • condition_hidden_size (list[int])

  • condition_latent_size (int)

  • component_hidden_size (list[int])

  • output_size (int)

  • head_mode (str)

  • activation_name (str)

  • dropout_probability (float)

  • use_layer_norm (bool)

  • analytical_anchor_feature_mean (list[float] | None)

  • analytical_anchor_feature_scale (list[float] | None)

  • analytical_anchor_coefficient_matrix (list[list[float]] | None)

SUPPORTED_HEAD_MODE_SET = {'explicit_fourier', 'implicit_pinn'}
__init__(input_size, harmonic_index_list, condition_hidden_size, condition_latent_size, component_hidden_size, output_size=1, head_mode='implicit_pinn', activation_name='Tanh', dropout_probability=0.0, use_layer_norm=False, analytical_anchor_feature_mean=None, analytical_anchor_feature_scale=None, analytical_anchor_coefficient_matrix=None)[source]

Initialize the Phase 2 harmonic-kinematic model.

Parameters:

  • input_size (int) – Input width including output angle in column zero.

  • harmonic_index_list (list[int]) – Positive output orders represented explicitly.

  • condition_hidden_size (list[int]) – Hidden widths of the condition encoder.

  • condition_latent_size (int) – Width of the causal condition embedding.

  • component_hidden_size (list[int]) – Hidden widths of each implicit component.

  • output_size (int) – Scalar TE output count. Phase 2 requires one.

  • head_mode (str) – explicit_fourier control or implicit_pinn.

  • activation_name (str) – Activation used in the condition and component networks.

  • dropout_probability (float) – Hidden dropout probability.

  • use_layer_norm (bool) – Whether hidden layers use layer normalization.

  • analytical_anchor_feature_mean (list[float] | None) – Optional three-variable Bauer surface normalization mean.

  • analytical_anchor_feature_scale (list[float] | None) – Optional three-variable Bauer surface normalization scale.

  • analytical_anchor_coefficient_matrix (list[list[float]] | None) – Optional complete-quadratic coefficient surface with offset and sine/cosine columns.

Return type:

None

compute_auxiliary_output_dictionary(input_tensor, normalized_input_tensor)[source]

Expose inspectable offset and harmonic component predictions.

Parameters:

  • input_tensor (Tensor)

  • normalized_input_tensor (Tensor)

Return type:

dict[str, Tensor]

compute_analytical_anchor_prediction_tensor(input_tensor)[source]

Evaluate the frozen Phase 1 Bauer surface in physical TE degrees.

Parameters:

input_tensor (Tensor)

Return type:

Tensor

static compute_normalized_oscillator_residual(component_tensor, theta_rad_tensor, harmonic_index)[source]

Compute first derivative, second derivative, and normalized residual.

Parameters:

  • component_tensor (Tensor)

  • theta_rad_tensor (Tensor)

  • harmonic_index (int)

Return type:

tuple[Tensor, Tensor, Tensor]

compute_physics_residual_dictionary(input_tensor, normalized_input_tensor, maximum_collocation_points=256, maximum_boundary_conditions=16, target_mean_tensor=None, target_std_tensor=None)[source]

Compute target-free oscillator and periodic-boundary losses.

Parameters:

  • input_tensor (Tensor)

  • normalized_input_tensor (Tensor)

  • maximum_collocation_points (int)

  • maximum_boundary_conditions (int)

  • target_mean_tensor (Tensor | None)

  • target_std_tensor (Tensor | None)

Return type:

dict[str, Tensor]

forward_with_input_context(input_tensor, normalized_input_tensor)[source]

Predict normalized TE with raw angular context.

Parameters:

  • input_tensor (Tensor)

  • normalized_input_tensor (Tensor)

Return type:

Tensor

forward(normalized_input_tensor)[source]

Fallback forward path when raw context is unavailable.

Parameters:

normalized_input_tensor (Tensor)

Return type:

Tensor