Preferences

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

Bases: NamedObject, 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`
`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)
`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`()	rtype: `dict`[`str`, `Any`]

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

owner: Rational | None = None

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

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

Return type:: list[PreferencesChange]

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, 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 (str | None) – Name of the file to dump into. If not given, a unique name is created
info (dict[str, Any] | None) – 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
Return type:: dict[str, Any]

Returns:

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 (bool) – 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 (tuple | None) – First outcome to be compared
second (tuple | None) – Second outcome to be compared

Return type:

bool

Remarks:

Should raise ValueError if the comparison cannot be done

is_equivalent(first, second)[source]

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

Parameters:

first (tuple | None) – First outcome to be compared
second (tuple | None) – Second outcome to be compared

Return type:

bool

Remarks:

Should raise ValueError if the comparison cannot be done

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 (tuple | None) – First outcome to be compared
second (tuple | None) – Second outcome to be compared

Return type:

bool

Remarks:

Should raise ValueError if the comparison cannot be done

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 utility of an outcome depend on the NegotiatorMechanismInterface?

Return type:: bool

abstract is_state_dependent()[source]

Does the utility of an outcome depend on the negotiation state?

Return type:: bool

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 utility of an outcome depend on factors outside the negotiation?

Return type:: bool

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 (tuple | None) – First outcome to be compared
second (tuple | None) – Second outcome to be compared

Return type:

bool

Remarks:

Should raise ValueError if the comparison cannot be done

reset_changes()[source]

Will be called whenever we need to reset changes.

Return type:: None

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

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

classmethod spawn_object(*args, **kwargs)

to_dict()[source]

Return type:: dict[str, Any]