[rust-refactor] meta issue

[nreinicke]

summary

A meta issue to keep track of the experimental refactor of the core of hive into rust.

The current branch for all this work is explore-rust. All work should be branched off here and then merged back into it via a PR.

We should also periodically merge main back into this branch to keep it up to date.

setup

To build the rust backend, you can use maturin like this:

cd rust/
pip install maturin
maturin develop

Then, when running the main hive command, you can pass the USE_RUST environment variable to load the rust python objects:

USE_RUST=True hive denver_demo.yaml

testing

In addition to passing the unit tests, each PR should test running the hive base model hive denver_demo.yaml against the new rust additions: USE_RUST=True hive denver_demo.yaml to make sure the results are similar.

scope

The scope of this work is to move the core of hive into rust, exposed via python. At a high level this includes:

• the model
• all state machines
• the environment
• the reporter

notes

In order to support our design choice of maintaining immutable copies of the simulation state, we need to use structural sharing whenever we modify state. In python, we've used the replace method for data classes:

hive/nrel/hive/model/base.py

Lines 139 to 149 in 96ec422

	def checkout_stall(self) -> Optional[Base]:
	"""
	Checks out a stall and returns the updated base if there are enough stalls.
	:return: Updated Base or None
	"""
	stalls = self.available_stalls
	if stalls < 1:
	return None
	else:
	return replace(self, available_stalls=stalls - 1)

In rust, we're using Arc to allow for shared references of state without deep copies:

hive/rust/src/base.rs

Lines 165 to 174 in 96ec422

	pub fn checkout_stall(&self) -> Option<Base> {
	if *self.available_stalls == 0 {
	return None;
	} else {
	let mut new_self = self.clone();
	let new_stalls = Arc::make_mut(&mut new_self.available_stalls);
	*new_stalls = *new_stalls - 1;
	Some(new_self)
	}
	}

progress

Right now, we're just focusing on moving the model into rust:

• base
• station
• energy
• request
• haversine road network
• osm road network
• vehicle
• mechatronics
• powertrain
• powercurve
• entity position
• membership
• passenger
• sim time