bnelearn.sampler.base module

This class provides primitives to implement samplers that support drawing of valuation and observation profiles for a set of players.

class bnelearn.sampler.base.CompositeValuationObservationSampler(n_players: int, valuation_size: int, observation_size: int, subgroup_samplers: List[ValuationObservationSampler], default_batch_size=1, default_device=None)

Bases: ValuationObservationSampler

A class representing composite prior distributions that are made up of several groups of bidders, each of which can be represented by an atomic ValuationObservationSampler, and which are independent between-group (but not necessarily within-group).

Limitation: The current implementation requires that all players nevertheless have the same valuation_size.

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, inner_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/batches 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 (batch_size x n_players x valuation_size):

a conditional valuation profile

observations: torch.Tensor (*outer_batch_sizes, 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

draw_profiles(batch_sizes: Optional[int] = None, device=None) → Tuple[Tensor, Tensor]

Draws and returns a batch of valuation and observation profiles.

Kwargs:

batch_sizes (optional): List[int], the batch_size to draw. If none provided, self.default_batch_size will be used. device (optional): torch.cuda.Device, the device to draw profiles on

Returns:

valuations: torch.Tensor (*batch_sizes x n_players x valuation_size): a valuation profile observations: torch.Tensor (*batch_sizes x n_players x observation_size): an observation profile

generate_action_grid(**kwargs) → Tensor

Possibly need to call specific sampling

generate_cell_partition(**kwargs) → Tensor

Possibly need to call specific sampling

generate_reduced_grid(**kwargs) → Tensor

Possibly need to call specific sampling

generate_valuation_grid(**kwargs) → Tensor

Possibly need to call specific sampling

class bnelearn.sampler.base.FlushedWrappedSampler(base_sampler: ValuationObservationSampler, flush_val_dims: int = 1, flush_obs_dims: int = 1)

Bases: ValuationObservationSampler

A sampler that relies on a base sampler but flushes the last valuation and observations dimensions with zeros.

This is useful when some players have lower observation / valuation size than others.

Note on implementation: an alternative would be using a lower-dimensional base sampler and then adding extra zeroes. We instead go this route of overwriting unnecessary values because the incurred cost of sampling too many values will be cheaper in most cases compared to ‘growing’ tensors after the fact.

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

draw_profiles(batch_sizes: Optional[Union[int, List[int]]] = None, device=None) → Tuple[Tensor, Tensor]

Draws and returns a batch of valuation and observation profiles.

Kwargs:

batch_sizes (optional): List[int], the batch_sizes to draw. If none provided, [self.default_batch_size] will be used. device (optional): torch.cuda.Device, the device to draw profiles on

Returns:

valuations: torch.Tensor (*batch_sizes x n_players x valuation_size): a valuation profile observations: torch.Tensor (*batch_sizes x n_players x observation_size): an observation profile

class bnelearn.sampler.base.IPVSampler(n_players: int, valuation_size: int, support_bounds, default_batch_size: int = 1, default_device: Optional[Union[device, str, int]] = None)

Bases: PVSampler, ABC

A sampler in Independent Private Value Settings.

NOTE: We will only use this class as an interface to perform quick checks for IPV (e.g. in FlushedWrappedSampler below). Implementation is left to subclasses.

See the module .samplers_ipv for examples.

class bnelearn.sampler.base.PVSampler(n_players: int, valuation_size: int, support_bounds, default_batch_size: int = 1, default_device: Optional[Union[device, str, int]] = None)

Bases: ValuationObservationSampler, ABC

A sampler for Private Value settings, i.e. when observations and valuations are identical.

draw_profiles(batch_sizes: Optional[int] = None, device: Optional[Union[device, str, int]] = None) → Tuple[Tensor, Tensor]

Draws and returns a batch of valuation and observation profiles.

Kwargs:

batch_sizes (optional): List[int], the batch_sizes to draw. If none provided, [self.default_batch_size] will be used. device (optional): torch.cuda.Device, the device to draw profiles on

Returns:

valuations: torch.Tensor (*batch_sizes x n_players x valuation_size): a valuation profile observations: torch.Tensor (*batch_sizes x n_players x observation_size): an observation profile

class bnelearn.sampler.base.ValuationObservationSampler(n_players, valuation_size, observation_size, support_bounds, default_batch_size=1, default_device=None)

Bases: ABC

Provides functionality to draw valuation and observation profiles.

abstract 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

abstract draw_profiles(batch_sizes: Optional[Union[int, List[int]]] = None, device=None) → Tuple[Tensor, Tensor]

Draws and returns a batch of valuation and observation profiles.

Kwargs:

batch_sizes (optional): List[int], the batch_sizes to draw. If none provided, [self.default_batch_size] will be used. device (optional): torch.cuda.Device, the device to draw profiles on

Returns:

valuations: torch.Tensor (*batch_sizes x n_players x valuation_size): a valuation profile observations: torch.Tensor (*batch_sizes x n_players x observation_size): an observation profile

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

As the grid is also used for finding best responses, some samplers need extensive grids that sample a broader area. (E.g. when a bidder with high valuations massively shads her bids.)

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_reduced_grid(player_position: int, minimum_number_of_points: int, dtype=torch.float32, device=None) → Tensor

For some samplers, the action dimension is smaller and the grid can be reduced to that lower dimension.

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.