LinDiscountedUFun
- class negmas.preferences.LinDiscountedUFun(ufun, cost=None, factor='current_step', power=1.0, name=None, reserved_value=- inf, dynamic_reservation=True, id=None, **kwargs)[source]
Bases:
negmas.preferences.discounted.DiscountedUtilityFunction
A utility function with linear discounting based on some factor of the negotiation
- Parameters
ufun (BaseUtilityFunction) – The utility function that is being discounted
cost (Optional[float]) – discount factor
factor (callable -> must receive a mechanism info object and returns a float representing the) – str -> The name of the AgentMechanismInterface variable based on which discounting operate
factor –
power (float | None) – A power to raise the total cost to before discounting it from the utility_function value
Attributes Summary
Returns the utility_function base type ignoring discounting and similar wrappings.
The unique ID of this entity
A convenient name of the entity (intended primarily for printing/logging/debugging).
- rtype
- rtype
Returns the utility_function type.
- rtype
The unique ID of this entity
Methods Summary
__call__
(offer)Calculate the utility_function value for a given outcome at the given negotiation state.
argrank
(outcomes[, descending])Ranks the given list of outcomes with weights.
argrank_with_weights
(outcomes[, descending])Ranks the given list of outcomes with weights.
best
()- rtype
changes
()- rtype
checkpoint
(path[, file_name, info, ...])Saves a checkpoint of the current object at the given path.
checkpoint_info
(file_name)Returns the information associated with a dump of the object saved in the given file
create
(*args, **kwargs)Creates an object and returns a proxy to it.
difference
(first, second)Returns a numeric difference between the utility of the two given outcomes
difference_prob
(first, second)Returns a numeric difference between the utility of the two given outcomes
eu
(offer)calculates the expected utility value of the input outcome
eval
(offer)eval_normalized
(offer[, above_reserve, ...])Evaluates the ufun normalizing the result between zero and one
eval_on_state
(offer[, nmi, state])Evaluates the offer given a session and state
extreme_outcomes
([outcome_space, issues, ...])- rtype
tuple[Outcome, Outcome]
from_checkpoint
(file_name[, return_info])Creates an object from a saved checkpoint
from_dict
(d)from_genius
(file_name, **kwargs)Imports a utility function from a GENIUS XML file.
from_xml_str
(xml_str, issues[, ...])Imports a utility function from a GENIUS XML string.
invert
([inverter])Inverts the ufun, initializes it and caches the result.
is_better
(first, second)Compares two offers using the
ufun
returning whether the first is strictly better than the secondis_equivalent
(first, second)Compares two offers using the
ufun
returning whether the first is strictly equivelent than the secondis_not_better
(first, second)Compares two offers using the
ufun
returning whether the first is worse or equivalent than the secondis_not_worse
(first, second)Is
first
at least as good assecond
Does the utiltiy of an outcome depend on the
NegotiatorMechanismInterface
?Does the utiltiy of an outcome depend on the negotiation state?
Are the preferences stationary (i.e.
Does the utiltiy of an outcome depend on factors outside the negotiation?
is_worse
(first, second)Compares two offers using the
ufun
returning whether the first is strictly worse than the secondmax
()- rtype
min
()- rtype
minmax
([outcome_space, issues, outcomes, ...])Finds the range of the given utility function for the given outcomes
normalize
([to, minmax])- rtype
T
normalize_for
([to, outcome_space, issues, ...])- rtype
T
random
(issues[, reserved_value, normalized, ...])Generates a random ufun of the given type
rank
(outcomes[, descending])Ranks the given list of outcomes with weights.
rank_with_weights
(outcomes[, descending])Ranks the given list of outcomes with weights.
sample_outcome_with_utility
(rng[, ...])Samples an outcome in the given utiltity range or return None if not possible
scale_by
(scale[, scale_reserved])- rtype
WeightedUtilityFunction | T
scale_max
(to[, rng])- rtype
T
scale_max_for
(to[, outcome_space, issues, ...])- rtype
T
scale_min
(to[, rng])- rtype
T
scale_min_for
(to[, outcome_space, issues, ...])- rtype
T
shift_by
(offset[, shift_reserved])- rtype
WeightedUtilityFunction | T
shift_max_for
(to[, outcome_space, issues, ...])- rtype
T
shift_min_for
(to[, outcome_space, issues, ...])- rtype
T
spawn
([spawn_as, spawn_params])spawn_object
(*args, **kwargs)to_crisp
()- rtype
to_dict
()to_genius
(file_name[, issues])Exports a utility function to a GENIUS XML file.
to_prob
()- rtype
to_xml_str
([issues, discount_factor])Exports a utility function to a well formatted string
worst
()- rtype
xml
(issues)- rtype
Attributes Documentation
- base_type
- id
The unique ID of this entity
- name
A convenient name of the entity (intended primarily for printing/logging/debugging).
- reserved_distribution
- Return type
- type
- uuid
The unique ID of this entity
Methods Documentation
- __call__(offer)
Calculate the utility_function value for a given outcome at the given negotiation state.
- Parameters
offer (Outcome | None) – The offer to be evaluated.
Remarks:
It calls the abstract method
eval
after opationally adjusting the outcome type.It is preferred to override eval instead of directly overriding this method
You cannot return None from overriden eval() functions but raise an exception (ValueError) if it was not possible to calculate the Value.
Return a float from your
eval
implementation.Return the reserved value if the offer was None
- Return type
Value
- Returns
The utility of the given outcome
- argrank(outcomes, descending=True)
Ranks the given list of outcomes with weights. None stands for the null outcome.
- argrank_with_weights(outcomes, descending=True)
Ranks the given list of outcomes with weights. None stands for the null outcome.
- Returns
- an list of integers giving the index in the input array (outcomes) of an outcome (at the given utility level)
the weight of that outcome
The list is sorted by weights descendingly
- Return type
A list of tuples each with two values
- changes()
- Return type
- checkpoint(path, file_name=None, info=None, exist_ok=False, single_checkpoint=True, step_attribs=('current_step', '_current_step', '_Entity__current_step', '_step'))
Saves a checkpoint of the current object at the given path.
- Parameters
path (
PathLike
) – Full path to a directory to store the checkpointfile_name (
Optional
[str
]) – Name of the file to dump into. If not given, a unique name is createdinfo (
Optional
[dict
[str
,Any
]]) – Information to save with the checkpoint (must be json serializable)exist_ok (
bool
) – If true, override existing dumpsingle_checkpoint (
bool
) – If true, keep a single checkpoint for the last stepstep_attribs (
tuple
[str
,...
]) – Attributes to represent the time-step of the object. Any of the given attributes will be used in the file name generated if single_checkpoint is False. If single_checkpoint is True, the filename will not contain time-step information
- Return type
- Returns
full path to the file used to save the checkpoint
- classmethod checkpoint_info(file_name)
Returns the information associated with a dump of the object saved in the given file
- Parameters
file_name (Path | str) – Name of the object
Returns:
- classmethod create(*args, **kwargs)
Creates an object and returns a proxy to it.
- difference(first, second)
Returns a numeric difference between the utility of the two given outcomes
- Return type
- difference_prob(first, second)
Returns a numeric difference between the utility of the two given outcomes
- Return type
- eval(offer)
- eval_normalized(offer, above_reserve=True, expected_limits=True)
Evaluates the ufun normalizing the result between zero and one
- Parameters
- Remarks:
If the maximum and the minium are equal, finite and above reserve, will return 1.0.
If the maximum and the minium are equal, initinte or below reserve, will return 0.0.
For probabilistic ufuns, a distribution will still be returned.
The minimum and maximum will be evaluated freshly every time. If they are already caached in the ufun, the cache will be used.
- Return type
Value
- extreme_outcomes(outcome_space=None, issues=None, outcomes=None, max_cardinality=1000)
- Return type
tuple[Outcome, Outcome]
- classmethod from_checkpoint(file_name, return_info=False)
Creates an object from a saved checkpoint
- Parameters
file_name (Path | str) –
return_info – If True, tbe information saved when the file was dumped are returned
- Return type
- Returns
Either the object or the object and dump-info as a dict (if return_info was true)
Remarks:
- If info is returned, it is guaranteed to have the following members:
time: Dump time
type: Type of the dumped object
id: ID
name: name
- classmethod from_genius(file_name, **kwargs)
Imports a utility function from a GENIUS XML file.
- Parameters
file_name (str) – File name to import from
- Return type
Tuple[‘BaseUtilityFunction’ | None, float | None]
- Returns
A utility function object (depending on the input file)
Examples
>>> from negmas.preferences import UtilityFunction >>> import pkg_resources >>> from negmas.inout import load_genius_domain >>> domain = load_genius_domain(pkg_resources.resource_filename('negmas' ... , resource_name='tests/data/Laptop/Laptop-C-domain.xml')) >>> u, d = UtilityFunction.from_genius(file_name = pkg_resources.resource_filename('negmas' ... , resource_name='tests/data/Laptop/Laptop-C-prof1.xml') ... , issues=domain.issues) >>> u.__class__.__name__ 'LinearAdditiveUtilityFunction' >>> u.reserved_value 0.0 >>> d 1.0
- Remarks:
See
from_xml_str
for all the parameters
- classmethod from_xml_str(xml_str, issues, safe_parsing=True, ignore_discount=False, ignore_reserved=False, name=None)
Imports a utility function from a GENIUS XML string.
- Parameters
- Return type
Tuple[‘BaseUtilityFunction’ | None, float | None]
- Returns
A utility function object (depending on the input file)
Examples
>>> from negmas.preferences import UtilityFunction >>> import pkg_resources >>> from negmas.inout import load_genius_domain >>> domain = load_genius_domain(pkg_resources.resource_filename('negmas' ... , resource_name='tests/data/Laptop/Laptop-C-domain.xml')) >>> u, _ = UtilityFunction.from_xml_str(open(pkg_resources.resource_filename('negmas' ... , resource_name='tests/data/Laptop/Laptop-C-prof1.xml') ... , 'r').read(), issues=domain.issues)
>>> u, _ = UtilityFunction.from_xml_str(open(pkg_resources.resource_filename('negmas' ... , resource_name='tests/data/Laptop/Laptop-C-prof1.xml') ... , 'r').read(), issues=domain.issues) >>> assert abs(u(("Dell", "60 Gb", "19'' LCD",)) - 21.987727736172488) < 0.000001 >>> assert abs(u(("HP", "80 Gb", "20'' LCD",)) - 22.68559475583014) < 0.000001
- invert(inverter=None)
Inverts the ufun, initializes it and caches the result.
- Return type
- is_better(first, second)
Compares two offers using the
ufun
returning whether the first is strictly better than the second- Parameters
first (Outcome | None) – First outcome to be compared
second (Outcome | None) – Second outcome to be compared
Remarks:
Should raise
ValueError
if the comparison cannot be done
- Return type
- is_equivalent(first, second)
Compares two offers using the
ufun
returning whether the first is strictly equivelent than the second- Parameters
first (Outcome | None) – First outcome to be compared
second (Outcome | None) – Second outcome to be compared
Remarks:
Should raise
ValueError
if the comparison cannot be done
- Return type
- is_not_better(first, second)
Compares two offers using the
ufun
returning whether the first is worse or equivalent than the second- Parameters
first (Outcome) – First outcome to be compared
second (Outcome | None) – Second outcome to be compared
Remarks:
Should raise
ValueError
if the comparison cannot be done
- Return type
- is_session_dependent()
Does the utiltiy of an outcome depend on the
NegotiatorMechanismInterface
?
- is_state_dependent()
Does the utiltiy of an outcome depend on the negotiation state?
- is_stationary()
Are the preferences stationary (i.e. repeated calls return the same value for any preferences comparion or evaluaton method)?
- Return type
- is_volatile()
Does the utiltiy of an outcome depend on factors outside the negotiation?
- Remarks:
A volatile preferences is one that can change even for the same mechanism state due to outside influence
- Return type
- is_worse(first, second)
Compares two offers using the
ufun
returning whether the first is strictly worse than the second- Parameters
first (Outcome | None) – First outcome to be compared
second (Outcome | None) – Second outcome to be compared
Remarks:
Should raise
ValueError
if the comparison cannot be done
- Return type
- max()
- Return type
- min()
- Return type
- minmax(outcome_space=None, issues=None, outcomes=None, max_cardinality=1000, above_reserve=False)
Finds the range of the given utility function for the given outcomes
- Parameters
self – The utility function
outcomes (list[Outcome] | None) – A collection of outcomes (optional)
max_cardinality – the maximum number of outcomes to try sampling (if sampling is used and outcomes are not given)
above_reserve – If given, the minimum and maximum will be set to reserved value if they were less than it.
- Return type
- Returns
(lowest, highest) utilities in that order
- normalize(to=(0.0, 1.0), minmax=None, **kwargs)
- Return type
T
- normalize_for(to=(0.0, 1.0), outcome_space=None, issues=None, outcomes=None, minmax=None, **kwargs)
- Return type
T
- classmethod random(issues, reserved_value=(0.0, 1.0), normalized=True, cost_range=(0.8, 1.0), power_range=(0.0, 1.0), base_preferences_type='negmas.LinearAdditiveUtilityFunction', **kwargs)[source]
Generates a random ufun of the given type
- Return type
- rank(outcomes, descending=True)
Ranks the given list of outcomes with weights. None stands for the null outcome.
- rank_with_weights(outcomes, descending=True)
Ranks the given list of outcomes with weights. None stands for the null outcome.
- Returns
- an list of integers giving the index in the input array (outcomes) of an outcome (at the given utility level)
the weight of that outcome
The list is sorted by weights descendingly
- Return type
A list of tuples each with two values
- sample_outcome_with_utility(rng, outcome_space=None, issues=None, outcomes=None, n_trials=100)
Samples an outcome in the given utiltity range or return None if not possible
- Parameters
outcome_space (OutcomeSpace | None) – outcome_space
issues (List[Issue] | None) – issues
outcomes (List[Outcome] | None) – outcomes
n_trials (int) – n_trials
- Return type
Optional[“Outcome”]
- scale_by(scale, scale_reserved=True)
- Return type
- scale_max(to, rng=None)
- Return type
T
- scale_max_for(to, outcome_space=None, issues=None, outcomes=None, rng=None)
- Return type
T
- scale_min(to, rng=None)
- Return type
T
- scale_min_for(to, outcome_space=None, issues=None, outcomes=None, rng=None)
- Return type
T
- shift_by(offset, shift_reserved=True)
- Return type
- shift_max_for(to, outcome_space=None, issues=None, outcomes=None, rng=None)
- Return type
T
- shift_min_for(to, outcome_space=None, issues=None, outcomes=None, rng=None)
- Return type
T
- classmethod spawn(spawn_as='object', spawn_params=None, *args, **kwargs)
- classmethod spawn_object(*args, **kwargs)
- to_crisp()
- Return type
- to_genius(file_name, issues=None, **kwargs)
Exports a utility function to a GENIUS XML file.
- Parameters
- Returns
None
Examples
>>> from negmas.preferences import UtilityFunction >>> from negmas.inout import load_genius_domain >>> import pkg_resources >>> domain = load_genius_domain(domain_file_name=pkg_resources.resource_filename('negmas' ... , resource_name='tests/data/Laptop/Laptop-C-domain.xml')) >>> u, d = UtilityFunction.from_genius(file_name=pkg_resources.resource_filename('negmas' ... , resource_name='tests/data/Laptop/Laptop-C-prof1.xml') ... , issues=domain.issues) >>> u.to_genius(discount_factor=d ... , file_name = pkg_resources.resource_filename('negmas' ... , resource_name='tests/data/LaptopConv/Laptop-C-prof1.xml') ... , issues=domain.issues)
- Remarks:
See
to_xml_str
for all the parameters
- to_prob()
- Return type
- to_stationary()
- to_xml_str(issues=None, discount_factor=None)
Exports a utility function to a well formatted string
- Return type