New and updated reprs for Variable, ParticleFile, Field, VectorField, and ParticleSet

docs/examples/parcels_tutorial.ipynb

@@ -152,8 +152,12 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "P[0](lon=330000.000000, lat=100000.000000, depth=0.000000, time=not_yet_set)\n",
-      "P[1](lon=330000.000000, lat=280000.000000, depth=0.000000, time=not_yet_set)\n"
+      "<ParticleSet>\n",
+      "    fieldset   : <parcels.fieldset.FieldSet object at 0x15f033530>\n",
+      "    pclass     : False\n",
+      "    repeatdt   : None\n",
+      "    # particles: 2\n",
+      "    particles  : [P[0](lon=330000.000000, lat=100000.000000, depth=0.000000, time=not_yet_set), P[1](lon=330000.000000, lat=280000.000000, depth=0.000000, time=not_yet_set)]\n"
      ]
     }
    ],
@@ -220,8 +224,22 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "INFO: Output files are stored in EddyParticles.zarr.\n",
-      "100%|██████████| 518400.0/518400.0 [00:03<00:00, 172443.78it/s]\n"
+      "INFO: Output files are stored in EddyParticles.zarr.\n"
+     ]
+    },
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "/Users/erik/Codes/ParcelsCode/parcels/particleset.py:1082: FileWarning: Some of the particles have a start time that is not a multiple of outputdt. This could cause the first output to be at a different time than expected.\n",
+      "  _warn_outputdt_release_desync(outputdt, self.particledata.data[\"time_nextloop\"])\n"
+     ]
+    },
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "100%|██████████| 518400.0/518400.0 [00:05<00:00, 95421.55it/s] \n"
      ]
     }
    ],
@@ -13228,8 +13246,12 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "P[0](lon=329983.281250, lat=100495.609375, depth=0.000000, time=300.000000)\n",
-      "P[1](lon=330289.968750, lat=280418.906250, depth=0.000000, time=300.000000)\n"
+      "<ParticleSet>\n",
+      "    fieldset   : <parcels.fieldset.FieldSet object at 0x15f033530>\n",
+      "    pclass     : False\n",
+      "    repeatdt   : None\n",
+      "    # particles: 2\n",
+      "    particles  : [P[0](lon=329983.281250, lat=100495.609375, depth=0.000000, time=300.000000), P[1](lon=330289.968750, lat=280418.906250, depth=0.000000, time=300.000000)]\n"
      ]
     },
     {

parcels/field.py

@@ -21,7 +21,7 @@
     assert_valid_gridindexingtype,
     assert_valid_interp_method,
 )
-from parcels.tools._helpers import deprecated_made_private
+from parcels.tools._helpers import deprecated_made_private, pretty_field
 from parcels.tools.converters import (
     Geographic,
     GeographicPolar,
@@ -312,6 +312,9 @@ def __init__(
         if len(kwargs) > 0:
             raise SyntaxError(f'Field received an unexpected keyword argument "{list(kwargs.keys())[0]}"')
 
+    def __repr__(self) -> str:
+        return pretty_field(self)
+
     @property
     @deprecated_made_private  # TODO: Remove 6 months after v3.1.0
     def dataFiles(self):

parcels/particle.py

@@ -53,7 +53,7 @@ def __set__(self, instance, value):
             setattr(instance, f"_{self.name}", value)
 
     def __repr__(self):
-        return f"PVar<{self.name}|{self.dtype}>"
+        return f"Variable(name={self._name}, dtype={self.dtype}, initial={self.initial}, to_write={self.to_write})"
 
     def is64bit(self):
         """Check whether variable is 64-bit."""

parcels/particlefile.py

@@ -10,7 +10,7 @@
 
 import parcels
 from parcels._compat import MPI
-from parcels.tools._helpers import deprecated, deprecated_made_private
+from parcels.tools._helpers import default_repr, deprecated, deprecated_made_private
 from parcels.tools.warnings import FileWarning
 
 __all__ = ["ParticleFile"]
@@ -116,6 +116,16 @@
                 fname = name if extension in [".zarr"] else f"{name}.zarr"
         self._fname = fname
 
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}("
+            f"name={self.fname!r}, "
+            f"particleset={default_repr(self.particleset)}, "
+            f"outputdt={self.outputdt!r}, "
+            f"chunks={self.chunks!r}, "
+            f"create_new_zarrfile={self.create_new_zarrfile!r})"
+        )
+
     @property
     def create_new_zarrfile(self):
         return self._create_new_zarrfile

parcels/particleset.py

@@ -27,7 +27,7 @@
 from parcels.particle import JITParticle, Variable
 from parcels.particledata import ParticleData, ParticleDataIterator
 from parcels.particlefile import ParticleFile
-from parcels.tools._helpers import deprecated, deprecated_made_private
+from parcels.tools._helpers import deprecated, deprecated_made_private, pretty_particleset
 from parcels.tools.converters import _get_cftime_calendars, convert_to_flat_array
 from parcels.tools.global_statics import get_package_dir
 from parcels.tools.loggers import logger
@@ -386,7 +386,7 @@ def size(self):
         return len(self.particledata)
 
     def __repr__(self):
-        return "\n".join([str(p) for p in self])
+        return pretty_particleset(self)
 
     def __len__(self):
         return len(self.particledata)

parcels/tools/_helpers.py

@@ -1,9 +1,15 @@
 """Internal helpers for Parcels."""
 
+from __future__ import annotations
+
 import functools
 import warnings
 from collections.abc import Callable
+from textwrap import dedent
+from typing import TYPE_CHECKING, Any
 
+if TYPE_CHECKING:
+    from parcels import Field, ParticleSet
 PACKAGE = "Parcels"
 
 
@@ -56,3 +62,37 @@
 
 def patch_docstring(obj: Callable, extra: str) -> None:
     obj.__doc__ = f"{obj.__doc__ or ''}{extra}".strip()
+
+
+def pretty_field(field: Field) -> str:
+    """Return a pretty repr for Field"""
+    out = f"""<{type(field).__name__}>
+    grid            : {field.grid!r                    }
+    extrapolate time: {field.allow_time_extrapolation!r}
+    time_periodic   : {field.time_periodic!r           }
+    gridindexingtype: {field.gridindexingtype!r        }
+    to_write        : {field.to_write!r                }
+"""
+    return dedent(out).strip()
+
+
+def pretty_particleset(pset: ParticleSet) -> str:
+    """Return a pretty repr for ParticleSet"""
+    if len(pset) < 10:
+        particles = repr(list(pset))
+    else:
+        lst = [repr(pset[i]) for i in range(7)] + ["..."]
+        particles = f"[{', '.join(lst)}]"
+
+    out = f"""<{type(pset).__name__}>
+    fieldset   : {pset.fieldset}
+    pclass     : {pset.pclass}
+    repeatdt   : {pset.repeatdt}
+    # particles: {len(pset)}
+    particles  : {particles}
+"""
+    return dedent(out).strip()
+
+
+def default_repr(obj: Any):
+    return object.__repr__(obj)

tests/test_reprs.py

@@ -1,9 +1,12 @@
+import re
+from datetime import timedelta
 from typing import Any
 
 import numpy as np
 
-from parcels import Grid, TimeConverter
+from parcels import Grid, ParticleFile, TimeConverter, Variable
 from parcels.grid import RectilinearGrid
+from tests.utils import create_fieldset_unit_mesh, create_simple_pset
 
 
 def validate_simple_repr(class_: type, kwargs: dict[str, Any]):
@@ -17,6 +20,36 @@
     assert class_.__name__ in obj_repr
 
 
+def valid_indentation(s: str) -> bool:
+    """Make sure that all lines in string is indented with a multiple of 4 spaces."""
+    if s.startswith(" "):
+        return False
+
+    lines = s.split("\n")
+    for line in lines:
+        line = re.sub("^( {4})+", "", line)
+        if line.startswith(" "):
+            return False
+    return True
+
+
+def test_check_indentation():
+    valid = """
+test
+    test
+test
+    test
+        test
+    test"""
+    assert valid_indentation(valid)
+    invalid = """
+test
+    test
+ invalid!
+"""
+    assert not valid_indentation(invalid)
+
+
 def test_grid_repr():
     """Test arguments are in the repr of a Grid object"""
     kwargs = dict(
@@ -25,6 +58,12 @@
     validate_simple_repr(Grid, kwargs)
 
 
+def test_variable_repr():
+    """Test arguments are in the repr of the Variable object."""
+    kwargs = dict(name="test", dtype=np.float32, initial=0, to_write=False)
+    validate_simple_repr(Variable, kwargs)
+
+
 def test_rectilineargrid_repr():
     """
     Test arguments are in the repr of a RectilinearGrid object.
@@ -35,3 +74,24 @@
         lon=np.array([1, 2, 3]), lat=np.array([4, 5, 6]), time=None, time_origin=TimeConverter(), mesh="spherical"
     )
     validate_simple_repr(RectilinearGrid, kwargs)
+
+
+def test_particlefile_repr():
+    pset = create_simple_pset()
+    kwargs = dict(
+        name="file.zarr", particleset=pset, outputdt=timedelta(hours=1), chunks=None, create_new_zarrfile=False
+    )
+    validate_simple_repr(ParticleFile, kwargs)
+
+
+def test_field_repr():
+    field = create_fieldset_unit_mesh().U
+    assert valid_indentation(repr(field))
+
+
+def test_particleset_repr():
+    pset = create_simple_pset()
+    valid_indentation(repr(pset))
+
+    pset = create_simple_pset(n=15)
+    valid_indentation(repr(pset))

tests/utils.py

@@ -4,6 +4,7 @@
 
 import numpy as np
 
+import parcels
 from parcels import FieldSet
 
 PROJECT_ROOT = Path(__file__).resolve().parents[1]
@@ -47,6 +48,18 @@ def create_fieldset_zeros_conversion(mesh="spherical", xdim=200, ydim=100, mesh_
     return FieldSet.from_data(data, dimensions, mesh=mesh)
 
 
+def create_simple_pset(n=1):
+    zeros = np.zeros(n)
+    return parcels.ParticleSet(
+        fieldset=create_fieldset_unit_mesh(),
+        pclass=parcels.ScipyParticle,
+        lon=zeros,
+        lat=zeros,
+        depth=zeros,
+        time=zeros,
+    )
+
+
 def create_spherical_positions(n_particles, max_depth=100000):
     yrange = 2 * np.random.rand(n_particles)
     lat = 180 * (np.arccos(1 - yrange) - 0.5 * np.pi) / np.pi