libs/helpers-SEU.nls

Handling all SEU functions, dealing with agent’s process of taking decisions.

Summary
libs/helpers-SEU.nlsHandling all SEU functions, dealing with agent’s process of taking decisions.
choose-actionAgent takes a decision about the next action to take.
calculate-best-actionCalculates the best action for the given possible destinations
calculate-utilityCalculates subjective expected utility for the given action, where action consists of 3 ordered items: node-to-take, edge-to-take, technology-to-use
calculate-p-technology-preferenceCalculates p-value for SEU calculation for a “hidden” goal, advancing some given technology, independent from situational parameters.
calculate-p-costsCalculates p-value for SEU calculation for a goal like money-saving.
calculate-p-moneyCalculates p-value for SEU calculation for a goal like money-saving.
calculate-p-costs-simpleCalculates p-value for SEU calculation for a goal like money-saving.
calculate-p-money-simpleCalculates p-value for SEU calculation for a goal like money-saving.
linear-functionCalculates y-value of a point P3 on a straight line, given by two (different!)
calculate-p-durationcalculates p-value based on (given) duration of using an edge.
calculate-pHolds metrics used to calculate probabilities “p” used in SEU-calculation.
node-condition-type-pReports 1 if the cost-benefits-value in my-dimension equals my-value.
print-p-calculationsPrints all p-calculation formulas for debugging purposes
agent-technology-switch-allowedReports, whether an agent my switch technologies on the given node (based on item 2 node-costs-benefits-agents).
check-pEnsures that the int given as input does not exceed the limits of [0,1], because p-values are probabilities and thus restricted by these values.
compute-neighborsComputes all direct neighbors which are are connected to the given node.
check-edge-aliveChecks, if edges are still alive and thus may be used in choose-action.

choose-action

to-report choose-action

Agent takes a decision about the next action to take.  This includes a node to visit, as well as the edge and the technology used to reach the node.  Choosing an action depends on situational constraints like the position the agent is actually located and on his rating of goals, as the agent will calculate the subjective expexted utility (SEU) in calculate-utility for each of the actions available.

Returns

ordered listnode to reach, edge to use, technology to use.
empty listif there is no action available for the agent.

calculate-best-action

to-report calculate-best-action [possible-destinations]

Calculates the best action for the given possible destinations

Parameters

possible-destinationscontains a set of technologies for each node/edge combination

Returns

listcontains exactly one action, given as node, edge, technology, represents the best action out of the given possible destinations and based on calculated subjective utility values
empty-listif there is no action available at all (should not happen normally).

calculate-utility

to-report calculate-utility [my-action]

Calculates subjective expected utility for the given action, where action consists of 3 ordered items: node-to-take, edge-to-take, technology-to-use

Parameter

my-actionordered list of random node-to-take, edge-to-take, technology-to-use

Returns

floating point numberutility of the given action, based on SEU calculation.  U-values are agents-own, p-values calculated on the fly

calculate-p-technology-preference

to-report calculate-p-technology-preference [my-technology-name my-technology]

Calculates p-value for SEU calculation for a “hidden” goal, advancing some given technology, independent from situational parameters.

Parameter

my-technology-namethe name of the technology that should be preferred
my-technology-namethe technology that is part of the action actually handled

calculate-p-costs

to-report calculate-p-costs [my-vector my-dimension my-time-horizon my-factor]

Calculates p-value for SEU calculation for a goal like money-saving.  Besides integrating the costs of an action to this calculation, the pay-off gained in previous steps (aka “bank balance”) is taken into consideration.  This function assumes that the semantics is bases on the term “costs”.  Thus, a positive value indicates costs (or in other words: money that must be paid), a negative value can be accounted as income.

Paramters

my-vectorthe costs-benefits-vector of the action for which the p-value shall be calculated
my-dimensionint, the “costs” dimension’s number
my-time-horizonstring, short- or long time (the respective payoff will be used)
my-factoror borderline, indicating how far the costs-payoff shall influence the resulting p-value.

Returns

floating point numberp-value

calculate-p-money

to-report calculate-p-money [my-vector my-dimension my-time-horizon my-factor]

Calculates p-value for SEU calculation for a goal like money-saving.  Besides integrating the costs (money-dimension) of an action to this calculation, the pay-off gained in previous steps (aka “bank balance”) is taken into consideration.  This function assumes that the semantics is bases on the term “money”.  Thus, a negative value indicates costs (or in other words: money that must be paid), a positive value can be accounted as income.

Paramters

my-vectorthe costs-benefits-vector of the action for which the p-value shall be calculated
my-dimensionint, the “money’s” dimension’s number
my-time-horizonstring, short- or long time (the respective payoff will be used)
my-factoror borderline, indicating how far the costs-payoff shall influence the resulting p-value.

Returns

floating point numberp-value

calculate-p-costs-simple

to-report calculate-p-costs-simple [my-vector my-dimension my-time-horizon my-factor]

Calculates p-value for SEU calculation for a goal like money-saving.  Uses costs of the action and a borderline as parameters, only.

Paramters

my-vectorthe costs-benefits-vector of the action for which the p-value shall be calculated
my-dimensionint, the “costs” dimension’s number
my-time-horizonstring, short- or long time (the respective payoff will be used)
my-factorborderline, indicating which values are evaluated as “too expensive”

Returns

floating point numberp-value

calculate-p-money-simple

Calculates p-value for SEU calculation for a goal like money-saving.  Uses money-change induced by the action and a borderline as parameters, only.

linear-function

to-report linear-function [x1 y1 x2 y2 x]

Calculates y-value of a point P3 on a straight line, given by two (different!) points on that line (P1/P2) as well as the x-value of point P3.

Parameters

x1x-value of P1
y1y-value of P1
x2x-value of P2
y2y-value of P2
xx-value of point P3 to be calculated

Returns

floating point numbery-value of point P3 to be calculated

calculate-p-duration

to-report calculate-p-duration [my-duration upper-border]

calculates p-value based on (given) duration of using an edge.  Upper border indicates borderline with p=0

Parameters

my-durationint, length of duration (ticks)
upper-bordertime-value (ticks) which shall lead to a p-value of 0

Returns

floating point numberp-value for the given parameters

calculate-p

to-report calculate-p [my-metric my-dimension my-vector my-parameter]

Holds metrics used to calculate probabilities “p” used in SEU-calculation.  Some of these were implemented for very special purposes and scenarios.

Parameters

my-metriccalculation-method to be used
my-dimensiondimension (of limits) to be considered
my-vectorvector with situational parameters to be used within calculation
my-parameterparameter to be used within the respective metric, semantics may differ between metrics.

Returns

floating point numberp-value for the given parameters

node-condition-type-p

to-report node-condition-type-p [my-dimension my-value my-node]

Reports 1 if the cost-benefits-value in my-dimension equals my-value.  May be used by specifying in input files and using runresult.

Parameter

my-nodenode-object, indicating the node whose ID shall be compared with those goven by ID within <agent-destinations-once>

Returns

int1 or 0.

print-p-calculations

to print-p-calculations

Prints all p-calculation formulas for debugging purposes

agent-technology-switch-allowed

to-report agent-technology-switch-allowed? [my-node]

Reports, whether an agent my switch technologies on the given node (based on item 2 node-costs-benefits-agents).

Parameters

my-nodenode on which technology shall be switched

Returns

booltrue, if agent may switch technology on my-node, false otherwise

check-p

to-report check-p [my-p]

Ensures that the int given as input does not exceed the limits of [0,1], because p-values are probabilities and thus restricted by these values.

Parameter

my-pinteger to be checked

Returns

intinput-value, if within [0,1], 0 if below, 1 if above.

compute-neighbors

Computes all direct neighbors which are are connected to the given node.  Boundary conditions: Neighbor as well as the edge connecting it are “alive” and there exists a technology that may be used on the connected node as well as on the connecting edge.

Parameter

my-nodestarting node.  This will in most cases be the node the agent is actually on.

Returns

ordered nested listall nodes reacheable from the one given as input as well as the technology->technology-names indicating which technologies may be used to reach the node.  Basic version implemented: report all possible nodes, if they can be reached by a technology-allowed on the edge that is allowd on the node, too!  Future extension: As this may heavily depend on the mode of governance or the net-logics, rework this function in the future.
empty listif there is no edge to any of the neighbor-nodes usable with a technology allowed on the neighbor-nodes as well.

check-edge-alive

to-report check-edge-alive [my-from-node my-to-nodes]

Checks, if edges are still alive and thus may be used in choose-action.

Parameters

my-from-nodenode the edges to check start from
my-to-nodeslist of nodes, each of them the end of an edge

Returns

listof nodes, including only those nodes from my-to-nodes, that can be reached with an edge still alive.
to-report choose-action
Agent takes a decision about the next action to take.
to-report calculate-best-action [possible-destinations]
Calculates the best action for the given possible destinations
to-report calculate-utility [my-action]
Calculates subjective expected utility for the given action, where action consists of 3 ordered items: node-to-take, edge-to-take, technology-to-use
Hold the nodes’ information concerning their characteristics as well as actual values, indicating their state.
Holds the edges
Holds the technologies
to-report calculate-p-technology-preference [my-technology-name my-technology]
Calculates p-value for SEU calculation for a “hidden” goal, advancing some given technology, independent from situational parameters.
to-report calculate-p-costs [my-vector my-dimension my-time-horizon my-factor]
Calculates p-value for SEU calculation for a goal like money-saving.
to-report calculate-p-money [my-vector my-dimension my-time-horizon my-factor]
Calculates p-value for SEU calculation for a goal like money-saving.
to-report calculate-p-costs-simple [my-vector my-dimension my-time-horizon my-factor]
Calculates p-value for SEU calculation for a goal like money-saving.
to-report linear-function [x1 y1 x2 y2 x]
Calculates y-value of a point P3 on a straight line, given by two (different!)
to-report calculate-p-duration [my-duration upper-border]
calculates p-value based on (given) duration of using an edge.
to-report calculate-p [my-metric my-dimension my-vector my-parameter]
Holds metrics used to calculate probabilities “p” used in SEU-calculation.
to-report node-condition-type-p [my-dimension my-value my-node]
Reports 1 if the cost-benefits-value in my-dimension equals my-value.
to print-p-calculations
Prints all p-calculation formulas for debugging purposes
to-report agent-technology-switch-allowed? [my-node]
Reports, whether an agent my switch technologies on the given node (based on item 2 node-costs-benefits-agents).
to-report check-p [my-p]
Ensures that the int given as input does not exceed the limits of [0,1], because p-values are probabilities and thus restricted by these values.
to-report check-edge-alive [my-from-node my-to-nodes]
Checks, if edges are still alive and thus may be used in choose-action.
Hold the technology objects.
Holds the agents and information like the technology owned, actual state based on previous actions and variables used for calculate-utility (SEU calculation)
Hold the nodes.
the technologie’s name.
Close