Add porous medium example

flow360/component/simulation/models/volume_models.py

@@ -699,11 +699,15 @@ def _ensure_entities_have_sufficient_attributes(cls, value: EntityList):
 class PorousMedium(Flow360BaseModel):
     """
     :class:`PorousMedium` class for specifying porous media settings.`.
-    For further information please refer to the :ref:`porous media knowledge base <knowledge_base_porousMedia>`
+    For further information please refer to the :ref:`porous media knowledge base <knowledge_base_porousMedia>`.
 
     Example
     -------
 
+    Define a porous medium model :code:`porous_zone` with the :py:class:`Box` entity.
+    The center and size of the `porous_zone` box is (0, 0, 0) * fl.u.m and (0.2, 0.3, 2) * fl.u.m, respectively.
+    The axes of the :code:`porous_zone` is set as (0, 1, 0) and (0, 0, 1).
+
     >>> fl.PorousMedium(
     ...     entities=[
     ...         fl.Box.from_principal_axes(
@@ -718,6 +722,19 @@ class PorousMedium(Flow360BaseModel):
     ...    volumetric_heat_source=1.0 * fl.u.W/ fl.u.m **3,
     ... )
 
+    Define a porous medium model :code:`porous_zone` with the :code:`volume_mesh["porous_zone"]` volume.
+    The axes of entity must be specified for the :class:`PorousMedium` model, and we set the axes of
+    the :code:`porous_zone` as (1, 0, 0) and (0, 1, 0).
+
+    >>> porous_zone = volume_mesh["porous_zone"]
+    >>> porous_zone.axes = [(1, 0, 0), (0, 1, 0)]
+    >>> porous_medium_model = fl.PorousMedium(
+    ...     entities=[porous_zone],
+    ...     darcy_coefficient=(1e6, 0, 0) / fl.u.m **2,
+    ...     forchheimer_coefficient=(1, 0, 0) / fl.u.m,
+    ...     volumetric_heat_source=1.0 * fl.u.W/ fl.u.m **3,
+    ... )
+
     ====
     """
 
@@ -726,7 +743,8 @@ class PorousMedium(Flow360BaseModel):
     entities: EntityList[GenericVolume, Box] = pd.Field(
         alias="volumes",
         description="The entity list for the `PorousMedium` model. "
-        + "The entity should be :class:`Box` type.",
+        + "The entity should be defined by :class:`Box` or zones from the geometry/volume mesh."
+        + "The axes of entity must be specified for the :class:`PorousMedium` model.",
     )
 
     darcy_coefficient: InverseAreaType.Point = pd.Field(