Better document pipeline concepts.

[bangerth]

I've been reading my way through the documentation of the pipeline classes and noticed two things:

• All of the examples shown always use serial stages. It would be nice to have an example or two where a stage is parallel.
• TaskFlow uses a concept of "lines" in pipelines, but the truth is that I haven't quite been able to figure out what that means. I think it replicates the whole pipeline multiple times to route items/tokens down one or the other. But in truth I don't quite understand, in particular because the pipeline graphs are all meshes that also have dependencies between lines -- though there too I'm unsure because the graph doesn't make clear whether the x-axis represents lines and the y-axis the stages of a pipeline, or the other way around. It would be nice to see the concept of a "line" documented somewhere.
• TaskFlow uses somewhat unusual terminology in that the places in a pipeline where work is done are called "pipes", whereas everyone else thinks of these places as the "nodes" of a graph and the "pipes" are just the connecting edges that transport data from one node to another. That's also how the task graphs are visualized. But in TaskFlow, the "pipes" are the nodes of the graph, not the edges. All of that is fine -- it's just terminology -- but it would be nice to explain these concepts in a central place.

[tsung-wei-huang]

Hi @bangerth thank you for your suggestions. I will take that in mind to improve the doc. When we design the pipeline, we didn't know how to exactly match each pipe to a task, and that's why we tried not to mix those terms (pipe, node) together. In fact, the underlying implementation is based on condition-task and composition, but this of course should be transparent to users.

[bangerth]

@tsung-wei-huang I understand.

Would you mind explaining (or linking to a description) of what a "line" is in a pipeline? I could not figure that out from the documentation or the examples.

[tsung-wei-huang]

Hi @bangerth , line means the parallelism of your pipeline program. If you have four lines, then taskflow will use four tasks to build your pipeline structure, which goes to a parallelism of 4 threads. The scheduling runs in a circular fashion like the first figure here