rompy.swan.components.physics.OBSTACLE#

pydantic model rompy.swan.components.physics.OBSTACLE[source]#

Subgrid obstacle.

OBSTACLE ->TRANSM|TRANS1D|TRANS2D|GODA|DANGREMOND REFL [reflc] ->RSPEC|RDIFF &
    (FREEBOARD [hgt] [gammat] [gammar] QUAY) LINE < [xp] [yp] >

With this optional command the user provides the characteristics of a (line of) sub-grid obstacle(s) through which waves are transmitted or against which waves are reflected (possibly both at the same time). The obstacle is sub-grid in the sense that it is narrow compared to the spatial meshes; its length should be at least one mesh length.

The location of the obstacle is defined by a sequence of corner points of a line. The obstacles interrupt the propagation of the waves from one grid point to the next wherever this obstacle line is located between two neighbouring grid points (of the computational grid; the resolution of the obstacle is therefore equal to the computational grid spacing). This implies that an obstacle to be effective must be located such that it crosses at least one grid line. This is always the case when an obstacle is larger than one mesh length.

Notes

The advise is to define obstacles with the least amount of points possible.
SWAN checks if the criterion reflc^2 + trcoef^2 LE 1 is fulfilled.

Examples

In [91]: from rompy.swan.components.physics import OBSTACLE

In [92]: obs = OBSTACLE(
   ....:     transmission=dict(model_type="transm", trcoef=0.5),
   ....:     reflection=dict(reflc=0.5),
   ....:     line=dict(xp=[174.1, 174.2, 174.3], yp=[-39.1, -39.1, -39.1]),
   ....: )
   ....: 

In [93]: print(obs.render())
OBSTACLE TRANSM trcoef=0.5 REFL reflc=0.5 LINE 174.1 -39.1 174.2 -39.1 174.3 -39.1

Show JSON schema

{
   "title": "OBSTACLE",
   "description": "Subgrid obstacle.\n\n.. code-block:: text\n\n    OBSTACLE ->TRANSM|TRANS1D|TRANS2D|GODA|DANGREMOND REFL [reflc] ->RSPEC|RDIFF &\n        (FREEBOARD [hgt] [gammat] [gammar] QUAY) LINE < [xp] [yp] >\n\nWith this optional command the user provides the characteristics of a (line\nof) sub-grid obstacle(s) through which waves are transmitted or against which\nwaves are reflected (possibly both at the same time). The obstacle is sub-grid\nin the sense that it is narrow compared to the spatial meshes; its length should\nbe at least one mesh length.\n\nThe location of the obstacle is defined by a sequence of corner points of a line.\nThe obstacles interrupt the propagation of the waves from one grid point to the\nnext wherever this obstacle line is located between two neighbouring grid points\n(of the computational grid; the resolution of the obstacle is therefore equal to\nthe computational grid spacing). This implies that an obstacle to be effective must\nbe located such that it crosses at least one grid line. This is always the case\nwhen an obstacle is larger than one mesh length.\n\nNotes\n-----\n\n* The advise is to define obstacles with the least amount of points possible.\n* SWAN checks if the criterion `reflc^2 + trcoef^2 LE 1` is fulfilled.\n\nExamples\n--------\n\n.. ipython:: python\n    :okwarning:\n\n    from rompy.swan.components.physics import OBSTACLE\n    obs = OBSTACLE(\n        transmission=dict(model_type=\"transm\", trcoef=0.5),\n        reflection=dict(reflc=0.5),\n        line=dict(xp=[174.1, 174.2, 174.3], yp=[-39.1, -39.1, -39.1]),\n    )\n    print(obs.render())",
   "type": "object",
   "properties": {
      "model_type": {
         "default": "obstacle",
         "description": "Model type discriminator",
         "enum": [
            "obstacle",
            "OBSTACLE"
         ],
         "title": "Model Type",
         "type": "string"
      },
      "transmission": {
         "anyOf": [
            {
               "description": "Wave transmission",
               "discriminator": {
                  "mapping": {
                     "DANGREMOND": "#/$defs/DANGREMOND",
                     "GODA": "#/$defs/GODA",
                     "TRANS1D": "#/$defs/TRANS1D",
                     "TRANS2D": "#/$defs/TRANS2D",
                     "TRANSM": "#/$defs/TRANSM",
                     "dangremond": "#/$defs/DANGREMOND",
                     "goda": "#/$defs/GODA",
                     "trans1d": "#/$defs/TRANS1D",
                     "trans2d": "#/$defs/TRANS2D",
                     "transm": "#/$defs/TRANSM"
                  },
                  "propertyName": "model_type"
               },
               "oneOf": [
                  {
                     "$ref": "#/$defs/TRANSM"
                  },
                  {
                     "$ref": "#/$defs/TRANS1D"
                  },
                  {
                     "$ref": "#/$defs/TRANS2D"
                  },
                  {
                     "$ref": "#/$defs/GODA"
                  },
                  {
                     "$ref": "#/$defs/DANGREMOND"
                  }
               ]
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Transmission"
      },
      "reflection": {
         "anyOf": [
            {
               "$ref": "#/$defs/REFL"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Wave reflection"
      },
      "reflection_type": {
         "anyOf": [
            {
               "description": "Wave reflection type",
               "discriminator": {
                  "mapping": {
                     "RDIFF": "#/$defs/RDIFF",
                     "RSPEC": "#/$defs/RSPEC",
                     "rdiff": "#/$defs/RDIFF",
                     "rspec": "#/$defs/RSPEC"
                  },
                  "propertyName": "model_type"
               },
               "oneOf": [
                  {
                     "$ref": "#/$defs/RSPEC"
                  },
                  {
                     "$ref": "#/$defs/RDIFF"
                  }
               ]
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Reflection Type"
      },
      "freeboard": {
         "anyOf": [
            {
               "$ref": "#/$defs/FREEBOARD"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Freeboard"
      },
      "line": {
         "$ref": "#/$defs/LINE",
         "default": null,
         "description": "Line of obstacle"
      }
   },
   "$defs": {
      "DANGREMOND": {
         "additionalProperties": false,
         "description": "DAM transmission of d'Angremond et al. (1996).\n\n.. code-block:: text\n\n    DAM DANGREMOND [hgt] [slope] [Bk]\n\nThis option specifies transmission coefficients dependent on the incident wave\nconditions at the obstacle and on the obstacle height (which may be submerged).\n\nReferences\n----------\nd'Angremond, K., Van Der Meer, J.W. and De Jong, R.J., 1996. Wave transmission at\nlow-crested structures. In Coastal Engineering 1996 (pp. 2418-2427).\n\nExamples\n--------\n\n.. ipython:: python\n    :okwarning:\n\n    from rompy.swan.subcomponents.physics import DANGREMOND\n    transm = DANGREMOND(hgt=3.0, slope=60, Bk=10.0)\n    print(transm.render())",
         "properties": {
            "model_type": {
               "default": "dangremond",
               "description": "Model type discriminator",
               "enum": [
                  "dangremond",
                  "DANGREMOND"
               ],
               "title": "Model Type",
               "type": "string"
            },
            "hgt": {
               "description": "The elevation of the top of the obstacle above reference level (same reference level as for bottom etc.); use a negative value if the top is below that reference level",
               "title": "Hgt",
               "type": "number"
            },
            "slope": {
               "description": "The slope of the obstacle (in degrees)",
               "maximum": 90.0,
               "minimum": 0.0,
               "title": "Slope",
               "type": "number"
            },
            "Bk": {
               "description": "The crest width of the obstacle",
               "title": "Bk",
               "type": "number"
            }
         },
         "required": [
            "hgt",
            "slope",
            "Bk"
         ],
         "title": "DANGREMOND",
         "type": "object"
      },
      "FREEBOARD": {
         "additionalProperties": false,
         "description": "Freeboard dependent transmission and reflection.\n\n.. code-block:: text\n\n    FREEBOARD [hgt] [gammat] [gammar] [QUAY]\n\nWith this option the user indicates that the fixed transmission `trcoef` and\nreflection `reflc` coefficients are freeboard dependent. The freeboard dependency\nhas no effect on the transmission coefficient as computed using the DAM option.\n\nNotes\n-----\nSee the Scientific/Technical documentation for background information on the\n`gammat` and `gammar` shape parameters.\n\nExamples\n--------\n\n.. ipython:: python\n    :okwarning:\n\n    from rompy.swan.subcomponents.physics import FREEBOARD\n    freeboard = FREEBOARD(hgt=2.0)\n    print(freeboard.render())\n    freeboard = FREEBOARD(hgt=2.0, gammat=1.0, gammar=1.0, quay=True)\n    print(freeboard.render())",
         "properties": {
            "model_type": {
               "default": "freeboard",
               "description": "Model type discriminator",
               "enum": [
                  "freeboard",
                  "FREEBOARD"
               ],
               "title": "Model Type",
               "type": "string"
            },
            "hgt": {
               "description": "The elevation of the top of the obstacle or height of the quay above the reference level (same reference level as for the bottom). Use a negative value if the top is below that reference level. In case `hgt` is also specified in the DAM option, both values of `hgt` should be equal for consistency",
               "title": "Hgt",
               "type": "number"
            },
            "gammat": {
               "anyOf": [
                  {
                     "exclusiveMinimum": 0.0,
                     "type": "number"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Shape parameter of relative freeboard dependency of transmission coefficient. This parameter should be higher than zero (SWAN default 1.0)",
               "title": "Gammat"
            },
            "gammar": {
               "anyOf": [
                  {
                     "exclusiveMinimum": 0.0,
                     "type": "number"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Shape parameter of relative freeboard dependency of reflection coefficient. This parameter should be higher than zero (SWAN default 1.0)",
               "title": "Gammar"
            },
            "quay": {
               "default": false,
               "description": "With this option the user indicates that the freeboard dependency of the transmission and reflection coefficients also depends on the relative position of an obstacle-linked grid point with respect to the position of the obstacle line representing the edge of a quay. In case the active grid point is on the deeper side of the obstacle, then the correction factors are applied using the parameters `hgt`, `gammat` and `gammar`.In case the active grid point is on the shallower side of the obstacle, the reflection coefficient is set to 0 and the transmission coefficient to 1.",
               "title": "Quay",
               "type": "boolean"
            }
         },
         "required": [
            "hgt"
         ],
         "title": "FREEBOARD",
         "type": "object"
      },
      "GODA": {
         "additionalProperties": false,
         "description": "DAM transmission of Goda/Seelig (1979).\n\n.. code-block:: text\n\n    DAM GODA [hgt] [alpha] [beta]\n\nThis option specified transmission coefficients dependent on the incident wave\nconditions at the obstacle and on the obstacle height (which may be submerged).\n\nReferences\n----------\nGoda, Y. and Suzuki, Y., 1976. Estimation of incident and reflected waves in random\nwave experiments. In Coastal Engineering 1976 (pp. 828-845).\n\nSeelig, W.N., 1979. Effects of breakwaters on waves: Laboratory test of wave\ntransmission by overtopping. In Proc. Conf. Coastal Structures, 1979\n(Vol. 79, No. 2, pp. 941-961).\n\nExamples\n--------\n\n.. ipython:: python\n    :okwarning:\n\n    from rompy.swan.subcomponents.physics import GODA\n    transm = GODA(hgt=3.0)\n    print(transm.render())\n    transm = GODA(hgt=3.0, alpha=2.6, beta=0.15)\n    print(transm.render())",
         "properties": {
            "model_type": {
               "default": "goda",
               "description": "Model type discriminator",
               "enum": [
                  "goda",
                  "GODA"
               ],
               "title": "Model Type",
               "type": "string"
            },
            "hgt": {
               "description": "The elevation of the top of the obstacle above reference level (same reference level as for bottom etc.); use a negative value if the top is below that reference level",
               "title": "Hgt",
               "type": "number"
            },
            "alpha": {
               "anyOf": [
                  {
                     "type": "number"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "coefficient determining the transmission coefficient for Goda's transmission formula (SWAN default: 2.6)",
               "title": "Alpha"
            },
            "beta": {
               "anyOf": [
                  {
                     "type": "number"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Another coefficient determining the transmission coefficient for Goda's transmission formula (SWAN default: 0.15)",
               "title": "Beta"
            }
         },
         "required": [
            "hgt"
         ],
         "title": "GODA",
         "type": "object"
      },
      "LINE": {
         "additionalProperties": false,
         "description": "Line of points to define obstacle location.\n\n.. code-block:: text\n\n    LINE < [xp] [yp] >\n\nWith this option the user indicates that the fixed transmission `trcoef` and\nreflection `reflc` coefficients are freeboard dependent. The freeboard dependency\nhas no effect on the transmission coefficient as computed using the DAM option.\n\nNotes\n-----\nPoints coordinates should be provided in m If Cartesian coordinates are used or in\ndegrees if spherical coordinates are used (see command `COORD`). At least two\ncorner points must be provided.\n\nExamples\n--------\n\n.. ipython:: python\n    :okwarning:\n\n    from rompy.swan.subcomponents.physics import LINE\n    line = LINE(xp=[174.1, 174.2, 174.3], yp=[-39.1, -39.1, -39.1])\n    print(line.render())",
         "properties": {
            "model_type": {
               "default": "line",
               "description": "Model type discriminator",
               "enum": [
                  "line",
                  "LINE"
               ],
               "title": "Model Type",
               "type": "string"
            },
            "xp": {
               "description": "The x-coordinates of the points defining the line",
               "items": {
                  "type": "number"
               },
               "minItems": 2,
               "title": "Xp",
               "type": "array"
            },
            "yp": {
               "description": "The y-coordinates of the points defining the line",
               "items": {
                  "type": "number"
               },
               "minItems": 2,
               "title": "Yp",
               "type": "array"
            }
         },
         "required": [
            "xp",
            "yp"
         ],
         "title": "LINE",
         "type": "object"
      },
      "RDIFF": {
         "additionalProperties": false,
         "description": "Diffuse reflection.\n\n.. code-block:: text\n\n    RDIFF [pown]\n\nSpecular reflection where incident waves are scattered over reflected direction.\n\nExamples\n--------\n\n.. ipython:: python\n    :okwarning:\n\n    from rompy.swan.subcomponents.physics import RDIFF\n    refl = RDIFF()\n    print(refl.render())\n    refl = RDIFF(pown=1.0)\n    print(refl.render())",
         "properties": {
            "model_type": {
               "default": "rdiff",
               "description": "Model type discriminator",
               "enum": [
                  "rdiff",
                  "RDIFF"
               ],
               "title": "Model Type",
               "type": "string"
            },
            "pown": {
               "anyOf": [
                  {
                     "type": "number"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Each incoming direction \u03b8 is scattered over reflected direction \u03b8_refl according to cos^pown(\u03b8-\u03b8_refl). The parameter `pown` indicates the widthof the redistribution function (SWAN default: 1.0)",
               "title": "Pown"
            }
         },
         "title": "RDIFF",
         "type": "object"
      },
      "REFL": {
         "additionalProperties": false,
         "description": "Obstacle reflections.\n\n.. code-block:: text\n\n    REFL [reflc]\n\nExamples\n--------\n\n.. ipython:: python\n    :okwarning:\n\n    from rompy.swan.subcomponents.physics import REFL\n    refl = REFL()\n    print(refl.render())\n    refl = REFL(reflc=0.5)\n    print(refl.render())",
         "properties": {
            "model_type": {
               "default": "refl",
               "description": "Model type discriminator",
               "enum": [
                  "refl",
                  "REFL"
               ],
               "title": "Model Type",
               "type": "string"
            },
            "reflc": {
               "anyOf": [
                  {
                     "type": "number"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Constant reflection coefficient (ratio of reflected over incoming significant wave height) (SWAN default: 1.0)",
               "title": "Reflc"
            }
         },
         "title": "REFL",
         "type": "object"
      },
      "RSPEC": {
         "additionalProperties": false,
         "description": "Specular reflection.\n\n.. code-block:: text\n\n    RSPEC\n\nExamples\n--------\n\n.. ipython:: python\n    :okwarning:\n\n    from rompy.swan.subcomponents.physics import RSPEC\n    refl = RSPEC()\n    print(refl.render())",
         "properties": {
            "model_type": {
               "default": "rspec",
               "description": "Model type discriminator",
               "enum": [
                  "rspec",
                  "RSPEC"
               ],
               "title": "Model Type",
               "type": "string"
            }
         },
         "title": "RSPEC",
         "type": "object"
      },
      "TRANS1D": {
         "additionalProperties": false,
         "description": "Frequency dependent transmission.\n\n.. code-block:: text\n\n    TRANS1D < [trcoef] >\n\nExamples\n--------\n\n.. ipython:: python\n    :okwarning:\n\n    from rompy.swan.subcomponents.physics import TRANS1D\n    transm = TRANS1D(trcoef=[0.0, 0.0, 0.2, 0.5, 0.2, 0.0, 0.0])\n    print(transm.render())",
         "properties": {
            "model_type": {
               "default": "trans1d",
               "description": "Model type discriminator",
               "enum": [
                  "trans1d",
                  "TRANS1D"
               ],
               "title": "Model Type",
               "type": "string"
            },
            "trcoef": {
               "description": "Transmission coefficient (ratio of transmitted over incoming significant wave height) per frequency. The number of these transmission values must be equal to the number of frequencies, i.e. `msc` + 1",
               "items": {
                  "maximum": 1.0,
                  "minimum": 0.0,
                  "type": "number"
               },
               "title": "Trcoef",
               "type": "array"
            }
         },
         "required": [
            "trcoef"
         ],
         "title": "TRANS1D",
         "type": "object"
      },
      "TRANS2D": {
         "additionalProperties": false,
         "description": "Frequency-direction dependent transmission.\n\n.. code-block:: text\n\n    TRANS2D < [trcoef] >\n\nExamples\n--------\n\n.. ipython:: python\n    :okwarning:\n\n    from rompy.swan.subcomponents.physics import TRANS2D\n    trcoef = np.array([[0.0, 0.0], [0.1, 0.1], [0.2, 0.2]])\n    transm = TRANS2D(trcoef=trcoef)\n    print(transm.render())",
         "properties": {
            "model_type": {
               "default": "trans2d",
               "description": "Model type discriminator",
               "enum": [
                  "trans2d",
                  "TRANS2D"
               ],
               "title": "Model Type",
               "type": "string"
            },
            "trcoef": {
               "description": "Transmission coefficient (ratio of transmitted over incoming significant wave height) per frequency and direction, rows represent directions and columns represent frequencies",
               "properties": {
                  "data_type": {
                     "default": "Any",
                     "title": "dtype",
                     "type": "string"
                  },
                  "data": {
                     "items_schema": {
                        "items_schema": {
                           "type": "any"
                        },
                        "type": "list"
                     },
                     "max_length": 2,
                     "min_length": 2,
                     "type": "list"
                  }
               },
               "required": [
                  "data_type",
                  "data"
               ],
               "title": "Numpy Array",
               "type": "np.ndarray[tuple[int, int], np.dtype[Any]]"
            }
         },
         "required": [
            "trcoef"
         ],
         "title": "TRANS2D",
         "type": "object"
      },
      "TRANSM": {
         "additionalProperties": false,
         "description": "Constant transmission coefficient.\n\n.. code-block:: text\n\n    TRANSM [trcoef]\n\nExamples\n--------\n\n.. ipython:: python\n    :okwarning:\n\n    from rompy.swan.subcomponents.physics import TRANSM\n    transm = TRANSM()\n    print(transm.render())\n    transm = TRANSM(trcoef=0.5)\n    print(transm.render())",
         "properties": {
            "model_type": {
               "default": "transm",
               "description": "Model type discriminator",
               "enum": [
                  "transm",
                  "TRANSM"
               ],
               "title": "Model Type",
               "type": "string"
            },
            "trcoef": {
               "anyOf": [
                  {
                     "maximum": 1.0,
                     "minimum": 0.0,
                     "type": "number"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Constant transmission coefficient (ratio of transmitted over incoming significant wave height) (SWAN default: 0.0) (no transmission = complete blockage)",
               "title": "Trcoef"
            }
         },
         "title": "TRANSM",
         "type": "object"
      }
   },
   "additionalProperties": false
}