Plugins

Plugins extend the functionality of the enchanted-surrogates package by adding support for specific simulation codes. Each plugin typically consists of a parser and a runner that handle the specifics of reading/writing input/output files and executing simulations for a particular code.

How to install plugins

To install a plugin, you need to clone its repository and install it using pip. For example, you can use the following commands:

git clone https://github.com/DIGIfusion/enchanted-plugin-codename.git
pip install -e enchanted-plugin-codename/

How to use plugins

Once you have installed a plugin, you can use it with the enchanted-surrogates interface. You need to specify the parser and runner corresponding to the plugin in your configuration file.

How to develop plugins

📂 Project Structure

Go to enchanted-plugin-template and click "Use this template" to create a new repository for your plugin.

Note that the repository name should follow the format enchanted-plugin-template, where template is a unique identifier for your plugin. The package name inside src/ should match this name but with underscores between the words instead of hyphens.

The basic structure of the plugin should look like this:

enchanted-plugin-template/
├── src/
│  └── enchanted_plugin_template/
│    ├── __init__.py
│    ├── template_parser.py
│    └── template_runner.py
├── tests/
│    └── test_plugin.py
│    └── ...
├── README.md
├── pyproject.toml

The template contains basic units tests and a GitHub Actions workflow. Change the names and contents of the files to match your plugin.

🛠️ Development Steps

Set Up Your Environment:

Create a virtual environment and activate it:

python -m venv .venv
source .venv/bin/activate  # On Windows use `.venv\Scripts\activate`

Clone the enchanted-surrogates repository to have access to the core package:

git clone https://github.com/DIGIfusion/enchanted-surrogates.git
pip install -e enchanted-surrogates/

Create the Plugin Repository:

Go to enchanted-plugin-template and click "Use this template" to create a new repository for your plugin. Name it following the format enchanted-plugin-codename, where codename is a unique identifier for your plugin.

Clone your new repository and install it in editable mode:
```
git clone https://github.com/DIGIfusion/enchanted-plugin-codename.git
pip install -e enchanted-plugin-codename/
```
Inside this directory, create/edit the necessary files.

Dependencies and entrypoints

Create a pyproject.toml file in the root of your plugin directory to manage dependencies and define entry points. Here is a basic example:

[tool.poetry]
name = "enchanted-plugin-codename"
version = "0.1.0"
description = "A plugin for enchanted-surrogates to support Codename simulations."
readme = "README.md"
authors = [{name = "", email = ""},]
license = {text = "MIT"}
dependencies = [
  "enchanted_surrogates",
  "f90nml==1.4.4",
  "numpy",
  "fortranformat",
  "scipy",]
requires-python = ">=3.10"

[tool.setuptools.packages.find]
where = ["src"]

Define entry points in pyproject.toml to register your parser and runner with the enchanted-surrogates framework. For example:

[tool.poetry.plugins."enchanted_surrogates.parsers"]
codename_parser = "enchanted_plugin_codename.codename_parser:CodenameParser"

[tool.poetry.plugins."enchanted_surrogates.runners"]
codename_runner = "enchanted_plugin_codename.codename_runner:CodenameRunner"

These will allow the main package to discover and utilize your plugin seamlessly.

Implement the Plugin:

In codename_parser.py, implement the class CodenameParser with logic to read and write input/output files.

In codename_runner.py, implement the class CodenameRunner with logic to execute simulations.

Ensure your code adheres to the interfaces defined in the enchanted-surrogates package.

When the entrypoints and the logic is implemented, you can install your plugin in editable mode for development:
```
cd enchanted-plugin-codename
pip install -e .
```
after which you can use your plugin with enchanted-surrogates.
Testing:

Write unit tests in the tests\ folder to validate the functionality of your parser and runner. The folder already contains some test files that should be edited to correctly test your plugin.

Use pytest to run your tests:
```
pytest tests/ -sv
```
Github Actions:

The plugin template contains a GitHub Actions workflow setup to automate testing and deployment. Make sure the tests pass.
Documentation:

Update the README.md file with information about your plugin, including installation instructions, usage examples, and any other relevant details.

In case you want to add your plugin to the official documentation, create a pull request to the docs/plugins/ in the enchanted-surrogates repository, following the format used for existing plugins.

You can also add docstring documentation if you have it on the plugin. Ensure first that you have init.py in module you want to import even if it is empty.

For adding docstring documentation fill out the configuration file plugins.yml in main repo as shown below and as done with other plugins, and create a pull request with the updated configuration file. Docstrings will be added automatically.

Example of filling configuration file for template plugin:

  - name: templete_plugin
    repo: DIGIfusion/enchanted-plugin-templete
    module: enchanted_plugin_templete
    src_path: src

Module import all module in templete plugin. If you want import only one or more specific module use exact path. For example for importing only runner documentation use enchanted_plugin_templete.template_runner

Existing plugins

The template for creating new plugins is publicly available at enchanted-plugin-template.

The existing plugins are private repositories, but you can request access by contacting DIGIfusion. The currently available plugins are: