FAIRFluids

A Python framework for creating FAIR (Findable, Accessible, Interoperable, Reusable) fluid property documents with standardized metadata and experimental data representation.

Part of the FAIRChemistry initiative.

FAIRFluids standardizes how experimental and literature fluid data are represented, converted, and shared. It provides:

• A Pydantic-based data model for compounds, samples, properties, parameters, and measurements
• I/O pipelines for CSV, CML XML, and ThermoML
• Analysis and visualization helpers (Arrhenius/VFT fits, plots, DataFrames)
• Optional Bayesian inference workflows (NumPyro / JAX / ArviZ)

Requirements: Python ≥ 3.12 (reference environment: 3.13 via environment.yml). The bayesian / all extras require Python ≥ 3.12 because of the ArviZ stack.

• Structured schema for fluids, compounds, properties, parameters, and uncertainties
• Import from CSV, CML, and ThermoML; export to JSON and ThermoML
• Bidirectional ThermoML conversion (fairfluids.io.thermoml_to_fairfluids, fairfluids.io.fairfluids_to_thermoml)
• PubChem enrichment for compound metadata
• Plotting and DataFrame extraction for workflow notebooks
• Neo4j graph export (neo4j/) for querying document collections
• CLI for common create / CSV / CML operations

FAIRFluids/
├── fairfluids/                 # Main package
│   ├── core/                   # Data models (lib.py), analysis helpers, plot utils
│   ├── io/                     # CSV/JSON I/O, CML, PubChem, ThermoML converters
│   ├── operations/             # Compound/sample operations
│   ├── visualization/          # Plotting and DataFrame APIs
│   ├── analysis/               # Fits, activation energy, Bayesian hooks
│   ├── inspection/             # Document inspection, CST export
│   └── data/                   # Example CSV, CML, ThermoML files
├── docs/                       # Migration guide, API inventory, model layers
├── specifications/             # Model and ThermoML specifications
├── neo4j/                      # Neo4j import and query scripts
├── thin_layer/                 # Lightweight views / Arrhenius helpers
├── test/                       # Pytest suite
├── environment.yml             # Conda environment (Python 3.13, self-contained)
├── requirements.txt            # Core pip deps (see pyproject.toml extras)
├── requirements-conda.txt        # Pip-only add-ons for custom minimal conda envs
└── pyproject.toml              # Package metadata and optional extras

See docs/MIGRATION.md if you are updating code from an older package layout.

pyproject.toml is the single source of truth for dependencies and optional extras.

git clone https://github.com/FAIRChemistry/FAIRFluids.git
cd FAIRFluids

conda env create -f environment.yml
conda activate fairfluids

environment.yml is self-contained: core packages, notebooks, Neo4j, Bayesian stack, test tools, and an editable install of FAIRFluids.

git clone https://github.com/FAIRChemistry/FAIRFluids.git
cd FAIRFluids

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

pip install -e ".[all]"

For a minimal install (library + CLI only):

pip install -e .

git clone https://github.com/FAIRChemistry/FAIRFluids.git
cd FAIRFluids

uv sync --extra all

Run commands without activating the virtual environment:

uv run fairfluids --help
uv run pytest test/

Install only what you need via optional dependencies:

pip install -e ".[viz]"
pip install -e ".[bayesian]"
pip install -e ".[all]"

uv sync --extra workflows --extra bayesian

requirements.txt lists core runtime dependencies only. Prefer the extras above instead of maintaining a separate full requirements file.

For a custom minimal conda env (without the pip section in environment.yml), use:

pip install -r requirements-conda.txt

fairfluids --help
python -c "import fairfluids; print(fairfluids.__version__)"
python test/test_installation.py
python test/test_conda_env.py
pytest test/

from fairfluids import FAIRFluidsDocument, Version, Citation

doc = FAIRFluidsDocument(version=Version(versionMajor=1, versionMinor=0))
doc.citation = Citation(litType="journal")
doc.citation.add_to_author(given_name="Jane", family_name="Doe")

doc.add_to_compound(
    compoundID="1",
    pubChemID=962,
    commonName="Water",
    name_IUPAC="oxidane",
)

doc.save_to_json("fairfluids_model.json")

from fairfluids import FluidIO, FAIRFluidsDocument, Version

doc = FAIRFluidsDocument(version=Version(versionMajor=1, versionMinor=0))
fluid = FluidIO()
fluid.data_from_csv("fairfluids/data/csvs/exp_glycerol.csv")
doc.fluid.append(fluid)

from fairfluids import FAIRFluidsDocument, Version, FAIRFluidsCMLParser

doc = FAIRFluidsDocument(version=Version(versionMajor=1, versionMinor=0))
parser = FAIRFluidsCMLParser("fairfluids/data/cml_xml/gygli/glycerol.xml", document=doc)
doc = parser.parse()

from pathlib import Path
from fairfluids.core.lib import FAIRFluidsDocument
from fairfluids.io.thermoml_to_fairfluids import convert

payload = convert(Path("fairfluids/data/thermoml_xml/j.jct.2013.05.041.xml"))
doc = FAIRFluidsDocument.model_validate(payload)

from pathlib import Path
from fairfluids.io.fairfluids_to_thermoml import convert

xml_bytes = convert(Path("fairfluids_model.json"))
Path("output.thermoml.xml").write_bytes(xml_bytes)

CLI modules:

python -m fairfluids.io.thermoml_to_fairfluids.main --help
python -m fairfluids.io.fairfluids_to_thermoml.main --help

fairfluids create --output document.json
fairfluids csv fairfluids/data/csvs/exp_glycerol.csv --output document.json
fairfluids cml fairfluids/data/cml_xml/gygli/glycerol.xml --output document.json
fairfluids --help

Interactive Jupyter notebooks are kept in a local Workflows/ directory that is not tracked in the repository (it is gitignored as a personal scratch/experiment area). Typical examples you can build there:

Install the notebook stack and start Jupyter after creating your own Workflows/:

pip install -e ".[workflows]"   # or use environment.yml
jupyter notebook Workflows/

Full schema details: specifications/model.md, specifications/ThermoML.md.

If your code used fairfluids.core.fluid_io, fairfluids.ThermoMLMapping, or top-level ThermoML shims, see docs/MIGRATION.md for the new import paths.

conda activate fairfluids   # or your venv
pip install -e ".[dev,test]"
pytest test/ -v

Branch testing carries the current development line; open PRs against main when ready.

1. Fork the repository
2. Create a feature branch from testing or main
3. Make changes and add tests where applicable
4. Open a pull request on GitHub

MIT License — see pyproject.toml.

If you use FAIRFluids in your research, please cite the FAIRChemistry project and the relevant dataset publications. (Citation block to be added.)

• Issues: github.com/FAIRChemistry/FAIRFluids/issues
• FAIRChemistry: github.com/FAIRChemistry