Spaces:
Sleeping
Sleeping
[DOC] README: British spelling (optimization -> optimisation, optimizer -> optimiser)
Browse files
README.md
CHANGED
|
@@ -9,9 +9,9 @@ app_file: app.py
|
|
| 9 |
pinned: false
|
| 10 |
---
|
| 11 |
|
| 12 |
-
# Carbon Dioxide Removal
|
| 13 |
|
| 14 |
-
A Streamlit app for
|
| 15 |
|
| 16 |
---
|
| 17 |
|
|
@@ -83,8 +83,8 @@ The app has seven tabs, accessible from the left sidebar:
|
|
| 83 |
| Welcome | Welcome | Introduction, instructions, and a quick-start guide |
|
| 84 |
| Resource inputs | Resource inputs | Set the available quantity of each resource; add custom resource batches |
|
| 85 |
| Method constraints | Method constraints | Activate or deactivate CDR methods; set caps and constraints per method |
|
| 86 |
-
| Resource coefficients | Resource coefficients | View and adjust the coefficient values (min / median / max) used by the
|
| 87 |
-
| Portfolio generation | Portfolio generation | Run the LP
|
| 88 |
| Sensitivity analysis | Sensitivity analysis | Analyse how binding each resource constraint is; identify bottlenecks |
|
| 89 |
| Scenario comparison | Scenario comparison | Save the current scenario, load a previous one, and compare multiple runs side by side |
|
| 90 |
|
|
@@ -94,7 +94,7 @@ The app has seven tabs, accessible from the left sidebar:
|
|
| 94 |
|
| 95 |
In the **Resource inputs** tab, users can add custom resource batches β named resources that substitute for a standard or "Other" reference resource within a specific CDR method.
|
| 96 |
|
| 97 |
-
For example, a user might add a batch called "Basalt A" linked to the reference group "Basalt mineral" and assign it to the Enhanced weathering method. The
|
| 98 |
|
| 99 |
Custom batches are stored in the session and saved when exporting a scenario. They do **not** require any change to `inputs_aggregated.csv`.
|
| 100 |
|
|
@@ -104,7 +104,7 @@ Custom batches are stored in the session and saved when exporting a scenario. Th
|
|
| 104 |
|
| 105 |
In the **Scenario comparison** tab, users can:
|
| 106 |
|
| 107 |
-
- **Export** the current state (resource caps, method constraints, coefficients,
|
| 108 |
- **Import** a previously exported scenario file to restore a complete session state
|
| 109 |
- **Compare** multiple saved scenarios side by side in the charts
|
| 110 |
|
|
@@ -282,7 +282,7 @@ Each row represents **one resource used by one CDR method**, with the following
|
|
| 282 |
|
| 283 |
> **Naming convention β "Other" resources:** any resource whose name starts with `Other ` (capital O, followed by a space β e.g. `Other land`, `Other water`) is **hidden from the standard resource display** in Tabs 1 and 3. It still functions normally in the model and remains available as a reference group in the "Add resource" dialog. Use this convention intentionally when you want a resource to be inherited by custom user-defined batches but not shown as a standalone input row.
|
| 284 |
|
| 285 |
-
> **Naming convention β "Other" methods:** any CDR method whose name starts with `Other` receives special treatment in the
|
| 286 |
|
| 287 |
---
|
| 288 |
|
|
@@ -363,7 +363,7 @@ You should see `(venv)` at the start of your terminal line.
|
|
| 363 |
|
| 364 |
**When to use:** A new carbon removal approach needs to be added to the tool.
|
| 365 |
|
| 366 |
-
> β οΈ **"Other" method naming:** if the method name starts with `Other` (e.g. `Other CDR`), the
|
| 367 |
|
| 368 |
**Option 1 - On Hugging Face**
|
| 369 |
|
|
@@ -615,7 +615,7 @@ This section explains how to keep the tool's software dependencies up to date, s
|
|
| 615 |
|
| 616 |
### What is a library (dependency)?
|
| 617 |
|
| 618 |
-
The tool is built on top of external software packages ("libraries") that handle things like displaying the interface, reading Excel files, or running the
|
| 619 |
|
| 620 |
Libraries sometimes release updates - fixing bugs, patching security holes, or adding new features. The risk is that an update can also change how a library behaves and break the tool.
|
| 621 |
|
|
@@ -631,7 +631,7 @@ These are the libraries that matter most for this tool:
|
|
| 631 |
| **streamlit-option-menu** | The navigation sidebar menu | π‘ Medium - must stay compatible with streamlit version |
|
| 632 |
| **pandas** | Reads and processes CSV and Excel files | π‘ Medium - occasional API changes |
|
| 633 |
| **numpy** | Numerical operations (arrays, math) | π‘ Medium - used by scipy and pandas |
|
| 634 |
-
| **scipy** | Runs the LP
|
| 635 |
| **plotly** | All charts and interactive graphs | π‘ Medium - chart API evolves |
|
| 636 |
| **openpyxl** | Reads and writes Excel files (.xlsx) | π’ Low - stable API |
|
| 637 |
| **pillow** | Image handling (indirect use) | π’ Low |
|
|
@@ -675,7 +675,7 @@ openpyxl βββββββββββββββΊ pillow
|
|
| 675 |
|
| 676 |
#### β
Update when needed
|
| 677 |
- **Streamlit** - when a new feature in the app requires it, or when a critical bug in the current version is causing problems.
|
| 678 |
-
- **pandas / numpy / scipy** - when a bug in the current version is causing incorrect data processing or
|
| 679 |
- **openpyxl** - when Excel import/export breaks with newer `.xlsx` files.
|
| 680 |
|
| 681 |
#### β Do NOT update just because a newer version exists
|
|
@@ -744,7 +744,7 @@ pip freeze > requirements.txt
|
|
| 744 |
- Start the app: `streamlit run app.py`
|
| 745 |
- Go through every tab
|
| 746 |
- Import and export an Excel file
|
| 747 |
-
- Run an
|
| 748 |
- Check that charts display correctly
|
| 749 |
|
| 750 |
**Step 7 - If something breaks**
|
|
|
|
| 9 |
pinned: false
|
| 10 |
---
|
| 11 |
|
| 12 |
+
# Carbon Dioxide Removal Optimiser
|
| 13 |
|
| 14 |
+
A Streamlit app for optimising carbon removal portfolios across different methods and constraints.
|
| 15 |
|
| 16 |
---
|
| 17 |
|
|
|
|
| 83 |
| Welcome | Welcome | Introduction, instructions, and a quick-start guide |
|
| 84 |
| Resource inputs | Resource inputs | Set the available quantity of each resource; add custom resource batches |
|
| 85 |
| Method constraints | Method constraints | Activate or deactivate CDR methods; set caps and constraints per method |
|
| 86 |
+
| Resource coefficients | Resource coefficients | View and adjust the coefficient values (min / median / max) used by the optimiser |
|
| 87 |
+
| Portfolio generation | Portfolio generation | Run the LP optimiser and view results (charts, tables, resource usage) |
|
| 88 |
| Sensitivity analysis | Sensitivity analysis | Analyse how binding each resource constraint is; identify bottlenecks |
|
| 89 |
| Scenario comparison | Scenario comparison | Save the current scenario, load a previous one, and compare multiple runs side by side |
|
| 90 |
|
|
|
|
| 94 |
|
| 95 |
In the **Resource inputs** tab, users can add custom resource batches β named resources that substitute for a standard or "Other" reference resource within a specific CDR method.
|
| 96 |
|
| 97 |
+
For example, a user might add a batch called "Basalt A" linked to the reference group "Basalt mineral" and assign it to the Enhanced weathering method. The optimiser will then use the batch's custom coefficients instead of the standard reference values for that method.
|
| 98 |
|
| 99 |
Custom batches are stored in the session and saved when exporting a scenario. They do **not** require any change to `inputs_aggregated.csv`.
|
| 100 |
|
|
|
|
| 104 |
|
| 105 |
In the **Scenario comparison** tab, users can:
|
| 106 |
|
| 107 |
+
- **Export** the current state (resource caps, method constraints, coefficients, optimisation results) as a `.zip` file or an Excel `.xlsx` file
|
| 108 |
- **Import** a previously exported scenario file to restore a complete session state
|
| 109 |
- **Compare** multiple saved scenarios side by side in the charts
|
| 110 |
|
|
|
|
| 282 |
|
| 283 |
> **Naming convention β "Other" resources:** any resource whose name starts with `Other ` (capital O, followed by a space β e.g. `Other land`, `Other water`) is **hidden from the standard resource display** in Tabs 1 and 3. It still functions normally in the model and remains available as a reference group in the "Add resource" dialog. Use this convention intentionally when you want a resource to be inherited by custom user-defined batches but not shown as a standalone input row.
|
| 284 |
|
| 285 |
+
> **Naming convention β "Other" methods:** any CDR method whose name starts with `Other` receives special treatment in the optimiser. Instead of appearing as a fixed method, the LP automatically creates **one variant per custom resource batch** the user adds that is linked to that method. This is intended for generic CDR pathways where the type of resource is user-defined. If you add a method using this naming convention, make sure it is intentional.
|
| 286 |
|
| 287 |
---
|
| 288 |
|
|
|
|
| 363 |
|
| 364 |
**When to use:** A new carbon removal approach needs to be added to the tool.
|
| 365 |
|
| 366 |
+
> β οΈ **"Other" method naming:** if the method name starts with `Other` (e.g. `Other CDR`), the optimiser treats it specially β it creates one variant per custom resource batch that the user links to this method, instead of running it as a fixed method. Only use this naming if that expansion behavior is intentional. For a standard CDR method with defined resource inputs, use a name that does not start with `Other`.
|
| 367 |
|
| 368 |
**Option 1 - On Hugging Face**
|
| 369 |
|
|
|
|
| 615 |
|
| 616 |
### What is a library (dependency)?
|
| 617 |
|
| 618 |
+
The tool is built on top of external software packages ("libraries") that handle things like displaying the interface, reading Excel files, or running the optimisation. These libraries are listed in `requirements.txt` with their exact version numbers (e.g., `streamlit==1.45.1`).
|
| 619 |
|
| 620 |
Libraries sometimes release updates - fixing bugs, patching security holes, or adding new features. The risk is that an update can also change how a library behaves and break the tool.
|
| 621 |
|
|
|
|
| 631 |
| **streamlit-option-menu** | The navigation sidebar menu | π‘ Medium - must stay compatible with streamlit version |
|
| 632 |
| **pandas** | Reads and processes CSV and Excel files | π‘ Medium - occasional API changes |
|
| 633 |
| **numpy** | Numerical operations (arrays, math) | π‘ Medium - used by scipy and pandas |
|
| 634 |
+
| **scipy** | Runs the LP optimisation (`linprog`) | π‘ Medium - optimisation results could change |
|
| 635 |
| **plotly** | All charts and interactive graphs | π‘ Medium - chart API evolves |
|
| 636 |
| **openpyxl** | Reads and writes Excel files (.xlsx) | π’ Low - stable API |
|
| 637 |
| **pillow** | Image handling (indirect use) | π’ Low |
|
|
|
|
| 675 |
|
| 676 |
#### β
Update when needed
|
| 677 |
- **Streamlit** - when a new feature in the app requires it, or when a critical bug in the current version is causing problems.
|
| 678 |
+
- **pandas / numpy / scipy** - when a bug in the current version is causing incorrect data processing or optimisation results.
|
| 679 |
- **openpyxl** - when Excel import/export breaks with newer `.xlsx` files.
|
| 680 |
|
| 681 |
#### β Do NOT update just because a newer version exists
|
|
|
|
| 744 |
- Start the app: `streamlit run app.py`
|
| 745 |
- Go through every tab
|
| 746 |
- Import and export an Excel file
|
| 747 |
+
- Run an optimisation
|
| 748 |
- Check that charts display correctly
|
| 749 |
|
| 750 |
**Step 7 - If something breaks**
|