Skip to content

Time

Sub-commands to support time definition

Time

Bases: BaseSubComponent

Time specification in SWAN.

.. code-block:: text

[time]

Time is rendered in one of the following formats:

  • 1: ISO-notation 19870530.153000
  • 2: (as in HP compiler) '30-May-87 15:30:00'
  • 3: (as in Lahey compiler) 05/30/87.15:30:00
  • 4: 15:30:00
  • 5: 87/05/30 15:30:00'
  • 6: as in WAM 8705301530

Note

The time field can be specified as:

  • existing datetime object
  • int or float, assumed as Unix time, i.e. seconds (if >= -2e10 or <= 2e10) or milliseconds (if < -2e10 or > 2e10) since 1 January 1970.
  • ISO 8601 time string.

Examples

.. ipython:: python :okwarning:

from rompy_swan.subcomponents.time import Time
from datetime import datetime
time = Time(time=datetime(1990, 1, 1))
print(time.render())
time = Time(time="2012-01-01T00:00:00", tfmt=2)
print(time.render())
Source code in rompy_swan/subcomponents/time.py 
32
33
34
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
class Time(BaseSubComponent):
    """Time specification in SWAN.

    .. code-block:: text

        [time]

    Time is rendered in one of the following formats:

    * 1: ISO-notation 19870530.153000
    * 2: (as in HP compiler) '30-May-87 15:30:00'
    * 3: (as in Lahey compiler) 05/30/87.15:30:00
    * 4: 15:30:00
    * 5: 87/05/30 15:30:00'
    * 6: as in WAM 8705301530

    Note
    ----
    The `time` field can be specified as:

    * existing datetime object
    * int or float, assumed as Unix time, i.e. seconds (if >= -2e10 or <= 2e10) or
      milliseconds (if < -2e10 or > 2e10) since 1 January 1970.
    * ISO 8601 time string.

    Examples
    --------

    .. ipython:: python
        :okwarning:

        from rompy_swan.subcomponents.time import Time
        from datetime import datetime
        time = Time(time=datetime(1990, 1, 1))
        print(time.render())
        time = Time(time="2012-01-01T00:00:00", tfmt=2)
        print(time.render())

    """

    model_type: Literal["time", "Time", "TIME"] = Field(
        default="time", description="Model type discriminator"
    )
    time: datetime = Field(description="Datetime specification")
    tfmt: Union[Literal[1, 2, 3, 4, 5, 6], str] = Field(
        default=1,
        description="Format to render time specification",
        validate_default=True,
    )

    @field_validator("tfmt")
    @classmethod
    def set_time_format(cls, v: int | str) -> str:
        """Set the time format to render."""
        if isinstance(v, str):
            return v
        return TIME_FORMAT[v]

    def cmd(self) -> str:
        """Render subcomponent cmd."""
        return f"{self.time.strftime(self.tfmt)}"

Attributes

model_type class-attribute instance-attribute 

model_type: Literal['time', 'Time', 'TIME'] = Field(default='time', description='Model type discriminator')

time class-attribute instance-attribute 

time: datetime = Field(description='Datetime specification')

tfmt class-attribute instance-attribute 

tfmt: Union[Literal[1, 2, 3, 4, 5, 6], str] = Field(default=1, description='Format to render time specification', validate_default=True)

Functions

set_time_format classmethod 

set_time_format(v: int | str) -> str

Set the time format to render.

Source code in rompy_swan/subcomponents/time.py 
82
83
84
85
86
87
88
@field_validator("tfmt")
@classmethod
def set_time_format(cls, v: int | str) -> str:
    """Set the time format to render."""
    if isinstance(v, str):
        return v
    return TIME_FORMAT[v]

cmd 

cmd() -> str

Render subcomponent cmd.

Source code in rompy_swan/subcomponents/time.py 
90
91
92
def cmd(self) -> str:
    """Render subcomponent cmd."""
    return f"{self.time.strftime(self.tfmt)}"

Delt

Bases: BaseSubComponent

Time interval specification in SWAN.

.. code-block:: text

[delt] SEC|MIN|HR|DAY

Note

The tdelta field can be specified as:

  • existing timedelta object
  • int or float, assumed as seconds

  • ISO 8601 duration string, following formats work:

  • [-][DD ][HH:MM]SS[.ffffff]

  • [±]P[DD]DT[HH]H[MM]M[SS]S (ISO 8601 format for timedelta)

Examples

.. ipython:: python :okwarning:

from rompy_swan.subcomponents.time import Delt
from datetime import timedelta
delt = Delt(delt=timedelta(minutes=30))
print(delt.render())
delt = Delt(delt="PT1H", dfmt="hr")
print(delt.render())
Source code in rompy_swan/subcomponents/time.py 
 95
 96
 97
 98
 99
100
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
class Delt(BaseSubComponent):
    """Time interval specification in SWAN.

    .. code-block:: text

        [delt] SEC|MIN|HR|DAY

    Note
    ----
    The `tdelta` field can be specified as:

    * existing timedelta object
    * int or float, assumed as seconds
    * ISO 8601 duration string, following formats work:

      * `[-][DD ][HH:MM]SS[.ffffff]`
      * `[±]P[DD]DT[HH]H[MM]M[SS]S` (ISO 8601 format for timedelta)

    Examples
    --------

    .. ipython:: python
        :okwarning:

        from rompy_swan.subcomponents.time import Delt
        from datetime import timedelta
        delt = Delt(delt=timedelta(minutes=30))
        print(delt.render())
        delt = Delt(delt="PT1H", dfmt="hr")
        print(delt.render())

    """

    model_type: Literal["delt"] = Field(
        default="delt", description="Model type discriminator"
    )
    delt: timedelta = Field(description="Time interval")
    dfmt: Literal["sec", "min", "hr", "day"] = Field(
        default="sec",
        description="Format to render time interval specification",
    )

    @property
    def delt_float(self):
        delt_scaling = {"sec": 1, "min": 60, "hr": 3600, "day": 86400}
        return self.delt.total_seconds() / delt_scaling[self.dfmt]

    def cmd(self) -> str:
        """Render subcomponent cmd."""
        return f"{self.delt_float} {self.dfmt.upper()}"

Attributes

model_type class-attribute instance-attribute 

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

delt class-attribute instance-attribute 

delt: timedelta = Field(description='Time interval')

dfmt class-attribute instance-attribute 

dfmt: Literal['sec', 'min', 'hr', 'day'] = Field(default='sec', description='Format to render time interval specification')

delt_float property 

delt_float

Functions

cmd 

cmd() -> str

Render subcomponent cmd.

Source code in rompy_swan/subcomponents/time.py 
142
143
144
def cmd(self) -> str:
    """Render subcomponent cmd."""
    return f"{self.delt_float} {self.dfmt.upper()}"

TimeRangeOpen

Bases: BaseSubComponent

Regular times with an open boundary.

.. code-block:: text

[tbeg] [delt] SEC|MIN|HR|DAY

Time is rendered in one of the following formats:

  • 1: ISO-notation 19870530.153000
  • 2: (as in HP compiler) '30-May-87 15:30:00'
  • 3: (as in Lahey compiler) 05/30/87.15:30:00
  • 4: 15:30:00
  • 5: 87/05/30 15:30:00'
  • 6: as in WAM 8705301530

Note

The tbeg field can be specified as:

  • existing datetime object
  • int or float, assumed as Unix time, i.e. seconds (if >= -2e10 or <= 2e10) or milliseconds (if < -2e10 or > 2e10) since 1 January 1970.
  • ISO 8601 time string.

Note

The tdelta field can be specified as:

  • existing timedelta object
  • int or float, assumed as seconds

  • ISO 8601 duration string, following formats work:

    • [-][DD ][HH:MM]SS[.ffffff]
    • [±]P[DD]DT[HH]H[MM]M[SS]S (ISO 8601 format for timedelta)

Note

Default values for the time specification fields are provided for the case where the user wants to set times dynamically after instantiating this subcomponent.

Examples

.. ipython:: python :okwarning:

from rompy_swan.subcomponents.time import TimeRangeOpen
from datetime import datetime, timedelta
times = TimeRangeOpen(
    tbeg=datetime(1990, 1, 1), delt=timedelta(minutes=30), dfmt="min"
)
print(times.render())
times = TimeRangeOpen(
    tbeg="2012-01-01T00:00:00", delt="PT1H", tfmt=2, dfmt="hr", suffix="blk"
)
print(times.render())
Source code in rompy_swan/subcomponents/time.py 
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
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
class TimeRangeOpen(BaseSubComponent):
    """Regular times with an open boundary.

    .. code-block:: text

        [tbeg] [delt] SEC|MIN|HR|DAY

    Time is rendered in one of the following formats:

    * 1: ISO-notation 19870530.153000
    * 2: (as in HP compiler) '30-May-87 15:30:00'
    * 3: (as in Lahey compiler) 05/30/87.15:30:00
    * 4: 15:30:00
    * 5: 87/05/30 15:30:00'
    * 6: as in WAM 8705301530

    Note
    ----
    The `tbeg` field can be specified as:

    * existing datetime object
    * int or float, assumed as Unix time, i.e. seconds (if >= -2e10 or <= 2e10) or
      milliseconds (if < -2e10 or > 2e10) since 1 January 1970.
    * ISO 8601 time string.

    Note
    ----
    The `tdelta` field can be specified as:

    * existing timedelta object
    * int or float, assumed as seconds
    * ISO 8601 duration string, following formats work:

        * `[-][DD ][HH:MM]SS[.ffffff]`
        * `[±]P[DD]DT[HH]H[MM]M[SS]S` (ISO 8601 format for timedelta)

    Note
    ----
    Default values for the time specification fields are provided for the case where
    the user wants to set times dynamically after instantiating this subcomponent.

    Examples
    --------

    .. ipython:: python
        :okwarning:

        from rompy_swan.subcomponents.time import TimeRangeOpen
        from datetime import datetime, timedelta
        times = TimeRangeOpen(
            tbeg=datetime(1990, 1, 1), delt=timedelta(minutes=30), dfmt="min"
        )
        print(times.render())
        times = TimeRangeOpen(
            tbeg="2012-01-01T00:00:00", delt="PT1H", tfmt=2, dfmt="hr", suffix="blk"
        )
        print(times.render())

    """

    model_type: Literal["open", "OPEN"] = Field(
        default="open", description="Model type discriminator"
    )
    tbeg: datetime = Field(default=DEFAULT_TIME, description="Start time")
    delt: timedelta = Field(default=DEFAULT_DELT, description="Time interval")
    tfmt: Union[Literal[1, 2, 3, 4, 5, 6], str] = Field(
        default=1,
        description="Format to render time specification",
    )
    dfmt: Literal["sec", "min", "hr", "day"] = Field(
        default="sec",
        description="Format to render time interval specification",
    )
    suffix: str = Field(
        default="",
        description="Suffix to prepend to argument names when rendering",
    )

    def cmd(self) -> str:
        """Render subcomponent cmd."""
        repr = f"tbeg{self.suffix}={Time(time=self.tbeg, tfmt=self.tfmt).render()}"
        repr += f" delt{self.suffix}={Delt(delt=self.delt, dfmt=self.dfmt).render()}"
        return repr

Attributes

model_type class-attribute instance-attribute 

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

tbeg class-attribute instance-attribute 

tbeg: datetime = Field(default=DEFAULT_TIME, description='Start time')

delt class-attribute instance-attribute 

delt: timedelta = Field(default=DEFAULT_DELT, description='Time interval')

tfmt class-attribute instance-attribute 

tfmt: Union[Literal[1, 2, 3, 4, 5, 6], str] = Field(default=1, description='Format to render time specification')

dfmt class-attribute instance-attribute 

dfmt: Literal['sec', 'min', 'hr', 'day'] = Field(default='sec', description='Format to render time interval specification')

suffix class-attribute instance-attribute 

suffix: str = Field(default='', description='Suffix to prepend to argument names when rendering')

Functions

cmd 

cmd() -> str

Render subcomponent cmd.

Source code in rompy_swan/subcomponents/time.py 
225
226
227
228
229
def cmd(self) -> str:
    """Render subcomponent cmd."""
    repr = f"tbeg{self.suffix}={Time(time=self.tbeg, tfmt=self.tfmt).render()}"
    repr += f" delt{self.suffix}={Delt(delt=self.delt, dfmt=self.dfmt).render()}"
    return repr

TimeRangeClosed

Bases: TimeRangeOpen

Regular times with a closed boundary.

.. code-block:: text

[tbeg] [delt] SEC|MIN|HR|DAY [tend]

Note

Default values for the time specification fields are provided for the case where the user wants to set times dynamically after instantiating this subcomponent.

Examples

.. ipython:: python :okwarning:

from rompy_swan.subcomponents.time import TimeRangeClosed
from datetime import datetime, timedelta
times = TimeRangeClosed(
    tbeg=datetime(1990, 1, 1),
    tend=datetime(1990, 1, 7),
    delt=timedelta(minutes=30),
    dfmt="min",
)
print(times.render())
times = TimeRangeClosed(
    tbeg="2012-01-01T00:00:00",
    tend="2012-02-01T00:00:00",
    delt="PT1H",
    tfmt=2,
    dfmt="hr",
    suffix="blk",
)
print(times.render())
Source code in rompy_swan/subcomponents/time.py 
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
class TimeRangeClosed(TimeRangeOpen):
    """Regular times with a closed boundary.

    .. code-block:: text

        [tbeg] [delt] SEC|MIN|HR|DAY [tend]

    Note
    ----
    Default values for the time specification fields are provided for the case where
    the user wants to set times dynamically after instantiating this subcomponent.

    Examples
    --------

    .. ipython:: python
        :okwarning:

        from rompy_swan.subcomponents.time import TimeRangeClosed
        from datetime import datetime, timedelta
        times = TimeRangeClosed(
            tbeg=datetime(1990, 1, 1),
            tend=datetime(1990, 1, 7),
            delt=timedelta(minutes=30),
            dfmt="min",
        )
        print(times.render())
        times = TimeRangeClosed(
            tbeg="2012-01-01T00:00:00",
            tend="2012-02-01T00:00:00",
            delt="PT1H",
            tfmt=2,
            dfmt="hr",
            suffix="blk",
        )
        print(times.render())

    """

    model_type: Literal["closed", "CLOSED"] = Field(
        default="closed", description="Model type discriminator"
    )
    tend: datetime = Field(default=DEFAULT_TEND, description="End time")

    def __call__(self) -> list[Time]:
        """Returns the list of Time objects."""
        times = pd.date_range(start=self.tbeg, end=self.tend, freq=self.delt)
        return [time.to_pydatetime() for time in times]

    def __getitem__(self, index) -> datetime | list[datetime]:
        """Slicing from the times array."""
        return self.__call__()[index]

    def __len__(self):
        """Returns the length of the times array."""
        return len(self())

    def cmd(self) -> str:
        """Render subcomponent cmd."""
        repr = super().cmd()
        repr += f" tend{self.suffix}={Time(time=self.tend, tfmt=self.tfmt).render()}"
        return repr

Attributes

model_type class-attribute instance-attribute 

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

tend class-attribute instance-attribute 

tend: datetime = Field(default=DEFAULT_TEND, description='End time')

Functions

cmd 

cmd() -> str

Render subcomponent cmd.

Source code in rompy_swan/subcomponents/time.py 
289
290
291
292
293
def cmd(self) -> str:
    """Render subcomponent cmd."""
    repr = super().cmd()
    repr += f" tend{self.suffix}={Time(time=self.tend, tfmt=self.tfmt).render()}"
    return repr

NONSTATIONARY

Bases: TimeRangeClosed

Nonstationary time specification.

.. code-block:: text

NONSTATIONARY [tbeg] [delt] SEC|MIN|HR|DAY [tend]

Note

Default values for the time specification fields are provided for the case where the user wants to set times dynamically after instantiating this subcomponent.

Examples

.. ipython:: python :okwarning:

from rompy_swan.subcomponents.time import NONSTATIONARY
nonstat = NONSTATIONARY(
    tbeg="2012-01-01T00:00:00",
    tend="2012-02-01T00:00:00",
    delt="PT1H",
    dfmt="hr",
)
print(nonstat.render())
from datetime import datetime, timedelta
nonstat = NONSTATIONARY(
    tbeg=datetime(1990, 1, 1),
    tend=datetime(1990, 1, 7),
    delt=timedelta(minutes=30),
    tfmt=1,
    dfmt="min",
    suffix="tbl",
)
print(nonstat.render())
Source code in rompy_swan/subcomponents/time.py 
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
class NONSTATIONARY(TimeRangeClosed):
    """Nonstationary time specification.

    .. code-block:: text

        NONSTATIONARY [tbeg] [delt] SEC|MIN|HR|DAY [tend]

    Note
    ----
    Default values for the time specification fields are provided for the case where
    the user wants to set times dynamically after instantiating this subcomponent.

    Examples
    --------

    .. ipython:: python
        :okwarning:

        from rompy_swan.subcomponents.time import NONSTATIONARY
        nonstat = NONSTATIONARY(
            tbeg="2012-01-01T00:00:00",
            tend="2012-02-01T00:00:00",
            delt="PT1H",
            dfmt="hr",
        )
        print(nonstat.render())
        from datetime import datetime, timedelta
        nonstat = NONSTATIONARY(
            tbeg=datetime(1990, 1, 1),
            tend=datetime(1990, 1, 7),
            delt=timedelta(minutes=30),
            tfmt=1,
            dfmt="min",
            suffix="tbl",
        )
        print(nonstat.render())

    """

    model_type: Literal["nonstationary", "NONSTATIONARY"] = Field(
        default="nonstationary", description="Model type discriminator"
    )
    tbeg: datetime = Field(default=DEFAULT_TIME, description="Start time")
    tend: datetime = Field(default=DEFAULT_TEND, description="End time")
    delt: timedelta = Field(default=DEFAULT_DELT, description="Time interval")

    def cmd(self) -> str:
        """Render subcomponent cmd."""
        repr = f"NONSTATIONARY {super().cmd()}"
        return repr

Attributes

model_type class-attribute instance-attribute 

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

tbeg class-attribute instance-attribute 

tbeg: datetime = Field(default=DEFAULT_TIME, description='Start time')

tend class-attribute instance-attribute 

tend: datetime = Field(default=DEFAULT_TEND, description='End time')

delt class-attribute instance-attribute 

delt: timedelta = Field(default=DEFAULT_DELT, description='Time interval')

Functions

cmd 

cmd() -> str

Render subcomponent cmd.

Source code in rompy_swan/subcomponents/time.py 
342
343
344
345
def cmd(self) -> str:
    """Render subcomponent cmd."""
    repr = f"NONSTATIONARY {super().cmd()}"
    return repr

STATIONARY

Bases: BaseSubComponent

Stationary time specification.

.. code-block:: text

STATIONARY [time]

Note

The field time is optional to allow for the case where the user wants to set the time dynamically after instantiating this component.

Examples

.. ipython:: python :okwarning:

from rompy_swan.subcomponents.time import STATIONARY
stat = STATIONARY(time="2012-01-01T00:00:00")
print(stat.render())
Source code in rompy_swan/subcomponents/time.py 
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
class STATIONARY(BaseSubComponent):
    """Stationary time specification.

    .. code-block:: text

        STATIONARY [time]

    Note
    ----
    The field `time` is optional to allow for the case where the user wants to set the
    time dynamically after instantiating this component.

    Examples
    --------

    .. ipython:: python
        :okwarning:

        from rompy_swan.subcomponents.time import STATIONARY
        stat = STATIONARY(time="2012-01-01T00:00:00")
        print(stat.render())

    """

    model_type: Literal["stationary", "STATIONARY"] = Field(
        default="stationary", description="Model type discriminator"
    )
    time: datetime = Field(default=DEFAULT_TIME, description="Stationary time")
    tfmt: Union[Literal[1, 2, 3, 4, 5, 6], str] = Field(
        default=1,
        description="Format to render time specification",
    )

    def __call__(self) -> list[Time]:
        """Returns the list of Time object for consistency with NONSTATIONARY."""
        return [self.time]

    def __getitem__(self, index) -> Time | list[Time]:
        """Slicing from the times array."""
        return self.__call__()[index]

    def __len__(self):
        """Returns the length of the times array."""
        return len(self())

    def cmd(self) -> str:
        """Render subcomponent cmd."""
        return f"STATIONARY time={Time(time=self.time, tfmt=self.tfmt).render()}"

Attributes

model_type class-attribute instance-attribute 

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

time class-attribute instance-attribute 

time: datetime = Field(default=DEFAULT_TIME, description='Stationary time')

tfmt class-attribute instance-attribute 

tfmt: Union[Literal[1, 2, 3, 4, 5, 6], str] = Field(default=1, description='Format to render time specification')

Functions

cmd 

cmd() -> str

Render subcomponent cmd.

Source code in rompy_swan/subcomponents/time.py 
393
394
395
def cmd(self) -> str:
    """Render subcomponent cmd."""
    return f"STATIONARY time={Time(time=self.time, tfmt=self.tfmt).render()}"