TechnologyCollection ¶

Bases: BaseModel


              flowchart TD
              technologydata.technology_collection.TechnologyCollection[TechnologyCollection]

              

              click technologydata.technology_collection.TechnologyCollection href "" "technologydata.technology_collection.TechnologyCollection"

Represent a collection of technologies.

Attributes:

schema_version (int) –

Version of the data schema, see SCHEMA_VERSION.
technologies (List[Technology]) –

List of Technology objects.

Methods:

__add__ –

Merge two TechnologyCollection objects using the + operator.
__getitem__ –

Access a TechnologyCollection by index, slice.
__iter__ –

Return an iterator over the list of Technology objects.
__len__ –

Return the number of technologies in this collection.
__str__ –

Return a compact human-readable summary of the TechnologyCollection.
append –

Append a technology to an existing TechnologyCollection.
calculate_parameters –

Derive missing parameters of every contained Technology using registered equations.
check_consistency –

Check equation-level consistency for selected parameters of every contained Technology.
fit –

Fit a growth model to a specified parameter across all technologies in the collection.
from_json –

Load a TechnologyCollection instance from a JSON file.
get –

Filter technologies based on regex patterns for non-optional attributes.
get_parameter –

Get parameter values across all technologies in the collection.
project –

Project specified parameters for all technologies in the collection to future years.
to_csv –

Export the TechnologyCollection to a CSV file.
to_currency –

Adjust the currency of all parameters of all contained Technology objects to the target currency.
to_dataframe –

Convert the TechnologyCollection to a pandas DataFrame.
to_json –

Export the TechnologyCollection to a JSON file, together with a data schema.

schema_version `class-attribute` `instance-attribute` ¶

schema_version: Annotated[int, Field(description='Version of the data schema.')] = SCHEMA_VERSION

technologies `instance-attribute` ¶

technologies: Annotated[list[Technology], Field(description='List of Technology objects.')]

add ¶

__add__(other: Self) -> Self

Merge two TechnologyCollection objects using the + operator.

Parameters:

other (TechnologyCollection) –

The collection to merge with.

Returns:

TechnologyCollection –

A new TechnologyCollection containing technologies from both collections.

getitem ¶

__getitem__(index: int) -> Technology

__getitem__(index: slice) -> Self

__getitem__(index: int | slice) -> Technology | Self

Access a TechnologyCollection by index, slice.

Parameters:

index (int | slice) –

Index or slice of the Technology to access.

Returns:

Technology | Self –

The requested Technology (if an index is provided) or TechnologyCollection (if a slice is given).

iter ¶

__iter__() -> Iterator[Technology]

Return an iterator over the list of Technology objects.

Returns:

Iterator[Technology] –

An iterator over the Technology objects contained in the collection.

len ¶

__len__() -> int

Return the number of technologies in this collection.

Returns:

int –

The number of Technology objects in the technologies list.

str ¶

__str__() -> str

Return a compact human-readable summary of the TechnologyCollection.

Returns:

str –

Summary with count and brief technology information.

append ¶

append(tech: Technology) -> Self

Append a technology to an existing TechnologyCollection.

Parameters:

tech (Technology) –

The technology to add.

Returns:

TechnologyCollection –

A new TechnologyCollection with the appended technology.

calculate_parameters ¶

calculate_parameters(targets: str | list[str] | None = None, equation_names: dict[str, str] | None = None) -> Self

Derive missing parameters of every contained Technology using registered equations.

Parameters:

targets (str or list of str, default: None ) –

Parameter names to derive. If None, for each technology all parameters that can be derived from its currently available parameters (and are not already present) are calculated automatically.
equation_names (dict of str to str, default: None ) –

Mapping of parameter name to equation name, used to override the default equation for specific targets (e.g. {"eac": "eac_simple"}).

Returns:

TechnologyCollection –

A new TechnologyCollection with the derived parameters added to each technology.

Raises:

ValueError –

If a requested target has no applicable equation, required parameters are missing, or input currencies are inconsistent, for any technology.

check_consistency ¶

check_consistency(parameters: Sequence[str] | None = None, equations: EquationRegistry | None = None, rtol: float = 1e-06, atol: float = 1e-09) -> list[dict[str, bool | str]]

Check equation-level consistency for selected parameters of every contained Technology.

See :meth:Technology.check_consistency for the semantics applied to each technology individually.

Parameters:

parameters (Sequence[str] | None, default: None ) –

The parameters to check for consistency. If None are specified, all parameters of each Technology are considered.
equations (EquationRegistry | None, default: None ) –

A registry of equations to check against. Defaults to technologydata.equation_registry.
rtol (float, default: 1e-06 ) –

Relative tolerance to use for checking consistency of the parameters.
atol (float, default: 1e-09 ) –

Absolute tolerance to use for checking consistency of the parameters.

Returns:

list[dict[str, bool | str]] –

Consistency status per checked equation, one dict per technology, in the same order as self.technologies.

Raises:

ValueError –

If parameters is given explicitly and includes a name for which no equation is registered, for any technology.

fit ¶

fit(parameter: str, model: GrowthModel, p0: dict[str, float] | None = None) -> GrowthModel

Fit a growth model to a specified parameter across all technologies in the collection.

This method aggregates data points for the specified parameter from all technologies in the collection, adds them to the provided growth model, and fits the model using the initial parameter guesses provided in p0.

Parameters:

parameter (str) –

The name of the parameter to fit the model to (e.g., "installed capacity").
model (GrowthModel) –

An instance of a growth model (e.g., LinearGrowth, ExponentialGrowth) to be fitted. May already be partially initialized with some parameters and/or data points.
p0 (dict[str, float], default: None ) –

Initial guess for the model parameters.

Returns:

GrowthModel –

The fitted growth model with optimized parameters.

Raises:

ValueError –

If the collection contains incompatible parameters with different units, heating values, or carriers.

from_json `classmethod` ¶

from_json(file_path: Path | str) -> Self

Load a TechnologyCollection instance from a JSON file.

Parameters:

file_path (Path or str) –

Path to the JSON file containing the data. Can be a pathlib.Path object or a string path.

Returns:

TechnologyCollection –

An instance of TechnologyCollection initialized with the data from the JSON file.

Raises:

TypeError –

If file_path is not a pathlib.Path or str.
ValueError –

If the file's schema_version differs from SCHEMA_VERSION.

get ¶

get(name: str | None = None, region: str | None = None, year: int | None = None, case: str | None = None, detailed_technology: str | None = None) -> Self

Filter technologies based on regex patterns for non-optional attributes.

Parameters not provided will match any value (equivalent to .* regex).

Parameters:

name (str, default: None ) –

Regex pattern to filter technology names. If None, matches all names.
region (str, default: None ) –

Regex pattern to filter region identifiers. If None, matches all regions.
year (int, default: None ) –

Regex pattern to filter the year of the data. If None, matches all years.
case (str, default: None ) –

Regex pattern to filter case or scenario identifiers. If None, matches all cases.
detailed_technology (str, default: None ) –

Regex pattern to filter detailed technology names. If None, matches all detailed technologies.

Returns:

TechnologyCollection –

A new TechnologyCollection with filtered technologies.

get_parameter ¶

get_parameter(name: str) -> list[Parameter | None]

Get parameter values across all technologies in the collection.

Parameters:

name (str) –

Parameter name to retrieve.

Returns:

list[Parameter | None] –

List with one entry per technology. None for technologies that don't have this parameter.

project ¶

project(to_years: list[int], parameters: dict[str, GrowthModel | str]) -> Self

Project specified parameters for all technologies in the collection to future years.

This method uses the provided growth models to project the specified parameters for each technology in the collection to the given future years.

To keep other parameters that should not be projected, add them to the dictionary as well without a growth model. Instead, there are other options available: 'mean', 'closest' and 'NaN'. 'mean' will set the parameter to the mean of all existing values in the collection, while 'NaN' will add the parameter with NaN values as a placeholder. 'closest' will set the parameter to the value of the closest year in the original data, with a preference for past years if equidistant. (Not yet implemented.)

The method creates new Technology objects for each combination of original technology and future year, applying the appropriate growth model projections.

Parameters:

to_years (list[int]) –

List of future years to which the parameters should be projected.
parameters (dict[str, GrowthModel | str]) –

A dictionary mapping parameter names to their respective growth models for projection. If provided, parameter and model cannot be used. To keep other parameters without projecting, available options are 'mean', 'closest' and 'NaN'.

Returns:

TechnologyCollection –

A new TechnologyCollection with technologies projected to the specified future years.

Raises:

ValueError –

If neither parameter and model, or parameters are not or all provided.

Examples:

>>> tc.project(
...     to_years=[2030, 2040],
...     parameters={
...         "installed capacity": LinearGrowth(m=0.5, A=10),
...         "lifetime": "mean",
...         "efficiency": "NaN"
...     }
... )

to_csv ¶

to_csv(**kwargs: Path | str | bool) -> None

Export the TechnologyCollection to a CSV file.

Parameters:

**kwargs (dict, default: {} ) –

Additional keyword arguments passed to pandas.DataFrame.to_csv(). Common options include: - path_or_buf : str or pathlib.Path or file-like object, optional File path or object, if None, the result is returned as a string. Default is None. - sep : str String of length 1. Field delimiter for the output file. Default is ','. - index : bool Write row names (index). Default is True. - encoding : str String representing the encoding to use in the output file. Default is 'utf-8'.

Notes

The method converts the collection to a pandas DataFrame using self.to_dataframe() and then writes it to a CSV file using the provided kwargs.

to_currency ¶

to_currency(target_currency: str, overwrite_country: None | str = None, source: str = 'worldbank') -> Self

Adjust the currency of all parameters of all contained Technology objects to the target currency.

The conversion includes inflation and exchange rates based on each Technology objects's region. If a different country should be used for inflation adjustment, use overwrite_country.

Parameters:

target_currency (str) –

The target currency (e.g., 'EUR_2020').
overwrite_country (str, default: None ) –

ISO 3166 alpha-3 country code to use for inflation adjustment instead of the object's region.
source (str, default: 'worldbank' ) –

The source of the inflation data, either "worldbank"/"wb" or "international_monetary_fund"/"imf". Defaults to "worldbank". Depending on the source, different years to adjust for inflation may be available.

Returns:

TechnologyCollection –

A new TechnologyCollection object with all its parameters adjusted to the target currency.

to_dataframe ¶

to_dataframe() -> DataFrame

Convert the TechnologyCollection to a pandas DataFrame.

Returns:

DataFrame –

A DataFrame containing the technology data.

to_json ¶

to_json(file_path: Path, schema_path: Path | None = None, output_schema: bool = False) -> None

Export the TechnologyCollection to a JSON file, together with a data schema.

Parameters:

file_path (Path) –

The path to the JSON file to be created.
schema_path (Path, default: None ) –

The path to the JSON schema file to be created. By default, created with a schema suffix next to file_path.
output_schema (bool, default: False ) –

If True, generates a JSON schema file describing the data structure. The schema will include field descriptions and type information.

TechnologyCollection ¶

schema_version class-attribute instance-attribute ¶

technologies instance-attribute ¶

__add__ ¶

__getitem__ ¶

__iter__ ¶

__len__ ¶

__str__ ¶

append ¶

calculate_parameters ¶

check_consistency ¶

fit ¶

from_json classmethod ¶

get ¶

get_parameter ¶

project ¶

to_csv ¶

to_currency ¶

to_dataframe ¶

to_json ¶

schema_version `class-attribute` `instance-attribute` ¶

technologies `instance-attribute` ¶

add ¶

getitem ¶

iter ¶

len ¶

str ¶

from_json `classmethod` ¶