MFA System

pydantic model flodym.MFASystem

An MFASystem class handles the calculation of a Material Flow Analysis system, which consists of a set of processes, flows, stocks defined over a set of dimensions. For the concrete definition of the system, a subclass of MFASystem must be implemented.

Example Define your MFA System:

>>> from flodym import MFASystem
>>> class CustomMFA(MFASystem):
>>>     def compute(self):
>>>         # do some computations on the CustomMFA attributes: stocks and flows

MFA flows, stocks and parameters are defined as instances of subclasses of flodym.FlodymArray. Dimensions are managed with the flodym.Dimension and flodym.DimensionSet.

Config:

  • protected_namespaces: tuple = ()

  • extra: str = allow

Fields:

  • dims (flodym.dimensions.DimensionSet)

  • flows (Dict[str, flodym.flodym_arrays.Flow])

  • parameters (Dict[str, flodym.flodym_arrays.Parameter])

  • processes (Dict[str, flodym.processes.Process])

  • stocks (Dict[str, flodym.stocks.Stock] | None)

field dims: DimensionSet [Required]

All dimensions that appear in the MFA system.

field flows: Dict[str, Flow] [Required]

The flows of the MFA system, i.e. the edges of the MFA system graph, as a dictionary mapping the names of the MFA system flows to the flows themselves.

field parameters: Dict[str, Parameter] [Required]

The parameters of the MFA system, as a dictionary mapping the names of the MFA system parameters to the parameters themselves.

field processes: Dict[str, Process] [Required]

The processes of the MFA system, i.e. the nodes of the MFA system graph, as a dictionary mapping the names of the MFA system processes to the processes themselves.

field stocks: Dict[str, Stock] | None = {}

The stocks of the MFA system, as a dictionary mapping the names of the MFA system stocks to the stocks themselves.

check_flows(exceptions=[], raise_error=False, verbose=False)

Check if all flows are non-negative.

Parameters:

  • exceptions (list[str]) – A list of strings representing flow names to be excluded from the check.

  • raise_error (bool) – If True, raises an error instead of logging warnings.

  • verbose (bool) – If True, logs detailed information about negative flows.

Raises:

ValueError – If a negative flow is found and raise_error is True.

Logs:

Warning: If a negative flow is found and raise_error is False. Info: If no negative flows are found.

check_mass_balance(tolerance=None, raise_error=True)

Compute mass balance, and check whether it is within a certain tolerance. Throw an error if it isn’t.

Parameters:

  • tolerance (float, optional) – The tolerance for the mass balance check. If None, defaults to 100 times the numpy float precision, multiplied by the maximum absolute flow or stock value.

  • raise_error (bool) – If True, raises an error if the mass balance check fails. Else, logs a warning and continues execution.

compute()

Perform all computations for the MFA system. This method must be implemented in a subclass of MFASystem.

classmethod from_csv(definition, dimension_files, parameter_files, allow_missing_parameter_values=False, allow_extra_parameter_values=False)

Define and set up the MFA system and load all required data from CSV files. Initialises stocks and flows with all zero values.

See flodym.CSVDimensionReader and flodym.CSVParameterReader, and flodym.FlodymArray.from_df() for expected format.

Parameters:

  • definition (MFADefinition) – The MFA definition object

  • dimension_files (dict) – A dictionary mapping dimension names to CSV files

  • parameter_files (dict) – A dictionary mapping parameter names to CSV files

  • allow_missing_parameter_values (bool) – Whether to allow missing values in the parameter data (missing rows or empty value cells)

  • allow_extra_parameter_values (bool) – Whether to allow extra values in the parameter data

classmethod from_data_reader(definition, data_reader)

Define and set up the MFA system and load all required data. Initialises stocks and flows with all zero values.

Parameters:
Return type:

MFASystem

classmethod from_excel(definition, dimension_files, parameter_files, dimension_sheets=None, parameter_sheets=None, allow_missing_parameter_values=False, allow_extra_parameter_values=False)

Define and set up the MFA system and load all required data from Excel files. Initialises stocks and flows with all zero values. Builds a CompoundDataReader from Excel readers, and calls the from_data_reader class method.

See flodym.ExcelDimensionReader, flodym.ExcelParameterReader, and flodym.FlodymArray.from_df() for expected format.

Parameters:

  • definition (MFADefinition) – The MFA definition object

  • dimension_files (dict) – A dictionary mapping dimension names to Excel files

  • parameter_files (dict) – A dictionary mapping parameter names to Excel files

  • dimension_sheets (dict | None) – A dictionary mapping dimension names to sheet names in the Excel files

  • parameter_sheets (dict | None) – A dictionary mapping parameter names to sheet names in the Excel files

  • allow_missing_parameter_values (bool) – Whether to allow missing values in the parameter data (missing rows or empty value cells)

  • allow_extra_parameter_values (bool) – Whether to allow extra values in the parameter data

get_new_array(dim_letters=None, **kwargs)

get a new FlodymArray object.

Parameters:

  • dim_letters (tuple | None) – tuple of dimension letters to include in the new FlodymArray. If None, all dimensions are included.

  • kwargs – keyword arguments to pass to the FlodymArray constructor.

Return type:

FlodymArray

flodym.make_empty_flows(processes, flow_definitions, dims, naming=<function process_names_with_arrow>)

Initialize all defined flows with zero values.

Parameters:

  • processes (dict[str, Process]) – Dictionary of processes, with process names as keys.

  • flow_definitions (list[FlowDefinition]) – List of flow definitions.

  • dims (DimensionSet) – DimensionSet object containing all dimensions.

  • naming (Callable[[Process, Process], str]) – Function to generate names for flows. Default is process_names_with_arrow.

Returns:

Dictionary of flows, with flow names as keys.

Return type:

dict[str, Flow]

flodym.make_empty_stocks(stock_definitions, processes, dims)

Initialise empty Stock objects for each of the stocks listed in stock definitions.

Parameters:
Return type:

dict[str, Stock]

flodym.make_processes(definitions)

Create a dictionary of processes from a list of process names.

Parameters:

definitions (List[str])

Return type:

dict[str, Process]