Merge branch 'main' into explore-rust

Author: nreinicke

.gitignore

@@ -1,3 +1,6 @@
+cache/
+build/
+
 py-notebooks/
 *.ipynb
 

README.md

@@ -11,29 +11,34 @@ HIVE supports researchers who explore **Electric Vehicle (EV) fleet control**, *
 Out-of-the-box, it provides a baseline set of algorithms for fleet dispatch, but provides a testbed for exploring alternatives from leading research in model-predictive control (MPC) and deep reinforcement learning.
 HIVE is designed to integrate with vehicle power and energy grid power models in real-time for accurate, high-fidelity energy estimation over arbitrary road networks and demand scenarios.
 
-## Installation
+For more information about HIVE, please visit the [HIVE website](https://www.nrel.gov/hive).
 
-HIVE depends on a Python installation [3.7, 3.8, 3.9, 3.10] and the pip package manager ( [python.org](https://www.python.org/downloads/).
-In our installation example we use [conda](https://www.anaconda.com/products/distribution) | [miniconda](https://docs.conda.io/en/latest/miniconda.html) for managing a HIVE Python environment.
+For technical details about the HIVE platform, please see the [Technical Report](https://www.nrel.gov/docs/fy21osti/80682.pdf).
 
-### via pip
+For more documentation on how to use HIVE, please see the [HIVE documentation](https://nrelhive.readthedocs.io/en/latest/).
 
-    > pip install nrel.hive
+## Installation
 
-### build from source
+HIVE depends on a Python installation [3.7, 3.8, 3.9, 3.10] and the pip package manager ( [python.org](https://www.python.org/downloads/).
+In our installation example we use [conda](https://www.anaconda.com/products/distribution) |  for managing a HIVE Python environment.
 
-Via conda, create a dedicated 'hive' Python environment:
+### (optional) set up a virtual environment using conda
 
-    > conda create -n hive python=3.8 
-    > conda activate hive
+We recommend setting up a virtual environment to install HIVE.
+One way to do this is to use Anaconda:
+    1. Install [Anaconda](https://www.anaconda.com/products/distribution) or [Miniconda](https://docs.conda.io/en/latest/miniconda.html)
+    1. Open a terminal or Anaconda Prompt.
+    1. Create a new virtual environment: `conda create --name hive python=3.10`
+    1. Activate the virtual environment `conda activate hive`
 
-to run tests, also install `pytest`:
+### via pip
 
-    > pip install pytest
+    > pip install nrel.hive
 
-to load hive as a command line application along with all dependencies into your conda environment:
+### build from source
 
-    > git clone https://github.com/NREL/hive.git
+Clone the repository and install the code via pip:
+    > git clone <https://github.com/NREL/hive.git>
     > cd hive
     > pip install -e .
 
@@ -59,30 +64,7 @@ denver_demo_constrained_charging.yaml | default scenario with limited charging s
 denver_demo_fleets.yaml | default scenario with two competing TNC fleets
 manhattan.yaml | larger test scenario with 200 vehicles and 20k requests sampled from the NY Taxi Dataset
 
-## Scenario configuration
-
-Scenarios are run by reading a YAML file describing the parameters of the simulation. The files list all scenario-specific parameters but can fall back to defaults set [here](https://github.com/NREL/hive/blob/main/nrel/hive/resources/defaults/hive_config.yaml).
-
-Scenario YAML files organize a list of resource files to use as input. If a file resource is listed which doesn't resolve to a local file path, HIVE will search for a default resource [here](nrel/hive/resources). By default, HIVE expects file resources stored in a directory matching their resource type. For example, using the [default Denver scenario](nrel/hive/resources/scenarios/denver_downtown/denver_demo.yaml):
-
-```yaml
-...
-input:
-  vehicles_file: denver_demo_vehicles.csv  # vehicles/denver_demo_vehicles.csv
-  requests_file: denver_demo_requests.csv  # requests/denver_demo_requests.csv
-  bases_file: denver_demo_bases.csv        # bases/denver_demo_bases.csv
-...
-```
-
-For a description of file contents and schemas, please read our [technical report](https://www.nrel.gov/docs/fy21osti/80682.pdf). Example scenario and resource data can be found [here](nrel/hive/resources).  
-
-## Global configuration
-
-Some values are set by a global configuration file with filename `.hive.yaml`.
-The defaults are set in the repo [here](nrel/hive/resources/defaults/.hive.yaml).
-If you want to override any entries in this file, you can create a new one by the same name `.hive.yaml` and place it in your working directory or a parent directory.
-Hive will also check your base user directory for this file (aka `~/.hive.yaml`).
-This can be useful if you would like to reduce the output files or change the default output base directory (for example, to something like `~/hive/output`).
+For more information on how to build your own scenario, please see the [HIVE documentation](https://nrelhive.readthedocs.io/en/latest/inputs.html).
 
 ## Dependencies
 
@@ -103,7 +85,7 @@ Beyond these, HIVE uses Uber H3, a geospatial index which HIVE uses for position
 
 ## Developer documentation
 
-Documentation can be found [here](https://readthedocs.org/nrel-hive).
+Documentation can be found [here](https://nrelhive.readthedocs.io/en/latest/developer/index.html).
 
 ## Why HIVE?
 
@@ -303,6 +285,19 @@ If you have found HIVE useful for your research, please cite our [technical repo
 }
 ```
 
+## Contributors
+
+HIVE is currently maintained by Nick Reinicke ([@nreinicke](https://github.com/nreinicke)) and Rob Fitzgerald ([@robfitzgerald](https://github.com/robfitzgerald)). It would not be what it is today without the support of:
+
+- Brennan Borlaug
+- Thomas Grushka
+- Jacob Holden
+- Joshua Hoshiko
+- Eleftheria Kontou
+- Matthew Moniot
+- Eric Wood
+- Clement Raimes
+
 ## Notice
 
 Copyright © 2022 Alliance for Sustainable Energy, LLC, Inc. All Rights Reserved

docs/source/conf.py

@@ -23,7 +23,7 @@
 author = "NREL"
 
 # The full version, including alpha/beta/rc tags
-release = "v1.0.0"
+release = "v1.2.2"
 
 # -- General configuration ---------------------------------------------------
 

docs/source/developer/contributing.md

@@ -0,0 +1,41 @@
+# Contributing to HIVE
+
+This simple guide will walk you through the process of contributing to HIVE.
+
+## Table of Contents
+
+- Identifying an Issue
+- Letting Others Know You're Working on the Issue
+- Forking the Repository
+- Opening a Pull Request
+
+## Identifying an Issue
+
+1. Go to the "Issues" tab in the repository.
+1. Look for issues with labels such as "good first issue" if you're new to the project.
+1. Read the issue description and any associated comments to make sure you understand the problem and its requirements.
+1. Choose an issue that aligns with your skills and interests.
+
+## Letting Others Know You're Working on the Issue
+
+1. Leave a comment on the issue, stating that you'd like to work on it. This helps prevent duplication of effort and lets us know someone is addressing the problem.
+1. Wait for a response from the maintainers or the issue creator. They may provide additional information or guidance, or assign the issue to you.
+
+## Forking the Repository
+
+1. Navigate to the main HIVE page on GitHub.
+1. Click on the "Fork" button in the upper right corner. This creates a copy of the repository under your GitHub account.
+1. Clone your forked repository to your local machine by clicking the "Code" button and copying the URL. Then, open your terminal or command prompt and run git clone [URL], replacing [URL] with the copied URL.
+
+## Opening a Pull Request
+
+1. Create a new branch in your local repository by running git checkout -b [branch-name], replacing [branch-name] with a descriptive name for your changes.
+1. Make changes to the code, addressing the issue you've chosen to work on.
+1. Commit your changes with a meaningful commit message. Use git add [file] to stage changes, and git commit -m "[commit-message]" to commit them.
+1. Push your changes to your forked repository using git push origin [branch-name].
+1. Go to your forked repository on GitHub and click on the "Pull requests" tab.
+1. Click on the "New Pull Request" button, and select your branch in the "compare" dropdown menu.
+1. Review your changes and click "Create Pull Request". Add a descriptive title and a detailed explanation of the changes you made.
+1. Submit your pull request. The project maintainers will review your changes and provide feedback or merge your changes into the main repository.
+
+Thanks for taking the time to contribute to HIVE!

docs/source/developer/release.md

@@ -5,6 +5,10 @@
     - `docs/source/conf.py`
     - `pyproject.toml`
 
+1. Create a new branch and open a PR on GitHub which will run all actions
+
+1. Apply any fixes to make the actions pass 
+
 1. Build the wheel and source distributions:
 
     ```bash
@@ -29,3 +33,5 @@
     git tag -a v<major>.<minor>.<patch> -m "version <major>.<minor>.<patch>"
     git push origin <tagname>
     ```
+
+1. Merge PR 

docs/source/inputs.md

@@ -2,8 +2,9 @@
 
 ## Scenario Config
 
-The main simulation input is a yaml file that contains a bunch of parameters for running a scenario.
-On example of a scenario file can be found at `nrel.hive.resources.scenarios.denver_demo.yaml`:
+Scenarios are run by reading a YAML file describing the parameters of the simulation. The files list all scenario-specific parameters but can fall back to defaults set [here](https://github.com/NREL/hive/blob/main/nrel/hive/resources/defaults/hive_config.yaml).
+
+Scenario YAML files organize a list of resource files to use as input. If a file resource is listed which doesn't resolve to a local file path, HIVE will search for a default resource [here](nrel/hive/resources). By default, HIVE expects file resources stored in a directory matching their resource type.
 
 ```{note}
 some inputs in hive are optional and will fall back to defaults if not specified; here we will denote whether the
@@ -33,49 +34,44 @@ In addition to the scenario config yaml file, each scenario has several other fi
 ```{include} ../../nrel/hive/resources/scenarios/denver_downtown/charging_prices/README.md
 ```
 
-### Fleets 
+### Fleets
 
 ```{include} ../../nrel/hive/resources/scenarios/denver_downtown/fleets/README.md
 ```
 
-### Geofence 
-
-```{include} ../../nrel/hive/resources/scenarios/denver_downtown/geofence/README.md
-```
-
-### Mechatronics 
+### Mechatronics
 
 ```{include} ../../nrel/hive/resources/scenarios/denver_downtown/mechatronics/README.md
 ```
 
-### Requests 
+### Requests
 
 ```{include} ../../nrel/hive/resources/scenarios/denver_downtown/requests/README.md
 ```
 
-### Road Network 
+### Road Network
 
 ```{include} ../../nrel/hive/resources/scenarios/denver_downtown/road_network/README.md
 ```
 
-### Service Prices 
+### Service Prices
 
 ```{include} ../../nrel/hive/resources/scenarios/denver_downtown/service_prices/README.md
 ```
 
-### Stations 
+### Stations
 
 ```{include} ../../nrel/hive/resources/scenarios/denver_downtown/stations/README.md
 ```
 
-### Stations 
+### Stations
 
 ```{include} ../../nrel/hive/resources/scenarios/denver_downtown/stations/README.md
 ```
 
-### Vehicles 
+### Vehicles
 
-```{include} ../../nrel/hive/resources/scenarios/denver_downtown/stations/README.md
+```{include} ../../nrel/hive/resources/scenarios/denver_downtown/vehicles/README.md
 ```
 
 ## Global Config

examples/download_road_network.py

@@ -1,24 +1,47 @@
 from pathlib import Path
-
 import geopandas as gpd
-
+import argparse
 from nrel.hive.model.roadnetwork.osm.osm_roadnetwork import OSMRoadNetwork
 
-GEOJSON_PATH = Path(
-    "../nrel/hive/resources/scenarios/denver_downtown/geofence/downtown_denver.json"
+# this example script builds a HIVE road network using OSMNx and GeoPandas
+# and can be called from the command line via
+# `$ python download_road_network.py some_boundary.geojson`
+# under the hood, HIVE will call OSMNx and build the road network with some
+# simple rules for downloading and reading the OSM data. for more complex
+# network parsing rules you will need to build your own process.
+
+parser = argparse.ArgumentParser(description="network builder")
+parser.add_argument(
+    "boundary",
+    type=Path,
+    help="GeoJSON boundary file describing the extent of the network to load",
+)
+parser.add_argument(
+    "--outfile",
+    type=Path,
+    default="network.json",
+    help="file path to use when writing the HIVE network",
 )
-OUTFILE = Path("denver_demo_road_network.json")
-
 
-def build_road_network(geojson_file: Path, outfile: Path):
-    df = gpd.read_file(geojson_file)
 
-    polygon = df.iloc[0].geometry
+def import_network(geojson_file: Path, outfile: Path):
+    """builds a road network for HIVE from the provided source GeoJSON.
+    a simple wrapper around reading the GeoJSON via GeoPandas and then
+    calling HIVE's OSM network reader.
+    depends on OSMNx: https://github.com/gboeing/osmnx
 
+    :param geojson_file: file containing network boundary
+    :type geojson_file: Path
+    :param outfile: _description_
+    :type outfile: Path
+    """
+    df = gpd.read_file(geojson_file)
+    polygon = df.geometry.unary_union
     rn = OSMRoadNetwork.from_polygon(polygon)
 
-    rn.to_file(OUTFILE)
+    rn.to_file(outfile)
 
 
 if __name__ == "__main__":
-    build_road_network(GEOJSON_PATH, OUTFILE)
+    args = parser.parse_args()
+    import_network(args.boundary, args.outfile)

nrel/hive/app/hive_cosim.py

@@ -21,14 +21,15 @@ def load_scenario(
     scenario_file: Path,
     custom_instruction_generators: Optional[Tuple[T, ...]] = None,
     custom_init_functions: Optional[Iterable[InitFunction]] = None,
+    output_suffix: Optional[str] = None,
 ) -> RunnerPayload:
     """
     load a HIVE scenario from file and return the initial simulation state
     :param scenario_file: the HIVE scenario file to read
     :return: the initial simulation state payload
     :raises: Error when issues with files
     """
-    config = load_config(scenario_file)
+    config = load_config(scenario_file, output_suffix)
     initial_payload = load_simulation(config, custom_instruction_generators, custom_init_functions)
 
     # add a specialized Reporter handler that catches vehicle charge events
@@ -40,7 +41,6 @@ def load_scenario(
 class CrankResult(NamedTuple):
     runner_payload: RunnerPayload
     sim_time: SimTime
-    charge_events: DataFrame
 
 
 def crank(
@@ -55,38 +55,23 @@ def crank(
     :param time_steps: the number of steps to take, using the timestep size set in the HiveConfig
     :param progress_bar: show a progress bar in the console
     :param flush_events: write all requested event logs to their file destinations
+
     :return: the updated simulation state and all charge events that occurred
     """
 
     steps = tqdm(range(time_steps), position=0) if progress_bar else range(time_steps)
 
-    def run_step(acc: Tuple[RunnerPayload, Tuple[DataFrame, ...]], i: int):
-        rp0, events = acc
+    def run_step(rp0: RunnerPayload, i: int):
         # regular step
         rp1 = rp0.u.apply_update(rp0)
         if flush_events:
             rp1.e.reporter.flush(rp1)
 
-        # output events
-        new_events = None
-        for handler in rp1.e.reporter.handlers:
-            if isinstance(handler, VehicleChargeEventsHandler):
-                new_events = handler.get_events()
-                handler.clear()
-
-        if new_events is None:
-            raise SimulationStateError(
-                f"VehicleChargeEventsHandler missing from reporter in env {rp1.e}"
-            )
-
-        updated_events = events + (new_events,)
-
-        return rp1, updated_events
+        return rp1
 
-    initial = (runner_payload, ())
-    next_state, unmerged_events = ft.reduce(run_step, steps, initial)
-    events = pd.concat(unmerged_events)
-    result = CrankResult(next_state, next_state.s.sim_time, events)
+    initial = runner_payload
+    next_state = ft.reduce(run_step, steps, initial)
+    result = CrankResult(next_state, next_state.s.sim_time)
     return result
 
 

nrel/hive/config/config_builder.py

@@ -4,7 +4,6 @@
 
 
 class ConfigBuilder:
-
     T = TypeVar("T")
 
     @classmethod