bw_timex.dynamic_biosphere_builder

Module Contents

Classes

DynamicBiosphereBuilder

Class for building a dynamic biosphere matrix with dimensions (biosphere flow at a specific point in time) x (processes)

class bw_timex.dynamic_biosphere_builder.DynamicBiosphereBuilder(lca_obj: bw2calc.LCA, activity_time_mapping: dict, biosphere_time_mapping: dict, demand_timing: dict, node_collections: dict, temporal_grouping: str, database_dates: dict, database_dates_static: dict, timeline: pandas.DataFrame, interdatabase_activity_mapping: bw_timex.helper_classes.SetList, expand_technosphere: bool = True, background_unit_lci_cache: dict | None = None)

Class for building a dynamic biosphere matrix with dimensions (biosphere flow at a specific point in time) x (processes)

Initializes the DynamicBiosphereBuilder object.

Parameters:

• lca_obj (LCA object) – instance of the bw2calc LCA class, e.g. TimexLCA.lca

• activity_time_mapping (dict) – A dictionary mapping activity to their respective timing in the format ((‘database’, ‘code’), datetime_as_integer): time_mapping_id)

• biosphere_time_mapping (dict) – A dictionary mapping biosphere flows to their respective timing in the format ((‘database’, ‘code’), datetime_as_integer): time_mapping_id), empty at this point.

• demand_timing (dict) – A dictionary mapping of the demand to demand time

• node_collections (dict) – A dictionary containing lists of node ids for different node subsets

• temporal_grouping (str) – A string indicating the temporal grouping of the processes, e.g. ‘year’, ‘month’, ‘day’, ‘hour’

• database_dates (dict) – A dictionary mapping database names to their respective date

• database_dates_static (dict) – A dictionary mapping database names to their respective date, but only containing static databases, which are the background databases.

• timeline (pd.DataFrame) – The edge timeline, created from TimexLCA.build_timeline()

• interdatabase_activity_mapping (SetList) – A list of sets, where each set contains the activity ids of the same activity in different databases

• expand_technosphere (bool, optional) – A boolean indicating if the dynamic biosphere matrix is built via expanded matrices or directly from the timeline. Default is True.

Return type:

None

build_dynamic_biosphere_matrix(expand_technosphere: bool = True)

This function creates a separate biosphere matrix, with the dimensions (bio_flows at a specific time step) x (processes).

Every temporally resolved biosphere flow has its own row in the matrix, making it highly sparse. The timing of the emitting process and potential additional temporal information of the biosphere flow (e.g. delay of emission compared to the timing of the process) are considered.

Absolute Temporal Distributions for biosphere exchanges are dealt with as a look up function: If an activity happens at timestamp X and the biosphere exchange has an absolute temporal distribution (ATD), it looks up the amount from the ATD corresponding to timestamp X. E.g.: X = 2024, TD=(data=[2020,2021,2022,2023,2024,…..,2120], amount=[3,4,4,5,6,……,3]), it will look up the value 6 corresponding 2024. If timestamp X does not exist, it finds the nearest timestamp available (if two timestamps are equally close, it will take the first in order of appearance (see numpy.argmin() for this behavior).

Parameters:

expand_technosphere (bool, optional) – A boolean indicating if the dynamic biosphere matrix is built via expanded matrices or directly from the timeline. Default is via expanded matrices.

Returns:

• dynamic_biosphere_matrix (scipy.sparse.csr_matrix) – A sparse matrix with the dimensions (bio_flows at a specific time step) x (processes).

• temporal_market_lcis (dict) – A dictionary containing the disaggregated LCI’s of the temporal markets, with the time-mapped-activity id as key.

demand_from_timeline(row)

Returns a demand dict directly from the timeline row and its temporal_market_shares.

Parameters:

row: pd.Series

A row of the timeline DataFrame

returns:

demand – A demand-dictionary with as keys the ids of the time-mapped activities and as values the share.

rtype:

dict

demand_from_technosphere(idx, process_col_index)

Returns a demand dict of background processes based on the technosphere column. Foreground exchanges are skipped as these are added separately.

Parameters:

idx: int

The time-mapped-activity id of the producer

process_col_index: int

The technosphere matrix id of the producer

returns:

demand – A demand-dictionary with as keys the brightway ids of the consumed background activities and as values their consumed amount.

rtype:

dict

add_matrix_entry_for_biosphere_flows(row, col, amount)

Adds an entry to the internal matrix-entry mapping, which is then used to construct the dynamic biosphere matrix. Only unique entries are added, i.e. if the same row and col index already exists, the value is not added again.

Parameters:

• row (int) – A row index of a new element to the dynamic biosphere matrix

• col (int) – A column index of a new element to the dynamic biosphere matrix

• amount (float) – The amount of the new element to the dynamic biosphere matrix

Returns:

the internal matrix-entry mapping is updated

Return type:

None

get_biosphere_exchanges(original_db, original_code)

Return cached biosphere exchanges for a producer.

Keyed by the source database’s modified token so foreground or background edits invalidate stale entries automatically.

get_background_unit_lci(act)

Return unit background LCI matrix for an activity, cached by process identity.

Background activities can occur repeatedly with different exchange amounts. Reusing the unit LCI avoids repeated redo_lci solves for equivalent processes.

_inventory_to_triplets(inv)

Convert a CSR inventory matrix to structure-independent triplets.

Translates row/col indices into stable bioflow / activity ids via the producing lca_obj’s dicts, so the cache entry can be reused by lca_objs with different index spaces. Returns a tuple of three numpy arrays (bioflow_ids, activity_ids, values) — vectorized for speed (Python-tuple lists cost ~1.3 s on premise/ecoinvent).

_lca_obj_id_arrays()

row/col index → bioflow_id / activity_id, cached per builder.

_rebuild_unit_lci(triplets)

Rebuild a unit-LCI CSR sized to this lca_obj from cached triplets.

Entries referring to bioflows or activities not present in the current lca_obj are silently skipped. For consumers using the same set of databases this never drops anything; for legitimately narrower scenarios it correctly excludes out-of-scope entries.

count_pending_background_solves()

Count uncached background unit-LCI solves that the matrix build will need.

Walks the temporal-markets branch of build_dynamic_biosphere_matrix without performing any redo_lci solves — just consults the existing cache. TimexLCA uses this to decide whether LU-factorizing the technosphere upfront is worth it; factorization only pays off once the number of pending solves exceeds the break-even point.

get_background_lci_cache_key(act)

Build a stable cache key for background unit LCI reuse.