diff --git a/doc/index.rst b/doc/index.rst index e0d0324..2641448 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -4,13 +4,25 @@ ewoks |version| .. image:: https://img.shields.io/badge/DOI-10.1080/08940886.2024.2432305-blue :target: https://doi.org/10.1080/08940886.2024.2432305 + +**Ewoks is an ecosystem of Python packages designed to execute computational graphs**, also known as workflows. + +In these workflows: + +- **Nodes** represent processing steps +- **Links** represent data flowing between steps + +.. image:: https://gitlab.esrf.fr/workflow/ewokstutorials/ewoksfordevs/-/raw/main/images/workflow1.excalidraw.svg?ref_type=heads + Many `workflow management systems `_ exist to -deal with data processing problems that can be expressed as a graph of tasks, also referred -to as a *computational graph* or *workflow*. The main purpose of a workflow management system -is to provide a framework for implementing tasks, creating graphs of tasks and executing these graphs. +deal with data processing problems by expressing them as *workflows*. + +Ewoks acts as a **bridge between workflow systems**, enabling the same workflow to be executed across different systems. +Any workflow system can be integrated into Ewoks as an `execution engine <./engines.html>`_, allowing interoperability without +changing the workflow definition or implementation. -The purpose of *ewoks* (Extensible Workflow System) is to provide an abstraction layer between graph -representation and execution. This allows using the same tasks and graphs in different workflow management systems. +Workflows can be defined using **JSON**, **YAML**, or created programmatically in Python following the +`Ewoks specification `_. *ewoks* has been developed by the `Software group `_ of the `European Synchrotron `_. diff --git a/doc/tutorials/getting_started.rst b/doc/tutorials/getting_started.rst index 30663b3..6958612 100644 --- a/doc/tutorials/getting_started.rst +++ b/doc/tutorials/getting_started.rst @@ -1,50 +1,113 @@ Getting started =============== -Install *ewoks* +Install the Ewoks core libraries suite using ``pip``: .. code-block:: bash - pip install ewoks + pip install ewoks -Create a test workflow in JSON format (“acyclic1” is an test workflow that ships with ewoks) +This will include all core tools and example workflows. + +Run an Example Workflow +----------------------- + +The ``ewoks`` package includes several demo workflows. To run the ``demo`` workflow from the command line: .. code-block:: bash - ewoks convert acyclic1 --test test.json + ewoks execute demo -p a=10 -p b=3 --test --outputs=all + +- ``-p a=10 -p b=3``: Set input parameters +- ``--test``: Load the ``demo`` workflow from Ewoks test suite +- ``--outputs=all``: Print outputs of all workflow nodes -Inspect workflow parameters before executing the workflow +For full CLI options, run: .. code-block:: bash - ewoks show test.json + ewoks execute -h -Execute a workflow and print the output of all tasks +Or refer to the `Command-line reference <../reference/cli.html>`_. -.. code-block:: bash +Inspect Workflow Parameters +---------------------------- + +Before executing a workflow, you can inspect its parameters using: - ewoks execute test.json --outputs all +.. code-block:: bash -For a desktop GUI, install *ewoks* with the orange binding + ewoks show demo -p a=10 -p b=3 --test + +Example output: + +.. code-block:: text + + Workflow: demo + Id: demo + Description: demo + ╒════════╤════════════════╤═══════════════════╤═══════╕ + │ Name │ Value │ Task identifier │ Id │ + ╞════════╪════════════════╪═══════════════════╪═══════╡ + │ list │ [0, 1, 2] │ SumList │ task0 │ + ├────────┼────────────────┼───────────────────┼───────┤ + │ delay │ 0 │ SumList │ task0 │ + ├────────┼────────────────┼───────────────────┼───────┤ + │ b │ │ SumTask │ task1 │ + ├────────┼────────────────┼───────────────────┼───────┤ + │ delay │ 0 │ SumTask │ task1 │ + ├────────┼────────────────┼───────────────────┼───────┤ + │ a │ 10 │ SumTask │ task2 │ + ├────────┼────────────────┼───────────────────┼───────┤ + │ b │ 3 │ SumTask │ task2 │ + ├────────┼────────────────┼───────────────────┼───────┤ + │ delay │ 0 │ SumTask │ task2 │ + ├────────┼────────────────┼───────────────────┼───────┤ + │ b │ 3 │ SumTask │ task3 │ + ├────────┼────────────────┼───────────────────┼───────┤ + │ delay │ 0 │ SumTask │ task3 │ + ├────────┼────────────────┼───────────────────┼───────┤ + │ b │ 4 │ SumTask │ task4 │ + ├────────┼────────────────┼───────────────────┼───────┤ + │ delay │ 0 │ SumTask │ task4 │ + ├────────┼────────────────┼───────────────────┼───────┤ + │ delay │ 0 │ SumTask │ task5 │ + ├────────┼────────────────┼───────────────────┼───────┤ + │ b │ 6 │ SumTask │ task6 │ + ├────────┼────────────────┼───────────────────┼───────┤ + │ delay │ 0 │ SumTask │ task6 │ + ╘════════╧════════════════╧═══════════════════╧═══════╛ + +Convert Workflow Format +----------------------- + +To inspect or modify a workflow, convert it to a JSON file: .. code-block:: bash - pip install ewoks[orange] + ewoks convert demo demo.json --test -Open the test workflow in the GUI +Learn More +========== -.. code-block:: bash +.. note:: - ewoks execute test.json --engine orange + **To go further** -For a web GUI, install *ewoksserver* with the frontend + - **Create workflows in Python** -.. code-block:: bash + See the `Hello World example <./hello_world.html>`_ - pip install ewoksserver[frontend] + - **Use graphical interfaces** -Start the *ewoks* web server, open the link in a web browser and load the `test.json` file + Explore the `GUI creation tools <../howtoguides/gui.html>`_ -.. code-block:: bash + - **Need specific guidance?** + + Check the `How-to guides <../howtoguides.html>`_ + + - **Learn Ewoks step-by-step** + + The `Ewoks tutorial for developers `_ introduces all core concepts: workflows, tasks, and Ewoks tools. - ewoks-server + ℹ️ *This tutorial is regularly updated and used in ESRF training sessions.* \ No newline at end of file