From c3c5d35aa1ed99596086f10d05eb218e60dbf951 Mon Sep 17 00:00:00 2001 From: CoderBear801 Date: Wed, 1 Jul 2020 10:06:24 -0700 Subject: [PATCH 1/3] doc: Initial document for oasis architecture design issue: #359 --- integration/doc/oasis/README.md | 7 ++ integration/doc/oasis/architecture_design.md | 87 ++++++++++++++++++++ 2 files changed, 94 insertions(+) create mode 100644 integration/doc/oasis/README.md create mode 100644 integration/doc/oasis/architecture_design.md diff --git a/integration/doc/oasis/README.md b/integration/doc/oasis/README.md new file mode 100644 index 00000000000..203a308e4ae --- /dev/null +++ b/integration/doc/oasis/README.md @@ -0,0 +1,7 @@ +OASIS stands for Optimized Charge Station Selection Service, which mainly supports generating optimal charge station candidates for given query based on user's vehical information. It expects routing engine(like OSRM) to generate electronic spcific cost and only focus on how to choose most optimal charge station combination which balances charging cost(charging time, payment, etc). +For example, OASIS might suggest user spend 1 hour to charge at station A for x amount of energy then reach destination with 2 hours in total, or charge at station B and station C for 30 minutes each and reach destination with duration of 2 hours 10 minutes. + +Documents +- [api document](./api.md) +- [architecture design](./architecture_design.md) + \ No newline at end of file diff --git a/integration/doc/oasis/architecture_design.md b/integration/doc/oasis/architecture_design.md new file mode 100644 index 00000000000..ddf9ddbc4e6 --- /dev/null +++ b/integration/doc/oasis/architecture_design.md @@ -0,0 +1,87 @@ +# Architecture design + +## Overview +overview
+ +## Service layer +overview
+ +## Solution layer + +overview
+ +- `Solution` is the layer contains logic for how to select charge stations, such as + * whether need charge or not + * is destination reachable by single charge + * multiple charge station solution finding, which could be search along route or charge station based routing, implemented by lower layer +- `GenerateSolution` abstract the interface for how to generate multiple charge station solution + +## Graph layer + +overview
+ +- `stationgraph` implements the `GenerateSolution` interface, and this package represents algorithm +- `chargingstrategy` abstract logic of `charge` which supports calculation in `stationgraph` + +## Place layer + +overview
+ +A different view: +overview
+ +Definition of `Place` +```go +// Place records place(location, point of interest) related information such as +// ID and location +// Place represents charge stations for most of times for OASIS service, but it +// could also represent for a user select location such as original location or +// destination location. +type Place struct { + ID PlaceID + Location *nav.Location +} + +// PlaceID defines ID for given place(location, point of interest) +// The data used for pre-processing must contain valid PlaceID, which means it +// either a int64 directly or be processed as int64 +type PlaceID int64 +``` + +Definition of `TopoQuerier` interface +```go +// TopoQuerier used to return topological information for places +type TopoQuerier interface { + + // GetNearByPlaces finds near by stations by given placeID and return them in recorded sequence + // Returns nil if given placeID is not found or no connectivity + GetNearByPlaces(placeID common.PlaceID) []*common.RankedPlaceInfo + + // LocationQuerier returns *nav.location for given placeID + LocationQuerier +} +``` + +Definition of `SpatialQuerier` interface +```go +// SpatialQuerier answers special query +type SpatialQuerier interface { + + // GetNearByPlaceIDs returns a group of places near to given center location + GetNearByPlaceIDs(center nav.Location, radius float64, limitCount int) []*common.PlaceInfo +} +``` +Definition of `LocationQuerier` interface +```go +// LocationQuerier returns *nav.location for given placeID +type LocationQuerier interface { + + // GetLocation returns *nav.Location for given placeID + // Returns nil if given placeID is not found + GetLocation(placeID PlaceID) *nav.Location +} +``` + + +## More info +- For discussions, please go to [#352](https://github.com/Telenav/osrm-backend/issues/352) \ No newline at end of file From f858908bf6e854b2a53c8fd3327c020a21529427 Mon Sep 17 00:00:00 2001 From: CoderBear801 Date: Wed, 1 Jul 2020 10:13:18 -0700 Subject: [PATCH 2/3] fix: update document --- CHANGELOG-FORK.md | 4 ++-- integration/doc/oasis/architecture_design.md | 2 ++ 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/CHANGELOG-FORK.md b/CHANGELOG-FORK.md index e856ab38591..f804b05a168 100644 --- a/CHANGELOG-FORK.md +++ b/CHANGELOG-FORK.md @@ -6,12 +6,12 @@ Changes from v10.3.0 - CHANGED for integration of pre-generated connectivity data with OASIS service [#339](https://github.com/Telenav/osrm-backend/pull/339) - CHANGED for internal refactoring, replace `Location` in `spatialindexer` to nav.Location, replace all name of `point` to `place` [#341](https://github.com/Telenav/osrm-backend/pull/341) - CHANGED for internal refactoring, move package oasis/solution, oasis/osrmhelper and oasis/searchhelper into oasis/internal [#343](https://github.com/Telenav/osrm-backend/pull/343) - - CHANGED for internal refactoring, improve performance for OASIS service, more information please go to [#344](https://github.com/Telenav/osrm-backend/issues/344) [#353](https://github.com/Telenav/osrm-backend/pull/353) + - CHANGED for internal refactoring, improve performance for OASIS service, more information please go to [#344](https://github.com/Telenav/osrm-backend/issues/344) [#353](https://github.com/Telenav/osrm-backend/pull/353) - Bugfix: - Performance: - Tools: - Docs: - + - ADDED document `oasis architecture design` [#360](https://github.com/Telenav/osrm-backend/pull/360) # v10.3.0 Changes from v10.2.0 diff --git a/integration/doc/oasis/architecture_design.md b/integration/doc/oasis/architecture_design.md index ddf9ddbc4e6..1219310a388 100644 --- a/integration/doc/oasis/architecture_design.md +++ b/integration/doc/oasis/architecture_design.md @@ -16,6 +16,8 @@ * multiple charge station solution finding, which could be search along route or charge station based routing, implemented by lower layer - `GenerateSolution` abstract the interface for how to generate multiple charge station solution + + ## Graph layer overview
From 7027ff235312e7d069cb3500d9a0320df6d84c00 Mon Sep 17 00:00:00 2001 From: CoderBear801 Date: Mon, 6 Jul 2020 11:56:31 -0700 Subject: [PATCH 3/3] fix: adjust comments based on Jay's recommendation --- integration/doc/oasis/README.md | 2 +- integration/doc/oasis/architecture_design.md | 4 ++-- integration/service/oasis/spatialindexer/interface.go | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/integration/doc/oasis/README.md b/integration/doc/oasis/README.md index 203a308e4ae..6f222b3f761 100644 --- a/integration/doc/oasis/README.md +++ b/integration/doc/oasis/README.md @@ -1,4 +1,4 @@ -OASIS stands for Optimized Charge Station Selection Service, which mainly supports generating optimal charge station candidates for given query based on user's vehical information. It expects routing engine(like OSRM) to generate electronic spcific cost and only focus on how to choose most optimal charge station combination which balances charging cost(charging time, payment, etc). +OASIS stands for Optimized Charge Station Selection Service, which mainly supports generating optimal charge station candidates for given query based on user's vehical information. It expects routing engine(like OSRM) to generate electronic specific cost and only focus on how to choose most optimal charge station combination which balances charging cost(charging time, payment, etc). For example, OASIS might suggest user spend 1 hour to charge at station A for x amount of energy then reach destination with 2 hours in total, or charge at station B and station C for 30 minutes each and reach destination with duration of 2 hours 10 minutes. Documents diff --git a/integration/doc/oasis/architecture_design.md b/integration/doc/oasis/architecture_design.md index 1219310a388..bb8d5241167 100644 --- a/integration/doc/oasis/architecture_design.md +++ b/integration/doc/oasis/architecture_design.md @@ -13,7 +13,7 @@ - `Solution` is the layer contains logic for how to select charge stations, such as * whether need charge or not * is destination reachable by single charge - * multiple charge station solution finding, which could be search along route or charge station based routing, implemented by lower layer + * multiple charge station solution finding, which could be search along route or charge station based routing, implemented by internal layer - `GenerateSolution` abstract the interface for how to generate multiple charge station solution @@ -66,7 +66,7 @@ type TopoQuerier interface { Definition of `SpatialQuerier` interface ```go -// SpatialQuerier answers special query +// SpatialQuerier answers spatial query type SpatialQuerier interface { // GetNearByPlaceIDs returns a group of places near to given center location diff --git a/integration/service/oasis/spatialindexer/interface.go b/integration/service/oasis/spatialindexer/interface.go index a7830408cf3..3fe00c9c4cf 100644 --- a/integration/service/oasis/spatialindexer/interface.go +++ b/integration/service/oasis/spatialindexer/interface.go @@ -10,7 +10,7 @@ import ( // UnlimitedCount means all spatial search result will be returned const UnlimitedCount = math.MaxInt32 -// Finder answers special query +// Finder answers spatial query type Finder interface { // FindNearByPlaceIDs returns a group of places near to given center location