Skip to content

plugin_development.md

Latest commit

 

History

History
79 lines (55 loc) · 2.09 KB

plugin_development.md

File metadata and controls

79 lines (55 loc) · 2.09 KB
Raw

Plugin Development Guide

This guide walks you through creating a new ERAD plugin.

Plugin Layout

Every plugin lives under plugins/ and follows the standard src layout:

plugins/erad-plugin-<name>/
├── pyproject.toml
├── README.md
├── src/
│   └── erad_plugin_<name>/
│       ├── __init__.py
│       └── plugin.py
└── tests/
    ├── __init__.py
    └── test_plugin.py

Step-by-Step

1. Scaffold the plugin

Copy an existing plugin as a starting point:

cp -r plugins/erad-plugin-forefire plugins/erad-plugin-<name>

Rename the source package:

mv plugins/erad-plugin-<name>/src/erad_plugin_forefire \
   plugins/erad-plugin-<name>/src/erad_plugin_<name>

2. Update pyproject.toml

Edit the plugin's pyproject.toml:

  • Set name to erad-plugin-<name>.
  • Update description, authors, and dependencies.
  • Register the entry point:
[project.entry-points."erad.plugins"]
<name> = "erad_plugin_<name>.plugin:register"

3. Implement the plugin

In src/erad_plugin_<name>/plugin.py, implement your plugin logic. The register() function serves as the entry point that ERAD will call to discover the plugin.

Your plugin can produce any ERAD hazard model type (`FireModel`, `EarthQuakeModel`, `FloodModel`, `WindModel`). As long as you return valid model objects, ERAD's `HazardSimulator` will handle the rest.

4. Add tests

Write tests under tests/. The plugin's pyproject.toml includes pytest as a dev dependency.

cd plugins/erad-plugin-<name>
pip install -e '.[dev]'
pytest

5. Add documentation

Add a docs page under docs/plugins/<name>/ and register it in docs/_toc.yml.

Conventions

  • Naming: Use erad-plugin-<name> for the package and erad_plugin_<name> for the Python module.
  • Entry points: Register under the erad.plugins group so ERAD can auto-discover plugins.
  • Dependencies: Declare NREL-erad as a dependency in your plugin's pyproject.toml.
  • Testing: Each plugin must have its own test suite under tests/.