.. image:: _static/logo.png
    :align: center
    :scale: 15%
    :alt: bmi_roms
    :target: https://bmi-roms.readthedocs.io/en/latest/

`bmi_roms <https://github.com/gantian127/bmi_roms/>`_ package is an implementation of the Basic Model Interface
`(BMI) <https://bmi-spec.readthedocs.io/en/latest/>`_ for the `ROMS model <https://www.myroms.org/>`_ datasets.
This package wraps the dataset with BMI for data control and query.
This package is not implemented for people to use but is the key element to convert the ROMS dataset into
a data component `(pymt_roms) <https://pymt-roms.readthedocs.io/>`_ for
the `PyMT <https://pymt.readthedocs.io/en/latest/?badge=latest>`_ modeling framework developed
by Community Surface Dynamics Modeling System `(CSDMS) <https://csdms.colorado.edu/wiki/Main_Page>`_.

The current implementation supports 2D, 3D and 4D ROMS output datasets defined with geospatial and/or time dimensions
(e.g., dataset defined with dimensions as [time, s_rho, eta_rho, xi_rho])

If you have any suggestion to improve the current function, please create a github issue
`here <https://github.com/gantian127/bmi_roms/issues>`_.


Getting Started
===============

Installation
++++++++++++

**Stable Release**

The bmi_roms package and its dependencies can be installed with pip

.. code-block:: console

    $ pip install bmi_roms

or conda

.. code-block:: console

    $ conda install -c conda-forge bmi_roms

**From Source**

After downloading the source code, run the following command from top-level folder
(the one that contains setup.py) to install bmi_roms.

.. code-block:: console

    $ pip install -e .


Code Example
++++++++++++++++++++++++++++++++++++

Learn more details of the example from the
`tutorial notebook <https://github.com/gantian127/bmi_roms/blob/master/notebooks/bmi_roms.ipynb>`_ provided in this package.
You can also launch binder to test and run the code below. |binder|

.. code-block:: python

   from bmi_roms import BmiRoms
   import numpy as np
   import matplotlib.pyplot as plt

   data_comp = BmiRoms()
   data_comp.initialize('config_file.yaml')

   # get variable info
   for var_name in  data_comp.get_output_var_names():
       var_unit = data_comp.get_var_units(var_name)
       var_location = data_comp.get_var_location(var_name)
       var_type = data_comp.get_var_type(var_name)
       var_grid = data_comp.get_var_grid(var_name)
       var_itemsize = data_comp.get_var_itemsize(var_name)
       var_nbytes = data_comp.get_var_nbytes(var_name)
       print('variable_name: {} \nvar_unit: {} \nvar_location: {} \nvar_type: {} \nvar_grid: {} \nvar_itemsize: {}'
               '\nvar_nbytes: {} \n'. format(var_name, var_unit, var_location, var_type, var_grid, var_itemsize, var_nbytes))

   # get time info
   start_time = data_comp.get_start_time()
   end_time = data_comp.get_end_time()
   time_step = data_comp.get_time_step()
   time_unit = data_comp.get_time_units()
   time_steps = int((end_time - start_time)/time_step) + 1
   print('start_time:{} \nend_time:{} \ntime_step:{} \ntime_unit:{} \ntime_steps:{} \n'.format(
       start_time, end_time, time_step, time_unit, time_steps))

   # get variable grid info
   for var_name in data_comp.get_output_var_names():
       var_grid = data_comp.get_var_grid(var_name)

       grid_rank = data_comp.get_grid_rank(var_grid)
       grid_size = data_comp.get_grid_size(var_grid)

       grid_shape = np.empty(grid_rank, int)
       data_comp.get_grid_shape(var_grid, grid_shape)

       grid_spacing = np.empty(grid_rank)
       data_comp.get_grid_spacing(var_grid, grid_spacing)

       grid_origin = np.empty(grid_rank)
       data_comp.get_grid_origin(var_grid, grid_origin)

       print('var_name: {} \ngrid_id: {}\ngrid_rank: {} \ngrid_size: {} \ngrid_shape: {} \ngrid_spacing: {} \ngrid_origin: {} \n'.format(
           var_name, var_grid, grid_rank, grid_size, grid_shape, grid_spacing, grid_origin))

   # get variable data
   data = np.empty(1026080, 'float64')
   data_comp.get_value('time-averaged salinity', data)
   data_3D = data.reshape([40, 106, 242])

   # get lon and lat data
   lat = np.empty(25652, 'float64')
   data_comp.get_value('latitude of RHO-points', lat)

   lon = np.empty(25652, 'float64')
   data_comp.get_value('longitude of RHO-points', lon)

   # make a contour plot
   fig = plt.figure(figsize=(10,7))
   im = plt.contourf(lon.reshape([106, 242]), lat.reshape([106, 242]), data_3D[0], levels=36)
   fig.colorbar(im)
   plt.axis('equal')
   plt.xlabel('Longitude [degree_east]')
   plt.ylabel('Latitude [degree_north]')
   plt.title('ROMS model data of time-averaged salinity')

|plot|


Parameters
++++++++++++++++++++++++++++++++++++

A `configuration file <https://github.com/gantian127/bmi_roms/blob/master/notebooks/config_file.yaml>`_ is required
to initialize an instance of the ROMS data component. This file includes the following parameters:

* **filename**: Path or URL (e.g., OPeNDAP data url) of the ROMS model data to open.
* **download**: Bool value as True or False to indicate whether to download and save the data as a netCDF file with the
  provided URL. The dataset will be saved in the working directory with a file name including the time information
  (e.g., romsdata_12032023T162045.nc)


.. links:

.. |binder| image:: https://mybinder.org/badge_logo.svg
 :target: https://mybinder.org/v2/gh/gantian127/bmi_roms/master?filepath=notebooks%2Fbmi_roms.ipynb

.. |plot| image:: _static/contour_plot.png