[FXC-4804] Support surface selection for custom force distribution

Author: yifan-flex

flow360/component/simulation/outputs/outputs.py

@@ -1661,12 +1661,23 @@ class ForceDistributionOutput(Flow360BaseModel):
     Example
     -------
 
+    Basic usage with default settings (all wall surfaces):
 
     >>> fl.ForceDistributionOutput(
     ...     name="spanwise",
     ...     distribution_direction=[0.1, 0.9, 0.0],
     ... )
 
+    Specifying specific surfaces to include in the force integration (useful for automotive cases
+    to exclude road/floor surfaces):
+
+    >>> fl.ForceDistributionOutput(
+    ...     name="vehicle_x_distribution",
+    ...     distribution_direction=[1.0, 0.0, 0.0],
+    ...     entities=[volume_mesh["vehicle_body"], volume_mesh["wheels"]],
+    ...     number_of_segments=500,
+    ... )
+
     ====
     """
 
@@ -1677,10 +1688,29 @@ class ForceDistributionOutput(Flow360BaseModel):
     distribution_type: Literal["incremental", "cumulative"] = pd.Field(
         "incremental", description="Type of the distribution."
     )
+    entities: Optional[EntityList[Surface, MirroredSurface]] = pd.Field(
+        None,
+        alias="surfaces",
+        description="List of surfaces to include in the force integration. "
+        "If not specified, all wall surfaces are included. "
+        "This is useful for automotive cases to exclude road/floor surfaces.",
+    )
+    number_of_segments: Optional[pd.PositiveInt] = pd.Field(
+        None,
+        description="Number of segments (bins) to use along the distribution direction. "
+        "If not specified, the default of 300 segments is used. "
+        "Increasing this value provides higher resolution in the force distribution plot.",
+    )
     output_type: Literal["ForceDistributionOutput"] = pd.Field(
         "ForceDistributionOutput", frozen=True
     )
 
+    @contextual_field_validator("entities", mode="after")
+    @classmethod
+    def ensure_surface_existence(cls, value, param_info: ParamsValidationInfo):
+        """Ensure all boundaries will be present after mesher"""
+        return validate_entity_list_surface_existence(value, param_info)
+
 
 class TimeAverageForceDistributionOutput(ForceDistributionOutput):
     """
@@ -1698,6 +1728,17 @@ class TimeAverageForceDistributionOutput(ForceDistributionOutput):
     ...     start_step=4,
     ... )
 
+    Specifying specific surfaces to include in the force integration (useful for automotive cases
+    to exclude road/floor surfaces):
+
+    >>> fl.TimeAverageForceDistributionOutput(
+    ...     name="vehicle_x_distribution",
+    ...     distribution_direction=[1.0, 0.0, 0.0],
+    ...     entities=[volume_mesh["vehicle_body"], volume_mesh["wheels"]],
+    ...     number_of_segments=500,
+    ...     start_step=100,
+    ... )
+
     ====
     """
 

flow360/component/simulation/services.py

@@ -22,7 +22,9 @@
 
 # Required for correct global scope initialization
 from flow360.component.simulation.blueprint.core.dependency_graph import DependencyGraph
-from flow360.component.simulation.entity_info import GeometryEntityInfo
+from flow360.component.simulation.entity_info import (
+    GeometryEntityInfo,
+)
 from flow360.component.simulation.entity_info import (
     merge_geometry_entity_info as merge_geometry_entity_info_obj,
 )

flow360/component/simulation/translator/solver_translator.py

@@ -819,10 +819,18 @@ def translate_force_distribution_output(output_params: list):
     force_distribution_output = {}
     for output in output_params:
         if is_exact_instance(output, ForceDistributionOutput):
-            force_distribution_output[output.name] = {
+            config = {
                 "direction": list(output.distribution_direction),
                 "type": output.distribution_type,
             }
+            # Add surfaces if specified (for selective face integration)
+            if output.entities is not None:
+                surface_names = [entity.full_name for entity in output.entities.stored_entities]
+                config["surfaces"] = surface_names
+            # Add number of segments if specified
+            if output.number_of_segments is not None:
+                config["numberOfSegments"] = output.number_of_segments
+            force_distribution_output[output.name] = config
     return force_distribution_output
 
 
@@ -831,11 +839,19 @@ def translate_time_averaged_force_distribution_output(output_params: list):
     time_averaged_force_distribution_output = {}
     for output in output_params:
         if isinstance(output, TimeAverageForceDistributionOutput):
-            time_averaged_force_distribution_output[output.name] = {
+            config = {
                 "direction": list(output.distribution_direction),
                 "type": output.distribution_type,
                 "startAverageIntegrationStep": output.start_step,
             }
+            # Add surfaces if specified (for selective face integration)
+            if output.entities is not None:
+                surface_names = [entity.full_name for entity in output.entities.stored_entities]
+                config["surfaces"] = surface_names
+            # Add number of segments if specified
+            if output.number_of_segments is not None:
+                config["numberOfSegments"] = output.number_of_segments
+            time_averaged_force_distribution_output[output.name] = config
     return time_averaged_force_distribution_output
 
 

tests/simulation/params/test_validators_output.py

@@ -1386,3 +1386,72 @@ def test_force_output_with_model_id():
         assert err["type"] == exp_err["type"]
         assert err["ctx"]["relevant_for"] == exp_err["ctx"]["relevant_for"]
         assert err["msg"] == exp_err["msg"]
+
+
+def test_force_distribution_output_entities_validation():
+    """Test ForceDistributionOutput entities validation."""
+
+    # Test 1: Valid case - ForceDistributionOutput without entities (default all walls)
+    with imperial_unit_system:
+        SimulationParams(
+            outputs=[
+                ForceDistributionOutput(
+                    name="test_default",
+                    distribution_direction=[1.0, 0.0, 0.0],
+                ),
+            ],
+        )
+
+    # Test 2: Valid case - ForceDistributionOutput with surface entities
+    with imperial_unit_system:
+        SimulationParams(
+            outputs=[
+                ForceDistributionOutput(
+                    name="test_with_surfaces",
+                    distribution_direction=[1.0, 0.0, 0.0],
+                    entities=[Surface(name="fluid/wing")],
+                ),
+            ],
+        )
+
+    # Test 3: Valid case - TimeAverageForceDistributionOutput with entities
+    with imperial_unit_system:
+        SimulationParams(
+            outputs=[
+                TimeAverageForceDistributionOutput(
+                    name="test_time_avg",
+                    distribution_direction=[0.0, 1.0, 0.0],
+                    entities=[Surface(name="fluid/body")],
+                    start_step=10,
+                ),
+            ],
+            time_stepping=Unsteady(steps=100, step_size=1e-3),
+        )
+
+    # Test 4: Valid case - ForceDistributionOutput with multiple surfaces
+    with imperial_unit_system:
+        SimulationParams(
+            outputs=[
+                ForceDistributionOutput(
+                    name="test_multiple_surfaces",
+                    distribution_direction=[0.0, 0.0, 1.0],
+                    entities=[
+                        Surface(name="fluid/wing"),
+                        Surface(name="fluid/fuselage"),
+                    ],
+                ),
+            ],
+        )
+
+    # Test 5: Valid case - ForceDistributionOutput with custom number_of_segments
+    with imperial_unit_system:
+        SimulationParams(
+            outputs=[
+                ForceDistributionOutput(
+                    name="test_custom_segments",
+                    distribution_direction=[1.0, 0.0, 0.0],
+                    entities=[Surface(name="fluid/wing")],
+                    number_of_segments=500,
+                ),
+            ],
+        )

tests/simulation/translator/test_output_translation.py

@@ -1224,6 +1224,93 @@ def test_force_distribution_output():
     assert compare_values(param_with_ref[1], translated["forceDistributionOutput"])
 
 
+def test_force_distribution_output_with_entities_and_segments():
+    """Test ForceDistributionOutput with entities (selective surfaces) and number_of_segments parameters."""
+    # Test with entities (selective surfaces)
+    param_with_entities = (
+        [
+            ForceDistributionOutput(
+                name="test_with_entities",
+                distribution_direction=[1.0, 0.0, 0.0],
+                entities=[
+                    Surface(name="wing", private_attribute_full_name="fluid/wing"),
+                    Surface(name="fuselage", private_attribute_full_name="fluid/fuselage"),
+                ],
+            ),
+        ],
+        {
+            "test_with_entities": {
+                "direction": [1.0, 0.0, 0.0],
+                "type": "incremental",
+                "surfaces": ["fluid/wing", "fluid/fuselage"],
+            },
+        },
+    )
+
+    with SI_unit_system:
+        param = SimulationParams(outputs=param_with_entities[0])
+    param = param._preprocess(mesh_unit=1.0 * u.m, exclude=["models"])
+
+    translated = {}
+    translated = translate_output(param, translated)
+    assert compare_values(param_with_entities[1], translated["forceDistributionOutput"])
+
+    # Test with number_of_segments
+    param_with_segments = (
+        [
+            ForceDistributionOutput(
+                name="test_with_segments",
+                distribution_direction=[0.0, 1.0, 0.0],
+                number_of_segments=500,
+            ),
+        ],
+        {
+            "test_with_segments": {
+                "direction": [0.0, 1.0, 0.0],
+                "type": "incremental",
+                "numberOfSegments": 500,
+            },
+        },
+    )
+
+    with SI_unit_system:
+        param = SimulationParams(outputs=param_with_segments[0])
+    param = param._preprocess(mesh_unit=1.0 * u.m, exclude=["models"])
+
+    translated = {}
+    translated = translate_output(param, translated)
+    assert compare_values(param_with_segments[1], translated["forceDistributionOutput"])
+
+    # Test with both entities and number_of_segments
+    param_with_both = (
+        [
+            ForceDistributionOutput(
+                name="test_with_both",
+                distribution_direction=[0.0, 0.0, 1.0],
+                entities=[Surface(name="body", private_attribute_full_name="fluid/body")],
+                number_of_segments=400,
+                distribution_type="cumulative",
+            ),
+        ],
+        {
+            "test_with_both": {
+                "direction": [0.0, 0.0, 1.0],
+                "type": "cumulative",
+                "surfaces": ["fluid/body"],
+                "numberOfSegments": 400,
+            },
+        },
+    )
+
+    with SI_unit_system:
+        param = SimulationParams(outputs=param_with_both[0])
+    param = param._preprocess(mesh_unit=1.0 * u.m, exclude=["models"])
+
+    translated = {}
+    translated = translate_output(param, translated)
+    assert compare_values(param_with_both[1], translated["forceDistributionOutput"])
+
+
 def test_time_averaged_force_distribution_output():
     param_with_ref = (
         [
@@ -1263,6 +1350,107 @@ def test_time_averaged_force_distribution_output():
     assert compare_values(param_with_ref[1], translated["timeAveragedForceDistributionOutput"])
 
 
+def test_time_averaged_force_distribution_output_with_entities_and_segments():
+    """Test TimeAverageForceDistributionOutput with entities and number_of_segments parameters."""
+    # Test with entities (selective surfaces)
+    param_with_entities = (
+        [
+            TimeAverageForceDistributionOutput(
+                name="test_time_avg_entities",
+                distribution_direction=[1.0, 0.0, 0.0],
+                entities=[
+                    Surface(name="wing", private_attribute_full_name="fluid/wing"),
+                ],
+                start_step=10,
+            ),
+        ],
+        {
+            "test_time_avg_entities": {
+                "direction": [1.0, 0.0, 0.0],
+                "type": "incremental",
+                "startAverageIntegrationStep": 10,
+                "surfaces": ["fluid/wing"],
+            },
+        },
+    )
+
+    with SI_unit_system:
+        param = SimulationParams(
+            outputs=param_with_entities[0], time_stepping=Unsteady(steps=100, 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_entities[1], translated["timeAveragedForceDistributionOutput"])
+
+    # Test with number_of_segments
+    param_with_segments = (
+        [
+            TimeAverageForceDistributionOutput(
+                name="test_time_avg_segments",
+                distribution_direction=[0.0, 1.0, 0.0],
+                number_of_segments=600,
+                start_step=20,
+            ),
+        ],
+        {
+            "test_time_avg_segments": {
+                "direction": [0.0, 1.0, 0.0],
+                "type": "incremental",
+                "startAverageIntegrationStep": 20,
+                "numberOfSegments": 600,
+            },
+        },
+    )
+
+    with SI_unit_system:
+        param = SimulationParams(
+            outputs=param_with_segments[0], time_stepping=Unsteady(steps=100, 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_segments[1], translated["timeAveragedForceDistributionOutput"])
+
+    # Test with both entities and number_of_segments
+    param_with_both = (
+        [
+            TimeAverageForceDistributionOutput(
+                name="test_time_avg_both",
+                distribution_direction=[0.0, 0.0, 1.0],
+                entities=[
+                    Surface(name="body", private_attribute_full_name="fluid/body"),
+                    Surface(name="tail", private_attribute_full_name="fluid/tail"),
+                ],
+                number_of_segments=350,
+                distribution_type="cumulative",
+                start_step=50,
+            ),
+        ],
+        {
+            "test_time_avg_both": {
+                "direction": [0.0, 0.0, 1.0],
+                "type": "cumulative",
+                "startAverageIntegrationStep": 50,
+                "surfaces": ["fluid/body", "fluid/tail"],
+                "numberOfSegments": 350,
+            },
+        },
+    )
+
+    with SI_unit_system:
+        param = SimulationParams(
+            outputs=param_with_both[0], time_stepping=Unsteady(steps=100, 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_both[1], translated["timeAveragedForceDistributionOutput"])
+
+
 def test_surface_slice_output(vel_in_km_per_hr):
     param_with_ref = (
         [