Rasterization and street graph

.gitignore

@@ -23,6 +23,7 @@ examples/research/**/*.png
 # OSM cache and large outputs
 cache/
 examples/output/
+examples/research/virtual_philadelphia/*.gpkg
 
 # macOS system file
 .DS_Store
@@ -62,3 +63,4 @@ virtual-environments/
 .DS_Store
 Thumbs.db
 *.tmp
+sandbox/sandbox_data.gpkg

CODING_PRINCIPLES.md

@@ -0,0 +1,26 @@
+# Coding Principles
+
+1. **Avoid bloating the code at all costs.** This means no unnecessary variables, no defensive coding that nobody asked for, no checking of data types (unless we are purposefully debugging a problem). This bloats the code and is NOT equal to good coding.
+2. **No blind coding or guessing function arguments with if else.** For instance "if 'building_id' in df" because you don't know the right column name. No. Go and check the codebase for how the objects are defined. Same with other libraries, go online and check the correct function signature.
+3. **Absolutely no ad-hoc hot patches just to pass tests**, consider that the test might be outdated, or that there might be a deeper rework needed which DEFINITELY would need user input.
+4. **No type hints in function signatures.** Instead, the parameter types are in the docstring.
+5. **All imports go at the beginning of the file, never inside functions.**
+6. **Double for loops are to be avoided at all costs.** As well as dictionaries when a pandas series or dataframe can do the job. We need to rely on the highly optimized and vectorized functions provided by numpy, pandas, and geopandas.
+7. **Do not edit the code before sharing a plan with the user and explaining WHY it adheres to the coding principles.**
+
+## Testing and Development Environment
+
+### Virtual Environment
+- This project uses a Python virtual environment located at `.venv/`
+- Activate with: `.venv\Scripts\activate` (Windows) or `source .venv/bin/activate` (Unix)
+
+### Running Tests
+- Tests are located in `nomad/tests/`
+- Run tests with pytest: `pytest nomad/tests/test_<module>.py -v`
+- Run specific test: `pytest nomad/tests/test_<module>.py::test_function_name -v`
+- The venv must be active or use direct path to pytest in venv
+
+### Terminal/PowerShell Syntax
+- This projects uses the default powershell the system provides via the terminal command tool. At least in this machine, it seems to be PSVersion 7.5.4 on a Windows 10 OS
+- Example: `cd "C:\path\to\project"; pytest nomad\tests\test_file.py -v`
+- Always quote paths with spaces

config_high_ha.json

@@ -0,0 +1,44 @@
+{
+    "dt": 0.5,
+    "N": 6,
+    "name_count": 2,
+    "name_seed": 2025,
+    "city_file": "nomad/data/garden-city.gpkg",
+    "destination_diary_file": "exp_1_destinations_unbalanced.csv",
+    "output_files": {
+        "sparse_path": "./sparse_traj_2",
+        "diaries_path": "./diaries_2",
+        "homes_path": "./homes_2"
+    },
+    "agent_params": {
+        "agent_homes": "h-x13-y11",
+        "agent_workplaces": "w-x18-y8",
+        "seed_trajectory": [
+            0,
+            1,
+            2,
+            3,
+            4,
+            5
+        ],
+        "seed_sparsity": [
+            0,
+            1,
+            2,
+            3,
+            4,
+            5
+        ],
+        "beta_ping": [
+            1.0,
+            1.0,
+            10.5,
+            10.5,
+            20.0,
+            20.0
+        ],
+        "beta_durations": null,
+        "beta_start": null,
+        "ha": 1.0
+    }
+}

config_low_ha.json

@@ -0,0 +1,44 @@
+{
+    "dt": 0.5,
+    "N": 6,
+    "name_count": 2,
+    "name_seed": 2025,
+    "city_file": "nomad/data/garden-city.gpkg",
+    "destination_diary_file": "exp_1_destinations_balanced.csv",
+    "output_files": {
+        "sparse_path": "./sparse_traj_1",
+        "diaries_path": "./diaries_1",
+        "homes_path": "./homes_1"
+    },
+    "agent_params": {
+        "agent_homes": "h-x13-y11",
+        "agent_workplaces": "w-x18-y8",
+        "seed_trajectory": [
+            0,
+            1,
+            2,
+            3,
+            4,
+            5
+        ],
+        "seed_sparsity": [
+            0,
+            1,
+            2,
+            3,
+            4,
+            5
+        ],
+        "beta_ping": [
+            1.0,
+            1.0,
+            10.5,
+            10.5,
+            20.0,
+            20.0
+        ],
+        "beta_durations": null,
+        "beta_start": null,
+        "ha": 0.7666666666666667
+    }
+}

docs/source/poi_synthetic.ipynb

@@ -46,37 +46,37 @@
     "]\n",
     "\n",
     "works = [\n",
-    "    {'type': 'work', 'door': (3, 4), 'blocks': [(4, 4), (4, 5)]},\n",
-    "    {'type': 'work', 'door': (5, 3), 'blocks': [(5, 4), (5, 5)]},\n",
-    "    {'type': 'work', 'door': (6, 6), 'geom': box(6, 4, 8, 6)},\n",
-    "    {'type': 'work', 'door': (8, 6), 'geom': box(8, 4, 10, 6)},\n",
-    "    {'type': 'work', 'door': (12, 6), 'geom': box(11, 5, 14, 6)},\n",
-    "    {'type': 'work', 'door': (12, 3), 'geom': box(11, 4, 14, 5)},\n",
-    "    {'type': 'work', 'door': (15, 3), 'geom': box(14, 4, 17, 6)},\n",
-    "    {'type': 'work', 'door': (18, 4), 'geom': box(17, 4, 18, 6)},\n",
-    "    {'type': 'work', 'door': (18, 6), 'geom': box(16, 6, 18, 8)},\n",
-    "    {'type': 'work', 'door': (15, 9), 'geom': box(16, 8, 17, 10)},\n",
-    "    {'type': 'work', 'door': (18, 8), 'geom': box(17, 8, 18, 10)},\n",
-    "    {'type': 'work', 'door': (18, 10), 'geom': box(16, 10, 18, 12)},\n",
-    "    {'type': 'work', 'door': (18, 13), 'geom': box(16, 13, 18, 15)},\n",
-    "    {'type': 'work', 'door': (18, 15), 'geom': box(16, 15, 18, 16)},\n",
-    "    {'type': 'work', 'door': (15, 15), 'geom': box(15, 16, 18, 17)},\n",
-    "    {'type': 'work', 'door': (14, 15), 'blocks': [(14, 16)]},\n",
-    "    {'type': 'work', 'door': (16, 18), 'geom': box(16, 17, 18, 18)},\n",
-    "    {'type': 'work', 'door': (15, 18), 'geom': box(14, 17, 16, 18)},\n",
-    "    {'type': 'work', 'door': (13, 18), 'geom': box(12, 16, 14, 18)},\n",
-    "    {'type': 'work', 'door': (11, 18), 'geom': box(10, 17, 12, 18)},\n",
-    "    {'type': 'work', 'door': (11, 15), 'geom': box(10, 16, 12, 17)},\n",
-    "    {'type': 'work', 'door': (8, 18), 'geom': box(7, 16, 9, 18)},\n",
-    "    {'type': 'work', 'door': (6, 18), 'geom': box(5, 17, 7, 18)},\n",
-    "    {'type': 'work', 'door': (6, 15), 'geom': box(5, 16, 7, 17)},\n",
-    "    {'type': 'work', 'door': (3, 16), 'blocks': [(4, 16), (4, 17)]},\n",
-    "    {'type': 'work', 'door': (3, 13), 'geom': box(4, 13, 6, 16)},\n",
-    "    {'type': 'work', 'door': (6, 12), 'geom': box(4, 12, 6, 13)},\n",
-    "    {'type': 'work', 'door': (3, 10), 'blocks': [(4, 9), (4, 10)]},\n",
-    "    {'type': 'work', 'door': (6, 9), 'blocks': [(5, 9), (5, 10)]},\n",
-    "    {'type': 'work', 'door': (6, 8), 'blocks': [(4, 8), (5, 8)]},\n",
-    "    {'type': 'work', 'door': (3, 6), 'geom': box(4, 6, 6, 8)},\n",
+    "    {'type': 'workplace', 'door': (3, 4), 'blocks': [(4, 4), (4, 5)]},\n",
+    "    {'type': 'workplace', 'door': (5, 3), 'blocks': [(5, 4), (5, 5)]},\n",
+    "    {'type': 'workplace', 'door': (6, 6), 'geom': box(6, 4, 8, 6)},\n",
+    "    {'type': 'workplace', 'door': (8, 6), 'geom': box(8, 4, 10, 6)},\n",
+    "    {'type': 'workplace', 'door': (12, 6), 'geom': box(11, 5, 14, 6)},\n",
+    "    {'type': 'workplace', 'door': (12, 3), 'geom': box(11, 4, 14, 5)},\n",
+    "    {'type': 'workplace', 'door': (15, 3), 'geom': box(14, 4, 17, 6)},\n",
+    "    {'type': 'workplace', 'door': (18, 4), 'geom': box(17, 4, 18, 6)},\n",
+    "    {'type': 'workplace', 'door': (18, 6), 'geom': box(16, 6, 18, 8)},\n",
+    "    {'type': 'workplace', 'door': (15, 9), 'geom': box(16, 8, 17, 10)},\n",
+    "    {'type': 'workplace', 'door': (18, 8), 'geom': box(17, 8, 18, 10)},\n",
+    "    {'type': 'workplace', 'door': (18, 10), 'geom': box(16, 10, 18, 12)},\n",
+    "    {'type': 'workplace', 'door': (18, 13), 'geom': box(16, 13, 18, 15)},\n",
+    "    {'type': 'workplace', 'door': (18, 15), 'geom': box(16, 15, 18, 16)},\n",
+    "    {'type': 'workplace', 'door': (15, 15), 'geom': box(15, 16, 18, 17)},\n",
+    "    {'type': 'workplace', 'door': (14, 15), 'blocks': [(14, 16)]},\n",
+    "    {'type': 'workplace', 'door': (16, 18), 'geom': box(16, 17, 18, 18)},\n",
+    "    {'type': 'workplace', 'door': (15, 18), 'geom': box(14, 17, 16, 18)},\n",
+    "    {'type': 'workplace', 'door': (13, 18), 'geom': box(12, 16, 14, 18)},\n",
+    "    {'type': 'workplace', 'door': (11, 18), 'geom': box(10, 17, 12, 18)},\n",
+    "    {'type': 'workplace', 'door': (11, 15), 'geom': box(10, 16, 12, 17)},\n",
+    "    {'type': 'workplace', 'door': (8, 18), 'geom': box(7, 16, 9, 18)},\n",
+    "    {'type': 'workplace', 'door': (6, 18), 'geom': box(5, 17, 7, 18)},\n",
+    "    {'type': 'workplace', 'door': (6, 15), 'geom': box(5, 16, 7, 17)},\n",
+    "    {'type': 'workplace', 'door': (3, 16), 'blocks': [(4, 16), (4, 17)]},\n",
+    "    {'type': 'workplace', 'door': (3, 13), 'geom': box(4, 13, 6, 16)},\n",
+    "    {'type': 'workplace', 'door': (6, 12), 'geom': box(4, 12, 6, 13)},\n",
+    "    {'type': 'workplace', 'door': (3, 10), 'blocks': [(4, 9), (4, 10)]},\n",
+    "    {'type': 'workplace', 'door': (6, 9), 'blocks': [(5, 9), (5, 10)]},\n",
+    "    {'type': 'workplace', 'door': (6, 8), 'blocks': [(4, 8), (5, 8)]},\n",
+    "    {'type': 'workplace', 'door': (3, 6), 'geom': box(4, 6, 6, 8)},\n",
     "]\n",
     "\n",
     "retails = [\n",

examples/download_poi_data_from_OSM.ipynb

@@ -35,7 +35,7 @@
     "streets.to_file(\"philadelphia_streets.geojson\", driver=\"GeoJSON\")\n",
     "\n",
     "print(f\"Downloaded {len(buildings)} buildings, {len(streets)} streets\")\n",
-    "print(f\"Building categories: {buildings['garden_city_category'].value_counts().to_dict()}\")\n",
+    "print(f\"Building categories: {buildings['building_type'].value_counts().to_dict()}\")\n",
     "\n",
     "# Show sample of downloaded data\n",
     "print(\"\\nSample buildings data:\")\n",
@@ -46,23 +46,23 @@
     "\n",
     "colors = {\n",
     "    'park': 'green',\n",
-    "    'residential': 'blue', \n",
+    "    'home': 'blue', \n",
     "    'retail': 'orange',\n",
     "    'workplace': 'purple',\n",
     "    'other': 'grey'\n",
     "}\n",
     "\n",
     "# Buildings by category with proper colors\n",
     "for category, color in colors.items():\n",
-    "    subset = buildings[buildings['garden_city_category'] == category]\n",
+    "    subset = buildings[buildings['building_type'] == category]\n",
     "    if len(subset) > 0:\n",
     "        subset.plot(ax=axes[0], color=color, edgecolor='black', linewidth=0.1, alpha=0.7)\n",
     "axes[0].set_title('Buildings by Category')\n",
     "axes[0].set_aspect('equal')\n",
     "\n",
     "# Buildings + Streets\n",
     "for category, color in colors.items():\n",
-    "    subset = buildings[buildings['garden_city_category'] == category]\n",
+    "    subset = buildings[buildings['building_type'] == category]\n",
     "    if len(subset) > 0:\n",
     "        subset.plot(ax=axes[1], color=color, edgecolor='black', linewidth=0.08, alpha=0.7)\n",
     "streets.plot(ax=axes[1], color='black', linewidth=0.4)\n",
@@ -99,7 +99,7 @@
     "salem_streets.to_file(\"salem_streets.geojson\", driver=\"GeoJSON\")\n",
     "\n",
     "print(f\"Downloaded {len(salem_buildings)} buildings, {len(salem_streets)} streets\")\n",
-    "print(f\"Building categories: {salem_buildings['garden_city_category'].value_counts().to_dict()}\")\n",
+    "print(f\"Building categories: {salem_buildings['building_type'].value_counts().to_dict()}\")\n",
     "# Show sample of downloaded data\n",
     "print(\"\\nSample Salem buildings data:\")\n",
     "print(salem_buildings.head())\n",
@@ -112,23 +112,23 @@
     "\n",
     "colors = {\n",
     "    'park': 'green',\n",
-    "    'residential': 'blue', \n",
+    "    'home': 'blue', \n",
     "    'retail': 'orange',\n",
     "    'workplace': 'purple',\n",
     "    'other': 'grey'\n",
     "}\n",
     "\n",
     "# Buildings by category\n",
     "for category, color in colors.items():\n",
-    "    subset = salem_buildings[salem_buildings['garden_city_category'] == category]\n",
+    "    subset = salem_buildings[salem_buildings['building_type'] == category]\n",
     "    if len(subset) > 0:\n",
     "        subset.plot(ax=axes[0], color=color, edgecolor='black', linewidth=0.1)\n",
     "axes[0].set_title('Salem Buildings by Category')\n",
     "axes[0].set_aspect('equal')\n",
     "\n",
     "# Buildings + Streets\n",
     "for category, color in colors.items():\n",
-    "    subset = salem_buildings[salem_buildings['garden_city_category'] == category]\n",
+    "    subset = salem_buildings[salem_buildings['building_type'] == category]\n",
     "    if len(subset) > 0:\n",
     "        subset.plot(ax=axes[1], color=color, edgecolor='black', linewidth=0.08, alpha=0.7)\n",
     "salem_streets.plot(ax=axes[1], color='black', linewidth=0.5)\n",

examples/download_poi_data_from_OSM.py

@@ -37,7 +37,7 @@
 streets.to_file("philadelphia_streets.geojson", driver="GeoJSON")
 
 print(f"Downloaded {len(buildings)} buildings, {len(streets)} streets")
-print(f"Building categories: {buildings['garden_city_category'].value_counts().to_dict()}")
+print(f"Building categories: {buildings['building_type'].value_counts().to_dict()}")
 
 # Show sample of downloaded data
 print("\nSample buildings data:")
@@ -48,23 +48,23 @@
 
 colors = {
     'park': 'green',
-    'residential': 'blue', 
+    'home': 'blue', 
     'retail': 'orange',
     'workplace': 'purple',
     'other': 'grey'
 }
 
 # Buildings by category with proper colors
 for category, color in colors.items():
-    subset = buildings[buildings['garden_city_category'] == category]
+    subset = buildings[buildings['building_type'] == category]
     if len(subset) > 0:
         subset.plot(ax=axes[0], color=color, edgecolor='black', linewidth=0.1, alpha=0.7)
 axes[0].set_title('Buildings by Category')
 axes[0].set_aspect('equal')
 
 # Buildings + Streets
 for category, color in colors.items():
-    subset = buildings[buildings['garden_city_category'] == category]
+    subset = buildings[buildings['building_type'] == category]
     if len(subset) > 0:
         subset.plot(ax=axes[1], color=color, edgecolor='black', linewidth=0.08, alpha=0.7)
 streets.plot(ax=axes[1], color='black', linewidth=0.4)
@@ -94,7 +94,7 @@
 salem_streets.to_file("salem_streets.geojson", driver="GeoJSON")
 
 print(f"Downloaded {len(salem_buildings)} buildings, {len(salem_streets)} streets")
-print(f"Building categories: {salem_buildings['garden_city_category'].value_counts().to_dict()}")
+print(f"Building categories: {salem_buildings['building_type'].value_counts().to_dict()}")
 # Show sample of downloaded data
 print("\nSample Salem buildings data:")
 print(salem_buildings.head())
@@ -107,23 +107,23 @@
 
 colors = {
     'park': 'green',
-    'residential': 'blue', 
+    'home': 'blue', 
     'retail': 'orange',
     'workplace': 'purple',
     'other': 'grey'
 }
 
 # Buildings by category
 for category, color in colors.items():
-    subset = salem_buildings[salem_buildings['garden_city_category'] == category]
+    subset = salem_buildings[salem_buildings['building_type'] == category]
     if len(subset) > 0:
         subset.plot(ax=axes[0], color=color, edgecolor='black', linewidth=0.1)
 axes[0].set_title('Salem Buildings by Category')
 axes[0].set_aspect('equal')
 
 # Buildings + Streets
 for category, color in colors.items():
-    subset = salem_buildings[salem_buildings['garden_city_category'] == category]
+    subset = salem_buildings[salem_buildings['building_type'] == category]
     if len(subset) > 0:
         subset.plot(ax=axes[1], color=color, edgecolor='black', linewidth=0.08, alpha=0.7)
 salem_streets.plot(ax=axes[1], color='black', linewidth=0.5)

examples/generate_synthetic_trajectories.py

@@ -132,8 +132,8 @@ def generate_agent_trajectory(args):
 # %%
 np.random.seed(100)
 n_agents = 15
-homes = city.buildings_gdf[city.buildings_gdf['type'] == 'home']['id'].tolist()
-workplaces = city.buildings_gdf[city.buildings_gdf['type'] == 'work']['id'].tolist()
+homes = city.buildings_gdf[city.buildings_gdf['building_type'] == 'home']['id'].tolist()
+workplaces = city.buildings_gdf[city.buildings_gdf['building_type'] == 'workplace']['id'].tolist()
 
 agent_params = [
     (f'agent_{i:04d}',