Bounded Loop with Range Map

What this workflow does

This workflow demonstrates the bounded loop of horus-runtime. It uses the same declarative map: construct as the fan-out showcase. It takes range: N instead of an upstream collection.

Horus creates N clones with the indices 0 to N-1. No producer stage is needed. Each clone reads its own iteration index and squares it. A gather stage sums the results.

The example is deterministic. With range: 5, the result is 0² + 1² + 2² + 3² + 4², which is 30.

The problem it solves

Some work is a fixed count of independent runs. Common cases are a replica set, a seed sweep, and a repeat count for a stochastic method. There is no collection to fan out over. The count is the input.

Without a bounded loop, you fake the collection. You write a producer stage whose only job is to emit N placeholder files. That stage is pure overhead. It also hides the real parameter, which is the count.

The range: form states the count directly in the YAML file. Horus runs the clones concurrently and gives each clone its own working directory. Each clone knows its own index, so it can pick its seed or its parameter value from it.

The fan-in is the same as the collection form. Horus places the clone outputs under <stage>.gathered/<i>/. The gather stage reads one folder. The loop is bounded, so the graph stays finite and the engine can plan the whole run in advance.

Pipeline

iterate[00..04] (map, range: 5, 5x concurrent clones, no upstream collection)
   │  each clone: reads its own iteration index, squares it
   │  ──► square.txt   (fan-in target: iterate.gathered/<i>/)

gather (local)              iterate.gathered/ (5 subfolders) ──► results/total.txt
   │  sums every clone's square.txt: 0² + 1² + 2² + 3² + 4² = 30

Inputs and outputs

Input

• None. The range: 5 field in workflow.yaml is the only input.

Outputs land in horus_workflow_results/:

• iterate.gathered/<i>/square.txt: i * i for each clone i in 0 to 4.
• results/total.txt: the sum of the five squares, 30.

Run the workflow

Install uv if you do not have it:

curl -LsSf https://astral.sh/uv/install.sh | sh

Then install the horus-runtime and run the workflow:

cd workflows/engine-showcases/w03-loop-map
uv sync
horus run workflow.yaml

You can also install the runtime with pip:

pip install horus-runtime

To change the iteration count, edit map.range on the iterate stage in workflow.yaml. The result changes predictably. It is the sum of the squares from 0 to N-1, which is (N-1) * N * (2N-1) / 6.

References

• Horus repositories