diff --git a/doc/user/advanced_features.rst b/doc/user/advanced_features.rst index c488b60be..4bf6b8e2a 100644 --- a/doc/user/advanced_features.rst +++ b/doc/user/advanced_features.rst @@ -180,7 +180,8 @@ As an example, if you wanted to generate 10 SPORES, all of which are within 10% spores_score_cost_class: spores_score # The cost class to optimise against when generating SPORES spores_slack_cost_group: systemwide_cost_max # The group constraint name in which the `cost_max` constraint is assigned, for use alongside the slack and cost-optimal cost parameters: - slack: 0.1 # The fraction above the cost-optimal cost to set the maximum cost during SPORES + slack: + data: 0.1 # The fraction above the cost-optimal cost to set the maximum cost during SPORES You will also need to manually set up some other parts of your model to deal with SPORES: diff --git a/doc/user/building.rst b/doc/user/building.rst index 623bcf35f..afdeebefd 100644 --- a/doc/user/building.rst +++ b/doc/user/building.rst @@ -105,7 +105,7 @@ None of the configuration options are _required_ as there is a default value for To test your model pipeline, `config.init.subset_time` is a good way to limit your model size by slicing the time dimension to a smaller range. `config.build.mode` -~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^ In the ``build`` section we have ``mode``. A model can run in ``plan``, ``operate``, or ``spores`` mode. @@ -113,7 +113,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. `config.solve.solver` -~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^ Possible options for solver include ``glpk``, ``gurobi``, ``cplex``, and ``cbc``. The interface to these solvers is done through the Pyomo library. Any `solver compatible with Pyomo `_ should work with Calliope. @@ -238,7 +238,7 @@ To use a single alternative cost class, disabling the consideration of the defau :ref:`config_reference_constraints`, :ref:`config_reference_costs`, :doc:`tutorials `, :doc:`built-in examples ` Allowing for unmet demand -------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^ For a model to find a feasible solution, supply must always be able to meet demand. To avoid the solver failing to find a solution, you can ensure feasibility: @@ -266,7 +266,7 @@ For parameters that vary in time, time series data can be added to a model in tw Reading in CSV files is possible from both the command-line tool as well running interactively with python (see :doc:`running` for details). However, passing dataframes as arguments in ``calliope.Model`` is possible only when running from a python session. Reading in CSV files --------------------- +^^^^^^^^^^^^^^^^^^^^ To read in CSV files, specify e.g., :yaml:`source: file=filename.csv` to pick the desired CSV file from within the configured timeseries data path (``model.timeseries_data_path``). By default, Calliope looks for a column in the CSV file with the same name as the location. It is also possible to specify a column to use when setting ``source`` per location, by giving the column name with a colon following the filename: :yaml:`source: file=filename.csv:column` @@ -301,7 +301,7 @@ For example, the first few lines of a CSV file, called ``pv_resource.csv`` givin 2005-01-01 06:00:00,90,458 Reading in timeseries from ``pandas`` dataframes ------------------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When running models from python scripts or shells, it is also possible to pass timeseries directly as ``pandas`` dataframes. This is done by specifying :yaml:`source: df=tskey` where ``tskey`` is the key in a dictionary containing the relevant dataframes. For example, if the same timeseries as above is to be passed, a dataframe called ``pv_resource`` may be in the python namespace: .. code-block:: python @@ -345,7 +345,6 @@ The time series index must be ISO 8601 compatible time stamps and can be a stand .. Note:: * If a parameter is not explicit in time and space, it can be specified as a single value in the model definition (or, using location-specific definitions, be made spatially explicit). This applies both to parameters that never vary through time (for example, cost of installed capacity) and for those that may be time-varying (for example, a technology's available resource). However, each model must contain at least one time series. - * Only the subset of parameters listed in `file_allowed` in the :ref:`model configuration ` can be loaded from file or dataframe in this way. It is advised not to update this default list unless you are developing the core code, since the model will likely behave unexpectedly. * You _cannot_ have a space around the ``=`` symbol when pointing to a timeseries file or dataframe key, i.e. :yaml:`source: file = filename.csv` is not valid. * If running from a command line interface (see :doc:`running`), timeseries must be read from CSV and cannot be passed from dataframes via ``df=...``. * It's possible to mix reading in from CSVs and dataframes, by setting some config values as ``file=...`` and some as ``df=...``. diff --git a/doc/user/config_defaults.rst b/doc/user/config_defaults.rst index 5809e1d11..97a223269 100644 --- a/doc/user/config_defaults.rst +++ b/doc/user/config_defaults.rst @@ -7,11 +7,29 @@ Defaults are automatically applied in constraints whenever there is no user inpu .. _config_reference_config: -Model configuration -------------------- +Model initialisation configuration +---------------------------------- .. csv-table:: - :file: includes/config.csv + :file: includes/config_init.csv + :header: Setting,Default,Comments + :widths: 10, 5, 15 + :stub-columns: 0 + +Optimisation problem build configuration +---------------------------------------- + +.. csv-table:: + :file: includes/config_build.csv + :header: Setting,Default,Comments + :widths: 10, 5, 15 + :stub-columns: 0 + +Optimisation problem solve configuration +---------------------------------------- + +.. csv-table:: + :file: includes/config_solve.csv :header: Setting,Default,Comments :widths: 10, 5, 15 :stub-columns: 0 diff --git a/doc/user/ref_formulation.rst b/doc/user/ref_formulation.rst index 3517f430f..0c767f6ca 100644 --- a/doc/user/ref_formulation.rst +++ b/doc/user/ref_formulation.rst @@ -10,7 +10,7 @@ All built-in Calliope math can be found in the calliope `math directory ` is loaded from file. If you want to overwrite the base math with other built-in math, you can do so by referring to the file by its name (without the file extension) in :yaml:`model.custom_math`, e.g. :yaml:`model.custom_math: [storage_inter_cluster]`. -When solving the model in a :ref:`run mode ` other than `plan`, some built-in custom math will be applied automatically from a file of the same name (`spores` mode custom math is stored in `math/spores.yaml `_). +When solving the model in a :ref:`run mode ` other than `plan`, some built-in custom math will be applied automatically from a file of the same name (`spores` mode custom math is stored in `math/spores.yaml `_). The changes made by the built-in custom math are detailed in this page. .. note:: Custom math is applied in the order it appears in the :yaml:`model.custom_math` list. By default, any run mode custom math will be applied as the final step. If you want to apply your own custom math *after* the run mode custom math, you should add it explicitly to the :yaml:`model.custom_math` list, e.g., :yaml:`model.custom_math: [operate, my_custom_math.yaml]`. diff --git a/src/calliope/example_models/national_scale/scenarios.yaml b/src/calliope/example_models/national_scale/scenarios.yaml index e7111f82f..1d50e7aca 100644 --- a/src/calliope/example_models/national_scale/scenarios.yaml +++ b/src/calliope/example_models/national_scale/scenarios.yaml @@ -41,12 +41,12 @@ overrides: spores_score_cost_class: "spores_score" spores_number: 3 parameters: - spores_slack: + spores_slack: # In SPORES mode, slack to apply when setting the upper limit on system `spores_slack_cost_group` costs. The constraint will limit the costs to `(spores_slack + 1) * sum(costs[cost=spores_slack_cost_group])`. data: 0.1 objective_cost_class: data: [1, 0] index: ["monetary", "spores_score"] - spores_objective_cost_class: + spores_objective_cost_class: # In SPORES mode, the new objective function cost class weightings to apply after the initial base run. data: [1, 0] index: [spores_score, monetary] dims: costs diff --git a/tests/common/test_model/scenarios.yaml b/tests/common/test_model/scenarios.yaml index dd8981171..589c2c5db 100644 --- a/tests/common/test_model/scenarios.yaml +++ b/tests/common/test_model/scenarios.yaml @@ -255,7 +255,7 @@ overrides: spores_score_cost_class: "spores_score" spores_number: 3 parameters: - spores_slack: 0.1 + spores_slack.data: 0.1 objective_cost_class.data: { "monetary": 1, "spores_score": 0 } techs.test_supply_elec.costs.spores_score.flow_cap: 0