CharityWorld-NL

This applet requires Java 1.4.1 or higher. You may obtain the latest Java plugin from Sun's Java site.

created with NetLogo
view/download model file: CharityWorld-NL.nlogo

We'd really appreciate it if you would be prepared to send us an e-mail just to let us know that you have some interest in our work.
That would help us a lot to justify this aspect of our research.
E-mail address: l.izquierdo@macaulay.ac.uk, or g.polhill@macaulay.ac.uk.
Thank you very much indeed!

WHAT IS IT?

CharityWorld-NL is a model designed to show the emergent effects of floating-point errors in agent-based models. This is done by showing how the model behaves dramatically differently using floating-point arithmetic and using real arithmetic.

CharityWorld-NL is a model of wealth redistribution in which a number of spatially embedded agents begin with a highly unequal distribution of wealth. This unequal distribution is then redistributed by the agents using a simple rule determining when and to whom money should be given.

CharityWorld-NL is an unofficial and reduced version of CharityWorld. CharityWorld-NL should be used for illustration purposes only. You can find the official version of CharityWorld (written in Objective-C) in http://www.macaulay.ac.uk/fearlus/floating-point/charity-world/.

HOW IT WORKS

In CharityWorld-NL, the square grid (of default size 15x15) is filled with stationary agents, one per cell. Agents are endowed with an initial wealth of 2 coins.

At the beginning of the simulation agents participate in a lottery for which they have to pay 2 coins as the ticket price. The agent at the centre of the grid happens to be the winner of the lottery so, after the lottery has taken place (i.e. after clicking on "conduct-lottery"), its wealth in coins is equal to the number of agents times 2, while the other agents' wealth is 0.

At any point in time an agent is locally rich (if and only if the agent is richer than its neighbourhood average), locally average (if and only if the agent's wealth is exactly equal to its neighbourhood average), or locally poor (if and only if the agent is poorer than its neighbourhood average). These agents have a strong craving for equality, so if they are locally rich, they are prepared to donate a coin to their neighbours who are not locally rich (an agent's neighbours are the 8 other agents with whom the agent shares an edge or a corner. Topology is toroidal). More specifically, an agent considers its neighbours in ascending order of wealth, and gives one coin to each of them (one neighbour at a time) as long as the donating agent is locally rich and the considered neighbour is not locally rich. This process is called the cycle of redistribution.

Scheduling in the model works as follows: at every time-step a locally rich agent is selected at random and told to perform a cycle of redistribution.

So, to clarify things, the first cycle of redistribution in a simulation run should consist of the lottery winner (who is the only locally rich agent right after the lottery has taken place) giving one coin to each of its neighbours (who are not locally rich). Subsequent cycles of redistribution will also be conducted by the lottery winner until one of its neighbours becomes locally rich and is selected (at random) to perform the cycle of redistribution. At that point, wealth will spread even further, eventually making other neighbouring agents locally rich, and therefore turning them into potential donors. The question is: will wealth be completely redistributed using only this simple local rule?

HOW TO USE IT

1. Choose a coin value.
This parameter determines the value of the coin used to calculate every agent's wealth.
Please realise that if the model ran without any rounding errors, then the value of the coin would not make any difference whatsoever. Using binary numbers like 0.5, 1.0, 1.5, 2.0, or any other multiple of 0.5, prevents any errors from happening. Thus, the behaviour of the model using any of those numbers is exactly the same (using the same random seed). On the contrary, using numbers like 0.1, 0.2, 0.3, 0.4, 0.6, 0.7, ... causes the appearance of rounding errors and of its undesirable consequences in the emergent properties of the model.

2. Select a type of agent.
Different types of agents use different equations to assess whether they are locally rich, average, or poor. The four equations implemented in CharityWorld-NL are all mathematically equivalent in real arithmetic, but can give different results in floating-point arithmetic.

a) "inclusive total": The two quantities that are compared are the particular agent's wealth multiplied by 9, and the total wealth in the neighbourhood (including the particular agent's wealth).

b) "inclusive mean": The two quantities that are compared are the particular agent's wealth, and the average wealth in the neighbourhood (including the particular agent's wealth in the calculation of the average).

c) "exclusive total": The two quantities that are compared are the particular agent's wealth multiplied by 8, and the total wealth in the neighbourhood (excluding the particular agent's wealth).

d) "exclusive mean": The two quantities that are compared are the particular agent's wealth, and the average wealth in the neighbourhood (excluding the particular agent's wealth in the calculation of the average).

When using coin values that prevent errors from happening (e.g. integers), the 4 algorithms above give always the same answer. Thus, runs conducted with any of them (using the same random seed) will be exactly the same. On the contrary, when using values that cause floating-point errors to happen (e.g. 0.1, 0.2, 0.3, or 0.4), each implementation gives a different result (if the model is run for long enough).

3. Use a generated random seed or, alternatively, input one.
To replicate runs, use the same random seed.

4. Click on setup.
At this point every agent will be endowed with 2 coins.

5. Click on conduct-lottery.
Every agent gives the 2 coins to the agent in the centre.

6. Click on go.
A locally rich agent is selected at random and asked to perform the cycle of redistribution.

7. Explore the two display modes.

"Absolute wealth": Each agent is coloured according to the following legend:
a) wealth > 2 * coin-value: green shades. The more wealth, the darker the shade of green.
b) wealth = 2 * coin-value: yellow.
c) wealth < 2 * coin-value: red shades. The less wealth, the darker the shade of red.
d) Blue overrides when: (wealth > 1.5 * coin-value AND wealth < 2.5 * coin-value AND wealth != 2 * coin-value). Blue will not appear in runs that do not suffer floating-poin errors.

"Relative (local) wealth": Each agent is coloured according to the following legend:
a) locally rich: green
b) locally average: yellow
c) locally poor: red

The button "update-grid" is provided to compare snapshots of the two types of graphs above that refer to the same time-step. When the model is running, the grid is updated every time-step automatically.

THINGS TO NOTICE

Under real arithmetic, it can be proved that every simulation run should behave in exactly the same way no matter the coin value or the type of agent selected (as long as the same random seed is used). It can also be proved that, under real arithmetic, every simulation run should eventually terminate with all the agents having the initial wealth of 2 coins (wealth is eventually completely redistributed irrespective of the coin value, the type of agent, or the random seed). These results can be checked using coin values that are multiples of 0.5, for which simulations run without errors.

Under floating-point arithmetic, however, the story is very different. There are many parameter values (in fact most of them) for which the coin value makes a difference, the type of agent makes a difference, and wealth is never redistributed. Some coin values that show this type of behaviour are: 0.1, 0.2, 0.3, 0.4, 0.6, 0.7, 0.8, and 0.9.

THINGS TO TRY

An immediate way of appreciating the impact of floating-point errors in this model is to choose a coin value of 0.4, set the display mode to "Relative (local) wealth", and click on set-up. At this point every agent has a wealth of 0.8, so every agent should be locally average. However, due to floating-point errors, every agent sees itself as locally rich, and therefore it would be willing to perform the cycle of redistribution! This is caused only by floating-point errors.

You can also check that when the value of the coin is a multiple of 0.5 (no floating-point errors occur), simulation runs terminate with all the wealth redistributed, and the behaviour of the model is exactly the same using any type of agent and for any of those coin values (remember to use the same random seed). On the contrary, when using a coin value of 0.4, the behaviour of the model is incorrect (it never terminates), and is dependent on the type of agent selected (but it should not be).

IMPORTANT NOTE

It is important to remark that the floating-point problems that this model illustrates are caused strictly by the use of floating point arithmetic, not by the use of Netlogo in particular. FLOATING-POINT PROBLEMS ARE BY NO MEANS SPECIFIC ONLY TO NETLOGO. NetLogo, like most programming environments, operates according to the IEEE 754 standard for floating-point arithmetic. You can expect the exact same behaviour if you implement this model in any other platform that follows the IEEE 754 standard.

EXTENDING THE MODEL

CharityWorld-NL is an unofficial and reduced version of CharityWorld. CharityWorld-NL should only be used for illustration purposes. The official version of CharityWorld, which was created by Gary Polhill and Luis Izquierdo, is more flexible and includes many extensions to this reduced version. You can find the official version of CharityWorld (written in Objective-C) in http://www.macaulay.ac.uk/fearlus/floating-point/charity-world/.

CharityWorld is written in a manner that follows a fairly standard simple Swarm model implementation, with the exception that all floating point numbers are represented using objects rather than the standard double C data type. These objects all belong to the class DoubleSimple, which contains a double instance variable, and methods to replace the arithmetic operators {+, -, *, /} and the comparison operators. Subclasses of DoubleSimple implement various techniques to deal with floating-point problems (e.g. tolerance windows, offsets, interval arithmetic, strings...), and DoubleSimple features creation methods that cause all new floating point objects to belong to one of these subclasses rather than DoubleSimple itself. The user can therefore specify which subclass of Double-Simple they wish to use throughout a particular simulation, and hence which technique will be used to manage floating point issues.

For a detailed description of CharityWorld, see:
Polhill, J.G., Izquierdo, L.R. and Gotts, N.M. (in press)
What every agent-based modeller should know about floating point arithmetic.
Environmental Modelling and Software.
http://www.sciencedirect.com/science/journal/13648152

RELATED MODELS

CharityWorld-NL is an unofficial and reduced version of CharityWorld. The official version of CharityWorld, which was created by Gary Polhill and Luis Izquierdo, is more flexible and includes many extensions to this reduced version. You can find the official version of CharityWorld (written in Objective-C) in http://www.macaulay.ac.uk/fearlus/floating-point/charity-world/.

CREDITS AND REFERENCES

CharityWorld-NL has been implemented by Luis Izquierdo. CharityWorld-NL is available online at: http://www.macaulay.ac.uk/fearlus/floating-point/charity-world-nl/

If you are interested in the effects of floating-point errors on agent-based models you might want to read the following papers:

Polhill, J.G., Izquierdo, L.R. and Gotts, N.M. (in press)
What every agent-based modeller should know about floating point arithmetic.
Environmental Modelling and Software.
http://www.sciencedirect.com/science/journal/13648152

Izquierdo, L.R. and Polhill, J.G. (2005)
Is your model susceptible to floating point errors? - and if so... does it really matter?.
In Troitzsch K.G. (ed.) Proceedings of the 3rd Annual Conference of the European Social Simulation Association.
Available upon request (l.izquierdo@macaulay.ac.uk).

Polhill, J.G., Izquierdo, L.R. and Gotts, N.M. (2005)
The ghost in the model (and other effects of floating point arithmetic).
Journal of Artificial Societies and Social Simulation 8(1).
http://jasss.soc.surrey.ac.uk/8/1/5.html

Polhill, J.G. and Izquierdo, L.R. (2005)
Lessons learned from converting the Artificial Stock Market to interval arithmetic.
Journal of Artificial Societies and Social Simulation 8(2).
http://jasss.soc.surrey.ac.uk/8/2/2.html