Getting started

This page is for readers who want to understand, run, and extend pyodt1.

What this project is

pyodt1 is a Python reimplementation of the classic Basic ODT (odt1) code.

The current emphasis is not on immediately reproducing the entire legacy solver in one jump. Instead, the project is organized around a more reliable strategy:

  1. port small but important algorithmic pieces,

  2. validate them against the original Fortran,

  3. document the mapping and the validation carefully,

  4. then expand the implementation step by step.

This means the project is both a codebase and a teaching/validation effort.

What you can do right now

At the current stage, you can:

  • run the Python tests,

  • inspect the package structure,

  • run a direct Fortran-vs-Python comparison harness,

  • read detailed algorithm notes in the documentation site.

Environment setup with uv

Create and activate a virtual environment:

uv venv .venv
source .venv/bin/activate

Install the package in editable mode:

uv pip install -e .

Install development tools if needed:

uv pip install pytest jupyterlab ruff mypy

Install documentation dependencies:

uv pip install -r docs/requirements.txt

Run tests

pytest -q

The test suite is currently used both for ordinary unit tests and for regression-style checks on algorithmic behavior.

Run the comparison harness

The main validation entry point is:

python scripts/compare_one_step.py

If gfortran is available, the script will:

  1. generate temporary Fortran drivers,

  2. compile selected original odt1 source files,

  3. run them,

  4. compare their outputs against the Python implementation.

If gfortran is not available, the script still prints the Python reference path, so it remains useful as a debugging tool.

Build the docs locally

sphinx-build -b html docs docs/_build/html

Open:

docs/_build/html/index.html

Suggested reading order for new learners

If you are new to ODT or new to this package, a good sequence is:

  1. ODT for CFD readers

  2. ODT in the literature

  3. Algorithm overview

  4. Legacy Fortran to Python mapping

  5. Legacy RNG

  6. Triplet map

  7. Eddy sampling

  8. Acceptance probability

  9. Accepted eddy update

  10. Validation harness

Important current scope caveat

The current implementation validates a minimal but important path:

  • legacy RNG,

  • eddy-size distribution,

  • eddy-size sampling,

  • eddy-location sampling,

  • BsKd,

  • acceptance probability,

  • accepted-eddy update.

This is already meaningful, but it is not yet the full odt1 runtime loop.

That distinction matters. The project is already useful as a validated algorithmic reimplementation scaffold, but it is still under active expansion.