Difference between revisions of "Animover 1"

From Numerus
Jump to navigation Jump to search
 
(19 intermediate revisions by the same user not shown)
Line 1: Line 1:
'''Download Ramp'''
[https://www.numerusinc.com/studio/ Download Numerus Studio]


Click here for a publication describing this Ramp in detail.
[https://6db9fc8aec9da0846939-3276ccc2b20695183db7791dd451b756.ssl.cf1.rackcdn.com/NMBStudio/Ramps/Ani1CR3.nms '''Download RAMP''']
 
Click [https://www.biorxiv.org/content/10.1101/2023.12.27.573450v1 here] for a publication describing this RAMP in detail.


==About Animover 1==
==About Animover 1==
'''Animover 1''' is the first in a series of models simulating animal movement over a territory containing resources. In Animover 1 a single agent is foraging over the landscape with the ability to detect and consume a single resource. This resource is depleted by the agent's movement, which will cease if the agent's resource level ever reaches 0. The resource appears in clumps randomly across the landscape.
'''Animover 1''' is the first in a series of models simulating animal movement over a territory containing resources. In Animover 1 a single agent is foraging over the landscape with the ability to detect and consume a single resource. The amount of resource contained in the agent is depleted by the agent's movement, and the agent will cease moving if its resource level ever reaches 0. The resource appears in patches randomly across the landscape.
 
Movement is governed by a kernel data structure, which selects a set of acceptable target locations for the agent from a set of candidates, based on a number of criteria. The kernel then uses a selection algorithm <ref>Animover 1 uses multinomial selection based on fitness criteria described later.</ref> to determine the actual target. Kernels draw from an initial pool of potential next locations. This pool is a segment of an annulus defined by radii ''r<sub>min</sub>'', ''r<sub>max</sub>'' and angle ''&psi;'', as described [[#Kernel Definitions and Rules|below]].


Movement is governed by a kernel data structure, which selects a set of acceptable target locations for the agent from a set of candidates, based on a number of criteria. The kernel then uses a selection algorithm <ref>Animover 1 uses multinomial selection based on fitness criteria described later.</ref> to determine the actual target. Kernels draw from an initial pool of potential next locations. Two kernel types are employed, depending on the agent's current circumstances: ''Between Patches (BP)'' and '' Within Patches (WP)''. Generally, an agent using the ''BP'' kernel will try to find a site within a resource clump of maximal utility. When using a ''WP'' kernel, the agent will tend to move within the clump as long as the clump's resource level is above a threshold, and the length of the stay is not too great.
Two kernel types are employed, depending on the agent's current circumstances: ''Between Patches (BP)'' and '' Within Patches (WP)''. Generally, an agent using the ''BP'' kernel will try to find a site within a resource patch of maximal utility. When using a ''WP'' kernel, the agent will tend to move within the patch as long as the patch's resource level is above a threshold, and the length of the stay is not too great.


The simulation starts with the agent in an initial location, with an initial trajectory ''&theta;'' and an initial kernel. The current kernel selects the next location and the next kernel. Because selecting the next location may require more than one simulation clock tick, a separate model clock is maintained which advances only when the agent actually moves.
The simulation starts with the agent in an initial location, with an initial trajectory ''&theta;'' and an initial kernel. The current kernel selects the next location and the next kernel. Because selecting the next location may require more than one simulation clock tick, a separate model clock is maintained which advances only when the agent actually moves.


Displays show the landscape and animate the agent's movement over time. Kernel selection behavior is also displayed. Data corresponding to the agent's journey is shown in a visual log and collected in CSV file.
Displays show the landscape and animate the agent's movement over time. Kernel selection behavior is also displayed. Data corresponding to the agent's journey is shown in a visual log and collected in CSV files.


<br clear="both">
<br clear="both">


==Ramp Controls==
==RAMP Controls==
[[File:console1.png|800px|thumb|Animover 1 Console]]
[[File:console1.png|800px|thumb|Animover 1 Console]]


===Parameter Sliders===
===Parameter Sliders===
Sliders belong to one of three groups, determined by their color.
Sliders belong to one of three groups, determined by their color.
;Clump Creation (orange)
;Patch Creation (orange)
:Resource clumps are laid down randomly over multiple passes when the simulation is reset. These parameters determine the number of passes and control the density of resources within clumps, and clumps throughout the landscape.
:Resource patches are laid down randomly over multiple passes when the simulation is reset. These parameters determine the number of passes and control the density of resources within patches, and patches throughout the landscape.
;Kernel Specifications (yellow)
;Kernel Specifications (yellow)
:Determines the min and max radii and the angles associated with the ''BP'' and ''WP'' Kernels.
:Determines the min and max radii and the angles associated with the ''BP'' and ''WP'' Kernels.
;Resource Energy and Regrowth (purple)
;Resource Energy and Regrowth (purple)
:Determines the agent's initial energy, its consumption and expended energy per time unit, and the resource growth rate. All of these are used by the equations used in the resource consumption and burn ram.
:Determines the agent's initial energy, its consumption and expended energy per time unit, and the resource growth rate. All of these are used by the equations used in the Extraction RAM.


===Buttons===
===Buttons===
Line 32: Line 36:
:The '''CSV''' button saves the current run in a file uniquely identified with the run. Alternatively, selecting '''CSV Auto''' causes the previous run to be saved on reset.
:The '''CSV''' button saves the current run in a file uniquely identified with the run. Alternatively, selecting '''CSV Auto''' causes the previous run to be saved on reset.


;Clump Initialization (orange)
;Patch Initialization (orange)
:'''Initialization Algorithm''' selects either a random irregular or regular shape. When a regular shape is selected, '''Neighborhood''' determines whether a Moore or Von Neumann neighborhood is used.
:'''Initialization Algorithm''' selects either a random irregular or regular shape. When a regular shape is selected, '''Neighborhood''' determines whether a Moore or Von Neumann neighborhood is used.


;Parameter Viewer
;Parameter Viewer (blue)
:Opens the Parameter Viewer (discussed [[#Parameter Page|below]])
:Opens the Parameter Viewer (discussed [[#Parameter Page|below]])


;Log Off/On
;Log Off/On (blue)
:Disables/enables the Log Viewer
:Disables/enables the Log Viewer


Line 68: Line 72:


;CAM Definition
;CAM Definition
:''r min'', ''r max'', and ''&psi;'' are used to initialize the corresponding sliders. ''t_alpha'' and ''c_alpha'' are used in the computation that determines the next location. The Selection Rule specifies the rule used in the final selection of next location. These are described further below.
:''r min'', ''r max'', and ''&psi;'' are used to initialize the corresponding sliders. ''c_alpha'' and ''t_alpha'' are used in the computations that determines the next location and next kernel, respectively. The Selection Rule specifies the rule used in the final selection of next location. These are described further below.
 


===Zoomable Viewer===
===Zoomable Viewer===
Line 87: Line 90:
The initial pool is defined for each kernel type by the blue annulus shown in the figure. It uses the parameters ''r<sub>min</sub>'', ''r<sub>max</sub>'' and ''&psi;'', specified on the Parameter Page and by sliders (with ''&theta;'' representing the agent's current trajectory), to define a global prototype for that kernel type.
The initial pool is defined for each kernel type by the blue annulus shown in the figure. It uses the parameters ''r<sub>min</sub>'', ''r<sub>max</sub>'' and ''&psi;'', specified on the Parameter Page and by sliders (with ''&theta;'' representing the agent's current trajectory), to define a global prototype for that kernel type.


Kernels are specified as a sequence of ''phases'', ''&rho;<sub>i</sub>'', each of which may substitute values of  
Kernels are specified as a sequence of ''phases'', ''&Phi;<sub>i</sub>'', each of which may substitute values of  
''r<sub>min</sub>'', ''r<sub>max</sub>'' and ''&psi;'', whose values may depend on the global prototype, to specify its candidate pool ; i.e.,
''r<sub>min</sub>'', ''r<sub>max</sub>'' and ''&psi;'', whose values may depend on the global prototype, to specify its candidate pool ; i.e.,


:''K<sub>type</sub>'' = [''&rho;<sub>0</sub>''(''r<sub>0,min</sub>, r<sub>0,max</sub>, &psi;<sub>0</sub>''), ''&rho;<sub>1</sub>''(''r<sub>1,min</sub>, r<sub>1,max</sub>, &psi;<sub>1</sub>''), ...]
:''K<sub>type</sub>'' = [''&Phi;<sub>0</sub>''(''r<sub>0,min</sub>, r<sub>0,max</sub>, &psi;<sub>0</sub>''), ''&Phi;<sub>1</sub>''(''r<sub>1,min</sub>, r<sub>1,max</sub>, &psi;<sub>1</sub>''), ...]


Each phase attempts to create a non-empty set of potential targets, but a phase may fail. Phases are tried in sequence until one succeeds. Since the kernel is expected to succeed at making a selection, the last phase in each kernel must be guaranteed to succeed.
Each phase attempts to create a non-empty set of potential targets, but a phase may fail. Phases are tried in sequence until one succeeds. Since the kernel is expected to succeed at making a selection, the last phase in each kernel must be guaranteed to succeed.
Line 96: Line 99:
<br clear="both">
<br clear="both">
===''BP'' Kernel Description===
===''BP'' Kernel Description===
The ''BP'' kernel consists of 2 phases, ''Vision'' and ''Movement''. The Vision phase searches for a resource clump and the Movement phase is deployed when no clump is found. If a clump is found, it must pass a resource level test detailed below in order to be acceptable.
The ''BP'' kernel consists of 2 phases, ''Vision'' and ''Movement''. The Vision phase searches for a resource patch and the Movement phase is deployed when no patch is found. If a patch is found, it must pass a resource level test detailed below in order to be acceptable.


;Vision
;Vision
[[File:vision0.png|right|Vision]]
[[File:vision0.png|right|Vision]]
[[File:vision1.png|right|Vision]]
[[File:vision1.png|right|Vision]]
#Computes a candidate pool with ''r<sub>min</sub>'' = 0 and ''&psi;'' = ''&pi;'' /2 (''r<sub>max</sub>'' is the same as in the global prototype. If the candidate pool fails to intersect a resource clump, proceed to Movement.
#Computes a candidate pool with ''r<sub>min</sub>'' = 0 and ''&psi;'' = ''&pi;'' /2 (''r<sub>max</sub>'' is the same as in the global prototype. If the candidate pool fails to intersect a resource patch, proceed to Movement.
#Determine ''c<sub>max</sub>'', a cell with maximal resource value within the intersection.
#Determine ''c<sub>max</sub>'', a cell with maximal resource value within the intersection.
#Sum the resources in ''c<sub>max</sub>'' plus the resources in the Moore neighborhood of ''c<sub>max</sub>''.
#Sum the resources in ''c<sub>max</sub>'' plus the resources in the Moore neighborhood of ''c<sub>max</sub>''.
Line 114: Line 117:


===''WP'' Kernel Description===
===''WP'' Kernel Description===
The ''WP'' kernel consists of 3 phases, ''Consuming'', ''Seeking'' and ''Rim''. The Consuming phase uses a small candidate pool and continues foraging within a clump. The Seeking phase is uses a disk for its candidate pool to expand the foraging range. The Rim phase uses a thin, distant region to jump out of the resource patch.
The ''WP'' kernel consists of 3 phases, ''Consuming'', ''Seeking'' and ''Rim''. The Consuming phase uses a small candidate pool and continues foraging within a patch. The Seeking phase is uses a disk for its candidate pool to expand the foraging range. The Rim phase uses a thin, distant region to jump out of the resource patch.


;Consuming
;Consuming
[[File:consuming.png|right|Consuming]]
[[File:consuming.png|right|Consuming]]
#Computes a candidate pool with a global prototype in which ''r<sub>min</sub>'' = 0, ''r<sub>max</sub>'' is small, and ''ψ = π / 4''  
#Computes a candidate pool with a global prototype in which ''r<sub>min</sub>'' = 0, ''r<sub>max</sub>'' is small, and ''ψ = π / 4''  
#Succeeds if the intersection with the current clump passes the same resource test as described above with the ''BP'' kernel; otherwise move to the Seeking phase.
#Succeeds if the intersection with the current patch passes the same resource test as described above with the ''BP'' kernel; otherwise move to the Seeking phase.
#If successful, choose the target using the multinomial selection process described above.
#If successful, choose the target using the multinomial selection process described above.
<br sides="both">
<br sides="both">
Line 141: Line 144:
#If the aging computation determines that the current kernel should continue to be used, a resource computation similar to those used for the ''BP'' and ''WP'' kernels is carried out. The resource total ''tot'' for Moore neighborhood of the current location is computed. If the current kernel is ''BP'' and ''tot > c_alpha'', or the current kernel is ''WP'' and ''tot < c_alpha'', then a switch to the other kernel takes place despite the results of the aging computation.
#If the aging computation determines that the current kernel should continue to be used, a resource computation similar to those used for the ''BP'' and ''WP'' kernels is carried out. The resource total ''tot'' for Moore neighborhood of the current location is computed. If the current kernel is ''BP'' and ''tot > c_alpha'', or the current kernel is ''WP'' and ''tot < c_alpha'', then a switch to the other kernel takes place despite the results of the aging computation.
#If the aging computation indicates that the kernel should switch, then the switch takes place.
#If the aging computation indicates that the kernel should switch, then the switch takes place.
==Resource Extraction, Depletion and Regrowth==
[[file:extraction0.png|thumb|Default]]
The agent "burns" its resource as it moves across the landscape. Resources are transferred to the agent when it occupies a cell containing resources; correspondingly, a cell's resource may experience regrowth. These dynamics are handled by the Extraction RAM, with 3 possible supplied settings, to which the user may add his or her own versions. This RAM is used to choose among models that compute the next values of the individuals energy/size variable,
''h<sub>t</sub>'' and the cell resource variables ''c<sub>ab,t</sub>'', encoded respectively as <code>next_h</code> and <code>next_c</code>. Current value
''h<sub>t</sub>'' is encoded as <code>agent.h()</code>, and ''c<sub>ab,t</sub>'' is encoded as <code>cell.c()</code>.
In the default version, agent resource increases by the smaller of <tt>k_add</tt> and the amount remaining in the cell, and is depleted by the burn rate <tt>k_sub</tt> times the distance traveled. There is no regrowth.
[[file:extraction1.png|thumb|Alternative 1]]
In Alternative 1, regrowth is equal to the regrowth rate <tt>k_grw</tt> times the amount of resource remaining in the cell.
[[file:extraction2.png|thumb|Alternative 2]]
Alternative 2 is the same as Alternative 1 except it has 20 percent metabolic efficiency (not 100 percent), regrowth is reduced by a factor of 10 to deal with too many decimal points in the slider, and size-dependent traveling efficiency has been added.
<br sides="both">

Latest revision as of 17:25, 29 December 2023

Download Numerus Studio

Download RAMP

Click here for a publication describing this RAMP in detail.

About Animover 1

Animover 1 is the first in a series of models simulating animal movement over a territory containing resources. In Animover 1 a single agent is foraging over the landscape with the ability to detect and consume a single resource. The amount of resource contained in the agent is depleted by the agent's movement, and the agent will cease moving if its resource level ever reaches 0. The resource appears in patches randomly across the landscape.

Movement is governed by a kernel data structure, which selects a set of acceptable target locations for the agent from a set of candidates, based on a number of criteria. The kernel then uses a selection algorithm [1] to determine the actual target. Kernels draw from an initial pool of potential next locations. This pool is a segment of an annulus defined by radii rmin, rmax and angle ψ, as described below.

Two kernel types are employed, depending on the agent's current circumstances: Between Patches (BP) and Within Patches (WP). Generally, an agent using the BP kernel will try to find a site within a resource patch of maximal utility. When using a WP kernel, the agent will tend to move within the patch as long as the patch's resource level is above a threshold, and the length of the stay is not too great.

The simulation starts with the agent in an initial location, with an initial trajectory θ and an initial kernel. The current kernel selects the next location and the next kernel. Because selecting the next location may require more than one simulation clock tick, a separate model clock is maintained which advances only when the agent actually moves.

Displays show the landscape and animate the agent's movement over time. Kernel selection behavior is also displayed. Data corresponding to the agent's journey is shown in a visual log and collected in CSV files.


RAMP Controls

Animover 1 Console

Parameter Sliders

Sliders belong to one of three groups, determined by their color.

Patch Creation (orange)
Resource patches are laid down randomly over multiple passes when the simulation is reset. These parameters determine the number of passes and control the density of resources within patches, and patches throughout the landscape.
Kernel Specifications (yellow)
Determines the min and max radii and the angles associated with the BP and WP Kernels.
Resource Energy and Regrowth (purple)
Determines the agent's initial energy, its consumption and expended energy per time unit, and the resource growth rate. All of these are used by the equations used in the Extraction RAM.

Buttons

CSV Data File Control (green)
A CSV file can be downloaded after each run. The top of one such file is shown here.
Animover 1 CSV output
The file's header includes all of the parameter settingss. Each line shows date and time, location, distance traveled, current angle and change in angle for the last move. Also, current resource level and kernel used by the agent are included.
The CSV button saves the current run in a file uniquely identified with the run. Alternatively, selecting CSV Auto causes the previous run to be saved on reset.
Patch Initialization (orange)
Initialization Algorithm selects either a random irregular or regular shape. When a regular shape is selected, Neighborhood determines whether a Moore or Von Neumann neighborhood is used.
Parameter Viewer (blue)
Opens the Parameter Viewer (discussed below)
Log Off/On (blue)
Disables/enables the Log Viewer

Displays

Zoomable Landscape Display
Animates the movement of the agent, showing the kernel used at each step. Also shows resource regrowth.
This display is zoomable, as described below, and can be opened in a separate frame and enlarged.
Log Viewer
Shows the moves made on the current day. Includes day and time, agent resource level, and kernel action.
Agent Resource vs Time
Graph showing the agent's resource level over time.


Parameter Page

Parameter Page
Clicking the Parameter Viewer button opens a page of parameters, some of which are not present in the sliders and others which initialize the sliders. This page is part of a larger parameter set that will be deployed in later versions of the Animover.
Rows, Columns, Δx, Δy
Specify the geometry of the landscape and the unit of ground distance.
Number of Δt Per Day, Number of Days, Topology, Agent Diameter, Initial Values, Initial θ
The first 3 specify the run parameters. The display is centered at (0,0).
Simulation Length is computed.
Agent Diameter is for display purposes.
For the current release Topology is limited to Torus.
Initial Values and θ specify the initial location and direction of the agent.
CAM Definition
r min, r max, and ψ are used to initialize the corresponding sliders. c_alpha and t_alpha are used in the computations that determines the next location and next kernel, respectively. The Selection Rule specifies the rule used in the final selection of next location. These are described further below.

Zoomable Viewer

Zoomable Viewer

The Zoomable Viewer (shown in its separate frame mode) enables the user to observe specific areas of the landscape or the landscape in its entirety. It responds to both zooming and movement gestures when the Display Window has the focus. Zooming is controlled by the mouse scroll control. To move the landscape drag in the Display Window using the right mouse button; alternatively drag the Motion Tile to locate the landscape in the desired position. The Action Buttons are used to reset and center the Display Window to its original location and zoom level. Clicking the close button on the frame returns the viewer to the main display.


Kernel Definitions and Rules

Kernel Definition

As described above, a kernel is assigned to the agent for the purpose of controlling its movement. The kernel's responsibility is threefold:

  1. Determine an initial pool of candidates on the landscape for the next location;
  2. Create a non-empty subset of potential targets from that pool based on set of criteria specific to the kernel type.
  3. Once a target destination is selected, determine the next kernel.

The initial pool is defined for each kernel type by the blue annulus shown in the figure. It uses the parameters rmin, rmax and ψ, specified on the Parameter Page and by sliders (with θ representing the agent's current trajectory), to define a global prototype for that kernel type.

Kernels are specified as a sequence of phases, Φi, each of which may substitute values of rmin, rmax and ψ, whose values may depend on the global prototype, to specify its candidate pool ; i.e.,

Ktype = [Φ0(r0,min, r0,max, ψ0), Φ1(r1,min, r1,max, ψ1), ...]

Each phase attempts to create a non-empty set of potential targets, but a phase may fail. Phases are tried in sequence until one succeeds. Since the kernel is expected to succeed at making a selection, the last phase in each kernel must be guaranteed to succeed.


BP Kernel Description

The BP kernel consists of 2 phases, Vision and Movement. The Vision phase searches for a resource patch and the Movement phase is deployed when no patch is found. If a patch is found, it must pass a resource level test detailed below in order to be acceptable.

Vision
Vision
Vision
  1. Computes a candidate pool with rmin = 0 and ψ = π /2 (rmax is the same as in the global prototype. If the candidate pool fails to intersect a resource patch, proceed to Movement.
  2. Determine cmax, a cell with maximal resource value within the intersection.
  3. Sum the resources in cmax plus the resources in the Moore neighborhood of cmax.
  4. If this sum exceeds the c_alpha parameter (from the Parameter Page), then the intersection is accepted and a multinomial choice based on resource level is used to select the target.
  5. Otherwise proceed to Movement.


Movement
Movement
  1. Randomly select any cell in the global prototype.


WP Kernel Description

The WP kernel consists of 3 phases, Consuming, Seeking and Rim. The Consuming phase uses a small candidate pool and continues foraging within a patch. The Seeking phase is uses a disk for its candidate pool to expand the foraging range. The Rim phase uses a thin, distant region to jump out of the resource patch.

Consuming
Consuming
  1. Computes a candidate pool with a global prototype in which rmin = 0, rmax is small, and ψ = π / 4
  2. Succeeds if the intersection with the current patch passes the same resource test as described above with the BP kernel; otherwise move to the Seeking phase.
  3. If successful, choose the target using the multinomial selection process described above.


Seeking
Seeking
  1. Computes a candidate pool with rmin = 0, rmax is the same as that used for BP, and ψ = π.
  2. Repeat the resource test. If it fails, move to the Rim phase.
  3. If successful, choose the target using the multinomial selection process described above.


Rim
Rim
  1. Computes a candidate pool with rmin = rmax - 1 and ψ = π.
  2. Randomly select a target from this pool.


Next Kernel Selection

Following each selection of the next location target, a computation is carried out to determine the kernel to be used in the next cycle.

  1. First, a stochastic aging computation is performed: the current kernel is potentially continued with probability p = e-4*Δt - t_alpha / (1 + e-4*Δt - t_alpha), where Δt represents the time spend in the current kernel, and t_alpha is specified for each kernel on the Parameter Page.
  2. If the aging computation determines that the current kernel should continue to be used, a resource computation similar to those used for the BP and WP kernels is carried out. The resource total tot for Moore neighborhood of the current location is computed. If the current kernel is BP and tot > c_alpha, or the current kernel is WP and tot < c_alpha, then a switch to the other kernel takes place despite the results of the aging computation.
  3. If the aging computation indicates that the kernel should switch, then the switch takes place.

Resource Extraction, Depletion and Regrowth

Default

The agent "burns" its resource as it moves across the landscape. Resources are transferred to the agent when it occupies a cell containing resources; correspondingly, a cell's resource may experience regrowth. These dynamics are handled by the Extraction RAM, with 3 possible supplied settings, to which the user may add his or her own versions. This RAM is used to choose among models that compute the next values of the individuals energy/size variable, ht and the cell resource variables cab,t, encoded respectively as next_h and next_c. Current value ht is encoded as agent.h(), and cab,t is encoded as cell.c().

In the default version, agent resource increases by the smaller of k_add and the amount remaining in the cell, and is depleted by the burn rate k_sub times the distance traveled. There is no regrowth.

Alternative 1

In Alternative 1, regrowth is equal to the regrowth rate k_grw times the amount of resource remaining in the cell.

Alternative 2

Alternative 2 is the same as Alternative 1 except it has 20 percent metabolic efficiency (not 100 percent), regrowth is reduced by a factor of 10 to deal with too many decimal points in the slider, and size-dependent traveling efficiency has been added.

  1. Animover 1 uses multinomial selection based on fitness criteria described later.