iWrap

iWrap is a modular component generator, implemented in Python, used for creating IMAS actors from physics models. This mechanism allows to integrate physics codes written in one language (Fortran, CPP) within complex computing scenarios designed in other language (e.g. Python).

It's plug-in based modular design with clear separation of concerns allows to generate various types of actors and easily change data access paradigm (from dataset descriptor for AL to direct HDC data for instance)

Available Actor Types

iWrap includes the following built-in actor generators:

• Python Actor: Standard Python actors for straightforward Python integrations
• MUSCLE3 Actors (optional): High-performance multiscale coupling framework
  • MUSCLE3-Python: Python code with MUSCLE3 coupling
  • MUSCLE3-Cpp: C++ code with MUSCLE3 coupling
  • MUSCLE3-Fortran: Fortran code with MUSCLE3 coupling

For user conveniency it provides two kinds of interfaces:

• user friendly graphical interface that allows non-experienced users to define an actor in intuitive way
• command line interface foreseen for more advanced users that may want to e.g. automatise actor generation process using scripts.

Tutorials

To learn about iWrap, please follow tutorials/README.md to generate an interactive and step-by-step tutorial in a Jupyter Notebook.

We have also prepared HTML and Docker versions, so you can choose the one that suits you best.

Installation

Quick Install

Basic Installation (Core Only)

pip install iwrap

This installs iWrap with the standard Python actor generator.

Installation with MUSCLE3 Support

pip install iwrap[muscle3]

This enables MUSCLE3 actor generators (MUSCLE3-Python, MUSCLE3-Cpp, MUSCLE3-Fortran).

Development Installation

pip install iwrap[all]

Installs all optional dependencies including MUSCLE3.

Verify Installation

List available actor types:

iwrap --list-actor-types

Configuration of working environment

Downloading software

git clone https://github.com/iterorganization/iWrap.git
cd iwrap
git checkout <branch>

Environment configuration

To configure an environment, please go to iwrap main directory and execute from commandline:

source set-iter.sh (on ITER IO cluster)
OR
source set-gw.sh (on EF Gateway)

The scripts provide very simple operations. It:

• purges modules
• loads IMAS
• sets PATH and PYTHONPATH
• sets compiler flags like CXX, FC, MPICXX, MPIFC

Launching iWrap

To launch iWrap, just execute on commandline:

• to run commandline version

  iwrap

• to run iWrap user interface

  iwrap-gui

Both scripts share the same set arguments and switches:

shell>iwrap -h
usage: iwrap [-h] [-a ACTOR_NAME] [-t ACTOR_TYPE] [-d DATA_TYPE] [-f FILE]
             [-i INSTALL_DIR] [--list-actor-types]
             [--list-actor-details [ACTOR_TYPE]] [-v]

iWrap - a modular component generator, used for creating IMAS actors from
physics models.

optional arguments:
  -h, --help            show this help message and exit

Actor generation:
  -a ACTOR_NAME, --actor-name ACTOR_NAME
                        user defined name of the actor
  -t ACTOR_TYPE, --actor-type ACTOR_TYPE
                        type of an actor to be generated
  -d DATA_TYPE, --data-type DATA_TYPE
                        type of data to be used by the actor
  -f FILE, --file FILE  a path to code/actor description *.yaml file
  -i INSTALL_DIR, --install-dir INSTALL_DIR
                        actor installation directory

Additional information:
  --list-actor-types    lists registered actor types that can be generated
  --list-actor-details [ACTOR_TYPE]
                        lists details of given actor type generator
  -v, --version         show program's version number and exit


For more information, visit <https://confluence.iter.org/display/IMP/IMAS+component+generator>.

Actor generation

shell> iwrap -a <actor_name> -f <path/to/code_description.yaml>

... will generate an actor based on code description stored in yaml, where ...

shell> iwrap-gui -a <actor_name> -f <path/to/code_description.yaml>

... will launch iWrap GUI filled in with information coming from code description

Tutorials

iWrap provides its tutorials in two formats:

• interactive Jupyter Notebooks .ipynb
• static nested HTML pages in a book format .html

Start your tutorial journey by heading to the tutorials directory and opening the README.md file found there (it will explain how to set up and run tutorials in both formats and under different environments).

Manuals

Documentation is available at iwrap.readthedocs.io

Examples

Examples placed in directory iwrap/examples can be an excellent source of knowledge related to code description syntax, actors API and the way actors are called from workflow.

Introduction

A content of a directory is similar for all examples and consist of:

• native_code directory - containing a physics model to be wrapped
• YAML file - providing all information essential for iWrap to generate an actor from the native code
• Makefile that simplifies all the steps requires from building a native code to running an example
• Python script - containing simple scenario (aka workflow) that allow to run given example

Prerequisites

Following software must be available to run the examples:

• IMAS built with Access Layer of version 4.11 (or later)
• XMLLib library - necessary to build and run actors that wraps code using XML parameters - should be available via pkg-config mechanism
• compiler flags: CXX, FC, MPICXX, MPIFC must be set

To simplify setting up a working environment, configuration scripts are available for two of the platforms commonly utilized by IMAS users:

• set-iter.sh for the ITER Organisation computing cluster (SDCC)
• set-gw.(ba)sh for the EUROfusion Gateway

All scripts need to be sourced

Building and running examples

Following steps need to be performed to build and run an example:

1. Jump to example directory:

   cd <example_dir>
   

2. Build the native code:

   make native
   

3. Generate a Python actor:

   make actor
   

4. Run a simple scenario:

   make wf-run