From b9d94540a0dbe1eb8ec23c38539a8784bc443d74 Mon Sep 17 00:00:00 2001
From: Jo Basevi <johanna.basevi@edu.anu.au>
Date: Thu, 3 Aug 2023 11:37:18 +1000
Subject: [PATCH] update documentation to include module use option

---
 docs/source/config.rst | 16 ++++++++++------
 test/test_payu.py      | 15 +++++++++++++--
 2 files changed, 23 insertions(+), 8 deletions(-)

diff --git a/docs/source/config.rst b/docs/source/config.rst
index bc9a9e9d..058acc85 100644
--- a/docs/source/config.rst
+++ b/docs/source/config.rst
@@ -427,17 +427,21 @@ Miscellaneous
    is generally only used for testing purposes, such as bit reproducibility.
 
 ``modules``
-   Specify a list of environment modules to load at the start of the PBS job,
-   for example::
+   Defines options to specify lists of environment modules and/or directories 
+   to load/use at the start of the PBS job, for example::
 
       modules:
-         - netcdf-c-4.9.0
-         - parallel-netcdf-1.12.3
-         - xerces-c-3.2.3
+         use:
+            - /path/to/module/dir
+         load:
+            - netcdf-c-4.9.0
+            - parallel-netcdf-1.12.3
+            - xerces-c-3.2.3
 
    This is seldom needed, because payu is good at automatically determining
    the environment modules required by model executables. If the modules
-   require `module use` inorder to be found, do this prior to `payu run`,
+   require `module use` inorder to be found, this command can also be run
+   prior to `payu run` instead specifying the `use` option,
    e.g.::
 
       module use /path/to/module/directory
diff --git a/test/test_payu.py b/test/test_payu.py
index 7c188dbc..01800194 100644
--- a/test/test_payu.py
+++ b/test/test_payu.py
@@ -148,8 +148,19 @@ def test_read_config():
 
     assert(config.pop('collate') == {})
     assert(config.pop('control_path') == os.getcwd())
+    assert(config.pop('modules') == {})
     assert(config == {})
 
+    # Test transform legacy modules option 
+    with open(config_tmp, 'w') as f:
+        f.write('modules:\n   - test_user_defined_module')
+    
+    config = payu.fsops.read_config(config_tmp)
+    modules_config = config.get('modules', {})
+    
+    assert(modules_config.get('load', []) == ['test_user_defined_module'])
+    assert(modules_config.get('use', []) == [])
+
     os.remove(config_tmp)
 
 
@@ -222,8 +233,8 @@ def test_parse_ldd_output():
     with open(ldd_output_path, 'r') as f:
         ldd_output = f.read()
     required_libs = payu.fsops.parse_ldd_output(ldd_output)
-    assert(len(required_libs), 4) 
-    assert(required_libs['libmpi.so.40'], '/apps/openmpi/4.0.2/lib/libmpi.so.40')
+    assert(len(required_libs) == 4) 
+    assert(required_libs['libmpi.so.40'] == '/apps/openmpi/4.0.2/lib/libmpi.so.40')
 
 
 def test_lib_update_lib_if_required():