Revise API for component parameters, constants, and states

.github/workflows/tests.yml → .github/workflows/basic_tests.yml

@@ -47,22 +47,6 @@ jobs:
         run: |
           mamba install udunits2=2.2.25
           mamba install --file=requirements.txt
-
-      # build dummy components required for tests
-      - name: install Fortran compiler (linux)
-        if: matrix.os == 'ubuntu-latest'
-        run: |
-          mamba install gfortran_impl_linux-64
-
-      - name: install Fortran compiler (macos)
-        if: matrix.os == 'macos-latest'
-        run: |
-          mamba install gfortran_impl_osx-64
-
-      - name: build dummy C and Fortran components 
-        run: |
-          mamba install cython
-          (cd ./tests/components && make)
 
       # install package
       - name: install package

.gitignore

@@ -1,5 +1,6 @@
 __pycache__/
 *.pyc
+*.pyf
 *.so
 
 # ignore documentation built because copied in docs/ root already

README.rst

@@ -4,7 +4,7 @@ Community Model for the Terrestrial Water Cycle
 .. image:: https://img.shields.io/pypi/v/cm4twc?style=flat-square&color=00b0f0
    :target: https://pypi.python.org/pypi/cm4twc
    :alt: PyPI Version
-.. image:: https://zenodo.org/badge/234523723.svg
+.. image:: https://img.shields.io/badge/dynamic/json?url=https://zenodo.org/api/records/4726695&label=DOI&query=doi&style=flat-square&color=00b0f0
    :target: https://zenodo.org/badge/latestdoi/234523723
    :alt: DOI
 .. image:: https://img.shields.io/github/license/hydro-jules/cm4twc?style=flat-square&color=00b0f0

changelog.rst

@@ -3,11 +3,25 @@ v0.1.0
 
 Released on 2021, ???.
 
+.. rubric:: API changes
+
+* add units requirement for component parameters and constants
+  (`#21 <https://github.com/hydro-jules/cm4twc/issues/21>`_)
+
 .. rubric:: Bug fixes
 
 * fix dump file update bug due to missing 'divisions' dimension
   (`#32 <https://github.com/hydro-jules/cm4twc/issues/32>`_)
 
+.. rubric:: Enhancements
+
+* add support for arrays for component parameters
+  (`#21 <https://github.com/hydro-jules/cm4twc/issues/21>`_)
+* add support for multiple divisions for component states
+  (`#39 <https://github.com/hydro-jules/cm4twc/pull/39>`_)
+* add support for customisable divisions for component states
+  (`#31 <https://github.com/hydro-jules/cm4twc/issues/31>`_)
+
 .. rubric:: Documentation
 
 * document 'divisions' for component states in preparation page

cm4twc/components/_utils/records.py

@@ -75,9 +75,10 @@ def _delta_to_frequency_str(delta):
 
 class Record(object):
 
-    def __init__(self, name, units, **kwargs):
+    def __init__(self, name, units, divisions=(), **kwargs):
         self.name = name
         self.units = units
+        self.divisions = divisions
         self.streams = []
 
 
@@ -131,6 +132,8 @@ def __init__(self, delta):
         self.methods = {}
         # mapping to store record arrays (keys are record names)
         self.arrays = {}
+        # mapping to store record masks (keys are record names)
+        self.masks = {}
         # mapping for integer tracker to know where in array to write next
         # (keys are record names)
         self.array_trackers = {}
@@ -139,6 +142,22 @@ def __init__(self, delta):
         self.trigger = None
         self.trigger_tracker = None
 
+    def add_record(self, record, methods):
+        name = record.name
+        # store link to record object
+        self.records[name] = record
+        # store sequence of aggregation methods
+        methods_ = set()
+        for method in methods:
+            if method in _methods_map:
+                methods_.add(_methods_map[method])
+            else:
+                raise ValueError('method {} for record {} aggregation '
+                                 'unknown'.format(method, name))
+        self.methods[name] = methods_
+        # map this very stream in the record
+        record.streams.append(self)
+
     def initialise(self, timedomain, spacedomain, _skip_trackers=False):
         # check delta / timedomain resolution compatibility
         if (self.delta % timedomain.timedelta) != timedelta(seconds=0):
@@ -164,11 +183,31 @@ def initialise(self, timedomain, spacedomain, _skip_trackers=False):
 
         # initialise record arrays for accumulating values
         self.trigger = 0
-        for name in self.records:
+        for name, record in self.records.items():
             self.array_trackers[name] = 0
-            arr = np.zeros((self.length, *spacedomain.shape), dtype_float())
+
+            d = record.divisions
+
+            # initialise array
+            arr = np.zeros(
+                (self.length, *spacedomain.shape, *d), dtype_float()
+            )
             arr[:] = np.nan
             self.arrays[name] = arr
+
+            # process array mask
+            if spacedomain.land_sea_mask is None:
+                msk = None
+            else:
+                msk = ~spacedomain.land_sea_mask
+                if d:
+                    axes = [-(a + 1) for a in range(len(d))]
+                    msk = np.broadcast_to(
+                        np.expand_dims(msk, axis=axes),
+                        (*spacedomain.shape, *d)
+                    )
+            self.masks[name] = msk
+
             # add on length of stream to the record trigger
             self.trigger += self.length
 
@@ -177,22 +216,6 @@ def initialise(self, timedomain, spacedomain, _skip_trackers=False):
             self.time_tracker = 0
             self.trigger_tracker = 0
 
-    def add_record(self, record, methods):
-        name = record.name
-        # store link to record object
-        self.records[name] = record
-        # store sequence of aggregation methods
-        methods_ = set()
-        for method in methods:
-            if method in _methods_map:
-                methods_.add(_methods_map[method])
-            else:
-                raise ValueError('method {} for record {} aggregation '
-                                 'unknown'.format(method, name))
-        self.methods[name] = methods_
-        # map this very stream in the record
-        record.streams.append(self)
-
     def update_record(self, name, value):
         self.arrays[name][self.array_trackers[name], ...] = value
         self.array_trackers[name] += 1
@@ -237,11 +260,21 @@ def create_record_stream_file(self, filepath):
             b.calendar = self.timedomain.calendar
 
             for name, record in self.records.items():
+                d = record.divisions
+                if d:
+                    dims = []
+                    for n, v in enumerate(d):
+                        dim_name = '_'.join([name, 'divisions', str(n + 1)])
+                        f.createDimension(dim_name, v)
+                        dims.append(dim_name)
+                    dims = ('time', *axes, *dims)
+                else:
+                    dims = ('time', *axes)
+
                 # record variable
                 for method in self.methods[name]:
                     name_method = '_'.join([name, method])
-                    v = f.createVariable(name_method, dtype_float(),
-                                         ('time', *axes))
+                    v = f.createVariable(name_method, dtype_float(), dims)
                     v.standard_name = name
                     v.units = record.units
                     v.cell_methods = "time: {} over {}".format(
@@ -281,9 +314,7 @@ def update_record_to_stream_file(self):
 
                     # store result in file
                     f.variables[name_method][t] = np.ma.array(
-                        value, mask=(~self.spacedomain.land_sea_mask
-                                     if self.spacedomain.land_sea_mask
-                                     is not None else None)
+                        value, mask=self.masks[name]
                     )
 
                 # reset array tracker to point to start of array again
@@ -335,8 +366,18 @@ def create_record_stream_dump(self, filepath):
 
             # records
             for name, record in self.records.items():
-                s = f.createVariable(name, dtype_float(),
-                                     ('time', 'length', *axes),
+                d = record.divisions
+                if d:
+                    dims = []
+                    for n, v in enumerate(d):
+                        dim_name = '_'.join([name, 'divisions', str(n + 1)])
+                        f.createDimension(dim_name, v)
+                        dims.append(dim_name)
+                    dims = ('time', 'length', *axes, *dims)
+                else:
+                    dims = ('time', 'length', *axes)
+
+                s = f.createVariable(name, dtype_float(), dims,
                                      fill_value=9.9692099683868690E36)
                 s.standard_name = name
                 s.units = record.units

cm4twc/components/_utils/states.py

@@ -119,15 +119,18 @@ def create_states_dump(filepath, states_info, solver_history,
 
         # state variables
         for var in states_info:
-            d = states_info[var].get('divisions', 1)
-            if d > 1:
-                f.createDimension('{}_divisions'.format(var), d)
-                s = f.createVariable(var, dtype_float(),
-                                     ('time', 'history', *axes,
-                                      '{}_divisions'.format(var)))
+            d = states_info[var]['divisions']
+            if d:
+                dims = []
+                for n, v in enumerate(d):
+                    dim_name = '_'.join([var, 'divisions', str(n + 1)])
+                    f.createDimension(dim_name, v)
+                    dims.append(dim_name)
+                dims = ('time', 'history', *axes, *dims)
             else:
-                s = f.createVariable(var, dtype_float(),
-                                     ('time', 'history', *axes))
+                dims = ('time', 'history', *axes)
+
+            s = f.createVariable(var, dtype_float(), dims)
 
             s.standard_name = var
             s.units = states_info[var]['units']