Preferences

Bases: NamedObject, ABC

Base class for all preferences.

Parameters:: outcome_space – 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).
`short_type_name`
`type`	Returns the utility_function type.
`type_name`
`uuid`	The unique ID of this entity

Methods Summary

`changes`()	Returns a list of changes to the preferences (if any) since last call.
`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[, python_class_identifier])
`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 utility of an outcome depend on the `NegotiatorMechanismInterface`?
`is_state_dependent`()	Does the utility 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)?.
`is_volatile`()	Does the utility 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
`reset_changes`()	Will be called whenever we need to reset changes.
`set_id`(id)	Sets the unique ID of this entity
`spawn`([spawn_as, spawn_params])
`spawn_object`(args, *kwargs)
`to_dict`([python_class_identifier])

Attributes Documentation

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).

short_type_name

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

uuid: The unique ID of this entity

Methods Documentation

changes() → list[PreferencesChange][source]

Returns a list of changes to the preferences (if any) since last call.

Remarks:

If the ufun is stationary, the return list will always be empty.
If the ufun is not stationary, the ufun itself is responsible for saving the changes in _changes whenever they happen.

checkpoint(path: PathLike, file_name: str | None = None, info: dict[str, Any] | None = None, exist_ok: bool = False, single_checkpoint: bool = True, step_attribs: tuple[str, ...] = ('current_step', '_current_step', '_Entity__current_step', '_step')) → Path

Saves a checkpoint of the current object at the given path.

Parameters:

path – Full path to a directory to store the checkpoint
file_name – Name of the file to dump into. If not given, a unique name is created
info – Information to save with the checkpoint (must be json serializable)
exist_ok – If true, override existing dump
single_checkpoint – If true, keep a single checkpoint for the last step
step_attribs – 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

Returns:

full path to the file used to save the checkpoint

classmethod checkpoint_info(file_name: Path | str) → dict[str, Any]

Returns the information associated with a dump of the object saved in the given file

Parameters:: file_name – Name of the object

Returns:

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

classmethod from_checkpoint(file_name: Path | str, return_info: bool = False) → NamedObject | tuple[NamedObject, dict[str, Any]]

Creates an object from a saved checkpoint

Parameters:

file_name
return_info – If True, tbe information saved when the file was dumped are returned

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, python_class_identifier='__python_class__')[source]

is_better(first: tuple | None, second: tuple | None) → bool[source]

Compares two offers using the ufun returning whether the first is strictly better than the second

Parameters:

first – First outcome to be compared
second – Second outcome to be compared

Remarks:

Should raise ValueError if the comparison cannot be done

is_equivalent(first: tuple | None, second: tuple | None) → bool[source]

Compares two offers using the ufun returning whether the first is strictly equivelent than the second

Parameters:

first – First outcome to be compared
second – Second outcome to be compared

Remarks:

Should raise ValueError if the comparison cannot be done

is_not_better(first: tuple | None, second: tuple | None) → bool[source]

Compares two offers using the ufun returning whether the first is worse or equivalent than the second

Parameters:

first – First outcome to be compared
second – Second outcome to be compared

Remarks:

Should raise ValueError if the comparison cannot be done

abstractmethod is_not_worse(first: tuple | None, second: tuple | None) → bool[source]: Is first at least as good as second

abstractmethod is_session_dependent() → bool[source]: Does the utility of an outcome depend on the NegotiatorMechanismInterface?

abstractmethod is_state_dependent() → bool[source]: Does the utility of an outcome depend on the negotiation state?

is_stationary() → bool[source]: Are the preferences stationary (i.e. repeated calls return the same value for any preferences comparion or evaluaton method)?

abstractmethod is_volatile() → bool[source]

Does the utility 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: tuple | None, second: tuple | None) → bool[source]

Compares two offers using the ufun returning whether the first is strictly worse than the second

Parameters:

first – First outcome to be compared
second – Second outcome to be compared

Remarks:

Should raise ValueError if the comparison cannot be done

reset_changes() → None[source]: Will be called whenever we need to reset changes.

set_id(id: str): Sets the unique ID of this entity

classmethod spawn(spawn_as='object', spawn_params: dict[str, Any] | None = None, *args, **kwargs)

classmethod spawn_object(*args, **kwargs)

to_dict(python_class_identifier='__python_class__') → dict[str, Any][source]