Add post-processing step for a grid and generate grid plot

.gitignore

@@ -274,3 +274,6 @@ tests/validation/
 CLAUDE.md
 .claude/
 .mcp.json
+
+# pickle files
+*.pkl

docs/How-to/usage.md

@@ -172,6 +172,39 @@ Use the CLI to package the results of a grid into a zip file; e.g. for sharing o
 ```console
 proteus grid-pack -o output/grid_demo/
 ```
+## Postprocessing of grid results
+
+Results from a PROTEUS grid can be post-processed using the `proteus grid-analyse` command. Running the analysis generates summary CSV files containing all tested input parameters and the final time-step outputs for each simulation, along with a status overview plot showing the distribution of simulation outcomes (e.g., completed, running, error) and empirical cumulative distribution function (ECDF) plots that summarize selected output variables across all completed simulations. (For more details on ECDF plots, see the [Seaborn `ecdfplot` documentation](https://seaborn.pydata.org/generated/seaborn.ecdfplot.html).)
+
+Before running the command, configure the post-processing options in your grid configuration file:`input/ensembles/example.grid.toml`. The following options can be set:
+
+- `update_csv` — Generate or update the CSV summary files
+- `plot_format` — Output format for plots (e.g., `png`, `pdf`)
+- `plot_status` — Enable/disable the status summary plot
+- `plot_ecdf` — Enable/disable ECDF plot generation
+- `output_variables` — List of variables to include in ECDF plots
+
+> **Note:**
+> The variables specified in `output_variables` must match column names in `runtime_helpfile.csv`.
+> The `solidification_time` is the only variable computed during post-processing and is not directly stored in the simulation output.
+
+---
+
+To post-process a grid and generate ECDF plots for further analysis, run the following command:
+
+```
+proteus grid-analyse --config input/ensembles/example.grid.toml
+```
+
+
+After execution, a `post_processing/` directory is created inside the grid folder with the following structure:
+
+- `extracted_data/` This directory contains three CSV files:
+    - `{grid_name}_final_extracted_data_all.csv` which includes every run in the grid
+    - `{grid_name}_final_extracted_data_completed.csv` which contains only successful runs (used for ECDF plots)
+    - `{grid_name}_final_extracted_data_running_error.csv` for only failed simulations with status `Running` or `Error`.
+
+- `grid_plots/` This directory contains a status summary plot and a ECDF plot
 
 ## Retrieval scheme (Bayesian optimisation)
 

input/ensembles/example.grid.toml

@@ -1,11 +1,21 @@
 # Config file for running a grid of forward models
 
 # Path to output folder where grid will be saved (relative to PROTEUS output folder)
-output = "grid_demo/"
+output = "scratch/grid_demo/"
 
 # Make `output` a symbolic link to this absolute location. To disable: set to empty string.
 symlink = ""
 
+# Post-processing options
+update_csv  = true                  # Whether to update the summary CSV files before plotting
+plot_format = "png"                 # Format for saving plots ("png" or "pdf")
+plot_status = true                  # Generate status summary plot of the grid
+plot_ecdf   = true                  # Generate ECDF grid plot for input parameters tested in the grid and output_variables defined below
+colormap    = "berlin"             # Colormap for ECDF plot (e.g. "viridis", "managua")
+output_variables = ["solidification_time", "Phi_global",
+                    "T_surf", "P_surf", "atm_kg_per_mol",
+                    "esc_rate_total", "rho_obs"]  # List of output variables to include in ECDF plot (name must match variable name in runtime_helpfile.csv)
+
 # Path to base (reference) config file relative to PROTEUS root folder
 ref_config = "input/demos/dummy.toml"
 

pyproject.toml

@@ -64,6 +64,7 @@ dependencies = [
     "ruff",
     "sympy",
     "astropy",
+    "seaborn",
     "torch",
     "botorch",
     "gpytorch",

src/proteus/cli.py

@@ -554,6 +554,24 @@ def observe(config_path: Path):
 cli.add_command(offchem)
 cli.add_command(observe)
 
+# ----------------
+# 'grid_analyse' postprocessing commands
+# ----------------
+
+
+@click.command()
+@config_option
+def grid_analyse(config_path: Path):
+    """Generate grid analysis plots and CSV summary files from a grid
+    config_path : Path to the toml file containing grid analysis configuration
+    """
+    from proteus.grid.post_processing import main
+
+    main(config_path)
+
+
+cli.add_command(grid_analyse)
+
 # ----------------
 # GridPROTEUS and BO inference scheme, runners
 # ----------------

src/proteus/config/_escape.py

@@ -26,7 +26,7 @@ class Zephyrus:
     Attributes
     ----------
     Pxuv: float
-        Pressure at which XUV radiation become opaque in the planetary atmosphere [bar]
+        Pressure at which XUV radiation becomes opaque in the planetary atmosphere (should be above Pxuv > 0 bar) [bar]
     efficiency: float
         Escape efficiency factor
     tidal: bool