Release/v0.6.0

CMakeLists.txt

@@ -1,19 +1,22 @@
 cmake_minimum_required(VERSION 3.13)
 
 project(Warthog
-	VERSION 0.5.0
+	VERSION 0.6.0
 	LANGUAGES CXX C)
 
 set_property(GLOBAL PROPERTY WARTHOG_warthog-core ON)
 
-set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD 23)
 set(CMAKE_CXX_STANDARD_REQUIRED TRUE)
 
+option(WARTHOG_POSTHOC "Compile trace support generation for posthoc" OFF)
 option(WARTHOG_INT128 "Enable support for __int128 on gcc and clang" OFF)
 option(WARTHOG_BMI "Enable support cpu BMI for WARTHOG_INTRIN_HAS(BMI)" OFF)
 option(WARTHOG_BMI2 "Enable support cpu BMI2 for WARTHOG_INTRIN_HAS(BMI2), use for Zen 3+" OFF)
 option(WARTHOG_INTRIN_ALL "Enable march=native and support x86 intrinsics if able (based on system), supersedes all manual instruction sets" OFF)
 
+find_package(Threads REQUIRED)
+
 include(cmake/warthog.cmake)
 
 add_library(warthog_compile INTERFACE)
@@ -30,7 +33,7 @@ target_include_directories(warthog_core PUBLIC
   $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/include>
   $<INSTALL_INTERFACE:include>
 )
-target_link_libraries(warthog_core PUBLIC warthog::compile)
+target_link_libraries(warthog_core PUBLIC warthog::compile Threads::Threads)
 include(cmake/headers.cmake)
 
 add_executable(warthog_app)
@@ -47,7 +50,7 @@ add_subdirectory(apps)
 #
 
 warthog_top_level()
-if(_is_top)
+if(${_warthog_is_top})
 	option(BUILD_TESTING "Building testing suite" OFF)
 	include(CTest)
 	include(FetchContent)

CONTRIB.md

@@ -0,0 +1,18 @@
+Contributors to the Warthog Pathfinding Library
+===============================================
+
+Maintainers
+-----------
+
+Daniel Harabor @dharabor <Daniel.Harabor@monash.edu>
+Ryan Hechenberger @heavenfall <Ryan.Hechenberger@monash.edu>
+
+Contributors
+------------
+
+Arthur Maheo
+Shizhe Zhao
+Saman Ahmadi
+Mark Carlson <Mark.Carlson@monash.edu>
+Thomas Nobes <thomas.nobes@monash.edu>
+Massimo Bono

README.md

@@ -8,22 +8,134 @@ Github houses the newer version, the legacy version is available at: https://bit
 
 Warthog is split in several repos, all official repos will be located within [Shortest Path Lab](https://github.com/ShortestPathLab).
 
-### Core
-
 Repo [warthog-core](https://github.com/ShortestPathLab/warthog-core) houses the core library of the project.
-Any warthog library will require this dependency.
-It contains domain, search, heuristic, scenario loaders and other core utilities.
+Any project which employs warthog features will require this dependency.
 See `/apps` for pre-setup application that can run standard scenarios.
 
-### JPS
+Current downstream SPL projects which rely on warthog-core:
+ - [warthog-jps](https://github.com/ShortestPathLab/warthog-jps)
+
+# The Warthog Application
+
+## Compile
+
+Invoke CMake build to compile.
+
+Example release build commands, from project root:
+
+```
+cmake -B build -S . -DCMAKE_BUILD_TYPE=Release
+cmake --build build -j
+```
+
+To enable posthoc trace generation, it must be enabled through CMake (adds small overhead).
+Example setting (and then rebuild):
+
+```
+cmake build -DWARTHOG_POSTHOC=On
+cmake --build build -j
+```
+
+Many parameters are configurable (most in built library not application).
+They all prefixed `WARTHOTG_`.
+
+## Run
+
+Run application `build/warthog` from build commands.
+See overview of commands with `build/warthog --help`.
+
+## Examples
+
+    cmake -B build -S . -DCMAKE_BUILD_TYPE=Release -DWARTHOG_POSTHOC=On && cmake --build build -j
+    ./build/warthog --alg dijkstra --scen examples/arena2.map.scen --checkopt
+    ./build/warthog --alg astar --scen examples/NovaStation_Berlin.scen --checkopt
+    ./build/warthog --alg astar4c --scen examples/NovaStation_Berlin.scen --cost 4c --checkopt
+    ./build/warthog --alg astar --scen examples/NovaStation_Berlin.scen --filter=201 --dump-map=test.map --trace=test.trace.yaml
+    ./build/warthog --alg astar --scen examples/NovaStation_Berlin.scen --snapshot=40 --filter=1
+    ./build/warthog --alg astar_wgm --scen examples/arena2.map.scen --grid-weight examples/grid.weight --cost=-
+
+### Command line options overview
 
-Repo [warthog-jps](https://github.com/ShortestPathLab/warthog-jps) houses jps implementation.
-Requires `warthog-core` as a dependency.
+`--help`
+Set this parameter to print all available program options.
 
-# Using warthog
+`--alg [name]`
+Used to specify a named search algorithm.
+Current supported: astar, astar_wgm, astar4c, dijkstra
+
+`--scen [file]`
+Used to specify a scenario file for experiments.
+Support for v1 & v2 scenario format, see benchmark in resources.
+
+`--map [file]`
+Overrides map filename used in scenario.
+
+`--cost [type]`
+Scenario v2 files holds several costs for instances, specify these costs here.
+If given `-`, then remove all costs (works for both v1 and v2).
+Otherwise requires v2 scenario and cost to exist or error.
+If `--cost` is not supplied, uses the first cost (if present) for v2.
+
+`--grid-weight [file]`
+For use with weighted terrain algorithm (e.g. astar_wgm).
+Provide grid weights, provided `examples/grid.weight` for scenario grid
+weights and `examples/terrain.weight` for MovingAI terrain maps, as
+used in the jpsw paper.
+
+`--checkopt`
+Set this parameter to compare the length of each computed path against an
+optimal length value specified by the scenario file at hand.
+
+`--verbose`
+Set this parameter to print debugging information (must be in debug config).
+
+`--snapshot [id]`
+Default value `-1`, results in running all snapshots.
+Otherwise, only run instances from snapshot `id`.
+If snapshot does not exist, the program will error.
+Specifying a specific snapshot will make the scenario be considered as static.
+A static scenario is always static iff there is only a single snapshot,
+important as offline algorithms will not run on a dynamic scenario.
+
+`--filter [num]`
+Default value `-1`, run all instances.
+Otherwise run instance `num` from scenario, as the kth instances (zero-indexed).
+If used with `--snapshot`, then run instance number `num` in specified snapshot.
+e.g. `--snapshot=10 --filter=0` will run the first instance on snapshot 10.
+If instance does not exist, then program errors.
+If specific instance is specified, then scenario will be considered as static.
+
+`--trace [.trace.yaml file]`
+Requires `WARTHOG_POSTHOC=On`.
+Generate a trace file output for use with posthoc (see resources).
+The trace is only for first instance, use with `--filter` to choose instance.
+
+`--dump-map [file]`
+Dump the gridmap at the beginning of search to `file`.
+Use with `--filter` or `--snapshot` to choose the map to dump.
+Useful in dynamic scenario to see current state of grid, especially if used with `--trace`.
+
+### Advanced Compile Features
+
+Library includes support for x86 intrinsics instruction support, which may
+improve performance of some algorithms.
+To enable, compiler must have these instructions enabled, and they must be
+enabled in CMake, either `WARTHOG_INTRIN_ALL` for all or a specific
+supported instruction set, more to be added when required.
+
+Even if BMI2 may be supported by a CPU, the instructions may be implemented
+by microcode which may reduce performance instead; e.g. Zen 3 arch has some
+microcoded instructions, while Zen 4 supports full BMI2.
+User must determine manually if enabling is applicable.
+Example below (works with gcc or clang, other systems may differ or not support):
+
+    cmake build -DWARTHOG_INTRIN_ALL=On -DCMAKE_CXX_FLAGS="-march=native"
+    cmake --build build -j
+
+# The Warthog Library
 
 It is recommended to use warthog not as a fork, but included in an external repo.
-This setup support FetchContent, git submodule and git subtree.
+This setup support either FetchContent, git submodule or git subtree.
 
 ## CMake
 
@@ -32,7 +144,7 @@ Setup a basic project using the following the commands:
     git init
     git remote add warthog-core https://github.com/ShortestPathLab/warthog-core.git
     git fetch warthog-core
-    git checkout warthog-core/main cmake/warthog.cmake
+    git checkout warthog-core/main -- cmake/warthog.cmake
 
 Example `CMakeLists.txt`:
 
@@ -43,7 +155,7 @@ project(App
 	VERSION 0.0.1
 	LANGUAGES CXX C)
 
-set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD 23)
 set(CMAKE_CXX_STANDARD_REQUIRED TRUE)
 
 # warthog modules
@@ -56,6 +168,8 @@ add_executable(app main.cpp)
 target_link_libraries(app PUBLIC warthog::core)
 ```
 
+By default, this will fallback to FetchContent if modules are not present in `extern/`.
+
 ## Submodule
 
 Commands for adding a module as a submodules for each repo are found below:
@@ -72,16 +186,21 @@ To update the version of warthog, for warthog module `$module`:
     git add $module
 
 This will update the submodule to the checkout commit.
-Initialise or update the submodule on other clones with
-the following commands:
+Initialise or update the submodule on other clones with the following commands:
 
     git submodule init # after clone
     git submodule update # after pull
 
+Commit/tag should be added to the `warthog_module_declare` that match the
+submodule otherwise users who do not checkout the submodules will have
+a different version of that module.
+
 ## Subtree
 
 Subtree will make the module a part of your repo, allowing
-for local editing without forking.
+for local editing of modules.
+Modules setup with way will never have FetchContent called, so
+`warthog_module_declare` is not required.
 
 The setup for each module:
 
@@ -101,7 +220,7 @@ Calling `warthog_submodule(warthog-core)` will then add `warthog-core` to your C
 2. `FetchContent_Declare` then `FetchContent_MakeAvailable(warthog-core)` otherwise
 3. Error if cannot find `warthog-core` content
 
-The `warthog_module` call only adds a module once, the following calls will be ignored.
+The `warthog_module` call only adds a module once, following calls will be ignored.
 The submodule/subtree version only works if called in the top level project by default;
 if this method is preferred, then it should be added to the top level `/extern/`, can be overridden
 with code `warthog_module(warthog-core ON)`.
@@ -116,7 +235,8 @@ FetchContent_Declare(warthog-core
 	GIT_REPOSITORY https://github.com/ShortestPathLab/warthog-core.git
 	GIT_TAG [main|branch|tag|commit])
 ```
-This will declare what warthog-core version to fetched.
+
+This will declare the warthog-core version to fetched.
 The `warthog_module_declare` version makes it simple, although it only supports known warthog libraries.
 The optional second parameter sets the version to pull, by default is `main` branch.
 This system only support warthog 0.5 or greater.
@@ -126,3 +246,4 @@ This system only support warthog 0.5 or greater.
 - [Moving AI Lab](https://movingai.com/): pathfinding benchmark and tools
 - [Posthoc](https://posthoc-app.pathfinding.ai/): visualiser and debugger for pathfinding
 - [Pathfinding Benchmarks](https://benchmarks.pathfinding.ai/): git repo for benchmarks
+- [Dynamic Benchmarks](https://github.com/gppc-dev/benchmarks/): git repo for v2 scenarios

apps/cfg.cpp

@@ -39,7 +39,7 @@ warthog::util::cfg::parse_args(
 std::string
 warthog::util::cfg::get_param_value(std::string param_name)
 {
-	std::string ret("");
+	std::string ret;
 	std::map<std::string, std::vector<std::string>>::iterator it
 	    = params_.find(param_name);
 	if(it != params_.end())

apps/cfg.h

@@ -1,7 +1,7 @@
 #ifndef WARTHOG_APP_CFG_H
 #define WARTHOG_APP_CFG_H
 
-#include "getopt.h"
+#include <getopt.h>
 
 #include <cstdint>
 #include <iostream>