Repository: calliope-project/calliope (language: python)

Issue:
Proposed fixes / consistency changes for documentation
### Description

Follow up after a discussion with @sjpfenninger on 18.07., regarding some findings after combing through the current documentation, in no particular order (just numbered to make references in discussion easier):

1. `lookup_cluster_first_time` occurs in the base math; should that be part of the _Inter-cluster storage math_? [[link](https://calliope.readthedocs.io/en/latest/math/base/#balance_supply_with_storage)]
2. Missing links between entries:
	- `flow_cap` [[link](https://calliope.readthedocs.io/en/latest/math/base/#flow_cap)] makes use of, e.g., `flow_cap_min`, but the latter does not show that in it's _Used in_ section [[link](https://calliope.readthedocs.io/en/latest/math/base/#flow_cap_min)]
    - other parameters may be missing too, I assume these relations are built automatically, so probably just a single fix necessary
3. Adding "backlinks" between entries: [`area_use_max`](https://calliope.readthedocs.io/en/latest/math/base/#area_use_max) is used in [`area_use`](https://calliope.readthedocs.io/en/latest/math/base/#area_use), which is easy to follow. The latter makes use of [`source_unit`](https://calliope.readthedocs.io/en/latest/math/base/#source_unit), which may be hard to see on a first look, and further is then "hard" to follow up on. I assume the _"used in"_ section is built automatically, could the same approach also be used to build a _"makes use of"_  section? That would
    - show all used parameters, etc. immediately in a single list, and
    - make it easy to traverse the documentation by just hopping along the "dependency graph".
4. `balance_storage` checks for `where: (include_storage=true or base_tech=storage) ...`, whereas others check for `where: storage ...` instead; it seems to me those should be equivalent, because `storage` only exists with exactly the first condition [[link](https://calliope.readthedocs.io/en/latest/math/base/#storage)] - if that is true this could be unified for consistency, if not, the difference in behavior could be documented
5. `flow_cap_min` [[link](https://calliope.readthedocs.io/en/latest/math/base/#flow_cap_min)] contains a note stating _"this will force `flow_cap` to a minimum value unless `cap_method` is set to `integer`"_, which seems to not relate to the definition of `flow_cap` in a setting where `cap_method == LP` (and maybe more to `flow_cap_per_unit`, etc.).
6. Defaults, like for `cyclic_storage`, are hard to find: The [docs](https://calliope.readthedocs.io/en/latest/math/base/#cyclic_storage) do not mention this, but it can be checked, or found in the [schema description](https://calliope.readthedocs.io/en/latest/reference/model_schema/). Feels like the [base math](https://calliope.readthedocs.io/en/latest/math/base/) section should (?) contain all these.
7. Is there a way to alphabetically sort the entries in the right side-bar of the [base math](https://calliope.readthedocs.io/en/latest/math/base/) section? That would make it easier to find specific entries.

### Related links

Links are included in the description, a few things that I could guess how to fix are in #644.

### Version

latest (4fc6b84fe3f17d6533765c5543192e773deb05a9)

### Proposed change

_No response_


Discussion / hints:

Fix patch:
diff --git a/AUTHORS b/AUTHORS
index 70c3870b..7b1de98f 100644
--- a/AUTHORS
+++ b/AUTHORS
@@ -13,3 +13,4 @@ Francesco Lombardi, Politecnico di Milano <francesco.lombardi@polimi.it>
 Adriaan Hilbers, Imperial College London <a.hilbers17@imperial.ac.uk>
 Jann Launer, TU Delft <j.a.c.launer@tudelft.nl>
 Ivan Ruiz Manuel, TU Delft <i.ruizmanuel@tudelft.nl>
+Stefan Strömer, AIT Austrian Institute of Technology GmbH and TU Delft <stefan.stroemer@gmail.com>
diff --git a/src/calliope/config/model_data_checks.yaml b/src/calliope/config/model_data_checks.yaml
index 051ebed6..d8491743 100644
--- a/src/calliope/config/model_data_checks.yaml
+++ b/src/calliope/config/model_data_checks.yaml
@@ -26,8 +26,8 @@ fail:
   - where: carrier_export and not any(carrier_out, over=nodes)
     message: "Export carriers must be one of the technology outflow carriers."
 
-  - where: storage_initial>1
-    message: "storage_initial is a fraction; values larger than 1 are not allowed."
+  - where: storage_initial<0 OR storage_initial>1
+    message: "storage_initial is a fraction, requiring values within the interval [0, 1]."
 
   - where: integer_dispatch=True AND NOT cap_method=integer
     message: Cannot use the integer `integer_dispatch` unless the technology is using an integer unit capacities (`cap_method=integer`).
diff --git a/src/calliope/config/model_def_schema.yaml b/src/calliope/config/model_def_schema.yaml
index b9fd2ab9..62288a32 100644
--- a/src/calliope/config/model_def_schema.yaml
+++ b/src/calliope/config/model_def_schema.yaml
@@ -675,7 +675,7 @@ properties:
             x-type: str
             title: Sink unit
             description: >-
-              Sets the unit of `Sink` to either `absolute` x-unit: energy), `per_area` x-unit: energy/area), or `per_cap` x-unit: energy/power).
+              Sets the unit of `Sink` to either `absolute` (unit: `energy`), `per_area` (unit: `energy/area`), or `per_cap` (unit: `energy/power`).
               `per_area` uses the `area_use` decision variable to scale the sink while `per_cap` uses the `flow_cap` decision variable.
             enum: [absolute, per_area, per_cap]
 
@@ -687,7 +687,7 @@ properties:
             title: Minimum bound on sink.
             description: >-
               Minimum sink use to remove a carrier from the system (e.g., electricity demand, transport distance).
-              Unit dictated by `source_unit`.
+              Unit dictated by `sink_unit`.
 
           sink_use_max:
             $ref: "#/$defs/TechParamNullNumber"
@@ -697,7 +697,7 @@ properties:
             title: Maximum bound on sink.
             description: >-
               Maximum sink use to remove a carrier from the system (e.g., electricity demand, transport distance).
-              Unit dictated by `source_unit`.
+              Unit dictated by `sink_unit`.
 
           sink_use_equals:
             $ref: "#/$defs/TechParamNullNumber"
@@ -707,7 +707,7 @@ properties:
             title: Required sink use.
             description: >-
               Required amount of carrier removal from the system (e.g., electricity demand, transport distance).
-              Unit dictated by `source_unit`.
+              Unit dictated by `sink_unit`.
 
           source_unit:
             type: string
@@ -716,7 +716,7 @@ properties:
             x-type: str
             title: Source unit
             description: >-
-              Sets the unit of `Source` to either `absolute` (e.g. kWh), `per_area` (e.g. kWh/m2), or `per_cap` (e.g. kWh/kW).
+              Sets the unit of `Source` to either `absolute` (unit: `energy`), `per_area` (unit: `energy/area`), or `per_cap` (unit: `energy/power`).
               `per_area` uses the `area_use` decision variable to scale the source while `per_cap` uses the `flow_cap` decision variable.
             enum: [absolute, per_area, per_cap]
 


Test patch:
diff --git a/tests/test_backend_pyomo.py b/tests/test_backend_pyomo.py
index 61bf37f6..10247f54 100755
--- a/tests/test_backend_pyomo.py
+++ b/tests/test_backend_pyomo.py
@@ -1605,7 +1605,9 @@ def test_storage_initial_fractional_value(self):
 
         with pytest.raises(exceptions.ModelError) as error:
             m.build()
-        assert check_error_or_warning(error, "values larger than 1 are not allowed")
+        assert check_error_or_warning(
+            error, "requiring values within the interval [0, 1]"
+        )
 
 
 class TestNewBackend: