# BasePandoraElicitor¶

class negmas.elicitation.BasePandoraElicitor(user: User, strategy: EStrategy, *, base_negotiator: negmas.sao.negotiators.SAONegotiator = <negmas.sao.negotiators.AspirationNegotiator object>, deep_elicitation: bool, opponent_model_factory: Optional[Callable[[AgentMechanismInterface], DiscreteAcceptanceModel]] = <function BasePandoraElicitor.<lambda>>, expector_factory: Union[Expector, Callable[[], Expector]] = <class 'negmas.elicitation.expectors.MeanExpector'>, single_elicitation_per_round=False, continue_eliciting_past_reserved_val=False, epsilon=0.001, true_utility_on_zero_cost=False, assume_uniform=True, user_model_in_index=True, precalculated_index=False, incremental=True, max_aspiration=0.99, aspiration_type='boulware')[source]

The base class of all Pandora’s box based algorithms.

Parameters
• user – A User object that can be elicited

• strategy – An elicitation strategy that determines the questions to be asked and their order.

• base_negotiator – The base negotiator used for responding and proposing

• deep_elicitation – If True, a single elicitation act (elicit_single) will elicit the utility value of an outcome until its uncertainty is under epsilon.

• opponent_model_factory – A callable to create opponent models. An opponent model is used to estimate acceptance probability of outcomes.

• expector_factory – A callable to create an Expector

• single_elicitation_per_round – If True, only a single elicitation act (call to elicit_single is allowed per negotiation round.

• continue_eliciting_past_reserved_val – If True, continue elicitation even if the estimated utility is under the reserved value.

• epsilon – A small number to represent small uncertainty after which no more elicitation is done.

• true_utility_on_zero_cost – If True, zero cost will force the final elicited value of any outcome to exactly match the utility function. If False, the final utility value after elicitation may be within epsilon from the true value.

• assume_uniform – If True, assume that all utility distributions are uniform

• user_model_in_index – Use the user model in the index

• precalculated_index – The index is calculated once and never updated when the opponent model probabilities of acceptance change.

• incremental – Only valid if precalculated_index is not set. If set, only the outcomes for which the opponemt model acceptance probability have changed will be updated whenever such a change occures. Otherwise, all outcomes will be updated on every change.

• max_aspiration – Maximum aspiration.

• aspiration_type – Aspiration type. Can be “boulware”, “linear”, “conceder” or a numric exponent.

Methods Summary

 Called before starting elicitation at every negotiation round. Checks whether there are any unknowns in the unknowns list. do_elicit(outcome, state) Does a real elicitation step. elicit_single(state) Does a single elicitation act init_elicitation(ufun, **kwargs) Initializes the elicitation process (called only once). Initializes the unknowns list which is a list of Tuples [-u(o), o] for o in outcomes. Returns the maximum estimaged utility and the corresponding outocme on_opponent_model_updated(outcomes, old, new) Called when the opponent model is updated. Removes the best offer from the unkonwn list and returns it. update_best_offer_utility(outcome, u) Updates the unknown list (and makes sure it is a heap) given the given utility value for the given outcome. Updates the cutoff utility under which no elicitation is done. utility_on_rejection(outcome, state) Uses the aspiration level as the utility of rejection. z_index([updated_outcomes]) Update the internal z-index or create it if needed.

Methods Documentation

before_eliciting()[source]

Called before starting elicitation at every negotiation round.

Remarks:
• It just updates cutoff utility

can_elicit()bool[source]

Checks whether there are any unknowns in the unknowns list.

do_elicit(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]

Does a real elicitation step.

Parameters
• outcome – The outcome to elicit

• state – The state at which elicitation is happening

Remarks:
• If deep_elicitation is set, the strategy is applied until the uncertainty in the utility value for outcome is less than the accuracty limit otherwise, apply it once.

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

Does a single elicitation act

Parameters

state – mechanism state

Remarks:

The process goes as follows:

1. Find the offer to elicit using offer_to_elicit.

2. If the utility of that offer is less than the cutoff utility, or the best offer to elicit is None, stop eliciting and return.

3. call do_elicit once.

4. update the distribution of the elicited outcome

5. add the elicited outcome to the offerable outcomes

6. If the utility of the best outcome is a number, remove it from the unknown outcomes list otherwise jsut update it

7. Update the cutoff utility and elicitation history.

init_elicitation(ufun: Optional[Union[IPUtilityFunction, UtilityDistribution]], **kwargs)[source]

Initializes the elicitation process (called only once).

Remarks:

init_unknowns()[source]

Initializes the unknowns list which is a list of Tuples [-u(o), o] for o in outcomes.

offer_to_elicit()Tuple[float, Optional[int]][source]

Returns the maximum estimaged utility and the corresponding outocme

Remarks:
• This method assumes that each element of the unkown list is a tuple of negative the utility value and the outcome.

• It also assumest that the first item in the unknown list contains the outocme with maximum estimated utility and the negative of the corresponding estimated utility.

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 when the opponent model is updated.

Parameters
• outcomes – changed outcomes

• old – old probabilities of acceptance

• new – new probabilities of acceptance

Remarks:

Updates the unknown list only if precalculated_index was not set.

remove_best_offer_from_unknown_list()Tuple[float, int][source]

Removes the best offer from the unkonwn list and returns it.

update_best_offer_utility(outcome: Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]], u: Union[negmas.helpers.Distribution, float])[source]

Updates the unknown list (and makes sure it is a heap) given the given utility value for the given outcome.

update_cutoff_utility()None[source]

Updates the cutoff utility under which no elicitation is done.

Remarks:
• By default it uses $$max_{o \in \Omega \cup \phi}{u(o)}$$ for all outcomes $$o \in \Omega$$ and the None outcome representing reserved value

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]

Uses the aspiration level as the utility of rejection.

Remarks:
z_index(updated_outcomes: Optional[List[Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]]]] = None)[source]

Update the internal z-index or create it if needed.

Parameters

updated_outcomes – A list of the outcomes with updated utility values.