negmas.preferences Package

Models basic types of utility functions.

Utility functions are at the core of negotiation. Agents engage in negotiations with the goal of maximizing some utility function. In most cases, these utility functions are assumed to be known a-periori and static for the duration of a single negotiations.

Notes

We try to allow for applications that do not necessary have these two assumptions in the following ways:

• A utility_function value (Value) can always represent represent a utility_function distribution over all possible utility_function values (Distribution) or a KnownValue which is a real number.

• The base class of all utility_function functions is UtilityFunction and is assumed to map outcomes (Outcome objects) to the aforementioned generic utility values (Value objects).

• Utility functions can be constructed using any Callable which makes it possible to construct them so that they change depending on the context or the progression of the negotiation.

Functions

pareto_frontier(ufuns[, outcomes, issues, ...])	Finds all pareto-optimal outcomes in the list.
pareto_frontier_of(points[, eps, ...])	Finds the pareto-frontier of a set of utils (i.e. utility values).
pareto_frontier_bf(points[, eps, ...])	rtype: ndarray
pareto_frontier_active(points[, eps, ...])	Finds the pareto-frontier of a set of points.
nash_points(ufuns, frontier[, ranges, ...])	Calculates all the Nash Bargaining Solutions on the Pareto frontier of a negotiation.
kalai_points(ufuns, frontier[, ranges, ...])	Calculates the all Kalai bargaining solutions on the Pareto frontier of a negotiation which is the most Egaliterian solution ref: Kalai, Ehud (1977).
ks_points(ufuns, frontier[, ranges, ...])	Calculates the all Kalai-Somordinsky bargaining solutions on the Pareto frontier of a negotiation which is the bargaining solution that maximizes minimum advantage ratio ref: Kalai, Ehud, and Meir Smorodinsky.
max_welfare_points(ufuns, frontier[, ...])	Calculates all the points with maximum relative welfare (i.e. sum of improvements above reserved value) on the Pareto frontier of a negotiation.
max_relative_welfare_points(ufuns, frontier)	Calculates all the points with maximum relative welfare (i.e. sum of improvements above reserved value) on the Pareto frontier of a negotiation.
make_discounted_ufun(ufun[, cost_per_round, ...])	rtype: DiscountedUtilityFunction | UFunType
scale_max(ufun[, to, outcome_space, issues, ...])	Normalizes a utility function to the given range.
normalize(ufun[, to, outcome_space, issues, ...])	Normalizes a utility function to the given range.
sample_outcome_with_utility(ufun, rng[, ...])	Gets one outcome within the given utility range or None on failure.
extreme_outcomes(ufun[, outcome_space, ...])	Finds the best and worst outcomes.
minmax(ufun[, outcome_space, issues, ...])	Finds the range of the given utility function for the given outcomes.
conflict_level(u1, u2, outcomes[, max_tests])	Finds the conflict level in these two ufuns.
opposition_level(ufuns[, max_utils, ...])	Finds the opposition level of the two ufuns defined as the minimum distance to outcome (1, 1)
winwin_level(u1, u2, outcomes[, max_tests])	Finds the win-win level in these two ufuns.
get_ranks(ufun, outcomes[, normalize])	rtype: list[float] | NDArray[np.floating[Any]]
distance_to(w, p)	rtype: float
distance_between(w, n)	rtype: float
calc_outcome_distances(utils, stats)	rtype: OutcomeDistances
calc_scenario_stats(ufuns[, outcomes, eps])	rtype: ScenarioStats
sort_by_utility(ufun[, outcomes, ...])	Returns an ordered list of utility values and outcomes for the given ufun
calc_reserved_value(ufun[, fraction, nmin, ...])	Calculates a reserved value that keeps the given fraction of outcomes (saturated between nmin and nmax).
dominating_points(utils, points)	Tests whether the given point in utility space is dominated by any in the given points (eps is the tolerance).
make_fun_from_xml(item)	rtype: tuple[BaseFun, str]

Classes

Distribution(*args, **kwargs)	A protocol representing a probability distribution
VolatileUFunMixin()	Indicates that the ufun is volatile
SessionDependentUFunMixin()	Indicates that the ufun is session-dependent (i.e. utility value of outcomes depend on the NMI).
StateDependentUFunMixin()	Indicates that the ufun is state-dependent (i.e. utility value of outcomes depend on the mechanism state).
StationaryMixin()	Indicates that the ufun is stationary which means that it is not session or state dependent and not volatile.
BasePref(*args, **kwargs)	Base Protcol for all preferences in NegMAS.
Ordinal(*args, **kwargs)	Can be ordered (at least partially)
CardinalProb(*args, **kwargs)	Differences between outcomes are meaningfull but probabilistic.
CardinalCrisp(*args, **kwargs)	Differences between outcomes are meaningfull and crisp (i.e. real numbers).
UFun(*args, **kwargs)	Can be called to map an Outcome to a Distribution or a float
UFunProb(*args, **kwargs)	Can be called to map an Outcome to a Distribution
UFunCrisp(*args, **kwargs)	Can be called to map an Outcome to a float
OrdinalRanking(*args, **kwargs)	Outcomes can be ranked.
CardinalRanking(*args, **kwargs)	Implements ranking of outcomes with meaningful differences (i.e. each rank is given a value and nearer values are more similar).
HasReservedOutcome(*args, **kwargs)	In case of disagreement, the value of reserved_outcome will be received by the entity
HasReservedValue(*args, **kwargs)	In case of disagreement, reserved_value will be received by the entity
HasReservedDistribution(*args, **kwargs)	In case of disagreement, a value sampled from reserved_distribution will be received by the entity
Randomizable(*args, **kwargs)	Random Preferences of this type can be created using a random method
Scalable(*args, **kwargs)	Can be scaled by a constant amount (i.e. utility values are all multiplied by this amount).
Shiftable(*args, **kwargs)	Can be shifted by a constant amount (i.e. utility values are all shifted by this amount).
PartiallyShiftable(*args, **kwargs)	Can be shifted by a constant amount for a specific part of the outcome space
PartiallyScalable(*args, **kwargs)	Can be scaled by a constant amount for a specific part of the outcome space
Normalizable(*args, **kwargs)	Can be normalized to a given range of values (default is 0-1)
HasRange(*args, **kwargs)	Has a defined range of utility values (a minimum and a maximum) and defined best and worst outcomes
InverseUFun(ufun)	Can be used to get one or more outcomes at a given range
IndIssues(*args, **kwargs)	The utility value depends on each Issue value through a value function that does not depend on any other issue.
XmlSerializableUFun(*args, **kwargs)	Can be serialized to XML format (compatible with GENIUS)
SingleIssueFun(*args, **kwargs)	A value function mapping values from a single issue to a real number
MultiIssueFun(*args, **kwargs)	A value function mapping values from multiple issues to a real number
Preferences(*args[, outcome_space, issues, ...])	Base class for all preferences.
BaseUtilityFunction(*args[, reserved_value])	Base class for all utility functions in negmas
UtilityFunction(*args[, reserved_value])	Base for all crisp ufuns
ProbUtilityFunction(*args[, reserved_value])	A probablistic utility function.
PresortingInverseUtilityFunction(ufun[, ...])	A utility function inverter that uses pre-sorting.
SamplingInverseUtilityFunction(ufun[, ...])	A utility function inverter that uses sampling.
LinDiscountedUFun(ufun[, cost, factor, ...])	A utility function with linear discounting based on some factor of the negotiation
ExpDiscountedUFun(ufun[, discount, factor, ...])	A discounted utility function based on some factor of the negotiation
DiscountedUtilityFunction(ufun, **kwargs)	Base class for all discounted ufuns
ConstUtilityFunction(value, *[, reserved_value])	A utility function that returns the same value for all outcomes.
LinearUtilityAggregationFunction	alias of LinearAdditiveUtilityFunction
LinearAdditiveUtilityFunction(values[, ...])	A linear aggregation utility function for multi-issue negotiations.
LinearUtilityFunction([weights])	A special case of the AffineUtilityFunciton for which the bias is zero.
AffineUtilityFunction([weights, bias])	An affine utility function for multi-issue negotiations.
MappingUtilityFunction(mapping[, default])	Outcome mapping utility function.
NonLinearAggregationUtilityFunction(values, ...)	A nonlinear utility function.
HyperRectangleUtilityFunction(...[, ...])	A utility function defined as a set of hyper-volumes.
NonlinearHyperRectangleUtilityFunction(...)	A utility function defined as a set of outcome_ranges.
RandomUtilityFunction([rng])	A random utility function for a discrete outcome space
RankOnlyUtilityFunction(ufun[, ...])	A utility function that keeps trak of outcome order onlyself.
ProbMappingUtilityFunction(mapping[, default])	Outcome mapping utility function.
IPUtilityFunction(outcomes[, distributions, ...])	Independent Probabilistic Utility Function.
ILSUtilityFunction(type, loc, scale, *args, ...)	A utility function which represents the loc and scale deviations as any crisp ufun
UniformUtilityFunction(loc, scale, *args, ...)	A utility function which represents the loc and scale deviations as any crisp ufun
ProbRandomUtilityFunction([locs, scales, types])	A random utility function for a discrete outcome space
ScenarioStats(opposition, utility_ranges, ...)
OutcomeDistances(pareto_dist, nash_dist, ...)
OutcomeOptimality(pareto_optimality, ...[, ...])
WeightedUtilityFunction(ufuns[, weights])	A utility function composed of linear aggregation of other utility functions
ComplexNonlinearUtilityFunction(ufuns, ...)	A utility function composed of nonlinear aggregation of other utility functions
ConstFun(bias)
IdentityFun()
AffineFun(slope[, bias])
LinearFun(slope)
TriangularFun(start, middle, end[, bias])
LambdaFun(f[, bias, min_value, max_value])
PolynomialFun(coefficients[, bias])
QuadraticFun(a2, a1[, bias])
ExponentialFun(tau[, bias, base])
LogFun(tau[, bias, base, scale])
SinFun([multiplier, bias, phase, amplitude])
CosFun([multiplier, bias, phase, amplitude])
TableFun(mapping)
TableMultiFun(mapping)
AffineMultiFun(slope[, bias])
LinearMultiFun(slope)
LambdaMultiFun(f[, bias, min_value, max_value])

Class Inheritance Diagram