diff --git a/examples/examples.ipynb b/examples/examples.ipynb index 1ed0a61b..f60c03e9 100644 --- a/examples/examples.ipynb +++ b/examples/examples.ipynb @@ -14,23 +14,25 @@ "\n", "With version 1.5.0, the following transformation are available:\n", "\n", - "* `update(\"biomass\")`: create regional biomass markets, adjusting the share of residual vs. purpose-grown boimass for use in heat and power generation\n", - "* `update(\"electricity\")`: create regional electricity markets and adjust efficiency of power plants, including that of photovoltaic panels\n", + "* `update(\"biomass\")`: creates regional biomass markets, adjusting the share of residual vs. purpose-grown boimass for use in heat and power generation\n", + "* `update(\"battery\")`: creates a global mix for stationary and mobile battery technologies.\n", + "* `update(\"electricity\")`: creates regional electricity markets and adjust efficiency of power plants, including that of photovoltaic panels\n", "* `update(\"cement\")`: creates regional markets for clinker production and adjust clinker production efficiency\n", "* `update(\"steel\")`: creates regional markets for steel and adjust steel production efficiency and the supply of secondary steel\n", "* `update(\"dac\")`: creates region- and scenario-specific inventories for Direct Air Capture (DAC) and Carbon Storage (DACCS) systems.\n", "* `update(\"fuels\")`: creates regional markets for liquid and gaseous fuels\n", - "* `update(\"heat\")`: regionalize some heat and steam generation datasets (working on diesel, biomass and natural gas)\n", - "* `update(\"emissions\")`: adjust emission of pollutants (PM, NOx, VOCs) for various activities, based on GAINS model projections.\n", + "* `update(\"heat\")`: regionalizes some heat and steam generation datasets (working on diesel, biomass and natural gas)\n", + "* `update(\"emissions\")`: adjusts emission of pollutants (PM, NOx, VOCs) for various activities, based on GAINS model projections.\n", "* `update(\"two_wheelers\")`: imports two-wheelers (bicycles, motorbikes, etc.)\n", - "* `update_cars()`: produces fleet average cars and relinks to activities consuming pasenger car transport\n", + "* `update(\"cars\")`: produces fleet average cars and relinks to activities consuming pasenger car transport\n", "* `update(\"trucks\")`: produces fleet average trucks and relinks to activities consuming lorry transport\n", "* `update(\"buses\")`: imports buses (urban and coach buses, single-deckers and double-deckers)\n", + "* `update(\"trains\")`: imports buses (urban and coach buses, single-deckers and double-deckers)\n", + "* `update(\"external\")`: runs any external scenarios provided.\n", "\n", - "Alternatively, `update()` performs all the above-mentioned transformations (except `update(\"two_wheelers\")`, `update(\"cars\")` and `update(\"buses\")`).\n", + "Alternatively, `update()` performs all the above-mentioned transformations.\n", "\n", - "There is also the possibility to integrate user-defined scenarios,\n", - "for which we have a separate notebook.\n", + "There is also the possibility to integrate user-defined scenarios (i.e., `update(\"external\")`), for which we have a separate notebook.\n", "\n", "Additional documentation on the methodology is available [here](https://premise.readthedocs.io/en/latest/introduction.html).\n", "\n", @@ -38,7 +40,7 @@ "\n", "## Requirements\n", "\n", - "* **Pyhton 3.9 or higher (up to 3.11) is highly recommended**\n", + "* **Pyhton 3.10 or higher (up to 3.11) is highly recommended**\n", "* a user license for ecoinvent v.3\n", "* a **decryption key**, to be asked from [Romain Sacchi](mailto:romain.sacchi@psi.ch)" ] @@ -50,18 +52,23 @@ "# Use case with [brightway2](https://brightway.dev/)\n", "\n", "`brightway2` is an open source LCA framework for Python.\n", - "To use `premise` from `brightway2`, it requires that you have an activated `brightway2` project with a `biosphere3` database as well as an ecoinvent v.3 cut-off or consequential database registered in that project." + "To use `premise` from `brightway2`, it requires that you have an activated `brightway2` project with a `biosphere3` database as well as an [ecoinvent](https://ecoinvent.prg) v.3 cut-off or consequential database registered in that project. Please refer to the brightway [documentation](https://brightway.dev) if you do not know how to create a project and install ecoinvent." ] }, { "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], + "metadata": { + "ExecuteTime": { + "end_time": "2024-08-13T09:59:07.856284Z", + "start_time": "2024-08-13T09:59:07.854148Z" + } + }, "source": [ "from premise import *\n", "import bw2data" - ] + ], + "outputs": [], + "execution_count": 3 }, { "cell_type": "markdown", @@ -70,27 +77,36 @@ "### List of available scenarios\n", "\n", "Some scenarios come installed with the library.\n", - "They are stored in `data/iam_ouput_files` from the root directory.\n", - "They are all within the same Shared Socio-Economic Pathway (SSP): SSP2 (nicknamed \"middle of the road\"), which describes a future world (in terms of GDP and demographics development, education, intergovernmental collaboration) very much in line with what has been observed historically..\n", + "They are stored in `premise/data/iam_ouput_files` from the root directory.\n", + "They are defined across different SSPs. For example, SSP2 (nicknamed \"middle of the road\"), which describes a future world (in terms of GDP and demographics development, education, intergovernmental collaboration) very much in line with what has been observed historically.\n", "\n", "But they are proposed in combination with different climate mitigation targets, called Representative Concentration Pathways (RCP).\n", "Read more about SSPs and RCPs, [here](https://www.carbonbrief.org/explainer-how-shared-socioeconomic-pathways-explore-future-climate-change).\n", "\n", "With REMIND, we have the following SSP/RCP scenarios:\n", "* \"SSP1-Base\"\n", - "* \"SSP5-Base\"\n", + "* \"SSP1-NPi\"\n", + "* \"SSP1-NDC\"\n", + "* \"SSP1-PkBudg1150\"\n", + "* \"SSP1-PkBudg500\"\n", "* \"SSP2-Base\"\n", "* \"SSP2-NPi\"\n", "* \"SSP2-NDC\"\n", "* \"SSP2-PkBudg1150\"\n", "* \"SSP2-PkBudg500\"\n", + "* \"SSP5-Base\"\n", + "* \"SSP5-NPi\"\n", + "* \"SSP5-NDC\"\n", + "* \"SSP5-PkBudg1150\"\n", + "* \"SSP5-PkBudg500\"\n", "\n", "With IMAGE, we have the following SSP/RCP scenarios:\n", + "* \"SSP1-Base\"\n", "* \"SSP2-Base\"\n", "* \"SSP2-RCP26\"\n", "* \"SSP2-RCP19\"\n", "\n", - "Refer to [the documentation](https://premise.readthedocs.io/en/latest/extract.html#current-iam-scenarios) for the meaning of thses scenarios, or have a look at our **[scenario explorer](https://premisedash-6f5a0259c487.herokuapp.com/)**.\n", + "Refer to [the documentation](https://premise.readthedocs.io/en/latest/extract.html#current-iam-scenarios) for a description of theses scenarios, or have a look at our **[scenario explorer](https://premisedash-6f5a0259c487.herokuapp.com/)**.\n", "Additionally, [this blog](https://www.carbonbrief.org/explainer-how-shared-socioeconomic-pathways-explore-future-climate-change/) is a good reading material to understand SSPs and RCPs.\n" ] }, @@ -100,7 +116,9 @@ "source": [ "### Database creation from default scenarios\n", "\n", - "To create a scenario using REMIND's SSP2 Base pathway, from ecoinvent 3.5 for the year 2028, one would execute the following cell. This leads to the extraction of the database, some cleanup as well as importing a few additional inventories." + "To create a scenario using REMIND's SSP2 Base pathway, from ecoinvent 3.10 for the year 2028, one would execute the following. This leads to the extraction of the database, some cleanup as well as importing a few additional inventories.\n", + "\n", + "First, activate the brightway2 project where you want to store the database." ] }, { @@ -109,52 +127,64 @@ "metadata": {}, "outputs": [], "source": [ + "# activate the bw project\n", "bw2data.projects.set_current(\"premise\")\n", + "# list currently installed databases\n", "bw2data.databases" ] }, { - "cell_type": "markdown", "metadata": {}, - "source": [ - "The first time you create a premise database, *premise* will store a copy of the ecoinvent database and external inventories, to be able to skip that time-consuming step next time. If you wish to clear this cache (which is only encourage if updating premise or if encountering issues with inventories), do:" - ] - }, - { "cell_type": "code", - "execution_count": null, - "metadata": {}, "outputs": [], - "source": [ - "clear_cache()" - ] - }, - { - "cell_type": "code", "execution_count": null, - "metadata": {}, - "outputs": [], "source": [ "ndb = NewDatabase(\n", " scenarios=[\n", " {\"model\":\"image\", \"pathway\":\"SSP2-RCP19\", \"year\":2050},\n", " {\"model\":\"remind\", \"pathway\":\"SSP2-PkBudg500\", \"year\":2050},\n", " ],\n", - " source_db=\"ecoinvent 3.8 cutoff\", # <-- name of the database in the BW2 project. Must be a string.\n", - " source_version=\"3.8\", # <-- version of ecoinvent. Can be \"3.5\", \"3.6\", \"3.7\" or \"3.8\". Must be a string.\n", + " source_db=\"ecoinvent-3.10-cutoff\", # <-- name of the database in the BW2 project. Must be a string.\n", + " source_version=\"3.10\", # <-- version of ecoinvent. Can be \"3.8\", \"3.9\" or \"3.10\". Must be a string.\n", " key='xxxxxxxxxxxxxxxxxxxxxxxxx', # <-- decryption key\n", " # to be requested from the library maintainers if you want ot use default scenarios included in `premise`\n", - " use_multiprocessing=True, # True by default, set to False if multiprocessing is causing troubles\n", - " keep_uncertainty_data=False # False by default, set to True if you want to keep ecoinvent's uncertainty data\n", - " use_absolute_efficiency=True, # False by default, set to True if you want to use the IAM's absolute efficiency for power plants\n", + " keep_source_db_uncertainty=False, # False by default, set to True if you want to keep ecoinvent's uncertainty data\n", + " keep_imports_uncertainty=False, # False by default, set to True if you want to keep the uncertainty data of the additional inventories\n", + " use_absolute_efficiency=True, # False by default, set to True if you want to use the IAM's absolute efficiencies\n", ")" ] }, + { + "metadata": {}, + "cell_type": "markdown", + "source": [ + "Here is a list of all arguments that can be passed to `NewDatabase()`:\n", + " \n", + " scenarios: List[dict],\n", + " source_version: str = \"3.10\",\n", + " source_type: str = \"brightway\",\n", + " key: bytes = None,\n", + " source_db: str = None,\n", + " source_file_path: str = None,\n", + " additional_inventories: List[dict] = None,\n", + " system_model: str = \"cutoff\",\n", + " system_args: dict = None,\n", + " use_cached_inventories: bool = True,\n", + " use_cached_database: bool = True,\n", + " external_scenarios: list = None,\n", + " quiet=False,\n", + " keep_imports_uncertainty=False,\n", + " keep_source_db_uncertainty=False,\n", + " gains_scenario=\"CLE\",\n", + " use_absolute_efficiency=False,\n", + " biosphere_name: str = \"biosphere3\"," + ] + }, { "cell_type": "markdown", "metadata": {}, "source": [ - "If you do not want to integrate the IAM projections in the database, but only wish to have the additional inventories, you can stop here and export the database back to Brightway or other destinations, by using the `write_db_to` methods, like so:" + "The first time you create a premise database, *premise* will store a copy of the ecoinvent database and external inventories, to be able to skip that time-consuming step next time. If you wish to clear this cache (which is only encourage if updating premise or if encountering issues with inventories), do:" ] }, { @@ -163,14 +193,15 @@ "metadata": {}, "outputs": [], "source": [ - "ndb.write_db_to_brightway()" + "clear_cache() # clears both ecoinvent and additional inventories cache\n", + "clear_inventory_cache() # clears only additional inventories cache" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "However, if you wish first to proceed with the IAM integration, you need to use the `update_` methods, like so for the electricity sector:" + "If you do not want to integrate the IAM projections in the database, but only wish to have the additional inventories, you can stop here and export the database back to Brightway or other destinations, by using the `write_db_to` methods, like so:" ] }, { @@ -179,23 +210,21 @@ "metadata": {}, "outputs": [], "source": [ - "ndb.update(\"electricity\")" + "ndb.write_db_to_brightway()" ] }, { - "cell_type": "code", - "execution_count": null, + "cell_type": "markdown", "metadata": {}, - "outputs": [], - "source": [ - "ndb.write_db_to_brightway()" - ] + "source": "However, if you wish first to proceed with the IAM integration, you need to use the `update()` method, like so for the electricity sector:" }, { - "cell_type": "markdown", + "cell_type": "code", + "execution_count": null, "metadata": {}, + "outputs": [], "source": [ - "or here with ecoinvent 3.7.1" + "ndb.update(\"electricity\")" ] }, { @@ -204,14 +233,7 @@ "metadata": {}, "outputs": [], "source": [ - "ndb = NewDatabase(\n", - " scenarios=[\n", - " {\"model\":\"remind\", \"pathway\":\"SSP2-Base\", \"year\":2028}\n", - " ],\n", - " source_db=\"ecoinvent 3.7 cutoff\", # <-- this is NEW.\n", - " source_version=\"3.7.1\", # <-- this is NEW\n", - " key='xxxxxxxxxxxxxxxxxxxxxxxxx'\n", - " )" + "ndb.write_db_to_brightway()" ] }, {