Merge pull request #14 from NREL/rjf/crate-readmes

Rjf/crate readmes

rust/routee-compass-core/README.md

@@ -1,43 +1,32 @@
-# Compass Core Crate
-
-Crate containing core routing modules of RouteE Compass used by all downstream crates.
-This can be broken up into the following modules:
-- [`crate::model`] - [data-model](#data-model) of the search algorithm
-  - [`crate::model::graph`] - road network topology collection type
-  - [`crate::model::property`] - road network record types
-  - [`crate::model::traversal`] - search cost model
-  - [`crate::model::frontier`] - search frontier validation predicates
-  - [`crate::model::termination::termination_model`] - system-level rules on timeouts + limits for search
-- [`crate::algorithm`] - [algorithm](#algorithm) implementations
-  - [`crate::algorithm::search`] - search algorithm module
-    - [`crate::algorithm::search::search_algorithm_type::SearchAlgorithmType`] - enumeration listing search algorithm types, so far only traditional a star supported
-    - [`crate::algorithm::search::a_star::a_star`] - a star search implementation
-  - [`crate::algorithm::component:scc`] - strongly-connected components algorithm
-- [`crate::util`] - utility modules
-
-### Data Model
-
-RouteE Compass takes a layered approach to modeling the road network.
-At the core is the [Graph] model. 
-The edges and vertices are stored in `vec`s and carry the minimal data required for most search applications:
-- [`crate::model::property::edge::Edge`] records store distance in meters
-- [`crate::model::property::vertex::Vertex`] records store coordinate locations, assumed in WGS84 projection
-
-A forward and reverse adjacency list describes connectivity in the graph using the indices of the edges and vertices in their respective `vec`s.
-
-From this alone we can implement a distance-minimizing search.
-This is done via a [TraversalModel], which provides an API for computing the costs of traversal based on the search state, graph, and any exogenous datasets.
-The convention in RouteE Compass is to load additional `vec`s in the [TraversalModel] which can serve as lookup functions by `EdgeId` for traversal costs and `(EdgeId, EdgeId)` for access costs.
-This is also where the compass-powertrain crate loads an energy estimator.
-See [TraversalModel] for more details.
-
-### Algorithm
-
-RouteE Compass is set up to provide a suite of search algorithms which may be useful for different search problems.
-In all cases, these are assumed to be deterministic searches.
-At present, only an a star algorithm is implemented.
-
-Other graph algorithms may be added here in future, such as the connected components module.
-
-[Graph]: crate::model::graph::Graph
-[TraversalModel]: crate::model::traversal::traversal_model::TraversalModel
+routee-compass-core
+============
+Crate containing core routing modules of RouteE Compass used by all downstream crates. 
+
+[![crates.io](https://img.shields.io/crates/v/routee-compass-core.svg)](https://crates.io/crates/routee-compass-core)
+
+### Usage
+
+Unless you are only interested in the core RouteE Compass data structures and algorithms, consider instead installing the [complete application crate](https://crates.io/crates/routee-compass).
+
+To install as a library in Rust, add routee-compass-core to your Cargo.toml file:
+
+```toml
+[dependencies]
+routee-compass-core = { version = "0.2.0" }
+```
+
+Please see the [documentation](https://docs.rs/routee-compass-core/latest/routee_compass_core/) for usage.
+
+### License
+
+Copyright 2023 Alliance for Sustainable Energy, LLC
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

rust/routee-compass-core/src/doc.md

@@ -0,0 +1,43 @@
+# Compass Core Crate
+
+Crate containing core routing modules of RouteE Compass used by all downstream crates.
+This can be broken up into the following modules:
+- [`crate::model`] - [data-model](#data-model) of the search algorithm
+  - [`crate::model::graph`] - road network topology collection type
+  - [`crate::model::property`] - road network record types
+  - [`crate::model::traversal`] - search cost model
+  - [`crate::model::frontier`] - search frontier validation predicates
+  - [`crate::model::termination::termination_model`] - system-level rules on timeouts + limits for search
+- [`crate::algorithm`] - [algorithm](#algorithm) implementations
+  - [`crate::algorithm::search`] - search algorithm module
+    - [`crate::algorithm::search::search_algorithm_type::SearchAlgorithmType`] - enumeration listing search algorithm types, so far only traditional a star supported
+    - [`crate::algorithm::search::a_star::a_star`] - a star search implementation
+  - [`crate::algorithm::component:scc`] - strongly-connected components algorithm
+- [`crate::util`] - utility modules
+
+### Data Model
+
+RouteE Compass takes a layered approach to modeling the road network.
+At the core is the [Graph] model. 
+The edges and vertices are stored in `vec`s and carry the minimal data required for most search applications:
+- [`crate::model::property::edge::Edge`] records store distance in meters
+- [`crate::model::property::vertex::Vertex`] records store coordinate locations, assumed in WGS84 projection
+
+A forward and reverse adjacency list describes connectivity in the graph using the indices of the edges and vertices in their respective `vec`s.
+
+From this alone we can implement a distance-minimizing search.
+This is done via a [TraversalModel], which provides an API for computing the costs of traversal based on the search state, graph, and any exogenous datasets.
+The convention in RouteE Compass is to load additional `vec`s in the [TraversalModel] which can serve as lookup functions by `EdgeId` for traversal costs and `(EdgeId, EdgeId)` for access costs.
+This is also where the compass-powertrain crate loads an energy estimator.
+See [TraversalModel] for more details.
+
+### Algorithm
+
+RouteE Compass is set up to provide a suite of search algorithms which may be useful for different search problems.
+In all cases, these are assumed to be deterministic searches.
+At present, only an a star algorithm is implemented.
+
+Other graph algorithms may be added here in future, such as the connected components module.
+
+[Graph]: crate::model::graph::Graph
+[TraversalModel]: crate::model::traversal::traversal_model::TraversalModel

rust/routee-compass-core/src/lib.rs

@@ -1,4 +1,4 @@
-#![doc = include_str!("../README.md")]
+#![doc = include_str!("doc.md")]
 
 pub mod algorithm;
 pub mod model;

rust/routee-compass-powertrain/README.md

@@ -1,82 +1,32 @@
-# Compass Powertrain Crate
+routee-compass-powertrain
+============
+Crate containing core routing modules of RouteE Compass used by all downstream crates. 
 
-This crate provides energy-aware route planning models that integrate [RouteE Powertrain](https://github.com/nrel/routee-powertrain) into RouteE Compass.
-
-### Energy Estimation in RouteE Compass
-
-A RouteE Powertrain is an energy estimation model trained on NREL's [FASTSim](https://www.nrel.gov/transportation/fastsim.html) model.
-RouteE Powertrain is an ML model which makes it sufficiently fast to run within the loop of a route planner cost model.
-RouteE Powertrain models are trained and exported via the RouteE Powertrain utility and then loaded into a runtime at the core of this crate.
-
-### Model Runtimes
-
-There are two underlying model runtimes available, [smartcore](https://smartcorelib.org/) and [ort](https://github.com/pykeio/ort) (for [ONNX](https://onnx.ai/) models).
-By default, this crate is loaded with ONNX deactivated. 
-To activate the ONNX feature, pass the `onnx` feature flag during compilation.
-Runtime kernels for 3 common OSs have been provided in the onnx-runtime directory within this crate.
-For more information on cargo features, see The Cargo Book chapter on [Features](https://doc.rust-lang.org/cargo/reference/features.html).
-
-The runtime is loaded via the TraversalModel(s) in this crate and used to estimate costs in RouteE Compass searches.
+[![crates.io](https://img.shields.io/crates/v/routee-compass-powertrain.svg)](https://crates.io/crates/routee-compass-powertrain)
 
 ### Usage
 
-The TraversalModel in this crate is integrated into [compass-app](../compass-app/README.md) and can be installed by running compass-app with a TraversalModel that uses energy.
-An example traversal model configuration that uses this crate may look like this:
+This crate only includes code for running RouteE Powertrain models from RouteE Compass. For installing and running an application instance of RouteE Compass, consider instead installing the downstream [complete application crate](https://crates.io/crates/routee-compass).
+
+To install as a library in Rust, add routee-compass-powertrain to your Cargo.toml file:
 
 ```toml
-[traversal]
-type = "speed_grade_energy_model"
-model_type = "smartcore"
-speed_table_file = "edges-posted-speed-enumerated.txt.gz"
-energy_model_file = "2016_TOYOTA_Camry_4cyl_2WD.bin"
-ideal_energy_rate = 0.02857142857
-speed_table_speed_unit = "kilometers_per_hour"
-energy_model_speed_unit = "miles_per_hour"
-energy_model_grade_unit = "decimal"
-energy_model_energy_rate_unit = "gallons_gasoline_per_mile"
-output_time_unit = "minutes"
-output_distance_unit = "miles"
-grade_table_file = "edges-grade-enumerated.txt.gz"
-grade_table_grade_unit = "decimal"
+[dependencies]
+routee-compass-powertrain = { version = "0.2.0" }
 ```
 
-This TOML section is deserialized into JSON and passed as arguments to the SpeedGradeEnergyModelBuilder which in turn loads the [SpeedGradeModelService] in this crate.
-This in turn builds the [SpeedGradeModel].
-
-### Search
-
-TraversalModels in this crate will add energy estimation to road network search, and will differ in their dependencies and evaluation procedures. 
-
-#### SpeedGradeModel
-
-##### Dependencies
-
-- speeds per graph edge as a lookup table
-- grade per graph edge as a lookup table _(optional)_
-- an `energy_cost_coefficient` value, _(optional with default of 1.0)_
-- a `real_world_adjustment_factor` value, _(optional with default of 1.0)_
+Please see the [documentation](https://docs.rs/routee-compass-powertrain/latest/routee_compass_powertrain/) for usage.
 
-##### Evaluation
+### License
 
-1. lookup speed for the edge in table
-2. compute travel time as `distance / speed` for this edge
-3. lookup grade for this edge in table; if missing, use `0.0`
-4. perform inference to retrieve energy rate from speed and grade values
-5. compute energy as `energy_rate * distance * real_world_adjustment_factor` for this edge 
-6. compute link cost as `(energy * energy_cost_coefficient) + (time * (1 - energy_cost_coefficient))`
+Copyright 2023 Alliance for Sustainable Energy, LLC
 
-### Real-World Adjustment Factors
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
 
-In addition to calculating the energy based on a RouteE Powertrain output, an adjustment factor should be applied to capture real-world effects of running a powertrain in an environment.
-As a result of NREL research, some recommended values for this adjustment are:
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
 
-powertrain type | factor
---- | ---
-combustion vehicle (CV) | 1.1660
-hybrid vehicle (HV) | 1.1252
-electric vehicle (EV) | 1.3958
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
 
-A factor of 1.0 equates to 100% of the original energy value.
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
 
-[SpeedGradeModelService]: crate::routee::speed_grade_model_service::SpeedGradeModelService
-[SpeedGradeModelService]: crate::routee::speed_grade_model::SpeedGradeModel
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

rust/routee-compass-powertrain/src/doc.md

@@ -0,0 +1,82 @@
+# Compass Powertrain Crate
+
+This crate provides energy-aware route planning models that integrate [RouteE Powertrain](https://github.com/nrel/routee-powertrain) into RouteE Compass.
+
+### Energy Estimation in RouteE Compass
+
+A RouteE Powertrain is an energy estimation model trained on NREL's [FASTSim](https://www.nrel.gov/transportation/fastsim.html) model.
+RouteE Powertrain is an ML model which makes it sufficiently fast to run within the loop of a route planner cost model.
+RouteE Powertrain models are trained and exported via the RouteE Powertrain utility and then loaded into a runtime at the core of this crate.
+
+### Model Runtimes
+
+There are two underlying model runtimes available, [smartcore](https://smartcorelib.org/) and [ort](https://github.com/pykeio/ort) (for [ONNX](https://onnx.ai/) models).
+By default, this crate is loaded with ONNX deactivated. 
+To activate the ONNX feature, pass the `onnx` feature flag during compilation.
+Runtime kernels for 3 common OSs have been provided in the onnx-runtime directory within this crate.
+For more information on cargo features, see The Cargo Book chapter on [Features](https://doc.rust-lang.org/cargo/reference/features.html).
+
+The runtime is loaded via the TraversalModel(s) in this crate and used to estimate costs in RouteE Compass searches.
+
+### Usage
+
+The TraversalModel in this crate is integrated into [compass-app](../compass-app/README.md) and can be installed by running compass-app with a TraversalModel that uses energy.
+An example traversal model configuration that uses this crate may look like this:
+
+```toml
+[traversal]
+type = "speed_grade_energy_model"
+model_type = "smartcore"
+speed_table_file = "edges-posted-speed-enumerated.txt.gz"
+energy_model_file = "2016_TOYOTA_Camry_4cyl_2WD.bin"
+ideal_energy_rate = 0.02857142857
+speed_table_speed_unit = "kilometers_per_hour"
+energy_model_speed_unit = "miles_per_hour"
+energy_model_grade_unit = "decimal"
+energy_model_energy_rate_unit = "gallons_gasoline_per_mile"
+output_time_unit = "minutes"
+output_distance_unit = "miles"
+grade_table_file = "edges-grade-enumerated.txt.gz"
+grade_table_grade_unit = "decimal"
+```
+
+This TOML section is deserialized into JSON and passed as arguments to the SpeedGradeEnergyModelBuilder which in turn loads the [SpeedGradeModelService] in this crate.
+This in turn builds the [SpeedGradeModel].
+
+### Search
+
+TraversalModels in this crate will add energy estimation to road network search, and will differ in their dependencies and evaluation procedures. 
+
+#### SpeedGradeModel
+
+##### Dependencies
+
+- speeds per graph edge as a lookup table
+- grade per graph edge as a lookup table _(optional)_
+- an `energy_cost_coefficient` value, _(optional with default of 1.0)_
+- a `real_world_adjustment_factor` value, _(optional with default of 1.0)_
+
+##### Evaluation
+
+1. lookup speed for the edge in table
+2. compute travel time as `distance / speed` for this edge
+3. lookup grade for this edge in table; if missing, use `0.0`
+4. perform inference to retrieve energy rate from speed and grade values
+5. compute energy as `energy_rate * distance * real_world_adjustment_factor` for this edge 
+6. compute link cost as `(energy * energy_cost_coefficient) + (time * (1 - energy_cost_coefficient))`
+
+### Real-World Adjustment Factors
+
+In addition to calculating the energy based on a RouteE Powertrain output, an adjustment factor should be applied to capture real-world effects of running a powertrain in an environment.
+As a result of NREL research, some recommended values for this adjustment are:
+
+powertrain type | factor
+--- | ---
+combustion vehicle (CV) | 1.1660
+hybrid vehicle (HV) | 1.1252
+electric vehicle (EV) | 1.3958
+
+A factor of 1.0 equates to 100% of the original energy value.
+
+[SpeedGradeModelService]: crate::routee::speed_grade_model_service::SpeedGradeModelService
+[SpeedGradeModelService]: crate::routee::speed_grade_model::SpeedGradeModel

rust/routee-compass-powertrain/src/lib.rs

@@ -1,3 +1,3 @@
-#![doc = include_str!("../README.md")]
+#![doc = include_str!("doc.md")]
 
 pub mod routee;