genius.core.analysis

Class BidSpace

java.lang.Object

genius.core.analysis.BidSpace

public class BidSpace
extends java.lang.Object

A collection of utilityspaces can be viewed as a space in which a bid is assigned multiple point corresponding to the utility of the bid for different agents. We refer to this space as a BidSpace. This class allows to calculate the properties of this space.

Author:

Dmytro Tykhonov, Tim Baarslag, Wouter Pasman

Field Summary

Fields

Modifier and Type	Field and Description
java.util.ArrayList<BidPoint>	bidPoints List of all bidpoints in the domain.

Constructor Summary

Constructors

Constructor and Description
BidSpace(AbstractUtilitySpace... utilityspaces) Default constructor used to construct a multidimensional bidding space.
BidSpace(AbstractUtilitySpace utilityspaceA, AbstractUtilitySpace utilityspaceB, boolean excludeBids) Constructor to createFrom a BidSpace given exactly two utility spaces.
BidSpace(AbstractUtilitySpace utilityspaceA, AbstractUtilitySpace utilityspaceB, boolean excludeBids, boolean skipCheckSpaceB) Constructor which is identical to its three parameter version, except for the argument skipCheckSpaceB.

Method Summary

Modifier and Type	Method and Description
double	distanceToNearestParetoBid(BidPoint bid) Method which given a bid point determines the distance to the nearest Pareto-optimal bid.
BidPoint	getKalaiSmorodinsky() Calculates Kalai-Smorodinsky optimal outcome.
BidPoint	getNash() Calculates the undiscounted Nash optimal outcome.
BidPoint	getNearestBidPoint(double utilA, double utilB, double weightA, double weightB, java.util.ArrayList<Bid> excludeList) Finds the bid with the minimal distance weightA*DeltaUtilA^2+weightB*DeltaUtilB^2 where DeltaUtilA is the difference between given utilA and the actual utility of the bid.
java.util.List<BidPoint>	getParetoFrontier() Returns the Pareto fronier.
java.util.List<Bid>	getParetoFrontierBids() Method which returns a list of the Pareto efficient bids.
double	ourUtilityOnPareto(double opponentUtility) Returns the nearest Pareto-optimal bid given the opponent's utility (agent B).
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

bidPoints

public java.util.ArrayList<BidPoint> bidPoints

List of all bidpoints in the domain.

Constructor Detail

BidSpace

public BidSpace(AbstractUtilitySpace... utilityspaces)
         throws java.lang.Exception

Default constructor used to construct a multidimensional bidding space. Warning: this call iterates over ALL possible bids.

Parameters:

utilityspaces - of which the bidding space consists.

Throws:

java.lang.Exception - is thrown when one of the utility spaces is corrupt.

BidSpace

public BidSpace(AbstractUtilitySpace utilityspaceA,
                AbstractUtilitySpace utilityspaceB,
                boolean excludeBids)
         throws java.lang.Exception

Constructor to createFrom a BidSpace given exactly two utility spaces. The main difference is that if excludeBids is true, then only the bid points are saved. This has is a good way to save memory. Warning: this call iterates over ALL possible bids.

Parameters:

utilityspaceA - utilityspace of agent A.

utilityspaceB - utilityspace of agent B.

excludeBids - if the real bids should be saved or not.

Throws:

java.lang.Exception - is thrown when one of the utility spaces is corrupt.

BidSpace

public BidSpace(AbstractUtilitySpace utilityspaceA,
                AbstractUtilitySpace utilityspaceB,
                boolean excludeBids,
                boolean skipCheckSpaceB)
         throws java.lang.Exception

Constructor which is identical to its three parameter version, except for the argument skipCheckSpaceB. Independent of the value of this parameter, this constructor skips the security checks for the second utilityspace. This is interesting if you use the utility of an opponent model in which some variables of the utilityspace may not be set. Warning: this call iterates over ALL possible bids.

Parameters:

utilityspaceA - utilityspace of agent A.

utilityspaceB - utilityspace of agent B.

excludeBids - if the real bids should be saved or not.

skipCheckSpaceB - skip security checks for the utilityspace of agent B.

Throws:

java.lang.Exception - if something goes wrong when calculating the utility of a bid.

Method Detail

getParetoFrontier

public java.util.List<BidPoint> getParetoFrontier()
                                           throws java.lang.Exception

Returns the Pareto fronier. If the Pareto frontier is unknown, then it is computed using an efficient algorithm. If the utilityspace contains more than 500000 bids, then a suboptimal algorithm is used.

Returns:

The Pareto frontier. The order is ascending utilityA.

Throws:

java.lang.Exception - if the utility of a bid can not be calculated.

getParetoFrontierBids

public java.util.List<Bid> getParetoFrontierBids()
                                          throws java.lang.Exception

Method which returns a list of the Pareto efficient bids.

Returns:

Pareto-efficient bids.

Throws:

java.lang.Exception - if the utility of a bid cannot be calculated

getKalaiSmorodinsky

public BidPoint getKalaiSmorodinsky()
                             throws java.lang.Exception

Calculates Kalai-Smorodinsky optimal outcome. Assumes that Pareto frontier is already built. Kalai-Smorodinsky is the point on paretofrontier that has least difference in utilities for A and B.

Returns:

the Kalai-Smorodinsky BidPoint.

Throws:

java.lang.Exception - when the Pareto frontier is invalid.

getNash

public BidPoint getNash()
                 throws java.lang.Exception

Calculates the undiscounted Nash optimal outcome. Assumes that Pareto frontier is already built. Nash is the point on paretofrontier that has max product of utilities for A and B.

Returns:

the Nash BidPoint.

Throws:

java.lang.Exception - when the Pareto frontier is invalid.

ourUtilityOnPareto

public double ourUtilityOnPareto(double opponentUtility)
                          throws java.lang.Exception

Returns the nearest Pareto-optimal bid given the opponent's utility (agent B).

Parameters:

opponentUtility - the utility for the opponent.

Returns:

the utility of us on the pareto curve.

Throws:

java.lang.Exception - if getPareto fails or other cases, e.g. paretoFrontier contains utilityB = NaN, which may occur if the opponent model creating the utility space is corrupt.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

Returns:

string representation of the BidSpace, which is basically a long list of all bid its bid points.

getNearestBidPoint

public BidPoint getNearestBidPoint(double utilA,
                                   double utilB,
                                   double weightA,
                                   double weightB,
                                   java.util.ArrayList<Bid> excludeList)

Finds the bid with the minimal distance weightA*DeltaUtilA^2+weightB*DeltaUtilB^2 where DeltaUtilA is the difference between given utilA and the actual utility of the bid.

Parameters:

utilA - the agent-A utility of the point to be found.

utilB - the agent-B utility of the point to be found.

weightA - weight in A direction.

weightB - weight in B direction.

excludeList - Bids to be excluded from the search.

Returns:

best point, or null if none remaining.

distanceToNearestParetoBid

public double distanceToNearestParetoBid(BidPoint bid)

Method which given a bid point determines the distance to the nearest Pareto-optimal bid. If the distance is small, than the bid is near Pareto-optimal.

Parameters:

bid - for which the smallest distance to the Pareto frontier is found.

Returns:

distance to the nearest Pareto-optimal bid.