bnelearn.sampler.samplers_ipv module

This module implements samplers for independent-private value auction settings.

Note that all samplers in this class should implement the IPVSampler interface from .base. Elsewhere in the implementation, we use instancechecks against IPVSampler in order to use functionality that is only available in independent settings, e.g. when drawing samples from conditional distributions.

class bnelearn.sampler.samplers_ipv.BetaSymmetricIPVSampler(alpha: float, beta: float, n_players: int, valuation_size: int, default_batch_size: int, default_device: Optional[Union[device, str, int]] = None)

Bases: SymmetricIPVSampler

An IPV sampler with symmetric Beta priors.

class bnelearn.sampler.samplers_ipv.FixedManualIPVSampler(valuation_tensor: Tensor)

Bases: IPVSampler

For testing purposes: A sampler that returns a fixed tensor as valuations/observations.

class bnelearn.sampler.samplers_ipv.GaussianSymmetricIPVSampler(mean, stddev, n_players, valuation_size, default_batch_size, default_device: Optional[Union[device, str, int]] = None)

Bases: SymmetricIPVSampler

An IPV sampler with symmetric Gaussian priors.

class bnelearn.sampler.samplers_ipv.MultiUnitValuationObservationSampler(n_players: int, n_items: int = 1, max_demand: Optional[int] = None, constant_marginal_values: bool = False, u_lo: float = 0.0, u_hi: float = 1.0, default_batch_size: int = 1, default_device=None)

Bases: UniformSymmetricIPVSampler

Sampler for Multi-Unit, private value settings. Sampler for valuations and signals in Multi-Unit Auctions, following Krishna, Chapter 13.

These are symmetric private value settings, where

• valuations are descending along the valuation_size dimension and represent the marginal utility of winning an additional item.

• bidders may be limited to be interested in at most a certain number of items.

generate_cell_partition(player_position: int, grid_size: int, dtype=torch.float32, device=None)

Generate a rectangular grid partition of the valuation/observation prior and return cells with their vertices.

generate_valuation_grid(player_position: int, minimum_number_of_points: int, dtype=torch.float32, device=None, support_bounds: Optional[Tensor] = None, return_mesh: bool = False) → Tensor

Generates an evenly spaced grid of (approximately and at least) minimum_number_of_points valuations covering the support of the valuation space for the given player. These are meant as rational actions for the player to evaluate, e.g. in the util_loss estimator.

The default reference implementation returns a rectangular grid on [0, upper_bound] x valuation_size.

class bnelearn.sampler.samplers_ipv.SplitAwardValuationObservationSampler(efficiency_parameter: float, **kwargs)

Bases: UniformSymmetricIPVSampler

Sampler for Split-Award, private value settings. Here bidders have two valuations of which one is a linear combination of the other.

generate_action_grid(player_position: int, minimum_number_of_points: int, dtype=torch.float32, device=None) → Tensor

From zero to some maximal value. Here, unlike in the other methods, the two outputs must not be linearly dependent.

generate_valuation_grid(player_position: int, minimum_number_of_points: int, dtype=torch.float32, device=None, support_bounds: Optional[Tensor] = None, return_mesh: bool = False) → Tensor

Generates an evenly spaced grid of (approximately and at least) minimum_number_of_points valuations covering the support of the valuation space for the given player. These are meant as rational actions for the player to evaluate, e.g. in the util_loss estimator.

The default reference implementation returns a rectangular grid on [0, upper_bound] x valuation_size.

class bnelearn.sampler.samplers_ipv.SymmetricIPVSampler(distribution: Distribution, n_players: int, valuation_size: int = 1, default_batch_size: int = 1, default_device: Optional[Union[device, str, int]] = None)

Bases: IPVSampler

A Valuation Oracle that draws valuations independently and symmetrically for all players and each entry of their valuation vector according to a specified distribution.

This base class works with all torch.distributions but requires sampling on cpu then moving to the device. When using cuda, use the faster, distribution-specific subclasses instead where provided.

UPPER_BOUND_QUARTILE_IF_UNBOUNDED = 0.999

draw_conditional_profiles(conditioned_player: int, conditioned_observation: Tensor, inner_batch_size: int, device: Optional[Union[device, str, int]] = None) → Tuple[Tensor, Tensor]

Draws and returns batches conditional valuation and corresponding observation profile. For each entry of conditioned_observation, batch_size samples will be drawn!

Note that here, we are returning full profiles instead (including conditioned_player’s observation and others’ valuations.)

Args:

conditioned_player: int

Index of the player whose observation we are conditioning on.

conditioned_observation: torch.Tensor (*outer_batch_sizes (implicit), observation_size)

A (batch of) observations of player conditioned_player.

Kwargs:

batch_size (optional): int, the “inner”batch_size to draw - i.e. how many conditional samples to draw for each provided conditional_observation. If none provided, will use self.default_batch_size of the class.

Returns:

valuations: torch.Tensor (outer_batch_size, inner_batch_size, n_players, valuation_size):

a conditional valuation profile

observations: torch.Tensor (*`outer_batch_size`s, inner_batch_size, n_players, observation_size):

a corresponding conditional observation profile. observations[:,conditioned_observation,:] will be equal to conditioned_observation repeated batch_size times

class bnelearn.sampler.samplers_ipv.UniformSymmetricIPVSampler(lo, hi, n_players, valuation_size, default_batch_size, default_device: Optional[Union[device, str, int]] = None)

Bases: SymmetricIPVSampler

An IPV sampler with symmetric Uniform priors.

default_batch_size: int

default_device: Optional[Union[device, str, int]]

n_players: int

observation_size: int

support_bounds: FloatTensor

valuation_size: int