Documentation improvements

docs/user_guide.md

@@ -15,6 +15,7 @@ muse2 example list
 It should print something like the following:
 
 ```sh
+circularity
 missing_commodity
 muse1_default
 simple
@@ -62,9 +63,18 @@ muse2 example extract simple new_model
 
 This will create a new subdirectory called `new_model` in the current folder.
 
+### Validating this model
+
+Before running a model, you can check that its input files can be read and that the model is
+internally consistent with:
+
+```sh
+muse2 validate new_model
+```
+
 ### Running this model
 
-First, let's run this model so you can see the output for a working model. You can do this by
+Next, let's run this model so you can see the output for a working model. You can do this by
 running:
 
 ```sh
@@ -77,7 +87,7 @@ the simulation (which should finish very quickly).
 The first few lines should look something like:
 
 ```txt
-[12:24:20 INFO muse2::cli] Starting MUSE2 v2.1.0
+[12:24:20 INFO muse2::cli] Starting MUSE2 vX.Y.Z
 [12:24:20 INFO muse2::cli] Loaded model from new_model/
 [12:24:20 INFO muse2::cli] Output folder: muse2_results/new_model
 ...
@@ -106,7 +116,7 @@ have a question, feel free to [open an issue].
 
 ## Visualising commodity graphs
 
-To visualise the structure of your model, you can use the [the `muse2 save-graphs` command] to
+To visualise the structure of your model, you can use the [`muse2 save-graphs` command] to
 create graphs of commodity/process relationships.
 This command will output a graph for each region/year in the simulation, where nodes are commodities
 and edges are processes.
@@ -115,7 +125,7 @@ with [Graphviz online].
 Dashed lines are used to indicate flows for non-primary outputs of a process (as defined in the
 `processes.csv` input file).
 
-[the `muse2 save-graphs` command]: command_line_help.md#muse2-save-graphs
+[`muse2 save-graphs` command]: command_line_help.md#muse2-save-graphs
 [DOT format]: https://graphviz.org/doc/info/lang.html
 [Graphviz]: https://graphviz.org/
 [Graphviz online]: https://dreampuf.github.io/GraphvizOnline
@@ -128,17 +138,18 @@ You can configure the behaviour of MUSE2 with a `settings.toml` file. To edit th
 muse2 settings edit
 ```
 
-There are also some more commands for working with the settings file; for details, run: `muse2
-settings help`.
+There are also some more commands for working with the settings file. For details, run
+`muse2 settings help` or see the [`muse2 settings` command documentation].
 
 For information about the available settings, see [the documentation for the `settings.toml`
 file][settings.toml-docs].
 
 [settings.toml-docs]: file_formats/program_settings.md
+[`muse2 settings` command documentation]: command_line_help.md#muse2-settings
 
 ## Setting the log level
 
-MUSE uses the [`fern`] crate for logging. The default log level is `info`, though this can be
+MUSE2 uses the [`fern`] crate for logging. The default log level is `info`, though this can be
 configured either via the `log_level` option in `settings.toml` or by setting the
 `MUSE2_LOG_LEVEL` environment variable. (If both are used, the environment variable takes
 precedence.)
@@ -152,7 +163,7 @@ The possible options are:
 - `trace`
 - `off`
 
-By default, MUSE will colourise the log output if this is available (i.e. it is outputting to a
+By default, MUSE2 will colourise the log output if this is available (i.e. it is outputting to a
 terminal rather than a file).
 
 For more information, please consult [the `fern` documentation].

examples/circularity/README.txt

@@ -2,7 +2,3 @@ This model extends "two_outputs" to showcase circular commodity flows, adding a
 turns electricity into hydrogen and back again.
 
 Note: this model is currently experimental and only included for development purposes.
-For now, this uses the "shadow" pricing strategy for ELCTRI and H2YPRD, as the default
-"full_average" strategy is not supported for commodities involved in circularities.
-This also uses a slightly wider `capacity_margin` compared to the default value, as this is
-required for this model to find a solution.

examples/circularity/model.toml

@@ -1,2 +1 @@
 milestone_years = [2020, 2030, 2040]
-capacity_margin = 0.3

schemas/settings.yaml

@@ -7,7 +7,8 @@ description: |
   All settings are optional. If the `settings.toml` file does not exist, the default settings will
   be used.
 
-  The `settings.toml` file must be in the current working directory.
+  The `settings.toml` file is read from MUSE2's platform-specific configuration directory, in a
+  `muse2` subdirectory. Use `muse2 settings path` to find the exact location on your system.
 type: object
 properties:
   log_level:

tests/data/circularity/asset_capacities.csv

@@ -35,12 +35,12 @@ milestone_year,asset_id,capacity,num_units
 2040,20,165.3505808753475,27
 2040,21,942.563016229748,28
 2040,22,2198.390989008045,39
-2040,23,34.19605824723177,15
+2040,23,38.755532680196005,17
 2040,24,5.471369319196239,6
-2040,25,9.118948865327066,9
-2040,26,132.08198143321187,15
-2040,27,453.28514602874316,33
+2040,25,8.10573232473517,8
+2040,26,153.84953248060512,21
+2040,27,358.63594983962076,37
 2040,28,972.485651665613,26
 2040,29,2349.6972514094086,33
-2040,30,475.9494033301804,33
+2040,30,376.5677473316019,37
 2040,31,2627.9227668603858,37