Table of Contents
This is an ocean vessel path finding algorithm that optimizes fuel consumption and travel time between destinations. We achieve this by combining the locally optimal solution found by the classic Zermelo's Navigation Problem and applies a discretized Jacobi-Newton method for path smoothing and global optimization.
The repository is structured into the following directories:
/hybrid_routing: where the python code is.
Conveniently, a set of workflows via Github actions are already installed:
black: Code styling & formatting.
In addition, all docstrings shall be in the numpy format.
This package is purely written in Python and it depends on Scipy, Numpy, and Google's JAX with their dependencies. All packages and dependencies are listed in requirements.txt.
There are two install options, we recommend installing an environment using conda. However it would work with a regular pip install.
- Conda:
Make sure to activate the conda environment once installation is finished.
conda env create -f environment.yml --force - Pip:
pip install -r requirements.txt pip install -e .[dev]
you can also use make install.
The difference between conda and pip is that conda will create an isolated environment while pip will install all the dependencies in the current Python env. This might be a conda environment or any other Python env created by other tools. If you already have the dependencies installed, you can update it to reflect the last version of the packages in the requirements.txt with pip-sync.
Add abstract dependency to setup.py. If neccessary, add version requirements but try to be as flexible as possible
- Update
requirements.txt:pip-compile --extra dev > requirements.txt - Update environment:
pip-sync
The library is structured as follows.
The module hybrid_routing.vectorfields contains all the different Vectorfield classes used in our study. Each Vectorfield implements a synthetic field of sea currents.
Sample code to use vectorfields:
from hybrid_routing.vectorfields import Circular
# Initialize the vectorfield
vectorfield = Circular()
# Get the current velocity (u, v) at point (x, y)
# x = longitude, y = latitude
x, y = 0.5, 0.2
# u = velocity vector component parallel to longitude
# v = velocity vector component parallel to latitude
u, v = vectorfield.get_current(x, y)
# Plot the vectorfield
vectorfield.plot()Here is the expected plot output:
The module hybrid_routing.jax_utils implements all the functions to optimize a route by using JAX.
Example and set up of optimize_route:
from hybrid_routing.jax_utils.optimize import optimize_route
from hybrid_routing.vectorfields import NoCurrent
import numpy
# We must provide the following parameters:
# vectorfield, (x_start, y_start), (x_end, y_end)
vectorfield = NoCurrent()
x_start, y_start = 0, 0
x_end, y_end = 10, 10
# The following parameters are optional, but we recommend
# you test them out:
# time_iter, time_step, angle_amplitude,
# num_angles, vel, dist_min
time_iter, time_step = 5, 0.5
angle_amplitude, num_angles = np.pi/2, 6
vel, dist_min = 2.5, 1
# invoking optimize route function:
list_routes = optimize_route(
vectorfield,
x_start, y_start,
x_end, y_end,
time_iter = time_iter, time_step = time_step,
angle_amplitude = angle_amplitude, num_angles = num_angles,
vel = vel, dist_min = dist_min)
# "list_routes" contains all paths as entries orginates
# from (x_start, y_start), each entry is a list of points
# (x, y, theta). It has the same length as time_iter /
# time_step, and there are "num_angles" amount of entries.
# The path that brings us closest to (x_end, y_end) is
# the first entry, as we are printing below:
print(list_routes[0])The diagram below illustrates the setup:
(x0, y0) = (x_start, y_start),
(xN, yN) = (x_end, y_end).
This module is not used right now. Avoid calling it.
The module hybrid_routing.tf_utils implements all the functions to optimize a route by using TensorFlow.
---SECTION UNDER CONSTRUCTION---
The module hybrid_routing.web contains the utils used to deploy our demo. You can learn more about this in our demo section.
With the hybrid-routing environment active, you can initialize the web application by running the following command:
streamlit run hybrid_routing/demo.py --server.port 8501
The demo will start at port 8501 (you can change the port to anyone you prefer). Then you can access the web in your PC by going to http://localhost:8501
Official website: https://smartshipping.es/
Robert Milson - rmilson@dal.ca
Project link: https://github.com/ShrimpyLouis/hybrid_ivp