Model2roms

<h1>model2roms</h1>

Model2roms is a Python toolbox for creating the necessary climatology, boundary, and initial forcing files required to run the ROMS (<a href="http://myroms.org/" target="_blank">Regional Ocean Modeling System</a>) model. The latest version of model2roms can convert several popular model hindcasts and projections including the NORESM (Norways Earth System Model), SODA global re-analysis, HYCOM, World Ocean Atlas (WOA), and GLORYS (Mercator Ocean) to a use as forcing files for a given ROMS grid structure.

<h3>Introduction</h3>

Model2roms is a Python toolbox for creating the necessary climatology, boundary, and initial forcing files required to run the ROMS (<a href="http://myroms.org/" target="_blank">Regional Ocean Modeling System</a>) model. The latest version of model2roms can convert several popular model hindcasts and projections including the NORESM (Norways Earth System Model) , SODA global re-analysis, and GLORYS (Mercator Ocean) to be used as forcing files for a given ROMS grid structure.

Model2roms uses the Earth System Modeling Framework (ESMF) as the default interpolation method. This allows the input data to be on any kind of grid structure (e.g. irregular) provided that geographical information such as the longitude and latitude of grid cells is available. The implementation uses the Python interface to ESMF which can be found here: <a href="https://www.earthsystemcog.org/projects/esmpy/" target="_blank">www.earthsystemcog.org/projects/esmpy/</a> . Using ESMF significantly increases the speed of the interpolation. As an example, interpolating one variable (e.g. temperature distribution) from a global irregular grid to a local non-rectangular grid of size 1250x789, at 70 different depth levels, takes 3 seconds on a Mac Laptop Pro. For most people, installing using Anaconda would be the best option to install the required packages to run <b>model2roms</b>. The minimum installation of required packages:

conda create -n model2roms`
conda config --add channels conda-forge
conda activate model2roms
conda install esmf xarray netcdf4 progressbar2 

Model2roms has been developed over several years, usually improved every time a new model configuration of ROMS has been required for my work. But the user groups of model2roms has also increased over these years and several people have pointed out bugs and ways to improve this package. The toolbox consists of collection of Python and Fortran modules that can be used to create climatology (CLIM), initial (INIT), and boundary (BRY) files necessary to run the <a href="www.myroms.org">ROMS</a> model.

Currently, model2roms takes rectangular gridded forcing files at Z-levels as input. These data are first interpolated to the ROMS grid at Z-levels. Next the Z-levels are interpolated vertically to the sigma layers (<a href="https://www.myroms.org/wiki/index.php/Vertical_S-coordinate">S-coordinates</a>). For U and V velocities, the interpolation is done at RHO points, and then interpolated to U and V points ((eta_u,xi_u), and (eta_v, xi_v)). All interpolated values are written to netCDF4 files using compression (zlib) to minimize file size. The result of running model2roms is one file for each CLIM, INIT, and BRY files. UBAR and VBAR (barotropic flow) are calculated from U and V velocities. Time is stored as julian day from 01/01/1948 (see model2roms.py)

<h4>Compile the Fortran modules</h4> To get started, compile the Fortran functions into modules callable by Python. First edit the file compile.py and select your Fortran compiler (currently gfortran and Intel Fortran compiler supported):

python
compile.py

Make sure that this successfully creates modules (.so files) that Python can import. Some users have reported that they have to run each compile command individually to compile (this may depend on your machine and OS). The use of Fortran modules as part of the calculations significantly speeds up the calculations.

<h4>Running model2roms</h4> Before you run model2roms you have to edit the configuration file `configM2R.py` to correctly point to the path of your gridfile, the type of forcing you want and the variables to use.

Once everything is correctly setup you can run model2roms with the command:

python
runM2R.py

<h4>Options for interpolation</h4> Model2roms makes use of the ESMF python package to handle all the horizontal interpolations. This has significantly sped up the time used on interpolation and also made interpolation more robust across the poles. In addition, ESMF can handle any input type grid and therefore making it very easy to convert any type of model into forcing files for ROMS. However, often the target grid has higher resolution than the source grid which opens up areas (e.g. along the coastlines) where you have no data. Model2roms contains an option `use_filter` that will extrapolate data to fill these areas with no data using a Laplace operator. This is quite useful, but also time-consuming and should be turned off unless you need it:

Without filter | With filter :-------------------------:|:-------------------------: <img src="http://www.trondkristiansen.com/wp-content/gallery/romstools/temperature_depth_ESMF_0_withoutfilter_time_75190.0.png" width=100%> | <img src="http://www.trondkristiansen.com/wp-content/gallery/romstools/temperature_depth_ESMF_0_withfilter_time_75190.0.png" width=100%>

<h3>Optional settings</h3> Prior to run model2roms you have to specify a number of settings so that the program can identify where input and grid files can be found. In addition, you can specify what sort of run you are doing by turning options on and off. All of the user settings are done in `configM2R.py`, a few definitions for variable names are found in `model2roms.py`, and finally a few settings for the grid specifications are found in `grd.py`. Eventually, all of the settings will be moved to one file. Still, the main settings are the following:

    def __init__(self):
    logging.info('\n--------------------------\n')
    logging.info('Started ' + time.ctime(time.time()))
    os.environ['WRAP_STDERR'] = 'true'

    # EDIT ===================================================================
    # Set show_progress to "False" if you do not want to see the progress
    # indicator for horizontal interpolation.
    self.show_progress = True

    # Set compileAll to True if you want automatic re-compilation of all the
    # fortran files necessary to run model2roms. Options are "gfortran" or "ifort". Edit
    # compile.py to add other Fortran compilers.
    self.compile_all = False

    # Extract time-series of data for given longitude/latitude
    self.extract_stations = False

    # Define a set of longitude/latitude positions with names to extract into
    # station files (using extractStations)
    if self.extract_stations:
        #  stationNames = ['NorthSea', 'Iceland', 'EastandWestGreenland', 'Lofoten', 'Georges Bank']
        #  lonlist = [2.4301, -22.6001, -47.0801, 13.3801, -67.2001]
        #  latlist = [54.5601, 63.7010, 60.4201, 67.5001, 41.6423]

        self.station_names = ["Ytre Utsira", "Indre Utsira", "Lista"]
        self.latlist = [59.316667, 59.316667, 58.016667]
        self.lonlist = [4.800000, 4.983333, 6.533333]
        self.numberofpoints = 4  # Number of points around lat/lon to extract and average as output

    # Create the bry, init, and clim files for a given grid and input data
    self.create_ocean_forcing = True

    # Create atmospheric forcing for the given grid
    self.create_atmos_forcing = False  # currently in beta stages

    # Create a smaller resolution grid based on your original. Decimates every second for
    # each time run
    self.decimate_gridfile = False

    # Write ice values to file (for Arctic regions)
    self.write_ice = False

    # Write biogeochemistry values to file
    self.write_bcg = False

    # ROMS sometimes requires input of ice and ssh, but if you dont have these write files containing zeros to file
    self.set_2d_vars_to_zero = False

    # Apply filter to smooth the 2D fields after interpolation (time consuming but enhances results)
    self.use_filter = True

    # Format to write the ouput to: 'NETCDF4', 'NETCDF4_CLASSIC', 'NETCDF3_64BIT', or 'NETCDF3_CLASSIC'
    # Using NETCDF4 automatically turns on compression of files (ZLIB)
    self.output_format = 'NETCDF4'
    self.use_zlib = True

    # Frequency of the input data: usually monthly
    self.time_frequency_inputdata = "month"  # Possible options: "month", "hour", "5days"

    # Path to where results files should be stored
    self.outdir = "../oceanography/NAUTILOS/"
    if not os.path.exists(self.outdir):
        os.makedirs(self.outdir, exist_ok=True)

    # IN GRIDTYPES ------------------------------------------------------------------------------
    # Define what grid type you w