lydiaCG commited on
Commit
f3941ec
Β·
verified Β·
1 Parent(s): 358d27e

[DOC] README: British spelling (optimization -> optimisation, optimizer -> optimiser)

Browse files
Files changed (1) hide show
  1. README.md +12 -12
README.md CHANGED
@@ -9,9 +9,9 @@ app_file: app.py
9
  pinned: false
10
  ---
11
 
12
- # Carbon Dioxide Removal Optimizer
13
 
14
- A Streamlit app for optimizing carbon removal portfolios across different methods and constraints.
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 optimizer |
87
- | Portfolio generation | Portfolio generation | Run the LP optimizer 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,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 optimizer 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,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, optimization 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,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 optimizer. 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,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 optimizer 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,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 optimization. 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,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 optimization (`linprog`) | 🟑 Medium - optimization 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,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 optimization results.
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 optimization
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**