sgs_tools#

Python tools for sub-grid scale (SGS) fluid dynamics analysis.

🚀 Install#

⚠️ This package is under active development. Interfaces, features and dependencies may change without notice. The devel branch is the actively maintained branch containing the latest features and fixes.

🏗️ Development Version#

To install the latest development version (from GitHub devel branch):

pip install git+https://github.com/dvlaykov/sgs_tools.git@devel

Requires Python >=3.11. Installation on older versions will fail with possibly unclear error messages.

▶️ Usage#

The package can be used both as a Python library and from the command line.

For example, run one of the included analysis scripts directly, e.g.

cs_dynamic --help

In Python, import the usual way

import sgs_tools
print (sgs_tools.__version__)

See documentation for available module and functionality and CLI scripts for sample usage.

📚 Documentation#

The documentation is hosted here. (It is updated via GitHub Actions, so may be a few minutes behind the latest PR merge.)

To build the documentation locally:

Install the package with documentation extras (sphinx and addons)

pip install git+https://github.com/dvlaykov/sgs_tools.git@devel#egg=sgs_tools[doc]

Or, if you’re using Poetry

poetry install --with doc

Generate
```
make doc
```
The rendered documentation can be accessed from <repo_directory>/documentation/index.html.

🤝 Contributing#

We welcome contributions of all kinds — bug reports, feature requests, documentation improvements, and pull requests.

Open issues for questions, ideas, or feedback. We appreciate your input!

To get started on a pull request follow the Development Setup instructions below.

Clone the repository and create a feature branch from devel
Use make pre_commit or tox -e pre_commit to fix common formatting/style issues
Use make test or tox to run checks before submitting a PR
Submit your PR to the devel branch

🧪 Development Setup & Tooling#

The dev tools are managed using Poetry.

If you’re unfamiliar with Poetry, it’s a Python packaging and publishing tool for dependency management and development workflows. You can still use pip for user installations, but we recommend Poetry for contributing to this project.

🥼 Setup#

Clone the repository

git clone https://github.com/dvlaykov/sgs_tools.git
cd sgs_tools

Create and activate a virtual environment in the preferred way (venv, conda, …) [Optional, Recommended]

Install Poetry (if not already installed), e.g.

curl -sSL https://install.python-poetry.org | python3 -

Install all dependencies including dev tools:
```
poetry install --with dev
```
This adds dev tools like tox, pytest, ruff, mypy, and pre-commit to the dependencies.
Activate Git hooks to help clean up formatting etc. on commit (this may slow down the commit somewhat).
```
pre-commit install
```

🔬 Testing & Style#

Testing and code style is managed via tox or a convenience make targets defined in the Makefile.

Run all checks (formatting, linting, type checks, tests, and coverage) across the repo with
```
make test
```
or
```
tox
```
Apply standard formatting fixes and checks (that would be applied anyway for PRs) with
```
make pre_commit
```
or
```
tox pre_commit
```

See the Makefile or tox.ini for more grannular options.

🔧 Tooling Overview#

Virtual environment for testing: tox
Unit/Integration Tests: pytest
- Will look for tests as test/test_*.py
Code Style:
- ruff: formatting and linting
- mypy: static type checking
- pre-commit: wraps up ruff and mypy and cleans-up staged files before commit. Automatically used in PRs to devel.