Extract, analyze, and summarize simulation output data — pull spatial fields at specific timesteps, compute time-series trends and detect steady state, extract line profiles through the domain, generate statistical summaries and distributions, calculate derived quantities (gradients, fluxes, volume fractions, interface area), compare results against analytical solutions or experimental data, and produce automated analysis reports. Use when interpreting finished simulation results, checking mass or energy conservation, comparing two runs or meshes, extracting interface profiles from phase-field output, or preparing publication-quality analysis, even if the user only says "what do my results look like" or "did my simulation reach steady state."
Analyze and extract meaningful information from simulation output data.
Goal
Transform raw simulation output into actionable insights through field extraction, statistical analysis, derived quantities, visualizations, and comparison with reference data.
Inputs to Gather
Before running post-processing scripts, collect:
Output Data Location
Path to simulation output files (JSON, CSV, HDF5, VTK)
Time step/snapshot indices of interest
Field names to extract
Read field names from the file, never assume them. Before extracting,
open the output file (or run field_extractor.py --input <file> --list --json) and use only the field names that actually appear under fields.
Do not invent fields such as temperature if they are not present, and do
not assume a grid size — read the real shape/count from the data.
Analysis Type
Field extraction (spatial data at specific times)
Time series (temporal evolution of quantities)
Line profiles (1D cuts through domain)
Statistical summary (mean, std, distributions)
Derived quantities (gradients, integrals, fluxes)
Comparison to reference data
Output Requirements
Output format (JSON, CSV, tabular)
Visualization needs
Report format
Scripts
Script
Purpose
Key Inputs
field_extractor.py
Extract field data from output files
--input, --field, --timestep
time_series_analyzer.py
Analyze temporal evolution
--input, --quantity, --window
profile_extractor.py
Extract line profiles
--input, --field, --start, --end
statistical_analyzer.py
Compute field statistics
--input, --field, --region
derived_quantities.py
Calculate derived quantities
--input, --quantity, --params
comparison_tool.py
Compare to reference data
--simulation, --reference, --metric
report_generator.py
Generate summary reports
--input, --template, --output
Workflow
1. Data Inventory
First, understand what data is available:
# List available fields and timesteps
python scripts/field_extractor.py --input results/ --list --json
# Global statistics
python scripts/statistical_analyzer.py \
--input results/field_0100.json \
--field concentration \
--json
# Statistics in a specific spatial region (1D/2D fields only).
# Coordinates are derived from the field shape and grid spacing
# (explicit dx/dy, or Lx/Ly via dx = Lx/(nx-1)); only the variables
# x, y, z compared against numbers, joined by and/or, are allowed.
python scripts/statistical_analyzer.py \
--input results/field_0100.json \
--field phi \
--region "x>0.3 and x<0.7" \
--json
# Distribution analysis
python scripts/statistical_analyzer.py \
--input results/field_0100.json \
--field phi \
--histogram \
--bins 50 \
--json
Interpret convergence differently depending on the quantity type, because the
two signals the analyzer reports (convergence.{rate,type} and
steady_state.reached) answer different questions and can legitimately
disagree.
Judge convergence by absolute magnitude vs a tolerance: a residual at or
below the target tolerance (e.g. 1e-6) is converged. Use
--absolute-threshold <tol> to get the convergence_threshold block, which
is the physically correct test for residuals.
The relative --detect-steady-state test answers "has the residual stopped
changing?", not "has it converged?". For a still-decreasing residual,
steady_state.reached = false is expected and not a failure.
A plateau of a residual means a stalled solver
(convergence.type = "stalled"), not steady state.
Reconcile the signals: if convergence.type is fast/linear and the
final residual is small (or convergence_threshold.reached = true), report
the run as converged even when steady_state.reached = false.
Monotonic decrease in energy: system approaching equilibrium.
Plateau (steady_state.reached = true): steady state reached.
Oscillations: may indicate the time step is too large.
Sudden jumps: possible numerical instability.
Statistical Analysis
Bimodal distribution of order parameter: Two-phase mixture
High variance: Heterogeneous microstructure
Skewed distribution: Asymmetric phase fractions
Comparison Metrics
Metric
Interpretation
L2 error < 1%
Excellent agreement
L2 error 1-5%
Good agreement
L2 error 5-10%
Moderate agreement
L2 error > 10%
Poor agreement, investigate
Output Format
All scripts support the --json flag for machine-readable output. Most
scripts emit a flat top-level object whose keys depend on the script. For
example, field_extractor.py --include-data on a single field emits:
Notes on envelope shapes (they are not uniform across scripts):
field_extractor.py, statistical_analyzer.py, time_series_analyzer.py,
profile_extractor.py, and comparison_tool.py emit a flat object with a
source_file key plus script-specific result keys.
derived_quantities.py wraps its payload in an { "inputs": {...}, "results": {...} } envelope.
report_generator.py emits top-level report_version and generator
keys plus the requested report sections.
No script emits top-level script, version, or input_file keys, and
field statistics (min/max/mean/count) appear at the top level, not
nested under a data object.
Verification checklist
Before trusting or reporting a post-processing result, produce and record the
concrete evidence below (tied to this skill's scripts and output keys):
Listed the real fields first. Ran field_extractor.py --list --json
and recorded the actual fields names and shape; every later --field
argument is one that appears in that list (no assumed temperature, no
guessed grid size).
Used the right convergence test for the quantity type. For a residual/error,
recorded convergence_threshold.reached and final_value from
--absolute-threshold <tol> (the |x_final| <= tol test) rather than
relying on steady_state.reached; for a physical quantity, recorded
steady_state.{reached,relative_variation,value} from --detect-steady-state.
Reconciled the two convergence signals. Logged convergence.type and
convergence.rate alongside steady_state.reached, and confirmed a
convergence.type = "stalled" is read as a stalled solver (not steady
state), and a still-decreasing residual with steady_state.reached = false
is not reported as a failure.
Checked conservation against a tolerance. Recorded the conserved
integral (derived_quantities.py --quantity mass / integral, or
volume_fraction) at the first and last timestep and confirmed the drift
is within the documented tolerance for the dynamics (≈0 for Cahn-Hilliard
conserved order parameter; expected to change for Allen-Cahn).
Confirmed grid spacing is physical. Recorded the spacing block
(dx/dy/dz) echoed by derived_quantities.py and verified it came
from explicit dx/dy or the correct Lx/(nx-1) derivation — and that no
WARNING: explicit dx ... inconsistent with Lx line was emitted to stderr.
Verified no non-finite values corrupted the result. Confirmed
derived-quantity scripts did not raise Field contains non-finite value
(NaN/Inf) and that reported min/max are physically plausible (e.g. an
order parameter stays within its expected bounds).
Qualified comparison error against the documented bands. Recorded the
comparison_tool.py metric value (e.g. l2_error) and mapped it to the
agreement band in this skill (<1% excellent ... >10% poor, investigate),
confirming the simulation and reference were aligned/interpolated onto the
same axis first.
Common pitfalls & rationalizations
Tempting shortcut
Why it's wrong / what to do
"steady_state.reached = false, so the solver didn't converge."
The relative steady-state test asks "has it stopped changing?", which is false for a still-decreasing residual. For residuals use --absolute-threshold <tol> and read convergence_threshold.reached; reconcile with convergence.type/rate.
"The residual plateaued, so it reached steady state."
A flat residual is a stalled solver (convergence.type = "stalled", rate > 0.99), not convergence. Confirm the plateau value is actually at/below tolerance before calling it converged.
"I'll just extract temperature / assume a 256×256 grid."
Field names and shape are not guaranteed. Run field_extractor.py --list --json first and use only the fields and shape that the file actually reports.
"Two grids/runs agree, so the result is mesh-independent."
comparison_tool.py on two fields only bounds their difference; it does not establish the asymptotic range. Use >=3 resolutions to estimate an observed order before claiming mesh independence.
"Volume fraction looks stable, so mass is conserved."
A stable volume_fraction (a thresholded count) is not the conserved integral. Check --quantity integral/mass drift between first and last timestep against tolerance — and only expect ≈0 drift for conserved (Cahn-Hilliard) dynamics.
"Default dx=1.0 is fine for the derived quantity."
When no spacing is in the file the scripts fall back to dx=dy=dz=1.0, so any length/area/flux/integral is in grid units, not physical units. Supply --dx/--dy (or Lx/Ly in the file) and verify the echoed spacing block.
"It ran and emitted JSON, so the numbers are valid."
Completion is not correctness. Verify conservation drift, the convergence verdict, finite values, and the comparison error band before reporting.
Security
Input Validation
User-provided field names are validated against [a-zA-Z_][a-zA-Z0-9_.-]* to prevent injection via crafted field names
statistical_analyzer.py validates --region conditions against a strict allowlist before use: only the coordinate variables x, y, z compared (< <= > >= == !=) against numeric literals and joined by and/or are accepted; anything else exits with code 2. The parsed condition is applied as a real coordinate mask (no eval/exec), so the reported statistics describe the requested region
profile_extractor.py validates the field name against the same pattern and point coordinates as finite numbers with max 3 dimensions
--metric values in comparison_tool.py are validated against a fixed allowlist (l1_error, l2_error, linf_error, rmse, mae, max_difference, correlation, r_squared); unknown metrics return an error
--sections in report_generator.py are validated against the known section names (summary, statistics, convergence, validation, files, parameters, all); unknown sections exit with code 2
--bins (statistical_analyzer), --points (profile_extractor), and --window (time_series_analyzer) are validated as positive integers with upper bounds; out-of-range values exit with code 2
File Access
All JSON and CSV loading functions reject files exceeding 500 MB before parsing
Loaded JSON files must have an object (dict) as root element
report_generator.py caps directory listing at 10,000 entries to prevent resource exhaustion
Scripts read user-specified simulation output files (JSON, CSV) but do not traverse directories beyond what is explicitly provided
Output goes to stdout (JSON) unless the agent uses Write to save reports
Tool Restrictions
Read: Used to inspect script source, references, and simulation output files
Write: Used to save analysis results, comparison reports, or generated summaries; writes are scoped to the user's working directory
Grep/Glob: Used to locate simulation output files and search references
The skill's allowed-tools excludes Bash to prevent the agent from executing arbitrary commands when processing untrusted simulation output files
Safety Measures
No eval(), exec(), or dynamic code generation — region parsing uses regex matching, never code evaluation
All subprocess calls use explicit argument lists (no shell=True)
Reduced tool surface (no Bash) limits the agent to read/write operations only
Field names and region expressions are sanitized before use to prevent injection
references/comparison_metrics.md - Error metrics and interpretation
Requirements
Python 3.10+
NumPy (for numerical operations)
No other external dependencies for core functionality
Version History
See CHANGELOG.md for the authoritative record.
v1.1.3 (2026-06-24): Added a "Verification checklist" (evidence-based, tied to
the scripts' real output keys: field listing, residual-vs-physical convergence,
signal reconciliation, conservation drift, grid-spacing sanity, non-finite
guards, comparison error bands) and a "Common pitfalls & rationalizations"
table before the Security section. Documentation only; no script behavior change.
v1.1.2 (2026-06-23): Made the eval suite self-contained and discriminating —
copied the real fixtures into evals/files/ (only phi/concentration fields
on a 10x10 grid; residual series ending at 5e-6), rewrote every eval prompt to
reference those exact files, and added deterministic script_checks pinning the
verified script outputs (including the correct verdict that the 1e-6 absolute
residual threshold is NOT reached). Added guidance to read field names from the
output file rather than assuming them.
v1.1.1 (2026-06-23): Implemented real coordinate-based --region filtering in
statistical_analyzer.py; fixed report_generator.py to read nested
fields.*.values output; gave explicit dx/dy/dz precedence in
derived_quantities.py grid spacing; added an --absolute-threshold
convergence mode and residual-vs-physical interpretation guidance; corrected
the Output Format example and version metadata; added --bins/--window
bounds validation.
1---2name: post-processing3description: >4 Extract, analyze, and summarize simulation output data — pull spatial fields5 at specific timesteps, compute time-series trends and detect steady state,6 extract line profiles through the domain, generate statistical summaries7 and distributions, calculate derived quantities (gradients, fluxes, volume8 fractions, interface area), compare results against analytical solutions or9 experimental data, and produce automated analysis reports. Use when10 interpreting finished simulation results, checking mass or energy11 conservation, comparing two runs or meshes, extracting interface profiles12 from phase-field output, or preparing publication-quality analysis, even13 if the user only says "what do my results look like" or "did my simulation14 reach steady state."15allowed-tools: Read, Write, Grep, Glob16metadata:17 source: https://skillmd.com/skills/heshamfs/post-processing18 author: HeshamFS19 version: "1.1.3"20 security_tier: medium21 security_reviewed: true22 tested_with:23 - claude-code24 last_evaluated: "2026-06-23"25 eval_cases: 526 last_reviewed: "2026-06-23"27 standards:28 - "Lp error norms (L1/L2/L-infinity) for numerical convergence/verification studies"29 - "Sample variance with Bessel's correction (n-1 denominator)"30 - "Marching squares/cubes iso-surface extraction (Lorensen & Cline, 1987)"31 - "Central finite differences for gradient computation"32 - "Cahn-Hilliard (conserved) and Allen-Cahn (non-conserved) phase-field dynamics"33---3435# Post-Processing Skill3637Analyze and extract meaningful information from simulation output data.3839## Goal4041Transform raw simulation output into actionable insights through field extraction, statistical analysis, derived quantities, visualizations, and comparison with reference data.4243## Inputs to Gather4445Before running post-processing scripts, collect:46471. **Output Data Location**48 - Path to simulation output files (JSON, CSV, HDF5, VTK)49 - Time step/snapshot indices of interest50 - Field names to extract5152 > **Read field names from the file, never assume them.** Before extracting,53 > open the output file (or run `field_extractor.py --input <file> --list54 > --json`) and use only the field names that actually appear under `fields`.55 > Do not invent fields such as `temperature` if they are not present, and do56 > not assume a grid size — read the real `shape`/`count` from the data.57582. **Analysis Type**59 - Field extraction (spatial data at specific times)60 - Time series (temporal evolution of quantities)61 - Line profiles (1D cuts through domain)62 - Statistical summary (mean, std, distributions)63 - Derived quantities (gradients, integrals, fluxes)64 - Comparison to reference data65663. **Output Requirements**67 - Output format (JSON, CSV, tabular)68 - Visualization needs69 - Report format7071## Scripts7273| Script | Purpose | Key Inputs |74|--------|---------|------------|75| `field_extractor.py` | Extract field data from output files | --input, --field, --timestep |76| `time_series_analyzer.py` | Analyze temporal evolution | --input, --quantity, --window |77| `profile_extractor.py` | Extract line profiles | --input, --field, --start, --end |78| `statistical_analyzer.py` | Compute field statistics | --input, --field, --region |79| `derived_quantities.py` | Calculate derived quantities | --input, --quantity, --params |80| `comparison_tool.py` | Compare to reference data | --simulation, --reference, --metric |81| `report_generator.py` | Generate summary reports | --input, --template, --output |8283## Workflow8485### 1. Data Inventory8687First, understand what data is available:8889```bash90# List available fields and timesteps91python scripts/field_extractor.py --input results/ --list --json92```9394### 2. Field Extraction9596Extract spatial field data at specific timesteps:9798```bash99# Extract concentration field at timestep 100100python scripts/field_extractor.py \101 --input results/field_0100.json \102 --field concentration \103 --json104105# Extract multiple fields106python scripts/field_extractor.py \107 --input results/field_0100.json \108 --field "phi,concentration,temperature" \109 --json110```111112### 3. Time Series Analysis113114Analyze temporal evolution of quantities:115116```bash117# Extract total energy vs time118python scripts/time_series_analyzer.py \119 --input results/history.json \120 --quantity total_energy \121 --json122123# Compute moving average with window124python scripts/time_series_analyzer.py \125 --input results/history.json \126 --quantity mass \127 --window 10 \128 --json129130# Detect steady state (relative-variation test; best for physical quantities)131python scripts/time_series_analyzer.py \132 --input results/history.json \133 --quantity residual \134 --detect-steady-state \135 --tolerance 1e-6 \136 --json137138# Convergence by absolute threshold (physically correct test for residuals)139python scripts/time_series_analyzer.py \140 --input results/history.json \141 --quantity residual \142 --absolute-threshold 1e-6 \143 --json144```145146### 4. Line Profile Extraction147148Extract 1D profiles through the domain:149150```bash151# Extract profile along x-axis at y=0.5152python scripts/profile_extractor.py \153 --input results/field_0100.json \154 --field concentration \155 --start "0,0.5,0" \156 --end "1,0.5,0" \157 --points 100 \158 --json159160# Interface profile (through center)161python scripts/profile_extractor.py \162 --input results/field_0100.json \163 --field phi \164 --axis x \165 --slice-position 0.5 \166 --json167```168169### 5. Statistical Analysis170171Compute statistics over field data:172173```bash174# Global statistics175python scripts/statistical_analyzer.py \176 --input results/field_0100.json \177 --field concentration \178 --json179180# Statistics in a specific spatial region (1D/2D fields only).181# Coordinates are derived from the field shape and grid spacing182# (explicit dx/dy, or Lx/Ly via dx = Lx/(nx-1)); only the variables183# x, y, z compared against numbers, joined by and/or, are allowed.184python scripts/statistical_analyzer.py \185 --input results/field_0100.json \186 --field phi \187 --region "x>0.3 and x<0.7" \188 --json189190# Distribution analysis191python scripts/statistical_analyzer.py \192 --input results/field_0100.json \193 --field phi \194 --histogram \195 --bins 50 \196 --json197```198199### 6. Derived Quantities200201Calculate physical quantities from raw data:202203```bash204# Compute interface area205python scripts/derived_quantities.py \206 --input results/field_0100.json \207 --quantity interface_area \208 --threshold 0.5 \209 --json210211# Compute gradient magnitude212python scripts/derived_quantities.py \213 --input results/field_0100.json \214 --quantity gradient_magnitude \215 --field phi \216 --json217218# Compute volume fractions219python scripts/derived_quantities.py \220 --input results/field_0100.json \221 --quantity volume_fraction \222 --field phi \223 --threshold 0.5 \224 --json225226# Compute flux through boundary227python scripts/derived_quantities.py \228 --input results/field_0100.json \229 --quantity boundary_flux \230 --field concentration \231 --boundary "x=0" \232 --json233```234235### 7. Comparison with Reference236237Compare simulation results to reference data:238239```bash240# Compare to analytical solution241python scripts/comparison_tool.py \242 --simulation results/profile.json \243 --reference reference/analytical.json \244 --metric l2_error \245 --json246247# Compare to experimental data248python scripts/comparison_tool.py \249 --simulation results/history.json \250 --reference experimental_data.csv \251 --metric rmse \252 --interpolate \253 --json254255# Compare two simulations256python scripts/comparison_tool.py \257 --simulation results_fine/field.json \258 --reference results_coarse/field.json \259 --metric max_difference \260 --json261```262263### 8. Report Generation264265Generate automated reports:266267```bash268# Generate summary report269python scripts/report_generator.py \270 --input results/ \271 --output report.json \272 --json273274# Generate with specific sections275python scripts/report_generator.py \276 --input results/ \277 --sections "summary,statistics,convergence" \278 --output report.json \279 --json280```281282## Typical Post-Processing Pipeline283284For a complete simulation analysis:285286```bash287python scripts/field_extractor.py --input results/ --list --json # 1. inventory288python scripts/statistical_analyzer.py --input results/field_final.json --field phi --json # 2. final-state stats289python scripts/time_series_analyzer.py --input results/history.json --quantity residual --detect-steady-state --json # 3. convergence290python scripts/derived_quantities.py --input results/field_final.json --quantity volume_fraction --field phi --json # 4. derived quantities291python scripts/comparison_tool.py --simulation results/profile.json --reference benchmark/expected.json --metric l2_error --json # 5. compare to reference292python scripts/report_generator.py --input results/ --output analysis_report.json --json # 6. summary report293```294295## Interpretation Guidelines296297### Time Series Analysis298299Interpret convergence differently depending on the quantity type, because the300two signals the analyzer reports (`convergence.{rate,type}` and301`steady_state.reached`) answer different questions and can legitimately302disagree.303304**Residual / error quantities** (e.g. `residual`, `error`):305- Judge convergence by **absolute magnitude vs a tolerance**: a residual at or306 below the target tolerance (e.g. `1e-6`) is converged. Use307 `--absolute-threshold <tol>` to get the `convergence_threshold` block, which308 is the physically correct test for residuals.309- The relative `--detect-steady-state` test answers "has the residual stopped310 changing?", not "has it converged?". For a still-decreasing residual,311 `steady_state.reached = false` is **expected and not a failure**.312- A **plateau** of a residual means a **stalled** solver313 (`convergence.type = "stalled"`), not steady state.314- **Reconcile the signals**: if `convergence.type` is `fast`/`linear` and the315 final residual is small (or `convergence_threshold.reached = true`), report316 the run as **converged** even when `steady_state.reached = false`.317318**Physical quantities** (e.g. `energy`, `volume_fraction`, `mass`,319`interface_area`):320- **Monotonic decrease** in energy: system approaching equilibrium.321- **Plateau** (`steady_state.reached = true`): steady state reached.322- **Oscillations**: may indicate the time step is too large.323- **Sudden jumps**: possible numerical instability.324325### Statistical Analysis326- **Bimodal distribution** of order parameter: Two-phase mixture327- **High variance**: Heterogeneous microstructure328- **Skewed distribution**: Asymmetric phase fractions329330### Comparison Metrics331| Metric | Interpretation |332|--------|----------------|333| L2 error < 1% | Excellent agreement |334| L2 error 1-5% | Good agreement |335| L2 error 5-10% | Moderate agreement |336| L2 error > 10% | Poor agreement, investigate |337338## Output Format339340All scripts support the `--json` flag for machine-readable output. Most341scripts emit a **flat** top-level object whose keys depend on the script. For342example, `field_extractor.py --include-data` on a single field emits:343344```json345{346 "field": "concentration",347 "found": true,348 "data": [[0.1, 0.9], [0.3, 0.6]],349 "shape": [2, 2],350 "min": 0.1,351 "max": 0.9,352 "mean": 0.475,353 "count": 4,354 "source_file": "results/field_0100.json",355 "timestep_info": {"timestep": 100, "time": 1.5}356}357```358359Notes on envelope shapes (they are not uniform across scripts):360361- `field_extractor.py`, `statistical_analyzer.py`, `time_series_analyzer.py`,362 `profile_extractor.py`, and `comparison_tool.py` emit a flat object with a363 `source_file` key plus script-specific result keys.364- `derived_quantities.py` wraps its payload in an `{ "inputs": {...},365 "results": {...} }` envelope.366- `report_generator.py` emits top-level `report_version` and `generator`367 keys plus the requested report sections.368369No script emits top-level `script`, `version`, or `input_file` keys, and370field statistics (`min`/`max`/`mean`/`count`) appear at the top level, not371nested under a `data` object.372373## Verification checklist374375Before trusting or reporting a post-processing result, produce and record the376concrete evidence below (tied to this skill's scripts and output keys):377378- [ ] **Listed the real fields first.** Ran `field_extractor.py --list --json`379 and recorded the actual `fields` names and `shape`; every later `--field`380 argument is one that appears in that list (no assumed `temperature`, no381 guessed grid size).382- [ ] **Used the right convergence test for the quantity type.** For a residual/error,383 recorded `convergence_threshold.reached` and `final_value` from384 `--absolute-threshold <tol>` (the `|x_final| <= tol` test) rather than385 relying on `steady_state.reached`; for a physical quantity, recorded386 `steady_state.{reached,relative_variation,value}` from `--detect-steady-state`.387- [ ] **Reconciled the two convergence signals.** Logged `convergence.type` and388 `convergence.rate` alongside `steady_state.reached`, and confirmed a389 `convergence.type = "stalled"` is read as a stalled solver (not steady390 state), and a still-decreasing residual with `steady_state.reached = false`391 is not reported as a failure.392- [ ] **Checked conservation against a tolerance.** Recorded the conserved393 integral (`derived_quantities.py --quantity mass` / `integral`, or394 `volume_fraction`) at the first and last timestep and confirmed the drift395 is within the documented tolerance for the dynamics (≈0 for Cahn-Hilliard396 conserved order parameter; expected to change for Allen-Cahn).397- [ ] **Confirmed grid spacing is physical.** Recorded the `spacing` block398 (`dx`/`dy`/`dz`) echoed by `derived_quantities.py` and verified it came399 from explicit `dx`/`dy` or the correct `Lx/(nx-1)` derivation — and that no400 `WARNING: explicit dx ... inconsistent with Lx` line was emitted to stderr.401- [ ] **Verified no non-finite values corrupted the result.** Confirmed402 derived-quantity scripts did not raise `Field contains non-finite value`403 (NaN/Inf) and that reported `min`/`max` are physically plausible (e.g. an404 order parameter stays within its expected bounds).405- [ ] **Qualified comparison error against the documented bands.** Recorded the406 `comparison_tool.py` metric value (e.g. `l2_error`) and mapped it to the407 agreement band in this skill (<1% excellent ... >10% poor, investigate),408 confirming the simulation and reference were aligned/interpolated onto the409 same axis first.410411## Common pitfalls & rationalizations412413| Tempting shortcut | Why it's wrong / what to do |414|-------------------|-----------------------------|415| "`steady_state.reached = false`, so the solver didn't converge." | The relative steady-state test asks "has it stopped changing?", which is false for a still-decreasing residual. For residuals use `--absolute-threshold <tol>` and read `convergence_threshold.reached`; reconcile with `convergence.type`/`rate`. |416| "The residual plateaued, so it reached steady state." | A flat residual is a *stalled* solver (`convergence.type = "stalled"`, rate > 0.99), not convergence. Confirm the plateau value is actually at/below tolerance before calling it converged. |417| "I'll just extract `temperature` / assume a 256×256 grid." | Field names and shape are not guaranteed. Run `field_extractor.py --list --json` first and use only the `fields` and `shape` that the file actually reports. |418| "Two grids/runs agree, so the result is mesh-independent." | `comparison_tool.py` on two fields only bounds their difference; it does not establish the asymptotic range. Use >=3 resolutions to estimate an observed order before claiming mesh independence. |419| "Volume fraction looks stable, so mass is conserved." | A stable `volume_fraction` (a thresholded count) is not the conserved integral. Check `--quantity integral`/`mass` drift between first and last timestep against tolerance — and only expect ≈0 drift for conserved (Cahn-Hilliard) dynamics. |420| "Default `dx=1.0` is fine for the derived quantity." | When no spacing is in the file the scripts fall back to `dx=dy=dz=1.0`, so any length/area/flux/integral is in grid units, not physical units. Supply `--dx`/`--dy` (or `Lx`/`Ly` in the file) and verify the echoed `spacing` block. |421| "It ran and emitted JSON, so the numbers are valid." | Completion is not correctness. Verify conservation drift, the convergence verdict, finite values, and the comparison error band before reporting. |422423## Security424425### Input Validation426- User-provided field names are validated against `[a-zA-Z_][a-zA-Z0-9_.-]*` to prevent injection via crafted field names427- `statistical_analyzer.py` validates `--region` conditions against a strict allowlist before use: only the coordinate variables `x`, `y`, `z` compared (`< <= > >= == !=`) against numeric literals and joined by `and`/`or` are accepted; anything else exits with code 2. The parsed condition is applied as a real coordinate mask (no `eval`/`exec`), so the reported statistics describe the requested region428- `profile_extractor.py` validates the field name against the same pattern and point coordinates as finite numbers with max 3 dimensions429- `--metric` values in `comparison_tool.py` are validated against a fixed allowlist (`l1_error`, `l2_error`, `linf_error`, `rmse`, `mae`, `max_difference`, `correlation`, `r_squared`); unknown metrics return an error430- `--sections` in `report_generator.py` are validated against the known section names (`summary`, `statistics`, `convergence`, `validation`, `files`, `parameters`, `all`); unknown sections exit with code 2431- `--bins` (statistical_analyzer), `--points` (profile_extractor), and `--window` (time_series_analyzer) are validated as positive integers with upper bounds; out-of-range values exit with code 2432433### File Access434- All JSON and CSV loading functions reject files exceeding 500 MB before parsing435- Loaded JSON files must have an object (dict) as root element436- `report_generator.py` caps directory listing at 10,000 entries to prevent resource exhaustion437- Scripts read user-specified simulation output files (JSON, CSV) but do not traverse directories beyond what is explicitly provided438- Output goes to stdout (JSON) unless the agent uses Write to save reports439440### Tool Restrictions441- **Read**: Used to inspect script source, references, and simulation output files442- **Write**: Used to save analysis results, comparison reports, or generated summaries; writes are scoped to the user's working directory443- **Grep/Glob**: Used to locate simulation output files and search references444- The skill's `allowed-tools` excludes `Bash` to prevent the agent from executing arbitrary commands when processing untrusted simulation output files445446### Safety Measures447- No `eval()`, `exec()`, or dynamic code generation — region parsing uses regex matching, never code evaluation448- All subprocess calls use explicit argument lists (no `shell=True`)449- Reduced tool surface (no Bash) limits the agent to read/write operations only450- Field names and region expressions are sanitized before use to prevent injection451452## References453454For detailed information, see:455456- `references/data_formats.md` - Supported input/output formats457- `references/statistical_methods.md` - Statistical analysis methods458- `references/derived_quantities_guide.md` - Physical quantity calculations459- `references/comparison_metrics.md` - Error metrics and interpretation460461## Requirements462463- Python 3.10+464- NumPy (for numerical operations)465- No other external dependencies for core functionality466467## Version History468469See `CHANGELOG.md` for the authoritative record.470471- v1.1.3 (2026-06-24): Added a "Verification checklist" (evidence-based, tied to472 the scripts' real output keys: field listing, residual-vs-physical convergence,473 signal reconciliation, conservation drift, grid-spacing sanity, non-finite474 guards, comparison error bands) and a "Common pitfalls & rationalizations"475 table before the Security section. Documentation only; no script behavior change.476- v1.1.2 (2026-06-23): Made the eval suite self-contained and discriminating —477 copied the real fixtures into `evals/files/` (only `phi`/`concentration` fields478 on a 10x10 grid; residual series ending at 5e-6), rewrote every eval prompt to479 reference those exact files, and added deterministic `script_checks` pinning the480 verified script outputs (including the correct verdict that the 1e-6 absolute481 residual threshold is NOT reached). Added guidance to read field names from the482 output file rather than assuming them.483- v1.1.1 (2026-06-23): Implemented real coordinate-based `--region` filtering in484 `statistical_analyzer.py`; fixed `report_generator.py` to read nested485 `fields.*.values` output; gave explicit `dx`/`dy`/`dz` precedence in486 `derived_quantities.py` grid spacing; added an `--absolute-threshold`487 convergence mode and residual-vs-physical interpretation guidance; corrected488 the Output Format example and version metadata; added `--bins`/`--window`489 bounds validation.490- v1.1.0 (2026-03-26): Optimized description, evaluation suite, security review,491 standardized metadata, CHANGELOG.492- v1.0.0 (2026-02-25): Initial release.
Run npx get-skill add heshamfs/post-processing in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Extract, analyze, and summarize simulation output data — pull spatial fields at specific timesteps, compute time-series trends and detect steady state, extract line profiles through the domain, generate statistical summaries and distributions, calculate derived quantities (gradients, fluxes, volume fractions, interface area), compare results against analytical solutions or experimental data, and produce automated analysis reports. Use when interpreting finished simulation results, checking mass or energy conservation, comparing two runs or meshes, extracting interface profiles from phase-field output, or preparing publication-quality analysis, even if the user only says "what do my results look like" or "did my simulation reach steady state." It is listed under Research & Search on SkillMD.
This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: executes scripts. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
HeshamFS (@heshamfs) published this skill. Their other Agent Skills are listed on their SkillMD profile.