OneShotUFun

class scml.oneshot.OneShotUFun(ex_pin, ex_qin, ex_pout, ex_qout, input_product, input_agent, output_agent, production_cost, disposal_cost, shortfall_penalty, input_penalty_scale, output_penalty_scale, n_input_negs, n_output_negs, current_step, input_qrange=(0, 0), input_prange=(0, 0), output_qrange=(0, 0), output_prange=(0, 0), force_exogenous=True, n_lines=10, normalized=False, current_balance=inf, **kwargs)[source]

Bases: negmas.preferences.mixins.StationaryMixin, negmas.preferences.crisp_ufun.UtilityFunction

Calculates the utility function of a list of contracts or offers.

Parameters
  • force_exogenous (bool) – Is the agent forced to accept exogenous contracts given through ex_* arguments?

  • ex_pin (int) – total price of exogenous inputs for this agent

  • ex_qin (int) – total quantity of exogenous inputs for this agent

  • ex_pout (int) – total price of exogenous outputs for this agent

  • ex_qout (int) – total quantity of exogenous outputs for this agent.

  • cost – production cost of the agent.

  • disposal_cost (float) – disposal cost per unit of input/output.

  • shortfall_penalty (float) – penalty for failure to deliver one unit of output.

  • input_agent (bool) – Is the agent an input agent which means that its input product is the raw material

  • output_agent (bool) – Is the agent an output agent which means that its output product is the final product

  • n_lines (int) – Number of production lines. If None, will be read through the AWI.

  • input_product (int) – Index of the input product. If None, will be read through the AWI

  • input_qrange (tuple[int, int]) – A 2-int tuple giving the range of input quantities negotiated. If not given will be read through the AWI

  • input_prange (tuple[int, int]) – A 2-int tuple giving the range of input unit prices negotiated. If not given will be read through the AWI

  • output_qrange (tuple[int, int]) – A 2-int tuple giving the range of output quantities negotiated. If not given will be read through the AWI

  • output_prange (tuple[int, int]) – A 2-int tuple giving the range of output unit prices negotiated. If not given will be read through the AWI

  • n_input_negs (int) – How many input negotiations are allowed. If not given, it will be the number of suppliers as given by the AWI

  • n_output_negs (int) – How many output negotiations are allowed. If not given, it will be the number of consumers as given by the AWI

  • current_step (int) – Current simulation step. Needed only for ufun_range when returning best outcomes

  • normalized (bool) – If given the values returned by from_*, utility_range and __call__ will all be normalized between zero and one.

Remarks:
  • The utility function assumes that the agent will have to pay for all its input products but will receive money only for the output products it could generate and sell.

  • The utility function respects production capacity (n. lines). The agent cannot produce more than the number of lines it has.

  • disposal cost is paid for items bought but not produced only. Items consumed in production (i.e. sold) are not counted.

Attributes Summary

base_type

Returns the utility_function base type ignoring discounting and similar wrappings.

id

The unique ID of this entity

max_utility

The maximum possible utility value

min_utility

The minimum possible utility value

name

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

owner

reserved_distribution

rtype

Distribution

short_type_name

rtype

str

type

Returns the utility_function type.

type_name

rtype

str

uuid

The unique ID of this entity

Methods Summary

__call__(offer)

Calculate the utility_function value for a given outcome.

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

tuple

breach_level([qin, qout])

Calculates the breach level that would result from a given quantities

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.

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)

Calculates the utility function given a single contract.

eval_normalized(offer[, above_reserve, ...])

Evaluates the ufun normalizing the result between zero and one

extreme_outcomes([outcome_space, issues, ...])

rtype

tuple[tuple, tuple]

find_limit(best[, n_input_negs, ...])

Finds either the maximum or the minimum of the ufun.

find_limit_brute_force(best[, n_input_negs, ...])

Finds either the maximum and the minimum of the ufun.

from_aggregates(qin, qout_signed, qout_sold, ...)

Calculates the utility from aggregates of input/output quantity/prices

from_checkpoint(file_name[, return_info])

Creates an object from a saved checkpoint

from_contracts(contracts[, ignore_exogenous])

Calculates the utility function given a list of contracts

from_dict(d)

from_genius(file_name, **kwargs)

Imports a utility function from a GENIUS XML file.

from_offers()

Calculates the utility value given a list of offers and whether each offer is for output or not (= input).

from_xml_str(xml_str, issues[, ...])

Imports a utility function from a GENIUS XML string.

generate_bilateral(outcomes[, ...])

Generates a couple of utility functions

generate_random(n, outcomes[, normalized])

Generates N mapping utility functions

generate_random_bilateral(outcomes)

Generates a couple of utility functions

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 second

is_breach([qin, qout])

Whether the given quantities would lead to a breach.

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

max()

rtype

Union[Distribution, float]

min()

rtype

Union[Distribution, float]

minmax(*args, **kwargs)

Finds the range of the given utility function for the given outcomes

normalize([to])

rtype

Union[TypeVar(T, bound= BaseUtilityFunction), ConstUtilityFunction]

normalize_for([to, outcome_space])

rtype

Union[TypeVar(T, bound= BaseUtilityFunction), ConstUtilityFunction]

ok_to_buy_at(unit_price)

Checks if the unit price can -- even in principle -- be acceptable for buying

ok_to_sell_at(unit_price)

Checks if the unit price can -- even in principle -- be acceptable for selling

outcome_as_tuple(offer)

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

Union[WeightedUtilityFunction, TypeVar(T, bound= BaseUtilityFunction)]

scale_max(to[, rng])

rtype

TypeVar(T, bound= BaseUtilityFunction)

scale_max_for(to[, outcome_space, issues, ...])

rtype

TypeVar(T, bound= BaseUtilityFunction)

scale_min(to[, rng])

rtype

TypeVar(T, bound= BaseUtilityFunction)

scale_min_for(to[, outcome_space, issues, ...])

rtype

TypeVar(T, bound= BaseUtilityFunction)

shift_by(offset[, shift_reserved])

rtype

Union[WeightedUtilityFunction, TypeVar(T, bound= BaseUtilityFunction)]

shift_max_for(to[, outcome_space, issues, ...])

rtype

TypeVar(T, bound= BaseUtilityFunction)

shift_min_for(to[, outcome_space, issues, ...])

rtype

TypeVar(T, bound= BaseUtilityFunction)

spawn([spawn_as, spawn_params])

spawn_object(*args, **kwargs)

to_crisp()

rtype

UtilityFunction

to_dict()

rtype

dict[str, Any]

to_genius(file_name[, issues])

Exports a utility function to a GENIUS XML file.

to_prob()

rtype

ProbUtilityFunction

to_stationary()

to_xml_str([issues, discount_factor])

Exports a utility function to a well formatted string

utility_range([outcome_space, issues, ...])

Finds the utility range and optionally returns the corresponding outcomes from a given issue space or in a single negotiation.

worst()

rtype

tuple

xml(issues)

rtype

str

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

max_utility

The maximum possible utility value

min_utility

The minimum possible utility value

name

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

owner: Rational | None = None
reserved_distribution
Return type

Distribution

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

__call__(offer)

Calculate the utility_function value for a given outcome.

Parameters

offer (tuple | 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

float

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.

Return type

list[list[tuple | None]]

Returns

A list of lists of integers giving the outcome index in the input. The list is sorted by utlity value

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

best()
Return type

tuple

breach_level(qin=0, qout=0)[source]

Calculates the breach level that would result from a given quantities

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

difference(first, second)

Returns a numeric difference between the utility of the two given outcomes

Return type

float

difference_prob(first, second)

Returns a numeric difference between the utility of the two given outcomes

Return type

Distribution

eu(offer)

calculates the expected utility value of the input outcome

Return type

float

eval(offer)[source]

Calculates the utility function given a single contract.

Remarks:
  • This method calculates the utility value of a single offer assuming all other negotiations end in failure.

  • It can only be called for agents that exist in the first or last layer of the production graph.

Return type

float

eval_normalized(offer, above_reserve=True, expected_limits=True)

Evaluates the ufun normalizing the result between zero and one

Parameters
  • offer (Outcome | None) – offer

  • above_reserve (bool) – If True, zero corresponds to the reserved value not the minimum

  • expected_limits (bool) – If True, the expectation of the utility limits will be used for normalization instead of the maximum range and minimum lowest limit

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

float

extreme_outcomes(outcome_space=None, issues=None, outcomes=None, max_cardinality=1000)[source]
Return type

tuple[tuple, tuple]

find_limit(best, n_input_negs=None, n_output_negs=None, secured_input_quantity=0, secured_input_unit_price=0.0, secured_output_quantity=0, secured_output_unit_price=0.0)[source]

Finds either the maximum or the minimum of the ufun.

Parameters
  • best (bool) – Best(max) or worst (min) ufun value?

  • n_input_negs – How many input negs are we to consider? None means all

  • n_output_negs – How many output negs are we to consider? None means all

  • secured_input_quantity – A quantity that MUST be bought

  • secured_input_unit_price – The (average) unit price of the quantity that MUST be bought.

  • secured_output_quantity – A quantity that MUST be sold.

  • secured_output_unit_price – The (average) unit price of the quantity that MUST be sold.

Remarks:
  • You can use the secured_* arguments and control over the number of negotiations to consider to find the utility limits given some already concluded and signed contracts

Return type

UFunLimit

find_limit_brute_force(best, n_input_negs=None, n_output_negs=None, secured_input_quantity=0, secured_input_unit_price=0.0, secured_output_quantity=0, secured_output_unit_price=0.0)[source]

Finds either the maximum and the minimum of the ufun.

Parameters
  • best – Best(max) or worst (min) ufun value?

  • n_input_negs – How many input negs are we to consider? None means all

  • n_output_negs – How many output negs are we to consider? None means all

  • secured_input_quantity – A quantity that MUST be bought

  • secured_input_unit_price – The (average) unit price of the quantity that MUST be bought.

  • secured_output_quantity – A quantity that MUST be sold.

  • secured_output_unit_price – The (average) unit price of the quantity that MUST be sold.

Remarks:
  • You can use the secured_* arguments and control over the number of negotiations to consider to find the utility limits given some already concluded and signed contracts

Return type

UFunLimit

Returns

worst and best outcome information in the form of UFunLimit tuple.

from_aggregates(qin, qout_signed, qout_sold, pin, pout, input_penalty, output_penalty)[source]

Calculates the utility from aggregates of input/output quantity/prices

Parameters
  • qin (int) – Input quantity (total including all exogenous contracts).

  • qout_signed (int) – Output quantity (total including all exogenous contracts) that the agent agreed to sell.

  • qout_sold (int) – Output quantity (total including all exogenous contracts) that the agent will actually sell.

  • pin (int) – Input total price (i.e. unit price * qin).

  • pout (int) – Output total price (i.e. unit price * qin).

  • input_penalty – total disposal cost

  • output_penalty – total shortfall penalty

Remarks:
  • Most likely, you do not need to directly call this method. Consider from_offers and from_contracts that take current balance and exogenous contract information (passed during ufun construction) into account.

  • The method respects production capacity (n. lines). The agent cannot produce more than the number of lines it has.

  • This method does not take exogenous contracts or current balance into account.

  • The method assumes that the agent CAN pay for all input and production.

Return type

float

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

from_contracts(contracts, ignore_exogenous=True)[source]

Calculates the utility function given a list of contracts

Parameters
  • contracts (Iterable[Contract]) – A list/tuple of contracts

  • ignore_exogenous – If given, any contracts with a system agent will be ignored.

Remarks:
  • This method ignores any unsigned contracts passed to it.

  • We do not consider time at all so it is implicitly assumed that all contracts have the same delivery time value.

  • The reason for having the ignore_exogenous parameter is to avoid double counting exogenous contracts if their information is passed during construction of the ufun and they also exist in the list of contracts passed here.

Return type

float

classmethod from_dict(d)
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

from_offers(offers: tuple[tuple[int, int, int], ...], outputs: tuple[bool], return_producible: Literal[False] = False) float[source]
from_offers(offers: tuple[tuple[int, int, int], ...], outputs: tuple[bool], return_producible: Literal[True]) tuple[float, float]

Calculates the utility value given a list of offers and whether each offer is for output or not (= input).

Parameters
  • offers (tuple[tuple[int, int, int], ...]) – An iterable (e.g. list) of tuples each with three values: (quantity, time, unit price) IN THAT ORDER. Time is ignored and can be set to any value.

  • outputs (tuple[bool]) – An iterable of the same length as offers of booleans specifying for each offer whether it is an offer for buying the agent’s output product.

  • return_producible – If true, the producible quantity will be returned

Remarks:
  • This method takes into account the exogenous contract information passed when constructing the ufun.

Return type

float | tuple[float, int]

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
  • xml_str (str) – The string containing GENIUS style XML utility function definition

  • issues (List[Issue] | None) – Optional issue space to confirm that the utility function is valid

  • input (product of all issues in the) –

  • safe_parsing (bool) – Turn on extra checks

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
classmethod generate_bilateral(outcomes, conflict_level=0.5, conflict_delta=0.005)

Generates a couple of utility functions

Parameters
  • n_outcomes (int) – number of outcomes to use

  • conflict_level (float) – How conflicting are the two ufuns to generate. 1.0 means maximum conflict.

  • conflict_delta – How variable is the conflict at different outcomes.

Examples

>>> from negmas.preferences import conflict_level
>>> u1, u2 = UtilityFunction.generate_bilateral(outcomes=10, conflict_level=0.0
...                                             , conflict_delta=0.0)
>>> print(conflict_level(u1, u2, outcomes=10))
0.0
>>> u1, u2 = UtilityFunction.generate_bilateral(outcomes=10, conflict_level=1.0
...                                             , conflict_delta=0.0)
>>> print(conflict_level(u1, u2, outcomes=10))
1.0
>>> u1, u2 = UtilityFunction.generate_bilateral(outcomes=10, conflict_level=0.5
...                                             , conflict_delta=0.0)
>>> 0.0 < conflict_level(u1, u2, outcomes=10) < 1.0
True
Return type

tuple[UtilityFunction, UtilityFunction]

classmethod generate_random(n, outcomes, normalized=True)

Generates N mapping utility functions

Parameters
  • n (int) – number of utility functions to generate

  • outcomes (int | list[tuple]) – number of outcomes to use

  • normalized (bool) – if true, the resulting ufuns will be normlized between zero and one.

Return type

list[UtilityFunction]

classmethod generate_random_bilateral(outcomes)

Generates a couple of utility functions

Parameters
  • n_outcomes (int) – number of outcomes to use

  • conflict_level – How conflicting are the two ufuns to generate. 1.0 means maximum conflict.

  • conflict_delta – How variable is the conflict at different outcomes.

  • zero_summness – How zero-sum like are the two ufuns.

Return type

tuple[UtilityFunction, UtilityFunction]

invert(inverter=None)

Inverts the ufun, initializes it and caches the result.

Return type

InverseUFun

is_better(first, second)

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

Remarks:

  • Should raise ValueError if the comparison cannot be done

Return type

bool

is_breach(qin=0, qout=0)[source]

Whether the given quantities would lead to a breach.

is_equivalent(first, second)

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

Remarks:

  • Should raise ValueError if the comparison cannot be done

Return type

bool

is_not_better(first, second)

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

Parameters
  • first (tuple) – First outcome to be compared

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

Remarks:

  • Should raise ValueError if the comparison cannot be done

Return type

bool

is_not_worse(first, second)

Is first at least as good as second

Return type

bool

is_session_dependent()

Does the utiltiy of an outcome depend on the NegotiatorMechanismInterface?

Return type

bool

is_state_dependent()

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

Return type

bool

is_stationary()

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

Return type

bool

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

bool

is_worse(first, second)

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

Remarks:

  • Should raise ValueError if the comparison cannot be done

Return type

bool

max()
Return type

Union[Distribution, float]

min()
Return type

Union[Distribution, float]

minmax(*args, **kwargs)[source]

Finds the range of the given utility function for the given outcomes

Parameters
  • self – The utility function

  • issues – List of issues (optional)

  • outcomes – 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

tuple[float, float]

Returns

(lowest, highest) utilities in that order

normalize(to=(0.0, 1.0))
Return type

Union[TypeVar(T, bound= BaseUtilityFunction), ConstUtilityFunction]

normalize_for(to=(0.0, 1.0), outcome_space=None)
Return type

Union[TypeVar(T, bound= BaseUtilityFunction), ConstUtilityFunction]

ok_to_buy_at(unit_price)[source]

Checks if the unit price can – even in principle – be acceptable for buying

Remarks:
  • This method is very optimistic. If it returns False, an agent should never buy at this price. If it returns True, it may still be a bad idea to buy at this price.

  • If we buy at this price, the best case scenario is that we pay it and pay production cost then receive the unit price of one output.

  • If we do not buy at this price, the worst case scenario is that we will pay shortfall penalty for one item

  • We should NOT buy if the best case scenario when buying is worse than the worst case scenario when not buying.

  • If called for agents not at the end of the production chain, it will always return True because in these cases we do not know what the the unit price for the output so there is nothing to compare with.

Return type

bool

ok_to_sell_at(unit_price)[source]

Checks if the unit price can – even in principle – be acceptable for selling

Remarks:
  • This method is very optimistic. If it returns False, an agent should never sell at this price. If it returns True, it may still be a bad idea to sell at this price.

  • Sales decisions does not affect in any way the amount we pay for input materials. It only affects the amount we produce, the amout we get paid in sales and the amount we pay as disposal cost and shortfall penalty.

  • If we agree to sell an item at this price, the best case scenario is that we can actually produce this item and sell it. We pay production cost and receive the given unit price.

  • If we do not sell at this price, the worst case scenario is that we really needed that sale. In this case, we will pay disposal cost for one item.

  • We should NOT sell if the best case scenario when selling is worse than the worst case scenario when not selling.

  • If called for agents not at the beginning of the production chain, it will always return True because in these cases we do not know what the the unit price for the input so there is nothing to compare with.

Return type

bool

static outcome_as_tuple(offer)[source]
rank(outcomes, descending=True)

Ranks the given list of outcomes with weights. None stands for the null outcome.

Return type

list[list[tuple | None]]

Returns

A list of lists of integers giving the outcome index in the input. The list is sorted by utlity value

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
  • rng (Tuple[float, float]) – rng

  • 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

Union[WeightedUtilityFunction, TypeVar(T, bound= BaseUtilityFunction)]

scale_max(to, rng=None)
Return type

TypeVar(T, bound= BaseUtilityFunction)

scale_max_for(to, outcome_space=None, issues=None, outcomes=None, rng=None)
Return type

TypeVar(T, bound= BaseUtilityFunction)

scale_min(to, rng=None)
Return type

TypeVar(T, bound= BaseUtilityFunction)

scale_min_for(to, outcome_space=None, issues=None, outcomes=None, rng=None)
Return type

TypeVar(T, bound= BaseUtilityFunction)

shift_by(offset, shift_reserved=True)
Return type

Union[WeightedUtilityFunction, TypeVar(T, bound= BaseUtilityFunction)]

shift_max_for(to, outcome_space=None, issues=None, outcomes=None, rng=None)
Return type

TypeVar(T, bound= BaseUtilityFunction)

shift_min_for(to, outcome_space=None, issues=None, outcomes=None, rng=None)
Return type

TypeVar(T, bound= BaseUtilityFunction)

classmethod spawn(spawn_as='object', spawn_params=None, *args, **kwargs)
classmethod spawn_object(*args, **kwargs)
to_crisp()
Return type

UtilityFunction

to_dict()
Return type

dict[str, Any]

to_genius(file_name, issues=None, **kwargs)

Exports a utility function to a GENIUS XML file.

Parameters
  • file_name (str) – File name to export to

  • u – utility function

  • issues (Optional[Iterable[Issue]]) – The issues being considered as defined in the domain

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

ProbUtilityFunction

to_stationary()
to_xml_str(issues=None, discount_factor=None)

Exports a utility function to a well formatted string

Return type

str

utility_range(outcome_space=None, issues=None, outcomes=None, return_outcomes=False, max_n_outcomes=1000)[source]

Finds the utility range and optionally returns the corresponding outcomes from a given issue space or in a single negotiation.

Parameters
  • issues (Optional[list[Issue]]) – The set of issues of the negotiation. If not given it will be read from the AWI. Note that you cannot specify these issues except for agent in the first or last layer of the production graph (because otherwise, the agent cannot know whether this negotiation is for buying of selling).

  • outcomes (Optional[list[tuple]]) – A list of outcomes to consider. Using outcomes is much slower than using issues and you should never pass both.

  • infeasible_cutoff – A utility value under which we consider the outcome infeasible.

  • return_outcomes – If given the worst and best outcomes (in that order) will be returned.

  • max_n_outcomes – Maximum number of outcomes to try. Not used.

Return type

tuple[float, float] | tuple[float, float, tuple, tuple]

Returns

A tuple of worst and best utility values if return_outcomes is False. otherwise, the worst and best outcomes are appended to the returned utilities leading to a 4-items tuple instead of two.

Remarks:
  • You will get a warning if you use a list of outcomes here because it is too slow.

  • You should only pass issues if you know that the agent is either an input agent or an output agent. Agents in the middle of the production graph cannot know whether these issues are for buying of for selling. To find the utility range for these agents, you can use worst and best that allow specifying input and output issues separately.

  • It is always assumed that the range required is for a single negotiation not a set of negotiations and under the assumption that all other negotiations if any will end in failure

worst()
Return type

tuple

xml(issues)[source]
Return type

str