Issue #1299 public api fixes from imod5 (#1300)

Fixes #1299

* The SimulationAllocationOptions and SimulationDistributingOptions are
stowed away very far, and not part of the public API
* Yet, these objects used to store default settings are required to call
the public api method Modflow6Simulation.from_imod5_data...
* A description of "period_times" is missing in the docstring
* Example code snippets are missing from the docstring

# Description
This PR fixes the following things:
* Makes ``SimulationAllocationOptions`` and
``SimulationDistributingOptions`` part of the public API
* Makes ``allocation_options`` and ``distributing_options`` optional
arguments for ``Modflow6Simulation.from_imod5_data`` and
``GroundwaterFlowModel.from_imod5_data``
* To do this, I had to change the order of arguments for
Modflow6Simulation.from_imod5_data, as Python doesn't allow non-optional
args after an optional arg. This can break existing scripts, however
this has just been released, so not many scripts use it. As long as the
tutorial material is updated within time.
* Extends docstrings of ``GroundwaterFlowModel.from_imod5_data``,
``Modflow6Simulation.from_imod5_data``, ``SimulationAllocationOptions``,
and ``SimulationDistributingOptions``

Author: JoerivanEngelen

docs/api/changelog.rst

@@ -9,6 +9,13 @@ The format is based on `Keep a Changelog`_, and this project adheres to
 [Unreleased]
 ------------
 
+Added
+~~~~~
+
+- :class:`imod.prepare.topsystem.SimulationAllocationOptions`,
+  :class:`imod.prepare.topsystem.SimulationDistributingOptions`, which are used
+  to store default allocation and distributing options respectively.
+
 Fixed
 ~~~~~
 
@@ -19,6 +26,18 @@ Fixed
 - Fix bug where no ``ValidationError`` was thrown if there is an active RCH, DRN,
   GHB, or RIV cell where idomain = -1.
 
+Changed
+~~~~~~~
+
+- In :meth:`imod.mf6.Modflow6Simulation.from_imod5_data`, and
+  :meth:`imod.mf6.GroundwaterFlowModel.from_imod5_data` the arguments
+  ``allocation_options``, ``distributing_options`` are now optional.
+- The order of arguments of :meth:`imod.mf6.Modflow6Simulation.from_imod5_data`, 
+  and :meth:`imod.mf6.GroundwaterFlowModel.from_imod5_data`. It now is 
+  ``imod5_data, period_data, times, allocation_options, distributing_options, regridder_types``
+  instead of:
+  ``imod5_data, period_data, allocation_options, distributing_options, times, regridder_types``
+
 
 [0.18.0]
 --------

docs/api/prepare.rst

@@ -38,6 +38,8 @@ Prepare model input
 
     ALLOCATION_OPTION
     DISTRIBUTING_OPTION
+    SimulationAllocationOptions
+    SimulationDistributingOptions
     allocate_drn_cells
     allocate_ghb_cells
     allocate_rch_cells

imod/formats/prj/prj.py

@@ -1017,7 +1017,7 @@ def _is_var_ipf_and_path(block_content: dict[str, Any], var: str):
     return is_ipf, path
 
 
-def open_projectfile_data(path: FilePath) -> Dict[str, Any]:
+def open_projectfile_data(path: FilePath) -> tuple[dict[str, Any], dict[str, Any]]:
     """
     Read the contents of an iMOD project file and read/open the data present in
     it:

imod/mf6/model_gwf.py

@@ -192,22 +192,35 @@ def from_imod5_data(
         cls,
         imod5_data: dict[str, dict[str, GridDataArray]],
         period_data: dict[str, list[datetime]],
-        allocation_options: SimulationAllocationOptions,
-        distributing_options: SimulationDistributingOptions,
         times: list[datetime],
-        regridder_types: dict[str, RegridMethodType],
+        allocation_options: Optional[SimulationAllocationOptions] = None,
+        distributing_options: Optional[SimulationDistributingOptions] = None,
+        regridder_types: Optional[dict[str, RegridMethodType]] = None,
     ) -> "GroundwaterFlowModel":
         """
-        Imports a GroundwaterFlowModel (GWF) from the data in an IMOD5 project file.
-        It adds the packages for which import from imod5 is supported.
-        Some packages (like OC) must be added manually later.
+        Imports a GroundwaterFlowModel (GWF) from the data in an iMOD5 project
+        file and puts it in a simulation. Quasi-3D iMOD5 models, i.e. models
+        where there is only horizontal flow in aquifers and vertical flow in
+        aquitards, are not supported.
 
+        This method adds all static and boundary condition packages from the
+        projectfile to the simulation. Output Control (OC) must be added
+        manually after importing.
 
         Parameters
         ----------
         imod5_data: dict[str, dict[str, GridDataArray]]
             dictionary containing the arrays mentioned in the project file as xarray datasets,
             under the key of the package type to which it belongs
+        period_data: dict[str, list[datetime]]
+            dictionary containing the package names mapped to a list of repeated
+            stress periods. These are set as ``repeat_stress``.
+        times: list[datetime]
+            Time discretization of the simulation. These times are used for the
+            following:
+               * Times of wells with associated timeseries are resampled to these times
+               * Start- and end times in the list are used to repeat the stresses
+                 of periodic data (e.g. river stages in iMOD5 for "summer", "winter")
         allocation_options: SimulationAllocationOptions
             object containing the allocation options per package type.
             If you want a package to have a different allocation option,
@@ -216,10 +229,6 @@ def from_imod5_data(
             object containing the conductivity distribution options per package type.
             If you want a package to have a different allocation option,
             then it should be imported separately
-        time_min: datetime
-            Begin-time of the simulation.
-        time_max: datetime
-            End-time of the simulation.
         regridder_types:  dict[str, RegridMethodType]
             the key is the package name. The value is a subclass of RegridMethodType.
 
@@ -229,6 +238,13 @@ def from_imod5_data(
         add the OC package to the model.
 
         """
+        if allocation_options is None:
+            allocation_options = SimulationAllocationOptions()
+        if distributing_options is None:
+            distributing_options = SimulationDistributingOptions()
+        if regridder_types is None:
+            regridder_types = {}
+
         # first import the singleton packages
         # import dis
         regrid_cache = RegridderWeightsCache()

imod/mf6/simulation.py

@@ -1331,51 +1331,100 @@ def mask_all_models(
     def from_imod5_data(
         cls,
         imod5_data: dict[str, dict[str, GridDataArray]],
-        period_data: dict[str, dict[str, GridDataArray]],
-        allocation_options: SimulationAllocationOptions,
-        distributing_options: SimulationDistributingOptions,
+        period_data: dict[str, list[datetime]],
         times: list[datetime],
-        regridder_types: dict[str, RegridMethodType] = {},
+        allocation_options: Optional[SimulationAllocationOptions] = None,
+        distributing_options: Optional[SimulationDistributingOptions] = None,
+        regridder_types: Optional[dict[str, RegridMethodType]] = None,
     ) -> "Modflow6Simulation":
         """
-        Imports a GroundwaterFlowModel (GWF) from the data in an IMOD5 project file.
-        It adds the packages for which import from imod5 is supported.
-        Some packages (like OC) must be added manually later.
-
+        Imports a GroundwaterFlowModel (GWF) from the data in an iMOD5 project
+        file and puts it in a simulation. Quasi-3D iMOD5 models, i.e. models
+        where there is only horizontal flow in aquifers and vertical flow in
+        aquitards, are not supported.
+
+        This method adds all static and boundary condition packages from the
+        projectfile to the simulation. Output Control (OC) must be added
+        manually after importing. The
+        :func:`imod.mf6.ims.SolutionPresetModerate` solver settings are added
+        automatically under the "ims" key, but these can be overrided by the
+        user after importing.
 
         Parameters
         ----------
         imod5_data: dict[str, dict[str, GridDataArray]]
             dictionary containing the arrays mentioned in the project file as xarray datasets,
-            under the key of the package type to which it belongs
-        allocation_options: SimulationAllocationOptions
-            object containing the allocation options per package type.
-            If you want a package to have a different allocation option,
-            then it should be imported separately
-        distributing_options: SimulationDistributingOptions
-            object containing the conductivity distribution options per package type.
-            If you want a package to have a different allocation option,
-            then it should be imported separately
+            under the key of the package type to which it belongs.
+        period_data: dict[str, list[datetime]]
+            dictionary containing the package names mapped to a list of repeated
+            stress periods. These are set as ``repeat_stress``.
         times:  list[datetime]
-            time discretization of the model to be imported.
+            time discretization of the model to be imported. This is used for
+            the following:
+                * Times of wells with associated timeseries are resampled to these times
+                * Start and end times in the list are used to repeat the stresses
+                  of periodic data (e.g. river stages in iMOD5 for "summer", "winter")
+                * The simulation is discretized to these times, using
+                  :meth:`imod.mf6.Modflow6Simulation.create_time_discretization`
+        allocation_options: SimulationAllocationOptions, optional
+            object containing the allocation options per package type. If you
+            want a specific package to have a different allocation option, then
+            it should be imported separately.
+        distributing_options: SimulationDistributingOptions, optional
+            object containing the conductivity distribution options per package
+            type. If you want a package to have a different allocation option,
+            then it should be imported separately.
         regridder_types: dict[str, RegridMethodType]
             the key is the package name. The value is the RegridMethodType
             object containing the settings for regridding the package with the
-            specified key
+            specified key.
 
         Returns
         -------
+        Modflow6Simulation
+            Simulation prepared for MODFLOW6
+
+        Examples
+        --------
+        Open projectfile data first:
+
+        >>> from imod.formats.prj import open_projectfile_data
+        >>> imod5_data, period_data = open_projectfile_data("path/to/projectfile")
+
+        You can then import the simulation as follows:
+
+        >>> times = [np.datetime("2001-01-01"), np.datetime("2002-01-01"), np.datetime("2003-01-01")]
+        >>> mf6_sim = imod.mf6.Modflow6Simulation.from_imod5_data(imod5_data, period_data, times)
+
+        Allocate rivers differently:
+
+        >>> from imod.prepare.topsystem import SimulationAllocationOptions, ALLOCATION_OPTION
+        >>> allocation_options = SimulationAllocationOptions()
+        >>> allocation_options.riv = ALLOCATION_OPTION.at_elevation
+        >>> mf6_sim = imod.mf6.Modflow6Simulation.from_imod5_data(imod5_data, period_data, times, allocation_options)
+
+        You can override solver settings if needed after importing:
+
+        >>> mf6_sim["imported_model"]["ims"] = SolutionPresetComplex()
+
         """
+        if allocation_options is None:
+            allocation_options = SimulationAllocationOptions()
+        if distributing_options is None:
+            distributing_options = SimulationDistributingOptions()
+        if regridder_types is None:
+            regridder_types = {}
+
         simulation = Modflow6Simulation("imported_simulation")
         simulation._validation_context.strict_well_validation = False
 
         # import GWF model,
         groundwaterFlowModel = GroundwaterFlowModel.from_imod5_data(
             imod5_data,
             period_data,
+            times,
             allocation_options,
             distributing_options,
-            times,
             regridder_types,
         )
         simulation["imported_model"] = groundwaterFlowModel

imod/prepare/topsystem/__init__.py

@@ -11,4 +11,8 @@
     distribute_ghb_conductance,
     distribute_riv_conductance,
 )
+from imod.prepare.topsystem.default_allocation_methods import (
+    SimulationAllocationOptions,
+    SimulationDistributingOptions,
+)
 from imod.prepare.topsystem.resistance import c_leakage, c_radial

imod/prepare/topsystem/default_allocation_methods.py

@@ -7,14 +7,33 @@
 @dataclass()
 class SimulationAllocationOptions:
     """
-    Object containing allocation otpions, specified per packages type on
-    importing fron imod5. Can be used to set defaults when importing a
+    Object containing default allocation options, specified per packages type on
+    importing from imod5. Can be used to set defaults when importing a
     simulation or a GroundwaterFlowModel from imod5.
 
     Parameters
     ----------
-    drn: allocation option to be used for drainage packages
-    riv: allocation option to be used for river packages
+    drn: ALLOCATION_OPTION
+        allocation option to be used for drainage packages, defaults to
+        ``first_active_to_elevation``.
+    riv: ALLOCATION_OPTION
+        allocation option to be used for river packages, defaults to
+        ``stage_to_riv_bot``.
+    ghb: ALLOCATION_OPTION
+        allocation option to be used for general head boundary packages,
+        defaults to ``at_elevation``.
+
+    Examples
+    --------
+
+    Initiate allocation default options
+
+    >>> alloc_options = SimulationAllocationOptions()
+
+    You can set different options as follows:
+
+    >>> from imod.prepare.topsystem import ALLOCATION_OPTION
+    >>> alloc_options.riv = ALLOCATION_OPTION.at_elevation
 
     """
 
@@ -26,14 +45,33 @@ class SimulationAllocationOptions:
 @dataclass()
 class SimulationDistributingOptions:
     """
-    Object containing conductivity distribution methods, specified per packages
+    Object containing conductance distribution methods, specified per packages
     type. Can be used to set defaults when importing a simulation or a
     GroundwaterFlowModel from imod5.
 
     Parameters
     ----------
-    drn: distribution option to be used for drainage packages
-    riv: distribution option to be used for river packages
+    drn: DISTRIBUTING_OPTION
+        distribution option to be used for drainage packages, defaults to
+        ``by_corrected_transmissivity``.
+    riv: DISTRIBUTING_OPTION
+        distribution option to be used for river packages, defaults to
+        ``by_corrected_transmissivity``.
+    ghb: DISTRIBUTING_OPTION
+        distribution option to be used for general head boundary packages,
+        defaults to ``by_layer_transmissivity``.
+
+    Examples
+    --------
+
+    Initiate default distributing options
+
+    >>> dist_options = SimulationDistributingOptions()
+
+    You can set different options as follows:
+
+    >>> from imod.prepare.topsystem import DISTRIBUTING_OPTION
+    >>> dist_options.riv = DISTRIBUTING_OPTION.by_layer_transmissivity
 
     """
 

imod/tests/test_mf6/test_mf6_LHM.py

@@ -50,9 +50,9 @@ def LHM_imod5_data():
     simulation = Modflow6Simulation.from_imod5_data(
         imod5_data,
         period_data,
+        times,
         default_simulation_allocation_options,
         default_simulation_distributing_options,
-        times,
         regridding_option,
     )
     simulation["imported_model"]["oc"] = OutputControl(

imod/tests/test_mf6/test_mf6_simulation.py

@@ -491,9 +491,9 @@ def test_import_from_imod5(imod5_dataset, tmp_path):
     simulation = Modflow6Simulation.from_imod5_data(
         imod5_data,
         period_data,
+        datelist,
         default_simulation_allocation_options,
         default_simulation_distributing_options,
-        datelist,
     )
     simulation["imported_model"]["oc"] = OutputControl(
         save_head="last", save_budget="last"
@@ -527,9 +527,9 @@ def test_from_imod5__strict_well_validation_set(imod5_dataset):
     simulation = Modflow6Simulation.from_imod5_data(
         imod5_data,
         period_data,
+        datelist,
         default_simulation_allocation_options,
         default_simulation_distributing_options,
-        datelist,
     )
     assert simulation._validation_context.strict_well_validation is False
     assert Modflow6Simulation("test")._validation_context.strict_well_validation is True
@@ -554,9 +554,9 @@ def test_import_from_imod5__correct_well_type(imod5_dataset):
     simulation = Modflow6Simulation.from_imod5_data(
         imod5_data,
         period_data,
+        datelist,
         default_simulation_allocation_options,
         default_simulation_distributing_options,
-        datelist,
     )
     # Set layer back to right value (before AssertionError might be thrown)
     imod5_data["wel-WELLS_L3"]["layer"] = original_wel_layer
@@ -583,9 +583,9 @@ def test_import_from_imod5__nonstandard_regridding(imod5_dataset, tmp_path):
     simulation = Modflow6Simulation.from_imod5_data(
         imod5_data,
         period_data,
+        times,
         default_simulation_allocation_options,
         default_simulation_distributing_options,
-        times,
         regridding_option,
     )
     simulation["imported_model"]["oc"] = OutputControl(
@@ -621,9 +621,9 @@ def test_import_from_imod5_no_storage_no_recharge(imod5_dataset, tmp_path):
     simulation = Modflow6Simulation.from_imod5_data(
         imod5_data,
         period_data,
+        times,
         default_simulation_allocation_options,
         default_simulation_distributing_options,
-        times,
     )
     simulation["imported_model"]["oc"] = OutputControl(
         save_head="last", save_budget="last"