From 7c52ec2f25dbcc6f7ef61fe935ce1ae8361b576b Mon Sep 17 00:00:00 2001 From: rfitzger Date: Fri, 16 Jun 2023 09:06:16 -0600 Subject: [PATCH 1/3] sort reqs on value AND id --- nrel/hive/dispatcher/instruction_generator/dispatcher.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/nrel/hive/dispatcher/instruction_generator/dispatcher.py b/nrel/hive/dispatcher/instruction_generator/dispatcher.py index fd116b3f..a10602a5 100644 --- a/nrel/hive/dispatcher/instruction_generator/dispatcher.py +++ b/nrel/hive/dispatcher/instruction_generator/dispatcher.py @@ -96,7 +96,7 @@ def _valid_request(r: Request) -> bool: ) unassigned_requests = simulation_state.get_requests( - sort_key=lambda r: -r.value, + sort_key=lambda r: (-r.value, r.id), filter_function=_valid_request, ) From 275eb3a085d615a5b45853bff145165fd1ebb294 Mon Sep 17 00:00:00 2001 From: rfitzger Date: Fri, 16 Jun 2023 09:19:38 -0600 Subject: [PATCH 2/3] expand design section with stubs, determinism section --- docs/source/developer/design.md | 35 +++++++++++++++++++++++++++------ 1 file changed, 29 insertions(+), 6 deletions(-) diff --git a/docs/source/developer/design.md b/docs/source/developer/design.md index c17a9752..cb8bbc8f 100644 --- a/docs/source/developer/design.md +++ b/docs/source/developer/design.md @@ -4,11 +4,30 @@ This page describes details specific to HIVE for new developers interacting with ## table of contents +- **[immutability](#immutability)**: the modeling of system state in a HIVE simulation +- **[finite state machine](#finite-state-machine)**: how agent behavior is characterized +- **[error as value](#error-as-value)**: the choice to avoid exception throwing - **[determinism](#determinism)**: details related to keeping HIVE runs deterministic + - [iterating over immutables.Map collections](#iterating-over-map-collections) + - [sorting based on some field is not enough](#sorting-based-on-some-field-is-not-enough) -### determinism +## immutability -#### immutables.Map does not iterate based on insertion order +_todo_ + +## finite state machine + +_todo_ + +## error as value + +_todo_ + +## determinism + +It is essential that HIVE produces deterministic runs so that research can explore A/B test cases with stable results. In this section, we describe a few important patterns in the HIVE codebase for tackling non-deterministic behavior. + +#### iterating over Map collections Most of the HIVE state is stored in hash maps. A [3rd party library](https://github.com/MagicStack/immutables) provides an immutable hash map via the Hash Array Mapped Trie (HAMT) data structure. While it is, for the most part, a drop-in replacement for a python Dict, it has one caveat, which is that insertion order is not guaranteed. This has determinism implications for HIVE. For this reason, any iteration of HAMT data structures must first be _sorted_. This is the default behavior for accessing the entity collections on a `SimulationState`, that they are first sorted by `EntityId`, such as `sim.get_vehicles()`. @@ -19,10 +38,14 @@ Deeper within HIVE, whenever the HAMT data structure is interacted with, we must - here, prefer `DictOps.iterate_vals()` or `DictOps.iterate_items()` which first sort by key - if key sorting is not preferred, write a specialized sort -When making a specialized sort function over a set of entities, consider bundling the cost value with the entity id. If two entities have the same value, the id can be used to "break the tie" in a deterministic way. Example: +#### sorting based on some field is not enough + +In some instances we want to sort a set of things in HIVE based on a field. For example, when updating vehicle states, we ensure we first update enqueued vehicles and that we update them in a first-in, first-out order. to do this, we sort ChargeQueueing vehicles by their `enqueue_time`. But this value is _not unique_, which means that any vehicles that share a common `enqueue_time` will have matching sort order resulting in a non-deterministic sort assignment. + +To address this, we supply a `Tuple[T, EntityId]` as the sort value. The id serves to "break the tie" in a deterministic way. Example: ```python -vs: List[Vehicle] = ... # -sorted(vs, key=lambda v: v.distance_traveled_km) # bad -sorted(vs, key=lambda v: (v.distance_traveled_km, v.id)) # good +vs = sim.get_vehicles(filter_function=lambda v: isinstance(v.vehicle_state, ChargeQueueing)) +sorted(vs, key=lambda v: v.vehicle_state.enqueue_time) # bad +sorted(vs, key=lambda v: (v.vehicle_state.enqueue_time, v.id)) # good ``` From f98f8a22b8deb3c9cba13cdc89c8224a22adf5cd Mon Sep 17 00:00:00 2001 From: rfitzger Date: Fri, 16 Jun 2023 09:40:31 -0600 Subject: [PATCH 3/3] sphinx-rtd-theme currently requires sphinx<7 --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 9a07f21c..65c64596 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -34,7 +34,7 @@ requires-python = ">=3.8" [project.optional-dependencies] docs = [ - "sphinx", + "sphinx<7", "sphinx-autoapi", "sphinx-rtd-theme", "sphinxemoji",