negmas.types

Base types used to construct different entities in NegMAS. This module provides the fundamental building blocks that other NegMAS classes inherit from.

Overview

The types module defines three core abstractions:

  • NamedObject - Base class for all named entities with unique IDs

  • Rational - Base class for entities that have preferences (negotiators, agents)

  • Runnable - Protocol for objects that can be stepped/run

Class Hierarchy

NamedObject
    └── Rational
            ├── Negotiator
            ├── Agent
            └── Controller

NamedObject

class negmas.types.NamedObject(name: str | None = None, *, id: str | None = None, type_name: str | None = None)[source]

Bases: object

The base class of all named entities.

All named entities need to call this class’s __init__() somewhere during initialization.

Parameters:

  • name (str) – The given name of the entity. Notice that the class will add this to a base that depends on the child’s class name.

  • id (str) – A unique identifier in the whole system. In principle you should let the system create this identifier by passing None. In special cases like in serialization you may want to set the id directly

  • type_name (str) – A string to be returned by type_name and its short version is returned by short_type_name

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[source]

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][source]

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

Creates an object and returns a proxy to it.

classmethod from_checkpoint(file_name: Path | str, return_info: Literal[False] = False) → NamedObject[source]
classmethod from_checkpoint(file_name: Path | str, return_info: Literal[True] = True) → 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

property id[source]

The unique ID of this entity

property name[source]

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

set_id(id: str)[source]

Sets the unique ID of this entity

property short_type_name: str[source]

Short type name.

Returns:

The result.

Return type:

str

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

Spawn.

Parameters:

  • spawn_as – Spawn as.

  • spawn_params – Spawn params.

  • *args – Additional positional arguments.

  • **kwargs – Additional keyword arguments.

classmethod spawn_object(*args, **kwargs)[source]

Spawn object.

Parameters:

  • *args – Additional positional arguments.

  • **kwargs – Additional keyword arguments.

property type_name: str[source]

Type name.

Returns:

The result.

Return type:

str

property uuid[source]

The unique ID of this entity

Rational

class negmas.types.Rational(name: str | None = None, preferences: Preferences | None = None, ufun: BaseUtilityFunction | None = None, id: str | None = None, type_name: str | None = None)[source]

Bases: NamedObject

A rational object is an object that can have preferences.

Parameters:

  • name – Object name. Used for printing and logging but not internally by the system

  • preferences – An optional preferences to attach to the object

  • ufun – An optinoal utility function (overrides preferences if given)

  • id – Object ID (must be unique in the whole system). If None, the system will generate it

Remarks:

  • Rational objects can be created with a predefined preferences or without them but the preferences sould be set for any kind of rational object involved in negotiations before the negotiation starts and should not be changed after that.

  • ufun is aliased to negmas.preferences

property crisp_ufun: UtilityFunction | None[source]

Returns the preferences if it is a CrispUtilityFunction else None

property has_cardinal_preferences: bool[source]

Does the entity has an associated ufun?

property has_preferences: bool[source]

Does the entity has an associated ufun?

property has_ufun: bool[source]

Does the entity has an associated ufun?

on_preferences_changed(changes: list[PreferencesChange])[source]

Called to inform the entity that its ufun has changed.

Parameters:

changes – An ordered list of changes that happened.

Remarks:

  • You MUST call the super() version of this function either before or after your code when you are overriding it.

  • The most general form of change is PreferencesChange.General which indicates that you cannot trust anything you knew about the ufun anymore

property preferences: Preferences | None[source]

The utility function attached to that object

property prob_ufun: ProbUtilityFunction | None[source]

Returns the preferences if it is a ProbUtilityFunction else None

property reserved_outcome: Outcome | None[source]

Reserved outcome is the outcome that will be realized by default for this agent.

Remarks:

  • Reserved outcomes are defined for OrdinalPreferences.

See also

reserved_value

property reserved_value: float[source]

Reserved value is what the entity gets if no agreement is reached in the negotiation.

The reserved value can either be explicity defined for the ufun or it can be the output of the ufun for None outcome.

set_preferences(value: Preferences | None, force=False, ignore_exceptions: bool = False) → Preferences | None[source]

Sets the utility function/Preferences.

Parameters:
Returns:

The preferences that were set

Remarks:

  • This method does NOT set the owner on the preferences. Owner is set when the negotiator enters a negotiation (in _on_negotiation_start).

  • Calls on_preferences_changed with Initialization when preferences are set for the first time (old is None), otherwise uses General.

property ufun: BaseUtilityFunction | None[source]

Returns the preferences if it is a BaseUtilityFunction else None

Runnable

class negmas.types.Runnable(*args, **kwargs)[source]

Bases: Protocol

A protocol defining runnable objects

property current_step: int[source]

Returns the current time step index

run() → Any[source]

Run.

Returns:

The result.

Return type:

Any

step() → Any[source]

Step.

Returns:

The result.

Return type:

Any

WithPath

class negmas.types.WithPath(*args, path: Path, loaded: bool = True, **kwargs)[source]

Bases: object

An object loaded from a specific path

property is_loaded[source]
property path[source]

Module Contents

Implements basice data types used to construct different entities in NegMAS

class negmas.types.NamedObject(name: str | None = None, *, id: str | None = None, type_name: str | None = None)[source]

Bases: object

The base class of all named entities.

All named entities need to call this class’s __init__() somewhere during initialization.

Parameters:

  • name (str) – The given name of the entity. Notice that the class will add this to a base that depends on the child’s class name.

  • id (str) – A unique identifier in the whole system. In principle you should let the system create this identifier by passing None. In special cases like in serialization you may want to set the id directly

  • type_name (str) – A string to be returned by type_name and its short version is returned by short_type_name

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[source]

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][source]

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

Creates an object and returns a proxy to it.

classmethod from_checkpoint(file_name: Path | str, return_info: Literal[False] = False) → NamedObject[source]
classmethod from_checkpoint(file_name: Path | str, return_info: Literal[True] = True) → 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

property id[source]

The unique ID of this entity

property name[source]

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

set_id(id: str)[source]

Sets the unique ID of this entity

property short_type_name: str[source]

Short type name.

Returns:

The result.

Return type:

str

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

Spawn.

Parameters:

  • spawn_as – Spawn as.

  • spawn_params – Spawn params.

  • *args – Additional positional arguments.

  • **kwargs – Additional keyword arguments.

classmethod spawn_object(*args, **kwargs)[source]

Spawn object.

Parameters:

  • *args – Additional positional arguments.

  • **kwargs – Additional keyword arguments.

property type_name: str[source]

Type name.

Returns:

The result.

Return type:

str

property uuid[source]

The unique ID of this entity

class negmas.types.Rational(name: str | None = None, preferences: Preferences | None = None, ufun: BaseUtilityFunction | None = None, id: str | None = None, type_name: str | None = None)[source]

Bases: NamedObject

A rational object is an object that can have preferences.

Parameters:

  • name – Object name. Used for printing and logging but not internally by the system

  • preferences – An optional preferences to attach to the object

  • ufun – An optinoal utility function (overrides preferences if given)

  • id – Object ID (must be unique in the whole system). If None, the system will generate it

Remarks:

  • Rational objects can be created with a predefined preferences or without them but the preferences sould be set for any kind of rational object involved in negotiations before the negotiation starts and should not be changed after that.

  • ufun is aliased to negmas.preferences

property crisp_ufun: UtilityFunction | None[source]

Returns the preferences if it is a CrispUtilityFunction else None

property has_cardinal_preferences: bool[source]

Does the entity has an associated ufun?

property has_preferences: bool[source]

Does the entity has an associated ufun?

property has_ufun: bool[source]

Does the entity has an associated ufun?

on_preferences_changed(changes: list[PreferencesChange])[source]

Called to inform the entity that its ufun has changed.

Parameters:

changes – An ordered list of changes that happened.

Remarks:

  • You MUST call the super() version of this function either before or after your code when you are overriding it.

  • The most general form of change is PreferencesChange.General which indicates that you cannot trust anything you knew about the ufun anymore

property preferences: Preferences | None[source]

The utility function attached to that object

property prob_ufun: ProbUtilityFunction | None[source]

Returns the preferences if it is a ProbUtilityFunction else None

property reserved_outcome: Outcome | None[source]

Reserved outcome is the outcome that will be realized by default for this agent.

Remarks:

  • Reserved outcomes are defined for OrdinalPreferences.

See also

reserved_value

property reserved_value: float[source]

Reserved value is what the entity gets if no agreement is reached in the negotiation.

The reserved value can either be explicity defined for the ufun or it can be the output of the ufun for None outcome.

set_preferences(value: Preferences | None, force=False, ignore_exceptions: bool = False) → Preferences | None[source]

Sets the utility function/Preferences.

Parameters:
Returns:

The preferences that were set

Remarks:

  • This method does NOT set the owner on the preferences. Owner is set when the negotiator enters a negotiation (in _on_negotiation_start).

  • Calls on_preferences_changed with Initialization when preferences are set for the first time (old is None), otherwise uses General.

property ufun: BaseUtilityFunction | None[source]

Returns the preferences if it is a BaseUtilityFunction else None

class negmas.types.Runnable(*args, **kwargs)[source]

Bases: Protocol

A protocol defining runnable objects

property current_step: int[source]

Returns the current time step index

run() → Any[source]

Run.

Returns:

The result.

Return type:

Any

step() → Any[source]

Step.

Returns:

The result.

Return type:

Any

class negmas.types.WithPath(*args, path: Path, loaded: bool = True, **kwargs)[source]

Bases: object

An object loaded from a specific path

property is_loaded[source]
property path[source]