diff --git a/.readthedocs.yaml b/.readthedocs.yaml index bd7141c26..89746f73f 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -11,6 +11,7 @@ sphinx: formats: [] python: install: - - requirements: docs/requirements.txt - method: pip path: . + extra_requirements: + - dev diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 52872fcff..e58cc4123 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,3 +1,5 @@ +.. _contribute_label: + ============ Contributing ============ @@ -45,23 +47,27 @@ To set up `oemof-solph` for local development: git clone git@github.com:oemof/oemof-solph.git -3. Create a branch for local development:: +3. Install oemof.solph in editable mode with dev dependencies:: + + pip install -e ./path/to/local/clone[dev] + +4. Create a branch for local development:: - git checkout -b name-of-your-bugfix-or-feature + `git checkout -b features/name-of-your-feature` or `git checkout -b fix/name-of-your-fix` Now you can make your changes locally. -4. When you're done making changes run all the checks and docs builder with `tox `_ one command:: +5. When you're done making changes run all the checks and docs builder with `tox `_ one command:: tox -5. Commit your changes and push your branch to GitHub:: +6. Commit your changes and push your branch to GitHub:: git add . git commit -m "Your detailed description of your changes." git push origin name-of-your-bugfix-or-feature -6. Submit a pull request through the GitHub website. +7. Submit a pull request through the GitHub website. Pull Request Guidelines ----------------------- @@ -80,7 +86,6 @@ For merging, you should: It will be slower though ... - Tests ----- @@ -105,7 +110,6 @@ Note, to combine the coverage data from all the tox environments run: PYTEST_ADDOPTS=--cov-append tox - Tips ---- diff --git a/docs/_files/ExtractionTurbine_range_of_operation.svg b/docs/_files/ExtractionTurbine_range_of_operation.svg index 360997f92..066644e51 100644 --- a/docs/_files/ExtractionTurbine_range_of_operation.svg +++ b/docs/_files/ExtractionTurbine_range_of_operation.svg @@ -1,20 +1,19 @@ + inkscape:version="1.3.2 (091e20e, 2023-11-25, custom)" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns="http://www.w3.org/2000/svg" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:dc="http://purl.org/dc/elements/1.1/"> + inkscape:current-layer="g989" + inkscape:showpageshadow="2" + inkscape:pagecheckerboard="0" + inkscape:deskcolor="#d1d1d1" + inkscape:document-units="mm" /> + id="linearGradient3253" + inkscape:swatch="solid"> @@ -269,66 +272,60 @@ transform="matrix(1.368217,0,0,1.368217,-26.324083,-31.862608)" id="g989"> + style="color:#000000;fill:#787878;-inkscape-stroke:none" + d="m 27.8125,61.853516 -0.03711,0.263671 16.742187,2.345704 0.03711,-0.261719 z" + id="path19168" /> + style="color:#000000;fill:#787878;-inkscape-stroke:none" + d="m 27.644531,68.742187 -0.03711,0.263672 11.908203,1.669922 0.03711,-0.263672 z" + id="path19170" /> + style="color:#000000;fill:#787878;-inkscape-stroke:none" + d="m 27.8125,75.800781 -0.03711,0.263672 6.560546,0.919922 0.03711,-0.263672 z" + id="path19194" /> + + + + + + + + + + style="color:#000000;fill:#787878;-inkscape-stroke:none" + d="m 27.810547,40.876953 -0.03711,0.261719 31.964844,4.482422 0.03711,-0.263672 z" + id="path1321" /> - P + style="font-size:8.46667px;line-height:1;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583" + d="m 24.602709,26.23144 q 0,0.409278 -0.144694,0.760677 -0.14056,0.347266 -0.396876,0.603581 -0.318327,0.318327 -0.752409,0.479558 -0.434082,0.157096 -1.095541,0.157096 h -0.818555 v 2.294435 h -0.818555 v -6.155699 h 1.670183 q 0.553972,0 0.938445,0.09508 0.384473,0.09095 0.682129,0.289389 0.3514,0.235644 0.541569,0.587044 0.194304,0.3514 0.194304,0.888835 z m -0.851628,0.02067 q 0,-0.318327 -0.111621,-0.553972 -0.111622,-0.235645 -0.338998,-0.384473 -0.198438,-0.128157 -0.454753,-0.181901 -0.252181,-0.05788 -0.640788,-0.05788 h -0.810287 v 2.4598 h 0.690398 q 0.496094,0 0.806152,-0.08682 0.310059,-0.09095 0.504363,-0.285254 0.194303,-0.198437 0.272851,-0.417546 0.08268,-0.219108 0.08268,-0.491959 z" + id="text1325" + aria-label="P" /> - Q - + . + style="font-size:8.46667px;line-height:1.25;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583" + aria-label="." /> - - + + + + + + + + + + + + + + + + + + - + + + + + + + + + + style="font-size:4.23333px;stroke-width:0.264583" /> + style="stroke-width:0.264583" /> + + + + + + + + + + style="color:#000000;fill:#787878;-inkscape-stroke:none" + d="m 27.84375,48.080078 -0.03711,0.263672 26.660156,3.736328 0.03711,-0.261719 z" + id="path1321-3" /> + style="color:#000000;fill:#787878;-inkscape-stroke:none" + d="m 27.759766,54.96875 -0.03711,0.263672 21.767578,3.052734 0.03711,-0.263672 z" + id="path1321-6" /> - + style="color:#000000;fill:#000000;stroke-linecap:round;stroke-linejoin:round;-inkscape-stroke:none" + d="m 27.818359,33.865234 a 0.18274239,0.18274239 0 0 0 -0.207031,0.154297 0.18274239,0.18274239 0 0 0 0.154297,0.207031 l 36.556641,5.283204 -36.664063,45.423828 a 0.18274239,0.18274239 0 0 0 0.02734,0.257812 0.18274239,0.18274239 0 0 0 0.255859,-0.02734 L 64.806641,39.488281 a 0.18274239,0.18274239 0 0 0 0.03906,-0.08789 0.18274239,0.18274239 0 0 0 -0.0078,-0.08203 0.18274239,0.18274239 0 0 0 -0.01172,-0.02344 0.18274239,0.18274239 0 0 0 -0.03906,-0.05273 0.18274239,0.18274239 0 0 0 -0.0078,-0.0098 0.18274239,0.18274239 0 0 0 -0.0039,0 0.18274239,0.18274239 0 0 0 -0.08398,-0.03906 z" + id="path1321-2" /> + + Operation range constrained by nominal value of input flow - + Backpressure linedefined by (2)outflow-relation-constraint - + + + + + Iso-input lines with slope βdefined by (1)input-outflow-constraint + style="font-size:4.1254px;line-height:1.25;-inkscape-font-specification:sans-serif;letter-spacing:0px;word-spacing:0px;stroke-width:0.193378" + aria-label="Iso-input lines with slope βdefined by (1)input-outflow-constraint"> + + + + + diff --git a/docs/_files/ExtractionTurbine_range_of_operation_darkmode.svg b/docs/_files/ExtractionTurbine_range_of_operation_darkmode.svg new file mode 100644 index 000000000..409f44f2b --- /dev/null +++ b/docs/_files/ExtractionTurbine_range_of_operation_darkmode.svg @@ -0,0 +1,589 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/_files/GenericCHP_darkmode.svg b/docs/_files/GenericCHP_darkmode.svg new file mode 100644 index 000000000..80c96b21f --- /dev/null +++ b/docs/_files/GenericCHP_darkmode.svg @@ -0,0 +1,490 @@ + + + + + + + + + + + + + + image/svg+xml + + + + + + + Heat extraction + + + + + + + + + 5% + 12.5% + 20% + HL,FG= 5% + HL,FG=20% + + Pmax,woDH + Pmin,woDH + Electrical power + + Heat extraction + Pmax,woDH + Pmin,woDH + Electrical power + + + + + + + Heat extraction + + HL,FG=20% + + Pmax,woDH + Pmin,woDH + Electrical power + + + + + + + + + CCET + BPT + mCHP + HL,FG= 5% + + diff --git a/docs/_files/oemof_solph_example_darkmode.svg b/docs/_files/oemof_solph_example_darkmode.svg new file mode 100644 index 000000000..5671673fb --- /dev/null +++ b/docs/_files/oemof_solph_example_darkmode.svg @@ -0,0 +1,1191 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Class + + + + + + + + + electricity 1 + + + + + + + chp plant + + + + + + + demand 1 + + + + + + + natural gas + + + + + + + natural gas + + + + + + + pv system + + + + + + + wind power plant + + + + + + + electricity 2 + + + + + + + demand 2 + + + + + + + transport 1 + + + + + + + transport 2 + + + + + + + + battery + + + + + + heat + + + + + + + heat demand + + + + + + + Bus + + + + + + + Source + + + + + + + Converter + + + + + + + + GenericStorage + + + + + + Sink + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/_logo/README.rst b/docs/_static/_logo/README.rst similarity index 89% rename from docs/_logo/README.rst rename to docs/_static/_logo/README.rst index 364282605..1624bff03 100644 --- a/docs/_logo/README.rst +++ b/docs/_static/_logo/README.rst @@ -1,7 +1,7 @@ oemof.solph Logo ================ -You are free to use or integrate the logo of oemof-solph in your projects. We +You are free to use or integrate the logo of oemof.solph in your projects. We recommend using these logos instead of the logos with editable font, since those might not display correctly, if e.g. a browser does not support the font used in the logo. diff --git a/docs/_logo/editable_fonts/logo_oemof_solph_COMPACT_editable_fonts.svg b/docs/_static/_logo/editable_fonts/logo_oemof_solph_COMPACT_editable_fonts.svg similarity index 100% rename from docs/_logo/editable_fonts/logo_oemof_solph_COMPACT_editable_fonts.svg rename to docs/_static/_logo/editable_fonts/logo_oemof_solph_COMPACT_editable_fonts.svg diff --git a/docs/_logo/editable_fonts/logo_oemof_solph_FULL_editable_fonts.svg b/docs/_static/_logo/editable_fonts/logo_oemof_solph_FULL_editable_fonts.svg similarity index 100% rename from docs/_logo/editable_fonts/logo_oemof_solph_FULL_editable_fonts.svg rename to docs/_static/_logo/editable_fonts/logo_oemof_solph_FULL_editable_fonts.svg diff --git a/docs/_logo/editable_fonts/logo_oemof_solph_ICON_editable_fonts.svg b/docs/_static/_logo/editable_fonts/logo_oemof_solph_ICON_editable_fonts.svg similarity index 100% rename from docs/_logo/editable_fonts/logo_oemof_solph_ICON_editable_fonts.svg rename to docs/_static/_logo/editable_fonts/logo_oemof_solph_ICON_editable_fonts.svg diff --git a/docs/_logo/editable_fonts/logo_oemof_solph_NOTEXT_editable_fonts.svg b/docs/_static/_logo/editable_fonts/logo_oemof_solph_NOTEXT_editable_fonts.svg similarity index 100% rename from docs/_logo/editable_fonts/logo_oemof_solph_NOTEXT_editable_fonts.svg rename to docs/_static/_logo/editable_fonts/logo_oemof_solph_NOTEXT_editable_fonts.svg diff --git a/docs/_logo/logo_oemof_solph_COMPACT.svg b/docs/_static/_logo/logo_oemof_solph_COMPACT.svg similarity index 100% rename from docs/_logo/logo_oemof_solph_COMPACT.svg rename to docs/_static/_logo/logo_oemof_solph_COMPACT.svg diff --git a/docs/_logo/logo_oemof_solph_COMPACT_bg.svg b/docs/_static/_logo/logo_oemof_solph_COMPACT_darkmode.svg similarity index 84% rename from docs/_logo/logo_oemof_solph_COMPACT_bg.svg rename to docs/_static/_logo/logo_oemof_solph_COMPACT_darkmode.svg index 7efa5ed73..447232747 100644 --- a/docs/_logo/logo_oemof_solph_COMPACT_bg.svg +++ b/docs/_static/_logo/logo_oemof_solph_COMPACT_darkmode.svg @@ -4,14 +4,13 @@ id="svg2" height="264.60095" width="750.34601" - sodipodi:docname="logo_oemof_solph_COMPACT_bg.svg" - inkscape:version="1.1.1 (3bf5ae0d25, 2021-09-20)" + sodipodi:docname="logo_oemof_solph_COMPACT_darkmode.svg" + inkscape:version="1.4 (86a8ad7, 2024-10-11)" inkscape:export-filename="/home/uwe/extra/chiba/oemof/logos_icons_new/solph/logo_oemof_solph_big_editable_font_blue.png" inkscape:export-xdpi="300" inkscape:export-ydpi="300" xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" - xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://www.w3.org/2000/svg" xmlns:svg="http://www.w3.org/2000/svg" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" @@ -27,51 +26,25 @@ inkscape:pageopacity="0" inkscape:pageshadow="2" inkscape:window-width="1920" - inkscape:window-height="1043" + inkscape:window-height="1001" id="namedview45" showgrid="false" fit-margin-top="0" fit-margin-left="0" fit-margin-right="0" fit-margin-bottom="0" - inkscape:zoom="1.2898011" - inkscape:cx="375.25166" - inkscape:cy="131.80327" - inkscape:window-x="0" - inkscape:window-y="0" + inkscape:zoom="0.7778422" + inkscape:cx="386.32514" + inkscape:cy="80.350487" + inkscape:window-x="-9" + inkscape:window-y="-9" inkscape:window-maximized="1" - inkscape:current-layer="svg2" - inkscape:pagecheckerboard="0" /> + inkscape:current-layer="g869" + inkscape:pagecheckerboard="0" + inkscape:showpageshadow="2" + inkscape:deskcolor="#d1d1d1" /> - - - - - - - + id="defs4" /> @@ -83,13 +56,6 @@ - + style="line-height:0%;letter-spacing:0px;word-spacing:0px;fill:#84a7bf;fill-opacity:0.80392158"> + style="line-height:0%;letter-spacing:0px;word-spacing:0px;display:inline;fill:#e1e1e1;fill-opacity:1"> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/_logo/logo_oemof_solph_ICON.svg b/docs/_static/_logo/logo_oemof_solph_ICON.svg similarity index 100% rename from docs/_logo/logo_oemof_solph_ICON.svg rename to docs/_static/_logo/logo_oemof_solph_ICON.svg diff --git a/docs/_static/_logo/logo_oemof_solph_MINI.svg b/docs/_static/_logo/logo_oemof_solph_MINI.svg new file mode 100644 index 000000000..35bbd0cee --- /dev/null +++ b/docs/_static/_logo/logo_oemof_solph_MINI.svg @@ -0,0 +1,267 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + diff --git a/docs/_logo/logo_oemof_solph_NOTEXT.svg b/docs/_static/_logo/logo_oemof_solph_NOTEXT.svg similarity index 100% rename from docs/_logo/logo_oemof_solph_NOTEXT.svg rename to docs/_static/_logo/logo_oemof_solph_NOTEXT.svg diff --git a/docs/_static/_logo/logo_oemof_solph_NOTEXT_darkmode.svg b/docs/_static/_logo/logo_oemof_solph_NOTEXT_darkmode.svg new file mode 100644 index 000000000..4d5d77bb1 --- /dev/null +++ b/docs/_static/_logo/logo_oemof_solph_NOTEXT_darkmode.svg @@ -0,0 +1,251 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css new file mode 100644 index 000000000..f45c31dfa --- /dev/null +++ b/docs/_static/css/custom.css @@ -0,0 +1,12 @@ +.tight-table td { + white-space: normal !important; +} + +article p { + text-align: justify; +} + +figure figcaption p { + text-align: center; + font-weight: bold; +} diff --git a/docs/_static/js/custom.js b/docs/_static/js/custom.js new file mode 100644 index 000000000..5db6dfeff --- /dev/null +++ b/docs/_static/js/custom.js @@ -0,0 +1,20 @@ +function removeAnnouncementBanner() { + var banner = document.getElementsByClassName("announcement") + banner[0].remove() +}; + + +window.addEventListener('load', async () => { + const elmnt = document.querySelector('div[oemof-announcement]') + const response = await fetch(elmnt.getAttribute('oemof-announcement')) + if (response.status === 200) { + elmnt.innerHTML = ( + await response.text() + ) + if (elmnt.innerHTML.length === 0) { + removeAnnouncementBanner() + } + } else if (response.status === 404) { + removeAnnouncementBanner() + } +}) \ No newline at end of file diff --git a/docs/advanced_tutorials.rst b/docs/advanced_tutorials.rst new file mode 100644 index 000000000..29181f411 --- /dev/null +++ b/docs/advanced_tutorials.rst @@ -0,0 +1,43 @@ +.. _advanced_tutorials_label: + +~~~~~~~~~~~~~~~~~~ +Advanced Tutorials +~~~~~~~~~~~~~~~~~~ +We provide more advanced tutorials for you to better understand how to work +with more complex systems in oemof. + +A short description of the first advanced tutoial. + +A short description of the second advanced tutorial. + +If you have any questions, ideas for other tutorials or feedback, please reach +out to us. We are looking forward to hearing from you! + +.. grid:: 2 + :gutter: 1 + + .. grid-item-card:: Advanced Tutorial - 1 + :link: advanced_tutorial_1_label + :link-type: ref + + .. image:: /_static/_logo/logo_oemof_solph_FULL.svg + :class: only-light + + .. image:: /_static/_logo/logo_oemof_solph_FULL_darkmode.svg + :class: only-dark + + Coming soon! + + .. grid-item-card:: Advanced Tutorial - 2 + :link: advanced_tutorial_2_label + :link-type: ref + + Coming soon! + +.. toctree:: + :maxdepth: 1 + :glob: + :hidden: + + advanced_tutorials/advanced_tutorial_1.rst + advanced_tutorials/advanced_tutorial_2.rst \ No newline at end of file diff --git a/docs/advanced_tutorials/advanced_tutorial_1.rst b/docs/advanced_tutorials/advanced_tutorial_1.rst new file mode 100644 index 000000000..a1980681c --- /dev/null +++ b/docs/advanced_tutorials/advanced_tutorial_1.rst @@ -0,0 +1,6 @@ +.. _advanced_tutorial_1_label: + +Advanced Tutorial - 1 +--------------------- + +The first advanced tutorial for oemof.solph will be avaialble here \ No newline at end of file diff --git a/docs/advanced_tutorials/advanced_tutorial_2.rst b/docs/advanced_tutorials/advanced_tutorial_2.rst new file mode 100644 index 000000000..e4ff2ba05 --- /dev/null +++ b/docs/advanced_tutorials/advanced_tutorial_2.rst @@ -0,0 +1,6 @@ +.. _advanced_tutorial_2_label: + +Advanced Tutorial - 2 +--------------------- + +The second advanced tutorial for oemof.solph will be avaialble here \ No newline at end of file diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 000000000..5f7d4bafa --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,12 @@ +~~~~~~~~~~~~~~~~~ +API Documentation +~~~~~~~~~~~~~~~~~ + +The API documentation provides information on the different modules, classes +and methods available in oemof.solph. + +.. toctree:: + :maxdepth: 1 + :glob: + + reference/* \ No newline at end of file diff --git a/docs/basic_concepts.rst b/docs/basic_concepts.rst new file mode 100644 index 000000000..00baa6d6d --- /dev/null +++ b/docs/basic_concepts.rst @@ -0,0 +1,65 @@ +.. _basic_concepts_label: + +~~~~~~~~~~~~~~ +Basic Concepts +~~~~~~~~~~~~~~ + +The following sections give a detailed overview on the basic concepts of +oemof.solph. This includes all important components like the energy system, +buses and flows as well as the basic components. + +.. toctree:: + :maxdepth: 1 + :glob: + :hidden: + + basic_concepts/energy_system.rst + basic_concepts/buses.rst + basic_concepts/flows.rst + basic_concepts/components.rst + +.. grid:: 2 + :gutter: 1 + + .. grid-item-card:: Energy System + :link: basic_concepts_energy_system_label + :link-type: ref + + .. image:: /_static/_logo/logo_oemof_solph_NOTEXT.svg + :class: only-light + + .. image:: /_static/_logo/logo_oemof_solph_NOTEXT_darkmode.svg + :class: only-dark + + .. grid-item-card:: Buses + :link: basic_concepts_buses_label + :link-type: ref + + .. image:: /_static/_logo/logo_oemof_solph_NOTEXT.svg + :class: only-light + + .. image:: /_static/_logo/logo_oemof_solph_NOTEXT_darkmode.svg + :class: only-dark + +.. grid:: 2 + :gutter: 1 + + .. grid-item-card:: Flows + :link: basic_concepts_flows_label + :link-type: ref + + .. image:: /_static/_logo/logo_oemof_solph_NOTEXT.svg + :class: only-light + + .. image:: /_static/_logo/logo_oemof_solph_NOTEXT_darkmode.svg + :class: only-dark + + .. grid-item-card:: Components + :link: basic_concepts_components_label + :link-type: ref + + .. image:: /_static/_logo/logo_oemof_solph_NOTEXT.svg + :class: only-light + + .. image:: /_static/_logo/logo_oemof_solph_NOTEXT_darkmode.svg + :class: only-dark diff --git a/docs/basic_concepts/buses.rst b/docs/basic_concepts/buses.rst new file mode 100644 index 000000000..408f6c5da --- /dev/null +++ b/docs/basic_concepts/buses.rst @@ -0,0 +1,7 @@ +.. _basic_concepts_buses_label: + +~~~~~ +Buses +~~~~~ + +Here could a nice and short explanation of oemof.solphs buses. diff --git a/docs/basic_concepts/components.rst b/docs/basic_concepts/components.rst new file mode 100644 index 000000000..1c2a63a5c --- /dev/null +++ b/docs/basic_concepts/components.rst @@ -0,0 +1,8 @@ +.. _basic_concepts_components_label: + +~~~~~~~~~~ +Components +~~~~~~~~~~ + +Here could a nice and short explanation of oemof.solphs components like sinks +and sources as well as converters and storages. diff --git a/docs/basic_concepts/energy_system.rst b/docs/basic_concepts/energy_system.rst new file mode 100644 index 000000000..97f222c6e --- /dev/null +++ b/docs/basic_concepts/energy_system.rst @@ -0,0 +1,7 @@ +.. _basic_concepts_energy_system_label: + +~~~~~~~~~~~~~ +Energy System +~~~~~~~~~~~~~ + +Here could a nice and short explanation of oemof.solphs energy systems. diff --git a/docs/basic_concepts/flows.rst b/docs/basic_concepts/flows.rst new file mode 100644 index 000000000..c7d83259f --- /dev/null +++ b/docs/basic_concepts/flows.rst @@ -0,0 +1,7 @@ +.. _basic_concepts_flows_label: + +~~~~~ +Flows +~~~~~ + +Here could a nice and short explanation of oemof.solphs flows. diff --git a/docs/changelog.rst b/docs/changelog.rst index bb1a07f3f..65b7d2aed 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -3,12 +3,6 @@ Changelog These are new features and improvements of note in each release -.. contents:: `Releases` - :depth: 1 - :local: - :backlinks: top - - .. include:: whatsnew/v0-6-0.rst .. include:: whatsnew/v0-5-6.rst .. include:: whatsnew/v0-5-5.rst diff --git a/docs/conf.py b/docs/conf.py index e6b25a295..1cfd702c4 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -2,12 +2,11 @@ import os import sys +import oemof.solph import matplotlib from sphinx.ext.autodoc import between -from oemof.solph import __version__ - matplotlib.use("agg") sys.path.append(os.path.join(os.path.dirname(__file__), "..", "examples")) @@ -20,6 +19,11 @@ def setup(app): return app +# -- General configuration ------------------------------------------------ + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. extensions = [ "sphinx.ext.autodoc", "sphinx.ext.autosummary", @@ -33,41 +37,117 @@ def setup(app): "sphinx_copybutton", "sphinx_design", ] -source_suffix = ".rst" -master_doc = "index" + +# landing page +# master_doc = 'contents' +# names, years, etc project = "oemof.solph" -year = "2014-2023" -author = "oemof-developer-group" +year = "2024" +author = "oemof developer group" copyright = "{0}, {1}".format(year, author) -version = release = __version__ -pygments_style = "trac" -templates_path = ["."] +# The short X.Y version. +version = oemof.solph.__version__.split(" ")[0] +# The full version, including alpha/beta/rc tags. +release = oemof.solph.__version__ + +# The suffix of source filenames. +source_suffix = ".rst" +# folder for templates +templates_path = ["_templates"] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ["_build"] + +# The name of the Pygments (syntax highlighting) style to use. +# pygments_style = "some" +# pygments_dark_style = "someother" + +# show all class members +# numpydoc_show_class_members = False + +# place for bibtex references +bibtex_bibfiles = ["references.bib"] + +# links to github +github_repo_url = "https://github.com/oemof/oemof-solph/" extlinks = { - "issue": ("https://github.com/oemof/oemof-solph/issues/%s", "#%s"), - "pr": ("https://github.com/oemof/oemof-solph/pull/%s", "PR #%s"), + "issue": (f"{github_repo_url}/issues/%s", "#%s"), # noqa: WPS323 + "pr": (f"{github_repo_url}/pull/%s", "PR #%s"), # noqa: WPS323 + "commit": (f"{github_repo_url}/commit/%s", "%s"), # noqa: WPS323 } -# on_rtd is whether we are on readthedocs.org -on_rtd = os.environ.get("READTHEDOCS", None) == "True" -if not on_rtd: # only set the theme if we're building docs locally - html_theme = "sphinx_rtd_theme" +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. +html_theme = "furo" + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". + +# A shorter title for the navigation bar. Default is the same as html_title. +html_short_title = "%s-%s" % (project, version) + +# Some more stuff html_use_smartypants = True html_last_updated_fmt = "%b %d, %Y" html_split_index = False + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +# html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ["_static"] +html_css_files = [ + "css/custom.css", +] +# html_additional_pages = { +# "index": "index.html" +# } + html_sidebars = { - "**": ["searchbox.html", "globaltoc.html", "sourcelink.html"], + "**": [ + "sidebar/brand.html", + "sidebar/search.html", + "sidebar/scroll-start.html", + "sidebar/navigation.html", + "sidebar/ethical-ads.html", + "sidebar/scroll-end.html", + "sidebar/variant-selector.html", + ], } -html_short_title = "%s-%s" % (project, version) -html_logo = "./_logo/logo_oemof_solph_COMPACT_bg.svg" + +html_theme_options = { + "light_logo": "./_logo/logo_oemof_solph_COMPACT.svg", + "dark_logo": "./_logo/logo_oemof_solph_COMPACT_darkmode.svg", + "announcement": """ +
+ """, +} + +html_js_files = [ + "js/custom.js", +] + + +html_favicon = "./_static/_logo/logo_oemof_solph_ICON.svg" napoleon_use_ivar = True napoleon_use_rtype = False napoleon_use_param = False -nitpicky = False -exclude_patterns = ["_build", "whatsnew/*"] +# copybutton configuration +copybutton_prompt_text = r">>> |\.\.\. " +copybutton_prompt_is_regexp = True + +# Output file base name for HTML help builder. +htmlhelp_basename = "oemof.solph_doc" linkcheck_ignore = [ r"https://requires.io/.*", diff --git a/docs/examples/basic_example.rst b/docs/examples/basic_example.rst index abcd5e7c2..b7af0f69f 100644 --- a/docs/examples/basic_example.rst +++ b/docs/examples/basic_example.rst @@ -1,7 +1,7 @@ Basic example ------------- -Using standard oemof-solph components +Using standard oemof.solph components ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: basic_example.basic_example diff --git a/docs/index.rst b/docs/index.rst index 7e9bc0820..2087023ae 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,28 +1,38 @@ -.. oemof documentation master file, created by - sphinx-quickstart on Thu Dec 18 16:57:35 2014. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -======================================= -Welcome to oemof.solph's documentation! -======================================= - -.. toctree:: - :maxdepth: 3 - - readme - usage - reference/index - examples/index - contributing - authors - changelog - _logo/README.rst - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` +.. include:: introduction.rst +.. toctree:: + :maxdepth: 2 + :hidden: + + introduction + +.. toctree:: + :maxdepth: 2 + :caption: User Guide + :hidden: + + installation + introductory_tutorials + advanced_tutorials + showcase_examples + support + +.. toctree:: + :maxdepth: 2 + :caption: Documentation + :hidden: + + basic_concepts + advanced_concepts + api + changelog + zliterature + +.. toctree:: + :maxdepth: 2 + :caption: Contribute + :hidden: + + contributing + community + authors diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 000000000..49352b955 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,151 @@ +.. _installation_and_setup_label: + +###################### +Installation and setup +###################### + +Following you find guidelines for the installation process for various +operating systems. oemof.solph is a Python package, thus it requires you to +have Python 3 installed. On top of that, you need a solver to use oemof.solph. + +There are several solvers that can work with oemof.solph, both open source and +commercial. Two open source solvers are widely used (HiGHS, CBC and GLPK), but +oemof.solph suggests CBC (Coin-or branch and cut). It may be useful to compare +results of different solvers to see which performs best. Other commercial +solvers, like Gurobi or Cplex, are also options. Have a look at the +`pyomo docs `__ +to learn about which solvers are supported. + +.. tab-set:: + + .. tab-item:: Using conda (all OS) + + You can download a lightweight and open source variant of conda: + "miniforge3". + + 1. Download latest `miniforge3 `__ + for Python 3.x (64 or 32 bit). + 2. Install miniforge3 + 3. Open "miniforge prompt" to manage your virtual environments. You can + create a new environment and acivate it by + + .. code-block:: console + + conda create -n oemof-solph-env python=3.11 + activate oemof-solph-env + + 4. Install a solver, e.g. CBC + + .. code-block:: console + + conda install -c conda-forge coincbc + + 5. Only AFTER you have installed the solver via conda, use pip to install + oemof.solph: + + .. code-block:: console + + pip install oemof.solph + + .. tab-item:: Linux + + **Installing Python 3** + + Most Linux distributions will have Python 3 in their repository. Use the + specific software management to install it, if it is not yet installed. + If you are using Ubuntu/Debian try executing the following code in your + terminal: + + .. code:: console + + sudo apt-get install python3 + + You can also download different versions of Python via + https://www.python.org/downloads/. + + **Having Python 3 installed** + + We recommend installing oemof.solph within a virtual Python environment + and not into the base, system-wide Python installation. On Linux you can + use virtualenv to do so. + + 1. Install virtualenv using the package management of your Linux + distribution, pip install or install it from source + (`see virtualenv documentation `_) + 2. Open terminal to create and activate a virtual environment by typing: + + .. code-block:: console + + virtualenv -p /usr/bin/python3 your_env_name + source your_env_name/bin/activate + + 3. In terminal type: :code:`pip install oemof.solph` + + Warning: If you have an older version of virtualenv you should update pip + :code:`pip install --upgrade pip`. + + **Solver installation** + + To install the solvers have a look at the package repository of your + Linux distribution or search for precompiled packages. GLPK and CBC ares + available at Debian, Feodora, Ubuntu and others. + + .. tab-item:: Windows solver + + We recommend using conda for the python installation. If you want to + install the solver externally (not via conda), you can follow these + steps: + + 1. Download `CBC `_ or + `GLPK (64/32 bit) `_ + 2. Unpack CBC/GLPK to any folder (e.g. C:/Users/Somebody/my_programs) + 3. Add the path of the executable files of both solvers to the PATH variable using `this tutorial `_ + 4. Restart Windows + + .. tab-item:: OSX solver + + We recommend using conda for the python installation. If you want to + install the solver externally (not via conda), you can follow these + instructions: + + - CBC-solver: https://projects.coin-or.org/Cbc + - GLPK-solver: http://arnab-deka.com/posts/2010/02/installing-glpk-on-a-mac/ + + If you install the CBC solver via brew (highly recommended), it should + work without additional configuration. + + .. tab-item:: Developer version + + If you would like to get access to not yet released features or features + under development you can install the developer version. The steps are + similar to the steps here, but INSTEAD of installing oemof.solph using + + .. code-block:: console + + pip install oemof.solph + + follow the instructions on :ref:`this page `. + +Installation test +----------------- +Test the installation and the installed solver by running the installation test +in your virtual environment: + +.. code:: console + + oemof_installation_test + +If the installation was successful, you will receive something like this: + +.. code:: console + + ********* + Solver installed with oemof: + glpk: working + cplex: not working + cbc: working + gurobi: not working + ********* + oemof.solph successfully installed. + +as an output. diff --git a/docs/introduction.rst b/docs/introduction.rst new file mode 100644 index 000000000..4af6de16c --- /dev/null +++ b/docs/introduction.rst @@ -0,0 +1,110 @@ +=========== +oemof.solph +=========== + +.. image:: /_static/_logo/logo_oemof_solph_FULL.svg + :align: center + :class: only-light + + +.. image:: /_static/_logo/logo_oemof_solph_FULL_darkmode.svg + :align: center + :class: only-dark + +Introduction +============ +`oemof.solph` is a model generator for energy system modelling and Optimisation +(LP/MILP). The oemof.solph package is part of the +`open energy modelling framework (oemof) `_. +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 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. + +Contribution is already possible on a low level by simply fixing typos in +oemof's documentation or rephrasing sections which are unclear. +If you want to support us that way please fork the oemof-solph repository to your own +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. + +Keep in touch! - You can become a watcher at our `github site `_, +but this will bring you quite a few mails and might be more interesting for developers. +If you just want to get the latest news, like when is the next oemof meeting, +you can follow our news-blog at `oemof.org `_. + +Quick Installation +================== + +For oemof.solph you need a solver on top of the software itself. Complete +installation instructions can be found +:ref:`here `. For example, you can install +oemof.solph together with the CBC solver in a conda environment: + +.. code:: console + + (venv) conda install -c conda-forge coincbc + (venv) pip install oemof.solph + +Contributing +============ + +A warm welcome to all who want to join the developers and contribute to +oemof.solph. Information on the details and how to approach us can be found +:ref:`in this section `. + +Cite oemof.solph +================ + +For explicitly citing oemof.solph, you might want to refer to +`DOI:10.1016/j.simpa.2020.100028 `_, +which gives an overview over the capabilities of oemof.solph. +The core ideas of oemof as a whole are described in +`DOI:10.1016/j.esr.2018.07.001 `_ +(preprint at `arXiv:1808.0807 `_). +To allow citing specific versions, we use the zenodo project to get a DOI for +each version. + +Example Applications +==================== +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 in these sections: + +- :ref:`introductory tutorials ` +- :ref:`advanced tutorials ` +- :ref:`showcase applications ` + +You are welcome to contribute your own examples via a +`pull request `_ +or by e-mailing us (see `here `_ for contact +information). + +License +======= + +Copyright (c) oemof developer group + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/docs/introductory_tutorials.rst b/docs/introductory_tutorials.rst new file mode 100644 index 000000000..6ac9c931c --- /dev/null +++ b/docs/introductory_tutorials.rst @@ -0,0 +1,68 @@ +.. _introductory_tutorials_label: + +Basic Examples +~~~~~~~~~~~~~~~~~~~~~~ + +In this section we will introduce how to create your first simple oemof.solph models. The +subsections are step by step walkthroughs for typical energy system modelling applications. + +If you want to learn more about the basic building blocks, you should have a look at the +:ref:`Documentation section ` after the first steps. If +you have any questions please reach out to the +:ref:`oemof community `. + +.. toctree:: + :maxdepth: 1 + :hidden: + + introductory_tutorials/district_heating_supply.rst + introductory_tutorials/home_pv_battery_system.rst + introductory_tutorials/tutorial_3.rst + introductory_tutorials/tutorial_4.rst + + +.. grid:: 2 + :gutter: 1 + + .. grid-item-card:: Tutorial 1 + :link: district_heating_portfolio_optimization_label + :link-type: ref + + .. image:: /_files/example_network.svg + :class: only-light + + .. image:: /_files/example_network.svg + :class: only-dark + + .. grid-item-card:: Tutorial 2 + :link: home_pv_battery_system_label + :link-type: ref + + .. image:: /_files/example_network.svg + :class: only-light + + .. image:: /_files/example_network.svg + :class: only-dark + +.. grid:: 2 + :gutter: 1 + + .. grid-item-card:: Tutorial 3 + :link: tutorial_3_label + :link-type: ref + + .. image:: /_files/example_network.svg + :class: only-light + + .. image:: /_files/example_network.svg + :class: only-dark + + .. grid-item-card:: Tutorial 4 + :link: tutorial_4_label + :link-type: ref + + .. image:: /_files/example_network.svg + :class: only-light + + .. image:: /_files/example_network.svg + :class: only-dark diff --git a/docs/introductory_tutorials/district_heating_supply.rst b/docs/introductory_tutorials/district_heating_supply.rst new file mode 100644 index 000000000..8e57f5b23 --- /dev/null +++ b/docs/introductory_tutorials/district_heating_supply.rst @@ -0,0 +1,129 @@ +.. _district_heating_portfolio_optimization_label: + +District heating portfolio optimization +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In this tutorial we will optimize the portfolio of an existing heat supply. + +The tutorial is set up in 4 different steps + +- The existing system delivering heat with a gas boiler +- The optimization of a heat pump capacity utilizing waste heat from datacenter + with heat storage (ad-hoc dimensioning, ~2 days of maximum heat demand) +- Introduce minimal load with converter concept (just minimal load) + +.. figure:: /_files/example_network.svg + :align: center + :alt: Structure of the heating supplier's portfolio + :figclass: only-light + + Structure of the heating supplier's portfolio + +.. figure:: /_files/example_network_darkmode.svg + :align: center + :alt: Structure of the heating supplier's portfolio + :figclass: only-dark + + Structure of the heating supplier's portfolio + +Step 1: Status-Quo system +------------------------- + +1. Which information is required? (no code) + + - heat demand time series + - gas price + - gas boiler capactiy and technical specifications + +2. Import dependencies + setup EnergySystem (code snippet) + +.. literalinclude:: /../tutorials/introductory/district_heating_supply.py + :language: python + :start-after: [sec_1_start] + :end-before: [sec_1_end] + +3. Description of which buses are required + setup? (code snippet) + +.. literalinclude:: /../tutorials/introductory/district_heating_supply.py + :language: python + :start-after: [sec_2_start] + :end-before: [sec_2_end] + +4. Description which sinks and sources are required, load the necessary data, setup (code snippet) + +.. literalinclude:: /../tutorials/introductory/district_heating_supply.py + :language: python + :start-after: [sec_3_start] + :end-before: [sec_3_end] + +5. Converter setup (gas boiler), how to connect buses, variable costs, capacity (code snippet) + +.. literalinclude:: /../tutorials/introductory/district_heating_supply.py + :language: python + :start-after: [sec_4_start] + :end-before: [sec_4_end] + +6. "Optimization" of dispatch, has to follow load (code snippet) + +.. literalinclude:: /../tutorials/introductory/district_heating_supply.py + :language: python + :start-after: [sec_5_start] + :end-before: [sec_5_end] + +7. Some results, LCOH, CO2 emissions (how to calculate and resulting numbers), + dispatch plot(s). Include the plots in the page here!! + +.. dropdown:: Click to show plotting code + + .. literalinclude:: /../tutorials/introductory/district_heating_supply.py + :language: python + :start-after: [sec_6_start] + :end-before: [sec_6_end] + +.. figure:: /_files/example_network.svg + :align: center + :alt: System dispatch of heating system with gas boiler + :figclass: only-light + + System dispatch + +.. figure:: /_files/example_network_darkmode.svg + :align: center + :alt: System dispatch of heating system with gas boiler + :figclass: only-dark + + System dispatch + +Step 2: Plan capacity of heat pump and heat storage +--------------------------------------------------- + +.. dropdown:: See the complete code + + .. literalinclude:: /../tutorials/introductory/district_heating_supply.py + :language: python + :start-after: [sec_6_start] + :end-before: [sec_6_end] + +1. What information is required on the new components? (data, no code, include waste heat time series) + +2. Add new buses (electricity, waste heat) + +3. Add waste heat source and electricity source + +4. Add heat storage + +5. Add heat pump + +6. Run model and analyze results + +Step 3: Introduce a minimal load for the converters +--------------------------------------------------- + +1. Modify the converters, remaining parts are identical. + +.. tip:: + + What if minimum demand cannot be supplied? Add a slack source for the heat + demand. + +2. Run optimization, get results, what is the difference to before? diff --git a/docs/introductory_tutorials/home_pv_battery_system.rst b/docs/introductory_tutorials/home_pv_battery_system.rst new file mode 100644 index 000000000..565d4770b --- /dev/null +++ b/docs/introductory_tutorials/home_pv_battery_system.rst @@ -0,0 +1,49 @@ +.. _home_pv_battery_system_label: + +Home PV installation with battery storage +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Let's start with a more or less blank scenario: Imagine you want to set up a PV +plant on top of your single family house. How would you find out which system +fits best and why? Here are some possible points to think about: + +.. figure:: /_files/example_network.svg + :align: center + :alt: Structure of the heating supplier's portfolio + :figclass: only-light + + Structure of the heating supplier's portfolio + +.. figure:: /_files/example_network_darkmode.svg + :align: center + :alt: Structure of the heating supplier's portfolio + :figclass: only-dark + + Structure of the heating supplier's portfolio + +Step 1: PV installation without storage +--------------------------------------- + +1. Which information is required? (no code) + + - heat demand time series + - gas price + - gas boiler capactiy and technical specifications + +2. Import dependencies + setup EnergySystem (code snippet) + +.. literalinclude:: /../tutorials/introductory/pv_battery_system_1.py + :language: python + :start-after: [sec_1_start] + :end-before: [sec_1_end] + +:download:`pv_battery_system_1.py ` + +.. attention:: + + Hier musst du aufmerksam sein! + + +.. dropdown:: Click to expand + + Das ist versteckt diff --git a/docs/introductory_tutorials/tutorial_3.rst b/docs/introductory_tutorials/tutorial_3.rst new file mode 100644 index 000000000..8817a0507 --- /dev/null +++ b/docs/introductory_tutorials/tutorial_3.rst @@ -0,0 +1,6 @@ +.. _tutorial_3_label: + +Third tutorial +~~~~~~~~~~~~~~~~~~~~~~ + +This page will display the third basic tutorial. diff --git a/docs/introductory_tutorials/tutorial_4.rst b/docs/introductory_tutorials/tutorial_4.rst new file mode 100644 index 000000000..a17fcf009 --- /dev/null +++ b/docs/introductory_tutorials/tutorial_4.rst @@ -0,0 +1,6 @@ +.. _tutorial_4_label: + +Fourth tutorial +~~~~~~~~~~~~~~~~~~~~~~ + +This page will display the fourth basic tutorial. diff --git a/docs/readme.rst b/docs/readme.rst deleted file mode 100644 index 72a335581..000000000 --- a/docs/readme.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../README.rst diff --git a/docs/reference/index.rst b/docs/reference/index.rst deleted file mode 100644 index f4bdf3a8e..000000000 --- a/docs/reference/index.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. _api_reference_label: - -API Reference -============= - -.. toctree:: - :glob: - - oemof.solph* diff --git a/docs/requirements.txt b/docs/requirements.txt deleted file mode 100644 index 5937633e1..000000000 --- a/docs/requirements.txt +++ /dev/null @@ -1,14 +0,0 @@ -sphinx>=1.3, < 7 -sphinx-rtd-theme -sphinx-copybutton -sphinx-design -setuptools -matplotlib -blinker -dill -numpy -pandas >= 1.5.3 -pyomo >= 6.6.0, < 7.0 -networkx -oemof.tools >= 0.4.2 -oemof.network >= 0.5.0a1 diff --git a/docs/showcase_examples.rst b/docs/showcase_examples.rst new file mode 100644 index 000000000..b46908f3a --- /dev/null +++ b/docs/showcase_examples.rst @@ -0,0 +1,37 @@ +.. _showcase_examples_label: + +~~~~~~~~~~~~~~~~~~~~ +Showcases +~~~~~~~~~~~~~~~~~~~~ + +On this page we collect showcases applications of oemof.solph. If you want to +add your example here, please open an issue on GitHub and let us know. The +source code of the application should be accessible freely, so other users can +learn from your project. + + +.. card:: + + **Example showcase how to build an example** + ^^^ + + .. image:: /_static/_logo/logo_oemof_solph_COMPACT.svg + :align: center + :alt: Example Caption + :class: only-light + :target: https://github.com/oemof/oemof-solph + + .. image:: /_static/_logo/logo_oemof_solph_COMPACT_darkmode.svg + :align: center + :alt: Example Caption + :class: only-dark + :target: https://github.com/oemof/oemof-solph + + Your description of your project should be here + + +++ + Title: example + + Authors: oemof developer 1, oemof developer 2 + + Reference: :cite:`oemof` diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt deleted file mode 100644 index f95eb78d8..000000000 --- a/docs/spelling_wordlist.txt +++ /dev/null @@ -1,11 +0,0 @@ -builtin -builtins -classmethod -staticmethod -classmethods -staticmethods -args -kwargs -callstack -Changelog -Indices diff --git a/docs/support.rst b/docs/support.rst new file mode 100644 index 000000000..ec8de042b --- /dev/null +++ b/docs/support.rst @@ -0,0 +1,26 @@ +.. _support_label: + +########### +Get support +########### + +User forum +========== + +The `openmod forum `__ is the first resource for +your questions on using oemof.solph. Make sure to use the :code:`oemof-solph` +tag for your submission, so the community is notified of your question. + +Get online support +================== + +Furthermore, there is a monthly online meeting, which you can join without +registration. It takes place on every second Monday of a month at HH:MM CE(S)T. +Just join the `jit.si meeting room `__. + +Join the user meetings +====================== + +In person user meetings take place once per year. Date and location are +announced via GitHub: +`https://github.com/oemof/oemof/wiki `__. diff --git a/docs/usage.rst b/docs/usage.rst index bae69f778..b95887d26 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -8,18 +8,12 @@ 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:`examples_label` section. -This User's guide provides a user-friendly introduction into oemof-solph, +This User's guide provides a user-friendly introduction into oemof.solph, which includes small examples and nice illustrations. -However, the functionalities of oemof-solph go beyond the content of this User's guide section. +However, the functionalities of oemof.solph go beyond the content of this User's guide section. So, if you want to know all details of a certain component or a function, please go the :ref:`api_reference_label`. There, you will find -a detailed and complete description of all oemof-solph modules. - -.. contents:: - :depth: 2 - :local: - :backlinks: top - +a detailed and complete description of all oemof.solph modules. How can I use solph? -------------------- @@ -101,10 +95,15 @@ All solph *components* can be used to set up an energy system model but you shou An example of a simple energy system shows the usage of the nodes for real world representations: -.. image:: _files/oemof_solph_example.svg - :scale: 70 % - :alt: alternate text +.. figure:: /_files/oemof_solph_example_darkmode.svg + :alt: oemof_solph_example_darkmode.svgt :align: center + :figclass: only-dark + +.. figure:: /_files/oemof_solph_example.svg + :alt: oemof_solph_example.svg + :align: center + :figclass: only-light The figure shows a simple energy system using the four basic network classes and the Bus class. If you remove the transmission line (transport 1 and transport 2) you get two systems but they are still one energy system in terms of solph and will be optimised at once. @@ -413,10 +412,15 @@ the power loss factor :math:`\beta` (in some contexts also referred to as :math:`C_v`). The second constraint limits the decrease of electrical power and incorporates the backpressure coefficient :math:`C_b`. -.. image:: _files/ExtractionTurbine_range_of_operation.svg - :width: 70 % +.. figure:: /_files/ExtractionTurbine_range_of_operation.svg :alt: variable_chp_plot.svg :align: center + :figclass: only-light + +.. figure:: /_files/ExtractionTurbine_range_of_operation_darkmode.svg + :alt: variable_chp_plot_darkmode.svg + :align: center + :figclass: only-dark For now, :py:class:`~oemof.solph.components._extraction_turbine_chp.ExtractionTurbineCHP` instances must have one input and two output flows. The class allows the definition @@ -443,10 +447,17 @@ and thermal power production in contrast to a fixed chp (left). The plot is the output of an example in the `example directory `_. -.. image:: _files/variable_chp_plot.svg - :scale: 10 % +.. figure:: /_files/variable_chp_plot.svg + :scale: 10% :alt: variable_chp_plot.svg :align: center + :figclass: only-light + +.. figure:: /_files/variable_chp_plot_darkmode.svg + :scale: 10% + :alt: variable_chp_plot_darkmode.svg + :align: center + :figclass: only-dark .. note:: See the :py:class:`~oemof.solph.components._extraction_turbine_chp.ExtractionTurbineCHP` class for all parameters and the mathematical background. @@ -459,10 +470,17 @@ GenericCHP (component) With the GenericCHP class it is possible to model different types of CHP plants (combined cycle extraction turbines, back pressure turbines and motoric CHP), which use different ranges of operation, as shown in the figure below. -.. image:: _files/GenericCHP.svg +.. figure:: /_files/GenericCHP.svg + :scale: 70 % + :alt: scheme of GenericCHP operation range + :align: center + :figclass: only-light + +.. figure:: /_files/GenericCHP_darkmode.svg :scale: 70 % :alt: scheme of GenericCHP operation range :align: center + :figclass: only-dark Combined cycle extraction turbines: The minimal and maximal electric power without district heating (red dots in the figure) define maximum load and minimum load of the plant. Beta defines electrical power loss through @@ -790,16 +808,32 @@ The following figures show the power at the electrical and the thermal output and the resepctive ratios to the nonconvex flow (normalized). The efficiency becomes non-linear. -.. image:: _files/OffsetConverter_relations_1.svg +.. figure:: /_files/OffsetConverter_relations_1.svg :width: 70 % :alt: OffsetConverter_relations_1.svg :align: center + :figclass: only-light + +.. figure:: /_files/OffsetConverter_relations_1_darkmode.svg + :width: 70 % + :alt: OffsetConverter_relations_1_darkmode.svg + :align: center + :figclass: only-dark + + -.. image:: _files/OffsetConverter_relations_2.svg +.. figure:: /_files/OffsetConverter_relations_2.svg :width: 70 % :alt: OffsetConverter_relations_2.svg :align: center + :figclass: only-light + +.. figure:: /_files/OffsetConverter_relations_2_darkmode.svg + :width: 70 % + :alt: OffsetConverter_relations_2_darkmode.svg + :align: center + :figclass: only-dark .. math:: @@ -929,10 +963,17 @@ This small example of PV, grid and SinkDSM shows how to use the component Yielding the following results -.. image:: _files/Plot_delay_2013-01-01.svg +.. figure:: /_files/Plot_delay_2013-01-01.svg :width: 85 % :alt: Plot_delay_2013-01-01.svg :align: center + :figclass: only-light + +.. figure:: /_files/Plot_delay_2013-01-01_darkmode.svg + :width: 85 % + :alt: Plot_delay_2013-01-01_darkmode.svg + :align: center + :figclass: only-dark .. note:: @@ -1049,10 +1090,17 @@ The following figures illustrates the use of the nonconvex investment flow. Here, :math:`c_{invest,fix}` is the *offset* value and :math:`c_{invest,var}` is the *ep_costs* value: -.. image:: _files/nonconvex_invest_investcosts_power.svg +.. figure:: /_files/nonconvex_invest_investcosts_power.svg :width: 70 % :alt: nonconvex_invest_investcosts_power.svg :align: center + :figclass: only-light + +.. figure:: /_files/nonconvex_invest_investcosts_power_darkmode.svg + :width: 70 % + :alt: nonconvex_invest_investcosts_power_darkmode.svg + :align: center + :figclass: only-dark In case of a convex investment (which is the default setting `nonconvex=False`), the *minimum* attribute leads to a forced investment, @@ -1061,10 +1109,17 @@ whereas in the nonconvex case, the investment can become zero as well. The calculation of the specific costs per kilowatt installed capacity results in the following relation for convex and nonconvex investments: -.. image:: _files/nonconvex_invest_specific_costs.svg +.. figure:: /_files/nonconvex_invest_specific_costs.svg :width: 70 % :alt: nonconvex_invest_specific_costs.svg :align: center + :figclass: only-light + +.. figure:: /_files/nonconvex_invest_specific_costs_darkmode.svg + :width: 70 % + :alt: nonconvex_invest_specific_costs_darkmode.svg + :align: center + :figclass: only-dark See :py:class:`~oemof.solph.blocks.investment_flow.InvestmentFlow` and :py:class:`~oemof.solph.components._generic_storage.GenericInvestmentStorageBlock` for all the @@ -1424,10 +1479,17 @@ The following diagram shows the duration curve of a typical diesel genset in a h PV cells, battery, inverter, and rectifier. By using the :py:class:`~oemof.solph.flows._invest_non_convex_flow_block.InvestNonConvexFlowBlock` class, it is possible to obtain the optimal capacity of this component and simultaneously limit its operation between `min` and `max` loads. -.. image:: _files/diesel_genset_nonconvex_invest_flow.svg +.. figure:: /_files/diesel_genset_nonconvex_invest_flow.svg :width: 100 % :alt: diesel_genset_nonconvex_invest_flow.svg :align: center + :figclass: only-light + +.. figure:: /_files/diesel_genset_nonconvex_invest_flow_darkmode.svg + :width: 100 % + :alt: diesel_genset_nonconvex_invest_flow_darkmode.svg + :align: center + :figclass: only-dark Without using the new :py:class:`~oemof.solph.flows._invest_non_convex_flow_block.InvestNonConvexFlowBlock` class, if the same system is optimized again, but this time using the :py:class:`~oemof.solph.flows._investment_flow_block.InvestmentFlowBlock`, the corresponding duration curve would be similar to the following @@ -1439,20 +1501,35 @@ Moreover, using the :py:class:`~oemof.solph.flows._investment_flow_block.Investm oversized diesel genset, which has a 30% larger capacity compared with the optimal capacity obtained from the :py:class:`~oemof.solph.flows._invest_non_convex_flow_block.InvestNonConvexFlowBlock` class. -.. image:: _files/diesel_genset_investment_flow.svg +.. figure:: /_files/diesel_genset_investment_flow.svg :width: 100 % :alt: diesel_genset_investment_flow.svg :align: center + :figclass: only-light + +.. figure:: /_files/diesel_genset_investment_flow_darkmode.svg + :width: 100 % + :alt: diesel_genset_investment_flow_darkmode.svg + :align: center + :figclass: only-dark + Solving such an optimisation problem considering `min`/`max` loads without the :py:class:`~oemof.solph.flows._invest_non_convex_flow_block.InvestNonConvexFlowBlock` class, the only possibility is first to obtain the optimal capacity using the :py:class:`~oemof.solph.flows._investment_flow_block.InvestmentFlowBlock` and then implement the `min`/`max` loads using the :py:class:`~oemof.solph.flows._non_convex_flow_block.NonConvexFlowBlock` class. The following duration curve would be obtained by applying this method to the same diesel genset. -.. image:: _files/diesel_genset_nonconvex_flow.svg +.. figure:: /_files/diesel_genset_nonconvex_flow.svg :width: 100 % :alt: diesel_genset_nonconvex_flow.svg :align: center + :figclass: only-light + +.. figure:: /_files/diesel_genset_nonconvex_flow_darkmode.svg + :width: 100 % + :alt: diesel_genset_nonconvex_flow_darkmode.svg + :align: center + :figclass: only-dark Because of the oversized diesel genset obtained from this approach, the capacity of the PV and battery in the given case study would be 13% and 43% smaller than the capacities obtained using the :py:class:`~oemof.solph.flows.NonConvexInvestmentFlow` class. diff --git a/pyproject.toml b/pyproject.toml index 4c8cf1314..230213b6d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -17,6 +17,7 @@ include = [ "examples/", "src/", "tests/", + "tutorials/", ".bumpversion.cfg", ".coveragerc", ".editorconfig", @@ -76,11 +77,11 @@ Changelog = "https://oemof-solph.readthedocs.io/en/latest/changelog.html" [project.optional-dependencies] dev = [ "flit", + "furo", "matplotlib", "nbformat", "pytest", "sphinx", - "sphinx_rtd_theme", "sphinx-copybutton", "sphinx-design", "termcolor", diff --git a/tox.ini b/tox.ini index 835cefaa2..8c1d19f3a 100644 --- a/tox.ini +++ b/tox.ini @@ -29,6 +29,8 @@ passenv = deps = py pytest +extras = + dev commands = {posargs:pytest -vv --ignore=src} @@ -61,8 +63,6 @@ commands = [testenv:docs] usedevelop = true -deps = - -r{toxinidir}/docs/requirements.txt commands = sphinx-build {posargs:-E} -W -b html docs dist/docs sphinx-build -b linkcheck docs dist/docs diff --git a/tutorials/introductory/district_heating_supply_1.py b/tutorials/introductory/district_heating_supply_1.py new file mode 100644 index 000000000..b5a8ee62c --- /dev/null +++ b/tutorials/introductory/district_heating_supply_1.py @@ -0,0 +1,7 @@ +# %%[sec_1] +import oemof.solph as solph + +# %%[sec_2] +import oemof.solph as solph + +# %%[sec_3] diff --git a/tutorials/introductory/district_heating_supply_2.py b/tutorials/introductory/district_heating_supply_2.py new file mode 100644 index 000000000..b5a8ee62c --- /dev/null +++ b/tutorials/introductory/district_heating_supply_2.py @@ -0,0 +1,7 @@ +# %%[sec_1] +import oemof.solph as solph + +# %%[sec_2] +import oemof.solph as solph + +# %%[sec_3] diff --git a/tutorials/introductory/district_heating_supply_3.py b/tutorials/introductory/district_heating_supply_3.py new file mode 100644 index 000000000..b5a8ee62c --- /dev/null +++ b/tutorials/introductory/district_heating_supply_3.py @@ -0,0 +1,7 @@ +# %%[sec_1] +import oemof.solph as solph + +# %%[sec_2] +import oemof.solph as solph + +# %%[sec_3]