Repository: payu-org/payu
Pull request #573: remove matm
Author: login: anton-seaice
Created: 2025-04-03T00:58:19Z | Merged: 2025-04-07T00:22:51Z

Closes #486 and #571 

Deprecate matm

Linked issue #486: Drop support for matm model driver
The [`matm` model driver ](https://github.com/payu-org/payu/blob/master/payu/models/matm.py) is no longer being used, supported or updated.

https://github.com/COSIMA/matm

It was superseded by `yatm` and is not being actively used. Because of this we have no useful way of knowing if we're breaking it.

I propose we drop support for it, and delete it. 

Older versions of `payu` can always be used if, in extremis, in the highly unlikely event someone wants to use it.

Diff:
diff --git a/docs/source/config.rst b/docs/source/config.rst
index 10b71ec9..0d415bce 100644
--- a/docs/source/config.rst
+++ b/docs/source/config.rst
@@ -179,25 +179,26 @@ configuration.
 
       model: access
       submodels:
-         atmosphere:
-            model: matm
-            exe: matm_MPI1_nt62.exe
-            input: iaf_matm_simon
-            ncpus: 1
-         ocean:
+         -  name: atmosphere
+            model: um
+            ncpus: 192
+            exe: um_hg3.exe
+            input: /g/data/vk83/configurations/inputs/atmosphere
+         - name: ocean
             model: mom
-            exe: fms_MOM_ACCESS_kate.x
-            input: iaf_mom
-            ncpus: 120
-         ice:
-            model: cice
-            exe: cice_MPI1_6p.exe
-            input: iaf_cice
-            ncpus: 6
-         coupler:
+            ncpus: 180
+            exe: fms_ACCESS-ESM.x
+            input: /g/data/vk83/configurations/inputs/ocean
+         - name: ice
+            model: cice5
+            ncpus: 12
+            exe: cice_access-esm1.6_360x300_12x1_12p.exe
+            input: /g/data/vk83/configurations/inputs/ice
+         - name: coupler
             model: oasis
-            input: iaf_oasis
             ncpus: 0
+            input: /g/data/vk83/configurations/inputs/oasis
+
 
 ``restart_freq`` (*Default:* ``5``)
    Specifies the rate of saved restart files. This rate can be either an 
diff --git a/payu/models/__init__.py b/payu/models/__init__.py
index 8281cfa9..038c6145 100644
--- a/payu/models/__init__.py
+++ b/payu/models/__init__.py
@@ -6,7 +6,6 @@
 from payu.models.cice import Cice
 from payu.models.cice5 import Cice5
 from payu.models.gold import Gold
-from payu.models.matm import Matm
 from payu.models.mitgcm import Mitgcm
 from payu.models.mom import Mom
 from payu.models.mom6 import Mom6
@@ -29,7 +28,6 @@
     'cice':       Cice,
     'cice5':      Cice5,
     'gold':       Gold,
-    'matm':       Matm,
     'yatm':       Yatm,
     'mitgcm':     Mitgcm,
     'mom':        Mom,
diff --git a/payu/models/access.py b/payu/models/access.py
index 0fb8b29d..a26e16b5 100644
--- a/payu/models/access.py
+++ b/payu/models/access.py
@@ -67,20 +67,6 @@ def __init__(self, expt, name, config):
                 # Simulation length in seconds for new run
                 model.runtime_key = "runtime"
 
-            if model.model_type == 'matm':
-                # Structure of model coupling namelist
-                model.cpl_fname = 'input_atm.nml'
-                model.cpl_group = 'coupling'
-                model.start_date_nml_name = "restart_date.nml"
-                # Experiment initialisation date
-                model.init_date_key = "init_date"
-                # Start date for new run
-                model.inidate_key = "inidate"
-                # Total time in seconds since initialisation date
-                model.runtime0_key = 'truntime0'
-                # Simulation length in seconds for new run
-                model.runtime_key = "runtime"
-
 
     def setup(self):
         if not self.top_level_model:
@@ -113,10 +99,9 @@ def setup(self):
                         if os.path.isfile(f_src):
                             make_symlink(f_src, f_dst)
 
-            if model.model_type in ('cice', 'matm'):
+            if model.model_type == 'cice':
 
                 # Update the supplemental OASIS namelists
-
                 # cpl_nml is the coupling namelist copied from the control to
                 # work directory.
                 cpl_fpath = os.path.join(model.work_path, model.cpl_fname)
@@ -217,8 +202,7 @@ def setup(self):
                 f90nml.write(cpl_nml, nml_work_path + '~')
                 shutil.move(nml_work_path + '~', nml_work_path)
 
-            if model.model_type == 'cice':
-                if model.prior_restart_path and not self.expt.repeat_run:
+                if  model.prior_restart_path and not self.expt.repeat_run:
                     # Set up and check the cice restart files.
                     model.overwrite_restart_ptr(run_start_date,
                                                 previous_runtime,
@@ -271,7 +255,6 @@ def archive(self):
                 if os.path.exists(work_ice_nml_path):
                     shutil.copy2(work_ice_nml_path, restart_ice_nml_path)
 
-            if model.model_type in ('cice', 'matm'):
                 # Write the simulation end date to the restart date
                 # namelist.
 
diff --git a/payu/models/access_esm1p6.py b/payu/models/access_esm1p6.py
index 9c4fd2bd..ee998f7c 100644
--- a/payu/models/access_esm1p6.py
+++ b/payu/models/access_esm1p6.py
@@ -67,20 +67,6 @@ def __init__(self, expt, name, config):
                 # Simulation length in seconds for new run
                 model.runtime_key = "runtime"
 
-            if model.model_type == 'matm':
-                # Structure of model coupling namelist
-                model.cpl_fname = 'input_atm.nml'
-                model.cpl_group = 'coupling'
-                model.start_date_nml_name = "restart_date.nml"
-                # Experiment initialisation date
-                model.init_date_key = "init_date"
-                # Start date for new run
-                model.inidate_key = "inidate"
-                # Total time in seconds since initialisation date
-                model.runtime0_key = 'truntime0'
-                # Simulation length in seconds for new run
-                model.runtime_key = "runtime"
-
             if model.model_type == 'um':
                 # Additional Cable 3 namelists
 
@@ -122,10 +108,9 @@ def setup(self):
                         if os.path.isfile(f_src):
                             make_symlink(f_src, f_dst)
 
-            if model.model_type in ('cice', 'matm'):
+            if model.model_type == 'cice':
 
                 # Update the supplemental OASIS namelists
-
                 # cpl_nml is the coupling namelist copied from the control to
                 # work directory.
                 cpl_fpath = os.path.join(model.work_path, model.cpl_fname)
@@ -226,8 +211,7 @@ def setup(self):
                 f90nml.write(cpl_nml, nml_work_path + '~')
                 shutil.move(nml_work_path + '~', nml_work_path)
 
-            if model.model_type == 'cice':
-                if model.prior_restart_path and not self.expt.repeat_run:
+                if  model.prior_restart_path and not self.expt.repeat_run:
                     # Set up and check the cice restart files.
                     model.overwrite_restart_ptr(run_start_date,
                                                 previous_runtime,
@@ -280,7 +264,6 @@ def archive(self):
                 if os.path.exists(work_ice_nml_path):
                     shutil.copy2(work_ice_nml_path, restart_ice_nml_path)
 
-            if model.model_type in ('cice', 'matm'):
                 # Write the simulation end date to the restart date
                 # namelist.
 
diff --git a/payu/models/matm.py b/payu/models/matm.py
deleted file mode 100644
index 78bf37d3..00000000
--- a/payu/models/matm.py
+++ /dev/null
@@ -1,46 +0,0 @@
-# coding: utf-8
-"""payu.models.matm
-   ================
-
-   Driver interface to the MATM model.
-
-   :copyright: Copyright 2011 Marshall Ward, see AUTHORS for details
-   :license: Apache License, Version 2.0, see LICENSE for details
-"""
-
-# Standard Library
-import os
-
-# Local
-from payu.models.model import Model
-from payu.fsops import mkdir_p
-
-
-class Matm(Model):
-
-    def __init__(self, expt, name, config):
-        super(Matm, self).__init__(expt, name, config)
-
-        self.model_type = 'matm'
-        self.default_exec = 'matm'
-
-        # Default repo details
-        self.repo_url = 'https://github.com/CWSL/matm.git'
-        self.repo_tag = 'master'
-
-        self.config_files = ['input_atm.nml',
-                             'data_4_matm.table']
-
-    def set_model_pathnames(self):
-        super(Matm, self).set_model_pathnames()
-
-        self.build_exec_path = os.path.join(self.codebase_path, 'build_nt62')
-        self.work_input_path = os.path.join(self.work_path, 'INPUT')
-
-    def archive(self):
-
-        # Create an empty restart directory
-        mkdir_p(self.restart_path)
-
-    def collate(self):
-        pass
diff --git a/payu/models/oasis.py b/payu/models/oasis.py
index 262552b6..b827b709 100644
--- a/payu/models/oasis.py
+++ b/payu/models/oasis.py
@@ -88,15 +88,6 @@ def set_timestep(self, t_step):
 
                 input_ice.write(input_ice_path, force=True)
 
-            elif model.model_type == 'matm':
-
-                input_atm_path = os.path.join(model.work_path, 'input_atm.nml')
-                input_atm = f90nml.read(input_atm_path)
-
-                input_atm['coupling']['dt_atm'] = t_step
-
-                input_atm.write(input_atm_path, force=True)
-
             elif model.model_type == 'mom':
 
                 input_nml_path = os.path.join(model.work_path, 'input.nml')


Reviews:
user: login: aidanheerdegen
body: LGTM, but it's [still referenced in the docs](https://github.com/payu-org/payu/blob/39e4b9bdabceca3836bc25f0fcfe411d0c0b9f13/docs/source/config.rst?plain=1#L183-L186). 

We should update those to a newer example.

Any suggestions @jo-basevi?
state: CHANGES_REQUESTED
author_association: COLLABORATOR
submitted_at: 2025-04-03T01:26:22Z
user: login: blimlim
body: Thanks @anton-seaice for picking this up. This looks good to me, I just had a couple small suggestions outside of the changed lines.

In `access.py`, I think

```
if model.model_type in ('cice'):
```
in [line 102](https://github.com/payu-org/payu/blob/42a7c0e25be03de0246b7531f978e2e91e3c7960/payu/models/access.py#L102) and 
```python
if model.model_type == 'cice':
```
in [line 206](https://github.com/payu-org/payu/blob/42a7c0e25be03de0246b7531f978e2e91e3c7960/payu/models/access.py#L206) can be merged together.

I think the if statement
```
if model.model_type == 'cice':
```
in [line 192](https://github.com/payu-org/payu/blob/42a7c0e25be03de0246b7531f978e2e91e3c7960/payu/models/access.py#L192) can also be removed.

Likewise the two if statements in [line 237 ](https://github.com/payu-org/payu/blob/42a7c0e25be03de0246b7531f978e2e91e3c7960/payu/models/access.py#L237) and [260](https://github.com/payu-org/payu/blob/42a7c0e25be03de0246b7531f978e2e91e3c7960/payu/models/access.py#L260) should be able to be combined


Just remembered the same changes can also be made in the `access-esm1p6.py` driver too
state: CHANGES_REQUESTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-03T01:36:02Z
user: login: blimlim
body: Thanks @anton-seaice, just to clarify the suggestion around [this block](https://github.com/payu-org/payu/blob/f7ebb9b66a7a93029ddda74fe14745df101eed90/payu/models/access.py#L191-L197) in both access.py and access-esm1p6.py, I think the following change can be made, as the code already falls under the `if model.model_type == 'cice'` in line 102:
```diff
-                if model.model_type == 'cice':
-                    if self.expt.counter and not self.expt.repeat_run:
-                        cpl_group['jobnum'] = (
-                            1 + self.expt.counter
-                        )
-                    else:
-                        cpl_group['jobnum'] = 1
+                if self.expt.counter and not self.expt.repeat_run:
+                    cpl_group['jobnum'] = (
+                        1 + self.expt.counter
+                    )
+                else:
+                    cpl_group['jobnum'] = 1
```

state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-03T03:29:00Z
user: login: anton-seaice
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-03T05:32:49Z
user: login: blimlim
body: Thanks @anton-seaice, this is looking good to me! I think the changes do the docs look good
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-04-03T22:55:41Z
user: login: jo-basevi
body: Looks good to me
state: APPROVED
author_association: COLLABORATOR
submitted_at: 2025-04-03T23:02:23Z
user: login: aidanheerdegen
body: LGTM2
state: APPROVED
author_association: COLLABORATOR
submitted_at: 2025-04-06T23:48:15Z

Review comments:
diff_hunk: @@ -217,8 +202,9 @@ def setup(self):
                 f90nml.write(cpl_nml, nml_work_path + '~')
                 shutil.move(nml_work_path + '~', nml_work_path)
 
-            if model.model_type == 'cice':
-                if model.prior_restart_path and not self.expt.repeat_run:
+            if ( model.model_type == 'cice'
+                and model.prior_restart_path
+                and not self.expt.repeat_run ):
path: payu/models/access.py
user: login: blimlim
body: ```suggestion
                if  model.prior_restart_path and not self.expt.repeat_run:
```
created_at: 2025-04-03T03:12:55Z
author_association: CONTRIBUTOR
diff_hunk: @@ -217,8 +202,9 @@ def setup(self):
                 f90nml.write(cpl_nml, nml_work_path + '~')
                 shutil.move(nml_work_path + '~', nml_work_path)
 
-            if model.model_type == 'cice':
-                if model.prior_restart_path and not self.expt.repeat_run:
+            if ( model.model_type == 'cice'
+                and model.prior_restart_path
+                and not self.expt.repeat_run ):
path: payu/models/access.py
user: login: blimlim
body: Originally thinking something like this, but now that I think about it more, I think it's ok either way!
created_at: 2025-04-03T03:20:47Z
author_association: CONTRIBUTOR
diff_hunk: @@ -217,8 +202,9 @@ def setup(self):
                 f90nml.write(cpl_nml, nml_work_path + '~')
                 shutil.move(nml_work_path + '~', nml_work_path)
 
-            if model.model_type == 'cice':
-                if model.prior_restart_path and not self.expt.repeat_run:
+            if ( model.model_type == 'cice'
+                and model.prior_restart_path
+                and not self.expt.repeat_run ):
path: payu/models/access.py
user: login: anton-seaice
body: Ah yes - much better !
created_at: 2025-04-03T05:32:49Z
author_association: CONTRIBUTOR

PR comments:
user: login: coveralls
created_at: 2025-04-03T01:01:41Z
body: 
[![Coverage Status](https://coveralls.io/builds/73055688/badge)](https://coveralls.io/builds/73055688)

coverage: 58.693% (+0.4%) from 58.267%
when pulling **324a24dd143e6c0c3d5ae593c3b6e37a17b76a3d on 486-drop-matm**
into **39e4b9bdabceca3836bc25f0fcfe411d0c0b9f13 on master**.

author_association: NONE
user: login: jo-basevi
created_at: 2025-04-03T01:51:13Z
body: > Any suggestions @jo-basevi?

Looks good to me - I don't have any additional suggestions
author_association: COLLABORATOR
user: login: blimlim
created_at: 2025-04-03T02:34:23Z
body: > We should update those to a newer example.

As the example's using the ESM1.5 driver, I'm wondering if it would be easiest to swap it over to the UM?

```
 - name: atmosphere
      model: um
      ncpus: 240
      exe: um_hg3.exe
```
author_association: CONTRIBUTOR
user: login: anton-seaice
created_at: 2025-04-03T02:36:18Z
body: > LGTM, but it's [still referenced in the docs](https://github.com/payu-org/payu/blob/39e4b9bdabceca3836bc25f0fcfe411d0c0b9f13/docs/source/config.rst?plain=1#L183-L186).
> 
> We should update those to a newer example.
> 
> Any suggestions @jo-basevi?

The whole example is quite dated:

https://github.com/payu-org/payu/blob/39e4b9bdabceca3836bc25f0fcfe411d0c0b9f13/docs/source/config.rst?plain=1#L180-L200

Should I set based on esm1.5 ?
author_association: CONTRIBUTOR
user: login: anton-seaice
created_at: 2025-04-03T02:56:35Z
body: Thanks @blimlim - I think I made the changed suggested
author_association: CONTRIBUTOR
user: login: blimlim
created_at: 2025-04-03T05:48:12Z
body: > Should I set based on esm1.5 ?

That sounds good. I think either an ESM1.5 or OM2 config should be ok there
author_association: CONTRIBUTOR
user: login: anton-seaice
created_at: 2025-04-03T05:58:06Z
body: I pushed a newer config to docs ... i wasn't really sure what to do with the `input` lines ?
author_association: CONTRIBUTOR
user: login: jo-basevi
created_at: 2025-04-03T22:45:32Z
body: I'm not really sure what to do for the inputs either.. I feel most of the value of the example is just seeing what the `submodel` section of the configuration could look like, so I think it achieves that.
author_association: COLLABORATOR