Repository navigation
Output System
The CFD library provides a flexible output system for saving simulation results in VTK and CSV formats, and binary checkpoints for restarting a run.
| Type | Description | File Format |
|---|---|---|
OUTPUT_VELOCITY_MAGNITUDE |
Scalar velocity magnitude field | .vtk |
OUTPUT_VELOCITY |
Vector velocity field (u, v, w) | .vtk |
OUTPUT_FULL_FIELD |
Complete flow field (velocity vector, pressure, density, temperature, plus the turbulence fields turbulent_kinetic_energy, dissipation_rate, nu_tilde, turbulent_viscosity; zero when no turbulence model is active) |
.vtk |
| Type | Description | Columns |
|---|---|---|
OUTPUT_CSV_TIMESERIES |
Time history of global quantities | step, time, dt, max/avg of u, v, w, p, velocity magnitude, solver iterations, residual, elapsed_ms |
OUTPUT_CSV_STATISTICS |
Detailed statistics per step | step, time, min/max/avg for u, v, w, p, rho, T, velocity magnitude |
OUTPUT_CSV_CENTERLINE |
Profile along the horizontal domain center | x, u, v, w, p, rho, T, turb_k, turb_eps, nu_t, vel_mag |
#include "cfd/api/simulation_api.h"
simulation_data* sim = init_simulation(100, 100, 1,
0.0, 1.0, 0.0, 1.0, 0.0, 0.0);
// Register VTK output every 10 steps
simulation_register_output(sim, OUTPUT_VELOCITY_MAGNITUDE, 10, "velocity");
// Register CSV timeseries every step
simulation_register_output(sim, OUTPUT_CSV_TIMESERIES, 1, "timeseries");
// Register with default prefix (NULL)
simulation_register_output(sim, OUTPUT_FULL_FIELD, 50, NULL);for (int step = 0; step < 100; step++) {
run_simulation_step(sim);
// Automatically writes all registered outputs at their intervals
simulation_write_outputs(sim, step);
}Output files are organized in timestamped directories of the form <base>/output/<prefix>_<nx>x<ny>_<YYYYMMDD>_<HHMMSS>/. The default base is ../../artifacts, resolved against the working directory the program runs from (running from build/Release writes to <repo>/artifacts/output/):
artifacts/
output/
sim_100x100_20241208_143052/
velocity_000.vtk
velocity_010.vtk
velocity_020.vtk
timeseries.csv
statistics.csv
centerline_000.csv
centerline_010.csv
// Set base output directory (default: "../../artifacts")
simulation_set_output_dir(sim, "/path/to/base");
// Set run name prefix (default: "sim")
simulation_set_run_prefix(sim, "my_experiment");This creates: /path/to/base/output/my_experiment_NxM_YYYYMMDD_HHMMSS/. The library adds the output/ level itself, so a base of output nests as output/output/<run>.
The interval parameter controls how often each output is written:
// Write every step
simulation_register_output(sim, OUTPUT_CSV_TIMESERIES, 1, "timeseries");
// Write every 10 steps
simulation_register_output(sim, OUTPUT_VELOCITY_MAGNITUDE, 10, "velocity");
// Write every 100 steps
simulation_register_output(sim, OUTPUT_FULL_FIELD, 100, "flow_field");#include "cfd/api/simulation_api.h"
simulation_data* sim = init_simulation(100, 50, 1,
0.0, 2.0, 0.0, 1.0, 0.0, 0.0);
simulation_set_run_prefix(sim, "csv_export");
// Register all CSV outputs
simulation_register_output(sim, OUTPUT_CSV_TIMESERIES, 1, "timeseries");
simulation_register_output(sim, OUTPUT_CSV_STATISTICS, 5, "statistics");
simulation_register_output(sim, OUTPUT_CSV_CENTERLINE, 10, "centerline");
// Also save VTK for visualization
simulation_register_output(sim, OUTPUT_FULL_FIELD, 20, "flow_field");
for (int step = 0; step < 100; step++) {
run_simulation_step(sim);
simulation_write_outputs(sim, step);
}
free_simulation(sim);timeseries.csv - Time history:
step,time,dt,max_u,max_v,max_w,max_p,avg_u,avg_v,avg_w,avg_p,max_vel_mag,avg_vel_mag,iterations,residual,elapsed_msOne row per written step, with the values in %.6e format.
statistics.csv - Detailed statistics:
step,time,min_u,max_u,avg_u,min_v,max_v,avg_v,min_w,max_w,avg_w,min_p,max_p,avg_p,min_rho,max_rho,avg_rho,min_T,max_T,avg_T,min_vel_mag,max_vel_mag,avg_vel_magcenterline_NNN.csv - Velocity/pressure profiles along x at the middle row:
x,u,v,w,p,rho,T,turb_k,turb_eps,nu_t,vel_mag- Open ParaView
- File > Open > Select VTK files
- Click Apply to load
- Use filters:
- Contour: Create iso-surfaces
- Glyph: Visualize vectors as arrows
- Slice: Cut through the domain
- Threshold: Filter by value
import vtk
import matplotlib.pyplot as plt
import numpy as np
# Read VTK file
reader = vtk.vtkStructuredGridReader()
reader.SetFileName("velocity_000.vtk")
reader.Update()
# Extract data for matplotlib
grid = reader.GetOutput()
points = grid.GetPoints()
scalars = grid.GetPointData().GetScalars()
# Plot with matplotlib
# (convert to numpy arrays as needed)import pandas as pd
import matplotlib.pyplot as plt
# Load timeseries
df = pd.read_csv("timeseries.csv")
# Plot velocity over time
plt.figure(figsize=(10, 6))
plt.plot(df['time'], df['max_u'], label='Max U')
plt.plot(df['time'], df['max_v'], label='Max V')
plt.xlabel('Time')
plt.ylabel('Velocity')
plt.legend()
plt.savefig('velocity_history.png')- Open CSV file directly
- Use chart wizard to create plots
- Create pivot tables for analysis
To remove all registered outputs:
simulation_clear_outputs(sim);
// Register new outputs
simulation_register_output(sim, OUTPUT_VELOCITY, 20, "new_velocity");A checkpoint is a portable, versioned binary file (.cfdchk) holding everything needed to resume a run from a step boundary: the grid, the flow field (including the turbulence fields), the solver parameters (turbulence model, pressure solver, convection and viscous schemes, thermal and turbulence boundary conditions), the accumulated simulation time, and the active solver's name. Values are little-endian with a CRC32 trailer, so a truncated or corrupted file is rejected on load.
#include "cfd/api/simulation_api.h"
// Save the complete state
cfd_status_t status = save_simulation_checkpoint(sim, "run.cfdchk");
// Resume in a fresh simulation (free it with free_simulation)
simulation_data* resumed = load_simulation_from_checkpoint("run.cfdchk");
// Or restore into an existing simulation
status = restore_simulation_checkpoint(sim, "run.cfdchk");Function pointers cannot be serialized: custom source_func and heat_source_func callbacks, their contexts, the learned turbulence closure, and turbulence BC segment profiles are not stored. restore_simulation_checkpoint() keeps the ones already set on sim; load_simulation_from_checkpoint() leaves them NULL, so re-supply them on the returned simulation. Solver scratch buffers are not stored either; they are rebuilt from the field when the solver is recreated by name.
The lower-level cfd_checkpoint_write() and cfd_checkpoint_read() in cfd/io/checkpoint.h work on a grid, field and parameters directly. The steady_flow_multigrid example saves a checkpoint mid-run and restarts from it.
For advanced control, use the output registry directly:
#include "cfd/io/output_registry.h"
#include <stdio.h>
// Get the output registry
output_registry* reg = sim->outputs;
// Check how many outputs are registered
int count = output_registry_count(reg);
// Check if specific output type is registered
if (output_registry_has_type(reg, OUTPUT_VELOCITY_MAGNITUDE)) {
printf("Velocity magnitude output is enabled\n");
}- Use appropriate intervals: High-frequency output (every step) creates many files; use for CSV timeseries only
- VTK for visualization: Use VTK outputs for visualization tools like ParaView
- CSV for analysis: Use CSV outputs for plotting and data analysis
- Set meaningful prefixes: Use descriptive run prefixes to organize experiments
- Clean up old outputs: Periodically delete old output directories to save disk space
- Getting Started - Basic usage
- Solver Guide - Solver configuration
- Examples - Working code examples