.. _BMI-label:

BMI-enbled Web Service Model (BMI)
************************************************

BMI-enabled models are self-describing by uncovering models' metadata through BMI (`Basic Model Interface <https://csdms.colorado.edu/wiki/BMI_Description>`_) functions, developed in CSDMS (`Community Surface Dynamics Modeling System <https://csdms.colorado.edu/wiki/Main_Page>`_). We expose the BMI-enabled models as web services that allow users to access the functionality of BMI-enabled models through web services. A BMI-enabled web service model is composed of a set of REST API endpoints, each of which exposes a BMI function at most cases. One of the usages of BMI-enabled web services models is implemented in integrating these web service models through EMELI-WEB. Currently, `BMI-enabled TopoFlow components <https://csdms.colorado.edu/wiki/Model:TopoFlow>`_ are exposed as web services.


Endpoints for Available Models
------------------------------
.. http:get:: /bmi/models

   Return all the available BMI-enabled web service models.

   **Example request**:

   .. sourcecode:: http

      GET /bmi/models HTTP/1.1
      Host: ecgs.ncsa.illinois.edu/

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
       "models": [
          "channels_diffusive_wave",
          "channels_dynamic_wave",
          "channels_kinematic_wave",
          "met_base"]
      }

   .. jsoncall:: /bmi/models

	         {}

.. http:get:: /bmi/models/{model}/working

    Check whether a specific web service model named as `model` is working.

    :param model: the name of the model
    :type model: string

    **Example request**:

    .. sourcecode:: http

        GET /bmi/models/met_base/working HTTP/1.1
        Host: ecgs.ncsa.illinois.edu/

    **Example response 1 -- when the web service model is working**:

    .. sourcecode:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
            "info": true
        }

    **Example response 2 -- when the web service model is not working**:

    .. sourcecode:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
           "info": false
        }


Endpoints for Model Control Functions
-------------------------------------
.. http:post:: /bmi/models/{model}/instantiate

   Instantiate the BMI-enabled web service model with name 'model' and return back an ID for further web service interactions.

   :param model: the name of the model
   :type model: string

   **Example request**:

   .. sourcecode:: http

      POST /bmi/models HTTP/1.1
      Host: ecgs.ncsa.illinois.edu/

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
       "ID": "fa821dfbc4844559a6d67e910aa58db5"
      }

.. http:put:: /bmi/models/{model}/{id}/initialize

    Initialize the BMI-enabled web service model with name `model` and `id` after it is instantiated and the configuration file if any is sent to it.

    :param model: the name of the model
    :type model: string
    :param id: the ID of the model instance, generated when the model is instantiated
    :type id: string

    **Example request**:

    .. sourcecode:: http

      PUT /bmi/models/met_base/fa821dfbc4844559a6d67e910aa58db5/initialize HTTP/1.1
      Host: ecgs.ncsa.illinois.edu/

    **Example response1 -- when the web service model is instantiated**:

    .. sourcecode:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
          "status": "initialized",
          "DONE": false,
          "temp_file": "TopoFlow_Meterology_initialized.nc",
          "time": 0.0
        }

    **Example response2 -- when it fails**:

    .. sourcecode:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
         "info": "Model is not initialized."
        }

.. http:put:: /bmi/models/{model}/{id}/update

    Update the BMI-enabled web service model with name `model` and `id` after it is initialized.

    :param model: the name of the model
    :type model: string
    :param id: the ID of the model instance, generated when the model is instantiated
    :type id: string
    :query download_updatenc: a boolean value indicating whether a temporary NetCDF file storing the output variable values at the current time should be generated.

    **Example request**:

    .. sourcecode:: http

      PUT /bmi/models/met_base/fa821dfbc4844559a6d67e910aa58db5/update?download_updatenc=true HTTP/1.1
      Host: ecgs.ncsa.illinois.edu/

    **Example response1 -- when the web service model is updated and generates a NetCDF file**:

    .. sourcecode:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
          "status": "updated",
          "DONE": false,
          "temp_file": "TopoFlow_Meterology_updated.nc",
          "time": 6.0
        }

    **Example response2 -- when it fails**:

    .. sourcecode:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
         "info": "Model is not updated."
        }

.. http:put:: /bmi/models/{model}/{id}/finalize

    Finalize the BMI-enabled web service model with name `model` and `id` after the simulation is done.

    :param model: the name of the model
    :type model: string
    :param id: the ID of the model instance, generated when the model is instantiated
    :type id: string

    **Example request**:

    .. sourcecode:: http

      PUT /bmi/models/met_base/fa821dfbc4844559a6d67e910aa58db5/finalize HTTP/1.1
      Host: ecgs.ncsa.illinois.edu/

    **Example response1 -- when the web service model is instantiated**:

    .. sourcecode:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
          "status": "finalized",
          "DONE": true,
          "temp_file": "TopoFlow_Meterology_finalized.nc",
          "time": 24.0
        }

    **Example response2 -- when it fails**:

    .. sourcecode:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
         "info": "Model is not finalized."
        }

Endpoints for Model Information Functions
-----------------------------------------

.. http:get:: /bmi/models/{model}/get_input_requirements

    Return the configuration information about what the model with name `model` requires for the initialization in RDF triples.

    :param model: the name of the model
    :type model: string


.. http:get:: /bmi/models/{model}/{id}/get_input_var_names

    Return the inputs of the BMI-enabled web service model with name `model` and `id`

    :param model: the name of the model
    :type model: string
    :param id: the ID of the model instance, generated when the model is instantiated
    :type id: string

    **Example request**:

    .. sourcecode:: http

      GET /bmi/models/met_base/fa821dfbc4844559a6d67e910aa58db5/get_input_var_names HTTP/1.1
      Host: ecgs.ncsa.illinois.edu/

    **Example response**:

    .. sourcecode:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
          "inputs": [
            "snowpack__z_mean_of_mass-per-volumn-density",
            "snowpack__depth",
            "snowpack__liquid-equivalent_depth",
            "snowpack__melt_volume_flux"
          ]
        }


.. http:get:: /bmi/models/{model}/{id}/get_output_var_names

    Return the outputs of the BMI-enabled web service model with name `model` and `id`

    :param model: the name of the model
    :type model: string
    :param id: the ID of the model instance, generated when the model is instantiated
    :type id: string

    **Example request**:

    .. sourcecode:: http

      GET /bmi/models/met_base/fa821dfbc4844559a6d67e910aa58db5/get_output_var_names HTTP/1.1
      Host: ecgs.ncsa.illinois.edu/

    **Example response**:

    .. sourcecode:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
          "outputs": [
            "atmosphere_aerosol_dust__reduction_of_transmittance",
            "atmosphere_air-column_water-vapor__liquid-equivalent_depth",
            "atmosphere_bottom_air__brutsaert_emissivity_canopy_factor",
            "atmosphere_bottom_air__temperature"
          ]
        }


.. http:get:: /bmi/models/{model}/{id}/get_config_var_names

    Return the config variables of the BMI-enabled web service model with name `model` and `id`

    :param model: the name of the model
    :type model: string
    :param id: the ID of the model instance, generated when the model is instantiated
    :type id: string

    **Example request**:

    .. sourcecode:: http

      GET /bmi/models/met_base/fa821dfbc4844559a6d67e910aa58db5/get_config_var_names HTTP/1.1
      Host: ecgs.ncsa.illinois.edu/

    **Example response**:

    .. sourcecode:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
          "config": [
            "water-liquid__mass-per-volume_density",
            "model__time_step",
            "land_surface__temperature",
            "land_surface__emissivity"
          ]
        }


.. http:get:: /bmi/models/{model}/{id}/get_attributes

    Return the attributes of the BMI-enabled web service model with name `model` and `id`

    :param model: the name of the model
    :type model: string
    :param id: the ID of the model instance, generated when the model is instantiated
    :type id: string

    **Example request**:

    .. sourcecode:: http

      GET /bmi/models/met_base/fa821dfbc4844559a6d67e910aa58db5/get_attributes HTTP/1.1
      Host: ecgs.ncsa.illinois.edu/

    **Example response**:

    .. sourcecode:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
          "attributes": {
            "author_name": "Scott D. Peckham",
            "cfg_extension": "_meteorology.cfg",
            "cfg_template_file": "Meteorology.cfg.in",
            "cmt_var_prefix": "/Meteorology/Input/Var/",
            "comp_name": "Meteorology",
            "dialog_title": "Meteorology: Method 1 Parameters",
            "grid_type": "uniform",
            "gui_xml_file": "/home/csdms/cca/topoflow/3.1/src/share/cmt/gui/Meteorology.xml",
            "model_family": "TopoFlow",
            "model_name": "TopoFlow_Meteorology",
            "step_method": "explicit",
            "time_step_type": "fixed",
            "time_units": "seconds",
            "version": "3.1"
          }
        }


Endpoints for Temporal Information Functions
--------------------------------------------

.. http:get:: /bmi/models/{model}/{id}/get_time_step

    Return the time step of the BMI-enabled web service model with name `model` and `id` after it is initialized.

    :param model: the name of the model
    :type model: string
    :param id: the ID of the model instance, generated when the model is instantiated
    :type id: string

    **Example request**:

    .. sourcecode:: http

      GET /bmi/models/met_base/fa821dfbc4844559a6d67e910aa58db5/get_time_step HTTP/1.1
      Host: ecgs.ncsa.illinois.edu/

    **Example response1: when it succeeds**:

    .. sourcecode:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
          "step": 0.6
        }

    **Example response2: when it fails**:

    .. sourcecode:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
          "info": "time step cannot be obtained"
        }


.. http:get:: /bmi/models/{model}/{id}/get_time_units

    Return the time units of the BMI-enabled web service model with name `model` and `id` after it is initialized.

    :param model: the name of the model
    :type model: string
    :param id: the ID of the model instance, generated when the model is instantiated
    :type id: string

    **Example request**:

    .. sourcecode:: http

      GET /bmi/models/met_base/fa821dfbc4844559a6d67e910aa58db5/get_time_units HTTP/1.1
      Host: ecgs.ncsa.illinois.edu/

    **Example response1: when it succeeds**:

    .. sourcecode:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
          "units": "second"
        }

    **Example response2: when it fails**:

    .. sourcecode:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
          "info": "time units cannot be obtained"
        }


.. http:get:: /bmi/models/{model}/{id}/get_time/{when}

    Return the time of the BMI-enabled web service model with name `model` and `id` after it is initialized.

    :param model: the name of the model
    :type model: string
    :param id: the ID of the model instance, generated when the model is instantiated
    :type id: string
    :param when: the specified time (the available options for `when` are "current", "start" and "end")
    :type when: string

    **Example request**:

    .. sourcecode:: http

      GET /bmi/models/met_base/fa821dfbc4844559a6d67e910aa58db5/get_time/current HTTP/1.1
      Host: ecgs.ncsa.illinois.edu/

    **Example response1: when it succeeds in getting the current time**:

    .. sourcecode:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
          "time": 12.0
        }

    **Example response2: when it fails**:

    .. sourcecode:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
          "info": "current time cannot be obtained"
        }


Endpoints for Grid Control Functions
------------------------------------

.. http:get:: /bmi/models/{model}/{id}/{var}/get_grid_properties

    Return the grid properties of the variable with name `var` in the BMI-enabled web service model with name `model` and `id` after it is initialized.

    :param model: the name of the model
    :type model: string
    :param id: the ID of the model instance, generated when the model is instantiated
    :type id: string
    :param var: the standard name of the variable used by the model
    :type var: string

    **Example request**:

    .. sourcecode:: http

      GET /bmi/models/met_base/fa821dfbc4844559a6d67e910aa58db5/land_surface__slope_angle/get_grid_properties HTTP/1.1
      Host: ecgs.ncsa.illinois.edu/

    **Example response1: when it succeeds**:

    .. sourcecode:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
          "grid_type": "uniform",
          "grid_info": {
            "lower_left_corner": [377239, 4459392, 0.0],
            "spacing": [24.37, 32.85, 0.0],
            "shape": [586, 399, 0]
          }
        }

    **Example response2: when it fails**:

    .. sourcecode:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
          "info": "fail in getting the grid properties of land_surface__slope_angle."
        }


Endpoints for Variable Setter Functions
---------------------------------------

.. http:put:: /bmi/models/{model}/{id}/set_vars_provided_list

    Inform the BMI-enabled web service model with name `model` and `id` of the variables which would be used by other models after it is instantiated.

    :param model: the name of the model
    :type model: string
    :param id: the ID of the model instance, generated when the model is instantiated
    :type id: string
    :<json list[string] vars_provided: a list of variables which would used by other models in standard names.

    **Example request**:

    .. sourcecode:: http

      PUT /bmi/models/met_base/fa821dfbc4844559a6d67e910aa58db5/set_vars_provided HTTP/1.1
      Host: ecgs.ncsa.illinois.edu/
      Accept: application/json
      Data: {"vars_provided": ["atmosphere_aerosol_dust__reduction_of_transmittance", "atmosphere_air-column_water-vapor__liquid-equivalent_depth"]}

    **Example response1: when it succeeds**:

    .. sourcecode:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
          "info": "success"
        }

    **Example response2: when it fails**:

    .. sourcecode:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
          "info": "Fail in setting the provided variable list."
        }


.. http:put:: /bmi/models/{model}/{id}/set_values_for_vars

    Reset the values of some variables in the BMI-enabled web service model with name `model` and `id` by sending a NetCDF file which includes the values of variables to be setted after the model is instantiated.

    :param model: the name of the model
    :type model: string
    :param id: the ID of the model instance, generated when the model is instantiated
    :type id: string
    :form setted_vars_file: a file object containing the values of the variables that are to be setted in a NetCDF file
    :type setted_vars_file: file

    **Example response1: when it succeeds**:

    .. sourcecode:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
          "info": "success"
        }

    **Example response2: when it fails**:

    .. sourcecode:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
          "info": "Fail in setting the provided variable list."
        }


Other Endpoints
---------------
.. http:put:: /bmi/models/{model}/{id}/send_cfg_sup_files

    Send a configuration file along with any input files to the BMI-enabled web service model with name `model` and `id` after the model is instantiated.

    :param model: the name of the model
    :type model: string
    :param id: the ID of the model instance, generated when the model is instantiated
    :type id: string
    :form cfg_file: a file object for the configuration file
    :form sup_file: a file object for any input file (can be more than one)

    **Example response1: when the configuration file(s) is successfully sent to the service**:

    .. sourcecode:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
          "info": "success"
        }

    **Example response2: when it fails**:

    .. sourcecode:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
          "info": "Fail. File is not valid."
        }

.. http:put:: /bmi/models/{model}/{id}/update/{mode_status}

    Update the mode status of the BMI-enabled web service model with name `model` and `id` after it is instantiated.

    :param model: the name of the model
    :type model: string
    :param id: the ID of the model instance, generated when the model is instantiated
    :type id: string
    :param mode_status: the mode status of the model (options: "driver" and "nondriver")
    :type mode_status: string

    **Example request**:

    .. sourcecode:: http

      PUT /bmi/models/met_base/fa821dfbc4844559a6d67e910aa58db5/update/driver HTTP/1.1
      Host: ecgs.ncsa.illinois.edu/

    **Example response1: when it succeeds**:

    .. sourcecode:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
          "mode": "driver"
        }

    **Example response2: when it fails**:

    .. sourcecode:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
          "info": "the mode is not updated"
        }


.. http:get:: /bmi/models/{model}/{id}/output

    Get the information of the output files of the BMI-enabled web service model with name `model` and `id` after it is instantiated.

    :param model: the name of the model
    :type model: string
    :param id: the ID of the model instance, generated when the model is instantiated
    :type id: string

    **Example request**:

    .. sourcecode:: http

      PUT /bmi/models/met_base/fa821dfbc4844559a6d67e910aa58db5/output HTTP/1.1
      Host: ecgs.ncsa.illinois.edu/

    **Example response**:

    .. sourcecode:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
          "files": ["test_0D-I.nc"]
        }


.. http:get:: /bmi/models/{model}/{id}/download_temp_nc/{filename}

    Download the temporary NetCDF files of the BMI-enabled web service model with name `model` and `id` after the model is initialized, updated and finalized.

    :param model: the name of the model
    :type model: string
    :param id: the ID of the model instance, generated when the model is instantiated
    :type id: string
    :param filename: the filename of the temporary NetCDF files
    :type filename: string


.. http:get:: /bmi/models/{model}/{id}/download_output/{filename}

    Download the output files (if any) of the BMI-enabled web service model with name `model` and `id` after the model is finalized. The output file information can be obtained from the API endpoint of output.

    :param model: the name of the model
    :type model: string
    :param id: the ID of the model instance, generated when the model is instantiated
    :type id: string
    :param filename: the filename of the output file
    :type filename: string


.. http:delete:: /bmi/models/{model}/{id}/remove

    Remove the instance (the including the model instance and the files (i.e., input, output and temp files) if any) of BMI-enabled web service model with name `model` and `id` after the model is instantiated.

    **Example request**:

    .. sourcecode:: http

        DELETE /bmi/models/met_base/fa821dfbc4844559a6d67e910aa58db5/remove HTTP/1.1
        Host: ecgs.ncsa.illinois.edu/

    **Example response1: when the model instance is removed**:

    .. sourcecode:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
          "info": "success"
        }

    *Example response2: when the ID does not exist**:

    .. sourcecode:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
          "info": "ID does not exist"
        }