### Mathematical operators

Meaning | Example | |
---|---|---|

+ | Add | pop.size + otherpop.size |

– | Subtract | dominance – 10 |

* | Multiply | elevation * .01 |

/ | Divide | rainfall / 10 |

% | Mod | something % 5 |

^ | Exponential | biomass ^ 1.01 |

= | Equals (returns 1 if equal, 0 otherwise) | shore = 6 |

!= | Not equals (return 1 if unequal, 0 otherwise) | shore != 6 |

> | Greater than (returns 1 is greater than, 0 otherwise) | size > 1000 |

< | Less than (returns 1 if less than, 0 otherwise) | capdistance < 5 |

and | Logical AND – returns 1 if true, 0 if false | size > 1000 and capdistance < 5 |

or | Logical OR – return 1 if true, 0 if false | dominance > 10 or size < 1000 |

xor | Logical EXCLUSIVE OR – returns 1 if true, 0 if false | Capdistance > 5 or shore = 6 |

### Mathematical functions

Meaning | Example | |
---|---|---|

positive(x) | Take positive value, or 0 | positive(-100) => 0 positive(100) => 100 |

plusminus(x) | Random value plus or minus X | plusminus(3) => [-3,-2,…. 3] |

absolute(x) | Absolute value of x | absolute(-100) => 100 |

chance(x) | A 1 in X chance of returning 1, else 0 | chance(1000) => |

root(x, y) | The y’th root of x | root(x, 2) => square root of x |

min(x, y) | The smaller value of x and y | min(3,2) => 2 |

max(x, y) | The greater value of x and y | max(2,3) => 3 |

range(x, y, z) | Returns x, unless outside the bounds of y and z | range(5, 1,10) => 5 range(-10, 1, 10) => 10 range(20, 1, 10) => 20 |

if(x, y, z) | If x <> 0, then returns y. Otherwise returns z. | if (1 > 2, 100, 0) => 0 if (1 < 2, 100, 0) => 100 |

avg(x,y) | The average between x and y | avg(1,3) => 2 |

wavg(x,y,z,w) | The average between x and y, weighted by z and w. (usually used to weight averages by sizes) | wavg(pop.value, otherpop.value, pop.size, otherpop.size) |

proportion(x,y,z) | The value “z” the way between x and y | proportion(0, 10, 0) => 0 proportion(0, 10, .5) => 5 proportion(0, 10, 1) => 10 |

round(x) | Rounds the value to the nearest whole number | round(.8) => 1 round(.2) => 0 |

trend(x,y,z) | Returns the value as if x was trending to y over z turns | trend(0,10,20) => .5 trend(0,10,5) => 2 trend(0,10,2) => 5 |

### Objects available in each type of formula

##### Population update formulas

Meaning | Example | |
---|---|---|

(default) | The population | size, dominance, capdistance |

idtotal | The total values of all populations in the population’s identity | Idtotal.size |

idavg | The average values of all populations in the population’s identity (size weighted) | Idavg.capdistance |

hex | The hex the population is in | hex.elevation, hex.terrain |

hextotal | The total values of the populations in the hex | hextotal.size |

hexavg | The average values of the populations in the hex (weighted by size) | hexavg.dominance |

##### Population merge formulas

Meaning | Example | |
---|---|---|

(default) | The dominant population in the merge | size, dominance, capdistance |

idtotal | The total values of all populations in the population’s identity | Idtotal.size |

idavg | The average values of all populations in the population’s identity (size weighted) | Idavg.capdistance |

hex | The hex the population is in | hex.elevation, hex.terrain |

hextotal | The total values of the populations in the hex | hextotal.size |

hexavg | The average values of the populations in the hex (weighted by size) | hexavg.dominance |

otherpop | The other, non-dominant population in the merge | otherpop.size, otherpop.dominance |

##### Cell initial formulas

Meaning | Example | |
---|---|---|

(default) | The cell | terrain, rainfall, etc |

##### Cell update formulas

Meaning | Example | |
---|---|---|

(default) | The cell | terrain, rainfall, etc |

##### Split formula

Meaning | Example | |
---|---|---|

(default) | The population | size, dominance, capdistance |

idtotal | The total values of all populations in the population’s identity | Idtotal.size |

idavg | The average values of all populations in the population’s identity (size weighted) | Idavg.capdistance |

hex | The hex the population is in | hex.elevation, hex.terrain |

hextotal | The total values of the populations in the hex | hextotal.size |

hexavg | The average values of the populations in the hex (weighted by size) | hexavg.dominance |

##### Join formula

Meaning | Example | |
---|---|---|

(default) | The dominant population being considered for the join | size, dominance, capdistance |

otherpop | The non-dominant population being considered for the join | otherpop.size, otherpop.dominance |

##### Migrate potential & percentage formulas

Meaning | Example | |
---|---|---|

(default) | The dominant population in the merge | size, dominance, capdistance |

idtotal | The total values of all populations in the population’s identity | Idtotal.size |

idavg | The average values of all populations in the population’s identity (size weighted) | Idavg.capdistance |

hex | The hex the population is in | hex.elevation, hex.terrain |

hextotal | The total values of the populations in the hex | hextotal.size |

hexavg | The average values of the populations in the hex (weighted by size) | hexavg.dominance |

otherhex | The other cell being considered for migration | otherhex.shore, otherhex.elevation |

otherhexavg | The averages of the population properties of the other cell being considered for migration (weighted by size) | otherhexavg.dominance, otherhexavg.capdistance |

otherhextotal | The totals of the population properties of the other cell being considered for migration | otherhextotal.size, otherhextotal.capdistance |

special.IsSameIdentity | Is the same identity already in the hex in question? | special.IsSameIdentity |

special.IsSeaMigration | Is this a sea migration? | special.IsSeaMigration |

##### Special properties with special handling by the model engine

Meaning | Handling in the engine | |
---|---|---|

pop.size | The number of people in the population. | This is a required population property in all model designs. If it falls below 0, the population dies and is removed from the map. |

pop.dominance | The “dominance” of the population relative to other populations | This is a required population property in all model designs. When populations merge, the dominant population is retained, as part of the dominant identity. |

pop.capdistance | The distance from the population’s “Capital city”, which is the first, founding cell of the identity (when the original population split) | This is an optional population property. If a property called “capdistance” is defined, then the update & merge formulas are ignored, and the value is calculated by the engine. (NOTE: Currently it is calculated by some Euclidean approximation, making it difficult to use. A future version will calculate it based on “number of hexes away from the capital” instead.) |

pop.seamigrate | The number of hexes this population is capable of migrating over sea. | If this value is 2 or greater (eg. the population can journey over 1 water hex and then reach a land hex), then the engine will attempt a random sea voyages each turn as part of the migration potential calculations. Whether the overseas hex is migrated to still depends on whether the migration potential there is the highest. (Note there is a special value available in the migration potential function called “special.isoverseas” which is 1 for sea migrations) |

hex.terrain | Land or water, where water – 0 and land = 1 | This is a required hex property in all model designs, populated automatically by the map data. |

hex.shore | The total number of water hexes adjacent to the hex | This is an optional hex property. If added as a hex property, it is populated automatically from the model data. |

hexavg | The average values of the populations in the hex (weighted by size) |