Preferences

class negmas.preferences.Preferences(*args, outcome_space=None, issues=None, outcomes=None, reserved_outcome=None, **kwargs)[source]

Bases: negmas.types.named.NamedObject, abc.ABC

Base class for all preferences.

Parameters: outcome_space (OutcomeSpace | None) – The outcome-space over which the preferences are defined

Attributes Summary

`base_type`	Returns the utility_function base type ignoring discounting and similar wrappings.
`id`	The unique ID of this entity
`name`	A convenient name of the entity (intended primarily for printing/logging/debugging).
`owner`
`short_type_name`	rtype `str`
`type`	Returns the utility_function type.
`type_name`	rtype `str`
`uuid`	The unique ID of this entity

Methods Summary

`changes`()	rtype `list`[`PreferencesChange`]
`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.
`from_checkpoint`(file_name[, return_info])	Creates an object from a saved checkpoint
`from_dict`(d)
`is_better`(first, second)	Compares two offers using the `ufun` returning whether the first is strictly better than the second
`is_equivalent`(first, second)	Compares two offers using the `ufun` returning whether the first is strictly equivelent than the second
`is_not_better`(first, second)	Compares two offers using the `ufun` returning whether the first is worse or equivalent than the second
`is_not_worse`(first, second)	Is `first` at least as good as `second`
`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.
`is_volatile`()	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 second
`spawn`([spawn_as, spawn_params])
`spawn_object`(args, *kwargs)
`to_dict`()	rtype `dict`[`str`, `Any`]

Attributes Documentation

base_type

Returns the utility_function base type ignoring discounting and similar wrappings.

Return type: str

id: The unique ID of this entity

name: A convenient name of the entity (intended primarily for printing/logging/debugging).

owner: Rational | None = None

short_type_name

Return type: str

type

Returns the utility_function type.

Each class inheriting from this UtilityFunction class will have its own type. The default type is the empty string.

Examples

>>> from negmas.preferences import *
>>> from negmas.outcomes import make_issue
>>> print(LinearAdditiveUtilityFunction((lambda x:x, lambda x:x), issues=[make_issue((0, 1), (0, 1))]).type)
linear_additive
>>> print(MappingUtilityFunction([lambda x: x], issues=[make_issue((0.0, 1.0))]).type)
mapping

Returns: utility_function type
Return type: str

type_name

Return type: str

uuid: The unique ID of this entity

Methods Documentation

changes()[source]

Return type: list[PreferencesChange]

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 checkpoint
file_name (Optional[str]) – Name of the file to dump into. If not given, a unique name is created
info (Optional[dict[str, Any]]) – Information to save with the checkpoint (must be json serializable)
exist_ok (bool) – If true, override existing dump
single_checkpoint (bool) – If true, keep a single checkpoint for the last step
step_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

Path

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:

Return type: dict[str, Any]

classmethod create(*args, **kwargs): Creates an object and returns a proxy to it.

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

NamedObject | tuple[NamedObject, dict[str, Any]]

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_dict(d)[source]

is_better(first, second)[source]

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: bool

is_equivalent(first, second)[source]

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: bool

is_not_better(first, second)[source]

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: bool

abstract is_not_worse(first, second)[source]

Is first at least as good as second

Return type: bool

abstract is_session_dependent()[source]: Does the utiltiy of an outcome depend on the NegotiatorMechanismInterface?

abstract is_state_dependent()[source]: Does the utiltiy of an outcome depend on the negotiation state?

is_stationary()[source]

Are the preferences stationary (i.e. repeated calls return the same value for any preferences comparion or evaluaton method)?

Return type: bool

abstract is_volatile()[source]

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

is_worse(first, second)[source]

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: bool

classmethod spawn(spawn_as='object', spawn_params=None, *args, **kwargs)

classmethod spawn_object(*args, **kwargs)

to_dict()[source]

Return type: dict[str, Any]