Separate IRF truncation from smoothing and tapering

Previously, truncating the radiation impulse response function (RIRF) was bundled into the TaperedDirect mode -- you couldn't shorten the kernel without also enabling smoothing and tapering. Excitation IRF truncation was buried inside the irregular wave settings.

Introduce three independent, composable controls:

1. Excitation truncation time -- shorten the excitation IRF to ±T s
2. Radiation truncation time -- shorten the RIRF to [0, T] s
3. Kernel processing -- optionally smooth and/or taper the RIRF

Each can be used on its own or combined. All three are exposed via both the C++ API (SetExcitationTruncationTime, SetRadiationTruncationTime, SetRadiationKernelProcessing) and YAML configuration. Truncation works regardless of wave type.

YAML schema changes:
Old: convolution.mode, convolution.taper.end_time
New: excitation.truncation_time, radiation.truncation_time, radiation.smoothing, radiation.taper

Additional quality improvements:
- ExcitationRampType moved to hydrochrono::waves namespace (kLinear, kCosine)
- Frequency defaults extracted to named constants in IrregularWaveParams
- SG filter coefficients documented with citation, constexpr std::array
- Embed RadiationKernelProcessing directly in YAMLHydroData (was 7 flat fields)

Author: dav-og

data/demos/run_hydrochrono/f3of/decay_dt3/inputs/f3of_decay.hydro.yaml

@@ -10,16 +10,14 @@ hydrodynamics:
   waves:
     type: still
 
-  # System-wide convolution options
-  convolution:
-    mode: TaperedDirect            # Baseline | TaperedDirect
+  radiation:
+    method: rirf_convolution
     smoothing:
-      type: savitzky_golay         # savitzky_golay | moving_average
-      window_length: 5             # odd >= 3 (moving_average uses this; SG is fixed to quadratic, window=5)
+      type: sg                     # sg | moving_average
+      window_length: 5             # odd >= 3
     taper:
-      start_percent: 0.8           # start taper at 80% of total time series (taper last 20%)
-      end_percent: 1.0             # end taper at 100% of total time series
+      start_percent: 0.8           # start taper at 80% of RIRF length
+      end_percent: 1.0             # end taper at 100% of RIRF length
       final_amplitude: 0.0         # final amplitude (0.0 = zero, 1.0 = no change)
-      end_time: -1.0              # truncate RIRF at this time (seconds), -1.0 = use full length
     diagnostics:
       export_csv: true             # per-body CSV for representative channel (step,time,k_before,k_after)

data/yaml/rm3/rm3_mooring.hydro.yaml

@@ -7,7 +7,16 @@ hydrodynamics:
       h5_file: hydroData/rm3.h5
 
   waves:
-    type: still
+    type: irregular
+    eta_file: ../../verification/rm3_mooring/inputs/eta_rm3_mooring.txt
+    ramp_duration: 40.0
+    ramp_type: cosine
+    frequency_min: 0.001
+    frequency_max: 1.0
+    nfrequencies: 1000
+
+  excitation:
+    truncation_time: 20.0
 
   moordyn:
     enabled: true

include/hydroc/config/hydro_config.h

@@ -11,6 +11,7 @@
 #ifndef HYDROC_CONFIG_HYDRO_CONFIG_H
 #define HYDROC_CONFIG_HYDRO_CONFIG_H
 
+#include <hydroc/radiation/radiation_types.h>
 #include <string>
 #include <vector>
 #include <array>
@@ -23,15 +24,6 @@ struct HydroBody {
     std::string h5_file = "";
     bool include_excitation = true;
     bool include_radiation = true;
-    std::string radiation_calculation = "convolution";  // "convolution" or "state_space"
-    // Optional convolution mode for radiation kernel preprocessing: "Baseline" (default) or "TaperedDirect"
-    std::string radiation_convolution_mode = "Baseline";
-    // Optional TaperedDirect tuning
-    std::string td_smoothing = "sg";            // "sg" or "moving_average"
-    int td_window_length = 5;                    // odd >= 3
-    double td_rms_threshold_factor = 0.02;       // e.g. 0.02
-    double td_taper_fraction_remaining = 0.25;   // e.g. 0.25
-    bool td_export_plot_csv = false;             // export CSV for before/after
     // TODO: Add nonlinear buoyancy fields
     // TODO: Add drag coefficient fields
 };
@@ -49,6 +41,14 @@ struct WaveSettings {
     int seed = -1; // optional irregular seed; -1 means unset
     // Sweep support (expanded values) for period; if empty, use 'period'
     std::vector<double> period_values;
+    // Elevation import (if non-empty, overrides spectral generation)
+    std::string eta_file;
+    // Excitation ramp shape: "linear" (default) or "cosine" (WEC-Sim convention)
+    std::string ramp_type    = "linear";
+    double ramp_duration     = 0.0;   // Ramp duration [s]; 0 = no ramp (overrides function param if > 0)
+    double frequency_min  = 0.0;   // 0 = use IrregularWaveParams::kDefaultFreqMin
+    double frequency_max  = 0.0;   // 0 = use IrregularWaveParams::kDefaultFreqMax
+    int    nfrequencies   = 0;     // 0 = use IrregularWaveParams::kDefaultNFrequencies
     // TODO: Add spectrum parameters (peak enhancement factor, etc.)
 };
 
@@ -60,39 +60,33 @@ struct YAMLHydroData {
     WaveSettings waves;
 
     // ─────────────────────────────────────────────────────────────────────────
-    // Radiation method selection (system-wide)
+    // Convolution truncation (system-wide, wave-type-independent)
     // ─────────────────────────────────────────────────────────────────────────
-    // Top-level selection: "rirf_convolution" (default) or "state_space"
-    std::string radiation_method = "rirf_convolution";
+    double excitation_truncation_time = 0.0;  ///< Excitation IRF truncation [s]; 0 = full
+    double radiation_truncation_time = 0.0;   ///< Radiation RIRF truncation [s]; 0 = full
 
     // ─────────────────────────────────────────────────────────────────────────
-    // State-space options (only used if radiation_method == "state_space")
+    // Radiation method selection (system-wide)
     // ─────────────────────────────────────────────────────────────────────────
-    int ss_max_order = 10;           // Maximum exponential modes per DOF pair
-    double ss_r2_threshold = 0.95;   // R² fit quality threshold
-    int ss_max_hankel_size = 200;    // Max Hankel matrix size for SVD (key performance param)
-    int ss_r2_num_samples = 50;      // Number of samples for R² check during fitting
+    std::string radiation_method = "rirf_convolution";  ///< "rirf_convolution" or "state_space"
 
     // ─────────────────────────────────────────────────────────────────────────
-    // Convolution settings (only used if radiation_method == "rirf_convolution")
+    // Radiation kernel processing (smoothing + tapering, composable)
     // ─────────────────────────────────────────────────────────────────────────
-    std::string radiation_convolution_mode = "Baseline"; // Baseline | TaperedDirect
-    std::string td_smoothing = "sg";
-    int td_window_length = 5;
-    
-    // RIRF truncation
-    double td_rirf_end_time = -1.0;
+    hydrochrono::hydro::RadiationKernelProcessing radiation_kernel_processing;
 
-    // Simple taper control - sensible defaults for improved stability
-    double td_taper_start_percent = 0.8;      // start taper at 80% (taper last 20%)
-    double td_taper_end_percent = 1.0;        // end taper at 100% of total time series
-    double td_taper_final_amplitude = 0.0;    // final amplitude as fraction of original (0.0 = zero, 1.0 = no change)
-    bool td_export_plot_csv = false;          // dump before/after CSV summaries (false by default)
+    // ─────────────────────────────────────────────────────────────────────────
+    // State-space options (only used if radiation_method == "state_space")
+    // ─────────────────────────────────────────────────────────────────────────
+    int ss_max_order = 10;
+    double ss_r2_threshold = 0.95;
+    int ss_max_hankel_size = 200;
+    int ss_r2_num_samples = 50;
 
     // ─────────────────────────────────────────────────────────────────────────
     // Diagnostics
     // ─────────────────────────────────────────────────────────────────────────
-    bool output_kernel_fit = false;           // write kernel fit diagnostics to HDF5
+    bool output_kernel_fit = false;
 
     // ─────────────────────────────────────────────────────────────────────────
     // MoorDyn mooring coupling (optional)
@@ -103,4 +97,3 @@ struct YAMLHydroData {
 };
 
 #endif  // HYDROC_CONFIG_HYDRO_CONFIG_H
-

include/hydroc/hydro_system.h

@@ -360,14 +360,34 @@ class HydroSystem {
     double GetRIRFval(int row, int col, int st);
 
     // ─────────────────────────────────────────────────────────────────────────
-    // Radiation Configuration
+    // Convolution Truncation and Radiation Configuration
     // ─────────────────────────────────────────────────────────────────────────
-    // These types are defined in the radiation module (single source of truth):
+    // Types from include/hydroc/radiation/radiation_types.h:
     //   - hydrochrono::hydro::RadiationMethod (enum: kRirfConvolution, kStateSpace)
-    //   - hydrochrono::hydro::RadiationConvolutionMode (enum: Baseline, TaperedDirect)
-    //   - hydrochrono::hydro::TaperedDirectOptions (struct)
+    //   - hydrochrono::hydro::RadiationKernelProcessing (struct: smoothing + tapering)
     //   - hydrochrono::hydro::StateSpaceOptions (struct)
-    // See: include/hydroc/radiation/radiation_types.h
+
+    /**
+     * @brief Truncate excitation IRF to [-T, T] seconds.
+     * 
+     * 0 = use full IRF from H5 data. Only affects wave modes that use IRF
+     * convolution (irregular waves). Safe to call for any wave type.
+     * Must be called before the first timestep.
+     * 
+     * @param seconds Truncation time in seconds (0 = no truncation)
+     */
+    void SetExcitationTruncationTime(double seconds);
+
+    /**
+     * @brief Truncate radiation RIRF to [0, T] seconds.
+     * 
+     * 0 = use full RIRF from H5 data. Applied before any kernel processing
+     * (smoothing/tapering). Works with all radiation methods (convolution and
+     * state-space). Must be called before the first timestep.
+     * 
+     * @param seconds Truncation time in seconds (0 = no truncation)
+     */
+    void SetRadiationTruncationTime(double seconds);
 
     /**
      * @brief Set the radiation damping calculation method.
@@ -376,9 +396,6 @@ class HydroSystem {
      *   - kRirfConvolution: Direct RIRF convolution (default)
      *   - kStateSpace: State-space exponential approximation
      * 
-     * @note State-space method not yet implemented. This value is stored but
-     *       currently has no effect; runtime always uses RIRF convolution.
-     * 
      * @param method RadiationMethod::kRirfConvolution or ::kStateSpace
      */
     void SetRadiationMethod(hydrochrono::hydro::RadiationMethod method);
@@ -388,30 +405,20 @@ class HydroSystem {
      * 
      * Only applies when RadiationMethod == kStateSpace.
      * 
-     * @note State-space method not yet implemented. Options stored for future use.
-     * 
      * @param opts StateSpaceOptions struct with max_order and r2_threshold
      */
     void SetStateSpaceOptions(const hydrochrono::hydro::StateSpaceOptions& opts);
 
     /**
-     * @brief Set the radiation convolution mode. Default is Baseline.
+     * @brief Configure RIRF kernel processing (smoothing and/or tapering).
      * 
+     * Applied after truncation (SetRadiationTruncationTime). Smoothing and
+     * tapering are composable: either, both, or neither can be enabled.
      * Only applies when RadiationMethod == kRirfConvolution.
      * 
-     * @param mode RadiationConvolutionMode::Baseline or ::TaperedDirect
+     * @param opts RadiationKernelProcessing with smoothing/taper settings
      */
-    void SetRadiationConvolutionMode(hydrochrono::hydro::RadiationConvolutionMode mode);
-
-    /**
-     * @brief Set options for TaperedDirect preprocessing.
-     * 
-     * Only applies when RadiationMethod == kRirfConvolution and
-     * RadiationConvolutionMode == TaperedDirect.
-     * 
-     * @param opts TaperedDirectOptions struct with smoothing, tapering, and export settings
-     */
-    void SetTaperedDirectOptions(const hydrochrono::hydro::TaperedDirectOptions& opts);
+    void SetRadiationKernelProcessing(const hydrochrono::hydro::RadiationKernelProcessing& opts);
 
     /**
      * @brief Enable or disable kernel fit diagnostic output.
@@ -576,20 +583,22 @@ class HydroSystem {
     bool profiling_enabled_ = false;
 
     // ─────────────────────────────────────────────────────────────────────────
-    // Radiation configuration (uses canonical types from radiation module)
+    // Convolution truncation and radiation configuration
     // ─────────────────────────────────────────────────────────────────────────
 
+    double excitation_truncation_time_ = 0.0;   ///< Excitation IRF truncation [s], 0 = full
+    double radiation_truncation_time_ = 0.0;    ///< Radiation RIRF truncation [s], 0 = full
+    
     // Top-level method selection
     hydrochrono::hydro::RadiationMethod radiation_method_ = 
         hydrochrono::hydro::RadiationMethod::kRirfConvolution;
     hydrochrono::hydro::StateSpaceOptions state_space_opts_;
     bool output_kernel_fit_ = false;
 
-    // Convolution kernel preprocessing (only applies when method == kRirfConvolution)
-    hydrochrono::hydro::RadiationConvolutionMode convolution_mode_;
+    // Kernel processing (smoothing + tapering, composable, defaults are no-ops)
+    hydrochrono::hydro::RadiationKernelProcessing kernel_processing_;
     bool rirf_processed_ready_ = false;
     std::vector<Eigen::Tensor<double, 3>> rirf_processed_; // per body [dof x col x step]
-    hydrochrono::hydro::TaperedDirectOptions tapered_opts_;
     std::string diagnostics_output_dir_;
 
     void EnsureProcessedRIRF();

include/hydroc/radiation/radiation_types.h

@@ -4,8 +4,7 @@
  *
  * MAIN TYPES:
  *   - RadiationMethod: Selects the radiation damping calculation method
- *   - RadiationConvolutionMode: Baseline vs TaperedDirect RIRF processing
- *   - TaperedDirectOptions: Smoothing, tapering, and export settings
+ *   - RadiationKernelProcessing: Composable smoothing + tapering for RIRF kernels
  *   - StateSpaceOptions: Settings for state-space radiation approximation
  *********************************************************************/
 
@@ -23,43 +22,41 @@ namespace hydrochrono::hydro {
  *   - kRirfConvolution: Direct convolution of RIRF kernels with velocity history (default)
  *   - kStateSpace: State-space approximation using exponential decay modes
  * 
- * When using kRirfConvolution, additional options are available via
- * RadiationConvolutionMode (Baseline vs TaperedDirect).
+ * RIRF truncation (SetRadiationTruncationTime) is applied before either method.
+ * Kernel processing (smoothing/tapering) is applied only for kRirfConvolution.
  */
 enum class RadiationMethod {
     kRirfConvolution,  ///< Direct RIRF convolution (default, existing method)
     kStateSpace        ///< State-space approximation (exponential decay modes)
 };
 
 /**
- * @brief Convolution mode for radiation damping.
+ * @brief Composable RIRF kernel processing options (smoothing and/or tapering).
  * 
- * Only applies when RadiationMethod == kRirfConvolution.
- */
-enum class RadiationConvolutionMode {
-    Baseline,
-    TaperedDirect
-};
-
-/**
- * @brief Options for TaperedDirect RIRF preprocessing.
+ * Applied after RIRF truncation (which is handled separately via
+ * HydroSystem::SetRadiationTruncationTime). Smoothing is applied first,
+ * then tapering.
  * 
- * Only applies when RadiationMethod == kRirfConvolution and
- * RadiationConvolutionMode == TaperedDirect.
+ * Defaults are no-ops: smoothing is "none" and taper is disabled. If neither
+ * is configured, no kernel processing occurs.
  */
-struct TaperedDirectOptions {
-    // smoothing: "sg" (Savitzky–Golay) or "moving_average"
-    std::string smoothing = "sg";
-    int window_length = 5;                 // odd, >= 3
-    
-    // RIRF truncation
-    double rirf_end_time = -1.0;           // end RIRF at this time (seconds), -1.0 = use full length
-    
-    // Simple taper control - sensible defaults for improved stability
-    double taper_start_percent = 0.8;      // start taper at 80% (taper last 20%)
-    double taper_end_percent = 1.0;        // end taper at 100% of total time series  
-    double taper_final_amplitude = 0.0;    // final amplitude as fraction of original (0.0 = zero, 1.0 = no change)
-    bool export_plot_csv = false;          // dump before/after CSV summaries (false by default)
+struct RadiationKernelProcessing {
+    /// Smoothing type: "none" (default), "sg" (Savitzky-Golay), or "moving_average"
+    std::string smoothing_type = "none";
+    int smoothing_window = 5;              ///< Smoothing window length (odd, >= 3)
+
+    /// Tapering: when enabled, applies a half-cosine taper window near the end of the RIRF
+    bool taper_enabled = false;
+    double taper_start_percent = 0.8;      ///< Start taper at this fraction of RIRF length
+    double taper_end_percent = 1.0;        ///< End taper at this fraction of RIRF length
+    double taper_final_amplitude = 0.0;    ///< Final amplitude (0.0 = zero, 1.0 = no change)
+
+    bool export_csv = false;               ///< Export before/after CSV for diagnostics
+
+    /// Returns true if any processing (smoothing or tapering) is configured.
+    bool RequiresProcessing() const {
+        return smoothing_type != "none" || taper_enabled;
+    }
 };
 
 /**