POMDPPlanners.environments.pacman_pomdp.pacman_pomdp_beliefs package

PacMan POMDP belief support with vectorized particle filter.

This package provides vectorized belief updater, grid utilities, and a belief factory for the PacMan POMDP environment.

Classes:

PacManVectorizedUpdater: Batched updater for PacMan POMDP.

Functions:

create_pacman_belief: Factory producing a configured belief for PacManPOMDP.

class POMDPPlanners.environments.pacman_pomdp.pacman_pomdp_beliefs.PacManVectorizedUpdater(maze_size, num_ghosts, num_pellets, state_dim, neighbor_table, neighbor_validity, pellet_positions, ghost_aggressiveness, ghost_coordination, ghost_strategies, observation_noise_factor, max_observation_noise, idx_pac_row, idx_pac_col, idx_ghosts_start, idx_pellets_start, idx_pellets_end, idx_score, idx_terminal)[source]

Bases: VectorizedParticleBeliefUpdater

Vectorized particle belief updater for PacMan POMDP.

Performs all-particle transitions and observation log-likelihood evaluations using vectorized NumPy operations. Ghost movement uses batched softmax sampling, and collision/pellet logic operates on the full particle array at once.

Parameters:

  • maze_size (Tuple[int, int])

  • num_ghosts (int)

  • num_pellets (int)

  • state_dim (int)

  • neighbor_table (np.ndarray)

  • neighbor_validity (np.ndarray)

  • pellet_positions (np.ndarray)

  • ghost_aggressiveness (float)

  • ghost_coordination (str)

  • ghost_strategies (List[str])

  • observation_noise_factor (float)

  • max_observation_noise (float)

  • idx_pac_row (int)

  • idx_pac_col (int)

  • idx_ghosts_start (int)

  • idx_pellets_start (int)

  • idx_pellets_end (int)

  • idx_score (int)

  • idx_terminal (int)

maze_size

Grid dimensions (rows, cols).

num_ghosts

Number of ghosts.

num_pellets

Number of initial pellets.

state_dim

Dimensionality of the array state.

ghost_aggressiveness

Softmax temperature for ghost pursuit.

ghost_coordination

Ghost coordination mode.

ghost_strategies

Per-ghost strategy list.

observation_noise_factor

Multiplier for observation noise.

max_observation_noise

Maximum observation noise std.

batch_observation_log_likelihood(next_particles, action, observation)[source]

Compute observation log-likelihoods for all particles at once.

Parameters:

  • next_particles (ndarray) – Transitioned particle states of shape (N, d).

  • action (ndarray) – Action vector.

  • observation (ndarray) – Observed value.

Return type:

ndarray

Returns:

Log-likelihoods of shape (N,).

batch_transition(particles, action)[source]

Transition all particles in a single batched operation.

Parameters:

  • particles (ndarray) – Current particle states of shape (N, d).

  • action (ndarray) – Action vector.

Return type:

ndarray

Returns:

Next-state particles of shape (N, d).

property config_id: str

Return a deterministic identifier for this updater configuration.

classmethod from_environment(env)[source]

Construct an updater from a PacManPOMDP instance.

Parameters:

env (PacManPOMDP) – Environment to extract parameters from.

Return type:

PacManVectorizedUpdater

Returns:

A new PacManVectorizedUpdater instance.

POMDPPlanners.environments.pacman_pomdp.pacman_pomdp_beliefs.create_pacman_belief(env, belief_type=BeliefType.VECTORIZED_PARTICLE, n_particles=200, **kwargs)[source]

Create a ready-to-use belief for the PacMan POMDP.

Parameters:

  • env (PacManPOMDP) – PacManPOMDP environment instance.

  • belief_type (BeliefType) – Desired belief representation. Defaults to BeliefType.VECTORIZED_PARTICLE.

  • n_particles (int) – Number of particles. Defaults to 200.

  • **kwargs (Any) – Extra arguments (reserved for future use).

Return type:

Belief

Returns:

A configured Belief object.

Raises:

ValueError – If belief_type is not supported.

Example

>>> import numpy as np
>>> np.random.seed(42)
>>> from POMDPPlanners.environments.pacman_pomdp import PacManPOMDP
>>> env = PacManPOMDP(discount_factor=0.95)
>>> belief = create_pacman_belief(env, n_particles=50)
>>> belief.sample().shape[0] > 0
True

Submodules

POMDPPlanners.environments.pacman_pomdp.pacman_pomdp_beliefs.pacman_belief_factory module

Belief factory for the PacMan POMDP.

This module provides a factory function that creates ready-to-use belief objects for the PacMan POMDP, supporting both standard weighted particle beliefs and vectorized particle beliefs.

Functions:

create_pacman_belief: Factory producing a configured belief for PacManPOMDP.

POMDPPlanners.environments.pacman_pomdp.pacman_pomdp_beliefs.pacman_belief_factory.create_pacman_belief(env, belief_type=BeliefType.VECTORIZED_PARTICLE, n_particles=200, **kwargs)[source]

Create a ready-to-use belief for the PacMan POMDP.

Parameters:

  • env (PacManPOMDP) – PacManPOMDP environment instance.

  • belief_type (BeliefType) – Desired belief representation. Defaults to BeliefType.VECTORIZED_PARTICLE.

  • n_particles (int) – Number of particles. Defaults to 200.

  • **kwargs (Any) – Extra arguments (reserved for future use).

Return type:

Belief

Returns:

A configured Belief object.

Raises:

ValueError – If belief_type is not supported.

Example

>>> import numpy as np
>>> np.random.seed(42)
>>> from POMDPPlanners.environments.pacman_pomdp import PacManPOMDP
>>> env = PacManPOMDP(discount_factor=0.95)
>>> belief = create_pacman_belief(env, n_particles=50)
>>> belief.sample().shape[0] > 0
True

POMDPPlanners.environments.pacman_pomdp.pacman_pomdp_beliefs.pacman_grid_utils module

Precomputed grid navigation tables for vectorized PacMan operations.

This module provides utility functions that precompute lookup tables for maze navigation, enabling O(1) position lookups via NumPy fancy indexing instead of per-particle Python branching.

Functions:

precompute_valid_cell_mask: Boolean grid marking non-wall cells. precompute_neighbor_table: Result position for each cell and move. precompute_neighbor_validity: Boolean mask of valid moves per cell.

POMDPPlanners.environments.pacman_pomdp.pacman_pomdp_beliefs.pacman_grid_utils.precompute_neighbor_table(maze_size, valid_cell_mask)[source]

Precompute resulting position for each cell and each of 5 moves.

For each cell and move direction, stores the resulting position. If the move would go out of bounds or into a wall, the position stays the same (i.e., the agent does not move).

Parameters:
Return type:

ndarray

Returns:

Integer array of shape (rows, cols, 5, 2) where result[r, c, move_idx] gives [new_row, new_col].

POMDPPlanners.environments.pacman_pomdp.pacman_pomdp_beliefs.pacman_grid_utils.precompute_neighbor_validity(maze_size, valid_cell_mask)[source]

Precompute which moves are valid from each cell.

A move is valid if the resulting position is in-bounds and not a wall. The stay move (index 4) is always valid.

Parameters:

  • maze_size (Tuple[int, int]) – Grid dimensions as (rows, cols).

  • valid_cell_mask (ndarray) – Boolean array of shape (rows, cols).

Return type:

ndarray

Returns:

Boolean array of shape (rows, cols, 5) where result[r, c, move_idx] is True if the move leads to a valid cell.

POMDPPlanners.environments.pacman_pomdp.pacman_pomdp_beliefs.pacman_grid_utils.precompute_valid_cell_mask(maze_size, walls)[source]

Create boolean grid where True means the cell is not a wall.

Parameters:

  • maze_size (Tuple[int, int]) – Grid dimensions as (rows, cols).

  • walls (Set[Tuple[int, int]]) – Set of wall positions as (row, col) tuples.

Return type:

ndarray

Returns:

Boolean array of shape (rows, cols).

POMDPPlanners.environments.pacman_pomdp.pacman_pomdp_beliefs.pacman_vectorized_updater module

Vectorized particle belief updater for the PacMan POMDP.

This module implements a concrete VectorizedParticleBeliefUpdater that performs batched state transitions and observation log-likelihood evaluations for the PacMan environment, replacing per-particle Python loops with NumPy array operations.

Classes:

PacManVectorizedUpdater: Batched updater for the PacMan POMDP.

class POMDPPlanners.environments.pacman_pomdp.pacman_pomdp_beliefs.pacman_vectorized_updater.PacManVectorizedUpdater(maze_size, num_ghosts, num_pellets, state_dim, neighbor_table, neighbor_validity, pellet_positions, ghost_aggressiveness, ghost_coordination, ghost_strategies, observation_noise_factor, max_observation_noise, idx_pac_row, idx_pac_col, idx_ghosts_start, idx_pellets_start, idx_pellets_end, idx_score, idx_terminal)[source]

Bases: VectorizedParticleBeliefUpdater

Vectorized particle belief updater for PacMan POMDP.

Performs all-particle transitions and observation log-likelihood evaluations using vectorized NumPy operations. Ghost movement uses batched softmax sampling, and collision/pellet logic operates on the full particle array at once.

Parameters:

  • maze_size (Tuple[int, int])

  • num_ghosts (int)

  • num_pellets (int)

  • state_dim (int)

  • neighbor_table (np.ndarray)

  • neighbor_validity (np.ndarray)

  • pellet_positions (np.ndarray)

  • ghost_aggressiveness (float)

  • ghost_coordination (str)

  • ghost_strategies (List[str])

  • observation_noise_factor (float)

  • max_observation_noise (float)

  • idx_pac_row (int)

  • idx_pac_col (int)

  • idx_ghosts_start (int)

  • idx_pellets_start (int)

  • idx_pellets_end (int)

  • idx_score (int)

  • idx_terminal (int)

maze_size

Grid dimensions (rows, cols).

num_ghosts

Number of ghosts.

num_pellets

Number of initial pellets.

state_dim

Dimensionality of the array state.

ghost_aggressiveness

Softmax temperature for ghost pursuit.

ghost_coordination

Ghost coordination mode.

ghost_strategies

Per-ghost strategy list.

observation_noise_factor

Multiplier for observation noise.

max_observation_noise

Maximum observation noise std.

batch_observation_log_likelihood(next_particles, action, observation)[source]

Compute observation log-likelihoods for all particles at once.

Parameters:

  • next_particles (ndarray) – Transitioned particle states of shape (N, d).

  • action (ndarray) – Action vector.

  • observation (ndarray) – Observed value.

Return type:

ndarray

Returns:

Log-likelihoods of shape (N,).

batch_transition(particles, action)[source]

Transition all particles in a single batched operation.

Parameters:

  • particles (ndarray) – Current particle states of shape (N, d).

  • action (ndarray) – Action vector.

Return type:

ndarray

Returns:

Next-state particles of shape (N, d).

property config_id: str

Return a deterministic identifier for this updater configuration.

classmethod from_environment(env)[source]

Construct an updater from a PacManPOMDP instance.

Parameters:

env (PacManPOMDP) – Environment to extract parameters from.

Return type:

PacManVectorizedUpdater

Returns:

A new PacManVectorizedUpdater instance.