Gradient Resources

Gradient resource format is: 
  GRADIENT_RESOURCE gradient_resource_name[:options]  {gradient_resource_name ...}

Gradient Resources

Like other resources, gradient resources are defined in the Environment File and all entries on a gradient resource line are names of individual resources. Gradient resources are a type of spatial resource, some of the main difference being that gradient resources can move (standard gradient resources and halo gradient resources) and can affect org movements (hills and barriers). Currently moving gradient resources are only supported for bounded grid environments.

GRADIENT_RESOURCE Command

The syntax for the Gradient Resource command is: 
GRADIENT_RESOURCE gradient_resource_name[:options]  {gradient_resource_name ...}

Habitats:

The habitat a resource represents controls both the specifications of the resource (i.e. moving or stationary, orbiting or bounded within a defined area) and any effect of the resource on the organisms (i.e. blocking or slowing movement). Currently there are 4 habitats implemented: gradient, hills, barriers, and nests.

Gradient Resources: Standard and Halo

Standard gradient and halo resources allows the user to specify resource distributions which change over time. If movement is enabled, the conical resources move around the Avida grid. This movement may be confined to an orbit around a specified anchor cell on the Avida grid (halos) or within a defined bounding box (standard). Gradient resource cones can be capped with a plateau cylinder of a determined height wherever cone height meets or exceeds the value of 1. In terms of actual resource value, this is analogous to slicing the cone at height 1 and then setting the actual resource value (plateau) in the sliced area to some flat value. Organisms can use sense instructions to detect resources on all parts of the cone, but they can only consume the resources where the value is >= min value in the associated reaction or collect instruction. Typically, the min value is set so that only the plateau area of the cone can be consumed. When an organism consumes any part of the cone, the cone can be set to stop moving until a predifined number of updates (=decay) has passed or all consumable resource (all cells with value >= 1) has been consumed. The cone is then refreshed at some random location within the specified boundaries. An odd but useful quirk is that if decay is set to 1, you can have walking wounded resources.

Barriers: Random, Vertical, and Horizontal

Barriers are far simpler than halo and standard gradient resources. Barrier resources are simply meant to represent walls which block movement. Barriers are only implemented to be created randomly within the grid (the first block is set down in a random cell, then the next block set in a connected random, E-W, or N-S cell, and so on). For a vertical or horizontal barrier, the build direction is randomly selected at the start and the build continues in that direction until all the blocks are placed. If the end of the world is reached and there are still blocks to place, we go back to the original cell and build in the opposite direction. For random barriers, a random direction is selected at the start. Then, the direction of the build continues unchanged with a 95% probability, and a new random build direction with 5% probability. The user can also specify and exclusion area by using halo_inner_radius and halo anchors. Because barriers can be generated in the middle of a run, we allow orgs already standing on a barrier (which should only happen if they are born on a barrier or if a barrier was created underneath them) to continue moving. In other words, they can exit a barrier, but orgs cannot enter one. If an org (not already on a barrier) tries to enter a barrier cell, movement fails and a 0 is returned to the ?BX? register. Orgs can also make use of the sense-faced-habitat instruction to find the most restrictive habitat type in the faced cell. This will return a 1 if the 'worst' resource in the faced cell is a hill, a 2 if a barrier is in the faced cell, and a 0 if no hills or barriers are in the faced cell.

Hills

Hills are simply meant to represent areas which slow movement. Hills are only implemented to be created randomly within the grid. The center block for each occurance of a hill is set down in a random cell, then the rest of the block is drawn in a circle around the center point using a random radius selected from within the config set radius range. The user can also specify and exclusion area by using halo_inner_radius and halo anchors. The effects on movement are determined by the resistance config setting. This is implemented as the probability of successfully moving while on a hill is equal to 1/resistance. As such, on average, an org on a hill with resistance = 4, will have to execute 4 move instructions to move one cell.

Nests

Nests are standard gradient resources, but by declaring a gradient resource to be a nest, the resource will 'hidden' from long-distance sensing instructions such as look-ahead. Dens Dens are unhidden nests that are visible to instructions like look-ahead.

Predatory Resources

Predatory resources are gradient resources with teeth. See SetPredatoryResource in the events list of actions.
 

Table 1: Gradient Resource Options

black variables apply to all gradient resource types, blue variables apply to standard and halo gradient resources green variables apply only to halo resources brown(ish) variables apply to halo resources, hills and barriers red variables apply only to barriers purple variables apply only to hills blue-green variables apply to all topographic features (hills, barriers, dens)
Argument Description Default
habitat Type of gradient resource. This determines most of the behaviors and effects of the resource.0 = gradient (standard or halo), 1 = hills, 2 = barriers, 3 = nests(hidden), 4 = dens(visible), 5 = predatory, > 5 = other gradient resource (used to differentiate different 'kinds' of food. 0
refuge Is the resource a refuge (predation prevented)? 0
peakx Initial x-coordinate of cone peak cell. Only affects non-moving peaks. For moving peaks, random coordinates within appropriate bounds will be used. 0
peaky Initial y-coordinate of cone peak cell. 0
height Height in terms of resource value of the cone at the peak center. This affects values along the slope of the cone where the value of any cell on the slope = height/(distance to center + 1). Note that the height of the plateau may supersede the height of the cone, lowering or raising all cell resource values within the plateau to the plateau value. Since slope is height/distance, for a cone having a plateau and a height set to 10, the plateau will be the region of cells 10 or fewer cells from the center. 0
plateau Standard and Halo: Actual initial height in terms of resource levels wherever cone height is greater or equal to 1. This will supersede the cone height in eligible cells. A value of -1 turns this option off. Barriers and Hills: Height of the topographic feature. Apart from when plateau = 0 (off) and plateau > 0 (on), the plateau value has no effect outside of providing values for drawing/rendering. -1.0
spread Radius of the cone in terms of cells (i.e. extent of cone base). Because the spread starts counting the center cell as radius == 0, a spread of 4 will have 9 cells along the E-W/N-S axes (center cell + 4 cells either side). However, the height of this same resource would need to be == 5 to cover the same area with res value >= 1 (since we add 1 to distance from center cell for height). 0
decay Number of updates until gradient resource is refreshed after an organism initially consumes resources in the cone. The refresh will occur even if the plateau has not been completely consumed. If decay = 0, the peak will be regenerated at a new random location every update, regardless of whether any has been consumed. If decay = 1, the cone will never actually be regenerated, but will move continuously. If decay > 1, resources move until some has been consumed. Movement will then halt until decay # updates (including current) have passed and the cone will then be regenerated in a new random location. 1
min_x Leftmost coordinate of the rectangle in which resource will move randomly. The resource will stop moving left and bounce in a new random direction (inside the rectangle) when the edge of the plateau hits min_x. The case is the same for max_x, min_y, and max_y. 0
max_x Rightmost coordinate of the rectangle in which resource will move randomly. 0
min_y Topmost coordinate of the rectangle in which resource will move randomly. 0
max_y Bottommost coordinate of the rectangle in which resource will move randomly 0
threshold This set how other parts of avida interact with the resource, specifically look instructions (for now). In the look instructions, anything at or above this value will be treated and counted as an 'edible' cell. 1.0
move_a_scaler Measure of resource movement smoothness taken from the variable "A" in equation 1 from Morrison and DeJong's DF-1 Algorithm. Values range from 1 to 4. Values from 1 to around 3 yield smooth movements, while larger values yield chaotic movement. In the current implementation of gradient resources, this value is largely irrelevant, but move_a_scaler = 1 means no movement and the common setting for moving peaks is 3.8. 1.0
updatestep Standard and Halo: How many updates to wait until changing gradient resouce movement direction. Resources move in random directions, only changing course if they bounce or when updatestep is reached. Low updatestep numbers result in chaotic peak movements (and peaks tend not to travel very far overall). Barriers and Hills: How many updates to wait until regenerating the topographic features at new locations. Any value less than 1 (or >= the number of updates in the run) will turn off regeneration. 1
halo Determines if this is a halo gradient. Instead of moving in a predetermined box, halo resources move randomly in an orbit around some fixed anchor cell. 1 if true, 0 if false. Halos do not use the bounded box (min_x, max_x, min_y, max_y) variables. Instead, they rely on the radius and width definitions to determine movement bounds. Note that orbit distances are in terms of cells, so orbits are rectangle in Avida. A diagonal line of cells count as the same distance as a straight line of cells. 0
halo_inner_radius Halo: Closest (in number of cells) the inner edge of a plateau of a halo resource can be to the anchor cell. If no plateau is set, then this will just be the closest the center peak cell can be to the anchor, i.e. the minimum orbit. If plateau is set, minimum orbit will be halo_inner_radius + height (since radius of plateau = height). If you want a plateau of size 10 to be centered on the anchor point, you would need to set halo_inner_radius = -10. If you want the same peak to orbit the anchor point with no space between the plateau and the anchor, halo_inner_radius would be set to 10. Hills: Closest any part of any generated hill can be to the given anchor point. For hill placement, the box defined by the anchor point, inner_radius, and hill radius define an exclusion zone for placement of the hill center point and build of the hill. 0
halo_width How wide in cells the orbit is. The farthest the outer edge of the plateau can be from the anchor cell is halo_inner_radius + halo_width. If halo_width = 2 * height, halo resouces will travel in a fixed orbit, randomly changing orbit direction every updatestep. If halo_width > 2 * height, halo resources will travel along a random orbit between halo_inner_radius and halo_inner_radius + halo_width, changing EITHER orbit or orbit direction every updatestep. 0
halo_anchor_x X-coordinate of the anchor cell. For hills this is simply the center point of any exclusion zone and does not otherwise determine where the hill is drawn. 0
halo_anchor_y Y-coordinate of the anchor cell. 0
move_speed How 'fast' the gradient moves in the grid. Since gradient resources are built on spatial resources and spatial resources are only checked once per update, move_speed actually determines how far, in number of cells, the cone is moved between updates, not in an update. Thus move_speed > 1 will cause peaks to 'jump' ahead. Move speeds less than 1 will 'pause' resources for the abs(move_speed) number of updates between moves. This can be valuable if organisms, due to combinations of genome length and time slicing, are slow to react to resource moves and cannot otherwise keep up with the resource. 1
common In determining the cell values within the plateau, do we treat them as a common (= 1) resource, or as individual cells (= 0)? If common = 1, and any plateau cells are depletabled by organisms, at each update we look to see how much of the plateau was consumed, divide that by the number of cells in the plateau, subtract that amount from the plateau value at the beginning of the previous update (before depletion), and set all plateau cells to this new value. Thus, at the updates, the effects of depletion is spread out across all plateau cells. Peak height is then recalculated to reflect the change in this value and the entire cone is redrawn, while preserving the original extent of the plateau. If common = 0 resource depletions affect only individual plateau cells and the peak slopes are not changed. 0
initial Initial value for all plateau cells. If set to -1 (default), initial cell values will be set == plateau. -1.0
plateau_inflow Inflow rate of resources within the plateau. This amount will be added to each cell in the plateau at each update, regardless of common setting. Maximum value for plateau cells (if set at >= 0) remains original plateau value. If common = 1, the inflow is added to the current peak height and height is reset to the new value. All values in the peak are then recalculated, but keeping the original extent of the plateau. Maximum value for height (for cone shape) remains capped at original height value. 0.0
plateau_outflow Outflow rate of resource within the plateau. The quantity of resources = outflow * height will be removed from each cell in the plateau at each update, regardless of common setting. Minimum resulting value for plateau cells is 0. If common = 1, the outflow quantity is subtracted from the current peak height and height is reset to the new value. All values in the peak are then recalculated, but keeping the original extent of the plateau. Minimum resulting value for height (cone shape) is 0. 0.0
cone_inflow Inflow rate of resources for individual cells in the cone. This amount will be added to each cell in the cone at each update. The value for a cell will never exceed that expected based on cone height and distance from center (that is, this is a refill rate as much as it is an inflow). Will not affect height of the cone (as in plateau_inflow) and will not affect any plateau cells (use plateau_inflow and/or gradient_inflow for that). 0.0
cone_outflow Outflow rate for non-plateau cells 0.0
gradient_inflow Inflow rate of resources for individual cells in the cone scaled by distance from peak center. This amount / (this_distance + 1) will be added to each cell in the cone at each update. The value for a cell will never exceed that expected based on cone height and distance from center (that is, this is a refill rate as much as it is an inflow). Will not affect height of the cone (as in plateau_inflow) and will not affect any plateau cells (use plateau_inflow for that). Can be combined with cone_inflow and cone_outflow and / or plateau_inflow and plateau_outflow.
To 'grow' a cone, set the height to spread + 1, add gradient inflow, set initial to 0, and set plateau to be max desired reachable height. Cells in the cone will 'grow' at different rates, with cell height growth stopping when the cell value reaches the plateau value.		 0.0
floor Minimum value for cells within the cone. Cells that would otherwise have lower values (based on distance from center) will be set to this value. Floor does not affect plateau cells. Rather, it is intended to keep values along the spread from dropping below 1 for experiments where cell values along the slopes would affect merit rewards. 0.0
count The number of hills or walls/barriers to generate. 1
max_size The maximum wall size in number of blocks(cells) or maximum hill radius. Actual hill and wall sizes will be determined by a random number selected between min and max (inclusive), minus any blocks placed off-world or overlapping with other blocks of the same resource (or self for walls, if config = 0). 1
min_size The minimum wall or hill size. 1
config The orientation of the wall. 0 = random (all blocks placed randomly, but neighboring, relative to previous block), 1 = vertical (rand N or S from seed block), 2 = horizontal (rand E or W from seed block), 3 = vertical from seed (peakx, peaky) to S, 4 = horizontal from seed (peakx, peaky) to W.For hills, if config == 1, generate 1 hill at the peakx X peaky coordinates. 0
resistance This is implemented as a simple way of impacting the speed with which orgs can move through/across a hill. On average, an org on a hill will have to execute a number of move instructions equal to the resistance setting to move one cell.Setting resistance to 0 for a wall allows orgs to pass through it (creating a linear landmark rather than a barrier). 1.0
 
An example of setting a halo gradient of cone height 10 and radius 180. The plateau height is 1, meaning that the actual resource height is 1 at cells where the cone height is at least 1. Movement is smooth and is updated every 200 updates. The anchor cell is at 189, 249, and it moves no closer than 10 cells away from the anchor and no farther than 30. The resource is immediately refreshed after it has been consumed by at least one organism. 
GRADIENT_RESOURCE food1:height=10:spread=180:plateau=1:decay=1:move_a_scaler=3.8:updatestep=200:halo=1:halo_inner_radius=10:
halo_anchor_x=189:halo_anchor_y=249:halo_width=20:move_speed=1
An example of a gradient which will initialize at 189, 249 and is bounded by a 200x200 cell box. The cone height is 20, but the radius is only 10 cells. The plateau is of height 2, and the resource moves only every 10000 updates. 
GRADIENT_RESOURCE nest1:peakx=189:peaky=249:height=20:spread=19:plateau=2:decay=1:min_x=125:max_x=375:min_y=125:max_y=375:

move_a_scaler=1:updatestep=10000
Examples of barrier resources. Both will create 5 randomly placed vertical or horizontal walls, each between 10 and 200 cells long. For each barrier instance, the initial 'seed' block will be placed in a random cell. Then the build direction (N or S for the first, E or W for the second) will be chosen and the next block placed in the corresponding neighboring cell until the (randomly chosen) target size is met or the edge of the world is reached. All walls will be dismantled and new sets generated every 250 updates. 
GRADIENT_RESOURCE vert_walls:habitat=2:plateau=1.5:updatestep=250:count=5:max_size=200:min_size=10:config=1
GRADIENT_RESOURCE horiz_walls:habitat=2:plateau=1.5:updatestep=250:count=5:max_size=200:min_size=10:config=2
An example of a hill resource. This will draw 10 randomly placed hills every 1000 updates, with each individual hill having a radius between 50 and 125 cells. No hills will be drawn/placed within 10 cells of the center of the world (49, 49). When crossing any of these hills, an organism, on average, will have to take two steps for every one cell traversed. 
GRADIENT_RESOURCE hills:habitat=1:plateau=0.2:updatestep=1000:count=10:max_size=125:min_size=50:halo_inner_radius=10:
halo_anchor_x=49:halo_anchor_y=49:resistance=2