Metadata-Version: 2.4
Name: iwrap
Version: 2.0.0
Summary: A modular component generator, implemented in Python, used for creating IMAS actors from physics models.
Author-email: iWrap Developers <olivier.hoenen@iter.org>
License: LGPL-3.0
Project-URL: Homepage, https://github.com/iterorganization/iWrap.git
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: lxml
Requires-Dist: jinja2
Requires-Dist: packaging
Requires-Dist: pyyaml
Requires-Dist: f90nml
Requires-Dist: jsonschema
Requires-Dist: JPype1
Requires-Dist: imas-python
Provides-Extra: muscle3
Requires-Dist: muscle3>=0.7.0; extra == "muscle3"
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: pytest-timeout>=2.3; extra == "test"
Provides-Extra: docs
Requires-Dist: urllib3==2.5.0; extra == "docs"
Requires-Dist: jupyterlab==4.4.5; extra == "docs"
Requires-Dist: jupyter-book==1.0.4.post1; extra == "docs"
Requires-Dist: docutils==0.21.2; extra == "docs"
Requires-Dist: jupyterlab_myst==2.4.2; extra == "docs"
Requires-Dist: markdown_it_py==3.0.0; extra == "docs"
Requires-Dist: mdit_py_plugins==0.4.2; extra == "docs"
Requires-Dist: myst-nb==1.3.0; extra == "docs"
Requires-Dist: myst-parser==3.0.1; extra == "docs"
Requires-Dist: sphinx==7.4.7; extra == "docs"
Requires-Dist: sphinx_inline_tabs==2023.4.21; extra == "docs"
Requires-Dist: typing-extensions==4.14.1; extra == "docs"
Requires-Dist: pylint==3.3.7; extra == "docs"
Requires-Dist: pyparsing==3.2.3; extra == "docs"
Requires-Dist: numpy==1.26.4; extra == "docs"
Requires-Dist: sphinx_immaterial==0.13.5; extra == "docs"
Provides-Extra: all
Requires-Dist: muscle3>=0.7.0; extra == "all"
Requires-Dist: pytest>=8.0; extra == "all"
Requires-Dist: pytest-timeout>=2.3; extra == "all"
Requires-Dist: urllib3==2.5.0; extra == "all"
Requires-Dist: jupyterlab==4.4.5; extra == "all"
Requires-Dist: jupyter-book==1.0.4.post1; extra == "all"
Requires-Dist: docutils==0.21.2; extra == "all"
Requires-Dist: jupyterlab_myst==2.4.2; extra == "all"
Requires-Dist: markdown_it_py==3.0.0; extra == "all"
Requires-Dist: mdit_py_plugins==0.4.2; extra == "all"
Requires-Dist: myst-nb==1.3.0; extra == "all"
Requires-Dist: myst-parser==3.0.1; extra == "all"
Requires-Dist: sphinx==7.4.7; extra == "all"
Requires-Dist: sphinx_inline_tabs==2023.4.21; extra == "all"
Requires-Dist: typing-extensions==4.14.1; extra == "all"
Requires-Dist: pylint==3.3.7; extra == "all"
Requires-Dist: pyparsing==3.2.3; extra == "all"
Requires-Dist: numpy==1.26.4; extra == "all"
Requires-Dist: sphinx_immaterial==0.13.5; extra == "all"
Dynamic: license-file

# iWrap

[![Read the Docs](https://img.shields.io/badge/docs-readthedocs-blue)](https://iwrap.readthedocs.io)

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)
```bash
pip install iwrap
```
This installs iWrap with the standard Python actor generator.

### Installation with MUSCLE3 Support
```bash
pip install iwrap[muscle3]
```
This enables MUSCLE3 actor generators (MUSCLE3-Python, MUSCLE3-Cpp, MUSCLE3-Fortran).

### Development Installation
```bash
pip install iwrap[all]
```
Installs all optional dependencies including MUSCLE3.

## Verify Installation

List available actor types:
```bash
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:

```text
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](https://iwrap.readthedocs.io/en/latest)

# 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:
    ```Shell
    cd <example_dir>
    ```

2. Build the native code:
     ```Shell
    make native
    ```

3. Generate a Python actor:
    ```Shell
    make actor
    ```
   
4. Run a simple scenario:
    ```Shell
    make wf-run
    ```
