fairtool

Ravindra Shinde

fairtool - Computational Materials Data Processing made FAIR

FAIR Tool is a command-line interface for processing, analyzing, and visualizing computational materials data. It is designed to work with various calculation output files and provides a streamlined workflow.

Project Lead: Dr. Ravindra Shinde

Email : r.l.shinde@utwente.nl

Contributor: Konstantinos Kontogiannis

Email : k.kontogiannis@student.utwente.nl

Funding: 4TU Research Data Fund 4th Edition

Installing fairtool with uv

This guide explains how to install the fairtool package and its dependencies using uv, a fast Python package installer and resolver.

Prerequisites

Python 3.11 – 3.14 (Note: Python <= 3.10 is unsupported because modern upstream scientific dependencies such as pymatgen (2026+) and numpy require Python 3.11 or newer)
libmagic, a system library that fair parse uses to detect file types:
- macOS: brew install libmagic (Homebrew), or sudo port install file (MacPorts)
- Debian/Ubuntu: the libmagic1 package, usually already installed (if not, sudo apt install libmagic1)
uv installed (see below)
Git (optional, for cloning the repository)

1. Clone the Repository (if needed)

git clone https://github.com/neelravi/fairtool.git
cd fairtool

2. Install uv

If you don't have uv installed, run:

curl -Ls https://astral.sh/uv/install.sh | sh

This will install uv to ~/.local/bin/uv by default. Make sure this directory is in your PATH.

You may install Python using uv quickly with:

uv python install 3.11

3. Create a Virtual Environment with uv

It's recommended to use a virtual environment. You can create one using uv:

uv venv .venv
source .venv/bin/activate

4. Install Dependencies with uv

From the project root directory, run:

uv pip install -r requirements.txt

This will install all required dependencies quickly using uv's resolver.

5. Install fairtool (Editable/Development Mode)

To install the package in editable mode (recommended for development):

uv pip install -e .

6. Run the CLI

You can now run the CLI using:

fair

Verification & Testing

Verify that your installation, test suite, and site generation pass:

1. Run the Test Suite with Coverage

# Run pytest with code coverage breakdown
pytest --cov=fairtool --cov-report=term-missing

2. Verify Code Quality with Ruff

# Check linting and formatting
ruff check fairtool tests
ruff format --check fairtool tests

3. Verify Static Documentation Build

# Test site build without launching dev server
fair visualize tests/VASP/ --build

Troubleshooting

Ensure you are using Python 3.11+ for best compatibility.
If fair parse fails with ImportError: failed to find libmagic, install libmagic (see Prerequisites).
If you see ModuleNotFoundError: No module named 'fairtool', make sure your PYTHONPATH includes the project root.
If uv is not found, ensure ~/.local/bin is in your PATH.