technologydata 0.1.0__py3-none-any.whl

technologydata/__init__.py

@@ -0,0 +1,41 @@
+# SPDX-FileCopyrightText: technologydata contributors
+#
+# SPDX-License-Identifier: MIT
+
+"""technologydata: A package for managing and analyzing technology data used for energy system models."""
+
+from technologydata.datapackage import DataPackage
+from technologydata.parameter import Parameter
+from technologydata.source import Source
+from technologydata.source_collection import SourceCollection
+from technologydata.technology import Technology
+from technologydata.technology_collection import TechnologyCollection
+from technologydata.utils.commons import Commons, DateFormatEnum, FileExtensionEnum
+from technologydata.utils.units import (
+    CURRENCY_UNIT_PATTERN,
+    creg,
+    extract_currency_units,
+    get_conversion_rate,
+    get_iso3_from_currency_code,
+    hvreg,
+    ureg,
+)
+
+__all__ = [
+    "Commons",
+    "DateFormatEnum",
+    "DataPackage",
+    "FileExtensionEnum",
+    "Parameter",
+    "Source",
+    "SourceCollection",
+    "Technology",
+    "TechnologyCollection",
+    "CURRENCY_UNIT_PATTERN",
+    "creg",
+    "extract_currency_units",
+    "get_conversion_rate",
+    "get_iso3_from_currency_code",
+    "hvreg",
+    "ureg",
+]

technologydata/constants/__init__.py

@@ -0,0 +1,12 @@
+# SPDX-FileCopyrightText: technologydata contributors
+#
+# SPDX-License-Identifier: MIT
+
+"""Provide classes and utilities for handling techno-economic data for energy system modeling."""
+
+from technologydata.constants.energy_density import EnergyDensityHHV, EnergyDensityLHV
+
+__all__ = [
+    "EnergyDensityHHV",
+    "EnergyDensityLHV",
+]

technologydata/constants/energy_density.py

@@ -0,0 +1,324 @@
+# SPDX-FileCopyrightText: technologydata contributors
+#
+# SPDX-License-Identifier: MIT
+
+"""
+Energy density parameters for various carriers.
+
+This module defines dictionaries containing energy density parameters
+for different fuel carriers, specifically focusing on lower heating value (LHV)
+and higher heating value (HHV). Each entry maps a carrier name to a `Parameter`
+object that includes magnitude, unit, and carrier type.
+
+Attributes
+----------
+EnergyDensityLHV : dict[str, Parameter]
+    Dictionary mapping carrier names to their lower heating value (LHV)
+    parameters.
+    - Key: carrier name (e.g., 'hydrogen', 'methane')
+    - Value: Parameter object with magnitude, unit, and carrier info.
+
+EnergyDensityHHV : dict[str, Parameter]
+    Dictionary mapping carrier names to their higher heating value (HHV)
+    parameters.
+    - Key: carrier name (e.g., 'hydrogen', 'methane')
+    - Value: Parameter object with magnitude, unit, and carrier info.
+
+"""
+
+from technologydata import Parameter, Source, SourceCollection
+
+EnergyDensityLHV: dict[str, Parameter] = dict(
+    hydrogen=Parameter(
+        magnitude=120,
+        units="MJ/kg",
+        carrier="hydrogen",
+        sources=SourceCollection(
+            sources=[
+                Source(
+                    title="Higher Calorific Values of Common Fuels: Reference & Data",
+                    authors="The Engineering ToolBox (2003)",
+                    url="https://www.engineeringtoolbox.com/fuels-higher-calorific-values-d_169.html",
+                    url_date="2025-09-06",
+                ),
+            ],
+        ),
+    ),
+    methane=Parameter(
+        magnitude=50.0,
+        units="MJ/kg",
+        carrier="methane",
+        sources=SourceCollection(
+            sources=[
+                Source(
+                    title="Higher Calorific Values of Common Fuels: Reference & Data",
+                    authors="The Engineering ToolBox (2003)",
+                    url="https://www.engineeringtoolbox.com/fuels-higher-calorific-values-d_169.html",
+                    url_date="2025-09-06",
+                ),
+            ],
+        ),
+    ),
+    natural_gas=Parameter(
+        magnitude=47.1,
+        units="MJ/kg",
+        carrier="natural_gas",
+        note="Value for natural gas in the US market",
+        sources=SourceCollection(
+            sources=[
+                Source(
+                    title="Higher Calorific Values of Common Fuels: Reference & Data",
+                    authors="The Engineering ToolBox (2003)",
+                    url="https://www.engineeringtoolbox.com/fuels-higher-calorific-values-d_169.html",
+                    url_date="2025-09-06",
+                ),
+            ],
+        ),
+    ),
+    ammonia=Parameter(
+        magnitude=18.646,
+        units="MJ/kg",
+        carrier="ammonia",
+        sources=SourceCollection(
+            sources=[
+                Source(
+                    title="Heat of combustion",
+                    authors="Wikipedia contributors",
+                    url="https://en.wikipedia.org/w/index.php?title=Heat_of_combustion&oldid=1307512525",
+                    url_date="2025-09-09",
+                ),
+            ],
+        ),
+    ),
+    wood=Parameter(
+        magnitude=15.4,
+        units="MJ/kg",
+        carrier="wood",
+        sources=SourceCollection(
+            sources=[
+                Source(
+                    title="Higher Calorific Values of Common Fuels: Reference & Data",
+                    authors="The Engineering ToolBox (2003)",
+                    url="https://www.engineeringtoolbox.com/fuels-higher-calorific-values-d_169.html",
+                    url_date="2025-09-06",
+                ),
+            ],
+        ),
+    ),
+    carbon=Parameter(
+        magnitude=32.8,
+        units="MJ/kg",
+        carrier="carbon",
+        note="For pure carbon we assume LHV=HHV",
+        sources=SourceCollection(
+            sources=[
+                Source(
+                    title="Higher Calorific Values of Common Fuels: Reference & Data",
+                    authors="The Engineering ToolBox (2003)",
+                    url="https://www.engineeringtoolbox.com/fuels-higher-calorific-values-d_169.html",
+                    url_date="2025-09-06",
+                ),
+            ],
+        ),
+    ),
+    methanol=Parameter(
+        magnitude=19.9,
+        units="MJ/kg",
+        carrier="methanol",
+        sources=SourceCollection(
+            sources=[
+                Source(
+                    title="Higher Calorific Values of Common Fuels: Reference & Data",
+                    authors="The Engineering ToolBox (2003)",
+                    url="https://www.engineeringtoolbox.com/fuels-higher-calorific-values-d_169.html",
+                    url_date="2025-09-06",
+                ),
+            ],
+        ),
+    ),
+    gasoline=Parameter(
+        magnitude=43.4,
+        units="MJ/kg",
+        carrier="gasoline",
+        sources=SourceCollection(
+            sources=[
+                Source(
+                    title="Higher Calorific Values of Common Fuels: Reference & Data",
+                    authors="The Engineering ToolBox (2003)",
+                    url="https://www.engineeringtoolbox.com/fuels-higher-calorific-values-d_169.html",
+                    url_date="2025-09-06",
+                ),
+            ],
+        ),
+    ),
+    # Add more energy densities as needed
+)
+
+EnergyDensityHHV: dict[str, Parameter] = dict(
+    hydrogen=Parameter(
+        magnitude=141.7,
+        units="MJ/kg",
+        carrier="hydrogen",
+        sources=SourceCollection(
+            sources=[
+                Source(
+                    title="The Engineering ToolBox",
+                    authors="The Engineering ToolBox (2003). Higher Calorific Values of Common Fuels: Reference & Data. [online] Available at:https://www.engineeringtoolbox.com/fuels-higher-calorific-values-d_169.html [Accessed 6 September 2025].",
+                    url="https://www.engineeringtoolbox.com/fuels-higher-calorific-values-d_169.html",
+                ),
+            ],
+        ),
+    ),
+    methane=Parameter(
+        magnitude=55.5,
+        units="MJ/kg",
+        carrier="methane",
+        sources=SourceCollection(
+            sources=[
+                Source(
+                    title="Higher Calorific Values of Common Fuels: Reference & Data",
+                    authors="The Engineering ToolBox (2003)",
+                    url="https://www.engineeringtoolbox.com/fuels-higher-calorific-values-d_169.html",
+                    url_date="2025-09-06",
+                ),
+            ],
+        ),
+    ),
+    natural_gas=Parameter(
+        magnitude=52.2,
+        units="MJ/kg",
+        carrier="natural_gas",
+        note="Value for natural gas in the US market",
+        sources=SourceCollection(
+            sources=[
+                Source(
+                    title="Higher Calorific Values of Common Fuels: Reference & Data",
+                    authors="The Engineering ToolBox (2003)",
+                    url="https://www.engineeringtoolbox.com/fuels-higher-calorific-values-d_169.html",
+                    url_date="2025-09-06",
+                ),
+            ],
+        ),
+    ),
+    ammonia=Parameter(
+        magnitude=22.5,
+        units="MJ/kg",
+        carrier="ammonia",
+        sources=SourceCollection(
+            sources=[
+                Source(
+                    title="Higher Calorific Values of Common Fuels: Reference & Data",
+                    authors="The Engineering ToolBox (2003)",
+                    url="https://www.engineeringtoolbox.com/fuels-higher-calorific-values-d_169.html",
+                    url_date="2025-09-06",
+                ),
+            ],
+        ),
+    ),
+    wood=Parameter(
+        magnitude=16.2,
+        units="MJ/kg",
+        carrier="wood",
+        sources=SourceCollection(
+            sources=[
+                Source(
+                    title="Higher Calorific Values of Common Fuels: Reference & Data",
+                    authors="The Engineering ToolBox (2003)",
+                    url="https://www.engineeringtoolbox.com/fuels-higher-calorific-values-d_169.html",
+                    url_date="2025-09-06",
+                ),
+            ],
+        ),
+    ),
+    carbon=Parameter(
+        magnitude=32.8,
+        units="MJ/kg",
+        carrier="carbon",
+        sources=SourceCollection(
+            sources=[
+                Source(
+                    title="Higher Calorific Values of Common Fuels: Reference & Data",
+                    authors="The Engineering ToolBox (2003)",
+                    url="https://www.engineeringtoolbox.com/fuels-higher-calorific-values-d_169.html",
+                    url_date="2025-09-06",
+                ),
+            ],
+        ),
+    ),
+    lignite=Parameter(
+        magnitude=14.0,
+        units="MJ/kg",
+        carrier="lignite",
+        sources=SourceCollection(
+            sources=[
+                Source(
+                    title="Higher Calorific Values of Common Fuels: Reference & Data",
+                    authors="The Engineering ToolBox (2003)",
+                    url="https://www.engineeringtoolbox.com/fuels-higher-calorific-values-d_169.html",
+                    url_date="2025-09-06",
+                ),
+            ],
+        ),
+    ),
+    coal=Parameter(
+        magnitude=32.6,
+        units="MJ/kg",
+        carrier="coal",
+        sources=SourceCollection(
+            sources=[
+                Source(
+                    title="Higher Calorific Values of Common Fuels: Reference & Data",
+                    authors="The Engineering ToolBox (2003)",
+                    url="https://www.engineeringtoolbox.com/fuels-higher-calorific-values-d_169.html",
+                    url_date="2025-09-06",
+                ),
+            ],
+        ),
+    ),
+    methanol=Parameter(
+        magnitude=23.0,
+        units="MJ/kg",
+        carrier="methanol",
+        sources=SourceCollection(
+            sources=[
+                Source(
+                    title="Higher Calorific Values of Common Fuels: Reference & Data",
+                    authors="The Engineering ToolBox (2003)",
+                    url="https://www.engineeringtoolbox.com/fuels-higher-calorific-values-d_169.html",
+                    url_date="2025-09-06",
+                ),
+            ],
+        ),
+    ),
+    jet_fuel_a1=Parameter(
+        magnitude=46.2,
+        units="MJ/kg",
+        carrier="jet_fuel_a1",
+        sources=SourceCollection(
+            sources=[
+                Source(
+                    title="Jet fuel",
+                    authors="Wikipedia contributors",
+                    url="https://en.wikipedia.org/w/index.php?title=Jet_fuel&oldid=1310114781",
+                    url_date="2025-09-07",
+                ),
+            ],
+        ),
+    ),
+    gasoline=Parameter(
+        magnitude=46.4,
+        units="MJ/kg",
+        carrier="gasoline",
+        sources=SourceCollection(
+            sources=[
+                Source(
+                    title="Higher Calorific Values of Common Fuels: Reference & Data",
+                    authors="The Engineering ToolBox (2003)",
+                    url="https://www.engineeringtoolbox.com/fuels-higher-calorific-values-d_169.html",
+                    url_date="2025-09-06",
+                ),
+            ],
+        ),
+    ),
+    # Add more energy densities as needed
+)

technologydata/datapackage.py

@@ -0,0 +1,145 @@
+# SPDX-FileCopyrightText: technologydata contributors
+#
+# SPDX-License-Identifier: MIT
+
+"""
+DataPackage class for managing collections of Technology objects and batch operations.
+
+Examples
+--------
+>>> dp = DataPackage.from_json("path/to/data_package.json")
+
+"""
+
+import logging
+import pathlib
+from typing import Annotated, Self
+
+import pydantic
+
+from technologydata.source_collection import SourceCollection
+from technologydata.technology_collection import TechnologyCollection
+
+logger = logging.getLogger(__name__)
+
+
+class DataPackage(pydantic.BaseModel):
+    """
+    Container for a collection of Technology objects and/or Source objects, with batch operations and loading utilities.
+
+    Attributes
+    ----------
+    technologies : Optional[TechnologyCollection]
+        List of Technology objects.
+    sources : Optional[SourceCollection]
+        List of Source objects.
+
+    """
+
+    technologies: Annotated[
+        TechnologyCollection | None,
+        pydantic.Field(description="List of Technology objects."),
+    ] = None
+    sources: Annotated[
+        SourceCollection | None, pydantic.Field(description="List of Source objects.")
+    ] = None
+
+    def get_source_collection(self) -> None:
+        """
+        Get the SourceCollection associated with this DataPackage from the TechnologyCollection.
+
+        Returns
+        -------
+        SourceCollection
+            The SourceCollection instance.
+
+        """
+        sources_set = set()
+        if self.sources is None:
+            if self.technologies is not None:
+                for technology in self.technologies:
+                    for parameter in technology.parameters.values():
+                        for source in parameter.sources:
+                            sources_set.add(source)
+            else:
+                raise ValueError(
+                    "No technologies available to extract a sources collection from."
+                )
+        else:
+            logger.info("The data package already has a sources collection.")
+        self.sources = SourceCollection(sources=list(sources_set))
+
+    @classmethod
+    def from_json(cls, path_to_folder: pathlib.Path | str) -> Self:
+        """
+        Load a DataPackage from a JSON file.
+
+        Parameters
+        ----------
+        path_to_folder : pathlib.Path or str
+            Path to the data package folder.
+
+        Returns
+        -------
+        DataPackage
+            The loaded DataPackage instance.
+
+        """
+        # Load technologies
+        technologies_path = pathlib.Path(path_to_folder, "technologies.json")
+        technologies = TechnologyCollection.from_json(technologies_path)
+
+        # Create DataPackage instance
+        data_package = cls(
+            path=path_to_folder,
+            technologies=technologies,
+        )
+
+        # Generate sources collection from technologies if sources is None
+        data_package.get_source_collection()
+
+        return data_package
+
+    def to_json(self, folder_path: pathlib.Path) -> None:
+        """
+        Export the Datapackage to JSON files.
+
+        The files are:
+         - the 'technologies' attribute is exported to technologies.json, together with the corresponding data schema
+         - the 'sources' attribute is exported to sources.json, together with the corresponding data schema
+
+        Parameters
+        ----------
+        folder_path : pathlib.Path
+            The path to the folder where the JSON files are created
+
+        """
+        if self.technologies is not None:
+            technologies_path = pathlib.Path(folder_path, "technologies.json")
+            self.technologies.to_json(technologies_path)
+
+        if self.sources is not None:
+            sources_path = pathlib.Path(folder_path, "sources.json")
+            self.sources.to_json(sources_path)
+
+    def to_csv(self, folder_path: pathlib.Path) -> None:
+        """
+        Export the Datapackage to CSV files.
+
+        The files are:
+         - the 'technologies' attribute is exported to technologies.csv
+         - the 'sources' attribute is exported to sources.csv
+
+        Parameters
+        ----------
+        folder_path : pathlib.Path
+            The path to the folder where the CSV files are created
+
+        """
+        if self.technologies is not None:
+            technologies_path = pathlib.Path(folder_path, "technologies.csv")
+            self.technologies.to_csv(path_or_buf=technologies_path)
+
+        if self.sources is not None:
+            sources_path = pathlib.Path(folder_path, "sources.csv")
+            self.sources.to_csv(path_or_buf=sources_path)