Repository Navigation and Directory Guides

Table of Contents

• 1. Top-Level Repository Areas
• 2. Top-Level Guide Links
• 3. Configuration Subdirectory Guides
• 4. Documentation-Local Guides
• 5. Documentation Organization Rules
• 6. Related Documentation
  • CFD Reader Guidance and Practical Use
    • What To Extract Before Changing A Case
    • Practical CFD Troubleshooting Pattern

This page is the documentation map of the repository layout. Use it as the single directory-guide index so internal guide.md files do not need to appear as standalone documentation pages.

1. Top-Level Repository Areas

• Configuration library: config/
• Documentation source: docs/
• Runnable templates: examples/
• Public headers: include/
• C source implementation: src/
• Automation scripts: scripts/
• Tests and fixtures: tests/
• Developer scratch area: sandbox/
• Logs and warnings: logs/
• GitHub workflow definitions: .github/

2. Top-Level Guide Links

• Configuration Guide
• Documentation Guide
• Examples Guide
• Include Guide
• Source Guide
• Scripts Guide
• Tests Guide
• Sandbox Guide
• Logs Guide
• GitHub Workflows Guide

3. Configuration Subdirectory Guides

• Build Config Guide
• Grid Config Library Guide
• Monitor Profiles Guide
• Solver Profiles Guide
• Postprocessor Profiles Guide
• Scheduler Profiles Guide
• Study Config Guide

4. Documentation-Local Guides

• Pages Authoring Guide
• Assets Guide

5. Documentation Organization Rules

1. Repository-level conceptual docs should live in docs/pages/ as @page entries.
2. Directory orientation notes should live in local guide.md files.
3. Directory guides are indexed from this page, not promoted to top-level docs navigation.
4. When adding a major new directory, add a guide.md and add a link here.

6. Related Documentation

• Getting Started
• User Guide
• Developer Portal

CFD Reader Guidance and Practical Use

This page describes Repository Navigation and Directory Guides within the PICurv workflow. For CFD users, the most reliable reading strategy is to map the page content to a concrete run decision: what is configured, what runtime stage it influences, and which diagnostics should confirm expected behavior.

Treat this page as both a conceptual reference and a runbook. If you are debugging, pair the method/procedure described here with monitor output, generated runtime artifacts under runs/<run_id>/config, and the associated solver/post logs so numerical intent and implementation behavior stay aligned.

What To Extract Before Changing A Case

• Identify which YAML role or runtime stage this page governs.
• List the primary control knobs (tolerances, cadence, paths, selectors, or mode flags).
• Record expected success indicators (convergence trend, artifact presence, or stable derived metrics).
• Record failure signals that require rollback or parameter isolation.

Practical CFD Troubleshooting Pattern

1. Reproduce the issue on a tiny case or narrow timestep window.
2. Change one control at a time and keep all other roles/configs fixed.
3. Validate generated artifacts and logs after each change before scaling up.
4. If behavior remains inconsistent, compare against a known-good baseline example and re-check grid/BC consistency.