scottpdo/flocc

Agent-based modeling in JavaScript in the browser or on the server.

Flocc

Agent-based modeling in JavaScript. Run it in the browser to build interactive simulations that can live on public websites, or on the server or your machine for more computationally intensive modeling.

Usage

The recommended method is to install and import flocc as a module.

// Using ES6 `import` syntax:
import flocc from 'flocc';

// Or ES5 `require`
const flocc = require('flocc');

You can also import just the classes you need:

import { Agent, Environment } from 'flocc';

If you're running flocc in browser, and don't want to bother with imports and build process, you can download the top-level flocc.js file and include it on your page:

<script src="/flocc.js"></script>

<script>
    const agent = new flocc.Agent();
</script>

Documentation

Visit the documentation site for complete documentation

flocc's Issues

KDTree bug

KDTrees occasionally enter an infinite loop when rebalancing.

Unfortunately it appears inconsistent, but probably has to do with specific agent positions and the median comparing them to. Can occasionally (rarely) be seen in the Flocking model: https://codesandbox.io/s/flocking-vw76q

Difficulty in visualizing a simple basic netowork

Describe the bug
Working off the NetWork example.
Attempting to visualize a simple network
I can see I am generating the agents but cannot see them on the frame.
what am I missing? - Thanks.

code below:
const {Agent,Environment,CanvasRenderer,utils,Network,LineChartRenderer} = flocc;
const nodeNum = 10;
const environment = new Environment();
const network = new Network();
environment.use(network);

const renderer = new CanvasRenderer(environment, {
autoPosition: true,
background:'#eee',
width: 500,
height: 500
});
renderer.mount("#container");

function setup(){
// get some agents
for (let i = 0; i < nodeNum; i++){
const agent = new Agent();
agent.set('size', 5);
agent.set('color','#F00');
//agent.addRule(tick);
// add a few edges
network.connect(network.get(1),network.get(2));
network.connect(network.get(2),network.get(5));
network.connect(network.get(0),network.get(0));
network.connect(network.get(2),network.get(7));
//
environment.addAgent(agent);
network.addAgent(agent);
}

}
function draw() {
//environment.tick();
requestAnimationFrame(draw);
}
setup();
console.log(network.agents);
draw();

Desktop (please complete the following information):

• OS: Ubuntu 14.04

• Browser Google Chrome 74.0.3729.157

• Version [e.g. 22]
  .

developping locally

Hi Scott,

thanks for the awesome package.
I am not very experienced with js in case this is obvious:

I have tweaked the example in the code sandbox, but now i want to develop locally to merge with the rest of my script. In the readme, you write "you can download the top-level flocc.js file and...". i have downloaded the latest release and I cannot locate the said file. I have placed the entire folder in the my src folder, but it does not work – is it the CORS blocking it?

Thanks,
Panos

Let's have Networks and Terrains automatically sync with all Agents in their Environment

^ Pretty self-explanatory...

Instead of having their own .addAgent methods, Networks and Terrains, when constructed with an Environment, should just point their .agents array at the Environment's. Then when the Environment adds or removes Agents, they will automatically be synced to the helper in question.

In addition to updating the constructors, Environment's .addAgent and .removeAgent methods will need to be updated to do any cleanup/updates in the helpers (for example, if removing an Agent that has connections in the Network, remove those connections).

Since this will involve API changes, probably should go under a new major release 0.6.0.

Array methods, lambdas for rules

• map ['map', [1, 2, 3], ['subtract', 1]]; // [0, 1, 2]
  • First value after operator interpreted as array, not evaluated as step. Second value after operator interpreted as lambda with each value of array as its first value and it's second value applied to array elements.
• filter ['filter', [1, 2, 3], ['gt', 1]]; // [2, 3]
• reduce
• sort

Histogram buckets for discrete values

Allow Histogram buckets option to take an array of numbers, e.g. [1, 5, 10] that acts as both the number of buckets (here, 3), and the discrete values (as opposed to ranges of values) to be bucketed.

Might also benefit from a epsilon option (or similar) to target values that are within a given amount (say, 0.01) of the given bucket values.

Histogram improvements

Finish belowMin and aboveMax config options and values these additional buckets.

Allow ability to change # of buckets displayed (dynamically?), through a .rebucket(n) method or something similar.

Fix JSDoc declaration for `Terrain.neighbors`

Currently shows the (incorrect) parameters for GridEnvironment.neighbors, not Terrain.neighbors:
https://github.com/o-p-e-n-s-e-t/flocc/blob/c5f792f9d3cca0b211008b9b6996f8ab22b7a243/src/helpers/Terrain.ts#L180

CanvasRenderer + Network connection drawing issue

CanvasRenderers should draw all connections and then draw all agents, not draw them at the same time. Can use a buffer canvas for connections/agents and then merge.

Cannot change color of agents

Describe the bug
A clear and concise description of what the bug is.

Working off the flocking example seek to change color of agents when they are close and reset when the distance. I cannot get to change the color of the agents, and I am getting an error on the console saying the color is None.
Please advise, what I am doing wrong. Attaching code and screen shot. The agents are very close but color does not change. (Ubuntu 14.04, Mozilla Firefox 66.0.3)

`const { Agent, Environment, GridEnvironment, ASCIIRenderer, CanvasRenderer, utils, Vector } = flocc;

/* ------- PARAMETERS --------- */

const flockSize = 10;
const width = 300;
const height = 300;

/* ---------------------------- */

/* ------- SET UP ENVIRONMENT, RENDERER --------- */

const environment = new Environment();
const renderer = new CanvasRenderer(environment, { width, height });
const container = document.getElementById('container');
console.log(container)
renderer.mount(container);

function setup() {
for (let i = 0; i < flockSize; i++) {
const agent = new Agent();
agent.set('x', 0.25 * Math.random() * width);
agent.set('y', 0.25 * Math.random() * height);
agent.set('shape', 'arrow');
agent.set('color', '#0F0');
agent.set('size', 3);
const angle = 2 * Math.random() * Math.PI;
agent.set('vx', Math.cos(angle));
agent.set('vy', Math.sin(angle));

agent.addRule(tick);

environment.addAgent(agent);

}

}

function tick(agent) {
var x = agent.get('x');
var y = agent.get('y');
x += agent.get('vx');
y += agent.get('vy');

while (x < 0) x += width;
while (x >= width) x -= width;
while (y < 0) y += height;
while (y >= height) y -= height;

agent.set('x', x);
agent.set('y', y);

// update color if the agents are close

environment.getAgents().forEach(function(x){
console.log(x.get('color'))
})

environment.getAgents().filter(function(other){
var d = utils.distance(agent,other);

if ( d<=60 & d >0 ){
        other.set('color','red');
        agent.set('color','green');
  
} else {
        other.set('color','blue');
        agent.set('color','blue');
}

});

}

function render() {
environment.tick();
requestAnimationFrame(render);
}

setup();
render();
`

To Reproduce
Steps to reproduce the behavior:

1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error

Expected behavior
A clear and concise description of what you expected to happen.

Screenshots
If applicable, add screenshots to help explain your problem.

Desktop (please complete the following information):

• OS: [e.g. iOS]
• Browser [e.g. chrome, safari]
• Version [e.g. 22]

Smartphone (please complete the following information):

• Device: [e.g. iPhone6]
• OS: [e.g. iOS8.1]
• Browser [e.g. stock browser, safari]
• Version [e.g. 22]

Additional context
Add any other context about the problem here.

Calling environment.set(data) when subclassing doesn't set data

Example:

const env = new Environment({
  test: "123"
});
env.get("test"); // returns null

It does work if you call set separately:

const env = new Environment();
env.set({
  test: "123"
});
env.get("test"); // returns "123"

Network should safely handle `.neighbors(agent)` call when `agent` is not in network

Currently throws an error if agent.id is not present in the Network's data member.
https://github.com/o-p-e-n-s-e-t/flocc/blob/c5f792f9d3cca0b211008b9b6996f8ab22b7a243/src/helpers/Network.ts#L196

TypeScript improvements

• The callback passed to Terrain .addRule can return number, Pixel, or void
• Don't have to pass every key-value pair in Terrain options
• Don't have to pass every key-value pair in LineChartRenderer options
• Type-check CanvasRenderer options
• Type-check Environment options

Terrain.load can't be used from server side nodejs simulation

Describe the bug
Terrain.load is dependent on the DOM
const img = document.createElement("img");
so it won't work when running a server side model without a web browser.

To Reproduce
Steps to reproduce the behavior:

1. run the model headless in a nodejs app
2. create a terrain and attempt to load a local image using the path, as described in function comments
3. get error as document object not found

Expected behavior
need example on how to use this from nodjs rather than browser. I'm using a terrain image to model a complex environment for an ABM

Desktop (please complete the following information):
node v14.15.1
flocc v0.15.19

great project! thanks for all the work on this.

0.3.14 ideas

• Add percentile utility function. Use linear interpolation between adjacent values (like utils.median). These should be equivalent:

  utils.percentile(arr, 0) === utils.min(arr);
  utils.percentile(arr, 0.5) === utils.median(arr);
  utils.percentile(arr, 1) === utils.max(arr);

• Add environment.stat('key') to get array of data associated with agent.get('key'). Shorthand for environment.getAgents().map(a => a.get('key'))

• Add environment.memo(value) or environment.memo(function) to cache a value until the next tick. Ex. environment.memo(environment.stat('x'))

Histogram: Multiple Metrics

Histograms would be more useful if they could visualize multiple metrics, like this:

Heatmaps!

Heatmaps would be a great way to show correlation between two metrics. API might be:

new Heatmap({
  x: "key1",
  y: "key2",
});

with defaults for width, height, # of buckets for x/y, range for x/y, color range, and whether range is absolute or relative (à la Histogram bar heights). Dimensions and scale seems obvious, but how to set buckets and x/y ranges and color range?