API Reference¶
API Summary¶
Initial info data model |
|
The named tuple with info about extracted path or piece of path |
|
The named tuple with path info result |
|
The enumeration of travel time computation orders |
|
The enumeration of supported ODE solver methods |
|
MPE algorithm parameters model |
|
Context manager for using specified parameters |
|
Returns the default parameters |
|
Base exception class for all MPE errors |
|
The exception occurs when computing travel time has failed |
|
Base exception class for all extracting path errors |
|
The exception occurs when the ending point is not reached |
|
The named tuple with info about extracted path |
|
Minimal path extractor |
|
Extracts a minimal path by start/end and optionally way points |
Data and Models¶
-
class
skmpe.
InitialInfo
¶ Initial info data model
-
speed_data
¶ Speed data in numpy ndarray
-
start_point
¶ The starting point
-
end_point
¶ The ending point
-
way_points
¶ The tuple of way points
-
all_points
(self) → List[Sequence[int]]¶ Returns all initial points
-
point_intervals
(self) → List[Tuple[Sequence[int], Sequence[int]]]¶ Returns the list of the tuples of initial point intervals
-
-
class
skmpe.
PathInfo
¶ Bases:
tuple
The named tuple with info about extracted path or piece of path
-
path
¶ The path in numpy ndarray
-
start_point
¶ The starting point
-
end_point
¶ The ending point
-
travel_time
¶ The travel time numpy ndarray
-
extraction_result
¶ The path extraction result in
PathExtractionResult
that is returned byMinimalPathExtractor
-
reversed
¶ The flag is true if the extracted path is reversed
-
Parameters¶
-
class
skmpe.
TravelTimeOrder
¶ Bases:
enum.IntEnum
The enumeration of travel time computation orders
Orders:
first – the first ordered travel time computation
second – the second ordered travel time computation
-
first
= 1¶
-
second
= 2¶
-
class
skmpe.
OdeSolverMethod
¶ Bases:
str
,enum.Enum
The enumeration of supported ODE solver methods
-
BDF
= 'BDF'¶
-
DOP853
= 'DOP853'¶
-
LSODA
= 'LSODA'¶
-
RK23
= 'RK23'¶
-
RK45
= 'RK45'¶
-
Radau
= 'Radau'¶
-
-
class
skmpe.
Parameters
¶ MPE algorithm parameters model
-
travel_time_spacing
¶ The travel time computation spacing
default: 1.0
-
travel_time_order
¶ The travel time computation order
default:TravelTimeOrder.first
-
travel_time_cache
¶ Use or not travel time computation cache for extracting paths with way points
default: True
-
ode_solver_method
¶ ODE solver method
default: ‘RK45’
-
integrate_time_bound
¶ Integration time bound
default: 10000
-
integrate_min_step
¶ Integration minimum step
default: 0.0
-
integrate_max_step
¶ Integration maximum step
default: 4.0
-
dist_tol
¶ Distance tolerance for control path evolution
default: 1e-03
-
max_small_dist_steps
¶ The max number of small distance steps while path evolution
default: 100
-
dist_tol
= None
-
integrate_max_step
= None
-
integrate_min_step
= None
-
integrate_time_bound
= None
-
max_small_dist_steps
= None
-
ode_solver_method
= None
-
travel_time_cache
= None
-
travel_time_order
= None
-
travel_time_spacing
= None
-
-
skmpe.
parameters
(**kwargs)¶ Context manager for using specified parameters
- Parameters
- kwargsmapping
The parameters
Examples
>>> from skmpe import parameters >>> with parameters(integrate_time_bound=200000) as params: >>> print(params.__repr__()) Parameters( travel_time_spacing=1.0, travel_time_order=<TravelTimeOrder.first: 1>, travel_time_cache=False, ode_solver_method=<OdeSolverMethod.RK45: 'RK45'>, integrate_time_bound=200000.0, integrate_min_step=0.0, integrate_max_step=4.0, dist_tol=0.001, max_small_dist_steps=100 )
from skmpe import parameters, mpe ... with parameters(integrate_time_bound=200000): path_result = mpe(start_point, end_point)
-
skmpe.
default_parameters
() → skmpe.Parameters¶ Returns the default parameters
- Returns
- parametersParameters
Default parameters
Examples
>>> from skmpe import default_parameters >>> print(default_parameters().__repr__()) Parameters( travel_time_spacing=1.0, travel_time_order=<TravelTimeOrder.first: 1>, travel_time_cache=False, ode_solver_method=<OdeSolverMethod.RK45: 'RK45'>, integrate_time_bound=10000.0, integrate_min_step=0.0, integrate_max_step=4.0, dist_tol=0.001, max_small_dist_steps=100 )
Exceptions¶
-
class
skmpe.
MPEError
¶ Bases:
Exception
Base exception class for all MPE errors
-
class
skmpe.
ComputeTravelTimeError
¶ Bases:
skmpe.MPEError
The exception occurs when computing travel time has failed
-
class
skmpe.
PathExtractionError
(*args, travel_time: numpy.ndarray, start_point: Sequence[int], end_point: Sequence[int])¶ Bases:
skmpe.MPEError
Base exception class for all extracting path errors
-
property
end_point
¶ Ending point
-
property
start_point
¶ Starting point
-
property
travel_time
¶ Computed travel time data
-
property
-
class
skmpe.
EndPointNotReachedError
(*args, travel_time: numpy.ndarray, start_point: Sequence[int], end_point: Sequence[int], extracted_points: List[Sequence[float]], last_distance: float, reason: str)¶ Bases:
skmpe.PathExtractionError
The exception occurs when the ending point is not reached
-
property
end_point
¶ Ending point
-
property
extracted_points
¶ The list of extracted path points
-
property
last_distance
¶ The last distance to the ending point from the last path point
-
property
reason
¶ The reason of extracting path termination
-
property
start_point
¶ Starting point
-
property
travel_time
¶ Computed travel time data
-
property
Path Extraction¶
-
class
skmpe.
PathExtractionResult
¶ Bases:
tuple
The named tuple with info about extracted path
Notes
The instance of the class is returned from
MinimalPathExtractor.__call__()
.-
path_points
¶ The extracted path points in the list
-
path_integrate_times
¶ The list of integrate times for every path point
-
path_travel_times
¶ The list of travel time values for every path point
-
step_count
¶ The number of integration steps
-
func_eval_count
¶ The number of evaluations of the right hand function
-
-
class
skmpe.
MinimalPathExtractor
(speed_data: numpy.ndarray, end_point: Sequence[int], parameters: Optional[skmpe.Parameters] = None)¶ Minimal path extractor
Minimal path extractor based on the fast marching method and ODE solver.
- Parameters
- speed_datanp.ndarray
The speed data (n-d numpy array)
- end_pointSequence[int]
The ending point (a.k.a. “source point”)
- parametersclass:Parameters
The parameters
- Raises
- ComputeTravelTimeErrorComputing travel time has failed
Examples
from skmpe import MinimalPathExtractor # some function for computing speed data speed_data_2d = compute_speed_data_2d() mpe = MinimalPathExtractor(speed_data_2d, end_point=(10, 25)) path = mpe((123, 34))
-
__call__
(self, start_point: Sequence[int]) → skmpe.PathExtractionResult¶ Extract path from start point to source point (ending point)
- Parameters
- start_pointSequence[int]
The starting point
- Returns
- path_extraction_result
PathExtractionResult
The path extraction result
- path_extraction_result
- Raises
- PathExtractionErrorExtracting path has failed
- EndPointNotReachedErrorThe extracted path is not reached the ending point
-
property
parameters
¶ Returns the parameters
-
property
phi
¶ Returns the computed phi (zero contour) for given source point
-
property
travel_time
¶ Returns the computed travel time for given speed data
-
skmpe.
mpe
(*args, **kwargs) → skmpe.PathInfoResult¶ Extracts a minimal path by start/end and optionally way points
The function is high level API for extracting paths.
- Parameters
- init_info
InitialInfo
(sign 1) The initial info
- start_pointSequence[int]
(sign 2) The starting point
- end_pointSequence[int]
(sign 2) The ending point
- way_pointsSequence[Sequence[int]]
(sign 2) The way points
- parameters
Parameters
The parameters
- init_info
- Returns
- path_info
PathInfoResult
Extracted path info
- path_info
See also
Notes
There are two signatures of mpe function.
Use
InitialInfo
for init data:mpe(init_info: InitialInfo, *, parameters: Optional[Parameters] = None) -> ResultPathInfo
Set init data directly:
mpe(speed_data: np.ndarray, *, start_point: Sequence[int], end_point: Sequence[int], way_points: Sequence[Sequence[int]] = (), parameters: Optional[Parameters] = None) -> ResultPathInfo