Merge pull request #2329 from vicenzodarezzo/v4-dev

changing TimeExtrapolationError to OutsideTimeInterval

Author: erikvansebille

docs/examples_v3/example_globcurrent.py

@@ -121,7 +121,7 @@ def test__particles_init_time():
     assert pset[0].time - pset4[0].time == 0
 
 
-def test_globcurrent_time_extrapolation_error():
+def test_globcurrent_outside_time_interval_error():
     fieldset = set_globcurrent_fieldset()
     pset = parcels.ParticleSet(
         fieldset,
@@ -130,7 +130,7 @@ def test_globcurrent_time_extrapolation_error():
         lat=[-35],
         time=fieldset.U.grid.time[0] - timedelta(days=1).total_seconds(),
     )
-    with pytest.raises(parcels.TimeExtrapolationError):
+    with pytest.raises(parcels.OutsideTimeInterval):
         pset.execute(
             parcels.kernels.AdvectionRK4,
             runtime=timedelta(days=1),
@@ -179,7 +179,7 @@ def SampleP(particle, fieldset, time):  # pragma: no cover
         pset = parcels.ParticleSet(fieldset, pclass=MyParticle, lon=[25], lat=[-35])
 
     if with_starttime:
-        with pytest.raises(parcels.TimeExtrapolationError):
+        with pytest.raises(parcels.OutsideTimeInterval):
             pset.execute(
                 pset.Kernel(parcels.kernels.AdvectionRK4) + SampleP,
                 runtime=timedelta(days=1),

docs/examples_v3/tutorial_kernelloop.ipynb

@@ -265,7 +265,7 @@
     "### 3. The last time is not written to file\n",
     "Because the location at the start of the loop is written at the end of the Kernel loop, the last `particle.time` of the particle is not written to file. This is similar behaviour to e.g. `np.arange(start, stop)`, which also doesn't include the `stop` value itself. \n",
     "\n",
-    "If you do want to write the last time to file, you can increase the `runtime` or `endtime` by `dt` (although this may cause a TimeExtrapolationError if your run was to the end of the available hydrodynamic data), or you can call `pfile.write_latest_locations(pset, time=pset[0].time_nextloop)`. Note that in the latter case, the particle locations (longitude, latitude and depth) will be updated, but other variables will _not_ be updated as the Kernels are not run again."
+    "If you do want to write the last time to file, you can increase the `runtime` or `endtime` by `dt` (although this may cause an OutsideTimeInterval if your run was to the end of the available hydrodynamic data), or you can call `pfile.write_latest_locations(pset, time=pset[0].time_nextloop)`. Note that in the latter case, the particle locations (longitude, latitude and depth) will be updated, but other variables will _not_ be updated as the Kernels are not run again."
    ]
   },
   {

src/parcels/__init__.py

@@ -29,8 +29,8 @@
     FieldOutOfBoundError,
     FieldSamplingError,
     KernelError,
+    OutsideTimeInterval,
     StatusCode,
-    TimeExtrapolationError,
 )
 from parcels._core.uxgrid import UxGrid
 from parcels._core.warnings import (
@@ -69,8 +69,8 @@
     "FieldOutOfBoundError",
     "FieldSamplingError",
     "KernelError",
+    "OutsideTimeInterval",
     "StatusCode",
-    "TimeExtrapolationError",
     # Warnings
     "FieldSetWarning",
     "FileWarning",

src/parcels/_core/index_search.py

@@ -5,7 +5,7 @@
 
 import numpy as np
 
-from parcels._core.statuscodes import _raise_time_extrapolation_error
+from parcels._core.statuscodes import _raise_outside_time_interval_error
 
 if TYPE_CHECKING:
     from parcels._core.field import Field
@@ -78,7 +78,7 @@ def _search_time_index(field: Field, time: datetime):
         return np.zeros(shape=time.shape, dtype=np.float32), np.zeros(shape=time.shape, dtype=np.int32)
 
     if not field.time_interval.is_all_time_in_interval(time):
-        _raise_time_extrapolation_error(time, field=None)
+        _raise_outside_time_interval_error(time, field=None)
 
     ti = np.searchsorted(field.data.time.data, time, side="right") - 1
     tau = (time - field.data.time.data[ti]) / (field.data.time.data[ti + 1] - field.data.time.data[ti])

src/parcels/_core/kernel.py

@@ -14,7 +14,7 @@
     _raise_field_out_of_bound_surface_error,
     _raise_general_error,
     _raise_grid_searching_error,
-    _raise_time_extrapolation_error,
+    _raise_outside_time_interval_error,
 )
 from parcels._core.warnings import KernelWarning
 from parcels.kernels import (
@@ -31,7 +31,7 @@
 
 
 ErrorsToThrow = {
-    StatusCode.ErrorTimeExtrapolation: _raise_time_extrapolation_error,
+    StatusCode.ErrorOutsideTimeInterval: _raise_outside_time_interval_error,
     StatusCode.ErrorOutOfBounds: _raise_field_out_of_bound_error,
     StatusCode.ErrorThroughSurface: _raise_field_out_of_bound_surface_error,
     StatusCode.ErrorInterpolation: _raise_field_interpolation_error,
@@ -279,7 +279,7 @@ def execute(self, pset, endtime, dt):
             for error_code, error_func in ErrorsToThrow.items():
                 if np.any(pset.state == error_code):
                     inds = pset.state == error_code
-                    if error_code == StatusCode.ErrorTimeExtrapolation:
+                    if error_code == StatusCode.ErrorOutsideTimeInterval:
                         error_func(pset[inds].time)
                     else:
                         error_func(pset[inds].z, pset[inds].lat, pset[inds].lon)

src/parcels/_core/statuscodes.py

@@ -5,14 +5,14 @@
     "FieldOutOfBoundError",
     "FieldSamplingError",
     "KernelError",
+    "OutsideTimeInterval",
     "StatusCode",
-    "TimeExtrapolationError",
     "_raise_field_interpolation_error",
     "_raise_field_out_of_bound_error",
     "_raise_field_out_of_bound_surface_error",
     "_raise_general_error",
     "_raise_grid_searching_error",
-    "_raise_time_extrapolation_error",
+    "_raise_outside_time_interval_error",
 ]
 
 
@@ -30,7 +30,7 @@ class StatusCode:
     ErrorGridSearching = 52
     ErrorOutOfBounds = 60
     ErrorThroughSurface = 61
-    ErrorTimeExtrapolation = 70
+    ErrorOutsideTimeInterval = 70
 
 
 class FieldInterpolationError(RuntimeError):
@@ -94,19 +94,16 @@ def _raise_general_error(z, y, x):
     raise GeneralError(f"General error occurred at (z={z}, lat={y}, lon={x})")
 
 
-class TimeExtrapolationError(RuntimeError):
+class OutsideTimeInterval(RuntimeError):
     """Utility error class to propagate erroneous time extrapolation sampling."""
 
     def __init__(self, time, field=None):
-        message = (
-            f"{field.name if field else 'Field'} sampled outside time domain at time {time}."
-            " Try setting allow_time_extrapolation to True."
-        )
+        message = f"{field.name if field else 'Field'} sampled outside time domain at time {time}."
         super().__init__(message)
 
 
-def _raise_time_extrapolation_error(time: float, field=None):
-    raise TimeExtrapolationError(time, field)
+def _raise_outside_time_interval_error(time: float, field=None):
+    raise OutsideTimeInterval(time, field)
 
 
 class KernelError(RuntimeError):
@@ -124,7 +121,7 @@ def __init__(self, particles, fieldset=None, msg=None):
     FieldOutOfBoundError: StatusCode.ErrorOutOfBounds,
     FieldOutOfBoundSurfaceError: StatusCode.ErrorThroughSurface,
     GridSearchingError: StatusCode.ErrorGridSearching,
-    TimeExtrapolationError: StatusCode.ErrorTimeExtrapolation,
+    OutsideTimeInterval: StatusCode.ErrorOutsideTimeInterval,
     KernelError: StatusCode.Error,
     GeneralError: StatusCode.Error,
 }

tests/test_particleset_execute.py

@@ -9,11 +9,11 @@
     FieldInterpolationError,
     FieldOutOfBoundError,
     FieldSet,
+    OutsideTimeInterval,
     Particle,
     ParticleFile,
     ParticleSet,
     StatusCode,
-    TimeExtrapolationError,
     UxGrid,
     Variable,
     VectorField,
@@ -286,7 +286,7 @@ def test_some_particles_throw_outoftime(fieldset):
     def FieldAccessOutsideTime(particles, fieldset):  # pragma: no cover
         fieldset.U[particles.time + np.timedelta64(400, "D"), particles.z, particles.lat, particles.lon, particles]
 
-    with pytest.raises(TimeExtrapolationError):
+    with pytest.raises(OutsideTimeInterval):
         pset.execute(FieldAccessOutsideTime, runtime=np.timedelta64(1, "D"), dt=np.timedelta64(10, "D"))