Message Wrapping about docs

[Robadob]

I think this might be incorrect, based on research i did previously. tldr: Out of bounds agents are mapped to the the far cell, wrapped proceeds no further. ------------------------------ Doing deeper validation now and looking at individual particles, rather than my more abstract PBM matching a few weeks ago. I’ve been trying to match a model with 20 particles across an environment of 2x2x2 bins. added a counter to output how many message each agent iterates, and noticed that despite there only being 20 agents (and messages), most FLAME agents are accessing 70+ messages. Looking at FLAMEGPU_kernals it is quite clear this is due to the ‘bounding’ within message_location_hash() being a weird form of wrapping, rather than clamping. (Weird because it sets anything that exceeds an edge to equal the far edge, rather than relative to the far edge). //cheap bounding without mod (within range +- partition dimension) gridPos.x = (gridPos.x<0)? d_message_location_partitionDim.x-1: gridPos.x; gridPos.x = (gridPos.x>=d_message_location_partitionDim.x)? 0 : gridPos.x; gridPos.y = (gridPos.y<0)? d_message_location_partitionDim.y-1 : gridPos.y; gridPos.y = (gridPos.y>=d_message_location_partitionDim.y)? 0 : gridPos.y; gridPos.z = (gridPos.z<0)? d_message_location_partitionDim.z-1: gridPos.z; gridPos.z = (gridPos.z>=d_message_location_partitionDim.z)? 0 : gridPos.z; A comment in the above function also makes the distinction between wrapping and bounding, hence I’m unsure if this behaviour was intended as I don’t recall seeing wrapping ever documented with regards to FLAME (I realise that the tiny environment would exacerbate such an issue). Additionally this wrapping leads to agents in reading more messages than necessary.

…

------------------------------ Paul’s response at the time was: Perhaps a case of bad documentation. All environments are wrapped. It is up-to the flame function to avoid wrapping through explicit distance checking (which is always required anyway) if non wrapped environments are required. It would probably be better if this was a configurable option for each message. and it was taken no further.

[ptheywood]

I have an example of a 4 x 4 x 4 world, with 16 discrete and 16 continuous agents.

The agents are arranged in a grid on the 0 Z plane, at (0,0), (0, 1), etc.

With radius 1 discrete messaging, all agents read 8 discrete messages - it must wrap (and ignores itself).
With spatially partitioned messaging with a radius 1, all agents read 9 messages, including those at the edge.
With spatially partitioned messaging with a radius 4 (i.e 1 bin), all agents read 144 messages (16 * 9).

All agents are in bounds, although I have not checked bin counts manually.

[Robadob]

Check whether the generated code matches that I posted above. If it hasn't been changed, it's not technically wrapping or clamping, it's a mish mash inbetween and should be declared undefined behaviour.

Proper wrapping would require use of the modulo operator. And as the C modulo operator doesn't act as a continuous function across 0 (it instead mirrors), you would need to then do further arithmetic of GridDim - (partitionDim%GridDim) if partitionDim began as <0 (iirc).

[ptheywood]

The generated code is the same as above.

For the reading of messages in spatially partitoned messaging where only the moores neighbourhood is considered this is correctly wrapping.
Writing out of the environment bounds is clamped to the bin, but writing out of bounds is effectively undefined behaviour - it shouldn't really be happening.

Discrete messages are wrapped via

#define sWRAP(x,m) (((x)<m)?(((x)<0)?(m+(x)):(x)):(m-(x))) /**<signed integer wrap (no modulus) for negatives where 2m > |x| > m */

Which looks like it should be fine for all sensible radii values. Not sensible values (ie. a radius larger than the environment) is effectively an invalid configuration and is undefined / should be not allowed realistically.

[ptheywood]

Spatially Partitioned Messaging

• Document that spatial partitioning must result in environments of > 3 bins in the X and Y dimensions or an error will occur
  • In this case the user should just use brute-force messaging
• Document that spatially partitioned messages wrap in the X,Y dimensions to form a torus
• Document that outputting a spatially partitioned message outside of the environment bounds is undefined behaviour.
  • This is currently clamped but this should not be relied upon.

Discrete Partitioned Messages

• Document that radii should be less than or equal to floor((width - 1) / 2) - to avoid reading the same message multiple times, where width is the sqrt(bufferSize)
• Document that messages wrap in the X Y dimensions, forming a torus.
• Document that outputting a message with X Y dimensions out of range is undefined behaviour.