Adding ability to use multiple Socrates versions and compile separate executables

docs/source/modules/socrates.rst

@@ -9,7 +9,8 @@ Summary
 SOCRATES (Suite Of Community RAdiative Transfer codes based on Edwards and Slingo) is the radiation scheme used by UK Met Office for Earth and planetary science [MannersEtAl2015]_, which has many significant advantages over RRTM, notably its flexibility in terms of atmospheric composition and the spectral properties of the radiation scheme (e.g. number of bands, etc).
 
 * The code used to integrate Socrates into Isca is contained within the folder ``src/atmos_params/socrates/interface``.
-* The Socrates source code itself is **NOT** packed within this Isca repository, and **NEW** users will need to download it from the `Met Office Science Repository <https://code.metoffice.gov.uk/trac/socrates>`_. Users can then either choose to put the Socrates code within the directory ``src/atmos_params/socrates/src/trunk``, or can set the bash environment variable ``GFDL_SOC`` equal to the location of the source code for Socrates. Detailed instructions on how to do this are included in the `README.md <https://github.com/ExeClim/Isca/blob/master/exp/test_cases/socrates_test/README.md>`_ for the Socrates test-case: ``exp/test_cases/socrates_test/README.md``.
+* The Socrates source code itself is **NOT** packed within this Isca repository, and **NEW** users will need to download it from the `Met Office Science Repository <https://code.metoffice.gov.uk/trac/socrates>`_. Users can then either choose to put the Socrates code within the directory ``src/atmos_params/socrates/src/1703``, or can set the bash environment variable ``GFDL_SOC`` equal to the location of the source code for Socrates. Detailed instructions on how to do this are included in the `README.md <https://github.com/ExeClim/Isca/blob/master/exp/test_cases/socrates_test/README.md>`_ for the Socrates test-case: ``exp/test_cases/socrates_test/README.md``.
+* Some users of Isca may wish to compile Isca separately with several different versions of Socrates (If you only want a single version then you can ignore this). To do this, you will need to create a folder containing all of your Socrates versions and set the ``GFDL_SOC_DIR`` environment variable to that location. Within the ``GFDL_SOC_DIR`` folder should be folders containing each of your Socrates versions. Then when you create the ``SocratesCodeBase`` object in your experiment script, you can use the option ``socrates_version=YOUR_VERSIONS_FOLDER_NAME_HERE``. For example, if my ``GFDL_SOC_DIR`` folder has folders within it called ``1703`` and ``2207``, which are my different versions, then I can choose version ``1703`` by setting ``socrates_version=1703`` when I create a ``SocratesCodeBase`` object in my experiment script. Then, when Isca compiles, it will build seperate executables for the different Socrates versions. 
 * The basis of ``socrates_interface`` was coded by Mark Hammond (Univ. of Oxford) and James Manners (Met Office) and modified by Stephen Thomson (Univ. of Exeter) [Thomson_and_Vallis2019]_. Features added include seasonality in the radiation based on Isca's ``astronomy`` package, and the ability to use a ``radiation timestep != atmospheric timestep``.
 * Socrates radiation scheme requires ``mass mixing ratios`` for all quantities (e.g. CO2, water vapor etc). This contrasts with RRTM, which wants ``volume mixing ratios``.
 
@@ -65,10 +66,10 @@ The following namelist variables set radiation time stepping and spatial samplin
 Spectral files
 ^^^^^^^^^^^^^^
 
-Socrates reads external input spectral files that tell it the number of spectral bands to use, with one file setting the shortwave options, and another file setting the longwave options. Some spectral files have lots of bands, which will make the model run slowly. The default files used in the Met Office's Unified Model-GA7, and also in Isca, can be found within the ``data/spectra`` directory of Socrates source code. For example, it can be here if you put the Socrates source code within the ``trunk`` directory:
+Socrates reads external input spectral files that tell it the number of spectral bands to use, with one file setting the shortwave options, and another file setting the longwave options. Some spectral files have lots of bands, which will make the model run slowly. The default files used in the Met Office's Unified Model-GA7, and also in Isca, can be found within the ``data/spectra`` directory of Socrates source code. For example, it can be here if you put the Socrates source code within the ``1703`` directory:
 ::
-  src/atmos_param/socrates/src/trunk/data/spectra/ga7/sp_lw_ga7 for the longwave
-  src/atmos_param/socrates/src/trunk/data/spectra/ga7/sp_sw_ga7 for the shortwave
+  src/atmos_param/socrates/src/1703/data/spectra/ga7/sp_lw_ga7 for the longwave
+  src/atmos_param/socrates/src/1703/data/spectra/ga7/sp_sw_ga7 for the shortwave
 
 or here if you have set ``GFDL_SOC`` as an environment variable:
 ::

exp/test_cases/column_test_case/column_test_socrates_ozone.py

@@ -154,8 +154,8 @@
 
     'socrates_rad_nml': {
         'stellar_constant':1370.,
-        'lw_spectral_filename':os.path.join(GFDL_BASE,'src/atmos_param/socrates/src/trunk/data/spectra/ga7/sp_lw_ga7'),
-        'sw_spectral_filename':os.path.join(GFDL_BASE,'src/atmos_param/socrates/src/trunk/data/spectra/ga7/sp_sw_ga7'),
+        'lw_spectral_filename':os.path.join(GFDL_BASE,'src/atmos_param/socrates/src/1703/data/spectra/ga7/sp_lw_ga7'),
+        'sw_spectral_filename':os.path.join(GFDL_BASE,'src/atmos_param/socrates/src/1703/data/spectra/ga7/sp_sw_ga7'),
         'dt_rad':7200,
         'store_intermediate_rad':True,
         'chunk_size': 1, # MUST BE 1 FOR COLUMN MODEL 

exp/test_cases/socrates_test/README.md

@@ -34,19 +34,19 @@ Navigate to the following Isca directory:
 
 `$GFDL_BASE/src/atmos_param/socrates/src`
 
-make a folder called `trunk` and then put the contents of your downloaded Socrates code into the `trunk` folder.
+make a folder called `1703` and then put the contents of your downloaded Socrates code into the `1703` folder.
 
 You should then have the following directory structure:
 
-`$GFDL_BASE/src/atmos_param/socrates/src/trunk/src/radiance_core/`
+`$GFDL_BASE/src/atmos_param/socrates/src/1703/src/radiance_core/`
 
 ### 3. Edit the number of angles in the phase function
 
 From this point, the Isca test case for Socrates should run without issue. However, it is strongly advised to first make the following changes to the Socrates source code.
 
 Open the file
 
-`$GFDL_BASE/src/atmos_param/socrates/src/trunk/src/modules_core/dimensions_spec_ucf.F90`
+`$GFDL_BASE/src/atmos_param/socrates/src/1703/src/modules_core/dimensions_spec_ucf.F90`
 
 and make the following changes:
 
@@ -75,17 +75,17 @@ and run the test-case `socrates_aquaplanet.py`. This will compile and run Isca w
 * Isca is set up to pass socrates a certain number of vertical profiles for each time the Socrates is called. This number is set as `chunk_size` in the `socrates_rad_nml`. A value of 16 was found to be optimal on large linux-server-type machines in Exeter, but it is worth playing with this number to find the optimal number on your machine.
 
 * Socrates reads external input files that tell it the number of spectral bands to use, with one file setting the short-wave options, and another file setting the long-wave options. Some spectral files have lots of bands, which will make the model run slowly. The default files used in the Met Office's Unified Model-GA7, and also in Isca, can be found here:
-	* `$GFDL_BASE/src/atmos_param/socrates/src/trunk/data/spectra/ga7/sp_lw_ga7` for the long-wave
-	* `$GFDL_BASE/src/atmos_param/socrates/src/trunk/data/spectra/ga7/sp_sw_ga7` for the short-wave
+	* `$GFDL_BASE/src/atmos_param/socrates/src/1703/data/spectra/ga7/sp_lw_ga7` for the long-wave
+	* `$GFDL_BASE/src/atmos_param/socrates/src/1703/data/spectra/ga7/sp_sw_ga7` for the short-wave
 * Other options are available within this folder, and a useful set of other spectral files are provided via this [webpage](https://simplex.giss.nasa.gov/gcm/ROCKE-3D/).
 
 ### 6. If you find Socrates doesn't compile
 
-* Isca's Python front-end uses a static list of file names to be compiled for the Socrates version of Isca. This list of files is here: `$GFDL_BASE/src/extra/model/socrates/path_names`. This list was compiled from a version of Socrates that we first used with Isca, which is close to v17.
+* Isca's Python front-end uses a static list of file names to be compiled for the Socrates version of Isca. This list of files is here: `$GFDL_BASE/src/extra/model/socrates/socrates_version_paths/SOCRATES_VERSION_NAME`, where `SOCRATES_VERSION_NAME` is replaced by whichever version of Socrates you're using. The original list is in file `1703`, which was compiled from a version of Socrates that we first used with Isca, which is close to version 17.03.
 
-* When you download the Socrates code, please download the latest version, as this will include the latest updates etc. By doing this, however, you might find that the compilation of Isca fails because of files that are in `path_names` but no longer exist within Socrates, or new files that have been added to Socrates that are not in the `path_names` file, but are required.
+* When you download the Socrates code, please download the latest version, as this will include the latest updates etc. By doing this, however, you might find that the compilation of Isca fails. To attempt to fix this, you can set `socrates_version=SOCRATES_VERSION_NAME` in your first call to `SocratesCodeBase`. This will then look for a file `$GFDL_BASE/src/extra/model/socrates/socrates_version_paths/SOCRATES_VERSION_NAME` containing the list of path names for your version. If the version you have chosen does not have such a file, then you'll have to create one.
 
-* In the future, we will look to generate `path_names` dynamically. However, in the meantime, please begin by updating your `path_names` file to include **every** fortran file in the directory `src/radiance_core/` directory of Socrates. All the files in this folder are likely to be essential for compiling the version of Socrates you are using.
+* In the future, we will look to generate path names for each socrates version dynamically. However, in the meantime, please begin by updating your `SOCRATES_VERSION_NAME` file to include **every** fortran file in the directory `src/radiance_core/` directory of Socrates. All the files in this folder are likely to be essential for compiling the version of Socrates you are using.
 
 * You may also find errors of the type `multiple definition of MAIN`. This happens because various pieces of code within Socrates are designed to be run offline, meaning they have MAIN sections. These MAIN sections cause conflicts with Isca's MAIN section, and so the relevant Socrates files cannot be part of Isca's compiled version. To get around this error, remove from `path_names` any Socrates files that cause this error (i.e. remove the relevant files from `path_names` that start with `atmos_param/socrates/src` not Isca's MAIN program, which is `atmos_solo/atmos_model.F90`).
 

exp/test_cases/socrates_test/socrates_aquaplanet.py

@@ -9,7 +9,7 @@
 base_dir = os.path.dirname(os.path.realpath(__file__))
 # a CodeBase can be a directory on the computer,
 # useful for iterative development
-cb = SocratesCodeBase.from_directory(GFDL_BASE)
+cb = SocratesCodeBase.from_directory(GFDL_BASE, socrates_version='1703')
 
 # or it can point to a specific git repo and commit id.
 # This method should ensure future, independent, reproducibility of results.
@@ -81,8 +81,8 @@
     },
     'socrates_rad_nml': {
         'stellar_constant':1370.,
-        'lw_spectral_filename':os.path.join(GFDL_BASE,'src/atmos_param/socrates/src/trunk/data/spectra/ga7/sp_lw_ga7'),
-        'sw_spectral_filename':os.path.join(GFDL_BASE,'src/atmos_param/socrates/src/trunk/data/spectra/ga7/sp_sw_ga7'),
+        'lw_spectral_filename':os.path.join(GFDL_BASE,'src/atmos_param/socrates/src/1703/data/spectra/ga7/sp_lw_ga7'),
+        'sw_spectral_filename':os.path.join(GFDL_BASE,'src/atmos_param/socrates/src/1703/data/spectra/ga7/sp_sw_ga7'),
         'do_read_ozone': True,
         'ozone_file_name':'ozone_1990',
         'ozone_field_name':'ozone_1990',
@@ -199,6 +199,6 @@
         #This will be the name of the folder that the data will appear in.
 
         exp.run(1, use_restart=False, num_cores=NCORES, overwrite_data=False)
-
+        overwrite=False
         for i in range(2,121):
             exp.run(i, num_cores=NCORES, overwrite_data=overwrite)

exp/test_cases/socrates_test/socrates_aquaplanet_amip_with_original_era_topo_testing_only.py

@@ -89,8 +89,8 @@
     },
     'socrates_rad_nml': {
         'stellar_constant':1370.,
-        'lw_spectral_filename':os.path.join(GFDL_BASE,'src/atmos_param/socrates/src/trunk/data/spectra/ga7/sp_lw_ga7'),
-        'sw_spectral_filename':os.path.join(GFDL_BASE,'src/atmos_param/socrates/src/trunk/data/spectra/ga7/sp_sw_ga7'),
+        'lw_spectral_filename':os.path.join(GFDL_BASE,'src/atmos_param/socrates/src/1703/data/spectra/ga7/sp_lw_ga7'),
+        'sw_spectral_filename':os.path.join(GFDL_BASE,'src/atmos_param/socrates/src/1703/data/spectra/ga7/sp_sw_ga7'),
         'do_read_ozone': True,
         'ozone_file_name':'ozone_1990',
         'ozone_field_name':'ozone_1990',

exp/test_cases/socrates_test/socrates_aquaplanet_amip_with_topo.py

@@ -83,8 +83,8 @@
     },
     'socrates_rad_nml': {
         'stellar_constant':1370.,
-        'lw_spectral_filename':os.path.join(GFDL_BASE,'src/atmos_param/socrates/src/trunk/data/spectra/ga7/sp_lw_ga7'),
-        'sw_spectral_filename':os.path.join(GFDL_BASE,'src/atmos_param/socrates/src/trunk/data/spectra/ga7/sp_sw_ga7'),
+        'lw_spectral_filename':os.path.join(GFDL_BASE,'src/atmos_param/socrates/src/1703/data/spectra/ga7/sp_lw_ga7'),
+        'sw_spectral_filename':os.path.join(GFDL_BASE,'src/atmos_param/socrates/src/1703/data/spectra/ga7/sp_sw_ga7'),
         'do_read_ozone': True,
         'ozone_file_name':'ozone_1990',
         'ozone_field_name':'ozone_1990',

exp/test_cases/socrates_test/socrates_aquaplanet_amip_with_topo_clouds.py

@@ -101,8 +101,8 @@
     },
     'socrates_rad_nml': {
         'stellar_constant':1370.,
-        'lw_spectral_filename':os.path.join(GFDL_BASE,'src/atmos_param/socrates/src/trunk/data/spectra/ga7/sp_lw_ga7'),
-        'sw_spectral_filename':os.path.join(GFDL_BASE,'src/atmos_param/socrates/src/trunk/data/spectra/ga7/sp_sw_ga7'),
+        'lw_spectral_filename':os.path.join(GFDL_BASE,'src/atmos_param/socrates/src/1703/data/spectra/ga7/sp_lw_ga7'),
+        'sw_spectral_filename':os.path.join(GFDL_BASE,'src/atmos_param/socrates/src/1703/data/spectra/ga7/sp_sw_ga7'),
         'do_read_ozone': True,
         'ozone_file_name':'ozone_1990',
         'ozone_field_name':'ozone_1990',

exp/test_cases/socrates_test/socrates_aquaplanet_cloud.py

@@ -100,8 +100,8 @@
     },
     'socrates_rad_nml': {
         'stellar_constant':1370.,
-        'lw_spectral_filename':os.path.join(GFDL_BASE,'src/atmos_param/socrates/src/trunk/data/spectra/ga7/sp_lw_ga7'),
-        'sw_spectral_filename':os.path.join(GFDL_BASE,'src/atmos_param/socrates/src/trunk/data/spectra/ga7/sp_sw_ga7'),
+        'lw_spectral_filename':os.path.join(GFDL_BASE,'src/atmos_param/socrates/src/1703/data/spectra/ga7/sp_lw_ga7'),
+        'sw_spectral_filename':os.path.join(GFDL_BASE,'src/atmos_param/socrates/src/1703/data/spectra/ga7/sp_sw_ga7'),
         'do_read_ozone': True,
         'ozone_file_name':'ozone_1990',
         'ozone_field_name':'ozone_1990',