diff --git a/.github/workflows/tox_checks.yml b/.github/workflows/tox_checks.yml index cde986c4a..f84eb1c2c 100644 --- a/.github/workflows/tox_checks.yml +++ b/.github/workflows/tox_checks.yml @@ -25,6 +25,8 @@ jobs: - docs steps: + - name: Update package list + run: sudo apt update - name: Install LaTeX run: sudo apt install dvipng rubber texlive-latex-extra - name: Git clone diff --git a/README.rst b/README.rst index 12a9bf6f1..54c4cf9b4 100644 --- a/README.rst +++ b/README.rst @@ -100,15 +100,14 @@ Introduction The oemof.solph package is part of the `Open energy modelling framework (oemof) `_. -This an organisational framework to bundle tools for energy (system) modelling. +This is an organisational framework to bundle tools for energy (system) modelling. oemof-solph is a model generator for energy system modelling and optimisation. -The ``oemof.solph`` package is very often called just ``oemof`` as it was part of the -oemof meta package. Now you need to install ``oemof.solph`` instead of ``oemof``, but -everything else is still the same. -(Note: Since the oemof package refers to legacy versions before v0.4, -it is not possible to install both, oemof and oemof.solph, at the same time. -Just use ``pip install oemof.solph``.) +The package ``oemof.solph`` is very often called just ``oemof``. +This is because installing the ``oemof`` meta package was once the best way to get ``oemof.solph``. +Notice that you should prefeably install ``oemof.solph`` instead of ``oemof`` +if you want to use ``solph``. + Everybody is welcome to use and/or develop oemof.solph. Read our `contribution `_ section. @@ -116,7 +115,7 @@ Read our `contribution `_ +GitHub account and make changes as described in the `github guidelines `_ If you have questions regarding the use of oemof including oemof.solph you can visit the openmod forum (`tag oemof `_ or `tag oemof-solph `_) and open a new thread if your questions hasn't been already answered. @@ -135,20 +134,26 @@ The `oemof.solph documentation `_ is powere Installation ============ -If you have a working Python3 environment, use pypi to install the latest version of oemof.solph. Python >= 3.8 is recommended. Lower versions may work but are not tested. +If you have a working Python installation, use pypi to install the latest version of oemof.solph. +Python >= 3.8 is recommended. Lower versions may work but are not tested. + +We highly recommend to use virtual environments. +Please refer to the documentation of your Python distribution (e.g. Anaconda, +Micromamba, or the version of Python that came with your Linux installation) +to learn how to set up and use virtual environments. :: - pip install oemof.solph + (venv) pip install oemof.solph If you want to use the latest features, you might want to install the **developer version**. The developer version is not recommended for productive use:: - pip install https://github.com/oemof/oemof-solph/archive/dev.zip + (venv) pip install https://github.com/oemof/oemof-solph/archive/dev.zip For running an oemof-solph optimisation model, you need to install a solver. -Following you will find guidelines for the installation process for different operation systems. +Following you will find guidelines for the installation process for different operating systems. .. _windows_solver_label: .. _linux_solver_label: @@ -157,7 +162,7 @@ Installing a solver ------------------- There are various commercial and open-source solvers that can be used with oemof. -There are two common OpenSource solvers available (CBC, GLPK), while oemof recommends CBC (Coin-or branch and cut). +There are two common Open-Source solvers available (CBC, GLPK), while oemof recommends CBC (Coin-or branch and cut). But sometimes its worth comparing the results of different solvers. Other commercial solvers like Gurobi or Cplex can be used as well. Have a look at the `pyomo docs `_ to learn about which solvers are supported. @@ -192,12 +197,12 @@ If you install the CBC solver via brew (highly recommended), it should work with **conda** -Provided you are using a Linux or MacOS, the CBC-solver can also be installed in a `conda` environment. Please note, that it is highly recomended to `use pip after conda `_, so: +Provided you are using a Linux or MacOS, the CBC-solver can also be installed in a `conda` environment. Please note, that it is highly recommended to `use pip after conda `_, so: .. code:: console - conda install -c conda-forge coincbc - pip install oemof.solph + (venv) conda install -c conda-forge coincbc + (venv) pip install oemof.solph .. _check_installation_label: @@ -210,7 +215,7 @@ in your virtual environment: .. code:: console - oemof_installation_test + (venv) oemof_installation_test If the installation was successful, you will receive something like this: @@ -253,15 +258,16 @@ To allow citing specific versions, we use the zenodo project to get a DOI for ea Examples ======== -The linkage of specific modules of the various packages is called an -application (app) and depicts for example a concrete energy system model. -You can find a large variety of helpful examples in `oemof's example repository `_ on github to download or clone. -The examples show optimisations of different energy systems and are supposed +The combination of specific modules (often including other packages) is called an +application (app). For example, it can depict a concrete energy system model. +You can find a large variety of helpful examples in the documentstion. +The examples show optimisation of different energy systems and are supposed to help new users to understand the framework's structure. There is some elaboration on the examples in the respective repository. The repository has sections for each major release. -You are welcome to contribute your own examples via a `pull request `_ or by sending us an e-mail (see `here `_ for contact information). +You are welcome to contribute your own examples via a `pull request `_ +or by e-mailing us (see `here `_ for contact information). License ======= diff --git a/docs/conf.py b/docs/conf.py index 6f36c54a3..16ec76018 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -27,6 +27,8 @@ def setup(app): "sphinx.ext.napoleon", "sphinx.ext.todo", "sphinx.ext.viewcode", + "sphinx_copybutton", + "sphinx_design", ] source_suffix = ".rst" master_doc = "index" diff --git a/docs/examples/activity_costs.rst b/docs/examples/activity_costs.rst new file mode 100644 index 000000000..0edabd8c1 --- /dev/null +++ b/docs/examples/activity_costs.rst @@ -0,0 +1,7 @@ +Activity costs +-------------- + +Costs for operation a boiler +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: activity_costs.activity_costs diff --git a/docs/examples/basic_example.rst b/docs/examples/basic_example.rst new file mode 100644 index 000000000..abcd5e7c2 --- /dev/null +++ b/docs/examples/basic_example.rst @@ -0,0 +1,7 @@ +Basic example +------------- + +Using standard oemof-solph components +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: basic_example.basic_example diff --git a/docs/examples/cellular.rst b/docs/examples/cellular.rst new file mode 100644 index 000000000..27ae45942 --- /dev/null +++ b/docs/examples/cellular.rst @@ -0,0 +1,7 @@ +Cellular energy system +---------------------- + +Building your system from smaller cells +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: cellular.cellular diff --git a/docs/examples/custom_constraints.rst b/docs/examples/custom_constraints.rst new file mode 100644 index 000000000..ee7e58195 --- /dev/null +++ b/docs/examples/custom_constraints.rst @@ -0,0 +1,15 @@ +.. _custom_constraints_label: + +Custom constraints +------------------ + +Custom-made shared limit for Flows +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: flexible_modelling.add_constraints + + +Charge-rate depending on state-of-charge +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: flexible_modelling.saturating_storage diff --git a/docs/examples/electrical.lopf.rst b/docs/examples/electrical.lopf.rst new file mode 100644 index 000000000..391f372e7 --- /dev/null +++ b/docs/examples/electrical.lopf.rst @@ -0,0 +1,7 @@ +Linear optimal power flow (lopf) +-------------------------------- + +Three-Bus system +~~~~~~~~~~~~~~~~ + +.. automodule:: electrical.lopf diff --git a/docs/examples/electrical.transshipment.rst b/docs/examples/electrical.transshipment.rst new file mode 100644 index 000000000..52ce8307f --- /dev/null +++ b/docs/examples/electrical.transshipment.rst @@ -0,0 +1,7 @@ +Transshipment +------------- + +Using the link component +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: electrical.transshipment diff --git a/docs/examples/emission_constraint.rst b/docs/examples/emission_constraint.rst new file mode 100644 index 000000000..1933d3bb1 --- /dev/null +++ b/docs/examples/emission_constraint.rst @@ -0,0 +1,7 @@ +Emission constraint +------------------- + +Limiting CO2 emissions +~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: emission_constraint.emission_constraint diff --git a/docs/examples/excel_reader.rst b/docs/examples/excel_reader.rst new file mode 100644 index 000000000..ee2d6737f --- /dev/null +++ b/docs/examples/excel_reader.rst @@ -0,0 +1,9 @@ +.. _excel_reader_example_label: + +Spreadsheet (Excel) Reader +-------------------------- + +Generating a model from excel +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: excel_reader.dispatch diff --git a/docs/examples/flow_count_limit.rst b/docs/examples/flow_count_limit.rst new file mode 100644 index 000000000..62c3be78d --- /dev/null +++ b/docs/examples/flow_count_limit.rst @@ -0,0 +1,7 @@ +Flow count limit +---------------- + +Limit the maximum number of active flows +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: flow_count_limit.flow_count_limit diff --git a/docs/examples/flow_gradient.rst b/docs/examples/flow_gradient.rst new file mode 100644 index 000000000..ba70d9797 --- /dev/null +++ b/docs/examples/flow_gradient.rst @@ -0,0 +1,7 @@ +Flow gradient +------------- + +Ramping of a power plant +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: gradient_example.gradient_example diff --git a/docs/examples/index.rst b/docs/examples/index.rst index e64a5dbb4..1d440c1a4 100644 --- a/docs/examples/index.rst +++ b/docs/examples/index.rst @@ -5,5 +5,28 @@ Examples .. toctree:: :glob: + :maxdepth: 2 - solph.examples* + basic_example.rst + time_index.rst + nametuple.rst + simple_dispatch.rst + cellular.rst + activity_costs.rst + min_max_runtimes.rst + startup_costs.rst + flow_gradient.rst + variable_chp.rst + unbalanced_storage.rst + storage_costs.rst + emission_constraint.rst + flow_count_limit.rst + storage_level_constraint.rst + electrical.transshipment.rst + excel_reader.rst + storage_investment.rst + shared_invest_limit.rst + minimal_investment.rst + invest_nonconvex.rst + electrical.lopf.rst + custom_constraints.rst diff --git a/docs/examples/invest_nonconvex.rst b/docs/examples/invest_nonconvex.rst new file mode 100644 index 000000000..2c3f74c25 --- /dev/null +++ b/docs/examples/invest_nonconvex.rst @@ -0,0 +1,14 @@ +Combination of investment and binary status variable +---------------------------------------------------- + +Different components in common energy system +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. automodule:: invest_nonconvex_flow_examples.house_without_nonconvex_investment + +Same component but different Flows +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. automodule:: invest_nonconvex_flow_examples.house_with_nonconvex_investment + +Same Flow +~~~~~~~~~ +.. automodule:: invest_nonconvex_flow_examples.diesel_genset_nonconvex_investment diff --git a/docs/examples/min_max_runtimes.rst b/docs/examples/min_max_runtimes.rst new file mode 100644 index 000000000..aee5bc0e3 --- /dev/null +++ b/docs/examples/min_max_runtimes.rst @@ -0,0 +1,9 @@ +.. _runtime_limit_example_label: + +Minimal and maximal runtime +--------------------------- + +Constraining uptime and downtime of plants +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: min_max_runtimes.min_max_runtimes diff --git a/docs/examples/minimal_investment.rst b/docs/examples/minimal_investment.rst new file mode 100644 index 000000000..320bf04d2 --- /dev/null +++ b/docs/examples/minimal_investment.rst @@ -0,0 +1,7 @@ +Investment with minimal invest +------------------------------ + +Transformer with minimum size +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: investment_with_minimal_invest.minimal_invest diff --git a/docs/examples/nametuple.rst b/docs/examples/nametuple.rst new file mode 100644 index 000000000..497891d40 --- /dev/null +++ b/docs/examples/nametuple.rst @@ -0,0 +1,7 @@ +Tuple as label +-------------- + +Using tuples as names for components +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: tuple_as_labels.tuple_as_label diff --git a/docs/examples/shared_invest_limit.rst b/docs/examples/shared_invest_limit.rst new file mode 100644 index 000000000..6395703f3 --- /dev/null +++ b/docs/examples/shared_invest_limit.rst @@ -0,0 +1,7 @@ +Generic Invest limit +-------------------- + +Concurrence for building space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: generic_invest_limit.example_generic_invest diff --git a/docs/examples/simple_dispatch.rst b/docs/examples/simple_dispatch.rst new file mode 100644 index 000000000..101b82987 --- /dev/null +++ b/docs/examples/simple_dispatch.rst @@ -0,0 +1,7 @@ +Simple heat and power dispatch +------------------------------ + +Linear dispatch optimization +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: simple_dispatch.simple_dispatch diff --git a/docs/examples/solph.examples.rst b/docs/examples/solph.examples.rst deleted file mode 100644 index aa9562f29..000000000 --- a/docs/examples/solph.examples.rst +++ /dev/null @@ -1,143 +0,0 @@ -Basic example -------------- - -.. automodule:: basic_example.basic_example - - -Basic Time Index ----------------- - -.. automodule:: time_index_example.time_index_example - - -Activity costs --------------- - -.. automodule:: activity_costs.activity_costs - - -Balanced and unbalanced storage -------------------------------- - -.. automodule:: storage_balanced_unbalanced.storage - - -Cellular modelling ------------------- - -.. automodule:: cellular.cellular - - -Electrical ----------- - -Linear optimal power flow (lopf) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: electrical.lopf - -Transshipment -~~~~~~~~~~~~~ - -.. automodule:: electrical.transshipment - - -Emission constraint -------------------- - -.. automodule:: emission_constraint.emission_constraint - - -Flexible modelling ------------------- - -Add constraints -~~~~~~~~~~~~~~~ - -.. automodule:: flexible_modelling.add_constraints - - -Flow count limit ----------------- - -.. automodule:: flow_count_limit.flow_count_limit - - -Flow gradient -------------- - -.. automodule:: gradient_example.gradient_example - - -Generic Invest limit --------------------- - -.. automodule:: generic_invest_limit.example_generic_invest - - -Investment with minimal invest ------------------------------- - -.. automodule:: investment_with_minimal_invest.minimal_invest - - -Minimal and maximal runtime ---------------------------- - -.. automodule:: min_max_runtimes.min_max_runtimes - - -Simple heat and power dispatch ------------------------------- - -.. automodule:: simple_dispatch.simple_dispatch - - -Spreadsheet (Excel) Reader --------------------------- - -.. automodule:: excel_reader.dispatch - - -Start and shutdown costs ------------------------- - -.. automodule:: start_and_shutdown_costs.startup_shutdown - - -Storage investment ------------------- - -Optimize all technologies -~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: storage_investment.v1_invest_optimize_all_technologies - - -Optimize only gas and storage -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: storage_investment.v2_invest_optimize_only_gas_and_storage - -Optimize only storage with fossil share -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: storage_investment.v3_invest_optimize_only_storage_with_fossil_share - -Optimize all technologies with fossil share -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: storage_investment.v4_invest_optimize_all_technologies_with_fossil_share - - -Tuple as label --------------- - -.. automodule:: tuple_as_labels.tuple_as_label - - -Variable CHP ------------- - -.. automodule:: variable_chp.variable_chp - diff --git a/docs/examples/startup_costs.rst b/docs/examples/startup_costs.rst new file mode 100644 index 000000000..c9503c703 --- /dev/null +++ b/docs/examples/startup_costs.rst @@ -0,0 +1,7 @@ +Start and shutdown costs +------------------------ + +Costs for change in operational status +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: start_and_shutdown_costs.startup_shutdown diff --git a/docs/examples/storage_costs.rst b/docs/examples/storage_costs.rst new file mode 100644 index 000000000..55ce42087 --- /dev/null +++ b/docs/examples/storage_costs.rst @@ -0,0 +1,7 @@ +Storage costs +------------- + +Costs by state of charge +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: storage_costs.storage_costs diff --git a/docs/examples/storage_investment.rst b/docs/examples/storage_investment.rst new file mode 100644 index 000000000..2b22b60c8 --- /dev/null +++ b/docs/examples/storage_investment.rst @@ -0,0 +1,23 @@ +Storage investment +------------------ + +Optimize all technologies +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: storage_investment.v1_invest_optimize_all_technologies + + +Optimize only gas and storage +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: storage_investment.v2_invest_optimize_only_gas_and_storage + +Optimize only storage with fossil share +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: storage_investment.v3_invest_optimize_only_storage_with_fossil_share + +Optimize all technologies with fossil share +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: storage_investment.v4_invest_optimize_all_technologies_with_fossil_share diff --git a/docs/examples/storage_level_constraint.rst b/docs/examples/storage_level_constraint.rst new file mode 100644 index 000000000..31082b567 --- /dev/null +++ b/docs/examples/storage_level_constraint.rst @@ -0,0 +1,7 @@ +Storage level constraint +------------------------ + +Constrain inflows and outflows to storage level +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: storage_level_constraint.storage_level_constraint diff --git a/docs/examples/time_index.rst b/docs/examples/time_index.rst new file mode 100644 index 000000000..95a7da6f7 --- /dev/null +++ b/docs/examples/time_index.rst @@ -0,0 +1,12 @@ +Time Index +---------- + +Basic time index +~~~~~~~~~~~~~~~~ + +.. automodule:: time_index_example.simple_time_step_example + +Non-equidistant time steps +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: time_index_example.non_equidistant_time_step_example diff --git a/docs/examples/unbalanced_storage.rst b/docs/examples/unbalanced_storage.rst new file mode 100644 index 000000000..0215ca892 --- /dev/null +++ b/docs/examples/unbalanced_storage.rst @@ -0,0 +1,7 @@ +Balanced and unbalanced storage +------------------------------- + +Cyclic storage behavior +~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: storage_balanced_unbalanced.storage diff --git a/docs/examples/variable_chp.rst b/docs/examples/variable_chp.rst new file mode 100644 index 000000000..082c2bd33 --- /dev/null +++ b/docs/examples/variable_chp.rst @@ -0,0 +1,7 @@ +Variable CHP +------------ + +Modeling different types of CHP plants +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: variable_chp.variable_chp diff --git a/docs/requirements.txt b/docs/requirements.txt index edcd95c40..5937633e1 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,5 +1,7 @@ -sphinx>=1.3 +sphinx>=1.3, < 7 sphinx-rtd-theme +sphinx-copybutton +sphinx-design setuptools matplotlib blinker diff --git a/docs/usage.rst b/docs/usage.rst index 9c54d38f8..a3e9e2a73 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -6,7 +6,7 @@ User's guide ~~~~~~~~~~~~ -Solph is an oemof-package, designed to create and solve linear or mixed-integer linear optimization problems. The package is based on pyomo. To create an energy system model generic and specific components are available. To get started with solph, checkout the examples in the :ref:`solph_examples_label` section. +Solph is an oemof-package, designed to create and solve linear or mixed-integer linear optimization problems. The package is based on pyomo. To create an energy system model generic and specific components are available. To get started with solph, checkout the examples in the :ref:`examples_label` section. This User's guide provides a user-friendly introduction into oemof-solph, which includes small examples and nice illustrations. @@ -25,7 +25,8 @@ How can I use solph? -------------------- To use solph you have to install oemof.solph and at least one solver (see :ref:`installation_label`), which can be used together with pyomo (e.g. CBC, GLPK, Gurobi, Cplex). See the `pyomo installation guide `_ for all supported solvers. -You can test it by executing one of the existing examples (see :ref:`solph_examples_label`, or directly `oemof's example repository `__). Be aware that the examples require the CBC solver but you can change the solver name in the example files to your solver. +You can test it by executing one of the existing examples (see :ref:`examples_label`). +Be aware that the examples require the CBC solver but you can change the solver name in the example files to your solver. Once the examples work you are close to your first energy model. @@ -433,8 +434,8 @@ of the two flows is the main flow. In the example above, the flow to the Bus *'b_el'* is the main flow and the flow to the Bus *'b_th'* is the tapped flow. The following plot shows how the variable chp (right) schedules it's electrical and thermal power production in contrast to a fixed chp (left). The plot is the -output of an example in the `example repository -`_. +output of an example in the `example directory +`_. .. image:: _files/variable_chp_plot.svg :scale: 10 % @@ -609,7 +610,7 @@ By calling: you get the results of the scalar values of your storage, e.g. the initial storage content before time step zero (``init_content``). -For more information see the definition of the :py:class:`~oemof.solph.components._generic_storage.GenericStorage` class or check the `example repository of oemof `_. +For more information see the definition of the :py:class:`~oemof.solph.components._generic_storage.GenericStorage` class or check the :ref:`examples_label`. Using an investment object with the GenericStorage component @@ -1520,8 +1521,8 @@ increases the computation time by more than 9 times compared to the Adding additional constraints ----------------------------- -You can add additional constraints to your :py:class:`~oemof.solph.models.Model`. See `flexible_modelling in the example repository -`_ to learn how to do it. +You can add additional constraints to your :py:class:`~oemof.solph.models.Model`. +See :ref:`custom_constraints_label` to learn how to do it. Some predefined additional constraints can be found in the :py:mod:`~oemof.solph.constraints` module. @@ -1577,7 +1578,7 @@ The idea is to create different sheets within one spreadsheet file for different Once you have create your specific excel reader you can lower the entry barrier for other users. It is some sort of a GUI in form of platform independent spreadsheet software and to make data and models exchangeable in one archive. -See `oemof's example repository `_ for an excel reader example. +See :ref:`excel_reader_example_label` for an excel reader example. .. _oemof_outputlib_label: diff --git a/docs/whatsnew/v0-2-0.rst b/docs/whatsnew/v0-2-0.rst index 7b3ba7914..2800e41d3 100644 --- a/docs/whatsnew/v0-2-0.rst +++ b/docs/whatsnew/v0-2-0.rst @@ -5,9 +5,7 @@ API changes #################### * The `NodesFromCSV` has been removed from the code base. An alternative excel - (spreadsheet) reader is provided in the newly created - `excel example in the oemof_examples `_ - repository. + (spreadsheet) reader is provided at :ref:`excel_reader_example_label`. * LinearTransformer and LinearN1Transformer classes are now combined within one Transformer class. The new class has n inputs and n outputs. Please note that the definition of the conversion factors (for N1) has changed. See the new @@ -30,8 +28,7 @@ API changes ` to an `energy system `. This option has been made a bit more feature rich by the way, but see below for more on this. - Also check the - `oemof_examples `_ repository + Also check the :ref:`examples_label` for more information on the usage. * The `fixed_costs` attribute of the `nodes ` has been removed. See @@ -44,14 +41,12 @@ API changes New features #################### -* A new `oemof_examples `_ repository - with some new examples was created. * A new outputlib module has been created to provide a convenient data structure for optimization results and enable quick analyses. All decision variables of a Node are now collected automatically which enables an easier development of custom components. See the revised :ref:`oemof_outputlib_label` documentation for more details or have a look at - the `oemof_examples `_ repository + :ref:`examples_label` for information on the usage. Keep your eyes open, some new functions will come soon that make the processing of the results easier. See the actual pull request or issues for detailed information. @@ -91,13 +86,13 @@ New components Please check your results. Feedback is welcome! * The custom component `Link ` can now be used to model a bidirectional connection within one component. Check out the example in the - `oemof_examples `_ repository. + :ref:`examples_label`. * The component `GenericCHP ` can be used to model different CHP types such as extraction or back-pressure turbines and motoric plants. The component uses a mixed-integer linear formulation and can be adapted to different technical layouts with a high level of detail. Check out the example in the - `oemof_examples `_ repository. + :ref:`examples_label`. * The component `GenericCAES ` can be used to model different concepts of compressed air energy storage. Technical concepts such as diabatic or adiabatic layouts can be modelled at a high level @@ -146,7 +141,7 @@ Other changes they are less a necessary part but more an optional tool . Basic plotting examples that show how to quickly create plots from optimization results can now be found in the - `oemof_examples `_ repository. + :ref:`examples_label`. You can still find the "old" standard plots within the `oemof_visio `_ repository as they are now maintained separately. diff --git a/docs/whatsnew/v0-2-1.rst b/docs/whatsnew/v0-2-1.rst index 7e3a745b9..3a9f6127e 100644 --- a/docs/whatsnew/v0-2-1.rst +++ b/docs/whatsnew/v0-2-1.rst @@ -15,8 +15,7 @@ New features #################### * It is now possible determine minimum up and downtimes for nonconvex flows. - Check the `oemof_examples `_ - repository for an exemplary usage. + Check :ref:`runtime_limit_example_label` for an exemplary usage. * Startup and shutdown costs can now be defined time-dependent. diff --git a/docs/whatsnew/v0-4-4.rst b/docs/whatsnew/v0-4-4.rst index 62e393c86..292766fbd 100644 --- a/docs/whatsnew/v0-4-4.rst +++ b/docs/whatsnew/v0-4-4.rst @@ -12,7 +12,7 @@ API changes New components/constraints ########################## -* Custom component: oemof.solph.custom.PiecewiseLinearTransformer. A transformer model with one input and one output and an arbitrary piecewise linear conversion function. On how to use the component, refer to the `test script `_ and `example `_. +* Custom component: oemof.solph.custom.PiecewiseLinearTransformer. A transformer model with one input and one output and an arbitrary piecewise linear conversion function. On how to use the component, refer to the `test script `_. * Enhanced custom SinkDSM: * Renamed keyword argument `method` to `approach` * Renamed approaches `interval` to `oemof` and `delay` to `DIW` diff --git a/examples/activity_costs/activity_costs.py b/examples/activity_costs/activity_costs.py index a51dbbb0e..950304d21 100644 --- a/examples/activity_costs/activity_costs.py +++ b/examples/activity_costs/activity_costs.py @@ -8,19 +8,30 @@ There are the following components: - - demand_heat: heat demand (constant, for the sake of simplicity) - - fireplace: wood firing, burns "for free" if somebody is around - - boiler: gas firing, consumes (paid) gas +- demand_heat: heat demand (constant, for the sake of simplicity) +- fireplace: wood firing, burns "for free" if somebody is around +- boiler: gas firing, consumes (paid) gas Notice that activity_costs is an attribute to NonConvex. This is because it relies on the activity status of a component which is only available for nonconvex flows. +Code +---- +Download source code: :download:`activity_costs.py ` + +.. dropdown:: Click to display code + + .. literalinclude:: /../examples/activity_costs/activity_costs.py + :language: python + :lines: 43-118 Installation requirements ------------------------- This example requires oemof.solph (v0.5.x), install by: +.. code:: bash + pip install oemof.solph[examples] License diff --git a/examples/basic_example/basic_example.py b/examples/basic_example/basic_example.py index 03b806012..0350fcd42 100644 --- a/examples/basic_example/basic_example.py +++ b/examples/basic_example/basic_example.py @@ -28,16 +28,26 @@ storage(Storage) |<------------------| |------------------>| +Code +---- +Download source code: :download:`basic_example.py ` + +.. dropdown:: Click to display code + + .. literalinclude:: /../examples/basic_example/basic_example.py + :language: python + :lines: 61- Data ---- -basic_example.csv - +Download data: :download:`basic_example.csv ` Installation requirements ------------------------- This example requires oemof.solph (v0.5.x), install by: +.. code:: bash + pip install oemof.solph[examples] License diff --git a/examples/cellular/cellular.py b/examples/cellular/cellular.py index 53a223757..2d208a16e 100644 --- a/examples/cellular/cellular.py +++ b/examples/cellular/cellular.py @@ -13,11 +13,23 @@ the parent and child cell). Losses can be modelled by using the `conversion_factors` of the Link class. +Code +---- +Download source code: :download:`cellular.py ` + +.. dropdown:: Click to display code + + .. literalinclude:: /../examples/cellular/cellular.py + :language: python + :lines: 45-346 + Installation requirements ------------------------- This example requires at least oemof.solph (v0.5.1), install by: +.. code:: bash + pip install oemof.solph[examples] Licence diff --git a/examples/dual_variable_example/dual_variable_example.py b/examples/dual_variable_example/dual_variable_example.py index 77c9ec9fc..869113ac2 100644 --- a/examples/dual_variable_example/dual_variable_example.py +++ b/examples/dual_variable_example/dual_variable_example.py @@ -7,18 +7,44 @@ A basic example to show how to get the dual variables from the system. Try to understand the plot. +Code +---- +Download source code: :download:`dual_variable_example.py ` + +.. dropdown:: Click to display code + + .. literalinclude:: /../examples/dual_variable_example/dual_variable_example.py + :language: python + :lines: 34-297 + Installation requirements ------------------------- This example requires the version v0.5.x of oemof.solph: +.. code:: bash + pip install 'oemof.solph[examples]>=0.5,<0.6' SPDX-FileCopyrightText: Uwe Krien SPDX-License-Identifier: MIT """ +########################################################################### +# imports +########################################################################### + +import pandas as pd +from matplotlib import pyplot as plt +from oemof.tools import logger + +from oemof.solph import EnergySystem +from oemof.solph import Model +from oemof.solph import buses +from oemof.solph import components as cmp +from oemof.solph import flows +from oemof.solph import processing def main(): @@ -26,21 +52,6 @@ def main(): # ********** PART 1 - Define and optimise the energy system *************** # ************************************************************************* - ########################################################################### - # imports - ########################################################################### - - import pandas as pd - from matplotlib import pyplot as plt - from oemof.tools import logger - - from oemof.solph import EnergySystem - from oemof.solph import Model - from oemof.solph import buses - from oemof.solph import components as cmp - from oemof.solph import flows - from oemof.solph import processing - solver = "cbc" # 'glpk', 'gurobi',.... number_of_time_steps = 48 solver_verbose = False # show/hide solver output diff --git a/examples/electrical/lopf.py b/examples/electrical/lopf.py index 5c1918b9b..33be875c0 100644 --- a/examples/electrical/lopf.py +++ b/examples/electrical/lopf.py @@ -10,14 +10,28 @@ Note: As oemof currently does not support models with one timesteps, therefore there are two. +Code +---- +Download source code: :download:`lopf.py ` + +.. dropdown:: Click to display code + + .. literalinclude:: /../examples/electrical/lopf.py + :language: python + :lines: 44-221 + Installation requirements ------------------------- This example requires oemof.solph (v0.5.x), install by: +.. code:: bash + pip install oemof.solph[examples] To draw the graph pygraphviz is required, installed by: +.. code:: bash + pip install pygraphviz License diff --git a/examples/electrical/transshipment.py b/examples/electrical/transshipment.py index e86d1b0b5..2379da98b 100644 --- a/examples/electrical/transshipment.py +++ b/examples/electrical/transshipment.py @@ -6,15 +6,28 @@ This script shows how use the custom component `solph.custom.Link` to build a simple transshipment model. +Code +---- +Download source code: :download:`transshipment.py ` + +.. dropdown:: Click to display code + + .. literalinclude:: /../examples/electrical/transshipment.py + :language: python + :lines: 39-211 Installation requirements ------------------------- This example requires oemof.solph (v0.5.x), install by: +.. code:: bash + pip install oemof.solph[examples] To draw the graph pygraphviz is required, installed by: +.. code:: bash + pip install pygraphviz License diff --git a/examples/emission_constraint/emission_constraint.py b/examples/emission_constraint/emission_constraint.py index 0633ded72..5aaebd5bd 100644 --- a/examples/emission_constraint/emission_constraint.py +++ b/examples/emission_constraint/emission_constraint.py @@ -5,11 +5,23 @@ ------------------- Example that shows how to add an emission constraint in a model. +Code +---- +Download source code: :download:`emission_constraint.py ` + +.. dropdown:: Click to display code + + .. literalinclude:: /../examples/emission_constraint/emission_constraint.py + :language: python + :lines: 32-129 + Installation requirements ------------------------- This example requires oemof.solph (v0.5.x), install by: +.. code:: bash + pip install oemof.solph[examples] License diff --git a/examples/excel_reader/dispatch.py b/examples/excel_reader/dispatch.py index 4b32377d9..102186ef7 100644 --- a/examples/excel_reader/dispatch.py +++ b/examples/excel_reader/dispatch.py @@ -9,25 +9,38 @@ The pandas package supports the '.xls' and the '.xlsx' format but one can create read and adept the files with open source software such as libreoffice, -openoffice, gnumeric,... +openoffice, gnumeric, ... + +Code +---- +Download source code: :download:`dispatch.py ` + +.. dropdown:: Click to display code + + .. literalinclude:: /../examples/excel_reader/dispatch.py + :language: python + :lines: 57-437 Data ---- -scenario.xlsx +Download data: :download:`scenario.xlsx ` Installation requirements ------------------------- This example requires oemof.solph (v0.5.x), install by: - pip install oemof.solph[examples] +.. code:: bash - pip3 install openpyxl + pip install oemof.solph[examples] + pip install openpyxl If you want to plot the energy system's graph, you have to install pygraphviz using: - pip3 install pygraphviz +.. code:: bash + + pip install pygraphviz For pygraphviz under Windows, some hints are available in the oemof Wiki: https://github.com/oemof/oemof/wiki/Windows---general diff --git a/examples/flexible_modelling/add_constraints.py b/examples/flexible_modelling/add_constraints.py index 56db0dbc4..9febeec0c 100644 --- a/examples/flexible_modelling/add_constraints.py +++ b/examples/flexible_modelling/add_constraints.py @@ -8,14 +8,28 @@ The constraint we add forces a flow to be greater or equal a certain share of all inflows of its target bus. Moreover we will set an emission constraint. +Code +---- +Download source code: :download:`add_constraints.py ` + +.. dropdown:: Click to display code + + .. literalinclude:: /../examples/flexible_modelling/add_constraints.py + :language: python + :lines: 41-158 + Installation requirements ------------------------- This example requires oemof.solph (v0.5.x), install by: +.. code:: bash + pip install oemof.solph[examples] To draw the graph pygraphviz is required, installed by: +.. code:: bash + pip install pygraphviz License @@ -24,10 +38,6 @@ `MIT license `_ """ - -__copyright__ = "oemof developer group" -__license__ = "GPLv3" - import logging import pandas as pd diff --git a/examples/flexible_modelling/saturating_storage.py b/examples/flexible_modelling/saturating_storage.py index c2841ec88..08efa43ab 100644 --- a/examples/flexible_modelling/saturating_storage.py +++ b/examples/flexible_modelling/saturating_storage.py @@ -6,11 +6,23 @@ Example that shows the how to implement a `GenericStorage` that charges at reduced rates for high storage contents. +Code +---- +Download source code: :download:`saturating_storage.py ` + +.. dropdown:: Click to display code + + .. literalinclude:: /../examples/flexible_modelling/saturating_storage.py + :language: python + :lines: 34-140 + Installation requirements ------------------------- This example requires oemof.solph (v0.5.x), install by: +.. code:: bash + pip install oemof.solph[examples] diff --git a/examples/flow_count_limit/flow_count_limit.py b/examples/flow_count_limit/flow_count_limit.py index 3cbcd0c40..0ba707e74 100644 --- a/examples/flow_count_limit/flow_count_limit.py +++ b/examples/flow_count_limit/flow_count_limit.py @@ -4,14 +4,32 @@ General description ------------------- -Something... +Example that shows how to use "flow_count_limit". +This example shows a case where only one out of two Flows can be +active at a time. Another typical usage might be a connection to a +grid where energy can only flow into one direction or a storage that +cannot be charged and discharged at the same time. + +Note that binary variables are computationally expensive. Thus, you +might want to avoid using this constraint if you do not really need it. + +Code +---- +Download source code: :download:`flow_count_limit.py ` + +.. dropdown:: Click to display code + + .. literalinclude:: /../examples/flow_count_limit/flow_count_limit.py + :language: python + :lines: 39-159 Installation requirements ------------------------- - This example requires oemof.solph (v0.5.x), install by: +.. code:: bash + pip install oemof.solph[examples] License diff --git a/examples/generic_invest_limit/example_generic_invest.py b/examples/generic_invest_limit/example_generic_invest.py index 3a3776702..b8dc910c7 100644 --- a/examples/generic_invest_limit/example_generic_invest.py +++ b/examples/generic_invest_limit/example_generic_invest.py @@ -1,5 +1,7 @@ # -*- coding: utf-8 -*- r""" +General description +------------------- Example that shows how to use "Generic Investment Limit". There are two supply chains. The energy systems looks like that: @@ -32,10 +34,22 @@ And the total space is limited to 24. See what happens, have fun ;) +Code +---- +Download source code: :download:`example_generic_invest.py ` + +.. dropdown:: Click to display code + + .. literalinclude:: /../examples/generic_invest_limit/example_generic_invest.py + :language: python + :lines: 62-219 + Installation requirements ------------------------- This example requires oemof.solph (v0.5.x), install by: +.. code:: bash + pip install oemof.solph[examples] License @@ -43,8 +57,6 @@ Johannes Röder `MIT license `_ - - """ import logging diff --git a/examples/gradient_example/gradient_example.py b/examples/gradient_example/gradient_example.py index e6ea77bad..1e1ceb4d9 100644 --- a/examples/gradient_example/gradient_example.py +++ b/examples/gradient_example/gradient_example.py @@ -8,11 +8,22 @@ Change the GRADIENT variable in the example to see the effect on the usage of the storage. +Code +---- +Download source code: :download:`gradient_example.py ` + +.. dropdown:: Click to display code + + .. literalinclude:: /../examples/gradient_example/gradient_example.py + :language: python + :lines: 35-211 Installation requirements ------------------------- This example requires oemof.solph (v0.5.x), install by: +.. code:: bash + pip install oemof.solph[examples] diff --git a/examples/invest_nonconvex_flow_examples/__init__.py b/examples/invest_nonconvex_flow_examples/__init__.py deleted file mode 100644 index e69de29bb..000000000 diff --git a/examples/invest_nonconvex_flow_examples/diesel_genset_nonconvex_investment.py b/examples/invest_nonconvex_flow_examples/diesel_genset_nonconvex_investment.py index 098f4b673..d7eed06f3 100644 --- a/examples/invest_nonconvex_flow_examples/diesel_genset_nonconvex_investment.py +++ b/examples/invest_nonconvex_flow_examples/diesel_genset_nonconvex_investment.py @@ -8,22 +8,35 @@ There are the following components: - - pv: solar potential to generate electricity - - diesel_source: input diesel for the diesel genset - - diesel_genset: generates ac electricity - - rectifier: converts generated ac electricity from the diesel genset - to dc electricity - - inverter: converts generated dc electricity from the pv to ac electricity - - battery: stores the generated dc electricity - - demand_el: ac electricity demand (given as a separate *.csv file) - - excess_el: allows for some electricity overproduction +- pv: solar potential to generate electricity +- diesel_source: input diesel for the diesel genset +- diesel_genset: generates ac electricity +- rectifier: converts generated ac electricity from the diesel genset to dc electricity +- inverter: converts generated dc electricity from the pv to ac electricity +- battery: stores the generated dc electricity +- demand_el: ac electricity demand (given as a separate csv file) +- excess_el: allows for some electricity overproduction +Code +---- +Download source code: :download:`diesel_genset_nonconvex_investment.py ` +.. dropdown:: Click to display code + + .. literalinclude:: /../examples/invest_nonconvex_flow_examples/diesel_genset_nonconvex_investment.py + :language: python + :lines: 44- + +Data +---- +Download data: :download:`solar_generation.csv ` Installation requirements ------------------------- This example requires the version v0.5.x of oemof.solph. Install by: +.. code:: bash + pip install 'oemof.solph>=0.5,<0.6' """ diff --git a/examples/invest_nonconvex_flow_examples/house_with_nonconvex_investment.py b/examples/invest_nonconvex_flow_examples/house_with_nonconvex_investment.py index c03f8061e..e8fbb1458 100644 --- a/examples/invest_nonconvex_flow_examples/house_with_nonconvex_investment.py +++ b/examples/invest_nonconvex_flow_examples/house_with_nonconvex_investment.py @@ -9,18 +9,26 @@ There are the following components: - - demand_heat: heat demand (high in winter, low in summer) - - fireplace: wood firing, has a minimum heat and - will burn for a minimum time if lit. - - boiler: gas firing, more flexible but still - with minimal load and also with - higher cost than wood firing +- demand_heat: heat demand (high in winter, low in summer) +- fireplace: wood firing, has a minimum heat and will burn for a minimum time if lit. +- boiler: gas firing, more flexible but still with minimal load and also with higher cost than wood firing +Code +---- +Download source code: :download:`house_with_nonconvex_investment.py ` + +.. dropdown:: Click to display code + + .. literalinclude:: /../examples/invest_nonconvex_flow_examples/house_with_nonconvex_investment.py + :language: python + :lines: 37- Installation requirements ------------------------- This example requires the version v0.5.x of oemof.solph. Install by: +.. code:: bash + pip install 'oemof.solph>=0.5,<0.6' """ diff --git a/examples/invest_nonconvex_flow_examples/house_without_nonconvex_investment.py b/examples/invest_nonconvex_flow_examples/house_without_nonconvex_investment.py index ddf01bce6..cca936cce 100644 --- a/examples/invest_nonconvex_flow_examples/house_without_nonconvex_investment.py +++ b/examples/invest_nonconvex_flow_examples/house_without_nonconvex_investment.py @@ -9,24 +9,28 @@ There are the following components: - - demand_heat: heat demand (high in winter, low in summer) - - fireplace: wood firing, has a minimum heat and - will burn for a minimum time if lit - - boiler: gas firing, more flexible but with - higher (flexible) cost than wood firing - - thermal_collector: solar thermal collector, - size is to be optimized in this example - (high gain in summer, low in winter) - - excess_heat: allow for some heat overproduction - (solution would be trivial without, - as the collector size would be given - by the demand in summer) +- demand_heat: heat demand (high in winter, low in summer) +- fireplace: wood firing, has a minimum heat and will burn for a minimum time if lit +- boiler: gas firing, more flexible but with higher (flexible) cost than wood firing +- thermal_collector: solar thermal collector, size is to be optimized in this example (high gain in summer, low in winter) +- excess_heat: allow for some heat overproduction (solution would be trivial without, as the collector size would be given by the demand in summer) +Code +---- +Download source code: :download:`house_without_nonconvex_investment.py ` + +.. dropdown:: Click to display code + + .. literalinclude:: /../examples/invest_nonconvex_flow_examples/house_without_nonconvex_investment.py + :language: python + :lines: 43- Installation requirements ------------------------- This example requires the version v0.5.x of oemof.solph. Install by: +.. code:: bash + pip install 'oemof.solph>=0.5,<0.6' """ diff --git a/examples/investment_with_minimal_invest/minimal_invest.py b/examples/investment_with_minimal_invest/minimal_invest.py index 1b9b3c572..1ff186cf8 100644 --- a/examples/investment_with_minimal_invest/minimal_invest.py +++ b/examples/investment_with_minimal_invest/minimal_invest.py @@ -2,10 +2,22 @@ """ Example that shows how to use "Offset-Invest". +Code +---- +Download source code: :download:`minimal_invest.py ` + +.. dropdown:: Click to display code + + .. literalinclude:: /../examples/investment_with_minimal_invest/minimal_invest.py + :language: python + :lines: 31- + Installation requirements ------------------------- This example requires oemof.solph (v0.5.x), install by: +.. code:: bash + pip install oemof.solph[examples] License diff --git a/examples/min_max_runtimes/min_max_runtimes.py b/examples/min_max_runtimes/min_max_runtimes.py index 54ee37159..46a56deed 100644 --- a/examples/min_max_runtimes/min_max_runtimes.py +++ b/examples/min_max_runtimes/min_max_runtimes.py @@ -5,11 +5,23 @@ ------------------- Example that illustrates how to model min and max runtimes. +Code +---- +Download source code: :download:`min_max_runtimes.py ` + +.. dropdown:: Click to display code + + .. literalinclude:: /../examples/min_max_runtimes/min_max_runtimes.py + :language: python + :lines: 33- + Installation requirements ------------------------- This example requires oemof.solph (v0.5.x), install by: +.. code:: bash + pip install oemof.solph[examples] diff --git a/examples/simple_dispatch/simple_dispatch.py b/examples/simple_dispatch/simple_dispatch.py index 7c44b684b..3d01f08b0 100644 --- a/examples/simple_dispatch/simple_dispatch.py +++ b/examples/simple_dispatch/simple_dispatch.py @@ -13,15 +13,27 @@ Additionally, it shows how combined heat and power units may be easily modelled as well. +Code +---- +Download source code: :download:`simple_dispatch.py ` + +.. dropdown:: Click to display code + + .. literalinclude:: /../examples/simple_dispatch/simple_dispatch.py + :language: python + :lines: 45- + Data ---- -input_data.csv +Download data: :download:`input_data.csv ` Installation requirements ------------------------- This example requires oemof.solph (v0.5.x), install by: +.. code:: bash + pip install oemof.solph[examples] diff --git a/examples/start_and_shutdown_costs/startup_shutdown.py b/examples/start_and_shutdown_costs/startup_shutdown.py index abee8c9e6..47b9349b6 100644 --- a/examples/start_and_shutdown_costs/startup_shutdown.py +++ b/examples/start_and_shutdown_costs/startup_shutdown.py @@ -6,10 +6,22 @@ Example that illustrates how to model startup and shutdown costs attributed to a binary flow. +Code +---- +Download source code: :download:`startup_shutdown.py ` + +.. dropdown:: Click to display code + + .. literalinclude:: /../examples/start_and_shutdown_costs/startup_shutdown.py + :language: python + :lines: 32- + Installation requirements ------------------------- This example requires oemof.solph (v0.5.x), install by: +.. code:: bash + pip install oemof.solph[examples] License diff --git a/examples/storage_balanced_unbalanced/storage.py b/examples/storage_balanced_unbalanced/storage.py index 3e62f1f7d..396e96bb1 100644 --- a/examples/storage_balanced_unbalanced/storage.py +++ b/examples/storage_balanced_unbalanced/storage.py @@ -5,11 +5,22 @@ ------------------- Example that shows the parameter `balanced` of `GenericStorage`. +Code +---- +Download source code: :download:`storage.py ` + +.. dropdown:: Click to display code + + .. literalinclude:: /../examples/storage_balanced_unbalanced/storage.py + :language: python + :lines: 32- Installation requirements ------------------------- This example requires oemof.solph (v0.5.x), install by: +.. code:: bash + pip install oemof.solph[examples] diff --git a/examples/storage_costs/storage_costs.py b/examples/storage_costs/storage_costs.py index a9e11a11f..d82068860 100644 --- a/examples/storage_costs/storage_costs.py +++ b/examples/storage_costs/storage_costs.py @@ -7,14 +7,25 @@ A battery is used to make profit from fluctuating electricity prices. For a battery without storage costs, it is beneficial to be empty the end of the time horizon of the optimisation. For a battery that -assumes the average revenue, energy is kept at the end. +assumes the average revenue, energy is kept at the end. +Code +---- +Download source code: :download:`storage_costs.py ` + +.. dropdown:: Click to display code + + .. literalinclude:: /../examples/storage_costs/storage_costs.py + :language: python + :lines: 36- Installation requirements ------------------------- -This example requires oemof.solph (v0.5.x), install by: +This example requires oemof.solph (v0.5.x) and matplotlib, install by: + +.. code:: bash - pip install oemof.solph[examples] + pip install oemof.solph[examples] matplotlib License diff --git a/examples/storage_investment/v1_invest_optimize_all_technologies.py b/examples/storage_investment/v1_invest_optimize_all_technologies.py index ce3a79891..012a81eb7 100644 --- a/examples/storage_investment/v1_invest_optimize_all_technologies.py +++ b/examples/storage_investment/v1_invest_optimize_all_technologies.py @@ -30,25 +30,40 @@ The example exists in four variations. The following parameters describe the main setting for the optimization variation 1: - - optimize wind, pv, gas_resource and storage - - set investment cost for wind, pv and storage - - set gas price for kWh +- optimize wind, pv, gas_resource and storage +- set investment cost for wind, pv and storage +- set gas price for kWh - Results show an installation of wind and the use of the gas resource. - A renewable energy share of 51% is achieved. +Results show an installation of wind and the use of the gas resource. +A renewable energy share of 51% is achieved. + +.. tip:: Have a look at different parameter settings. There are four variations of this example in the same folder. +Code +---- +Download source code: :download:`v1_invest_optimize_all_technologies.py ` + +.. dropdown:: Click to display code + + .. literalinclude:: /../examples/storage_investment/v1_invest_optimize_all_technologies.py + :language: python + :lines: 80- + Data ---- -storage_investment.csv +Download data: :download:`storage_investment.csv ` + Installation requirements ------------------------- This example requires oemof.solph (v0.5.x), install by: +.. code:: bash + pip install oemof.solph[examples] diff --git a/examples/storage_investment/v2_invest_optimize_only_gas_and_storage.py b/examples/storage_investment/v2_invest_optimize_only_gas_and_storage.py index 6657df87b..02b1c8ef3 100644 --- a/examples/storage_investment/v2_invest_optimize_only_gas_and_storage.py +++ b/examples/storage_investment/v2_invest_optimize_only_gas_and_storage.py @@ -31,23 +31,41 @@ The example exists in four variations. The following parameters describe the main setting for the optimization variation 2: - - optimize gas_resource and storage - - set installed capacities for wind and pv - - set investment cost for storage - - set gas price for kWh +- optimize gas_resource and storage +- set installed capacities for wind and pv +- set investment cost for storage +- set gas price for kWh - Results show a higher renewable energy share than in variation 1 - (78% compared to 51%) due to preinstalled renewable capacities. - Storage is not installed as the gas resource is cheaper. +Results show a higher renewable energy share than in variation 1 +(78% compared to 51%) due to preinstalled renewable capacities. +Storage is not installed as the gas resource is cheaper. + +.. tip:: Have a look at different parameter settings. There are four variations of this example in the same folder. +Code +---- +Download source code: :download:`v2_invest_optimize_only_gas_and_storage.py ` + +.. dropdown:: Click to display code + + .. literalinclude:: /../examples/storage_investment/v2_invest_optimize_only_gas_and_storage.py + :language: python + :lines: 83- + +Data +---- +Download data: :download:`storage_investment.csv ` + Installation requirements ------------------------- This example requires oemof.solph (v0.5.x), install by: +.. code:: bash + pip install oemof.solph[examples] diff --git a/examples/storage_investment/v3_invest_optimize_only_storage_with_fossil_share.py b/examples/storage_investment/v3_invest_optimize_only_storage_with_fossil_share.py index 564310453..5ba196270 100644 --- a/examples/storage_investment/v3_invest_optimize_only_storage_with_fossil_share.py +++ b/examples/storage_investment/v3_invest_optimize_only_storage_with_fossil_share.py @@ -30,24 +30,42 @@ The example exists in four variations. The following parameters describe the main setting for the optimization variation 3: - - calculate storage - - set installed capacities for wind and pv - - set investment cost for storage - - remove the gas price and set a fossil share - - now it becomes a calculation of storage capacity (no cost optimization) +- calculate storage +- set installed capacities for wind and pv +- set investment cost for storage +- remove the gas price and set a fossil share +- now it becomes a calculation of storage capacity (no cost optimization) Results show now the installation of storage because a higher renewable share than achieved in variation 2 is now required (80% compared to 78%). -Have a look at different parameter settings. There are four variations -of this example in the same folder. +.. tip:: + + Have a look at different parameter settings. There are four variations + of this example in the same folder. + +Code +---- +Download source code: :download:`v3_invest_optimize_only_storage_with_fossil_share.py ` + +.. dropdown:: Click to display code + + .. literalinclude:: /../examples/storage_investment/v3_invest_optimize_only_storage_with_fossil_share.py + :language: python + :lines: 82- + +Data +---- +Download data: :download:`storage_investment.csv ` Installation requirements ------------------------- This example requires oemof.solph (v0.5.x), install by: +.. code:: bash + pip install oemof.solph[examples] diff --git a/examples/storage_investment/v4_invest_optimize_all_technologies_with_fossil_share.py b/examples/storage_investment/v4_invest_optimize_all_technologies_with_fossil_share.py index bea03c3e1..9cc7c7dba 100644 --- a/examples/storage_investment/v4_invest_optimize_all_technologies_with_fossil_share.py +++ b/examples/storage_investment/v4_invest_optimize_all_technologies_with_fossil_share.py @@ -30,21 +30,39 @@ The example exists in four variations. The following parameters describe the main setting for the optimization variation 4: - - optimize wind, pv, and storage - - set investment cost for wind, pv and storage - - set a fossil share +- optimize wind, pv, and storage +- set investment cost for wind, pv and storage +- set a fossil share - Results show now the achievement of 80% renewable energy share - by solely installing a little more wind and pv (compared to - variation 2). Storage is not installed. +Results show now the achievement of 80% renewable energy share +by solely installing a little more wind and pv (compared to +variation 2). Storage is not installed. + +.. tip:: Have a look at different parameter settings. There are four variations of this example in the same folder. +Code +---- +Download source code: :download:`v4_invest_optimize_all_technologies_with_fossil_share.py ` + +.. dropdown:: Click to display code + + .. literalinclude:: /../examples/storage_investment/v4_invest_optimize_all_technologies_with_fossil_share.py + :language: python + :lines: 79- + +Data +---- +Download data: :download:`storage_investment.csv ` + Installation requirements ------------------------- This example requires oemof.solph (v0.5.x), install by: +.. code:: bash + pip install oemof.solph[examples] diff --git a/examples/storage_level_constraint/storage_level_constraint.py b/examples/storage_level_constraint/storage_level_constraint.py index e8bfab87d..9fd51a607 100644 --- a/examples/storage_level_constraint/storage_level_constraint.py +++ b/examples/storage_level_constraint/storage_level_constraint.py @@ -1,3 +1,40 @@ +# -*- coding: utf-8 -*- + +""" +General description +------------------- +Example that shows the `storage_level_constraint`. + +Code +---- +Download source code: :download:`storage_level_constraint.py ` + +.. dropdown:: Click to display code + + .. literalinclude:: /../examples/storage_level_constraint/storage_level_constraint.py + :language: python + :lines: 33- + +Installation requirements +------------------------- +This example requires oemof.solph (v0.5.x) and matplotlib, install by: + +.. code:: bash + + pip install oemof.solph[examples] matplotlib + + +License +------- +`MIT license `_ +""" + + +import pandas as pd +from oemof.solph import Bus, EnergySystem, Flow, Model +from oemof.solph.components import GenericStorage, Source, Sink +from oemof.solph.processing import results + import matplotlib.pyplot as plt import pandas as pd @@ -11,90 +48,95 @@ from oemof.solph.constraints import storage_level_constraint from oemof.solph.processing import results -es = EnergySystem( - timeindex=pd.date_range("2022-01-01", freq="1H", periods=24), - infer_last_interval=True, -) - -multiplexer = Bus( - label="multiplexer", -) - -storage = GenericStorage( - label="storage", - nominal_storage_capacity=3, - initial_storage_level=1, - balanced=True, - loss_rate=0.05, - inputs={multiplexer: Flow()}, - outputs={multiplexer: Flow()}, -) - -es.add(multiplexer, storage) - -in_0 = Source( - label="in_0", - outputs={multiplexer: Flow(nominal_value=0.5, variable_costs=0.15)}, -) -es.add(in_0) - -in_1 = Source(label="in_1", outputs={multiplexer: Flow(nominal_value=0.1)}) -es.add(in_1) - -out_0 = Sink( - label="out_0", - inputs={multiplexer: Flow(nominal_value=0.25, variable_costs=-0.1)}, -) -es.add(out_0) - -out_1 = Sink( - label="out_1", - inputs={multiplexer: Flow(nominal_value=0.15, variable_costs=-0.1)}, -) -es.add(out_1) - - -model = Model(es) - -storage_level_constraint( - model=model, - name="multiplexer", - storage_component=storage, - multiplexer_bus=multiplexer, - input_levels={in_1: 1 / 3}, # in_0 is always active - output_levels={out_0: 1 / 6, out_1: 1 / 2}, -) -model.solve() - -my_results = results(model) - -df = pd.DataFrame(my_results[(storage, None)]["sequences"]) -df["in1_status"] = my_results[(in_1, None)]["sequences"] -df["out1_status"] = my_results[(out_1, None)]["sequences"] -df["out0_status"] = my_results[(out_0, None)]["sequences"] - -df["in1"] = my_results[(in_1, multiplexer)]["sequences"] -df["in0"] = my_results[(in_0, multiplexer)]["sequences"] -df["out0"] = my_results[(multiplexer, out_0)]["sequences"] -df["out1"] = my_results[(multiplexer, out_1)]["sequences"] - -plt.step(df.index, df["in0"], where="post", label="inflow (<= 1)") -plt.step(df.index, df["in1"], where="post", label="inflow (< 1/3)") -plt.step(df.index, df["out0"], where="post", label="outflow (> 1/6)") -plt.step(df.index, df["out1"], where="post", label="outflow (> 1/2)") - -plt.grid() -plt.legend() -plt.ylabel("Flow Power (arb. units)") -plt.ylim(0, 0.5) - -plt.twinx() - -plt.plot(df.index, df["storage_content"], "k--", label="storage content") -plt.ylim(0, 3) -plt.legend(loc="center right") -plt.ylabel("Stored Energy (arb. units)") - -print(df) - -plt.show() + +def storage_level_constraint_example(): + es = EnergySystem( + timeindex=pd.date_range("2022-01-01", freq="1H", periods=24), + infer_last_interval=True, + ) + + multiplexer = Bus( + label="multiplexer", + ) + + storage = GenericStorage( + label="storage", + nominal_storage_capacity=3, + initial_storage_level=1, + balanced=True, + loss_rate=0.05, + inputs={multiplexer: Flow()}, + outputs={multiplexer: Flow()}, + ) + + es.add(multiplexer, storage) + + in_0 = Source( + label="in_0", + outputs={multiplexer: Flow(nominal_value=0.5, variable_costs=0.15)}, + ) + es.add(in_0) + + in_1 = Source(label="in_1", outputs={multiplexer: Flow(nominal_value=0.1)}) + es.add(in_1) + + out_0 = Sink( + label="out_0", + inputs={multiplexer: Flow(nominal_value=0.25, variable_costs=-0.1)}, + ) + es.add(out_0) + + out_1 = Sink( + label="out_1", + inputs={multiplexer: Flow(nominal_value=0.15, variable_costs=-0.1)}, + ) + es.add(out_1) + + model = Model(es) + + storage_level_constraint( + model=model, + name="multiplexer", + storage_component=storage, + multiplexer_bus=multiplexer, + input_levels={in_1: 1 / 3}, # in_0 is always active + output_levels={out_0: 1 / 6, out_1: 1 / 2}, + ) + model.solve() + + my_results = results(model) + + df = pd.DataFrame(my_results[(storage, None)]["sequences"]) + df["in1_status"] = my_results[(in_1, None)]["sequences"] + df["out1_status"] = my_results[(out_1, None)]["sequences"] + df["out0_status"] = my_results[(out_0, None)]["sequences"] + + df["in1"] = my_results[(in_1, multiplexer)]["sequences"] + df["in0"] = my_results[(in_0, multiplexer)]["sequences"] + df["out0"] = my_results[(multiplexer, out_0)]["sequences"] + df["out1"] = my_results[(multiplexer, out_1)]["sequences"] + + plt.step(df.index, df["in0"], where="post", label="inflow (<= 1)") + plt.step(df.index, df["in1"], where="post", label="inflow (< 1/3)") + plt.step(df.index, df["out0"], where="post", label="outflow (> 1/6)") + plt.step(df.index, df["out1"], where="post", label="outflow (> 1/2)") + + plt.grid() + plt.legend() + plt.ylabel("Flow Power (arb. units)") + plt.ylim(0, 0.5) + + plt.twinx() + + plt.plot(df.index, df["storage_content"], "k--", label="storage content") + plt.ylim(0, 3) + plt.legend(loc="center right") + plt.ylabel("Stored Energy (arb. units)") + + print(df) + + plt.show() + + +if __name__ == "__main__": + storage_level_constraint_example() diff --git a/examples/time_index_example/non_equidistant_time_step_example.py b/examples/time_index_example/non_equidistant_time_step_example.py index c03c7e570..8e8d47081 100644 --- a/examples/time_index_example/non_equidistant_time_step_example.py +++ b/examples/time_index_example/non_equidistant_time_step_example.py @@ -7,23 +7,35 @@ An example to show how non-equidistant time steps work. In addition to the comments in the simple example, note that: -* Time steps in the beginning are 15 minutes. -* Time steps in the end are hourly. -* In the middle, there is a very short demand peak of one minute. - This, however, does barely influence the storage contents. -* Storage losses are defined per hour. - * storage_fixed looses 1 energy unit per hour - * storage_relative looses 50 % of its contents per hour -* If possible, energy is transferred from storage with - relative losses to the one with fixed losses to minimise total - losses. +- Time steps in the beginning are 15 minutes. +- Time steps in the end are hourly. +- In the middle, there is a very short demand peak of one minute. This, however, + does barely influence the storage contents. +- Storage losses are defined per hour. + - storage_fixed looses 1 energy unit per hour + - storage_relative looses 50 % of its contents per hour +- If possible, energy is transferred from storage with relative losses to the + one with fixed losses to minimise total losses. + +Code +---- +Download source code: :download:`non_equidistant_time_step_example.py ` + +.. dropdown:: Click to display code + + .. literalinclude:: /../examples/time_index_example/non_equidistant_time_step_example.py + :language: python + :lines: 40- Installation requirements ------------------------- This example requires oemof.solph, install by: +.. code:: bash + pip install oemof.solph + """ import pandas as pd diff --git a/examples/time_index_example/simple_time_step_example.py b/examples/time_index_example/simple_time_step_example.py index e84cc4e66..7a0509872 100644 --- a/examples/time_index_example/simple_time_step_example.py +++ b/examples/time_index_example/simple_time_step_example.py @@ -6,22 +6,33 @@ A minimal example to show how time steps work. -* Flows are defined in time intervals, storage content at points in time. - Thus, there is one more value for storage contents then for the - flow values. -* Time intervals are named by the time at the beginning of that interval. - The quantity changes to the given value at the given point in time. -* The initial_storage_level of a GenericStorage is given - at the first time step. If the storage is balanced, - this is the same storage level as in the last time step. -* The nominal_value in Flows has to be interpreted in means of power: - We have nominal_value=0.5, but the maximum change of the storage content - of an ideal storage is 0.125. +* Flows are defined in time intervals, storage content at points in time. Thus, + there is one more value for storage contents then for the flow values. +* Time intervals are named by the time at the beginning of that interval. The + quantity changes to the given value at the given point in time. +* The initial_storage_level of a GenericStorage is given at the first time step. + If the storage is balanced, this is the same storage level as in the last time + step. +* The nominal_value in Flows has to be interpreted in means of power: We have + nominal_value=0.5, but the maximum change of the storage content of an ideal + storage is 0.125. + +Code +---- +Download source code: :download:`non_equidistant_time_step_example.py ` + +.. dropdown:: Click to display code + + .. literalinclude:: /../examples/time_index_example/simple_time_step_example.py + :language: python + :lines: 43- Installation requirements ------------------------- This example requires oemof.solph (v0.5.x), install by: +.. code:: bash + pip install oemof.solph[examples] diff --git a/examples/time_index_example/time_index_example.py b/examples/time_index_example/time_index_example.py deleted file mode 100644 index e84cc4e66..000000000 --- a/examples/time_index_example/time_index_example.py +++ /dev/null @@ -1,110 +0,0 @@ -# -*- coding: utf-8 -*- - -""" -General description -------------------- - -A minimal example to show how time steps work. - -* Flows are defined in time intervals, storage content at points in time. - Thus, there is one more value for storage contents then for the - flow values. -* Time intervals are named by the time at the beginning of that interval. - The quantity changes to the given value at the given point in time. -* The initial_storage_level of a GenericStorage is given - at the first time step. If the storage is balanced, - this is the same storage level as in the last time step. -* The nominal_value in Flows has to be interpreted in means of power: - We have nominal_value=0.5, but the maximum change of the storage content - of an ideal storage is 0.125. - -Installation requirements -------------------------- -This example requires oemof.solph (v0.5.x), install by: - - pip install oemof.solph[examples] - - -License -------- -`MIT license `_ -""" -import matplotlib.pyplot as plt - -from oemof import solph - - -def main(): - solver = "cbc" # 'glpk', 'gurobi',... - solver_verbose = False # show/hide solver output - - date_time_index = solph.create_time_index(2000, interval=0.25, number=8) - - energy_system = solph.EnergySystem( - timeindex=date_time_index, infer_last_interval=False - ) - - bus = solph.buses.Bus(label="bus") - source = solph.components.Source( - label="source", - outputs={ - bus: solph.flows.Flow( - nominal_value=2, - variable_costs=0.2, - max=[0, 0, 0, 0, 1, 0.25, 0.75, 1], - ) - }, - ) - storage = solph.components.GenericStorage( - label="storage", - inputs={bus: solph.flows.Flow()}, - outputs={bus: solph.flows.Flow()}, - nominal_storage_capacity=4, - initial_storage_level=0.5, - ) - sink = solph.components.Sink( - label="sink", - inputs={ - bus: solph.flows.Flow( - nominal_value=2, - variable_costs=0.1, - fix=[1, 1, 0.5, 0.5, 0, 0, 0, 0], - ) - }, - ) - - energy_system.add(bus, source, sink, storage) - model = solph.Model(energy_system) - model.solve(solver=solver, solve_kwargs={"tee": solver_verbose}) - - results = solph.processing.results(model) - - results_df = results[(storage, None)]["sequences"].copy() - results_df["storage_inflow"] = results[(bus, storage)]["sequences"]["flow"] - results_df["storage_outflow"] = results[(storage, bus)]["sequences"][ - "flow" - ] - - print(results_df) - - if plt is not None: - plt.plot( - results[(bus, storage)]["sequences"], - drawstyle="steps-post", - label="Storage inflow", - ) - plt.plot( - results[(storage, None)]["sequences"], label="Storage content" - ) - plt.plot( - results[(storage, bus)]["sequences"], - drawstyle="steps-post", - label="Storage outflow", - ) - - plt.legend(loc="lower left") - plt.show() - - -if __name__ == "__main__": - main() diff --git a/examples/tuple_as_labels/tuple_as_label.py b/examples/tuple_as_labels/tuple_as_label.py index 44fbcd79e..f079a0986 100644 --- a/examples/tuple_as_labels/tuple_as_label.py +++ b/examples/tuple_as_labels/tuple_as_label.py @@ -66,18 +66,30 @@ This a helpful adaption for automatic plots etc.. Afterwards you can use `format` to define your own custom string.: + >>> print('{0}+{1}-{2}'.format(pv_label.region, pv_label.tag2, pv_label.tag1)) region_1+pv-renewable_source -Data +Code ---- -basic_example.csv +Download source code: :download:`tuple_as_label.py ` +.. dropdown:: Click to display code + + .. literalinclude:: /../examples/tuple_as_labels/tuple_as_label.py + :language: python + :lines: 106- + +Data +---- +Download data: :download:`tuple_as_label.csv ` Installation requirements ------------------------- This example requires oemof.solph (v0.5.x), install by: +.. code:: bash + pip install oemof.solph[examples] diff --git a/examples/variable_chp/variable_chp.py b/examples/variable_chp/variable_chp.py index fb296c0c8..03c9f61ce 100644 --- a/examples/variable_chp/variable_chp.py +++ b/examples/variable_chp/variable_chp.py @@ -11,15 +11,33 @@ heat and power excess and therefore needs more natural gas. The bar plot just shows the difference in the usage of natural gas. +Code +---- +Download source code: :download:`variable_chp.py ` + +.. dropdown:: Click to display code + + .. literalinclude:: /../examples/variable_chp/variable_chp.py + :language: python + :lines: 53- + +Data +---- +Download data: :download:`variable_chp.csv ` + Installation requirements ------------------------- This example requires oemof.solph (v0.5.x), install by: +.. code:: bash + pip install oemof.solph[examples] Optional to see the i/o balance plot: +.. code:: bash + pip install git+https://github.com/oemof/oemof_visio.git License diff --git a/setup.py b/setup.py index 59d882f1e..500ec08c6 100644 --- a/setup.py +++ b/setup.py @@ -87,12 +87,14 @@ def read(*names, **kwargs): ], extras_require={ "dev": [ + "matplotlib", + "nbformat", "pytest", "sphinx", "sphinx_rtd_theme", - "nbformat", + "sphinx-copybutton", + "sphinx-design", "termcolor", - "matplotlib", ], "examples": ["matplotlib"], "dummy": ["oemof"],