Skip to content

Plugins

Jump to bottom
Congjian Wang - INL edited this page Apr 29, 2024 · 24 revisions

RAVEN Plugins

Plugins in RAVEN are an option to associate a workflow or set of RAVEN external models to RAVEN without having them included in the RAVEN repository. Benefits include modularity, access restriction, and regression testing for compatibility with RAVEN as it continues to grow.

Table of Contents

  1. Introduction
  2. Official Plugins
  3. Installation
  4. Usage
  5. Plugin Testing
  6. PIP plugins

Introduction

RAVEN users commonly develop sophisticated workflows with complex physics models while doing their analyses. While RAVEN doesn't provide storage for workflows and physics, these can be associated to RAVEN by the use of plugins. Official plugins are supported through RAVEN regression testing.

  • For particular information on creating new plugins and interfacing with existing plugins, compile the RAVEN plugin manual at raven/docs.

Official Plugins

The following plugin repositories are officially supported by RAVEN. Some are openly available, and others are only available on the INL HPCGitlab repository.

Openly Available

These plugin repositories are available without restriction to RAVEN users:

  • TEAL module: https://github.com/idaholab/TEAL, provides economic analysis tools.
  • HERON module: https://www.github.com/idaholab/HERON, provides workflow generation and dispatching models for performing stochastic technoeconomic analysis of systems of components interconnected by the resources they produce and consume.
  • SR2ML module: https://github.com/idaholab/SR2ML, provides safety, risk and reliability analysis tools.
  • LOGOS module: https://github.com/idaholab/LOGOS, provides computational capabilities to optimize plant resources such as maintenance optimization and optimal component replacement schedule by using state-of-the-art discrete optimization methods.
  • FARM module: https://github.com/Argonne-National-Laboratory/FARM, is designed to solve the supervisory control problem in Integrated Energy System (IES) project. FARM utilizes the linear state-space representation (A,B,C matrices) of a model to predict the system state and output in the future time steps, and adjust the actuation variable to avoid the violation of implicit thermal mechanical constraints.
  • BayCal module: https://github.com/idaholab/BayCal, is arming at inversely quantifying the uncertainties associated with simulation model parameters based on available experiment data. BayCal trys to resolve two critical issues existing in the Bayesian inference: 1) high-dimensional experimental data (such as time series observations at multiple locations), 2) expensive computational simulations. These issues have been studied and resolved in literature, but there is not yet a complete toolkit to resolve these issues in an efficient and automatic way. BayCal automatizes the process by coupling with RAVEN, utilizes artificial intelligence algorithms to automatically construct surrogate models for the expensive computational simulations and dimensionality reduction techniques to significantly reduce the number of simulations for convergence.

On INL HPCGitlab

Access to these plugin repositories requires an open connection to HPCGitlab; if you want to get access to these Plugins, please Contact us.

Registration and Installation

To register a plugin with RAVEN and make its components accessible, run the script

  raven/scripts/install_plugins.py -s /abs/path/to/pluginName

replacing pluginName with the path to your plugin and the name of the directory, such as /user/projects/raven/plugins/pluginName. Use the absolute path to your new plugin to avoid any navigation problems.

If installing an officially-supported plugin that you do not plan on modifying, the following command can be run (using TEAL as the example plugin):

  raven/scripts/install_plugins.py -s TEAL

Note the path was eliminated. This will initialize (or update) the official plugin in raven/plugins with the official submoduled version.

To install all officially-supported plugins, the shortcut option -a or --all can be used:

  raven/scripts/install_plugins.py -a

At this stage, RAVEN will import all the plugins within that directory and perform some error checking.

Alternative Installation (Not Recommend)

In case you have access to any RAVEN plugins' repository (e.g. TEAL), you can clone that repository to be functional with RAVEN (as submodule).

MAC or Linux Machine

[~]> cd projects/raven
[~/projects/raven]> git submodule update --init **pluginName**

Windows Machine

C:\> cd projects\raven
C:\projects\raven> git submodule update --init **pluginName**

The result of the command is as follows:

Submodule 'pluginName' (https://github.com/idaholab/pluginName.git) registered for path 'pluginName'
Cloning into '/home/USER/projects/test/raven/plugins/pluginName'...
Submodule path 'pluginName': checked out '786576deef33a317e654558f39f5f45617c7442b'

Using the plugin in RAVEN

Once registered, new external models can be used in RAVEN by using the model subtype defined by your plugin name. For example, if your external model class is named "myPluginModel", you can access an external model in the RAVEN input as

<Models>
  ...
  <ExternalModel name='myName' subType='pluginName.pluginModel'>
    ...
  </ExternalModel>
  ...
</Models>

Plugin Testing

RAVEN supports some official plugins on a case-by-case basis for regression testing nightly against new RAVEN developments. If you are interested in maintaining your plugin as an official RAVEN plugin, please contact us.

PIP plugins

Some of the plugins are available via pip, including TEAL and HERON. To make a plugin support pip installation, it must be able to be run without any PYTHONPATH manipulation. (That is, imports should be like import TEAL.src.Amortization or from . import Amortization)

Also, a way to build the pip package should be provided. Here are the TEAL files:

setup.cfg

[metadata]
name = teal-ravenframework
version = 0.3
description = TEAL plugin for RAVEN framework
long_description = file: TEAL/README.md
license_files = TEAL/LICENSE.txt TEAL/NOTICE.txt
url = https://github.com/idaholab/TEAL

[options]
packages =
    TEAL
    TEAL/src
python_requires = >=3.7

install_requires =
   raven_framework >=2.2rc1,<2.3
   numpy-financial

pyproject.toml

[build-system]
requires = ["setuptools>=42"]
build-backend = "setuptools.build_meta"

MANIFEST.in

include TEAL/LICENSE.txt
include TEAL/NOTICE.txt
include TEAL/README.md

which can be used to build a TEAL package (note that the TEAL repository needs to be in a subdirectory):

python3 -m pip install --upgrade build
python3 -m build

Pip Plugins with a command

Note that if you want to have pip install a command, something like the following can be added to the setup.cfg:

[options.entry_points]
console_scripts =
   heron = HERON.src.main:main

This would create a script named heron that calls the main function in HERON/src/main.py

Upload the distribution archives (https://packaging.python.org/en/latest/tutorials/packaging-projects/)

python3 -m pip install --upgrade twine
python3 -m twine upload --repository testpypi dist/*

Installing and testing your newly uploaded package

pip install --extra-index-url  https://test.pypi.org/simple/ teal-ravenframework==0.3

Upload the distribution to PYPI

python3 -m twine upload dist/*
Clone this wiki locally