numerical-simulation

name

numerical-simulation

description

Build, run, validate, and document reproducible mathematical and scientific simulations in Python using NumPy, SciPy, pandas, Matplotlib, and Seaborn. Use when Codex needs to load raw tabular or numerical data, design numerical experiments, solve ODEs or optimization problems, compute statistics or sensitivity analyses, and output publication-quality scientific graphs from explicit plotting instructions while preserving original data.

Numerical Simulation

Overview

Use this skill to turn raw numerical inputs into reproducible simulation outputs, derived tables, and scientific figures. Keep original data read-only, make assumptions explicit, and write all generated artifacts to a clearly labeled derived output directory.

Workflow

1. Inspect the task, data files, expected model, requested plots, and required outputs.
2. Confirm or infer units, dimensions, missing-value conventions, random seeds, and constraints. Ask only when an assumption would change the scientific conclusion.
3. Read raw inputs with pandas or structured numerical loaders. Do not overwrite, filter, or re-save raw data in place.
4. Implement the simulation with NumPy arrays and SciPy routines:
   • ODEs: scipy.integrate.solve_ivp
   • optimization or fitting: scipy.optimize
   • sparse linear algebra: scipy.sparse and scipy.sparse.linalg
   • distributions/statistics: scipy.stats
5. Store intermediate and final derived data under an output directory such as Derived/, Results/, Figures/, or a user-provided path.
6. Plot with Matplotlib and Seaborn according to the user's instructions. Prefer direct scientific encodings over decorative styling.
7. Validate results with sanity checks: shapes, conservation laws, residuals, convergence flags, error metrics, seed reproducibility, and small known cases where possible.
8. Report the run command, input files, output files, random seeds, library assumptions, and any warnings.

Data Handling Rules

• Treat raw/source/original data as immutable.
• Use copies, derived files, or in-memory transforms for cleaning.
• Keep path handling explicit with pathlib.Path.
• Preserve indexes, labels, and units when converting between pandas objects and NumPy arrays.
• Record missing-value handling, normalization, scaling, filtering, or aggregation.
• For stochastic simulations, set and report a NumPy random generator seed: rng = np.random.default_rng(seed).

Reusable Runner

Use scripts/simulate_plot.py when the user needs a quick reproducible baseline from tabular data. It loads .csv, .tsv, .txt, or .xlsx, selects numeric columns, computes descriptive statistics and correlations, and writes scientific plots plus CSV summaries.

Example:

python scripts/simulate_plot.py --input raw.csv --output Derived/run-001 --plots line,scatter,heatmap --seed 123

Use the script as a scaffold for task-specific simulations: keep loading, validation, plotting, and output conventions, then replace or extend the run_analysis function with the requested mathematical model.

Plotting Guidance

Read references/plotting-guidelines.md when the user asks for publication-ready figures, journal-style graphs, multiple panels, uncertainty visualization, or precise Matplotlib/Seaborn styling.

Core defaults:

• Use Matplotlib for figure control and Seaborn for statistical styles.
• Include axis labels, units, legends, colorbars, captions or filenames that identify conditions, and high-DPI export.
• Save both raster and vector outputs when useful: .png for inspection and .pdf or .svg for manuscripts.
• Use colorblind-aware palettes for categorical comparisons.
• Avoid smoothing, interpolation, or normalization unless requested or scientifically justified.

Output Checklist

• run_metadata.json: timestamp, command, input paths, output paths, seed, package versions, assumptions.
• Derived data tables: cleaned/aggregated/simulated outputs with clear filenames.
• Figures: high-DPI plots with descriptive names.
• Short run note: methods, checks performed, and limitations.