Tutorial: Your First Simulation (Flat Channel)

Table of Contents

• 1. Tutorial Goal
• 2. Initialize the Study Directory
• 3. Understand File Roles
• 4. Validate Inputs Before Launch
• 5. Run Solver and Postprocessor
• 6. Inspect Generated Artifacts
• 7. First Validation Checks
• 8. Visualize in ParaView
• 9. Common First-Run Issues
• 10. Next Steps

Type TutorialFor New usersStatus Verified against current `main`

This is the complete first simulation walkthrough for PICurv using the flat_channel template. This is the canonical first-simulation walkthrough with both commands and reasoning.

1. Tutorial Goal

By the end of this tutorial you will have:

• generated a run directory from YAML,
• executed a solver step pipeline,
• produced postprocessed VTK output,
• understood where each configuration file is used.

2. Initialize the Study Directory

From repository root:

./bin/picurv init flat_channel --dest my_first_run

Expected files:

my_first_run/
|- flat_channel.yml
|- Imp-MG-Standard.yml
|- Standard_Output.yml
`- standard_analysis.yml

3. Understand File Roles

• flat_channel.yml case physics, scaling, grid, BC handlers, model flags.
• Imp-MG-Standard.yml momentum strategy, tolerances, pressure multigrid controls.
• Standard_Output.yml logging verbosity, profiling, output directories, monitor flags.
• standard_analysis.yml postprocessing pipeline tasks and VTK/statistics output settings.

4. Validate Inputs Before Launch

./bin/picurv validate \
  --case my_first_run/flat_channel.yml \
  --solver my_first_run/Imp-MG-Standard.yml \
  --monitor my_first_run/Standard_Output.yml \
  --post my_first_run/standard_analysis.yml

Validation confirms the YAML-to-runtime contract and catches mis-typed keys before execution.

5. Run Solver and Postprocessor

./bin/picurv run \
  --case my_first_run/flat_channel.yml \
  --solver my_first_run/Imp-MG-Standard.yml \
  --monitor my_first_run/Standard_Output.yml \
  --post my_first_run/standard_analysis.yml \
  -n 4 --solve --post-process

What happens internally:

1. all input files are loaded and validated,
2. run ID directory is created under runs/,
3. C-consumed artifacts are generated (*.control, bcs*.run, whitelist.run, profile.run, post.run),
4. bin/simulator is launched,
5. bin/postprocessor is launched.

6. Inspect Generated Artifacts

Typical output structure:

runs/
`- flat_channel_YYYYMMDD-HHMMSS/
   |- config/
   |- inputs/
   |- logs/
   |- output/
   |  |- checkpoints/
   |  |- analysis/
   |  `- visualization/
   |- scheduler/
   `- manifest.json

Interpretation:

• <run.config>/: exact runtime artifact snapshot for reproducibility,
• <run.runtime_logs>/: function-level and solver monitor traces,
• <run.solver_output>/: solver field outputs,
• <run.visualization>/<recipe_id>/: postprocessed VTK files for ParaView.

7. First Validation Checks

After run completion, verify:

• no fatal errors in <run.runtime_logs>/,
• non-empty VTK outputs in visualization directory,
• expected time sequence naming (Field_*.vts, optionally Particle_*.vtp).

If results are missing, check the recipe-specific post state under <run.config>/post-recipes/ and the post.yml output toggles first.

8. Visualize in ParaView

1. Open <run.visualization>/<recipe_id>/eulerian_data.pvd for the standard analysis recipe's checkpoint physical-time axis. If using a custom recipe with collections disabled, open its numbered .vts files instead.
2. Click Apply.
3. Add Slice filter.
4. Color by Ucat_nodal magnitude or streamwise component.
5. Optionally add Stream Tracer from inlet region.

Expected behavior: smooth channel flow with profile development consistent with setup.

9. Common First-Run Issues

• Missing binary: rerun ./picurv_cli/picurv build and check PETSc vars.
• Validation failure: compare key paths against examples and Configuration Contract (YAML -> Generated Artifacts -> Runtime).
• Empty post output: verify --post-process flag and post.yml output settings.

Mapped error guide:

• Common Fatal Errors and Fixes

10. Next Steps

• File-grid workflow: Tutorial: Using a File-Based Grid (Search Robustness)
• Visualization details: Tutorial: A Guide to Visualizing Your Results
• Operational recipes: User How-To Guides