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.

References

• uv documentation
• fairtool repository