[FXC-3159] Add TimeAverageForceDistributionOutput (#1623)

* [FXC-3159] Add TimeAverageForceDistributionOutput

* Remove unnecessary code

* Apply comments

Author: yifan-flex

flow360/__init__.py

@@ -142,6 +142,7 @@
     SurfaceOutput,
     SurfaceProbeOutput,
     SurfaceSliceOutput,
+    TimeAverageForceDistributionOutput,
     TimeAverageIsosurfaceOutput,
     TimeAverageProbeOutput,
     TimeAverageSliceOutput,
@@ -258,6 +259,7 @@
     "VolumeOutput",
     "TimeAverageVolumeOutput",
     "ForceDistributionOutput",
+    "TimeAverageForceDistributionOutput",
     "SliceOutput",
     "TimeAverageSliceOutput",
     "IsosurfaceOutput",

flow360/component/simulation/outputs/outputs.py

@@ -1314,6 +1314,37 @@ class ForceDistributionOutput(Flow360BaseModel):
     )
 
 
+class TimeAverageForceDistributionOutput(ForceDistributionOutput):
+    """
+    :class:`TimeAverageForceDistributionOutput` class for time-averaged customized force and moment distribution output.
+    Axis-aligned components are output for force and moment coefficients at the end of the simulation.
+
+    Example
+    -------
+
+    Calculate the average value starting from the :math:`4^{th}` physical step.
+
+    >>> fl.TimeAverageForceDistributionOutput(
+    ...     name="spanwise",
+    ...     distribution_direction=[0.1, 0.9, 0.0],
+    ...     start_step=4,
+    ... )
+
+    ====
+    """
+
+    name: str = pd.Field(
+        "Time average force distribution output",
+        description="Name of the `TimeAverageForceDistributionOutput`.",
+    )
+    start_step: Union[pd.NonNegativeInt, Literal[-1]] = pd.Field(
+        default=-1, description="Physical time step to start calculating averaging."
+    )
+    output_type: Literal["TimeAverageForceDistributionOutput"] = pd.Field(
+        "TimeAverageForceDistributionOutput", frozen=True
+    )
+
+
 OutputTypes = Annotated[
     Union[
         SurfaceOutput,
@@ -1334,6 +1365,7 @@ class ForceDistributionOutput(Flow360BaseModel):
         StreamlineOutput,
         TimeAverageStreamlineOutput,
         ForceDistributionOutput,
+        TimeAverageForceDistributionOutput,
     ],
     pd.Field(discriminator="output_type"),
 ]
@@ -1346,6 +1378,7 @@ class ForceDistributionOutput(Flow360BaseModel):
     TimeAverageProbeOutput,
     TimeAverageSurfaceProbeOutput,
     TimeAverageStreamlineOutput,
+    TimeAverageForceDistributionOutput,
 )
 
 MonitorOutputType = Annotated[

flow360/component/simulation/translator/solver_translator.py

@@ -74,6 +74,7 @@
     SurfaceOutput,
     SurfaceProbeOutput,
     SurfaceSliceOutput,
+    TimeAverageForceDistributionOutput,
     TimeAverageIsosurfaceOutput,
     TimeAverageProbeOutput,
     TimeAverageSliceOutput,
@@ -655,14 +656,27 @@ def translate_force_distribution_output(output_params: list):
     """Translate force distribution output settings."""
     force_distribution_output = {}
     for output in output_params:
-        if isinstance(output, ForceDistributionOutput):
+        if is_exact_instance(output, ForceDistributionOutput):
             force_distribution_output[output.name] = {
                 "direction": list(output.distribution_direction),
                 "type": output.distribution_type,
             }
     return force_distribution_output
 
 
+def translate_time_averaged_force_distribution_output(output_params: list):
+    """Translate time-averaged force distribution output settings."""
+    time_averaged_force_distribution_output = {}
+    for output in output_params:
+        if isinstance(output, TimeAverageForceDistributionOutput):
+            time_averaged_force_distribution_output[output.name] = {
+                "direction": list(output.distribution_direction),
+                "type": output.distribution_type,
+                "startAverageIntegrationStep": output.start_step,
+            }
+    return time_averaged_force_distribution_output
+
+
 def user_variable_to_udf(
     variable: UserVariable, input_params: SimulationParams
 ):  # pylint:disable=too-many-branches
@@ -1012,6 +1026,12 @@ def translate_output(input_params: SimulationParams, translated: dict):
     if has_instance_in_list(outputs, ForceDistributionOutput):
         translated["forceDistributionOutput"] = translate_force_distribution_output(outputs)
 
+    ##:: Step10b: Get translated["timeAveragedForceDistributionOutput"]
+    if has_instance_in_list(outputs, TimeAverageForceDistributionOutput):
+        translated["timeAveragedForceDistributionOutput"] = (
+            translate_time_averaged_force_distribution_output(outputs)
+        )
+
     ##:: Step11: Sort all "output_fields" everywhere
     # Recursively sort all "outputFields" lists in the translated dict
     def _sort_output_fields_in_dict(d):

flow360/component/simulation/validation/validation_output.py

@@ -11,6 +11,7 @@
     ProbeOutput,
     SurfaceIntegralOutput,
     SurfaceProbeOutput,
+    TimeAverageForceDistributionOutput,
 )
 from flow360.component.simulation.time_stepping.time_stepping import Steady
 from flow360.component.simulation.user_code.core.types import Expression
@@ -64,6 +65,7 @@ def extract_literal_values(annotation):
             "AeroAcousticOutput",
             "StreamlineOutput",
             "ForceDistributionOutput",
+            "TimeAverageForceDistributionOutput",
         ):
             continue
         # Get allowed output fields items:
@@ -120,6 +122,7 @@ def _check_output_fields_valid_given_turbulence_model(params):
             "AeroAcousticOutput",
             "StreamlineOutput",
             "ForceDistributionOutput",
+            "TimeAverageForceDistributionOutput",
         ):
             continue
         for item in output.output_fields.items:
@@ -168,6 +171,7 @@ def _check_output_fields_valid_given_transition_model(params):
             "AeroAcousticOutput",
             "StreamlineOutput",
             "ForceDistributionOutput",
+            "TimeAverageForceDistributionOutput",
         ):
             continue
         for item in output.output_fields.items:
@@ -246,7 +250,7 @@ def _check_unique_force_distribution_output_names(params):
     active_names = set()
 
     for output_index, output in enumerate(params.outputs):
-        if isinstance(output, ForceDistributionOutput):
+        if isinstance(output, (ForceDistributionOutput, TimeAverageForceDistributionOutput)):
             if output.name in active_names:
                 raise ValueError(
                     f"In `outputs`[{output_index}] {output.output_type}: "

tests/simulation/params/test_validators_output.py

@@ -26,6 +26,7 @@
     SurfaceIntegralOutput,
     SurfaceOutput,
     SurfaceProbeOutput,
+    TimeAverageForceDistributionOutput,
     TimeAverageSurfaceOutput,
     VolumeOutput,
 )
@@ -458,7 +459,7 @@ def test_duplicate_force_distribution_names():
     with pytest.raises(
         ValueError,
         match=re.escape(
-            "`outputs`[1] ForceDistributionOutput: Output name test has already been used for a "
+            "`outputs`[1] TimeAverageForceDistributionOutput: Output name test has already been used for a "
             "`ForceDistributionOutput`. Output names must be unique among all force distribution outputs."
         ),
     ):
@@ -469,14 +470,35 @@ def test_duplicate_force_distribution_names():
                         name="test",
                         distribution_direction=[1.0, 0.0, 0.0],
                     ),
-                    ForceDistributionOutput(
+                    TimeAverageForceDistributionOutput(
                         name="test",
                         distribution_direction=[0.0, 1.0, 0.0],
                     ),
                 ],
             )
 
 
+def test_time_averaged_force_distribution_output_requires_unsteady():
+    with pytest.raises(
+        ValueError,
+        match=re.escape(
+            "`TimeAverageForceDistributionOutput` can only be used in unsteady simulations."
+        ),
+    ):
+        with imperial_unit_system:
+            SimulationParams(
+                models=[Fluid(turbulence_model_solver=NoneSolver())],
+                outputs=[
+                    TimeAverageForceDistributionOutput(
+                        name="test",
+                        distribution_direction=[1.0, 0.0, 0.0],
+                        start_step=10,
+                    ),
+                ],
+                time_stepping=Steady(),
+            )
+
+
 def test_duplicate_probe_entity_names(mock_validation_context):
 
     # should have no error

tests/simulation/translator/test_output_translation.py

@@ -28,6 +28,7 @@
     SurfaceOutput,
     SurfaceProbeOutput,
     SurfaceSliceOutput,
+    TimeAverageForceDistributionOutput,
     TimeAverageIsosurfaceOutput,
     TimeAverageProbeOutput,
     TimeAverageSurfaceOutput,
@@ -1216,6 +1217,45 @@ def test_force_distribution_output():
     assert compare_values(param_with_ref[1], translated["forceDistributionOutput"])
 
 
+def test_time_averaged_force_distribution_output():
+    param_with_ref = (
+        [
+            TimeAverageForceDistributionOutput(
+                name="test_name",
+                distribution_direction=[0.1, 0.9, 0.0],
+            ),
+            TimeAverageForceDistributionOutput(
+                name="test_name2",
+                distribution_direction=[1.0, 0.0, 0.0],
+                distribution_type="cumulative",
+                start_step=5,
+            ),
+        ],
+        {
+            "test_name": {
+                "direction": [0.11043152607484655, 0.9938837346736189, 0.0],
+                "type": "incremental",
+                "startAverageIntegrationStep": -1,
+            },
+            "test_name2": {
+                "direction": [1.0, 0.0, 0.0],
+                "type": "cumulative",
+                "startAverageIntegrationStep": 5,
+            },
+        },
+    )
+
+    with SI_unit_system:
+        param = SimulationParams(
+            outputs=param_with_ref[0], time_stepping=Unsteady(steps=1, step_size=0.1)
+        )
+    param = param._preprocess(mesh_unit=1.0 * u.m, exclude=["models"])
+
+    translated = {}
+    translated = translate_output(param, translated)
+    assert compare_values(param_with_ref[1], translated["timeAveragedForceDistributionOutput"])
+
+
 def test_surface_slice_output(vel_in_km_per_hr):
     param_with_ref = (
         [