skills/fluidsim/references/output_analysis.md
Output analysis can detect errors and quantify diagnostics. It cannot by itself establish:
Keep plotting descriptive until those checks pass.
Official 0.9 source selects:
.nc with h5netcdf when h5py lacks MPI support (normal default)..h5 with h5py when h5py is MPI-enabled.Filename:
state_phys_t<TIME>[_it<ITERATION>].nc
or .h5, depending on the backend. The file is HDF5-backed in either current
path. It contains:
/state_phys: solver state datasets./state_phys attributes including time, it, variable type, and purpose./info_simul: solver and parameter provenance.Do not infer the latest valid checkpoint solely from a filename. Verify HDF5
readability, /state_phys, time/iteration attributes, expected datasets,
parameters, state parameters, size, and checksum.
Exact outputs depend on the solver and enabled classes.
spatial_means.txt, generally repeated
key = value records.spatial_means.json, JSON-lines records.Use the solver's load() implementation. It can return a dictionary, pandas
object, or another solver-specific structure; do not assume one universal
DataFrame schema.
Current 2D base spectra initialize:
spectra1D.h5
spectra2D.h5
Common datasets include:
timeskxE, kyE, or khEspectrum1D* or spectrum2D* arraysNS2D/NS3D and stratified variants define different keys and dimensions.
load1d_mean()/load2d_mean() return dictionaries in the base implementation;
inspect keys before use.
The current base filename is:
spect_energy_budg.h5
For NS2D, current source computes transfer2D_E and transfer2D_Z and derives
fluxes with a reverse cumulative sum multiplied by wave-number spacing. Other
solvers define different transfer/budget terms.
Do not interpret a transfer sign, flux plateau, or cascade without verifying:
A normal run may include:
params_simul.xmlinfo_solver.xmlstdout.txtInventory actual contents instead of assuming all files exist.
python3 scripts/output_inventory.py \
--path run-directory \
--max-files 256 \
--max-hdf5-files 32 \
--max-datasets 2000 \
--max-attributes 5000
The helper:
--root.If a .nc file is classic netCDF rather than HDF5, it reports it unreadable
rather than trying another unbounded parser.
from fluidsim import load_sim_for_plot
sim = load_sim_for_plot(
"run-directory",
merge_missing_params=False,
hide_stdout=True,
)
Official 0.9 source uses a coarse operator and disables saving/online plots. This is appropriate for output-class analysis, not full-resolution arbitrary field operations.
Examples:
sim.output.phys_fields.plot(time=1.0)
sim.output.spatial_means.plot()
sim.output.spectra.plot1d(tmin=0.5, tmax=1.0)
sim.output.spect_energy_budg.plot(tmin=0.5, tmax=1.0)
Methods and accepted arguments vary by solver/output class. Check the selected class API. A successful plot says nothing about correctness.
from fluidsim import load_state_phys_file
sim = load_state_phys_file(
"run-directory",
t_approx="last",
modif_save_params=True,
merge_missing_params=False,
init_with_initialized_state=True,
hide_stdout=True,
)
This can allocate full-resolution state/operators. Run the memory estimator first and do not use it merely to inspect metadata.
modif_save_params=True disables saving/online plotting. To continue a run,
use the reviewed restart workflow rather than toggling saving casually.
python3 scripts/budget_summary.py \
--path run-directory \
--max-files 128 \
--max-records 200000 \
--max-datasets 256 \
--max-values-per-dataset 4096
It:
This is a triage summary, not a solver-aware closure calculation.
Construct a table or plot for each governing budget:
Report absolute and normalized residuals, time interval, differencing method, save cadence, and uncertainty. A small instantaneous residual can be accidental; inspect trends and refinement.
For forced turbulence, compare requested forcing_rate to measured forcing
power. They are not interchangeable without checking the implementation's
normalization and time discretization.
At minimum:
Power-law fitting alone does not verify a cascade or resolved simulation.
Use stdout/output time-step history to inspect:
deltat.deltat_max/cfl_coef.Do not infer stability from the absence of NaNs.
Before time averaging:
Do not label “statistically steady” from a short visual plateau.
If built-in loaders are insufficient, keep access bounded:
import h5py
with h5py.File("spectra2D.h5", "r") as handle:
dataset = handle["spectrum2D_E"]
latest = dataset[-1, :4096]
Before indexing, inspect shape, dtype, chunks, and expected bytes. Never use
dataset[...] or [:] on an unknown large field. Check HDF5 links before
traversal; an external link can open another file.
Every exported result should carry:
Avoid manual GUI-only transformations that cannot be reconstructed.
.nc/.h5 selection, groups, attributes, state parameters, filename.