BaseVOIElicitor

class negmas.elicitation.BaseVOIElicitor(strategy: negmas.elicitation.EStrategy, user: User, *, dynamic_query_set=False, queries=None, adaptive_answer_probabilities=True, each_outcome_once=False, update_related_queries=True, **kwargs)[source]

Bases: negmas.elicitation.BaseElicitor

Base class for all value of information (VOI) elicitation algorithms

Parameters
  • strategy – The elicitation strategy. It is only used if dynamic_query_set is set. In that case, the strategy is used to compile the set of all possible queries during construction. If using dynamic_query_set pass None for the strategy.

  • user – The User to elicit.

  • base_negotiator – The base negotiator used for proposing and responding.

  • dynamic_query_set – If given, the user of the object is supposed to manage the queries manually and the strategy is not used.

  • queries – An optinal list of queries to use.

  • adaptive_answer_probabilities – If True, answer probabilities will not be considered equal for all possible answers. The probability of getting an answer will be based on the current estimate of the utility value distribution.

  • expector_factory – A Callable used to estimate real-valued utilities given a distribution.

  • opponent_model_factory – A Callable used to construct the opponent model.

  • single_elicitation_per_round – If set, a single query is allowed per round.

  • continue_eliciting_past_reserved_val – If set, elicition will continue even if the estimated utility of an outcome is less than the reserved value.

  • epsilon – A small number used to stop elicitation when the uncertainty in the utility value is within it.

  • true_utility_on_zero_cost – If set, the true utility will be elicited for outcomes if the elicitation cost is zero.

  • each_outcome_once – If set, each outcome is to be offered exactly once.

  • update_related_queries – If set, queries that are related to one that was asked and answered will get updated based on the answer.

Methods Summary

add_query(qeeu)

Adds a query to the heap of queries

before_eliciting()

Called every round before trying to elicit.

best_offer(state)

The best offer and its corresponding utility

best_offers(n)

Returns the best offer repeated n times

can_elicit()

Always can elicit

elicit_single(state)

Called to conduct a single eliciataion act.

init_elicitation(ufun[, queries])

Initializes the elicitation process once.

init_optimal_policy()

Gets the optimal policy given Negotiator utility_priors.

init_query_eeus()

Updates the heap eeu_query which has records of (-EEU, quesion)

on_opponent_model_updated(outcomes, old, new)

Called whenever the opponent model is updated.

update_optimal_policy(index, outcome, oldu, newu)

Updates the optimal policy after a change to the utility value of some outcome.

utility_on_rejection(outcome, state)

Estimated utility if this outcome rejected at this state.

Methods Documentation

add_query(qeeu: Tuple[float, int])None[source]

Adds a query to the heap of queries

Parameters

qeeu – A Tuple giving (-EEU, query_index)

Remarks:
  • Note that the first member of the tuple is minus the EEU

  • The sedond member of the tuple is an index of the query in the queries list (not the query itself).

before_eliciting()[source]

Called every round before trying to elicit. Does nothing

best_offer(state: negmas.common.MechanismState)Tuple[Optional[Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]]], float][source]

The best offer and its corresponding utility

Parameters

state – The mechanism state

Remarks:
  • It will return (None, reserved-value) if the best outcome has a utility less than the reserved value.

  • It uses the internal eu_policy heap to find the best outcome.

  • If each-outcome-once is set, the best outcome is popped from the heap which prevents it from ever being selected again.

best_offers(n: int)List[Tuple[Optional[Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]]], float]][source]

Returns the best offer repeated n times

can_elicit()bool[source]

Always can elicit

elicit_single(state: negmas.common.MechanismState)[source]

Called to conduct a single eliciataion act.

Parameters

state – The mechanism state

Remarks:
  • It returns False ending eliciatation if eeu_query is empty or can_elicit returns False

  • The algorithm outline is as follows:

    1. Pops the top query with its EEU from the heap

    2. elicitation is stopped if the top query is None, the eeu is less than the current EEU, or the EEU after asking will be less than the reserved value.

    3. If dynamic_query_set, the strategy is invoked to get the next query, otherwise, the user is asked the top query and the related queries are updated.

    4. The expected utility is updated base on the answer received from the user and update_optimal_policy is called followed by init_query_eeus.

init_elicitation(ufun: Optional[Union[IPUtilityFunction, UtilityDistribution]], queries: Optional[List[negmas.elicitation.Query]] = None, **kwargs)None[source]

Initializes the elicitation process once.

Remarks:
  • After calling parent, it checks that dynamic_query_set, queries and strategy settings are consistent.

  • It then calls, init_optimal_policy to initialize the optimal policy

  • The set of queries is updated from the strategy if needed and a mapping from outcomes to their queries is created if update_related_queries is set to be used for updating related queries later.

  • It then calls init_query_eeus to initialize the EEU of all queries.

abstract init_optimal_policy()None[source]

Gets the optimal policy given Negotiator utility_priors.

The optimal plicy should be sorted ascendingly on -EU or -EU * Acceptance

init_query_eeus()None[source]

Updates the heap eeu_query which has records of (-EEU, quesion)

on_opponent_model_updated(outcomes: List[Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]]], old: List[float], new: List[float])None[source]

Called whenever the opponent model is updated.

Parameters
  • outcomes – The updated outomes. None means all outcomes

  • old – The old acceptance probabilities

  • new – The new acceptance probabilities

Remarks:

It calls init_optimal_policy and init_query_eeus if any old value is not equal to a new value.

update_optimal_policy(index: int, outcome: Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]], oldu: float, newu: float)[source]

Updates the optimal policy after a change to the utility value of some outcome.

Parameters
  • outcome – The outcome whose utiltiy have changed

  • oldu – The old utility

  • newu – The new utility

Remarks:

It just calls update_optimal_policy

utility_on_rejection(outcome: Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]], state: negmas.common.MechanismState)Union[negmas.helpers.Distribution, float][source]

Estimated utility if this outcome rejected at this state.

Parameters
  • outcome – The outcome tested

  • state – The mechanism state

Remarks:
  • MUST be implemented by any Elicitor.