Skip to content

Implement a Flocking Model

Utopia Developers requested to merge 62-implement-a-flocking-model into master

This MR implements the SimpleFlocking model and expands AgentManager capabilities.

Specifically, it implements the (relatively simple) flocking model proposed by Vicsek et al., 1995, which simply updates particle orientation to the mean orientation of particles within a certain radius (plus some noise), leading to flocking phenomenology:

agents_in_domain

In the future, this model could be expanded by more elaborate mechanisms like described in Couzin et al., 2002: repulsion, field of view, and attraction.
Alternatively, the model used in Twomey et al., 2020, looks interesting as well. Similar mechanisms appear in the Boids model, which also forms the basis of the corresponding NetLogo implementation.

Is there something that needs to be double checked?

  • Model running as expected?
    • To test this, perhaps check out the results of all the configuration sets
  • Changes to core library reasonable?
  • Tests sufficient?

Can this MR be accepted?

  • Implemented the Vicsek et al. model
  • Added or adapted model tests
    • Python tests
    • C++ tests (only for some minor utility functions)
    • Added model to test:models job in .gitlab-ci.yml
    • Checked test code coverage on new and adjusted code
  • Implemented/configured plotting functions
    • Agents within domain (animated)
    • Time series plots
      • Circular mean and std. dev. of orientation
      • Only orientation of std. dev. (to assess organisation level)
      • Normalised absolute group velocity
  • Added config sets to reproduce figures from Vicsek et al., 1995, paper
  • Improved AgentManager and corresponding aspects of core library
    • Compute distance vector and distance between two agents (also across a boundary) by providing an interface to the corresponding Space methods
    • Expose RuleFunc and VoidRuleFunc types
    • Allow void rule functions for Update::sync states (somehow was not implemented)
    • Allow space.extent setup via scalar config value
    • Where possible, mark methods as const and use const references to avoid copying of arguments or return values
  • Added or adapted corresponding tests
    • AgentManager (migrated to Boost.Test and extended)
    • Space
    • Void rules for synchronous update (manually setting state_new)
  • Added documentation
    • Model itself is reasonably well documented
    • Model description in doc/models/ (.rst format!)
  • Ready for merging
    • Model requirements (see documentation) are all fulfilled
    • Reasonably up-to-date with current master
    • Pipeline passing
    • History cleaned-up or squash option set
    • Reviewed and approved

Related issues

Closes #62 (closed), #236 (closed), !189 (closed)

Edited by Utopia Developers

Merge request reports