diff --git a/CHANGELOG.md b/CHANGELOG.md index 940052f3..3ca4a693 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,9 @@ ### User-facing changes +|changed| "An overview of the Calliope terminology" information admonition to remove self-references and improve understandability. +Now also includes a visual depiction of how the different defined components connect together (#699). + |fixed| Area-based parameters have appropriate documented units of `area` rather than `area^2` (#701). |fixed| Technology capacity lower bound constraints so that `[cap-type]_min` (e.g., `flow_cap_min`) is not always enforced if the `purchased_units` variable is active (#643). diff --git a/docs/advanced/solver.md b/docs/advanced/solver.md index 35e177f2..8bdcabe7 100644 --- a/docs/advanced/solver.md +++ b/docs/advanced/solver.md @@ -2,7 +2,7 @@ ## Gurobi -Refer to the [Gurobi manual](https://www.gurobi.com/documentation/), which contains a list of parameters. +Refer to the [Gurobi manual](https://docs.gurobi.com/projects/optimizer/en/current/reference/parameters.html), which contains a list of parameters. Simply use the names given in the documentation (e.g. "NumericFocus" to set the numerical focus value). For example: diff --git a/docs/creating/index.md b/docs/creating/index.md index 35ddefb2..a03d6e0f 100644 --- a/docs/creating/index.md +++ b/docs/creating/index.md @@ -1,25 +1,22 @@ # Creating a model -In short, a Calliope model works like this: **supply technologies** can take a **source** from outside of the modeled system and turn it into a specific **carrier** in the system. -The model specifies one or more **nodes** along with the technologies allowed at those nodes. -**Transmission technologies** can move the same carrier from one node to another, while **conversion technologies** can convert one carrier into another at the same node. -**Demand technologies** remove carriers from the system through a **sink**, while **storage technologies** can store carriers at a specific node. -Putting all of these possibilities together allows a modeller to specify as simple or as complex a model as necessary to answer a given research question. - -??? info "An overview of the Calliope terminology" - The terminology defined here is used throughout the documentation and the model code and configuration files: - - * **Technology**: a technology that produces, consumes, converts or transports carriers. - * **Node**: a site which can contain multiple technologies and which may contain other nodes for carrier balancing purposes. - * **Source**: a source of commodity that can (or must) be used by a technology to introduce carriers into the system. - * **Sink**: a commodity sink that can (or must) be used by a technology to remove carriers from the system. - * **Carrier**: a carrier that groups technologies together into the same network, for example `electricity` or `heat`. - - As more generally in constrained optimisation, the following terms are also used: - - * Parameter: a fixed coefficient that enters into model equations. - * Variable: a variable coefficient (decision variable) that enters into model equations. - * Constraint: an equality or inequality expression that constrains one or several variables. +A Calliope model is a collection of interconnected technologies, nodes and carriers describing a real world system of flows. +Usually, we consider those to be _energy_ flows, and most of what you will read in this documentation concerns energy systems. +However, it is just as applicable to other types of flows, such as water! + +**Carriers** are commodities whose flows we track, e.g., electricity, heat, hydrogen, water, CO2. + +**Technologies** supply, consume, convert, store or transmit _carriers_, e.g., transmission lines/pipes, batteries, power plants, wind turbines, or home appliances. + +**Nodes** contain groups of _technologies_ and are usually geographic, e.g., a country, municipality or a single house. + +Flows can enter the system from **sources**, e.g., energy from the sun to power a solar panel, and can exit it into **sinks**, e.g., electricity consumed by household appliances. +Unlike _carriers_, we do not explicitly track the type of commodity described by sources and sinks. + +Putting all of these possibilities together allows a modeller to create a model that is as simple or complex as necessary to answer a given research question. +Calliope's syntax ensures these models are intuitive, and easy to understand and share. + +![Visual description of the Calliope terminology.](../img/description_of_system.svg) !!! example Refer to the [examples and tutorials section](../examples/index.md) for a more practical look at how to build a Calliope model. diff --git a/docs/img/description_of_system.svg b/docs/img/description_of_system.svg new file mode 100644 index 00000000..57c64261 --- /dev/null +++ b/docs/img/description_of_system.svg @@ -0,0 +1,668 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index bafdfbc7..82425575 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -152,10 +152,10 @@ gurobi_cl ResultFile=result.ilp my_saved_model.lp ``` !!! info "See also" - More detail on this Gurobi functionality is available in the [official Gurobi documentation](https://www.gurobi.com/documentation/current/refman/solving_a_model2.html). + More detail on this Gurobi functionality is available in the [official Gurobi documentation](https://docs.gurobi.com/projects/optimizer/en/current/reference/misc/commandline.html#solving-a-model). -To deal with numerically unstable models, try setting `#!yaml config.solve.solver_options: {Presolve: 0}`, as large numeric ranges can cause the pre-solver to generate an [infeasible or numerically unstable model](https://www.gurobi.com/documentation/current/refman/numerics_why_scaling_and_g.html). -The [Gurobi Guidelines for Numerical Issues](https://www.gurobi.com/documentation/current/refman/numerics_gurobi_guidelines.html) give detailed guidance for strategies to address numerically difficult optimisation problems. +To deal with numerically unstable models, try setting `#!yaml config.solve.solver_options: {Presolve: 0}`, as large numeric ranges can cause the pre-solver to generate an infeasible or numerically unstable model. +The [Gurobi Guidelines for Numerical Issues](https://docs.gurobi.com/projects/optimizer/en/current/concepts/numericguide.html) give detailed guidance for strategies to address numerically difficult optimisation problems. ### Using the CPLEX solver