Skip to content

Output System

Jump to bottom
shaia edited this page Mar 4, 2026 · 2 revisions

Output System

The CFD library provides a flexible output system for saving simulation results in VTK and CSV formats.

Output Types

VTK Outputs (Visualization)

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 (u, v, w, p, rho, T) .vtk

CSV Outputs (Data Analysis)

Type Description Columns
OUTPUT_CSV_TIMESERIES Time history of global quantities step, time, dt, max_u, max_v, max_p, avg_u, avg_v, avg_p
OUTPUT_CSV_STATISTICS Detailed statistics per step step, time, min/max/avg for all fields
OUTPUT_CSV_CENTERLINE Profile along domain center x, u, v, p, rho, T

Basic Usage

Registering Outputs

#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);

Writing Outputs

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 Directory Structure

Output files are organized in timestamped directories:

output/
  sim_100x100_20241208_143052/
    velocity_000.vtk
    velocity_010.vtk
    velocity_020.vtk
    timeseries.csv
    statistics.csv
    centerline_000.csv
    centerline_010.csv

Customizing Output Location

// Set base output directory
simulation_set_output_dir(sim, "/path/to/output");

// Set run name prefix (default: "sim")
simulation_set_run_prefix(sim, "my_experiment");

This creates: /path/to/output/my_experiment_NxM_YYYYMMDD_HHMMSS/

Output Intervals

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");

CSV Data Export Example

#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);

CSV File Contents

timeseries.csv - Time history:

step,time,dt,max_u,max_v,max_p,avg_u,avg_v,avg_p
0,0.000000,0.001000,0.100000,0.050000,1.013250,0.025000,0.012500,1.000000
1,0.001000,0.001000,0.099500,0.049750,1.013248,0.024875,0.012438,0.999995
...

statistics.csv - Detailed statistics:

step,time,min_u,max_u,avg_u,min_v,max_v,avg_v,min_p,max_p,avg_p
0,0.000000,-0.001000,0.100000,0.025000,-0.000500,0.050000,0.012500,0.999000,1.013250,1.000000
...

centerline_NNN.csv - Velocity/pressure profiles:

x,u,v,p,rho,T
0.010000,0.000000,0.000000,1.000000,1.000000,300.000000
0.030000,0.005000,0.002500,0.999990,1.000000,300.000000
...

Visualizing VTK Files

ParaView (Recommended)

  1. Open ParaView
  2. File > Open > Select VTK files
  3. Click Apply to load
  4. Use filters:
    • Contour: Create iso-surfaces
    • Glyph: Visualize vectors as arrows
    • Slice: Cut through the domain
    • Threshold: Filter by value

Python (matplotlib + VTK)

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)

Analyzing CSV Data

Python (pandas)

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')

Excel/LibreOffice

  1. Open CSV file directly
  2. Use chart wizard to create plots
  3. Create pivot tables for analysis

Clearing Outputs

To remove all registered outputs:

simulation_clear_outputs(sim);

// Register new outputs
simulation_register_output(sim, OUTPUT_VELOCITY, 20, "new_velocity");

Output Registry API

For advanced control, use the output registry directly:

#include "cfd/io/output_registry.h"

// Get the output registry
output_registry_t* 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");
}

Best Practices

  1. Use appropriate intervals: High-frequency output (every step) creates many files; use for CSV timeseries only
  2. VTK for visualization: Use VTK outputs for visualization tools like ParaView
  3. CSV for analysis: Use CSV outputs for plotting and data analysis
  4. Set meaningful prefixes: Use descriptive run prefixes to organize experiments
  5. Clean up old outputs: Periodically delete old output directories to save disk space

See Also

Clone this wiki locally