Agent ID

[Robadob]

This PR introduces agent id, will require documenting. Here's a brief summary of relevant info.

Had a brief look at docs master, but wasn't clear about the best way to fit the relevant info from this in.

Intro

Agents all contain an internal variable representing a unique identifier for the agent. This is automatically managed by FLAMEGPU2. IDs are assigned to agents at the start of a simulation, or at birth when new agents are created during the simulation. There is no method to change an agent's ID during a simulation's execution.

How IDs are handled at import/export

If agents with IDs are exported from a CUDASimulation to file or an AgentVector, their IDs will be retained when re-imported. If an ID conflict is detected when importing agents, an AgentIDCollision exception will be thrown. This can be resolved by using AgentVector::resetAllIDs() or AgentVector::Agent::resetID(), which will return IDs to an uninitialised state.

It is not currently possible to programmatically reset IDs when importing agents from file (as they cannot be loaded directly to an AgentVector). Therefore it is necessary to manually modify the xml or json file to replace any conflicting IDs.

Accessing agent IDs

Agent IDs can be accessed with the getID() method in all places where accessing an agent variable is possible (AgentVector::Agent, DeviceAPI, DeviceAPI::AgentOut, DeviceAgentVector, HostNewAgentAPI).

Type of ID

Within the C and CUDA interfaces the type of IDs is id_t, which likely maps to unsigned int. However, this may be mapped to other types in special builds which require a greater ID range. Within the python interface it is possible to add/use variables of id_t to messages, environment etc with newVariableID(). This will then update if someone rebuilds pyflamegpu with a different sized unsigned for IDs.

Checking for init ID

Agents which have not had their ID initialised will have and ID value of ID_NOT_SET (This is currently for internal usage, so may not be accessible via Python, but it evaluates to 0 and if changes will break alot of stuff.)

Submodels

Agents bound to a submodel will always have their ID bound to the submodel.

Agents within a submodel that are unbound, and therefore recreated each time the submodel is executed may have the same IDs between runs of the submodel, however this cannot be guaranteed so should not be relied on.