Merging main into rearchitecture

.gitignore

@@ -17,6 +17,7 @@ TestingNotebook.ipynb
 *.output.*json
 setup.cfg
 pip.sh
+datastore
 ./datastore/*
 datastore/*
 configs/*

docs/html/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: ce4e0f8520efa054677bcf5ff36a7f0f
+config: e5ba9cc97cc24cfb59e2b851b40042ab
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/html/_sources/index.rst.txt

@@ -2,9 +2,11 @@ Welcome to the PolarRoute Manual Pages
 ======================================
 
 PolarRoute is a tool for the optimisation of routes for maritime vehicles travelling in polar waters.
-This software package has been developed by the **British Antarctic Survey** (BAS), primarily 
-for the optimisation of polar routes for the BAS research vessel RRS Sir David Attenborough, 
-though it is applicable to any vessel (e.g. AUVs). The software is written in Python and is open source.
+It is an extension of `MeshiPhi <https://github.com/antarctica/MeshiPhi>`_; a package designed to 
+discretise the world from heterogeneous data sources (follow link for more details and docs). 
+This software package has been developed by the **British Antarctic Survey** (BAS), primarily for the 
+optimisation of polar routes for the BAS research vessel RRS Sir David Attenborough, though it is applicable 
+to any vessel (e.g. AUVs). The software is written in Python and is open source.
 
 For more information on the project, please visit the `PolarRoute website <https://www.bas.ac.uk/project/autonomous-marine-operations-planning/>`_
 and follow our `GitHub repository <https://github.com/antarctica/PolarRoute>`_.
@@ -25,10 +27,8 @@ Contents:
    ./sections/Command_line_interface
    ./sections/Configuration/Configuration_overview
    ./sections/Outputs
-   ./sections/Dataloaders/overview
-   ./sections/Mesh_Construction/Mesh_construction_overview
    ./sections/Vehicle_specifics
-   ./sections/Route_optimisation
    ./sections/Route_calculation
+   ./sections/Route_optimisation
    ./sections/Examples
 

docs/html/_sources/sections/Code_overview.rst.txt

@@ -0,0 +1,37 @@
+**********
+Background
+**********
+
+Code Overview
+#############
+
+The PolarRoute package provides an automated route-planning method for use by an ice-strengthened vessel operating in the polar regions. The long-distance route planning approach builds on the method developed for underwater vehicles reported in Fox et al (2021). We start with the same grid-based route construction approach to obtain routes that satisfy constraints on the performance of the ship in ice. We then apply a novel route-smoothing method to the resulting routes, shortening the grid-based routes and ensure that routes follow great circle arcs where possible. This two-stage process efficiently generates routes that follow standard navigation solutions in open water and optimise vessel performance in and around areas dominated by sea ice.  While we have focussed on navigation in and around polar ice, our methods are also applicable to shipping in a broader context (e.g.: commercial shipping) where route-planning must be responsive to changing local and weather conditions.
+
+
+Code Structure
+##############
+The aim of this manual is to provide the user with all the tools that they need to run the software for a set of examples. We also hope that the background information supplied for each section allows the user to understand the methods used throughout this software package.
+
+The PolarRoute package can be separated into the four main sections shown in the Figure below:
+
+.. figure:: ./Figures/FlowDiagram_Overview.png
+   :align: center
+   :width: 700
+
+   *Overview figure outlining the stages in planning a route with PolarRoute. Generation of the initial environmental mesh is performed by the MeshiPhi package.*
+
+The separate stages can be broken down into:
+
+1. :ref:`Vessel Performance <vessel-performance>` - Application of vehicle specific features applied to the discrete mesh. In this section we will supply the user with the knowledge of how vehicle specific features are applied to the discrete mesh or with variables applied to the computational graph of the mesh.
+2. :ref:`Route Planner` - Generating grid-based dijkstra paths and data constrained path smoothing from the gridded solutions - In this section we will give the user the background to constructing paths between user defined waypoints that minimise a specific objective function (e.g. travel time, fuel). Once the gridded Dijkstra paths are formulated we outline a smoothing based procedure that uses the data information to generate non-gridded improved route paths.
+
+.. figure:: ./Figures/PolarRoute_CodeFlowDiagram.png
+   :align: center
+   :width: 700
+
+   *Overview figure outlining the Input/Output of all sections of the Route Planning pipeline*
+
+Each stage of this pipeline makes use of a configuration file, found in the :ref:`Configuration Overview` section of the documentation
+and produces an output file, the form of which can be found in the :ref:`outputs` section of this document.
+
+In addition to the main section of the codebase we have also developed a series of plotting classes that allows the user to generate interactive maps and static figures for the Mesh Features and Route Paths. These can be found in the `Plotting` section later in the manual.

docs/html/_sources/sections/Command_line_interface.rst.txt

@@ -0,0 +1,143 @@
+###############################
+Command Line Interface
+###############################
+
+The PolarRoute package provides 4 CLI entry points, intended to be used in succession to plan a route through a digital environment.
+
+.. figure:: ./Figures/PolarRoute_CLI.png
+   :align: center
+   :width: 700
+
+   *Overview figure of the Command Line Interface entry points of PolarRoute*
+
+^^^^^^^^^^^
+add_vehicle
+^^^^^^^^^^^
+The *add_vehicle* command allows vehicle specific simulations to be performed on the digital environment. This vehicle specific
+information is then encoded into the digital environment file.
+
+::
+
+    add_vehicle <vessel_config.json> <mesh.json>
+
+positional arguments:
+
+::
+
+    vessel_config : A configuration file detailing the vessel to be simulated in the digital environment.
+    mesh : A digital environment file.
+
+The format for the required *<vessel.json>* file can be found in the :ref:`configuration - vessel performance modeller` section of the documentation.
+The required *<mesh.json>* file can be created using the *create_mesh* command from the `MeshiPhi <https://github.com/antarctica/MeshiPhi>`_ package.
+
+optional arguments are
+
+::
+
+    -v (verbose logging)
+    -o <output location> (set output location for mesh)
+
+The format of the return Vessel_Mesh.json file is explain in :ref:`the vessel_mesh.json file` section of the documentation.
+
+^^^^^^^^^^^^^^^
+optimise_routes
+^^^^^^^^^^^^^^^
+Optimal routes through a mesh can be calculated using the command:
+
+::
+
+    optimise_routes <route_config.json> <vessel_mesh.json> <waypoints.csv>
+
+positional parameters:
+
+::
+
+    vessel_mesh : A digital environment file with added vessel specific simulations.
+    route_config : A configuration file detailing optimisation parameters to be used when route planning.
+    waypoints: A .csv file containing waypoints to be travelled between.
+
+
+The format for the required *<route_config.json>* file can be found in the :ref:`configuration - route planning` section of the documentation.
+The required *<vessel_mesh.json>* file can be generated using the :ref:`add_vehicle` command shown above.
+The format for the required *<waypoints.csv>* file is as follows:
+
+As table:
+
++------------------+---------------+---------------+---------+---------------+
+| Name             | Lat           | Long          | Source  | Destination   |
++==================+===============+===============+=========+===============+
+| Halley           | -75.26722     | -27.21694     |         | X             |
++------------------+---------------+---------------+---------+---------------+
+| Rothera          | -68.3892      | -95.2436      |         |               |
++------------------+---------------+---------------+---------+---------------+
+| South Georgia    | -54.87916667  | -37.26416667  | X       |               |
++------------------+---------------+---------------+---------+---------------+
+| Falklands        | -55.63472222  | -64.88        |         |               |
++------------------+---------------+---------------+---------+---------------+
+| Elephant Island  | -60.54722222  | -55.18138889  |         |               |
++------------------+---------------+---------------+---------+---------------+
+
+As .csv:
+
+::
+
+    Name,Lat,Long,Source,Destination
+    Halley,-75.26722,-27.21694,,X
+    Rothera,-68.3892,-95.2436,,
+    South Georgia,-54.87916667,-37.26416667,X,
+    Falklands,-55.63472222,-64.88,,
+    Elephant Island,-60.54722222,-55.18138889,,
+
+Additional waypoints may be added by extending the '<waypoints.csv>' file. Which waypoints are navigated between is determined by 
+added a **X** in either the *Source* or *Destination* columns. When processed, the route planner will create routes from all 
+waypoints marked with an **X** in the source column to all waypoints marked with a **X** in the *destination* column. 
+
+optional arguments are
+
+::
+
+    -v (verbose logging)
+    -o <output location> (set output location for mesh)
+    -p (output only the calculated path, not the entire mesh)
+    -d (output Dijkstra path as well as smoothed path)
+
+
+The format of the returned *<route.json>* file is explained in :ref:`the route.json file` section of the documentation.
+
+^^^^^^^^^^^^^^^
+calculate_route
+^^^^^^^^^^^^^^^
+The cost of a user-defined route through a pre-generated mesh containing vehicle information can be calculated using the command:
+
+::
+
+    calculate_route <vessel_mesh.json> <route>
+
+positional parameters:
+
+::
+
+    vessel_mesh : A digital environment file with added vessel specific simulations.
+    route : A route file containing waypoints on a user-defined path.
+
+optional arguments:
+
+::
+
+    -v : verbose logging
+    -o : output location
+
+Running this command will calculate the cost of a route between a set of waypoints provided in either csv or geojson
+format. The route is assumed to travel from waypoint to waypoint in the order they are given, following a rhumb line.
+The format of the output *<route.json>* file is identical to that from the :ref:`optimise_routes` command.
+This is explained in :ref:`the route.json file` section of the documentation. The time and fuel cost of the route will
+also be logged out once the route file has been generated. If the user-defined route crosses a cell in the mesh that is
+considered inaccessible to the vessel then a warning will be displayed and no route will be saved.
+
+^^^^^^^^
+Plotting
+^^^^^^^^
+Meshes produced at any stage in the route planning process can be visualised using the GeoPlot 
+library found at the relevant `GitHub page <https://github.com/antarctica/GeoPlot>`_. Meshes and routes can also be
+plotted in other GIS software such as QGIS by exporting the mesh to a common format such as .geojson or .tif using
+the export_mesh command described in the `MeshiPhi <https://github.com/antarctica/MeshiPhi>`_ docs.

docs/html/_sources/sections/Configuration/Configuration_overview.rst.txt

@@ -0,0 +1,25 @@
+######################################
+Configuration Overview
+######################################
+
+In this section we will outline the standard structure for a configuration file used in 
+all portions of the PolarRoute software package.
+
+Each stage of the route-planning process is configured by a separate configuration file. 
+The configuration files are written in JSON, and are passed to each stage of the 
+route-planning process as command-line arguments or through a Python script.
+
+Example configuration files are provided in the `config` directory.
+
+Descriptions of the configuration options for the Vessel Performance Modelling can 
+be found in the :ref:`Configuration - Vessel Performance Modeller` section of the 
+documentation.
+
+Descriptions of the configuration options for Route Planning can be found in the 
+:ref:`Configuration - Route Planning` section of the documentation.
+
+.. toctree::
+   :maxdepth: 1
+
+   ./Vessel_performance_config
+   ./Route_planning_config

docs/html/_sources/sections/Configuration/Route_planning_config.rst.txt

@@ -0,0 +1,43 @@
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Configuration - Route Planning
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+::
+
+   {
+     "Objective_Function": "traveltime",
+     "Path_Variables": [
+        "fuel",
+        "traveltime"
+     ],
+     "WayPoints": "./WayPoints_org.csv",
+     "Source_Waypoints": ["LongPathStart"],
+     "End_Waypoints": [],
+     "Vector Names": ["uC","vC"],
+     "Zero_Currents": false,
+     "Variable_Speed": true,
+     "Time_unit": "days",
+     "Early_Stopping_Criterion": true,
+     "Save_Dijkstra_Graphs": false,
+     "Smooth Path":{
+        "Max Iteration Number":1000,
+        "Minimum Difference": 1e-3
+     }
+   }
+
+above is a typical set of configuration parameters used for route planning where the variables are as follows:
+
+* **objective_function** *(string)* : Defining the objective function to minimise for the construction of the mesh based Dijkstra routes. This variable can either be defined as 'traveltime' or 'fuel' .
+* **path_variables** *(list<(string)>)* : A list of strings of the route variables to return in the output geojson. 
+* **waypoints_path** *(string)* : A filepath to a CSV containing the user defined waypoints with columns including: 'Name','Lat',"Long"
+* **source_waypoints** *(list<(string)>)*: The source waypoints to define the routes from. The names in this list must be the same as names within the `waypoints_path` file. If left blank then routes will be determined from all waypoints.
+* **end_waypoints** *(list<(string)>)* : The end waypoints to define the routes to. The names in this list must be the same as names within the `waypoints_path` file. If left blank then routes will be determined to all waypoints.
+* **vector_names** *(list<(string)>)* : The definition of the horizontal and vertical components of the vector acting on the ship within each CellBox. These names must be within the 'cellboxes'.
+* **zero_currents** *(bool)* : For development use only. Removes the effect of currents acting on the ship, setting all current vectors to zero.
+* **Variable_Speed** *(bool)*  : For development use only. Removes the effect of variable speed acting on the ship, ship speed set to max speed defined by 'Vessel':{'Speed':...}.
+* **time_unit** *(string)* : The time unit to output the route path information. Currently only takes 'days', but will support 'hrs' in future releases.
+* **early_stopping_criterion** *(bool)* : For development use only. Dijkstra early stopping criterion. For development use only if the full objective_function from each starting waypoint is required. Should be used in conjunction with `save_dijkstra_graphs`.
+* **save_dijkstra_graphs** *(bool)* : For development use only. Saves the full dijkstra graph representing the objective_function value across all mesh cells.
+* **Smooth Path**
+   * **max_iteration_number** *(int)* : For development use only. Maximum number of iterations in the path smoothing. For most paths convergence is met 100x earlier than this value. 
+   * **minimum_difference** *(float)* : For development use only. Minimum difference between two path smoothing iterations before convergence is triggered
+

docs/html/_sources/sections/Configuration/Vessel_performance_config.rst.txt

@@ -0,0 +1,36 @@
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Configuration - Vessel Performance Modeller
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Vessel configuration file provides all the necessary information about the vessel that will execute
+the routes such that performance parameters (e.g. speed or fuel consumption) can be calculated by the
+`VesselPerformanceModeller` class. A file of this structure is also used as a command line argument for
+the 'add_vehicle' entry point.
+
+::
+
+   {
+     "vessel_type": "SDA",
+     "max_speed": 26.5,
+     "unit": "km/hr",
+     "beam": 24.0,
+     "hull_type": "slender",
+     "force_limit": 96634.5,
+     "max_ice_conc": 80,
+     "min_depth": 10,
+     "max_wave": 3,
+     "excluded_zones": ["exclusion_zone"]
+   }
+
+Above are a typical set of configuration parameters used for a vessel where the variables are as follows:
+
+* **vessel_type** *(string)* : The specific vessel class to use for performance modelling.
+* **max_speed** *(float)* : The maximum speed of the vessel in open water.
+* **unit** *(string)* : The units of measurement for the speed of the vessel (currently only "km/hr" is supported).
+* **beam** *(float)* : The beam (width) of the ship in metres.
+* **hull_type** *(string)* : The hull profile of the ship (should be one of either "slender" or "blunt").
+* **force_limit** *(float)* : The maximum allowed resistance force, specified in Newtons.
+* **max_ice_conc** *(float)* : The maximum Sea Ice Concentration the vessel is able to travel through given as a percentage.
+* **min_depth** *(float)* : The minimum depth of water the vessel is able to travel through in metres.
+* **max_wave** *(float)* : The maximum significant wave height the vessel is able to travel through in metres.
+* **excluded_zones** *(float)* : A list of of strings that name different boolean properties of a cell. Any cell with a value of True for any of the entered keys will be marked as unnavigable.