.. _models:

=========================
InVEST Model Entry Points
=========================

All InVEST models share a consistent python API:

    - Every InVEST model has a corresponding subpackage in the
      ``natcap.invest`` package. This subpackage will typically contain a main
      model module with that model's python source code.
    - The model modules contain a function called ``execute``. This function is
      also available from the model subpackage. For example,
      ``natcap.invest.carbon.execute`` and ``natcap.invest.carbon.carbon.execute``
      both work and refer to the same function.
    - The ``execute`` function takes a single argument (``args``), a dictionary
      that stores all data inputs and configuration options for the model
    - This dictionary contains an entry, ``'workspace_dir'``, which is a path
      to the folder where the model will create its output files
    - Other required and optional entries in the dictionary are specific to
      each model

To run a model, import the model's ``execute`` function and then call it with
the correct parameters. For example, a script for the Carbon model might look
like

.. code-block:: python

    import natcap.invest.carbon
    args = {
        'workspace_dir': 'path/to/workspace'
        # Other arguments, as needed for Carbon.
    }

    natcap.invest.carbon.execute(args)

For examples of scripting a model run, or multiple successive model runs,
see :ref:`CreatingPythonScripts`.


.. contents:: Available Models and Tools:
    :local:

Annual Water Yield
==================
.. autofunction:: natcap.invest.annual_water_yield.annual_water_yield.execute
   :noindex:

Carbon Storage and Sequestration
================================
.. autofunction:: natcap.invest.carbon.carbon.execute
   :noindex:

Coastal Blue Carbon
===================
.. autofunction:: natcap.invest.coastal_blue_carbon.coastal_blue_carbon.execute
   :noindex:

Coastal Blue Carbon Preprocessor
================================
.. autofunction:: natcap.invest.coastal_blue_carbon.preprocessor.execute
   :noindex:

Coastal Vulnerability
=====================
.. autofunction:: natcap.invest.coastal_vulnerability.coastal_vulnerability.execute
   :noindex:

Crop Production: Percentile
===========================
.. autofunction:: natcap.invest.crop_production_percentile.crop_production_percentile.execute
   :noindex:

Crop Production: Regression
===========================
.. autofunction:: natcap.invest.crop_production_regression.crop_production_regression.execute
   :noindex:

DelineateIt
===========
.. autofunction:: natcap.invest.delineateit.delineateit.execute
   :noindex:

Forest Carbon Edge Effect
=========================
.. autofunction:: natcap.invest.forest_carbon_edge_effect.forest_carbon_edge_effect.execute
   :noindex:

Habitat Quality
===============
.. autofunction:: natcap.invest.habitat_quality.habitat_quality.execute
   :noindex:

Habitat Risk Assessment
=======================
.. autofunction:: natcap.invest.hra.hra.execute
   :noindex:

Nutrient Delivery Ratio
=======================
.. autofunction:: natcap.invest.ndr.ndr.execute
   :noindex:

Crop Pollination
================
.. autofunction:: natcap.invest.pollination.pollination.execute
   :noindex:

Visitation: Recreation and Tourism
==================================
.. autofunction:: natcap.invest.recreation.recmodel_client.execute
   :noindex:

RouteDEM
========
.. autofunction:: natcap.invest.routedem.routedem.execute
   :noindex:

Scenario Generator: Proximity Based
===================================
.. autofunction:: natcap.invest.scenario_gen_proximity.scenario_gen_proximity.execute
   :noindex:

Scenic Quality
==============
.. autofunction:: natcap.invest.scenic_quality.scenic_quality.execute
   :noindex:

Sediment Delivery Ratio
=======================
.. autofunction:: natcap.invest.sdr.sdr.execute
   :noindex:

Seasonal Water Yield
====================
.. autofunction:: natcap.invest.seasonal_water_yield.seasonal_water_yield.execute
   :noindex:

Urban Stormwater Retention
==========================
.. autofunction:: natcap.invest.stormwater.stormwater.execute
   :noindex:

Urban Cooling
=============
.. autofunction:: natcap.invest.urban_cooling_model.urban_cooling_model.execute
   :noindex:

Urban Flood Risk Mitigation
===========================
.. autofunction:: natcap.invest.urban_flood_risk_mitigation.urban_flood_risk_mitigation.execute
   :noindex:

Urban Mental Health
===================
.. autofunction:: natcap.invest.urban_mental_health.urban_mental_health.execute
   :noindex:

Urban Nature Access
===================
.. autofunction:: natcap.invest.urban_nature_access.urban_nature_access.execute
   :noindex:

Wave Energy Production
======================
.. autofunction:: natcap.invest.wave_energy.wave_energy.execute
   :noindex:

Wind Energy Production
======================
.. autofunction:: natcap.invest.wind_energy.wind_energy.execute
   :noindex: