Skip to content

Numerics

Numerics commands control the numerical schemes used for wave propagation and source term integration.

Default Numerics

SWAN uses robust default numerical settings. Only modify these if you understand the implications for accuracy and stability.

PROP

Specifies the propagation scheme for geographic and spectral space.

PROP

Bases: BaseComponent

Propagation scheme.

.. code-block:: text

PROP BSTB|GSE

Notes

  • The scheme defaults to S&L and SORDUP for nonstationary and stationary simulations if not specified.
  • All schemes (BSBT, SORDUP and S&L) can be used in combination with curvilinear grids. With the higher order schemes (S&L and SORDUP) it is important to use a gradually varying grid otherwise there may be a severe loss of accuracy. If sharp transitions in the grid cannot be avoided it is safer to use the BSBT scheme.
  • In the computation with unstructured meshes, a lowest order upwind scheme will be employed. This scheme is very robust but rather diffusive. This may only be significant for the case when swell waves propagate over relative large distances (in the order of thousands of kilometers) within the model domain. However and most fortunately, in such a case this will alleviate the garden-sprinkler effect.
  • Alleviating the garden-sprinkler effect by adding some diffusion makes the SWAN computation conditionally stable. You can either use (i) a smaller time step, (ii) a lower value of waveage, (iii) better resolution in the directional space, or (iv) worse resolution in the geographic space, in order of preference, to make the model stable when necessary.

Examples

.. ipython:: python :okwarning:

from rompy_swan.components.numerics import PROP
prop = PROP()
print(prop.render())
prop = PROP(scheme=dict(model_type="bsbt"))
print(prop.render())
prop = PROP(
    scheme=dict(
        model_type="gse",
        waveage=dict(delt="PT5H", dfmt="hr"),
    ),
)
print(prop.render())
Source code in src/rompy_swan/components/numerics.py 
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
class PROP(BaseComponent):
    """Propagation scheme.

    .. code-block:: text

        PROP BSTB|GSE

    Notes
    -----
    * The scheme defaults to `S&L` and `SORDUP` for nonstationary and stationary
      simulations if not specified.
    * All schemes (BSBT, SORDUP and S&L) can be used in combination with curvilinear
      grids. With the higher order schemes (S&L and SORDUP) it is important to use a
      gradually varying grid otherwise there may be a severe loss of accuracy. If sharp
      transitions in the grid cannot be avoided it is safer to use the BSBT scheme.
    * In the computation with unstructured meshes, a lowest order upwind scheme will be
      employed. This scheme is very robust but rather diffusive. This may only be
      significant for the case when swell waves propagate over relative large distances
      (in the order of thousands of kilometers) within the model domain. However and
      most fortunately, in such a case this will alleviate the garden-sprinkler effect.
    * Alleviating the garden-sprinkler effect by adding some diffusion makes the SWAN
      computation conditionally stable. You can either use (i) a smaller time step,
      (ii) a lower value of `waveage`, (iii) better resolution in the directional
      space, or (iv) worse resolution in the geographic space, in order of preference,
      to make the model stable when necessary.

    Examples
    --------

    .. ipython:: python
        :okwarning:

        from rompy_swan.components.numerics import PROP
        prop = PROP()
        print(prop.render())
        prop = PROP(scheme=dict(model_type="bsbt"))
        print(prop.render())
        prop = PROP(
            scheme=dict(
                model_type="gse",
                waveage=dict(delt="PT5H", dfmt="hr"),
            ),
        )
        print(prop.render())

    """

    model_type: Literal["prop", "PROP"] = Field(
        default="prop", description="Model type discriminator"
    )
    scheme: Optional[PROP_TYPE] = Field(
        default=None,
        description=(
            "Propagation scheme, by default S&L for nonstationary and SORDUP for "
            "stationary computation."
        ),
    )

    def cmd(self) -> str:
        """Command file string for this component."""
        repr = "PROP"
        if self.scheme is not None:
            repr += f" {self.scheme.render()}"
        return repr

Attributes

model_type class-attribute instance-attribute 

model_type: Literal['prop', 'PROP'] = Field(default='prop', description='Model type discriminator')

scheme class-attribute instance-attribute 

scheme: Optional[PROP_TYPE] = Field(default=None, description='Propagation scheme, by default S&L for nonstationary and SORDUP for stationary computation.')

Functions

cmd 

cmd() -> str

Command file string for this component.

Source code in src/rompy_swan/components/numerics.py 
93
94
95
96
97
98
def cmd(self) -> str:
    """Command file string for this component."""
    repr = "PROP"
    if self.scheme is not None:
        repr += f" {self.scheme.render()}"
    return repr

NUMERIC

Controls iteration settings, accuracy criteria, and limiter options.

NUMERIC

Bases: BaseComponent

Numerical properties.

.. code-block:: text

NUMeric ( STOPC [dabs] [drel] [curvat] [npnts] ->STAT|NONSTAT [limiter] ) &
    ( DIRimpl [cdd] ) ( SIGIMpl [css] [eps2] [outp] [niter] ) &
    ( CTheta [cfl] ) ( CSigma [cfl] ) ( SETUP [eps2] [outp] [niter] )

Examples

.. ipython:: python :okwarning:

from rompy_swan.components.numerics import NUMERIC
numeric = NUMERIC()
print(numeric.render())
numeric = NUMERIC(
    stop=dict(
        model_type="stopc",
        dabs=0.05,
        drel=0.01,
        curvat=0.05,
        npnts=99.5,
    ),
    dirimpl=dict(cdd=0.5),
    sigimpl=dict(css=0.5, eps2=1e-4, outp=0, niter=20),
    ctheta=dict(cfl=0.9),
    csigma=dict(cfl=0.9),
    setup=dict(eps2=1e-4, outp=0, niter=20),
)
print(numeric.render())
Source code in src/rompy_swan/components/numerics.py 
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
class NUMERIC(BaseComponent):
    """Numerical properties.

    .. code-block:: text

        NUMeric ( STOPC [dabs] [drel] [curvat] [npnts] ->STAT|NONSTAT [limiter] ) &
            ( DIRimpl [cdd] ) ( SIGIMpl [css] [eps2] [outp] [niter] ) &
            ( CTheta [cfl] ) ( CSigma [cfl] ) ( SETUP [eps2] [outp] [niter] )

    Examples
    --------
    .. ipython:: python
        :okwarning:

        from rompy_swan.components.numerics import NUMERIC
        numeric = NUMERIC()
        print(numeric.render())
        numeric = NUMERIC(
            stop=dict(
                model_type="stopc",
                dabs=0.05,
                drel=0.01,
                curvat=0.05,
                npnts=99.5,
            ),
            dirimpl=dict(cdd=0.5),
            sigimpl=dict(css=0.5, eps2=1e-4, outp=0, niter=20),
            ctheta=dict(cfl=0.9),
            csigma=dict(cfl=0.9),
            setup=dict(eps2=1e-4, outp=0, niter=20),
        )
        print(numeric.render())

    """

    model_type: Literal["numeric", "NUMERIC"] = Field(
        default="numeric", description="Model type discriminator"
    )
    stop: Optional[Union[STOPC, ACCUR]] = Field(
        default=None,
        description="Iteration termination criteria",
        discriminator="model_type",
    )
    dirimpl: Optional[DIRIMPL] = Field(
        default=None,
        description="Numerical scheme for refraction",
    )
    sigimpl: Optional[SIGIMPL] = Field(
        default=None,
        description="Frequency shifting accuracy",
    )
    ctheta: Optional[CTHETA] = Field(
        default=None,
        description="Prevents excessive directional turning",
    )
    csigma: Optional[CSIGMA] = Field(
        default=None,
        description="Prevents excessive frequency shifting",
    )
    setup: Optional[SETUP] = Field(
        default=None,
        description="Stop criteria in the computation of wave setup",
    )

    def cmd(self) -> str:
        """Command file string for this component."""
        repr = "NUMERIC"
        if self.stop is not None:
            repr += f" {self.stop.render()}"
        if self.dirimpl is not None:
            repr += f" {self.dirimpl.render()}"
        if self.sigimpl is not None:
            repr += f" {self.sigimpl.render()}"
        if self.ctheta is not None:
            repr += f" {self.ctheta.render()}"
        return repr

Attributes

model_type class-attribute instance-attribute 

model_type: Literal['numeric', 'NUMERIC'] = Field(default='numeric', description='Model type discriminator')

stop class-attribute instance-attribute 

stop: Optional[Union[STOPC, ACCUR]] = Field(default=None, description='Iteration termination criteria', discriminator='model_type')

dirimpl class-attribute instance-attribute 

dirimpl: Optional[DIRIMPL] = Field(default=None, description='Numerical scheme for refraction')

sigimpl class-attribute instance-attribute 

sigimpl: Optional[SIGIMPL] = Field(default=None, description='Frequency shifting accuracy')

ctheta class-attribute instance-attribute 

ctheta: Optional[CTHETA] = Field(default=None, description='Prevents excessive directional turning')

csigma class-attribute instance-attribute 

csigma: Optional[CSIGMA] = Field(default=None, description='Prevents excessive frequency shifting')

setup class-attribute instance-attribute 

setup: Optional[SETUP] = Field(default=None, description='Stop criteria in the computation of wave setup')

Functions

cmd 

cmd() -> str

Command file string for this component.

Source code in src/rompy_swan/components/numerics.py 
165
166
167
168
169
170
171
172
173
174
175
176
def cmd(self) -> str:
    """Command file string for this component."""
    repr = "NUMERIC"
    if self.stop is not None:
        repr += f" {self.stop.render()}"
    if self.dirimpl is not None:
        repr += f" {self.dirimpl.render()}"
    if self.sigimpl is not None:
        repr += f" {self.sigimpl.render()}"
    if self.ctheta is not None:
        repr += f" {self.ctheta.render()}"
    return repr