Basic Usage

Contents

Basic Usage#

Have uv? ⚡

If you have uv installed, you can instantly open this page as a Jupyter notebook using opennb:

uvx --with "pipefunc[docs]" opennb pipefunc/pipefunc/docs/source/examples/basic-usage.md

This command creates an ephemeral environment with all dependencies and launches the notebook in your browser in 1 second - no manual setup needed! ✨.

Alternatively, run:

uv run https://raw.githubusercontent.com/pipefunc/pipefunc/refs/heads/main/get-notebooks.py

to download all documentation as Jupyter notebooks.

This example demonstrates a simple pipeline using the @pipefunc decorator and the Pipeline class. It showcases a basic workflow with sequential execution.

Code#

from pipefunc import pipefunc, Pipeline

@pipefunc(output_name="c")
def f(a, b):
    return a + b

@pipefunc(output_name="d")
def g(b, c, x=1):
    return b * c * x

@pipefunc(output_name="e")
def h(c, d, x=1):
    return c * d * x

pipeline = Pipeline([f, g, h])
pipeline.visualize()
cluster_legend Legend a a f(...) → c f(...) c a->f(...) → c a b b b->f(...) → c b g(...) → d g(...) d b->g(...) → d b x x  = 1 x->g(...) → d x=1 h(...) → e h(...) e x->h(...) → e x=1 f(...) → c->g(...) → d c f(...) → c->h(...) → e c g(...) → d->h(...) → e d legend_0 Argument legend_1 PipeFunc 
pipeline  # Display the pipeline

          Pipeline Info           
╔══════════════════════╦═════════╗
║ Category             ║ Items   ║
╠══════════════════════╬═════════╣
║ required_inputs      ║ a, b    ║
║ optional_inputs      ║ x       ║
║ inputs               ║ a, b, x ║
║ intermediate_outputs ║ c, d    ║
║ outputs              ║ e       ║
╚══════════════════════╩═════════╝

result = pipeline("e", a=2, b=3)  # Or: pipeline.run("e", kwargs={"a": 2, "b": 3})
print(result)

75

Explanation#

  1. Define “Pipeable” Functions: We define three functions, f, g, and h. Each is decorated with @pipefunc, making it usable within a Pipeline. output_name assigns a name to each function’s output.

  2. Create Pipeline: A Pipeline object is created using Pipeline([f, g, h]). The order of functions in this list does not affect execution order.

  3. Visualize Pipeline: The pipeline is visualized using pipeline.visualize(). This shows the function dependencies.

  4. Execute Pipeline: The pipeline is run using pipeline("e", a=2, b=3).

    • "e" indicates that we want the output of function h (which has output_name="e").

    • a=2, b=3 provide input arguments.

    • The pipeline automatically determines the correct execution order based on function dependencies.

  5. Sequential Execution: In this example, the functions are executed sequentially based on their dependencies:

    • f(a=2, b=3) produces c=5.

    • g(b=3, c=5, x=1) produces d=15.

    • h(c=5, d=15, x=1) produces e=75.

Features Demonstrated:

  • @pipefunc: Decorator to make a function “pipeable.”

  • Pipeline: Class to create and manage a pipeline of functions.

  • Visualization using visualize().

  • Sequential execution using pipeline() (or equivalently, run()).

Further Exploration:

  • For more details on creating pipelines, see the main tutorial.

  • Already familiar with the basics? Check out the Physics Based Example for an example using some awesome pipefunc features!

Contents