Metadata-Version: 2.1
Name: swirlc
Version: 0.0.1
Summary: Scientific Workflow Intermediate Representation Language
Author-email: Iacopo Colonnelli <iacopo.colonnelli@unito.it>, Doriana Medić <doriana.medic@unito.it>, Alberto Mulone <alberto.mulone@unito.it>
License: LGPL-3.0-or-later
Project-URL: Package, https://pypi.org/project/swirlc
Project-URL: Repository, https://github.com/alpha-unito/swirlc
Project-URL: Docker, https://hub.docker.com/r/alphaunito/swirlc
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: antlr4-python3-runtime==4.13.1
Requires-Dist: black==24.4.2
Requires-Dist: importlib_resources==6.4.0
Requires-Dist: jsonschema==4.22.0
Requires-Dist: referencing==0.35.1
Requires-Dist: ruamel.yaml==0.18.6
Provides-Extra: bandit
Requires-Dist: bandit==1.7.9; extra == "bandit"
Provides-Extra: lint
Requires-Dist: codespell==2.3.0; extra == "lint"
Requires-Dist: flake8-bugbear==24.4.26; extra == "lint"
Requires-Dist: pyupgrade==3.16.0; extra == "lint"
Provides-Extra: test
Requires-Dist: pytest==8.2.2; extra == "test"
Requires-Dist: pytest-cov==5.0.0; extra == "test"
Requires-Dist: pytest-xdist==3.6.1; extra == "test"

# SWIRL: Scientific Workflow Intermediate Representation Language

SWIRL is a low-level intermediate representation language for distributed scientific workflows. Unlike other product-agnostic workflow languages, SWIRL is not intended for human interaction but serves as a low-level compilation target for distributed workflow execution plans. It models the execution plan of a location-aware workflow graph as a distributed system with send/receive communication primitives. The optimised SWIRL representation can then be compiled into one or more self-contained executable bundles, making it adaptable to specific execution environments and embracing heterogeneity. This repository contains the reference SWIRL Compiler toolchain, called `swirlc`, written in Python 3 and relying on the [ANTLR](https://www.antlr.org/) parser generator.

## Install

### PyPI

The `swirlc` package is available on [PyPi](https://pypi.org/project/swirl/), so you can install it using pip.

```bash
pip install swirlc
```

Please note that the SWIRL compiler requires `python >= 3.8`. Then you can use it through the `swirlc` CLI.

### Docker

The SWIRL Docker image is available on [Docker Hub](https://hub.docker.com/r/alphaunito/swirlc). The script below gives an example of `swirlc` CLI invocation in a Docker container

```bash
mkdir -p SWIRL
docker run                          \
        --user $(id -u):$(id -g)    \
        --volume $(pwd):/data       \
        --workdir /data             \
        alphaunito/swirlc:latest    \
    swirlc                          \
        COMMAND                     \
        [OPTION]                     
```

## Use SWIRL

The `swirlc` CLI offers two primary functionalities: `translate` and `compile`. The former translates a distributed workflow written in one of the supported high-level languages into a low-level SWIRL intermediate representation. The latter compiles a SWIRL representation into a target executable bundle.

### Translate

The `swirlc translate` command can be used to translate an existing, high-level workflow representation into a SWIRL low-level intermediate representation, usually stored in a `*.swirl` file, and a `*.yml` file containing a set of metadata. As an example, the following command can be used to generate a SWIRL representation from a [DAX](https://pegasus.isi.edu/documentation/development/schemas.html) workflow generated by the [Pegasus WMS](https://pegasus.isi.edu/):
  
```bash
swirlc translate --language dax [DAX_DIRECTORY]
```

Note that the `DAX_DIRECTORY` must contain four files: `replica.yml`, `sites.yml`, `transformations.yml` and `workflow.yml`.

### Compile

The `swirlc compile` command can be used to create executable traces in different programming languages from a SWIRL representation. The result of the command is an executable bundle ready to run on highly-distributed execution environments (e.g., HPC, Cloud, or Edge). As an example, the following command can be used to generate a Python-based executable bundle from a `SWIRL_FILE` and a `METADATA_FILE`:
  
```bash
swirlc compile [SWIRL_FILE] [METADATA_FILE]
```

Note that all the target locations need to have the Python interpreter installed. 

## SWIRL Team

Iacopo Colonnelli <iacopo.colonnelli@unito.it> (Designer and maintainer)  
Doriana Medić <doriana.medic@unito.it> (Designer and maintainer)  
Alberto Mulone <alberto.mulone@unito.it> (Maintainer)
