source: src/main/java/genius/core/utility/AbstractUtilitySpace.java

Last change on this file was 232, checked in by Adel Magra, 5 years ago

Created a User class that implements an elicit functionality.

Created a Top_3 Agent with the BOA framework to showcase this functionality.
File size: 7.6 KB
Line 
1package genius.core.utility;
2
3import genius.core.Bid;
4import genius.core.Domain;
5import genius.core.timeline.TimeLineInfo;
6import genius.core.timeline.Timeline;
7
8/**
9 * Implements the basic functionality of {@link UtilitySpace} but does not
10 * implement the details. Adds the discountFactor as a mechanism to implement
11 * discount. A filename is remembered. Also adds default functionality to
12 * support implementation of concrete utility spaces.
13 */
14@SuppressWarnings("serial")
15public abstract class AbstractUtilitySpace implements UtilitySpace {
16
17 public static final String DISCOUNT_FACTOR = "discount_factor";
18 public static final String RESERVATION = "reservation";
19
20 private Domain domain;
21 protected String fileName;
22 private double discountFactor = 1;
23 private Double fReservationValue = null;
24 private UtilitySpaceTools ustools;
25
26 /**
27 * sets domain and tries to load the file into XML root.
28 *
29 * @param dom
30 * the {@link Domain} to load
31 */
32 public AbstractUtilitySpace(Domain dom) {
33 domain = dom;
34 ustools = new UtilitySpaceTools(this);
35 }
36
37 @Override
38 public Domain getDomain() {
39 return domain;
40 }
41
42 /**
43 * @param newRV
44 * new reservation value.
45 */
46 public void setReservationValue(double newRV) {
47 fReservationValue = newRV;
48 }
49
50 /**
51 * @param newDiscount
52 * new discount factor.
53 */
54 public void setDiscount(double newDiscount) {
55 discountFactor = validateDiscount(newDiscount);
56 }
57
58 /**
59 * The reservation value is the least favourable point at which one will
60 * accept a negotiated agreement. Also sometimes referred to as the walk
61 * away point.
62 * <p>
63 * This is value remains constant during the negotiation. However, by
64 * default, the reservation value descreases with time. To obtain the
65 * discounted version of the reservation value, use
66 * {@link #getReservationValueWithDiscount(TimeLineInfo)}.
67 *
68 * @return undiscounted reservation value of the preference profile (may be
69 * null).
70 */
71 public Double getReservationValue() {
72 return getReservationValueUndiscounted();
73 }
74
75 /**
76 * Equivalent to {@link #getReservationValue()}, but always returns a double
77 * value. When the original reservation value is <b>null</b> it returns the
78 * default value 0.
79 *
80 * @return undiscounted reservation value of the preference profile (never
81 * null).
82 * @see #getReservationValue()
83 */
84 public double getReservationValueUndiscounted() {
85 if (fReservationValue == null)
86 return 0;
87 return fReservationValue;
88 }
89
90 /**
91 * The discounted version of {@link #getReservationValue()}.
92 *
93 * @param time
94 * at which we want to know the utility of the reservation value.
95 * @return discounted reservation value.
96 */
97 public double getReservationValueWithDiscount(double time) {
98 Double rv = getReservationValue();
99 if (rv == null || rv == 0)
100 return 0;
101
102 return discount(rv, time);
103 }
104
105 /**
106 * The discounted version of {@link #getReservationValue()}.
107 *
108 * @param timeline
109 * specifying the current time in the negotiation.
110 * @return discounted reservation value.
111 */
112 public double getReservationValueWithDiscount(TimeLineInfo timeline) {
113 return getReservationValueWithDiscount(timeline.getTime());
114 }
115
116 /**
117 * @return true if the domain features discounts.
118 */
119 public boolean isDiscounted() {
120 return discountFactor < 1.0;
121 }
122
123 /**
124 * @return Discount factor of this preference profile.
125 */
126 public final double getDiscountFactor() {
127 return discountFactor;
128 }
129
130 /**
131 * @return filename of this preference profile.
132 */
133 public String getFileName() {
134 return fileName;
135 }
136
137 /**
138 * Let d in (0, 1) be the discount factor. (If d &le; 0 or d &ge; 1, we
139 * assume that d = 1.) Let t in [0, 1] be the current time, as defined by
140 * the {@link Timeline}. We compute the <i>discounted</i> utility
141 * discountedUtility as follows:
142 *
143 * discountedUtility = originalUtility * d^t.
144 *
145 * For t = 0 the utility remains unchanged, and for t = 1 the original
146 * utility is multiplied by the discount factor. The effect is almost linear
147 * in between. Works with any utility space.
148 *
149 * @param bid
150 * of which we are interested in its utility.
151 * @param timeline
152 * indicating the time passed in the negotiation.
153 * @return discounted utility.
154 */
155 public double getUtilityWithDiscount(Bid bid, TimeLineInfo timeline) {
156 double time = timeline.getTime();
157 return getUtilityWithDiscount(bid, time);
158 }
159
160 /**
161 * See {@link #getUtilityWithDiscount(Bid, double)}.
162 *
163 * @param bid
164 * of which we want to know the utility at the given time.
165 * @param time
166 * at which we want to know the utility of the bid.
167 * @return discounted utility.
168 */
169 public double getUtilityWithDiscount(Bid bid, double time) {
170 double util = 0;
171 try {
172 util = getUtility(bid);
173 } catch (Exception e) {
174 e.printStackTrace();
175 }
176
177 double discountedUtil = discount(util, time);
178 return discountedUtil;
179 }
180
181 /**
182 * Specific implementation for discount, based on a discount factor.
183 * Computes:
184 *
185 * discountedUtil = util * Math.pow(discount, time).
186 *
187 * Checks for bounds on the discount factor and time.
188 */
189 @Override
190 public Double discount(double util, double time) {
191 return discount(util, time, discountFactor);
192 }
193
194 /**
195 * Computes:
196 *
197 * discountedUtil = util * Math.pow(discount, time).
198 *
199 * Checks for bounds on the discount factor and time.
200 *
201 * @param util
202 * undiscounted utility.
203 * @param time
204 * at which we want to know the discounted utility.
205 * @param discountFactor
206 * of the preference profile.
207 * @return discounted version of the given utility at the given time.
208 */
209 private double discount(double util, double time, double discountFactor) {
210 double discount = discountFactor;
211 if (time < 0) {
212 System.err.println("Warning: time = " + time
213 + " < 0, using time = 0 instead.");
214 time = 0;
215 }
216 if (time > 1) {
217 System.err.println("Warning: time = " + time
218 + " > 1, using time = 1 instead.");
219 time = 1;
220 }
221
222 double discountedUtil = util * Math.pow(discount, time);
223 return discountedUtil;
224 }
225
226 protected double validateDiscount(double df) {
227 if (df < 0 || df > 1) {
228 System.err.println(
229 "Warning: discount factor = " + df + " was discarded.");
230 }
231
232 if (df <= 0 || df > 1) {
233 df = 1;
234 }
235 return df;
236 }
237
238 /**
239 * Returns the maximum bid in the utility space. This is only supported for
240 * linear utility spaces. Totally revised, brute-force search now.
241 *
242 * @return a bid with the maximum utility value attainable in this util
243 * space
244 * @throws Exception
245 * if there is no bid at all in this util space.
246 */
247 public final Bid getMaxUtilityBid() throws Exception {
248 return ustools.getMaxUtilityBid();
249 }
250
251 /**
252 * Returns the worst bid in the utility space. This is only supported for
253 * linear utility spaces.
254 *
255 * @return a bid with the lowest possible utility
256 * @throws Exception
257 * if there is no bid at all in the util space
258 */
259 public Bid getMinUtilityBid() throws Exception {
260 return ustools.getMinUtilityBid();
261 }
262
263 /**
264 * Check if this utility space is ready for negotiation. To be so, the
265 * domain must match the given domain and the space must be complete.
266 *
267 * @param dom
268 * is the domain in which nego is taking place
269 * @throws Exception
270 * if utility space is incomplete (@see isComplete())
271 */
272 public void checkReadyForNegotiation(Domain dom) throws Exception {
273 ustools.checkReadyForNegotiation(dom);
274 }
275
276 @Override
277 public String getName() {
278 if (fileName == null) {
279 return "domain@" + Integer.toHexString(hashCode());
280 }
281 return fileName;
282 }
283}
Note: See TracBrowser for help on using the repository browser.