Tutorial

This tutorial walks you through installation, development setup, testing, and first usage of coconut-tools.

Installation

Clone the repository and install in editable mode (recommended for development).

Windows (PowerShell)

git clone https://github.com/LuisLinan/coconut-tools.git
cd coconut-tools
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -U pip
pip install -e .

Linux / macOS (bash)

git clone https://github.com/LuisLinan/coconut-tools.git
cd coconut-tools
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
pip install -e .

Development

If you want to contribute or run the full test suite with documentation:

pip install -r requirements-dev.txt

This installs extra tools such as pytest, pooch, and sphinx.

Documentation

To build the documentation locally, run:

sphinx-build -b html source _build/html

Once the build is complete, open the following file in your browser:

_build/html/index.html

This will display the documentation locally.

Testing the installation

We use pytest for testing.

After installation, you can run the basic tests:

pytest -v

This checks that the package can be imported and that the test infrastructure works. Running the tests will also generate a set of images and test files stored in tests/_output/ for inspection.

Big-data tests

⚠️ Most of the meaningful tests rely on large simulation files (≈500 MB). By default they are skipped unless you explicitly allow download. We recommend enabling them for a complete test run:

pytest -v --prefetch-bigdata

Options:

  • --prefetch-bigdata → downloads the large .vtu and .CFmesh test files into tests/_bigdata_cache/.

  • --cleanup-bigdata → deletes them at the end of the test session.

You can combine both:

pytest -v --prefetch-bigdata --cleanup-bigdata

⚠️ Downloading may take a few minutes depending on your connection.

Usage

Each script can be used in two ways:

  1. Imported as a module

    from coconut_tools import plot
plot.main("output_directory")

  2. Executed directly

    Every script contains an if __name__ == "__main__": block, which shows example usage.

    python src/coconut_tools/plot.py

What you will find in these entry points:

  • Small runnable examples to illustrate the main function of each script

  • Ways to chain together multiple operations (e.g. load + preprocess + plot)

  • Links between different functions and modules, to show how they can be combined in practice

This makes each script both a tool you can run directly and a living example of how to reuse the functions in your own workflows.

Next steps