diff --git a/docs/gallery.md b/docs/gallery.md new file mode 100644 index 0000000..d017574 --- /dev/null +++ b/docs/gallery.md @@ -0,0 +1,70 @@ +--- +hide: + - navigation +--- + +# Gallery + +This page shows a gallery of the capabilities of the HPC MultiBench tool. + +## Viewing run configurations + +
+ ![Viewing run configurations](./images/hpc-multibench-run-configurations.png){ loading=lazy } +
A screenshot of the TUI viewing a run configuration, including the instantiation of variables and the Slurm sbatch file to run.
+
+ +## Viewing aggregated metrics + +
+ ![Viewing aggregated metrics](./images/hpc-multibench-aggregated-metrics.png){ loading=lazy } +
A screenshot of the TUI viewing the metric results extracted from and aggregated across a set of runs defined in the YAML file.
+
+ +## Dispatching runs + +
+ ![Viewing aggregated metrics](./images/hpc-multibench-dispatch-runs.png){ loading=lazy } +
A screenshot of the TUI showing a modal dialog as it spawns Slurm jobs after the "Run Test Plan" button is pressed.
+
+ +## Line plots + +
+ ![Plotext line plots](./images/hpc-multibench-line-plotext.png){ loading=lazy } +
A screenshot of a a line plot of the metrics rendered entirely in the terminal.
+
+ +
+ ![Plotext line plots](./images/hpc-multibench-line-plotext-2.png){ loading=lazy } +
A screenshot of a a line plot of the metrics rendered entirely in the terminal.
+
+ +
+ ![Matplotlib line plots](./images/hpc-multibench-line-matplotlib.png){ loading=lazy } +
A screenshot of a Matplotlib window spawned by the TUI displaying a line plot including error bars of the metrics.
+
+ +## Bar plots + +
+ ![Plotext bar plots](./images/hpc-multibench-bar-plotext.png){ loading=lazy } +
A screenshot of a a bar plot of the metrics rendered entirely in the terminal.
+
+ +
+ ![Matplotlib bar plots](./images/hpc-multibench-bar-matplotlib.png){ loading=lazy } +
A screenshot of a Matplotlib window spawned by the TUI displaying a bar plot including error bars of the metrics.
+
+ +## Roofline plots + +
+ ![Plotext roofline plots](./images/hpc-multibench-roofline-plotext.png){ loading=lazy } +
A screenshot of a a roofline plot of the metrics rendered entirely in the terminal.
+
+ +
+ ![Matplotlib roofline plots](./images/hpc-multibench-roofline-matplotlib.png){ loading=lazy } +
A screenshot of a Matplotlib window spawned by the TUI displaying a roofline plot including error bars of the metrics.
+
diff --git a/docs/images/hpc-multibench-aggregated-metrics.png b/docs/images/hpc-multibench-aggregated-metrics.png new file mode 100644 index 0000000..612618d Binary files /dev/null and b/docs/images/hpc-multibench-aggregated-metrics.png differ diff --git a/docs/images/hpc-multibench-bar-matplotlib.png b/docs/images/hpc-multibench-bar-matplotlib.png new file mode 100644 index 0000000..60f605a Binary files /dev/null and b/docs/images/hpc-multibench-bar-matplotlib.png differ diff --git a/docs/images/hpc-multibench-bar-plotext.png b/docs/images/hpc-multibench-bar-plotext.png new file mode 100644 index 0000000..2dc8d2f Binary files /dev/null and b/docs/images/hpc-multibench-bar-plotext.png differ diff --git a/docs/images/hpc-multibench-dispatch-runs.png b/docs/images/hpc-multibench-dispatch-runs.png new file mode 100644 index 0000000..8ed4f39 Binary files /dev/null and b/docs/images/hpc-multibench-dispatch-runs.png differ diff --git a/docs/images/hpc-multibench-line-matplotlib.png b/docs/images/hpc-multibench-line-matplotlib.png new file mode 100644 index 0000000..d3d0b1b Binary files /dev/null and b/docs/images/hpc-multibench-line-matplotlib.png differ diff --git a/docs/images/hpc-multibench-line-plotext-2.png b/docs/images/hpc-multibench-line-plotext-2.png new file mode 100644 index 0000000..ea71999 Binary files /dev/null and b/docs/images/hpc-multibench-line-plotext-2.png differ diff --git a/docs/images/hpc-multibench-line-plotext.png b/docs/images/hpc-multibench-line-plotext.png new file mode 100644 index 0000000..9a45a71 Binary files /dev/null and b/docs/images/hpc-multibench-line-plotext.png differ diff --git a/docs/images/hpc-multibench-roofline-matplotlib.png b/docs/images/hpc-multibench-roofline-matplotlib.png new file mode 100644 index 0000000..1238e79 Binary files /dev/null and b/docs/images/hpc-multibench-roofline-matplotlib.png differ diff --git a/docs/images/hpc-multibench-roofline-plotext.png b/docs/images/hpc-multibench-roofline-plotext.png new file mode 100644 index 0000000..2d08b16 Binary files /dev/null and b/docs/images/hpc-multibench-roofline-plotext.png differ diff --git a/docs/images/hpc-multibench-run-configurations.png b/docs/images/hpc-multibench-run-configurations.png new file mode 100644 index 0000000..898e060 Binary files /dev/null and b/docs/images/hpc-multibench-run-configurations.png differ diff --git a/docs/index.md b/docs/index.md index 48d6327..5c27863 100644 --- a/docs/index.md +++ b/docs/index.md @@ -15,7 +15,8 @@ HPC batch compute jobs via Slurm from a convenient YAML format. - [x] Define experiments from a convenient YAML file - [x] Support for zero effort re-runs of experiments, with aggregation for uncertainty calculations and error bars -- [x] Simple metric extraction and graph plotting from run results +- [x] Simple metric extraction and graph plotting from run results, including + line, bar and roofline plots - [x] Rendered entirely in the terminal -- including graph plotting capabilities; no need to set up X-forwarding! diff --git a/docs/manual.md b/docs/manual.md index 7490071..4d995f1 100644 --- a/docs/manual.md +++ b/docs/manual.md @@ -5,6 +5,11 @@ hide: # Manual +When the `hpc-multibench` tool and its subcommands are invoked with the `-h` or +`--help` flags, the following help pages are displayed. + +## Top-level help page + ``` usage: __main__.py [-h] -y YAML_PATH [-o OUTPUTS_DIRECTORY] {record,interactive,report} ... @@ -24,7 +29,7 @@ options: the path to the configuration YAML file ``` -## `record` subcommand +## `record` subcommand help page ``` usage: __main__.py record [-h] [-d] [-w] [-nc] @@ -36,7 +41,7 @@ options: -nc, --no-clobber don't delete any previous run results of the test benches ``` -## `report` subcommand +## `report` subcommand help page ``` usage: __main__.py report [-h] @@ -45,7 +50,7 @@ options: -h, --help show this help message and exit ``` -## `interactive` subcommand +## `interactive` subcommand help page ``` usage: __main__.py interactive [-h] [-nc] diff --git a/docs/quickstart.md b/docs/quickstart.md index 3f15ac2..cb29ec6 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -14,7 +14,7 @@ To install the tool, clone and navigate to the repository, then use poetry to create a virtual environment as follows: ```bash -git clone https://github.com/EdmundGoodman/hpc-multibench +git clone --recurse-submodules -j8 https://github.com/EdmundGoodman/hpc-multibench cd hpc-multibench poetry install --without docs,test,dev ``` diff --git a/docs/yaml_schema.md b/docs/yaml_schema.md new file mode 100644 index 0000000..eaecfca --- /dev/null +++ b/docs/yaml_schema.md @@ -0,0 +1,20 @@ +--- +hide: + - navigation +--- + +# YAML Schema + +## Run Configurations + +## Test Benches + +### Reruns + +### Matrix + +### Analysis + +#### Metrics + +#### Plotting diff --git a/mkdocs.yml b/mkdocs.yml index 3fd8df4..3f42393 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -16,12 +16,14 @@ nav: - Home: index.md - Quick start: quickstart.md - Manual: manual.md + - YAML schema: yaml_schema.md - Reference: - Main: reference/main.md - YAML model: reference/yaml_model.md - Test bench: reference/test_bench.md - Run configuration: reference/run_configuration.md - Roofline model: reference/roofline_model.md + - Gallery: gallery.md - Contributing: contributing.md theme: @@ -57,7 +59,9 @@ markdown_extensions: # Inbuilt extensions # https://python-markdown.github.io/extensions/ - admonition + - attr_list - footnotes + - md_in_html - meta - sane_lists - smarty