{ "metadata": { "kernelspec": { "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.12.8" } }, "nbformat_minor": 5, "nbformat": 4, "cells": [ { "id": "982a4fbe-7cf9-45dd-84ae-9854149db0b9", "cell_type": "markdown", "source": "# jobflow", "metadata": {} }, { "id": "e6180712-d081-45c7-ba41-fc5191f10427", "cell_type": "markdown", "source": "## Define workflow with jobflow\n\nThis tutorial will demonstrate how to use the PWD with `jobflow` and load the workflow with `aiida` and `pyiron`.\n\n[`jobflow`](https://joss.theoj.org/papers/10.21105/joss.05995) was developed to simplify the development of high-throughput workflows. It uses a decorator-based approach to define the “Job“s that can be connected to form complex workflows (“Flow“s). `jobflow` is the workflow language of the workflow library [`atomate2`](https://chemrxiv.org/engage/chemrxiv/article-details/678e76a16dde43c9085c75e9), designed to replace [atomate](https://www.sciencedirect.com/science/article/pii/S0927025617303919), which was central to the development of the [Materials Project](https://pubs.aip.org/aip/apm/article/1/1/011002/119685/Commentary-The-Materials-Project-A-materials) database.", "metadata": {} }, { "id": "69bedfb9ec12c092", "cell_type": "markdown", "source": "First, we start by importing the job decorator and the Flow class from jobflow, as welll as the necessary modules from the python workflow definition and the example arithmetic workflow.", "metadata": { "collapsed": false, "jupyter": { "outputs_hidden": false } } }, { "id": "000bbd4a-f53c-4eea-9d85-76f0aa2ca10b", "cell_type": "code", "source": "from jobflow import job, Flow", "metadata": { "ExecuteTime": { "end_time": "2025-04-24T12:51:34.747117656Z", "start_time": "2025-04-24T12:51:33.203979325Z" }, "trusted": true }, "outputs": [], "execution_count": 1 }, { "id": "06c2bd9e-b2ac-4b88-9158-fa37331c3418", "cell_type": "code", "source": "from python_workflow_definition.jobflow import write_workflow_json", "metadata": { "trusted": true }, "outputs": [], "execution_count": 2 }, { "id": "f9217ce7b093b5fc", "cell_type": "code", "source": "from workflow import (\n get_sum as _get_sum,\n get_prod_and_div as _get_prod_and_div,\n get_square as _get_square,\n)", "metadata": { "trusted": true }, "outputs": [], "execution_count": 3 }, { "id": "2639deadfae9c591", "cell_type": "markdown", "source": "Using the job object decorator, the imported functions from the arithmetic workflow are transformed into jobflow “Job”s. These “Job”s can delay the execution of Python functions and can be chained into workflows (“Flow”s). A “Job” can return serializable outputs (e.g., a number, a dictionary, or a Pydantic model) or a so-called “Response” object, which enables the execution of dynamic workflows where the number of nodes is not known prior to the workflow’s execution. ", "metadata": { "collapsed": false, "jupyter": { "outputs_hidden": false } } }, { "id": "1feba0898ee4e361", "cell_type": "code", "source": "workflow_json_filename = \"jobflow_simple.json\"", "metadata": { "ExecuteTime": { "end_time": "2025-04-24T10:30:04.751088Z", "start_time": "2025-04-24T10:30:04.748941Z" }, "trusted": true }, "outputs": [], "execution_count": 4 }, { "id": "07598344-0f75-433b-8902-bea21a42088c", "cell_type": "code", "source": "get_sum = job(_get_sum)\n# Note: one could also transfer the outputs to the datastore as well: get_prod_and_div = job(_get_prod_and_div, data=[\"prod\", \"div\"])\n# On the way from the general definition to the jobflow definition, we do this automatically to avoid overflow databases.\nget_prod_and_div = job(_get_prod_and_div)\nget_square = job(_get_square)", "metadata": { "trusted": true }, "outputs": [], "execution_count": 5 }, { "id": "ecef1ed5-a8d3-48c3-9e01-4a40e55c1153", "cell_type": "code", "source": "prod_and_div = get_prod_and_div(x=1, y=2)", "metadata": { "trusted": true }, "outputs": [], "execution_count": 6 }, { "id": "2b88a30a-e26b-4802-89b7-79ca08cc0af9", "cell_type": "code", "source": "tmp_sum = get_sum(x=prod_and_div.output.prod, y=prod_and_div.output.div)", "metadata": { "trusted": true }, "outputs": [], "execution_count": 7 }, { "id": "8d95c3aa", "cell_type": "code", "source": "result = get_square(x=tmp_sum.output)", "metadata": { "trusted": true }, "outputs": [], "execution_count": 8 }, { "id": "a5e5ca63-2906-47c9-bac6-adebf8643cba", "cell_type": "code", "source": "flow = Flow([prod_and_div, tmp_sum, result])", "metadata": { "trusted": true }, "outputs": [], "execution_count": 9 }, { "id": "27688edd256f1420", "cell_type": "markdown", "source": "As jobflow itself is only a workflow language, the workflows are typically executed on high-performance computers with a workflow manager such as [Fireworks](https://onlinelibrary.wiley.com/doi/full/10.1002/cpe.3505) or [jobflow-remote](https://github.com/Matgenix/jobflow-remote). For smaller and test workflows, simple linear, non-parallel execution of the workflow graph can be performed with jobflow itself. All outputs of individual jobs are saved in a database. For high-throughput applications typically, a MongoDB database is used. For testing and smaller workflows, a memory database can be used instead.", "metadata": { "collapsed": false, "jupyter": { "outputs_hidden": false } } }, { "id": "e464da97-16a1-4772-9a07-0a47f152781d", "cell_type": "code", "source": "write_workflow_json(flow=flow, file_name=workflow_json_filename)", "metadata": { "trusted": true }, "outputs": [], "execution_count": 10 }, { "id": "bca646b2-0a9a-4271-966a-e5903a8c9031", "cell_type": "code", "source": "!cat {workflow_json_filename}", "metadata": { "trusted": true }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": "{\n \"version\": \"0.1.0\",\n \"nodes\": [\n {\n \"id\": 0,\n \"type\": \"function\",\n \"value\": \"workflow.get_prod_and_div\"\n },\n {\n \"id\": 1,\n \"type\": \"function\",\n \"value\": \"workflow.get_sum\"\n },\n {\n \"id\": 2,\n \"type\": \"function\",\n \"value\": \"workflow.get_square\"\n },\n {\n \"id\": 3,\n \"type\": \"input\",\n \"name\": \"x\",\n \"value\": 1\n },\n {\n \"id\": 4,\n \"type\": \"input\",\n \"name\": \"y\",\n \"value\": 2\n },\n {\n \"id\": 5,\n \"type\": \"output\",\n \"name\": \"result\"\n }\n ],\n \"edges\": [\n {\n \"target\": 0,\n \"targetPort\": \"x\",\n \"source\": 3,\n \"sourcePort\": null\n },\n {\n \"target\": 0,\n \"targetPort\": \"y\",\n \"source\": 4,\n \"sourcePort\": null\n },\n {\n \"target\": 1,\n \"targetPort\": \"x\",\n \"source\": 0,\n \"sourcePort\": \"prod\"\n },\n {\n \"target\": 1,\n \"targetPort\": \"y\",\n \"source\": 0,\n \"sourcePort\": \"div\"\n },\n {\n \"target\": 2,\n \"targetPort\": \"x\",\n \"source\": 1,\n \"sourcePort\": null\n },\n {\n \"target\": 5,\n \"targetPort\": null,\n \"source\": 2,\n \"sourcePort\": null\n }\n ]\n}" } ], "execution_count": 11 }, { "id": "65389ef27c38fdec", "cell_type": "markdown", "source": "Finally, you can write the workflow data into a JSON file to be imported later.", "metadata": { "collapsed": false, "jupyter": { "outputs_hidden": false } } }, { "id": "87a27540-c390-4d34-ae75-4739bfc4c1b7", "cell_type": "markdown", "source": "## Load Workflow with aiida\n\nIn this part, we will demonstrate how to import the `jobflow` workflow into `aiida` via the PWD.", "metadata": {} }, { "id": "66a1b3a6-3d3b-4caa-b58f-d8bc089b1074", "cell_type": "code", "source": "from aiida import load_profile\n\nload_profile()", "metadata": { "trusted": true }, "outputs": [ { "execution_count": 12, "output_type": "execute_result", "data": { "text/plain": "Profile" }, "metadata": {} } ], "execution_count": 12 }, { "id": "4679693b-039b-45cf-8c67-5b2b3d705a83", "cell_type": "code", "source": "from python_workflow_definition.aiida import load_workflow_json", "metadata": { "trusted": true }, "outputs": [], "execution_count": 13 }, { "id": "cc7127193d31d8ef", "cell_type": "markdown", "source": "We import the necessary modules from `aiida` and the PWD, as well as the workflow JSON file.", "metadata": { "collapsed": false, "jupyter": { "outputs_hidden": false } } }, { "id": "68c41a61-d185-47e8-ba31-eeff71d8b2c6", "cell_type": "code", "source": "wg = load_workflow_json(file_name=workflow_json_filename)\nwg", "metadata": { "trusted": true }, "outputs": [ { "execution_count": 14, "output_type": "execute_result", "data": { "text/plain": "NodeGraphWidget(settings={'minimap': True}, style={'width': '90%', 'height': '600px'}, value={'name': 'WorkGra…", "application/vnd.jupyter.widget-view+json": { "version_major": 2, "version_minor": 1, "model_id": "9f822f7ac5ca4cb9960374af471f79cf" } }, "metadata": {} } ], "execution_count": 14 }, { "id": "4816325767559bbe", "cell_type": "markdown", "source": "Finally, we are now able to run the workflow with `aiida`.", "metadata": { "collapsed": false, "jupyter": { "outputs_hidden": false } } }, { "id": "05228ece-643c-420c-8df8-4ce3df379515", "cell_type": "code", "source": "wg.run()", "metadata": { "trusted": true }, "outputs": [ { "name": "stderr", "output_type": "stream", "text": "05/24/2025 05:38:40 AM <306> aiida.orm.nodes.process.workflow.workchain.WorkChainNode: [REPORT] [3|WorkGraphEngine|continue_workgraph]: tasks ready to run: get_prod_and_div1\n05/24/2025 05:38:41 AM <306> aiida.orm.nodes.process.workflow.workchain.WorkChainNode: [REPORT] [3|WorkGraphEngine|update_task_state]: Task: get_prod_and_div1, type: PyFunction, finished.\n05/24/2025 05:38:41 AM <306> aiida.orm.nodes.process.workflow.workchain.WorkChainNode: [REPORT] [3|WorkGraphEngine|continue_workgraph]: tasks ready to run: get_sum2\n05/24/2025 05:38:41 AM <306> aiida.orm.nodes.process.workflow.workchain.WorkChainNode: [REPORT] [3|WorkGraphEngine|update_task_state]: Task: get_sum2, type: PyFunction, finished.\n05/24/2025 05:38:41 AM <306> aiida.orm.nodes.process.workflow.workchain.WorkChainNode: [REPORT] [3|WorkGraphEngine|continue_workgraph]: tasks ready to run: get_square3\n05/24/2025 05:38:42 AM <306> aiida.orm.nodes.process.workflow.workchain.WorkChainNode: [REPORT] [3|WorkGraphEngine|update_task_state]: Task: get_square3, type: PyFunction, finished.\n05/24/2025 05:38:42 AM <306> aiida.orm.nodes.process.workflow.workchain.WorkChainNode: [REPORT] [3|WorkGraphEngine|continue_workgraph]: tasks ready to run: \n05/24/2025 05:38:42 AM <306> aiida.orm.nodes.process.workflow.workchain.WorkChainNode: [REPORT] [3|WorkGraphEngine|finalize]: Finalize workgraph.\n" } ], "execution_count": 15 }, { "id": "2c942094-61b4-4e94-859a-64f87b5bec64", "cell_type": "markdown", "source": "## Load Workflow with pyiron_base\n\nIn this part, we will demonstrate how to import the `jobflow` workflow into `pyiron` via the PWD.", "metadata": {} }, { "id": "ea102341-84f7-4156-a7d1-c3ab1ea613a5", "cell_type": "code", "source": "from python_workflow_definition.pyiron_base import load_workflow_json", "metadata": { "trusted": true }, "outputs": [], "execution_count": 16 }, { "id": "8f2a621d-b533-4ddd-8bcd-c22db2f922ec", "cell_type": "code", "source": "delayed_object_lst = load_workflow_json(file_name=workflow_json_filename)\ndelayed_object_lst[-1].draw()", "metadata": { "trusted": true }, "outputs": [ { "output_type": "display_data", "data": { "text/plain": "", "image/svg+xml": "\n\n\n\n\ncreate_function_job_25906340bd0c28c44fd73d69e7a3d8bc\n\ncreate_function_job=<pyiron_base.project.delayed.DelayedObject object at 0x733f400d1310>\n\n\n\nx_1a7fff02f6473a13e5e8742988186611\n\nx=<pyiron_base.project.delayed.DelayedObject object at 0x733f40ddb0e0>\n\n\n\nx_1a7fff02f6473a13e5e8742988186611->create_function_job_25906340bd0c28c44fd73d69e7a3d8bc\n\n\n\n\n\nx_e4655695917c433de56d1c64232473f9\n\nx=<pyiron_base.project.delayed.DelayedObject object at 0x733f4db8caa0>\n\n\n\nx_e4655695917c433de56d1c64232473f9->x_1a7fff02f6473a13e5e8742988186611\n\n\n\n\n\nx_1d847da32ecaabf6731c38f798c3d4ce\n\nx=1\n\n\n\nx_1d847da32ecaabf6731c38f798c3d4ce->x_e4655695917c433de56d1c64232473f9\n\n\n\n\n\ny_3b83397feef07a74d9a046a1b7f57749\n\ny=<pyiron_base.project.delayed.DelayedObject object at 0x733f4ed91130>\n\n\n\nx_1d847da32ecaabf6731c38f798c3d4ce->y_3b83397feef07a74d9a046a1b7f57749\n\n\n\n\n\ny_3b83397feef07a74d9a046a1b7f57749->x_1a7fff02f6473a13e5e8742988186611\n\n\n\n\n\ny_a9ec4f5f33f0d64e74ed5d9900bceac6\n\ny=2\n\n\n\ny_a9ec4f5f33f0d64e74ed5d9900bceac6->x_e4655695917c433de56d1c64232473f9\n\n\n\n\n\ny_a9ec4f5f33f0d64e74ed5d9900bceac6->y_3b83397feef07a74d9a046a1b7f57749\n\n\n\n\n" }, "metadata": {} } ], "execution_count": 17 }, { "id": "cf80267d-c2b0-4236-bf1d-a57596985fc1", "cell_type": "code", "source": "delayed_object_lst[-1].pull()", "metadata": { "trusted": true }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": "The job get_prod_and_div_00cf2c787390eacfbc4a51e9a0c38ec7 was saved and received the ID: 1\nThe job get_sum_4b5b9d16b259a13b6a32798ce2779af8 was saved and received the ID: 2\nThe job get_square_9cc2f0545498916d7720c59c1120a66d was saved and received the ID: 3\n" }, { "execution_count": 18, "output_type": "execute_result", "data": { "text/plain": "6.25" }, "metadata": {} } ], "execution_count": 18 }, { "id": "9414680d1cbc3b2e", "cell_type": "markdown", "source": "Here, the procedure is the same as before: Import the necessary `pyiron_base` module from the PWD, import the workflow JSON file and run the workflow with pyiron.", "metadata": { "collapsed": false, "jupyter": { "outputs_hidden": false } } }, { "metadata": {}, "cell_type": "markdown", "source": "## Load Workflow with pyiron_workflow", "id": "7da4733bfeffee63" }, { "metadata": {}, "cell_type": "code", "outputs": [], "execution_count": null, "source": "from python_workflow_definition.pyiron_workflow import load_workflow_json", "id": "6c87661996ff840b" }, { "metadata": {}, "cell_type": "code", "outputs": [], "execution_count": null, "source": "wf = load_workflow_json(file_name=workflow_json_filename)", "id": "33b1e9408924f9c0" }, { "metadata": {}, "cell_type": "code", "outputs": [], "execution_count": null, "source": "wf.draw(size=(10,10))", "id": "df63b2963a0d90a5" }, { "metadata": {}, "cell_type": "code", "outputs": [], "execution_count": null, "source": "wf.run()", "id": "bf110395454bd694" } ] }