v1.2.6: update docs; use C++17 for boost

.github/workflows/python-publish.yml

@@ -10,10 +10,7 @@ name: Upload Python Package
 
 on:
   push:
-    branches:
-      - main
-  release:
-    types: [published]
+    tags: [ 'v*.*.*' ]
 
 permissions:
   contents: read

docs/00-install.md

@@ -0,0 +1,17 @@
+# Installation
+
+## Prerequisites
+
+- Linux AMD64
+- CUDA 11.8 or higher
+- Python >= 3.9
+
+## PyPI
+
+```bash
+pip install python-moss mosstool
+```
+
+## From Source
+
+Go to [Development](06.development.md) for more information.

docs/01-core-concepts.md

@@ -2,7 +2,11 @@
 
 ## Map
 
-In MOSS, a map serves as the foundational layout that represents the physical infrastructure of the road network and surrounding buildings. A map provides a spatial context within which vehicles can be simulated moving according to predefined rules and behaviors. 
+In MOSS, a map serves as the foundational layout that represents the physical infrastructure of the road network and surrounding buildings. A map provides a spatial context within which vehicles can be simulated moving according to predefined rules and behaviors.
+
+:::{tip}
+More details about the map format can be found in the [Data Format](./03-data-format/01-map-format.md) section.
+:::
 
 ### Road Network
 
@@ -30,13 +34,13 @@ In the figure below, the junction has four driving-in road (enclosed by the gree
 
 Buildings within a map describe non-road-network elements surrounding the road network, such as residential buildings in neighborhoods, shopping centers, etc. Buildings are categorized into AOI (Area of Interest) and POI (Point of Interest) based on whether they have an area or not.
 
-#### `AOI` (Area of Interest)
+#### `AOI`
 
 AOIs are the buildings on the roadside which have a specific connection relationship with lane. People/vehicles can travel back and forth between AOI and the road network, as the light brown polygons in the figure below.
 
 ![Aoi](img/sample_aoi_view.png)
 
-#### `POI` (Point of Interest)
+#### `POI`
 
 POI is specific locations that have some significance, it could be a landmark, business, or any other place that might be of interest to users. All POIs are contained in AOIs.
 
@@ -50,3 +54,7 @@ The basic unit of trips is (who, when, where, how).
 - "When" means the departure time of the trip.
 - "Where" means the destination of the trip.
 - "How" means the mode of the trip, including driving and walking now.
+
+:::{tip}
+More details about the trip format can be found in the [Data Format](./03-data-format/02-trip-format.md) section.
+:::

docs/02-quick-start/01-map-building.md

@@ -9,16 +9,17 @@ In this step, we fetch `roadnet` and `aois` data within the area intended for si
 from mosstool.map.osm import RoadNet, Building
 from mosstool.map.builder import Builder
 from mosstool.util.format_converter import dict2pb
+projstr = "+proj=tmerc +lat_0=22.54095 +lon_0=113.90899"
 rn = RoadNet(
-    proj_str="+proj=tmerc +lat_0=22.54095 +lon_0=113.90899",
+    proj_str=projstr,
     max_latitude=39.92,
     min_latitude=39.78,
     max_longitude=116.32,
     min_longitude=116.40,
 )
 roadnet = rn.create_road_net("cache/topo.geojson")
 building = Building(
-    proj_str="+proj=tmerc +lat_0=22.54095 +lon_0=113.90899",
+    proj_str=projstr,
     max_latitude=39.92,
     min_latitude=39.78,
     max_longitude=116.32,
@@ -28,7 +29,7 @@ aois = building.create_building("cache/aois.geojson")
 builder = Builder(
     net=roadnet,
     aois=aois,
-    proj_str="+proj=tmerc +lat_0=22.54095 +lon_0=113.90899",
+    proj_str=projstr,
 )
 pb = dict2pb(m, Map())
 with open("data/temp/map.pb", "wb") as f:
@@ -38,4 +39,8 @@ with open("data/temp/map.pb", "wb") as f:
 - Here `max_latitude`, `min_latitude`, `max_longitude`, `min_longitude` describe the bounding box of the area from which data is to be obtained from OSM, and all are in WGS84 coordinates.
 - `proj_str` is a [PROJ.4](https://proj.org/en/9.5/) projection string, used to transform longitude and latitude coordinates into planar xy coordinates. Generally, if there are no special requirements, the `proj_str` can be directly set to a Transverse Mercator projection centered on the map's center, which is `f"+proj=tmerc +lat_0={(max_latitude+min_latitude)/2} +lon_0={(max_longitude+min_longitude)/2}"`. And must remain the same during this process.
 
+:::{caution}
+The `proj_str` must be the same in the `RoadNet` and `Building` classes, and the `Builder` class.
+:::
+
 **It's worth noting that** the `features` in output GeoJSON file of `create_road_net()` and `create_building()` remains in WGS84 coordinates. The provision of `proj_str` is because using planar xy coordinates is more precise than latitude and longitude coordinates when handling the internal topological relationships of the road network.

docs/02-quick-start/02-trip-generation.md

@@ -20,7 +20,7 @@ from mosstool.util.geo_match_pop import geo2pop
 
 aigc_generator = AigcGenerator()
 POP_TIF_PATH = "chn_ppp_2020_UNadj_constrained.tif"  # world pop data for china: "https://hub.worldpop.org/geodata/summary?id=49730"
-YOUR_ACCESS_TOKEN = "1"
+YOUR_ACCESS_TOKEN = "1" # any string is ok due to the free service
 
 with open("data/temp/map.pb", "rb") as f:
     m = Map()
@@ -35,7 +35,8 @@ area = geo2pop(gdf, POP_TIF_PATH, enable_tqdm=True)
 
 
 aigc_generator.set_satetoken(YOUR_ACCESS_TOKEN)
-area = gpd.read_file("data/gravitygenerator/Beijing-shp/beijing.shp")
+shp_path = "data/gravitygenerator/Beijing-shp/beijing.shp"
+area = gpd.read_file(shp_path)
 aigc_generator.load_area(area)
 od_matrix = aigc_generator.generate()
 
@@ -51,19 +52,19 @@ print(persons)
 ```
 
 - `agent_num` specifies the number of persons to be generated.
+- `shp_path` is the path of the shapefile of the area, which records the polygon of each region used to generate the OD matrix. (one region means one origin and one destination)
 
 ## Fill in the route of the persons' all schedules (Optional)
 
 This step requires extra packages released on [Releases · routing](https://github.com/tsinghua-fib-lab/routing/releases/).
-Activate the `routing` service before running codes below with `./routing -map data/temp/map.pb`.
+Activate the `routing` service before running codes below with `./routing -map data/temp/map.pb -listen localhost:52101`.
 ```python
 client = RoutingClient("http://localhost:52101")
 ok_persons = []
 for p in persons:
     p = await pre_route(client, p)
     if len(p.schedules) > 0 and len(p.schedules[0].trips) > 0:
         ok_persons.append(p)
-print(ok_persons)
 print("final length: ", len(ok_persons))
 pb = Persons(persons=ok_persons)
 with open("data/temp/persons.pb", "wb") as f:

docs/02-quick-start/03-run-your-simulation.md

@@ -15,7 +15,6 @@ e = Engine(
     person_file=TRIP_PATH,
     start_step=0,
     step_interval=1,
-    output_dir="output",  # AVRO output, local directory
     speed_stat_interval=300,  # open road status statistics
     verbose_level=Verbosity.ALL,
 )
@@ -24,14 +23,14 @@ recorder = DBRecorder(
     "postgres://user:password@url:port/simulation",
     "map_db.map_coll",  # map collection used for webui-backend
     "name",
-)  # used for PostgreSQL output
+)  # used for PostgreSQL output (optional)
 for _ in range(3600):
     e.next_step(1)
-    recorder.record()
+    recorder.record() # (optional)
     # YOU CAN DO SOMETHING HERE
     # persons = e.fetch_persons()
     # ...
-# save the simulation results to the database
+# save the simulation results to the database (optional)
 recorder.flush()
 ```
 - `map_file` and `person_file` are what we generated in Step `Build Map` and `Build Trip`.

docs/05-advanced-usage/02-trip-generation.md

@@ -12,33 +12,33 @@ This function returns a `Person` with fixed parameters each time it is called.
 
 ```python
 Person(
-        attribute=PersonAttribute(),
-        vehicle_attribute=VehicleAttribute(
-            length=5,
-            width=2,
-            max_speed=150 / 3.6,
-            max_acceleration=3,
-            max_braking_acceleration=-10,
-            usual_acceleration=2,
-            usual_braking_acceleration=-4.5,
-            headway=1.5,
-            lane_max_speed_recognition_deviation=1.0,
-            lane_change_length=10,
-            min_gap=1,
-            emission_attribute=EmissionAttribute(
-                weight=2100,
-                type=VehicleEngineType.VEHICLE_ENGINE_TYPE_FUEL,
-                coefficient_drag=0.251,
-                lambda_s=0.29,
-                frontal_area=2.52,
-                fuel_efficiency=VehicleEngineEfficiency(
-                    energy_conversion_efficiency=0.27 * 0.049
-                ),
+    attribute=PersonAttribute(),
+    vehicle_attribute=VehicleAttribute(
+        length=5,
+        width=2,
+        max_speed=150 / 3.6,
+        max_acceleration=3,
+        max_braking_acceleration=-10,
+        usual_acceleration=2,
+        usual_braking_acceleration=-4.5,
+        headway=1.5,
+        lane_max_speed_recognition_deviation=1.0,
+        lane_change_length=10,
+        min_gap=1,
+        emission_attribute=EmissionAttribute(
+            weight=2100,
+            type=VehicleEngineType.VEHICLE_ENGINE_TYPE_FUEL,
+            coefficient_drag=0.251,
+            lambda_s=0.29,
+            frontal_area=2.52,
+            fuel_efficiency=VehicleEngineEfficiency(
+                energy_conversion_efficiency=0.27 * 0.049
             ),
-            model="normal",
         ),
-        pedestrian_attribute=PedestrianAttribute(speed=1.34, model="normal"),
-        bike_attribute=BikeAttribute(speed=5, model="normal"),
+        model="normal",
+    ),
+    pedestrian_attribute=PedestrianAttribute(speed=1.34, model="normal"),
+    bike_attribute=BikeAttribute(speed=5, model="normal"),
 )
 
 ```
@@ -94,15 +94,15 @@ cg = CalibratedTemplateGenerator()
 
 `CalibratedTemplateGenerator.template_generator` returns a `Person` with [vehicle attributes](../04-trip-generation/01-format.md#vehicle) distributed according to the driving behavior parameters calibrated for Chinese drivers.
 
-## O-D Matrix Based Trip Generation
+## OD Matrix Based Trip Generation
 
-### O-D matrix generation
+### OD matrix generation
 
-We offer two methods for generating the O-D matrix: one is the classic gravity model, and the other is based on the Diffusion Model.
+We offer two methods for generating the OD matrix: one is the classic gravity model, and the other is based on the Diffusion Model.
 
 #### Gravity model
 
-##### Initialize the model and Generate the O-D matrix
+##### Initialize the model and Generate the OD matrix
 
 ```python
 import numpy as np
@@ -120,12 +120,12 @@ gravity_generator.load_area(area)
 od_matrix = gravity_generator.generate(pops)
 ```
 
-- `area` is `GeoDataFrame` data, containing the geometries that serve as the O-D regions.
+- `area` is `GeoDataFrame` data, containing the geometries that serve as the OD regions.
 - `pops` is a one-dimensional array containing the population numbers corresponding to each region in `area`.
 
 #### AIGC
 
-##### Initialize the model and Generate the O-D matrix
+##### Initialize the model and Generate the OD matrix
 
 ```python
 import geopandas as gpd
@@ -140,9 +140,9 @@ od_matrix = aigc_generator.generate()
 ```
 
 - Here we initialize the `aigc_generator` with specific `ACCESS_TOKEN`, which can be applied from [ArcGIS](https://www.arcgis.com/home/item.html?id=10df2279f9684e4a9f6a7f08febac2a9).
-- `area` is `GeoDataFrame` data, containing the geometries that serve as the O-D regions.
+- `area` is `GeoDataFrame` data, containing the geometries that serve as the OD regions.
 
-### Generate trips with O-D matrix
+### Generate trips with OD matrix
 
 In this step we utilize `generator.TripGenerator` to generated `Persons` with assigned movements between elements in the map.
 

docs/05-advanced-usage/03-rl-tsc.md

@@ -1,4 +1,11 @@
 # Run TSC on MOSS
+
+:::{caution}
+The showcase is based on python-moss v0.2.0. A lot of changes have been made in the latest version.
+
+We are working on updating the showcase to the latest version.
+:::
+
 We provide examples for a classic traffic policy scenario: Traffic Signal Control.
 To run the examples provided in the `moss-opt-showcases` repository, you need to clone the repository and install the required dependencies.
 

docs/06.development.md → docs/06-development.md

@@ -18,7 +18,7 @@ wget -O boost_1_86_0.tar.gz https://archives.boost.io/release/1.86.0/source/boos
 tar -zxvf boost_1_86_0.tar.gz
 cd boost_1_86_0
 ./bootstrap.sh --with-libraries=filesystem,iostreams,program_options,regex,system --prefix=/usr/local  # avro dependency
-./b2 cxxflags=-fPIC install
+./b2 cxxflags="-fPIC -std=c++17" install  # C++17 to match moss
 cd ..
 rm -r boost_1_86_0
 rm boost_1_86_0.tar.gz
@@ -54,4 +54,6 @@ The config file is a YAML file that contains the simulation parameters. You can
 pip install . -v
 ```
 
-1. You can submit a pull request to the repository to contribute to the project.
+:::{note}
+We are welcome to any contributions to the project. You can submit a pull request to the repository to contribute to the project.
+:::

docs/conf.py

@@ -20,6 +20,7 @@
     "myst_parser",
     "autodoc2",
 ]
+myst_enable_extensions = ["colon_fence"]
 autodoc2_packages = [
     "../python/src/moss",
 ]
@@ -32,9 +33,10 @@
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_title = "MOSS"
+html_title = ""
 html_theme = "furo"
 html_theme_options = {
+    "sidebar_hide_name": True,
     "top_of_page_buttons": ["view", "edit"],
     "source_repository": "https://github.com/tsinghua-fib-lab/moss/",
     "source_branch": "main",
@@ -53,3 +55,4 @@
     ],
 }
 html_static_path = ["_static"]
+html_logo = "logo-with-text-transparent.png"

docs/index.md

@@ -31,12 +31,13 @@ The related repositories of MOSS are as follows:
 ```{toctree}
 :maxdepth: 2
 
+00-install
 01-core-concepts
 02-quick-start/index
 03-data-format/index
 04-move-from-sumo/index
 05-advanced-usage/index
-06.development
-07.version
+06-development
+07-version
 apidocs/index
 ```

pyproject.toml

@@ -4,11 +4,12 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-moss"
-version = "1.2.5"
+version = "1.2.6"
 description = "MObility Simulation System"
 authors = [
   { name = "Jun Zhang", email = "[email protected]" },
   { name = "Wenxuan Ao", email = "[email protected]" },
+  { name = "Junbo Yan", email = "[email protected]" },
 ]
 readme = "README.md"
 license = { file = "LICENSE" }

python/before-all-manylinux.sh

@@ -11,7 +11,7 @@ wget -O boost_1_86_0.tar.gz https://archives.boost.io/release/1.86.0/source/boos
 tar -zxf boost_1_86_0.tar.gz
 cd boost_1_86_0
 ./bootstrap.sh --with-libraries=filesystem,iostreams,program_options,regex,system --prefix=/usr/local  # avro dependency
-./b2 cxxflags=-fPIC install
+./b2 cxxflags="-fPIC -std=c++17" install # C++17 to match moss
 cd ..
 rm -r boost_1_86_0
 rm boost_1_86_0.tar.gz