Ammo: Replication Guides for (semi-)Dummies

I'll for one admit it. These replication guides are useable, but not very understandable.. I get the basics they teach you over at Dynamo primer and in the designscript manual, but I see Dynamites use these for much more complicated things all the time and I wonder how they figure it out..

Well, this has got to end, right?

So the post today is mostly for my own sake. Hopefully, though, someothers can also pick it up and use it to get what these suckers is all about. I will also update the post as time goes by and additional knowledge is acquired.

Just some terminology I'm gonne use first of all. I'm going to name my list levels tier 1, tier 2, tier 3 etc. this corresponds with the number inside the replication guides. If I want a object to get in the tier 2 of a list, then I would have to use the <2> guide.
Secondly just by using replication guides it means that I will pair all of the values of the lists I'm providing, like crosslacing with ordinary nodes, but now I can choose how to group them as well!

EDIT: It has just been brought to my attention that one can use an "L" inside the angle brackets to make the replication guide utilize the "longest" lacing option. Like this: Point.ByCoordinates(x<1L>,y<1L,0)

Let's start with an example:

The Points:

So here we want to draw some points based on simple one dimensional lists for X, Y and Z-values. That will be lists that got only items in Tier 1.

This is the standard result without any replication guides added.

Observe that this works just like a standard Point.ByCoordinates node with lacing set to short where the point function takes the first item in each list, creates a point, then the second item in each list, creates a point and so on.

Now, if we add a <1> behind the x in our codeblock it means that the list of X's will be put in the Tier 1 of our resulting list. But there is not entered any replication guides for Y and Z so Dynamo can't quite figure out what to do. In other words it threats Y and Z values with lacing set to short, it only takes the first item in the Y and Z lists and pair it with each of the X-values.

If we now want all the the Y-values to be in the resulting list as well, considering the Tier 1 is already composed of all the X-values, we chose to put all the Y-values in Tier 2 using the <2> guide.

Observe that we now have a grid, since we've paired all of the X and Y-values. Since Dynamo still isn't told what to do with the Z-values, it takes only the first Z-value into consideration.
If we now want all the Z-values to be included, and Tier 1 and Tier 2 is taken, we say to Dynamo that we want the Z-values at Tier 3, using the <3> guide.

Understandable?
I think many people comes this far and find it ok(ish), but what about when we start to use this on other lists containing not only numbers but different kinds of data?

We'll have a look at another example:

The Translated Points:
Ok, so I start off with a list of three lines. I want to produce two points on each line, at parameter 0.2 and at parameter 0.8.

Just a digression:
The PointAtParameter node is an action node, so I can't type
Curve.PointAtParameter(curvevariable, parametervariable)
the "curvevariable" is put to the front as the object I'm doing something with. Like this:
curvevariable.PointAtParameter(parametervariable)

This applies to most action nodes! If I where to explain the DS syntax of most action nodes , this is my best go:

Digression End.

Now I have to choose how I will Tier my resulting list. In this example Tier 1 will be my lines (Use <1> behind the crv) and Tier 2 will be my parameters (Use <2> behind the param). Observe that this is like grouping! Will I group by lines or group by parameters?

And here is just an example of where I've grouped the list by parameters instead. Notice I switched the guides.

Now lets make this even worse. I want to use the points I've created and translate each of them two times i Z-direction. Of course I could have just duplicated the translate node with different vector input in each, but with replication guides you don't have to.

Setup:

Dynamo won't know what to do here cause my points are grouped by lines (nested list) and my vectors is also in lists.
I we want to conserve the grouping by curves and points we have to "pay homage" to its list structure by including its Tiers in the replication guides. The variable geom has to be followed by <1><2>, this way the result list starts with the points list original Tiers. If we then guide the translation vectors into Tier 3, we're all set.

See? Now we have maintained the grouping of data from the beginning until the end. If I pick index 0 from our first list of lines, then picking index 0 of the last codeblock corresponds to that! I will get the 4 translated points for the first curve.

Next up I want to add the first points I created to the list with the translated points. List.Create? No, sir!

(First of all, notice that the most of the List action nodes is not like the rest. Here you have the arguments inside the paranthesis like an ordinary create node.)

Now, what do I want to do here? I want to take each of the first list's Tier 2 and add it to the second list's Tier 2. Take the input lists structure into account, and you'll get this:

So pretty neat this replication guide, eh?

There is still many mysteries to me how replication guides works, but the above summarize what my simple mind think when I use them. If it sometimes doesn't work, I start with the above and just try various combination until it works. It obviously helps a lot if you know what your output list should look like.
 Be careful with replication guides and Revit nodes, though.. If you mess it up, you're going to have RAM-issues pretty quickly, you are hereby warned...
Hopefully, someday, someone can explain the logic in full detail and so simple that anybody can understand it! And please let me know if some of the logic above is utterly wrong.