--- a/README.md	Sat May 20 14:33:25 2023 +0200
+++ b/README.md	Sun May 21 20:51:52 2023 +0200
@@ -28,22 +28,54 @@
 ```
 will run any file named `lazy_tensor_operations_test.jl` and all the files in the `Grids` folder.
 
+## Running benchmarks
+Benchmarks are defined in `benchmark/` and use the tools for benchmark suites in BenchmarkTools.jl. The format is compatible with PkgBenchmark.jl which helps with running the suite, comparing results and presenting the results in a readable way. There are custom functions included for running the benchmarks in this Mercurial repository.
+
+`benchmark/` contains a julia environment with the necessary packages for working with the benchmarks.
+
+To run the benchmarks, either use `make` run them manually from the REPL, as explained further below.
+
+Using `make` there are four targets for benchmarks
+```shell
+make benchmark                                      # Runs the suite for the current working directory
+make benchmarkrev REV=rev                           # Runs the suite at the specified revision
+make benchmarkcmp TARGET=target BASELINE=baseline   # Compares two revisions
+make cleanbenchmark                                 # Cleans up benchmark tunings and results
+```
+Here `rev`, `target` and `baseline` are any valid Mercurial revision specifiers. Note that `make benchmarkrev` and `make benchmarkcmp` will fail if you have pending changes in your repository.
+
+
+Alternatively, the benchmarks can be run from the REPL. To do this, first activate the environment in `benchmark/` then include the file `benchmark_utils.jl`. The suite can then be run using the function `main` in one of the following ways
+
+```julia
+main()                  # Runs the suite for the current working directory
+main(rev)               # Runs the suite at the specified revision
+main(target, baseline)  # Compares two revisions
+```
+
+Again, `rev`, `target` and `baseline` are any valid Mercurial revision specifiers. Note that `main(rev)` and `main(target, baseline)` will fail if you have pending changes in your repository.
+
+PkgBenchmark can also be used directly.
+
+```julia
+using PkgBenchmark
+import Sbplib
+r = benchmarkpkg(Sbplib)
+
+export_markdown(stdout, r)
+```
 
 ## Generating and using the documentation
 Generating the documentation can be done using either `make` or through activating the `docs` environment and including the script `docs/make.jl` at the REPL.
 
-Using `make` there are three targets
+Using `make` there are four targets for documentation
 ```shell
-make docs
-make localdocs
-make opendocs
-make help
-```
-The first variant generates files suitable for webserver deployment, i.e with `prettyurls=true`. The second generates files sutible for local viewing in a web browser, i.e `prettyurls=false`. To view the documentation locally simply open `docs/build/index.html` in your web browser. The documentation can be automatically built and opened using
-```shell
-make opendocs
+make docs          # generates files suitable for webserver deployment, i.e with `prettyurls=true`
+make localdocs     # generates files suitable for local viewing in a web browser, i.e `prettyurls=false`
+make opendocs      # build and view documentation locally
+make cleandocs     # cleans up generated files
 ```
 
-When including the `docs/make.jl` script `prettyurls` is set to `false` by default.
+Alternatively, to view the documentation locally simply open `docs/build/index.html` in your web browser. When including the `docs/make.jl` script `prettyurls` is set to `false` by default.
 
-Including `docs/make.jl` from the REPL may be preferable when repeatadely building the documentation since this avoids compilation latency.
+Including `docs/make.jl` from the REPL may be preferable when repeatedly building the documentation since this avoids compilation latency.