r.agent.aco
Agents wander around on the terrain, marking paths to new locations.
r.agent.aco [-pscal] outputmap=string [inputmap=string] costmap=string sitesmap=string rounds=integer [outrounds=integer] [targetvisibility=integer] [highcostlimit=integer] [lowcostlimit=integer] [maxpheromone=integer] [minpheromone=integer] [volatilizationtime=integer] [stepintensity=integer] [pathintensity=integer] [maxants=integer] [antslife=integer] decisionalgorithm=string evaluateposition=string [agentfreedom=integer] pheromoneweight=integer randomnessweight=integer costweight=integer [--verbose] [--quiet] [--qq] [--ui]
Example:
r.agent.aco outputmap=string costmap=string sitesmap=string rounds=999 decisionalgorithm=standard evaluateposition=avoidorforgetloop pheromoneweight=1 randomnessweight=1 costweight=0
grass.script.run_command("r.agent.aco", outputmap, inputmap=None, costmap, sitesmap, rounds=999, outrounds=None, targetvisibility=None, highcostlimit=None, lowcostlimit=None, maxpheromone=None, minpheromone=None, volatilizationtime=None, stepintensity=None, pathintensity=None, maxants=None, antslife=None, decisionalgorithm="standard", evaluateposition="avoidorforgetloop", agentfreedom=None, pheromoneweight=1, randomnessweight=1, costweight=0, flags=None, verbose=False, quiet=False, superquiet=False)
Example:
gs.run_command("r.agent.aco", outputmap="string", costmap="string", sitesmap="string", rounds=999, decisionalgorithm="standard", evaluateposition="avoidorforgetloop", pheromoneweight=1, randomnessweight=1, costweight=0)
Parameters
outputmap=string [required]
Name of pheromone output map
inputmap=string
Name of input pheromone raster map (e.g. from prior run)
costmap=string [required]
Name of penalty resp. cost raster map (note conversion checkbox)
sitesmap=string [required]
Name of sites map, vector data with possible points of origin
rounds=integer [required]
Number of iterations/rounds to run
Allowed values: 0-999999
Default: 999
outrounds=integer
Produce output after running this number of iterations/rounds
Allowed values: 0-999999
targetvisibility=integer
Distance to target from where it might be 'sensed'
Allowed values: 0-999999
highcostlimit=integer
Penalty values above this point an ant considers as illegal/bogus when in 'costlymarked' modus
Allowed values: 0-
lowcostlimit=integer
Penalty values below this point an ant considers as illegal/bogus when in 'costlymarked' modus
Allowed values: -99999-99999
maxpheromone=integer
Absolute maximum of pheromone intensity a position may have
Allowed values:
minpheromone=integer
Absolute minimum of pheromone intensity to leave on playground
Allowed values: 0-
volatilizationtime=integer
Half-life for pheromone to volatize (e.g. =rounds)
Allowed values: 0-
stepintensity=integer
Pheromone intensity to leave on each step
Allowed values: 0-
pathintensity=integer
Pheromone intensity to leave on found paths
Allowed values: 0-
maxants=integer
Maximum amount of ants that may live concurrently (x*y)
Allowed values: 0-
antslife=integer
Time to live for an ant (e.g. four times points distance)
Allowed values: 0-
decisionalgorithm=string [required]
Algorithm used for walking step
Allowed values: standard, marked, costlymarked, random, test
Default: standard
evaluateposition=string [required]
Algorithm used for finding and remembering paths
Allowed values: standard, avoidloop, forgetloop, avoidorforgetloop
Default: avoidorforgetloop
agentfreedom=integer
Number of possible directions the ant can take (4 or 8)
Allowed values: 4, 8
pheromoneweight=integer [required]
How is the pheromone value (P) weighted when walking (p*P:r*R:c*C)
Allowed values: 0-99999
Default: 1
randomnessweight=integer [required]
How is the random value (R) weighted when walking (p*P:r*R:c*C)
Allowed values: 0-99999
Default: 1
costweight=integer [required]
How is the penalty value (C) weighted when walking (p*P:r*R:c*C)
Allowed values: 0-99999
Default: 0
-p
Allow overwriting existing pheromone maps
-s
Produce a sequence of pheromone maps (by appending a number)
-c
Overwrite existing cost map (only used with penalty conversion)
-a
Auto-convert cost (slope..) to penalty map (using "tobler", see docu)
-l
Avoid loops on the way back
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--qq
Very quiet module output
--ui
Force launching GUI dialog
outputmap : str, required
Name of pheromone output map
Used as: input, raster
inputmap : str, optional
Name of input pheromone raster map (e.g. from prior run)
Used as: input, raster
costmap : str, required
Name of penalty resp. cost raster map (note conversion checkbox)
Used as: input, raster
sitesmap : str, required
Name of sites map, vector data with possible points of origin
Used as: input, vector
rounds : int, required
Number of iterations/rounds to run
Used as:
Allowed values: 0-999999
Default: 999
outrounds : int, optional
Produce output after running this number of iterations/rounds
Used as:
Allowed values: 0-999999
targetvisibility : int, optional
Distance to target from where it might be 'sensed'
Used as:
Allowed values: 0-999999
highcostlimit : int, optional
Penalty values above this point an ant considers as illegal/bogus when in 'costlymarked' modus
Used as:
Allowed values: 0-
lowcostlimit : int, optional
Penalty values below this point an ant considers as illegal/bogus when in 'costlymarked' modus
Used as:
Allowed values: -99999-99999
maxpheromone : int, optional
Absolute maximum of pheromone intensity a position may have
Used as:
Allowed values:
minpheromone : int, optional
Absolute minimum of pheromone intensity to leave on playground
Used as:
Allowed values: 0-
volatilizationtime : int, optional
Half-life for pheromone to volatize (e.g. =rounds)
Used as:
Allowed values: 0-
stepintensity : int, optional
Pheromone intensity to leave on each step
Used as:
Allowed values: 0-
pathintensity : int, optional
Pheromone intensity to leave on found paths
Used as:
Allowed values: 0-
maxants : int, optional
Maximum amount of ants that may live concurrently (x*y)
Used as:
Allowed values: 0-
antslife : int, optional
Time to live for an ant (e.g. four times points distance)
Used as:
Allowed values: 0-
decisionalgorithm : str, required
Algorithm used for walking step
Used as:
Allowed values: standard, marked, costlymarked, random, test
Default: standard
evaluateposition : str, required
Algorithm used for finding and remembering paths
Used as:
Allowed values: standard, avoidloop, forgetloop, avoidorforgetloop
Default: avoidorforgetloop
agentfreedom : int, optional
Number of possible directions the ant can take (4 or 8)
Used as:
Allowed values: 4, 8
pheromoneweight : int, required
How is the pheromone value (P) weighted when walking (p*P:r*R:c*C)
Used as:
Allowed values: 0-99999
Default: 1
randomnessweight : int, required
How is the random value (R) weighted when walking (p*P:r*R:c*C)
Used as:
Allowed values: 0-99999
Default: 1
costweight : int, required
How is the penalty value (C) weighted when walking (p*P:r*R:c*C)
Used as:
Allowed values: 0-99999
Default: 0
flags : str, optional
Allowed values: p, s, c, a, l
p
Allow overwriting existing pheromone maps
s
Produce a sequence of pheromone maps (by appending a number)
c
Overwrite existing cost map (only used with penalty conversion)
a
Auto-convert cost (slope..) to penalty map (using "tobler", see docu)
l
Avoid loops on the way back
verbose: bool, optional
Verbose module output
Default: False
quiet: bool, optional
Quiet module output
Default: False
superquiet: bool, optional
Very quiet module output
Default: False
DESCRIPTION
As a first real example of a world there is an ACO-based environment (see Ant Colony Optimization) available.
The basic concept of such an ACO world, is to take some cost surface and transform it to a penalty layer. Even if the algorithm comes from the realm of insects, it might be adapted to different animal kingdoms. Depending on the type of agent this penalty layer must be reinterpreted: if for example, we want to talk about human agents the penalty layer may be expressed by the walking velocity, e.g. calculated with the algorithm proposed by Tobler1993. The actors on the playground will wander around on the playground using the time for their paths that correspond with the values in the penalty grid. If they find some attractor, they walk home to the position they originated, marking their way with pheromones. While this pheromone vanishes over time, the following agents are more likely to choose their next steps to a position that smells most.
This first toolset was mainly developed for Topoi Project A-III-4, with some inspirations from previous work conducted at the Uni Bern in 2008.
NOTES
The state of this software is: "first do it".
ACO works best on dynamic maps -- it constantly tries to improve paths...
EXAMPLE
A fictive use case could look something like this (note: at the moment the in- and output variables with libold, are still ascii-files):
r.agent.aco outputmap=out.map penaltymap=testpenalty.grid \
sitesmap=sites.vect rounds=100 outrounds=100 volatilizationtime=5000 \
antslife=2000 maxants=400 pathintensity=1000000
For running the total test suite on the libraries, i.e. to run all the tests that are at the end of each python file, use this test collection (for certain tests, the following files must exist though: "elev.grid", and "arch.vect"):
user@host:~$ cd /<pathtoaddons>/r.agent/libagent
user@host:libold$ ./alltests.py
TODO
Integrate it directly within grass.
Improve encapsulation of classes.
Find good parameters, or parameter finding strategies for the ACO part. Try to avoid high penalty fields. Think about heuristics too.
Implement other ABM scenarios.
SEE ALSO
AUTHOR
Michael Lustenberger inofix.ch
SOURCE CODE
Available at: r.agent.aco source code
(history)
Latest change: Thursday Feb 20 13:02:26 2025 in commit 53de819