Rjf/expose graph ops

[robfitzgerald]

this PR adds a few simple commands to inspect graph attributes from CompassApp and CompassAppWrapper / python CompassApp. that includes:

    def graph_edge_origin(self, edge_id: int) -> int:
    def graph_edge_destination(self, edge_id: int) -> int:
    def graph_edge_distance(self, edge_id: int, distance_unit: Optional[str]) -> float:
    def graph_get_out_edge_ids(self, vertex_id: int) -> List[int]:
    def graph_get_in_edge_ids(self, vertex_id: int) -> List[int]:

each time one of these methods is called, we clone the Arc<DriverReadOnlyLock<Graph>>, which is a small performance hit which may be acceptable for some one-off operations but may slow things down for large batch queries. if that becomes a bottleneck we can add some batch operations that follow the pattern of these methods to amortize the clone runtime hit.

example

using the golden, co test case in the notebook example, i have this for my edges-compass.csv.gz file:

      edge_id  src_vertex_id  dst_vertex_id  distance
0           0              0            429   474.918
1           1              2              3    71.722
2           2              2            173    33.589
3           3              2            178   111.341
4           4              3              2    71.722
...       ...            ...            ...       ...
1755     1755            743            474    59.098
1756     1756            743            744    25.754     <---- this row in example
1757     1757            744            732    31.905
1758     1758            745            574    21.303
1759     1759            745            663   217.939

i run these queries and get this result:

(
    app.graph_edge_origin(1756),
    app.graph_edge_destination(1756),
    app.graph_edge_distance(1756, None),          # None is also the default argument
    app.graph_edge_distance(1756, 'meters'),       
    app.graph_edge_distance(1756, 'kilometers'),
    app.graph_edge_distance(1756, 'miles'),
    app.graph_get_out_edge_ids(743),
    app.graph_get_in_edge_ids(744)
)
(743,
 744,
 25.754,
 25.754,                  # meters is default
 0.025754000000000003,    # 25.75 / 1000
 0.0160062150410092,      # 25.75 / 1609
 [1755, 1756],            # includes test row id
 [1733, 1756])            # includes test row id

Closes #15.

[robfitzgerald]

i'll add an example of error handling for distance units here:

app.graph_edge_distance(1756, 'boog')

---------------------------------------------------------------------------
Exception                                 Traceback (most recent call last)
[/Users/rfitzger/dev/nrel/routee/routee-compass/docs/notebooks/open_street_maps_example.ipynb](https://file+.vscode-resource.vscode-cdn.net/Users/rfitzger/dev/nrel/routee/routee-compass/docs/notebooks/open_street_maps_example.ipynb) Cell 10 line 1
----> [1](vscode-notebook-cell:/Users/rfitzger/dev/nrel/routee/routee-compass/docs/notebooks/open_street_maps_example.ipynb#X40sZmlsZQ%3D%3D?line=0) app.graph_edge_distance(1756, 'boog')

File [~/dev/nrel/routee/routee-compass/python/nrel/routee/compass/compass_app.py:120](https://file+.vscode-resource.vscode-cdn.net/Users/rfitzger/dev/nrel/routee/routee-compass/docs/notebooks/~/dev/nrel/routee/routee-compass/python/nrel/routee/compass/compass_app.py:120), in CompassApp.graph_edge_distance(self, edge_id, distance_unit)
    [119](https://file+.vscode-resource.vscode-cdn.net/Users/rfitzger/dev/nrel/routee/routee-compass/docs/notebooks/~/dev/nrel/routee/routee-compass/python/nrel/routee/compass/compass_app.py:119) def graph_edge_distance(self, edge_id: int, distance_unit: Optional[str]) -> float:
--> [120](https://file+.vscode-resource.vscode-cdn.net/Users/rfitzger/dev/nrel/routee/routee-compass/docs/notebooks/~/dev/nrel/routee/routee-compass/python/nrel/routee/compass/compass_app.py:120)     return self._app.graph_edge_distance(edge_id, distance_unit)

Exception: could not deserialize distance unit 'boog'

[nreinicke]

Cool, this makes sense to me. I left a small request for a comment.

[nreinicke]

Wonder if we could add some comments here to explain why this has to be done or maybe create a simple ops function that does this?

[robfitzgerald]

for real. i was fishing around for this trick and have run into this previously as well. i'll add a comment, as i'm not sure it's the best way to leverage serde to decode non-parameterized enums from a string.

[robfitzgerald]

eh, @nreinicke, i changed my mind; i'll make a generic utility for it, and then leverage that in FromStr implementations for the Unit types. coming right up.

[robfitzgerald]

@nreinicke addressed your comment by making that a generic util and then using it in FromStr implementations for the Unit types.

[nreinicke]

Sweet, looks great! Thanks for adding these in!