Moving statistic improvement based on QA testing

Author: angranl-flex

flow360/component/simulation/outputs/outputs.py

@@ -134,11 +134,19 @@ class MovingStatistic(Flow360BaseModel):
     :class:`ProbeOutput`, :class:`SurfaceProbeOutput`,
     :class:`SurfaceIntegralOutput` and :class:`ForceOutput`.
 
+    Notes
+    -----
+    - The window size is defined by the number of data points recorded in the output.
+    - For steady simulations, the solver typically outputs a data point once every **10 pseudo steps**.
+      This means a :py:attr:`moving_window_size`=10 would cover 100 pseudo steps.
+      Thus, the :py:attr:`start_step` value is automatically rounded up to
+      the nearest multiple of 10 for steady simulations.
+
     Example
     -------
 
     Define a moving statistic to compute the standard deviation in a moving window of
-    10 steps, with the initial 100 steps skipped.
+    10 data points, with the initial 100 steps skipped.
 
     >>> fl.MovingStatistic(
     ...     moving_window_size=10,
@@ -149,35 +157,24 @@ class MovingStatistic(Flow360BaseModel):
     ====
     """
 
-    moving_window_size: pd.PositiveInt = pd.Field(
+    moving_window_size: pd.StrictInt = pd.Field(
         10,
-        description="The number of pseudo/physical steps to compute moving statistics. "
-        "For steady simulation, the moving_window_size should be a multiple of 10.",
+        ge=2,
+        description="The size of the moving window in data points over which the "
+        "statistic is calculated. Must be greater than or equal to 2.",
     )
     method: Literal["mean", "min", "max", "std", "deviation"] = pd.Field(
-        "mean", description="The type of moving statistics used to monitor the output."
+        "mean", description="The statistical method to apply to the data within the moving window."
     )
     start_step: pd.NonNegativeInt = pd.Field(
         0,
-        description="The number of pseudo/physical steps to skip before computing the moving statistics. "
-        "For steady simulation, the moving_window_size should be a multiple of 10.",
+        description="The number of steps (pseudo or physical) to skip at the beginning of the "
+        "simulation before the moving statistics calculation starts. For steady "
+        "simulations, this value is automatically rounded up to the nearest multiple of 10, "
+        "as the solver outputs data every 10 pseudo steps.",
     )
     type_name: Literal["MovingStatistic"] = pd.Field("MovingStatistic", frozen=True)
 
-    @pd.field_validator("moving_window_size", "start_step", mode="after")
-    @classmethod
-    def _check_moving_window_for_steady_simulation(cls, value):
-        validation_info = get_validation_info()
-        if (
-            validation_info
-            and validation_info.time_stepping == TimeSteppingType.STEADY
-            and value % 10 != 0
-        ):
-            raise ValueError(
-                "For steady simulation, the number of steps should be a multiple of 10."
-            )
-        return value
-
 
 class _OutputBase(Flow360BaseModel):
     output_fields: UniqueItemList[str] = pd.Field()

flow360/component/simulation/simulation_params.py

@@ -88,6 +88,7 @@
 from flow360.component.simulation.utils import model_attribute_unlock
 from flow360.component.simulation.validation.validation_output import (
     _check_aero_acoustics_observer_time_step_size,
+    _check_moving_statistic_applicability,
     _check_output_fields,
     _check_output_fields_valid_given_transition_model,
     _check_output_fields_valid_given_turbulence_model,
@@ -579,6 +580,11 @@ def check_time_average_output(params):
         """Only allow TimeAverage output field in the unsteady simulations"""
         return _check_time_average_output(params)
 
+    @pd.model_validator(mode="after")
+    def check_moving_statistic_applicability(params):
+        """Check moving statistic settings are applicable to the simulation time stepping set up."""
+        return _check_moving_statistic_applicability(params)
+
     def _register_assigned_entities(self, registry: EntityRegistry) -> EntityRegistry:
         """Recursively register all entities listed in EntityList to the asset cache."""
         # pylint: disable=no-member

flow360/component/simulation/validation/validation_output.py

@@ -2,6 +2,7 @@
 Validation for output parameters
 """
 
+import math
 from typing import List, Literal, Union, get_args, get_origin
 
 from flow360.component.simulation.models.volume_models import Fluid
@@ -13,6 +14,9 @@
 )
 from flow360.component.simulation.time_stepping.time_stepping import Steady
 from flow360.component.simulation.user_code.core.types import Expression
+from flow360.component.simulation.validation.validation_utils import (
+    customize_model_validator_error,
+)
 
 
 def _check_output_fields(params):
@@ -243,3 +247,39 @@ def _check_unique_surface_volume_probe_entity_names(params):
                 active_entity_names.add(entity.name)
 
     return params
+
+
+def _check_moving_statistic_applicability(params):
+
+    if not params.time_stepping:
+        return params
+
+    if not params.outputs:
+        return params
+
+    is_steady = isinstance(params.time_stepping, Steady)
+    max_steps = params.time_stepping.max_steps if is_steady else params.time_stepping.steps
+
+    for output_index, output in enumerate(params.outputs):
+        if not hasattr(output, "moving_statistic") or output.moving_statistic is None:
+            continue
+        moving_window_size_in_step = (
+            output.moving_statistic.moving_window_size * 10
+            if is_steady
+            else output.moving_statistic.moving_window_size
+        )
+        start_step = (
+            math.ceil(output.moving_statistic.start_step / 10) * 10
+            if is_steady
+            else output.moving_statistic.start_step
+        )
+        if moving_window_size_in_step + start_step > max_steps:
+            raise customize_model_validator_error(
+                model_instance=params,
+                relative_location=("outputs", output_index, "moving_statistic"),
+                message="`moving_statistic`'s moving_window_size + start_step exceeds "
+                "the total number of steps in the simulation.",
+                input_value=output.moving_statistic.model_dump(),
+            )
+
+    return params