quantum/maps/README.md

Map Files

This directory contains environment maps used for quantum path planning experiments.

File Formats

Maps are stored in two formats:

1. YAML (.yaml) - Human-readable source format

   • Easy to edit and version control
   • Defines grid structure, obstacles, terrain, elevation
   • See template.yaml for format specification

2. HDF5 (.h5) - Binary runtime format

   • Efficient storage and loading
   • Generated automatically from YAML files
   • Includes both grid and graph representations

Directory Structure

maps/
├── synthetic/          # Synthetic test maps
│   ├── 3x3/           # Small test cases
│   ├── 5x5/           # Medium complexity
│   ├── 10x10/         # Larger scenarios
│   └── ...
├── template.yaml      # Template for creating new maps
├── yaml2HDF5.py       # Conversion script
└── map_generator.py   # Programmatic map generation

Generating Maps

Generate All Maps

From the repository root:

python generate_all_maps.py

This will:

• Find all .yaml files in quantum/maps/
• Generate corresponding .h5 files in the same directories
• Skip template.yaml

Options

# Clean all .h5 files before regenerating
python generate_all_maps.py --clean

# Show detailed output
python generate_all_maps.py --verbose

# Both
python generate_all_maps.py --clean --verbose

Generate Single Map

from quantum.maps.yaml2HDF5 import generate_map_from_yaml

generate_map_from_yaml(
    yaml_path="quantum/maps/synthetic/3x3/my_map.yaml",
    output_dir="quantum/maps/synthetic/3x3"
)

Coordinate convention

Maps are always static and matrix-native: (row, col), row 0 = top row, row increases downward, map_structure is 0=free/1=obstacle. This is fixed at the file level — unlike a robot's start/goal (see RobotConfig.coordinate_format in ../robotConfiguration.py), a .h5/.yaml map has no runtime "which convention is this in" flag, since it's a baked array, not something read live through a formatter.

If you find it more natural to author a map's obstacles / terrain / elevation positions in cartesian (x, y) (y increasing upward) instead, set coordinate_format: cartesian under map: in the source YAML (see template.yaml). generate_map_from_yaml() re-indexes every position field (grid.obstacles, each modification's positions list, each region's start/end corners) into matrix convention once, at generation time, via yaml2HDF5.flip_map_config_to_matrix() — the resulting .h5 is matrix-native either way. This is a one-time, one-directional migration, not a display toggle: omit the field (or leave it matrix) unless you're specifically authoring in cartesian.

Version Control

Both YAML and HDF5 files are tracked in git:

• YAML files are the source of truth
• HDF5 files are committed for convenience (users don't need to generate them)
• .gitignore is configured to:
  • Exclude .h5 files everywhere EXCEPT quantum/maps/
  • Allow map files to be committed while excluding generated data

Why commit HDF5 files?

• Users can clone and run immediately without setup
• Ensures consistency across different systems
• Small file sizes for test maps (<1 KB each)

When to regenerate:

• After modifying any .yaml file
• Before committing map changes
• When adding new maps

Creating New Maps

1. Copy the template:

   cp quantum/maps/template.yaml quantum/maps/synthetic/my_map.yaml
   

2. Edit the YAML file:

   • Set map name, dimensions
   • Define obstacles, terrain, elevation
   • See template comments for guidance

3. Generate HDF5:

   python generate_all_maps.py
   

4. Test the map:

   from quantum.pathFormulation import PathfindingProblem
   
   problem = PathfindingProblem.from_unified_data(
       "quantum/maps/synthetic/my_map.h5",
       start=(0, 0),
       end=(5, 5),
       T=10
   )
   

5. Commit both files:

   git add quantum/maps/synthetic/my_map.yaml
   git add quantum/maps/synthetic/my_map.h5
   git commit -m "Add new map: my_map"
   

Map Categories

Synthetic Maps

Programmatically generated test cases:

• No obstacles (no_obs*.yaml) - Open grids for baseline testing
• With obstacles (obs*.yaml) - Various obstacle configurations
• Terrain (*_ter.yaml) - Different material costs
• Elevation (*_elev.yaml) - Height-based costs
• Mixed (*_mix.yaml) - Combined features

Size Categories

• Tiny (2x2, 3x2, 3x3) - Unit tests, quick validation
• Small (5x5) - Algorithm development
• Medium (10x10) - Standard benchmarks
• Large (100x100, 1000x1000) - Scalability testing

Technical Details

HDF5 Structure

Each .h5 file contains:

map_file.h5
├── map_structure      # Occupancy grid (0=free, 1=obstacle)
├── terrain           # Material type IDs (optional)
├── elevation         # Height values (optional)
├── materials         # Material name list (optional)
└── graph/
    ├── nodes         # Node positions [(x,y), ...]
    └── edges         # Edges [(i,j,weight), ...]

Metadata Attributes

• map_name: Identifier
• grid_size: "MxN" format
• resolution: Spatial resolution (default: 1.0)
• generated_from: Source YAML path
• generated_at: Timestamp

Troubleshooting

"Map file not found"

• Ensure you've run generate_all_maps.py
• Check the path is relative to repository root

"Materials not found"

• Ensure quantum/config/materials.yaml exists
• Check material names match those defined in config

"Invalid map structure"

• Validate YAML syntax
• Check grid dimensions match obstacle positions
• Ensure all positions are within bounds

See Also

• template.yaml - Map format specification
• yaml2HDF5.py - Conversion implementation
• ../config/materials.yaml - Material definitions