zen-garden 2.7.17__tar.gz → 2.7.19__tar.gz

{zen_garden-2.7.17 → zen_garden-2.7.19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zen_garden
-Version: 2.7.17
+Version: 2.7.19
 Summary: ZEN-garden is an optimization model of energy systems and value chains.
 Author: Alissa Ganter, Johannes Burger, Francesco De Marco, Lukas Kunz, Lukas Schmidt-Engelbertz, Christoph Funke, Paolo Gabrielli, Giovanni Sansavini
 Author-email: Jacob Mannhardt <zen-garden@ethz.ch>

{zen_garden-2.7.17 → zen_garden-2.7.19}/pyproject.toml

@@ -16,7 +16,7 @@ authors = [
   {name = "Giovanni Sansavini"},
   ]
 # do not change version manually! Done by bump2version
-version = "2.7.17"
+version = "2.7.19"
 requires-python= ">=3.11,<3.14"
 description="ZEN-garden is an optimization model of energy systems and value chains."
 readme = "README.md"
@@ -79,4 +79,5 @@ addopts = "-n auto"
 
 [project.scripts]
 zen-garden = "zen_garden.__main__:run_module"
-zen-visualization = "zen_garden.visualization:parse_arguments_and_run"
+zen-visualization = "zen_garden.visualization:parse_arguments_and_run"
+zen-example = "zen_garden.dataset_examples:cli_download_example_dataset"

{zen_garden-2.7.17 → zen_garden-2.7.19}/zen_garden/__main__.py

@@ -9,12 +9,10 @@ import sys
 import os
 import zen_garden.default_config as default_config
 import json
-from zen_garden.utils import copy_dataset_example
 from pathlib import Path
 
 def run_module(args=None, config = "./config.py", dataset = None, 
-               folder_output = None, job_index = None, job_index_var = "SLURM_ARRAY_TASK_ID",
-               download_example = None):
+               folder_output = None, job_index = None, job_index_var = "SLURM_ARRAY_TASK_ID"):
     """
     Runs the main function of ZEN-Garden
 
@@ -28,7 +26,7 @@ def run_module(args=None, config = "./config.py", dataset = None,
                   "current working directory. You can specify a config file with the --config argument. However, " \
                   "note that the output directory will always be the current working directory, independent of the " \
                   "dataset specified in the config file."
-    parser = argparse.ArgumentParser(description=description, add_help=True, usage="usage: zen-garden [-h] [--config CONFIG] [--dataset DATASET] [--job_index JOB_INDEX] [--job_index_var JOB_INDEX_VAR] [-- download_example EXAMPLE_NAME]")
+    parser = argparse.ArgumentParser(description=description, add_help=True, usage="usage: zen-garden [-h] [--config CONFIG] [--dataset DATASET] [--job_index JOB_INDEX] [--job_index_var JOB_INDEX_VAR]")
     # TODO make json config default
     parser.add_argument("--config", required=False, type=str, default=config, help="Path to the config file used to run the pipeline (e.g., `./config.json`). Alternatively, if the config file is located in the current working directory, then the file name is alone is also acceptable (e.g. `config.json`).")
     parser.add_argument("--dataset", required=False, type=str, default=dataset, help="Path to the dataset (e.g. `./<dataset_name>`). Alternatively, if the dataset is located in the current working directory, then the folder name alone is also acceptable (e.g. `<dataset_name>`). IMPORTANT: This will overwrite the config.analysis.dataset attribute of the config file!")
@@ -37,15 +35,8 @@ def run_module(args=None, config = "./config.py", dataset = None,
     parser.add_argument("--job_index", required=False, type=str, default=job_index, help="A comma separated list (no spaces) of indices of the scenarios to run, if None, all scenarios are run in sequence")
     parser.add_argument("--job_index_var", required=False, type=str, default=job_index_var, help="Try to read out the job index from the environment variable specified here. "
                                                                                                          "If both --job_index and --job_index_var are specified, --job_index will be used.")
-    parser.add_argument("--download_example", required=False, type=str, default=download_example, help="Downloads an example data set to the current working directory. The argument should be the name of a dataset example in documentation/dataset_examples. This command will copy the dataset and the config to the current folder. It will not run ZEN-garden.")
-
     args = parser.parse_args(args)
 
-    # copy example dataset and run example
-    if args.download_example is not None:
-        example_path_cwd,config_path_cwd = copy_dataset_example(args.download_example)
-        return 
-
     if not os.path.exists(args.config):
         args.config = args.config.replace(".py", ".json")
 

zen_garden-2.7.19/zen_garden/dataset_examples.py

@@ -0,0 +1,186 @@
+"""
+This module contains code the coding for downloading the ZEN-garden 
+dataset examples. It defines a command line interface as well as a python 
+function for this purpose. 
+"""
+
+import argparse
+import sys
+import json
+import warnings
+import os
+import sys
+import requests
+from importlib.metadata import metadata
+import zipfile
+import io
+
+
+def download_example_dataset(dataset):
+    """ 
+    Downloads a dataset example to the current working directory. The function 
+    downloads the ZEN-garden dataset examples from the ZEN-garden Zenodo 
+    repository. It then extracts the dataset specified by the user and saves
+    it to the current working directory. In addition, it also downloads a 
+    ``config.json`` file and a Jupyter notebook demonstrating how to analyze
+    the results of a model. 
+
+    Args:
+        dataset (str): Name of the dataset to be downloaded. The following
+            options are currently available: "1_base_case", 
+            "2_multi_year_optimization", "3_reduced_import_availability", 
+            "4_PWA_nonlinear_capex", "5_multiple_time_steps_per_year",
+            "6_reduced_import_availability_yearly", "7_time_series_aggregation",
+            "8_yearly_variation", "9_myopic_foresight", "10_brown_field",
+            "11_multi_scenario", "12_multiple_in_output_carriers_conversion",
+            "13_yearly_interpolation", "14_retrofitting_and_fuel_substitution",
+            "15_unit_consistency_expected_error"
+
+    Returns:
+        tuple: 
+            str: The local path of the copied example
+            str: The local path of the copied config.json
+
+    Raises:
+        FileNotFoundError: If either the dataset or the config file could not 
+            be found in the Zenodo repository. 
+
+    Examples:
+        Basic usage example:
+
+        >>> from zen_garden.dataset_examples import download_dataset_example
+        >>> download_dataset_example("1_base_case")
+
+    """
+
+    # retrieve Zenodo metadata
+    url = metadata("zen_garden").get_all("Project-URL")
+    url = [u.split(", ")[1] for u in url if u.split(", ")[0] == "Zenodo"][0]
+
+    # fetch Zenodo metadata
+    zenodo_meta = requests.get(url, allow_redirects=True)
+    zenodo_meta.raise_for_status()
+    zenodo_data = zenodo_meta.json()
+    zenodo_zip_url = zenodo_data["files"][0]["links"]["self"]
+
+    # download ZIP file from Zenodo
+    zenodo_zip = requests.get(zenodo_zip_url)
+    zenodo_zip = zipfile.ZipFile(io.BytesIO(zenodo_zip.content))
+
+    # define relevant paths
+    base_path = zenodo_zip.filelist[0].filename
+    example_path = f"{base_path}docs/dataset_examples/{dataset}/"
+    config_path = f"{base_path}docs/dataset_examples/config.json"
+    notebook_path = f"{base_path}docs/dataset_examples/example_notebook.ipynb"
+
+    # create local directories
+    local_dataset_path = os.getcwd()
+    if not os.path.exists(local_dataset_path):
+        os.mkdir(local_dataset_path)
+    local_example_path = os.path.join(local_dataset_path, dataset)
+    if not os.path.exists(local_example_path):
+        os.mkdir(local_example_path)
+
+    # initialize flags for extracting files
+    example_found = False
+    config_found = False
+    notebook_found = False
+
+    # search for example within ZIP file
+    for file in zenodo_zip.filelist:
+
+        # download all files in dataset example
+        if file.filename.startswith(example_path):
+            filename_ending = file.filename.split(example_path)[1]
+            local_folder_path = os.path.join(
+                local_example_path, filename_ending)
+            if file.is_dir():
+                if not os.path.exists(local_folder_path):
+                    os.mkdir(os.path.join(local_example_path, filename_ending))
+            else:
+                local_file_path = os.path.join(
+                    local_example_path, filename_ending)
+                with open(local_file_path, "wb") as f:
+                    f.write(zenodo_zip.read(file))
+            example_found = True
+
+        # download config.json
+        elif file.filename == config_path:
+            with open(os.path.join(local_dataset_path, "config.json"), "wb") as f:
+                f.write(zenodo_zip.read(file))
+            config_found = True
+
+        # download jupyter notebook
+        elif file.filename == notebook_path:
+            notebook_path_local = os.path.join(
+                local_dataset_path, "example_notebook.ipynb")
+            notebook = json.loads(zenodo_zip.read(file))
+            for cell in notebook['cells']:
+                if cell['cell_type'] == 'code':  # Check only code cells
+                    for i, line in enumerate(cell['source']):
+                        if "<dataset_name>" in line:
+                            cell['source'][i] = line.replace(
+                                "<dataset_name>", dataset)
+            with open(notebook_path_local, "w") as f:
+                json.dump(notebook, f)
+            notebook_found = True
+
+    # display status, errors, and warnings
+    if not example_found:
+        raise FileNotFoundError(
+            f"Example {dataset} could not be found in the dataset examples!"
+        )
+    if not config_found:
+        raise FileNotFoundError(
+            "Config.json file could not be downloaded from the dataset "
+            "examples!"
+        )
+    if not notebook_found:
+        warnings.warn(
+            "Example jupyter notebook could not be downloaded from the "
+            "dataset examples!")
+
+    # print output
+    print(f"Example dataset {dataset} downloaded to {local_example_path}")
+
+    # return
+    return local_example_path, os.path.join(local_dataset_path, "config.json")
+
+
+def cli_download_example_dataset():
+    """ 
+    Creates a command line interface for downloading the dataset examples. 
+    The function parses a single required argument ``--dataset`` that 
+    specifies the name of the dataset to be downloaded. It then invokes
+    the function function ``download_example_dataset`` with that argument.
+
+    The ``[project.scripts]`` section of the pyproject.toml declares that 
+    this function will be called whenever a user enters ``zen-example`` into
+    the command prompt. This function is therefore creates the ``zen-example`` 
+    command line entry point.
+
+    Examples:
+        Basic usage in a command line prompt:
+
+        >>> zen-example --dataset="1_base_case"
+
+    """
+    # parse the args
+    description = "Downloads an example dataset for ZEN-garden to the current" \
+        "working directory"
+
+    parser = argparse.ArgumentParser(
+        description=description,
+        add_help=True,
+        usage="usage: zen-example [--dataset DATASET]")
+
+    parser.add_argument(
+        "--dataset",
+        required=True,
+        type=str,
+        help="Name of the dataset to download, e.g. '1_base_case'")
+
+    args = parser.parse_args(sys.argv[1:])
+
+    # download the example
+    download_example_dataset(args.dataset)

{zen_garden-2.7.17 → zen_garden-2.7.19}/zen_garden/postprocess/results/results.py

@@ -337,13 +337,21 @@ class Results:
         """
         Calculates the total values of a component for a all scenarios.
 
-        :param component_name: Name of the component
+        :param component_name: Name of the component. Should not be used for dual variables!
         :param year: Filter the results by a given year
         :param scenario_name: Filter the results by a given scenario
         :param keep_raw: Keep the raw values of the rolling horizon optimization
         :param index: slicing index of the resulting dataframe
         :return: Total values of the component
         """
+
+        # Throw error if used for a dual variable
+        if component_name in self.get_component_names("dual"):
+            raise ValueError(
+                "This method does not support the extraction of " \
+                "dual variables. Please use the methods " \
+                "`get_dual()` or `get_full_ts()` instead.")
+
         if scenario_name is None:
             scenario_names = list(self.solution_loader.scenarios)
         else:

{zen_garden-2.7.17 → zen_garden-2.7.19}/zen_garden/utils.py

@@ -46,74 +46,6 @@ def get_inheritors(klass):
     return subclasses
 
 
-def copy_dataset_example(example):
-    """ copies a dataset example to the current working directory
-
-    :param example: The name of the example to copy
-    :return: The local path of the copied example
-    :return: The local path of the copied config.json
-    """
-    import requests
-    from importlib.metadata import metadata
-    import zipfile
-    import io
-    url = metadata("zen_garden").get_all("Project-URL")
-    url = [u.split(", ")[1] for u in url if u.split(", ")[0] == "Zenodo"][0]
-    zenodo_meta = requests.get(url,allow_redirects=True)
-    zenodo_meta.raise_for_status()
-    zenodo_data = zenodo_meta.json()
-    zenodo_zip_url = zenodo_data["files"][0]["links"]["self"]
-    zenodo_zip = requests.get(zenodo_zip_url)
-    zenodo_zip = zipfile.ZipFile(io.BytesIO(zenodo_zip.content))
-    base_path = zenodo_zip.filelist[0].filename
-    example_path = f"{base_path}docs/dataset_examples/{example}/"
-    config_path = f"{base_path}docs/dataset_examples/config.json"
-    notebook_path = f"{base_path}docs/dataset_examples/example_notebook.ipynb"
-    #local_dataset_path = os.path.join(os.getcwd(), "dataset_examples")
-    local_dataset_path = os.getcwd()
-    if not os.path.exists(local_dataset_path):
-        os.mkdir(local_dataset_path)
-    local_example_path = os.path.join(local_dataset_path, example)
-    if not os.path.exists(local_example_path):
-        os.mkdir(local_example_path)
-    example_found = False
-    config_found = False
-    notebook_found = False
-    for file in zenodo_zip.filelist:
-        if file.filename.startswith(example_path):
-            filename_ending = file.filename.split(example_path)[1]
-            local_folder_path = os.path.join(local_example_path, filename_ending)
-            if file.is_dir():
-                if not os.path.exists(local_folder_path):
-                    os.mkdir(os.path.join(local_example_path, filename_ending))
-            else:
-                local_file_path = os.path.join(local_example_path, filename_ending)
-                with open(local_file_path, "wb") as f:
-                    f.write(zenodo_zip.read(file))
-            example_found = True
-        elif file.filename == config_path:
-            with open(os.path.join(local_dataset_path, "config.json"), "wb") as f:
-                f.write(zenodo_zip.read(file))
-            config_found = True
-        elif file.filename == notebook_path:
-            notebook_path_local = os.path.join(local_dataset_path, "example_notebook.ipynb")
-            notebook = json.loads(zenodo_zip.read(file))
-            for cell in notebook['cells']:
-                if cell['cell_type'] == 'code':  # Check only code cells
-                    for i, line in enumerate(cell['source']):
-                        if "<dataset_name>" in line:
-                            cell['source'][i] = line.replace("<dataset_name>", example)
-            with open(notebook_path_local, "w") as f:
-                json.dump(notebook, f)
-            notebook_found = True
-    assert example_found, f"Example {example} could not be downloaded from the dataset examples!"
-    assert config_found, f"Config.json file could not be downloaded from the dataset examples!"
-    if not notebook_found:
-        logging.warning("Example jupyter notebook could not be downloaded from the dataset examples!")
-    logging.info(f"Example dataset {example} downloaded to {local_example_path}")
-    return local_example_path, os.path.join(local_dataset_path, "config.json")
-
-
 # linopy helpers
 # --------------