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_mass_balance(tolerance=0.0001)

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

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)

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

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)

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

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]