This repository operationalizes Statistical Entropy Analysis (SEA) on material flow data, including complex processes from process simulation software. The analysis requires only two types of inputs: (1) flow networks (links between flows, processes, and environment nodes) and (2) flow mass flow rate and mass concentration data.
statistical_entropy_analysis/
βββ main_sea.ipynb # Main Jupyter notebook for SEA analysis
βββ sea.xlsx # Input Excel file with process data
βββ LICENSE # MIT License
βββ README.md # This file
The sea.xlsx file contains multiple sheets, each representing a Unit Process in the material flow system. Each sheet must follow a specific structure to be correctly parsed by the notebook.
Each sheet (unit process) must contain the following mandatory columns:
| Column Name | Data Type | Description | Example Values |
|---|---|---|---|
flow_name |
String | Unique identifier for the flow | f_0-1_eol-libs, f_12-1_int-recycled |
flow_type |
String | Type of flow | product, waste, by-product |
provider/consumer |
String | Source or destination of the flow | economic environment, fu, u12_tank, background |
direction |
String | Flow direction relative to the process | input or output |
mass-FU_kg-eq |
Float | Mass flow rate in kg-equivalent per functional unit | 1.000, 0.581 |
After the mandatory columns, chemical element columns must be present. These columns represent the mass concentration (in weight percent, w%) of each chemical element in the flow.
Recognized chemical elements (2-letter symbols from the periodic table):
Al,C,Ca,Co,Cu,F,Fe,H,Li,Mn,Na,Ni,O,P,S- The notebook also recognizes
e-(electrons) andRestas special cases
Example element columns:
| Al | C | Ca | Co | Cu | e- | F | Fe | H | Li | Mn | Na | Ni | O | P | S |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 1.874 | 31.163 | 0.0 | 7.584 | 1.295 | 0.0 | 3.078 | 0.0 | 0.161 | 4.469 | 7.070 | 0.000 | 22.660 | 20.635 | 0.011 | 0.000 |
The following columns are optional and used for extended analysis:
| Column Name | Data Type | Description |
|---|---|---|
enthalpy_flowsheet_kW |
Float | Enthalpy in kW |
enthalpy-FU_MJ-eq |
Float | Enthalpy per functional unit in MJ-equivalent |
exergy_flowsheet_kW |
Float | Exergy in kW |
exergy-FU_MJ-eq |
Float | Exergy per functional unit in MJ-equivalent |
mass_flowsheet_t/h |
Float | Mass flow rate in tonnes per hour |
lca_upr_name_*, lca_upr_loc_*, lca_flow_name_*, amount_*, lca_database_* |
Mixed | Life Cycle Assessment (LCA) data for background processes |
- Each sheet name represents a Unit Process
- Sheet names should be unique and descriptive
- Example:
u1_black-mass-pulping,u2_leaching,u3_hydrated-lime_pulping - The prefix
ufollowed by a number is recommended for ordering
- Direction Values: Must be either
inputoroutput(case-insensitive) - Provider/Consumer Values:
- For flows from the environment/background: Use terms like
economic environment, fu,background,stock - For flows between processes: Use the exact sheet name of the connected process (e.g.,
u12_tank)
- For flows from the environment/background: Use terms like
- Mass Flow Rate: Must be numeric (float or integer)
- Element Concentrations: Must be numeric (float or integer), representing weight percent (w%)
| flow_name | flow_type | provider/consumer | direction | mass-FU_kg-eq | Al | C | Ca | ... |
|-----------|-----------|-------------------|-----------|---------------|----|---|----|-----|
| f_0-1_eol-libs | product | economic environment, fu | input | 1.000 | 1.874 | 31.163 | 0.0 | ... |
| f_0-1_HF-heating | product | background | input | 0.000 | 0.0 | 0.0 | 0.0 | ... |
| f_12-1_int-recycled | product | u12_tank | input | 0.581 | 0.0 | 0.139 | 0.0 | ... |
| f_1-2_black-mass | product | u2_leaching | output | 1.581 | 1.874 | 31.163 | 0.0 | ... |
To create a compatible Excel file:
- Create a new Excel workbook
- Add sheets for each unit process in your system
- Include all mandatory columns in each sheet
- Add chemical element columns for all elements present in your flows
- Ensure data consistency:
- All flows must have valid
flow_namevalues directionmust be eitherinputoroutputprovider/consumermust reference either another process sheet or an environment/background source- Element concentrations must sum to approximately 100% (or less if
Restis used)
- All flows must have valid
- Save as
.xlsxformat (Excel Workbook)
Before running the notebook, verify your Excel file:
- Each sheet has a unique name
- All mandatory columns are present
- Chemical element columns use valid 1-2 letter symbols
-
directioncolumn contains onlyinputoroutput -
mass-FU_kg-eqcolumn contains numeric values - Element concentration values are numeric (0-100 range)
-
provider/consumerreferences are valid (either environment or existing process sheets)
The main_sea.ipynb notebook implements a complete Statistical Entropy Analysis workflow following the methodology described in:
- Rechberger & Graedel (2002) - The contemporary European copper cycle: statistical entropy analysis
- Laner et al. (2017) - Material flow analysis and statistical entropy for the assessment of recycling systems
Cells 1-4: Setup and configuration
-
Cell 1: Import required libraries
numpy,pandas- Data manipulationmatplotlib- Visualizationmendeleev- Chemical element validation (optional, with fallback)collections- Data structures for graph traversal
-
Cell 2: Define local paths
- Set
file_pathvariable to point to your Excel file location - Default:
excel_file_path = "sea.xlsx"(file in same directory)
- Set
-
Cell 3: Chemical element recognition
is_chemical_element()function validates column names as chemical elements- Supports standard periodic table symbols (1-2 letters)
- Special case:
"Rest"is treated as a valid component - Fallback mechanism if
mendeleevlibrary is not available
Cells 5-7: Mass balance verification
- Function:
check_mass_balance_per_element(excel_file) - Purpose: Validates mass balance for each process and element
- Output:
- Detailed mass balance per element (input vs output)
- Overall mass balance per process
- Relative error percentages
- Identification of largest imbalances
- Key Metrics:
- Total input/output mass (t/h)
- Element-wise mass flows (kg/h)
- Balance error and relative error (%)
Note: This step ensures data quality before proceeding with SEA calculations.
Cells 8-20: Process ranking and stage diagram creation
This section implements the stage diagram methodology from Rechberger & Graedel (2002):
"The number of stages in the system is defined as one more than the number of processes. If the system contains n_P processes, the number of stages n_S is given by: n_S = n_P + 1"
Subsections:
-
Get Original Processes (Cell 13)
get_original_processes(excel_file)- Identifies root nodes- Criteria: Processes with
"fu"in input provider OR no process inputs
-
Process Ranking (Cells 15-16)
assign_process_ranks_all_options()- Assigns ranks using BFS from each original process- Handles recycling flows (flows where producer rank β₯ consumer rank)
- Implements back-propagation for unranked providers
- Generates multiple ranking options (one per original process)
-
Flow Distinctions (Cell 17)
get_internal_recycling_flows()- Detects recycling flowsget_input_environment_flows()- Identifies environment inputsget_output_environment_flows()- Identifies environment outputsget_intermediate_foreground_product_flows()- Identifies intermediate flows
-
Stages Creation (Cells 19-20)
build_system_2stage_dataframes()- Creates 2-stage system diagrambuild_stage_flow_dataframes()- Builds dataframes for each stage- Stage Assignment Rules:
- Environment inputs: Stages 1 to consumer_rank
- Intermediate flows: provider_rank+1 to consumer_rank
- Environment outputs: producer_rank+1 to max_stage
- Recycling flows: Special handling for backward flows
Cells 21-30: Execute ranking and stage construction
- Select ranking option (manual or automatic)
- Generate stage dataframes
- Create visual stage diagram
Output:
stage_dfs[i]- DataFrame for each stage i, containing all flows in that stage- Ranking CSV files for each option
- Recycling flow identification
Cell 32: Validate mass balance at stage level
- Ensures mass conservation across stages
- Prepares data for entropy calculations
Cells 34-41: Statistical Entropy Analysis computation
Key Functions:
-
For One Stage (Cell 36)
compute_stage_entropy()- Calculates entropy for a single stage- Adds 3 columns to stage DataFrame:
- Shannon entropy
- Rechberger entropy
- Relative Statistical Entropy (RSE)
-
For Elements (Cell 39)
- Element-wise entropy calculations
- Contribution analysis per element
-
General (Cell 41)
- Aggregated entropy metrics
- System-level indicators
Entropy Formulas:
- Shannon Entropy: H = -Ξ£ (p_i Γ logβ(p_i))
- Where p_i is the mass fraction of flow i
- Rechberger Entropy: Modified Shannon entropy for material flows
- Relative Statistical Entropy (RSE): Normalized entropy measure
Cells 43-47: Run complete analysis and visualize results
- Execute all SEA computations
- Generate plots and charts
- Example: O concentration vs. O RSE contribution
Cells 49-57: Advanced analysis and interpretation
- Compare flows between stages - Track entropy changes through the system
- Contribution analysis - Identify which flows/elements contribute most to entropy
- Element listing - Detailed breakdown by chemical element
The notebook requires the following Python packages:
pip install numpy pandas matplotlib openpyxl mendeleevOptional: If mendeleev is not available, the notebook falls back to a predefined list of chemical symbols.
- Recommended: Python 3.8+
- Tested with: Python 3.10+
-
Clone the repository:
git clone https://github.com/LouisFreboeuf/statistical_entropy_analysis.git cd statistical_entropy_analysis -
Install dependencies:
pip install numpy pandas matplotlib openpyxl mendeleev
-
Prepare your data:
- Create
sea.xlsxfollowing the structure described above - Or use the provided example file
- Create
-
Run the notebook:
jupyter notebook main_sea.ipynb
-
Follow the workflow:
- Execute cells in order
- Review mass balance results
- Select ranking option if multiple original processes exist
- Analyze SEA results
The SEA methodology implemented in this repository is based on:
-
Rechberger, H., & Graedel, T. E. (2002). The contemporary European copper cycle: statistical entropy analysis. Center for Industrial Ecology, School of Forestry and Environmental Studies, Yale University. DOI:10.1016/j.ecolind.2017.07.060
-
Laner, D., Rechberger, H., & Astner, I. (2017). Material flow analysis and statistical entropy for the assessment of recycling systems. Ecological Indicators, 81, 148-158.
- Statistical Entropy: Measure of disorder or uncertainty in a system
- Material Flow Analysis (MFA): Tracking materials through a system
- Stage Diagram: Representation of material flows through sequential stages
- Recycling Flows: Material flows that loop back to earlier stages
If you use this repository or its methodology in your research, please cite it using the provided CITATION.cff file. This file follows the Citation File Format standard and is compatible with Zenodo and other citation tools.
-
Using the
CITATION.cfffile:- Many reference managers (e.g., Zotero) and platforms (e.g., Zenodo) automatically recognize this file.
- Example citation (APA style):
Freboeuf, L. (2026). Statistical Entropy Analysis (SEA) Repository (Version 1.0.0) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.XXXXXXX
-
Manual Citation:
- Format: Author (Year). Title (Version). [Computer software]. Repository URL. DOI (if available).
-
BibTeX Entry:
@software{Freboeuf2026StatisticalEntropyAnalysis, author = {Freboeuf, Louis}, title = {Statistical Entropy Analysis (SEA) Repository}, year = {2026}, version = {1.0.0}, publisher = {Zenodo}, doi = {10.5281/zenodo.XXXXXXX}, url = {https://github.com/LouisFreboeuf/statistical_entropy_analysis} }
This repository is configured for seamless integration with Zenodo. To create a citable archive:
- Connect your GitHub account to Zenodo.
- Enable the repository for automatic archiving.
- Create a GitHub release (e.g.,
v1.0.0). - Zenodo will automatically archive the release and assign a DOI.
This repository is licensed under the MIT License (see LICENSE file).
Permissions:
- β Free to use, copy, modify, merge
- β Free to publish, distribute, sublicense
- β Free to sell copies
- β Must include copyright notice and license in all copies
- β No liability or warranty provided
- Copyright: Β© 2026 LouisFreboeuf
- Attribution: When using this code or methodology, please cite the original repository and relevant academic papers
- The example
sea.xlsxfile contains simulated process data - No real-world proprietary data is included
- Users are responsible for ensuring their own data complies with privacy regulations
While this repository is currently a single-author project, contributions are welcome:
- Fork the repository
- Create a feature branch
- Submit a pull request with clear description of changes
- Ensure all tests pass (if applicable)
- Maintain code style and documentation standards
- This repository contains no sensitive credentials or API keys
- All data is synthetic and for demonstration purposes
- Users should not commit real-world sensitive data to public repositories
For questions or issues:
- Check this README for Excel file structure requirements
- Review the notebook comments for detailed explanations
- Consult the referenced papers for methodological questions
- Open an issue on GitHub for bugs or feature requests
This SEA implementation is suitable for:
- Recycling system analysis - Evaluate material recovery efficiency
- Process optimization - Identify entropy hotspots in material flows
- Sustainability assessment - Quantify resource dissipation
- Circular economy studies - Analyze material loop closure
- Industrial ecology - Model complex material flow networks
Last updated: July 2026 Maintainer: LouisFreboeuf