Metadata-Version: 2.4
Name: ymmsl2svg
Version: 0.1
Summary: Visualize yMMSL workflow as Scalable Vector Graphics (SVG)
Author-email: Maarten Sebregts <msebregts@ignitioncomputing.com>, Iris van der Werf <ivanderwerf@ignitioncomputing.com>
License-Expression: Apache-2.0
Project-URL: homepage, https://github.com/multiscale/ymmsl2svg
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: click
Requires-Dist: svg.py
Requires-Dist: watchfiles>=1.0
Requires-Dist: ymmsl>=0.18
Provides-Extra: dev
Requires-Dist: ruff; extra == "dev"
Requires-Dist: ty; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Dynamic: license-file

# ymmsl2svg: Visualize yMMSL workflows

Visualize yMMSL workflow as Scalable Vector Graphics (SVG).

This tool takes a yMMSL model (from a v0.2 yMMSL file) and generates an SVG image to
represent it.

## Features

- Visualize the coupling diagram for yMMSL (sub)models
- Call/release (a.k.a. macro-micro) coupling
- Dispatch coupling
- Visualize component ports: F_INIT ports are drawn on the left side of a component as
  an open diamond, O_F ports on the right side as a closed diamond, and O_I and S ports
  on the bottom as respectively a closed and an open circle.
- Visualize model ports: F_INIT ports on the left side of the model, O_F ports on the
  right side. Model O_I and S ports are not (yet) supported.
- Visualize "multi-cast" conduits, where one output port sends to multiple input ports.
- Draw conduits with filters.

Note that not `ymmsl2svg` cannot visualize all valid yMMSL configurations, see
[Roadmap](#roadmap) for a brief overview of missing functionality.

## Examples

Click to open the image in a new tab and enable interactive features, such as tooltips
with the port name when hovering over a port.

[![Dispatch submodel with model ports](examples/simple-dispatch.svg)](https://raw.githubusercontent.com/multiscale/ymmsl2svg/refs/heads/main/examples/simple-dispatch.svg)

[![Complex call/release coupling](examples/macro-micro-dispatched.svg)](https://raw.githubusercontent.com/multiscale/ymmsl2svg/refs/heads/main/examples/macro-micro-dispatched.svg)

## Installation

`ymmsl2svg` is [available on PyPI](https://pypi.org/project/ymmsl2svg/) and can be
installed with pip:

```bash
pip install ymmsl2svg
```

## Usage

```bash
# Create 'workflow.svg' image from the root model in 'workflow.ymmsl'
ymmsl2svg workflow.ymmsl -o workflow.svg

# Show supported options and settings
ymmsl2svg --help
```

### Live viewer

`ymmsl2svg-live` shows the diagram of a yMMSL file in your browser and re-renders it
every time you save the file, so you can edit yMMSL in your favourite text editor with
a live preview next to it. If you save a file with errors, the error message appears
above the last working diagram. If there is no working diagram yet, you see just the
error until you fix it. It works on Linux, macOS and Windows (including WSL).

To use it on your own computer, run:

```bash
ymmsl2svg-live workflow.ymmsl
```

This opens the viewer in your browser. If no browser opens (for example on WSL), copy
the address printed in the terminal, `http://127.0.0.1:8765`, into your browser. Use
`--no-open-browser` if you don't want a browser to open automatically. If that address
is already in use, choose another number with `--port`, for example `--port 12345`.

Use `--debug` to enable debug visualizations. Run `ymmsl2svg-live --help` for all
options.

## Roadmap

`ymmsl2svg` currently cannot visualize any valid yMMSL model yet, this section
provides a brief overview of missing features that we would like to implement in the
future: 

- **Missing yMMSL features**
  - Visualize interact coupling diagrams and time-scale bridges.
    <sup>[1](#footnote1)</sup>
  - Visualize components with multiple sub-timelines. <sup>[1](#footnote1)</sup>
  - Visualize O_I and S ports of models. <sup>[2](#footnote2)</sup>
- **Command Line Interface**
  - Allow selecting a specific model in the yMMSL configuration (currently only the
    [_root_ model](https://ymmsl-python.readthedocs.io/en/stable/api.html#ymmsl.v0_2.Configuration.root_model)
    is visualized).
  - Allow changing settings / parameters from the Command Line interface.
- **Additional features**
  - Interactive highlight of connected conduits when hovering over components or ports.
  - Add an option to draw parallel components under eachother.

<a name="footnote1">1</a>: The SVG generation currently fails for models containing
this.<br/>
<a name="footnote1">2</a>: An SVG is generated for models containing this, but a warning
is logged and the visualization is not complete.<br/>


## Legal

Copyright 2026 ITER Organization. The code in this repository is licensed under the
[Apache-2.0 license](LICENSE.txt)
