Getting Started Developing

This document is a brief overview of the repository layout and the main development workflow. For the more detailed command and process reference, see the development workflow.

Repository Layout

The overall structure of the project is:

  • main directory for project-wide metadata and tooling

  • docs for development documentation and project notes

  • examples for example usage and instructional scripts

  • src for the apps, library, and supporting modules

  • sphinx for rendered documentation build inputs

  • tests for automated tests

  • venvs for local virtual environments that should not be committed

Current App Workflow

The current app workflow is organized around case authoring, simulation execution, and result exploration.

Structured case files remain the source of truth for simulation setup. The panel2d_tui and panel2d_gui apps can be used to create, edit, and validate those case files. The panel2d_cli run command solves one structured case and writes one solved artifact YAML file. That solved artifact is the handoff between simulation and post-processing. The panel2d_cli inspect command can be used to review artifact metadata and optionally reconstruct integrated results from the command line. The GUI can also load solved artifacts directly for post-processing and visualization.

When the case file requests post.surface quantities, panel2d_cli run also writes one CSV export beside the artifact. That CSV uses the artifact stem with the .surface.csv suffix and contains integrated-quantity metadata at the top followed by collocation-point surface rows. If post.surface.quantities requests velocity, the CSV writes both tangent_velocity and normal_velocity columns.

One typical workflow looks like this:

panel2d_cli run examples/naca0012_designation.yaml
panel2d_cli inspect examples/naca0012_designation.solution.yaml --include-results

The CLI reference page in sphinx/source/cli/index.md documents the currently supported commands.

Testing

The main development practice used is test-driven development when practical. New features should usually arrive with unit tests and edge-case coverage in tests.

Run the full test suite from the project root with:

uv run pytest

Configuration for pytest is in pyproject.toml.

Linting And Formatting

This project uses Ruff for linting and formatting. The aim is to fix issues rather than suppress them.

Check lint:

uv run ruff check .

Apply automatic fixes where available:

uv run ruff check . --fix

Check formatting:

uv run ruff format . --check

Apply formatting:

uv run ruff format .

Configuration for Ruff is in pyproject.toml.

Coverage

To collect default coverage data for the project:

uv run coverage run

To collect coverage for one targeted test module:

uv run coverage run -m pytest {pytest-file-with-path}

To print a text report:

uv run coverage report -m

To build the HTML report:

uv run coverage html

The HTML report is written to htmlcov/index.html. Coverage configuration is in pyproject.toml.

Type Checking

Typing is treated strictly in this project. Fix identified issues before committing when practical, and use narrow documented ignores only when truly necessary.

Run mypy:

uv run mypy

Run BasedPyright:

uv run basedpyright

Type-checker configuration is in pyproject.toml.

CI-Parity Checks

Several checks run in CI for this repository. Before finishing substantial changes, run:

./scripts/run_checks.sh

This script runs the main pytest, lint, coverage, and type-check steps through the repository-managed environment.

Documentation

The documentation is generated with Sphinx and MyST Markdown. Autodoc is used to pull docstrings into the API reference.

The source documentation files live primarily in docs, while the rendered-doc build inputs live under sphinx/source. Build the HTML documentation with:

./scripts/build_docs.sh

The generated HTML output is written to sphinx/build/html. The Sphinx configuration lives in sphinx/source/conf.py.