Starting your own HydroMT Plugin

You’ve discovered HydroMT and would like to use it for your own model and wonder how to get started about it? This page gives you some tips and tricks on how start your own HydroMT plugin. Before reading this, you should already know a little about HydroMT, so please check out at least the User guide and the Overview models section.

Note

Most of this section of the docs is dedicated to creating new functinoality. If you already have a plugin and want to know how to port that to the new V1 architecture please refer to The migration guide specifically.

The new V1 architecture of HdydroMT already offers a lot more flexibility to customise the behaviour of HydroMT without the need for a plugin, by adding ModelComponents however there are still plenty of use cases you might want to make a plugin, including but not limited to:

• reading or writing custom data formats

• Implementing new components

• providing standard data catalogs for others to use

If you want to do any of the above, and there is a decent chance that others might want to use your code, then you have a good case for a plugin!

Create your own plugin repository

HydroMT makes it pretty easy to create your own plugin. You can create a plugin to customise or create new variants of any of the following objects:

• Model

• ModelComponent

• Resolvers

• Driver

• Catalog

Please see _register_plugins for more detail on how to make sure that HydroMT will find your implementation. Currently the only real requirement for making a HydroMT plugin is that it is a Python Package that uses one of the above entrypoints and inherits from the appropriate base class so hydroMT will know how to operate it.

This does not mean that your plugin must necessarily be written entirely in python, but if it isn’t you will have to make python bindings for it. This can help with performance but is also quite complex, so anyone unsure how to go about this, we recommend using Python.

Typical HydroMT repository structure

With HydroMT and some of its plugins, we usually use a classic folder structure and file organisation. It not mandatory to follow this structure But if you choose to, a classic folder structure and files for a HydroMT plugin (eg mymodel) looks like this:

• docs: folder containing your documentation pages.

• examples: folder containing example models, templates for building/updating models, jupyter notebooks.

• tests: folder containing your test scripts.

• pyproject.toml: your build-system requirements for your python package (used by pypi and conda).

• README.md: your landing documentation page for your repository.

• LICENSE: license file for your repository.

• hydromt_awesome: folder containing the functions for your plugin.

  • __init__.py: init python script used when importing the hydromt_awesome package in a python script.

  • submodules for the objects you wish to expose to hydromt such as: - resolvers - catalogs - model - components - drivers

Please refer to the specific section of each of these objects for more information about their specific requirements and uses.