Update model documentation and CHANGELOG

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ### User-facing changes
 
+|changed| to ensure the model configuration always remains in sync with the results, `kwargs` in `model.build()` and `model.solve()` now directly affect `model.config`
+
 |changed| `template:` can now be used anywhere within YAML definition files, not just in the `nodes`, `techs` and `data_tables` sections.
 
 |changed| "An overview of the Calliope terminology" information admonition to remove self-references and improve understandability.
@@ -33,6 +35,8 @@ This change has occurred to avoid confusion between data "sources" and model ene
 
 ### Internal changes
 
+|changed| Model configuration now uses `pydantic`.
+
 |changed| Model definition reading is now defined in a single place (preprocess/model_definition.py).
 
 |changed| Moved YAML reading/importing functionality out of `AttrDict`. It is now part of our `io` functionality.

docs/creating/config.md

@@ -42,7 +42,7 @@ To test your model pipeline, `config.init.time_subset` is a good way to limit yo
     See our [time adjustment page](../advanced/time.md) for more details.
 
 !!! info "See also"
-    The full set of available configuration options is documented in the [configuration schema][model-configuration-schema].
+    The full set of available configuration options is documented in the [configuration schema](../reference/config_schema.md).
     This provides you with a description of each configuration option and the default which will be used if you do not provide a value.
 
 ## Deep-dive into some key configuration options
@@ -83,7 +83,7 @@ In `plan` mode, capacities are determined by the model, whereas in `operate` mod
 In `spores` mode, the model is first run in `plan` mode, then run `N` number of times to find alternative system configurations with similar monetary cost, but maximally different choice of technology capacity and location (node).
 
 In most cases, you will want to use the `plan` mode.
-In fact, you can use a set of results from using `plan` model to initialise both the `operate` (`config.build.operate_use_cap_results`) and `spores` modes.
+In fact, you can use a set of results from using `plan` model to initialise both the `operate` (`config.build.operate.use_cap_results`) and `spores` modes.
 
 ### `config.solve.solver`
 

docs/creating/parameters.md

@@ -52,7 +52,7 @@ Which will add the new dimension `my_new_dim` to your model: `model.inputs.my_ne
 `foreach: [my_new_dim]`.
 
 !!! warning
-    The `parameter` section should not be used for large datasets (e.g., indexing over the time dimension) as it will have a high memory overhead on loading the data.
+    The `parameter` section should not be used for large datasets (e.g., indexing over the time dimension) as it will have a high memory overhead when loading the data.
 
 ## Broadcasting data along indexed dimensions
 

docs/creating/scenarios.md

@@ -37,33 +37,6 @@ Scenarios consist of a name and a list of override names which together form tha
 Scenarios and overrides can be used to generate scripts that run a single Calliope model many times, either sequentially, or in parallel on a high-performance cluster
 (see the section on [generating scripts to repeatedly run variations of a model](../advanced/scripts.md)).
 
-## Importing other YAML files in overrides
-
-When using overrides, it is possible to have [`import` statements](yaml.md#relative-file-imports) for more flexibility.
-This can be useful if many overrides are defined which share large parts of model configuration, such as different levels of interconnection between model zones
-The following example illustrates this:
-
-```yaml
-overrides:
-  some_override:
-    techs:
-      some_tech.constraints.flow_cap_max: 10
-    import: [additional_definitions.yaml]
-```
-
-`additional_definitions.yaml`:
-
-```yaml
-techs:
-  some_other_tech.constraints.flow_out_eff: 0.1
-```
-
-This is equivalent to the following override:
-
-```yaml
-overrides:
-  some_override:
-    techs:
-      some_tech.constraints.flow_cap_max: 10
-      some_other_tech.constraints.flow_out_eff: 0.1
-```
+???+ warning
+    Overrides are executed _after_ `imports:` but _before_ `templates:`.
+    This means it is possible to override template values, but not the files imported in your model definition.

docs/migrating.md

@@ -340,9 +340,9 @@ Along with [changing the YAML hierarchy of model configuration](#model-and-run-
 
 * `model.subset_time` → `config.init.time_subset`
 * `model.time: {function: resample, function_options: {'resolution': '6H'}}` → `config.init.time_resample`
-* `run.operation.window` → `config.build.operate_window`
-* `run.operation.horizon` → `config.build.operate_horizon`
-* `run.operation.use_cap_results` → `config.build.operate_use_cap_results`
+* `run.operation.window` → `config.build.operate.window`
+* `run.operation.horizon` → `config.build.operate.horizon`
+* `run.operation.use_cap_results` → `config.build.operate.use_cap_results`
 
 We have also moved some _data_ out of the configuration and into the [top-level `parameters` section](creating/parameters.md):
 
@@ -516,8 +516,8 @@ Therefore, `24H` is equivalent to `24` in v0.6 if you are using hourly resolutio
           init:
             time_resample: 6H
           build:
-            operate_window: 12H
-            operate_horizon: 24H
+            operate.window: 12H
+            operate.horizon: 24H
         ```
 
 !!! warning

docs/running.md

@@ -25,7 +25,7 @@ The `calliope run` command takes the following options:
 * `--scenario={scenario}` and `--override_dict={yaml_string}`: Specify a scenario, or one or several overrides, to apply to the model, or apply specific overrides from a YAML string (see below for more information).
 * `--help`: Show all available options.
 
-Multiple options can be specified, for example, saving NetCDF, CSV, and HTML plots simultaneously.
+Multiple options can be specified, for example, saving NetCDF and CSV simultaneously.
 
 ```shell
 $ calliope run testmodel/model.yaml --save_netcdf=results.nc --save_csv=outputs

mkdocs.yml

@@ -156,7 +156,7 @@ nav:
       - reference/api/attrdict.md
       - reference/api/exceptions.md
       - reference/api/logging.md
-    - reference/config_schema.md
+    - Model configuration schema: reference/config_schema.md
     - reference/data_table_schema.md
     - reference/model_schema.md
     - reference/math_schema.md