Running Pyage forams module - maciek123/pyage-forams GitHub Wiki

This page describes ways to run Pyage forams simulations. It is recommended to learn how to run Pyage platform first.

Installation

Pyage forams module is available in pypi, so you can install it using easy_install or pip command-line tool.

easy_install pyage
easy_install pyage-forams
```

## Running on a single machine

Example pyage config file:

```
# coding=utf-8
from pyage.core import address
from pyage.core.stop_condition import StepLimitStopCondition
from pyage_forams.solutions.environment import environment_factory, Environment3d
from pyage_forams.solutions.foram import create_forams, create_agent
from pyage_forams.solutions.genom import GenomFactory
from pyage_forams.solutions.insolation_meter import StaticInsolation
from pyage_forams.solutions.statistics import SimpleStatistics

factory = GenomFactory(chambers_limit=5)
genom_factory = lambda: factory.generate
forams = create_forams(8, initial_energy=5)
agents = create_agent
insolation_meter = StaticInsolation

size = lambda: 10
reproduction_minimum = lambda: 10
movement_energy = lambda: 0.25
growth_minimum = lambda: 10
energy_need = lambda: 0.2
algae_limit = lambda: 20
newborn_limit = lambda: 9
reproduction_probability = lambda: 0.8
growth_probability = lambda: 0.8
growth_cost_factor = lambda: 0.5
capacity_factor = lambda: 1.1
initial_algae_probability = lambda: 0.3

environment = environment_factory(regeneration_factor=0.1, clazz=Environment3d)
stop_condition = lambda: StepLimitStopCondition(90)
address_provider = address.SequenceAddressProvider
stats = SimpleStatistics
```
Parameters you may like to modify:
* size - size of the grid. Value '10' here means 10x10x10
* create_forams(8, initial_energy=5) - number of forams initially created and their energy level
* reproduction_minimum - minimal level of energy required for forams to reproduce
* reproduction_probability - probability of reproduction when other requirements satisfied
* newborn_limit - limit of newborn forams during single reproduction
* movement_energy - energy required to move
* growth_minimum - level of energy required to create new chamber
* growth_cost_factor - cost of creating new chamber. 0.5 means that half of the energy will be consumed
* growth_probability - probability of growth when other requirements satisfied 
* energy_need - factor determining forams energy consumption in a single step
* capacity_factor - factor determining how much algae can be consumed in a single step
* initial_algae_probability - with probability algae with be placed in every cell during initialization
* regeneration_factor - speed of algae growth 

## Running in distributed mode

Make sure you know how [to run Pyage in distributed mode](https://github.com/maciek123/pyage/wiki/Running-Pyage-in-distributed-mode) and run Pyro nameserver.

When running in distributed mode, you should have following **agents** property in your config file:
```
agents = partial(create_remote_agent, "lowerrightback")
```
Set your agent address (lowerrightback in above example) to something meaningful, as it will be used in topology setup below.

In addition to parameters from "standalone" configuration, you should also include:
```
neighbour_matcher = Neighbour3dMatcher
request_dispatcher = create_dispatcher()

neighbours = lambda: {"left": "lowerleftback", "upper": "upperrightback", "front": "lowerrightfront"}
```
Most important part is the **neighbours** parameter, it defines your topology. You should provide mapping from side (right/left/front etc.) to address of the agent that is neighbour on given side.

[Here](https://github.com/maciek123/pyage-forams/tree/master/pyage_forams/conf/distributed3d) and [here](https://github.com/maciek123/pyage-forams/tree/master/pyage_forams/conf/distributed2d) you can find working examples of distributed configurations.