crossing_smoothing

`FindEdge(cell_a, cell_b, case)` ¶

Class to return characteristics information about the edge connecting two cells. This information includes:

crossing (tuple) - Crossing point (long,lat) case (int) - Case type connecting the two cells start (dict) - Dictionary containing the environmental parameters of the start cell end (dict) - Dictionary containing the environmental parameters of the end cell

`PathValues(path_vars)` ¶

A class that returns attributes along a given path intersecting the environmental/vessel mesh.

Attributes:

Name	Type	Description
`unit_shipspeed`	`string) - unit speed type. This is a string of type`	'km/hr','knots'
`unit_time`	`string) - unit time format. This is a string of type`	'days','hr','min','s

Parameters:

Name	Type	Description	Default
`path_vars`		The path variables specified in the route config	required

`objective_function(adjacent_pairs, start_waypoint, end_waypoint)` ¶

Given a list of adjacent pairs determine the path related information apply waypoint_correction to get path related information along the path

Inputs

adjacent_pairs (list of type find_edge) - A list of the adjacent cell pairs in the form of find_edge start_waypoint (tuple) - Start waypoint (long,lat) end_waypoint (tuple) - End waypoint (long,lat)

`Smoothing(dijkstra_graph, adjacent_pairs, start_waypoint, end_waypoint, blocked_metric='SIC', max_iterations=2000, blocking_percentage=10.0, merge_separation=0.001, converged_sep=0.001, objective_function='traveltime')` ¶

Class construct that has all the operations required for path smoothing. Including: Relationship of adjacent pairs, edge finding new edges to add and returns a list of the adjacent pairs for the constructed path

Parameters:

Name	Type	Description	Default
`adjacent_pairs (list,find_edge) - An initial list of adjacent cell pairs as 'find_edge' objects comprising`		.start, the start cell environmental mesh dictionary; .end, the end environmental cell information; .crossing, a tuple of the crossing point on the edge (long,lat); and, .case, the adjacent cell case between the two cell boxes.	required

`add(index, ap_list)` ¶

Adding in a new adjacent cell pair

`blocked(new_cell, cell_a, cell_b)` ¶

Function that determines if the new cell being introduced is worse off than the original two cells according to various metrics.

Return

True if the cell cannot be entered, False if the cell can

`blocked_ice(new_cell, cell_a, cell_b)` ¶

Function that determines if the SIC of the new cell being introduced is worse than the original two cells. Currently, this is hard encoded to not enter a cell 5% worse off in Sea-Ice-Concentration

Return

True if the cell cannot be entered, False if the cell can

`blocked_objective(new_cell, cell_a, cell_b, blocked_variable)` ¶

Function that determines if the relevant objective variable of the new cell being introduced is worse than in the original two cells.

Return

True if the cell cannot be entered, False if the cell can

`blocked_tt(new_cell, cell_a, cell_b)` ¶

Function that determines if the tt for the new cell being introduced is worse than the original two cells.

Return

True if the cell cannot be entered, False if the cell can

`clip(cell_a, cell_b, case, x)` ¶

Given two cell boxes clip point to within the cell boxes

Function that clips back the crossing point so that it is only on the intersection between the two cell boxes in the adjacent cell pair

Return

x (tuple) - Updated crossing point clipped to cell intersection (long,lat)

`diagonal_case(case)` ¶

Function that determines if the adjacent cell pair is a diagonal case

Returns True is diagonal case, false if not

`diagonal_select_side(cell_a, cell_b, case, firstpoint, midpoint, lastpoint)` ¶

Assuming that midpoint is the common corner of the two cells in the diagonal edge ap. Then this function returns the cell that shares a boundary with both ap.start and ap.end on the same side of midpoint as the shorter great circle arc (using pyproj with default projection 'WGS84') passing between firstpoint and lastpoint.

If that cell is not in the neighbourhood graph then this returns None

Returns additional_indices (list) - A list of possible cell dictionary info. None if no index added. additional_cases (list) - A list of the cases connecting the additional cell indices. None if no index added.

`dist(start_point, end_point)` ¶

Determining the absolute distance between two points using pyproj and the reference project (default: WGS84)

Inputs

start_point (tuple) - Start Point (long,lat) end_point (tuple) - End Point (long,lat)

Outputs: distance (float) - Distance between the two points in km

`forward()` ¶

Applies inplace this function conducts a forward pass over the adjacent cell pairs, updating the crossing points between adjacent cell pairs for the given environmental conditions and great-circle characteristics. This is applied as a forward pass across the path moving out in adjacent cell pairs (triplets of crossing points with the cell adjacency).

Key features of forward pass include reverse edges - Removal of adjacent cell edges that enter and exit a cell on subsequent iterations. e.g. routes going back on themselves merging - When two crossing points are close, merge points and determine new common edge between start and end point diagonal case - If the middle point is a diagonal edge between cells, introduce a new cell box dependent on start and end crossing points. If cell is inaccessible 'blocked' then remain on corner for a later iteration.

                If exact diagonal, with same start and end crossing point, has be seen before
                then skip.

newton smooth - If adjacency is not diagonal then smooth the midpoint crossing point on the boundary given a
                horizontal or vertical smoothing. Returns a new midpoint that can either lie on the boundary
                between the two cells or outside the boundary

                If lies on the boundary then check if similar to previous seen case of this crossing point
                else continue and not converged

v shaped add  - If the crossing point lies outside the boundary in the newton smoothing stage the addition
                cell/cells must be included.

                Determine the new edges that need to be included if only a single cell (two edges) then do
                a v-shaped addition. If blocked then trim back. If exact v-shaped seen before, with same
                midpoint prime and possible edge additions, then skip. If blocked or seen before and crossing
                point hasn't changed within converge_sep then the crossing point has converged

u shaped add - Identical to v-shaped add but now with the addition of 2 cells (3 edges). If blocked then trim back. If exact v-shaped seen before, with same
                midpoint prime and possible edge additions, then skip. If blocked or seen before and crossing
                point hasn't changed within converge_sep then the crossing point has converged.

This code should be read relative to the pseudocode outlined in the paper. https://arxiv.org/pdf/2209.02389

`nearest_neighbour(start, end, case, x)` ¶

Returns the cell in the mesh that shares a boundary with cellA and has an edge on the line that extends the common boundary of cellA and cellB (and on which the point x lies) in the direction of x. If x lies inside cellA or there is no cell that satisfies these requirements, it returns null.

Returns additional_indices (list) - A list of possible cell dictionary info. None if no index added. additional_cases (list) - A list of the cases connecting the additional cell indices. None if no index added.

`newton_smooth(start, end, case, firstpoint, midpoint, lastpoint)` ¶

Given an adjacent cell pair that are non-diagonal determine the update to the crossing point/midpoint given the environmental conditions

Input

start (dict) - Dictionary of the start cell information end (dict) - Dictionary of the end cell information case (int) - Adjacency case type connecting the two cells firstpoint (tuple) - First Point (long,lat) midpoint (tuple) - Midpoint Point (long,lat) lastpoint (tuple) - Last Point (long,lat)

Return: midpoint (tuple) - Updated midpoint (long,lat)

`previous_diagonals(edge_a, edge_b, firstpoint, lastpoint)` ¶

For a diagonal-additional case determine if we have already seen these edges added in the same situation and the same first and last points. If a common past has been seen return True, otherwise add an additional case to of the diagonal to the global list and return False

Input

edge_a (find_edge) - First-edge connecting start cell to new cell edge_b (find_edge) - First-edge connecting new cell to end cell firstpoint (tuple) - firstpoint in the adjacent cell triplet of points (long,lat) lastpoint (tuple) - lastpoint in the adjacent cell triplet of points (long,lat)

Return

True if this diagonal case has been seen before, or false if not

`previous_us(edge_a, edge_b, edge_c, midpoint_prime)` ¶

For a U-additional case determine if we have already seen these edges added in the same situation and the same crossing point. If a common past has been seen return True, otherwise add this U-additional case to a global list and return False

Input

edge_a (find_edge) - First-edge connecting start cell to new cell 1 edge_b (find_edge) - First-edge connecting new cell 1 to new cell 2 edge_c (find_edge) - First-edge connecting new cell 2 to end cell midpoint_prime (tuple) - midpoint that triggered the u-additional case addition (long,lat)

Return

True if this U-additional case has been seen before, or false if not

`previous_vs(edge_a, edge_b, midpoint_prime)` ¶

For a V-additional case determine if we have already seen this edge added in the same situation. If a common past has been seen return True, otherwise add this v-additional case to a global list and return False

Return

True if this v-additional case has been seen before, or false if not

`remove(index)` ¶

Removing an adjacent cell pair

`dist_around_globe(start_point, crossing_point)` ¶

Determining the longitude distance around the globe between two points

Parameters:

Name	Type	Description	Default
`start_point`	`tuple`	Start Waypoint (long,lat)	required
`crossing_point`	`tuple`	End Waypoint (long,lat)	required

Returns: a (float): longitude distance between the two points in degrees

`rhumb_line_distance(start_waypoint, end_waypoint)` ¶

Defining the rhumb line distance from a given waypoint start and end point

Parameters:

Name	Type	Description	Default
`start_waypoint`	`list([Long, lat])`	Start Waypoint location with long lat	required
`end_waypoint`	`list([Long, lat])`	End Waypoint location with long lat	required

Returns:

Name	Type	Description
`distance`	`float`	Calculated rhumb line distance

`rhumb_traveltime_in_cell(cellbox, cp, sp, s, u, v)` ¶

Calculates traveltime in a cellbox based off of rhumb line distance

Parameters:

Name	Type	Description	Default
`cellbox`	`dict`	Cellbox containing line segment being analysed	required
`cp`	`ndarray`	End waypoint coordinates (long,lat)	required
`sp`	`ndarray`	Start waypoint coordinates (long,lat)	required
`s`	`float`	Ship speed value	required
`u`	`float`	Current velocity x-component	required
`v`	`float`	Current velocity y-component	required

Returns:

Name	Type	Description
`tt`	`float`	Calculated rhumb line travel time

crossing_smoothing

FindEdge(cell_a, cell_b, case) ¶

PathValues(path_vars) ¶

objective_function(adjacent_pairs, start_waypoint, end_waypoint) ¶

Smoothing(dijkstra_graph, adjacent_pairs, start_waypoint, end_waypoint, blocked_metric='SIC', max_iterations=2000, blocking_percentage=10.0, merge_separation=0.001, converged_sep=0.001, objective_function='traveltime') ¶

add(index, ap_list) ¶

blocked(new_cell, cell_a, cell_b) ¶

blocked_ice(new_cell, cell_a, cell_b) ¶

blocked_objective(new_cell, cell_a, cell_b, blocked_variable) ¶

blocked_tt(new_cell, cell_a, cell_b) ¶

clip(cell_a, cell_b, case, x) ¶

diagonal_case(case) ¶

diagonal_select_side(cell_a, cell_b, case, firstpoint, midpoint, lastpoint) ¶

dist(start_point, end_point) ¶

forward() ¶

nearest_neighbour(start, end, case, x) ¶

newton_smooth(start, end, case, firstpoint, midpoint, lastpoint) ¶

previous_diagonals(edge_a, edge_b, firstpoint, lastpoint) ¶

previous_us(edge_a, edge_b, edge_c, midpoint_prime) ¶

previous_vs(edge_a, edge_b, midpoint_prime) ¶

remove(index) ¶

dist_around_globe(start_point, crossing_point) ¶

rhumb_line_distance(start_waypoint, end_waypoint) ¶

rhumb_traveltime_in_cell(cellbox, cp, sp, s, u, v) ¶

`FindEdge(cell_a, cell_b, case)` ¶

`PathValues(path_vars)` ¶

`objective_function(adjacent_pairs, start_waypoint, end_waypoint)` ¶

`Smoothing(dijkstra_graph, adjacent_pairs, start_waypoint, end_waypoint, blocked_metric='SIC', max_iterations=2000, blocking_percentage=10.0, merge_separation=0.001, converged_sep=0.001, objective_function='traveltime')` ¶

`add(index, ap_list)` ¶

`blocked(new_cell, cell_a, cell_b)` ¶

`blocked_ice(new_cell, cell_a, cell_b)` ¶

`blocked_objective(new_cell, cell_a, cell_b, blocked_variable)` ¶

`blocked_tt(new_cell, cell_a, cell_b)` ¶

`clip(cell_a, cell_b, case, x)` ¶

`diagonal_case(case)` ¶

`diagonal_select_side(cell_a, cell_b, case, firstpoint, midpoint, lastpoint)` ¶

`dist(start_point, end_point)` ¶

`forward()` ¶

`nearest_neighbour(start, end, case, x)` ¶

`newton_smooth(start, end, case, firstpoint, midpoint, lastpoint)` ¶

`previous_diagonals(edge_a, edge_b, firstpoint, lastpoint)` ¶

`previous_us(edge_a, edge_b, edge_c, midpoint_prime)` ¶

`previous_vs(edge_a, edge_b, midpoint_prime)` ¶

`remove(index)` ¶

`dist_around_globe(start_point, crossing_point)` ¶

`rhumb_line_distance(start_waypoint, end_waypoint)` ¶

`rhumb_traveltime_in_cell(cellbox, cp, sp, s, u, v)` ¶