Reorganization for install with pip or conda by d-montgomery · Pull Request #59 · NatLabRockies/FuelLib

d-montgomery · 2026-05-13T17:33:02Z

This PR makes several improvements to the FuelLib project's installation, documentation, and CI workflows. The main changes include updating installation instructions and documentation to reflect new CLI tools and development workflows, switching CI and documentation builds to use editable/development installs, and modernizing the command-line exporter interface. Additionally, a new development guide has been added along a tutorial for using user defined custom fuels.

Major Changes

Installation

Users can now install FuelLib through pip install fuellib, then adding import fuellib as fl to any python script that utilizes FuelLib.

Module Organization & Architecture

Split monolithic FuelLib.py into modules:
- constants.py - Physical constants (k_B, N_A)
- convert.py - Temperature and unit conversions
- utility.py - Mixture properties and droplet calculations
- fuel.py - Main Fuel class for GCM calculations
Reorganized repository structure for proper Python packaging:
- Renamed source -> fuellib and added a pyproject.toml for distribution via pip and conda with proper entry point configuration
- Created fuellib/cli/ subpackage containing all command-line tools
- Improved package discovery and installation with pip install -e ., pip install -e '.[dev]', and pip install fuellib
- Reworked the antiquated paths structure for managing paths between data and scripts. Users only need to import fuellib as fl provided a pip install.
New fuel_metadata.yaml requirement:
- This allows for user defined mapping between gcData and groupDecompositions, eliminating redundant decomposition files.

CLI Tools Expansion & Organization

New CLI Commands:

fl-C2K, fl-K2C - Celsius/Kelvin conversion utilities
fl-C2F, fl-F2C, fl-F2K, fl-K2F - Additional temperature conversions
fl-eps2K - Lennard-Jones epsilon to characteristic temperature conversion
fl-export-converge - Export mixture properties for Converge CFD simulations
fl-export-pele - Export properties for PelePhysics simulations
fl-plt-comp - Composition plotting
fl-plt-props - Properties plotting
fl-fuels - List available fuels with metadata support

Testing Improvements

New test_exporters.py: Comprehensive integration tests for export commands (7 tests)
Updated test_source_docstrings.py: Now validates docstrings for all public API modules
test_utilities.py - Unit tests for utility functions and CLI temperature conversion commands
test_hc_identification.py - Unit tests for hydrocarbon classification logic
Simplified CI exporter job from 8 individual steps to single test_exporters.py call

Breaking Changes (v3.0.0)

Functions moved from fuellib namespace to submodules:

Temperature conversions: fl.C2K() → fl.convert.C2K()
Utility functions: fl.mixing_rule() → fl.utility.mixing_rule()
Constants: fl.k_B still works, but fl.constants.k_B recommended

Requirement of fuel_metadata.yaml

All fuels are now required to be listed in this file.

Copilot

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

This PR reorganizes FuelLib for installation via pip/conda by introducing a fuellib package with embedded data, modern CLI exporters, and updated documentation/CI to use editable installs and new entry points.

Changes:

Migrate tutorials/tests/export scripts to import fuellib and locate data via package helpers instead of paths.py/sys.path hacks.
Add packaging metadata (pyproject.toml), embedded data under fuellib/data, and CLI entry points (fl-export-*, fl-build-docs, etc.).
Update Sphinx docs and GitHub Actions workflows to use the new CLI and editable installs.

Reviewed changes

Copilot reviewed 80 out of 81 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tutorials/mixtureProperties.py	Switch tutorial to `fuellib` import and embedded data directory lookup
tutorials/hefaBlends.py	Switch tutorial to `fuellib` import and embedded data directory lookup
tutorials/compositionPlots.py	Switch tutorial to `fuellib` import (remove path hacks)
tutorials/basic.py	Switch tutorial to `fuellib` import
tests/test_source_docstrings.py	Update docstring contract test to check selected `fuellib` modules/scripts
tests/test_api.py	Switch tests to `fuellib` import (remove path hacks)
tests/test_accuracy.py	Replace `paths.py` usage with explicit baseline directory constants
tests/get_pred_and_data.py	Switch helper to `fuellib` and embedded data locator
source/FuelLib.py	Refactor data directory handling to use embedded data locator functions
source/Export4Pele.py	Migrate exporter to `fuellib`, default embedded data, and updated CLI args/docs
source/Export4Converge.py	Migrate exporter to `fuellib`, default embedded data, and updated CLI args/docs
pyproject.toml	Add packaging metadata, dependencies, extras, and CLI entry points
paths.py	Remove legacy hardcoded path helper module
gcmTableData/gcmTable.csv	Update MW row in legacy GCM table CSV
fuellib/format_code.py	Add `fl-format` CLI utility
fuellib/exporters/init.py	Add exporters subpackage init
fuellib/data/gcmTableData/gcmTable.csv	Add embedded GCM table data CSV
fuellib/data/gcmTableData/init.py	Add embedded data package marker
fuellib/data/fuelData/refCompounds.csv	Add embedded reference compounds table
fuellib/data/fuelData/propertiesData/posf11498.csv	Add embedded properties dataset
fuellib/data/fuelData/propertiesData/posf10325.csv	Add embedded properties dataset
fuellib/data/fuelData/propertiesData/posf10289.csv	Add embedded properties dataset
fuellib/data/fuelData/propertiesData/posf10264.csv	Add embedded properties dataset
fuellib/data/fuelData/propertiesData/heptane.csv	Add embedded properties dataset
fuellib/data/fuelData/propertiesData/hefa-jet-a-blends.csv	Add embedded properties dataset
fuellib/data/fuelData/propertiesData/hefa-WE-SAF-262714.csv	Add embedded properties dataset
fuellib/data/fuelData/propertiesData/hefa-S1.csv	Add embedded properties dataset
fuellib/data/fuelData/propertiesData/dodecane.csv	Add embedded properties dataset
fuellib/data/fuelData/propertiesData/decane.csv	Add embedded properties dataset
fuellib/data/fuelData/propertiesData/init.py	Add embedded data package marker
fuellib/data/fuelData/groupDecompositionData/posf11498.csv	Add embedded decomposition dataset
fuellib/data/fuelData/groupDecompositionData/heptane.csv	Add embedded decomposition dataset
fuellib/data/fuelData/groupDecompositionData/heptane-decane.csv	Add embedded decomposition dataset
fuellib/data/fuelData/groupDecompositionData/hefa-WE-SAF-262714.csv	Add embedded decomposition dataset
fuellib/data/fuelData/groupDecompositionData/hefa-S1.csv	Add embedded decomposition dataset
fuellib/data/fuelData/groupDecompositionData/dodecane.csv	Add embedded decomposition dataset
fuellib/data/fuelData/groupDecompositionData/decane.csv	Add embedded decomposition dataset
fuellib/data/fuelData/groupDecompositionData/init.py	Add embedded data package marker
fuellib/data/fuelData/gcData/posf4658_init.csv	Add embedded GC dataset
fuellib/data/fuelData/gcData/posf11498_init.csv	Add embedded GC dataset
fuellib/data/fuelData/gcData/posf10325_init.csv	Add embedded GC dataset
fuellib/data/fuelData/gcData/posf10289_init.csv	Add embedded GC dataset
fuellib/data/fuelData/gcData/posf10264_init.csv	Add embedded GC dataset
fuellib/data/fuelData/gcData/posf10264_T30_init.csv	Add embedded GC dataset
fuellib/data/fuelData/gcData/jet-a_init.csv	Add embedded GC dataset
fuellib/data/fuelData/gcData/heptane_init.csv	Add embedded GC dataset
fuellib/data/fuelData/gcData/heptane-decane_init.csv	Add embedded GC dataset
fuellib/data/fuelData/gcData/hefa-tall_init.csv	Add embedded GC dataset
fuellib/data/fuelData/gcData/hefa-mfat_init.csv	Add embedded GC dataset
fuellib/data/fuelData/gcData/hefa-came_init.csv	Add embedded GC dataset
fuellib/data/fuelData/gcData/hefa-WE-SAF-262714_init.csv	Add embedded GC dataset
fuellib/data/fuelData/gcData/hefa-S1_init.csv	Add embedded GC dataset
fuellib/data/fuelData/gcData/dodecane_init.csv	Add embedded GC dataset
fuellib/data/fuelData/gcData/decane_init.csv	Add embedded GC dataset
fuellib/data/fuelData/gcData/init.py	Add embedded data package marker
fuellib/data/fuelData/dataReferences.md	Add embedded data provenance documentation
fuellib/data/fuelData/init.py	Add embedded data package marker
fuellib/data/init.py	Add embedded data package marker
fuellib/clean_docs.py	Add `fl-clean-docs` CLI utility
fuellib/build_docs.py	Add `fl-build-docs` CLI utility
fuellib/_data_locator.py	Add helper functions to locate embedded data directories
docs/tutorials.rst	Update tutorials toctree entries for renamed exporter docs
docs/tutorials-export4pele.rst	Update exporter tutorial to new `fl-export-pele` command and flags
docs/tutorials-export4converge.rst	Update exporter tutorial to new `fl-export-converge` command and flags
docs/tutorials-basic.rst	Update basic tutorial for `pip install fuellib` workflow
docs/sourcecode.rst	Update source layout documentation and public API reference
docs/index.rst	Add installation section and update toctree
docs/fuelprops.rst	Update API references from `FuelLib` to `fuellib` and clarify Cp/Cl terminology
docs/development.rst	Add contributing/development workflow documentation
docs/conf.py	Update Sphinx import path to project root
README.md	Update install instructions, CLI usage, and dev workflow
.gitignore	Ignore `exportData/` and common Python build/venv artefacts
.github/workflows/documentation.yml	Switch docs build to editable dev install + `fl-build-docs`
.github/workflows/ci.yml	Switch CI installs to editable install and run new CLI exporters

Comments suppressed due to low confidence (4)

fuellib/format_code.py:1

This implementation depends on Unix utilities (find, xargs) and will fail on Windows runners/environments. For a cross-platform fl-format, consider invoking Black via python -m black with explicit paths, or enumerate files in Python (e.g., pathlib.Path.rglob) and pass them to Black without relying on external shell tools.
tests/test_source_docstrings.py:1
This test used to scan all source/*.py, but now it checks a fixed allowlist and silently skips missing files. That weakens the contract (new modules won’t be checked, and missing expected files won’t fail the test). Consider discovering modules dynamically (e.g., globbing fuellib/**/*.py with exclusions), and/or failing the test if any expected allowlisted file is missing.
tests/test_source_docstrings.py:1
This test used to scan all source/*.py, but now it checks a fixed allowlist and silently skips missing files. That weakens the contract (new modules won’t be checked, and missing expected files won’t fail the test). Consider discovering modules dynamically (e.g., globbing fuellib/**/*.py with exclusions), and/or failing the test if any expected allowlisted file is missing.
gcmTableData/gcmTable.csv:1
There are now two GCM table CSVs in the repo: the legacy gcmTableData/gcmTable.csv (updated MW values here) and the embedded fuellib/data/gcmTableData/gcmTable.csv (which still has the old integer MW row). Since the refactor switches runtime lookup to the embedded data, this creates a risk of inconsistent results depending on which table is used. Please ensure the embedded CSV is updated consistently (or remove/stop updating the legacy copy) so there is a single source of truth.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

- Rewrite tutorials-custom-fuels.rst for clarity - Add fuel_metadata requirement - Update error messages and fuel manager - Add fl-fuels command to README - Add testing for fuels shipped with FuelLib

… handling

Copilot

Pull request overview

Copilot reviewed 93 out of 110 changed files in this pull request and generated 11 comments.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

- Rename posf10264.csv to posf-cat-a.csv (Conventional ATM Surrogate) - Delete duplicate files: posf4658.csv, posf10289.csv, posf10325.csv (verified identical via checksum: 4026242a7a35eba58a47f3e9a38a025e) - Update fuel_metadata.yaml to point all four conventional POSF fuels to the consolidated posf-cat-a decomposition file - Reduces groupDecompositionData/ from 14 to 11 files - All fuels remain discoverable via CLI and API - Verified: test_api.py passes, fl-fuels lists all 13 fuels correctly, all five POSF fuels (posf4658, posf10264, posf10289, posf10325, posf11498) instantiate successfully - posf11498 (ATJ, isoparaffinic) remains separate as unique composition This change improves maintainability by eliminating file duplication while preserving distinct fuel metadata (names, sources, descriptions) through the fuel_metadata.yaml mapping.

- Remove unnecessary re-exports of C2K, K2C, get_props_data_from_metadata from main fuellib module (kept API clean) - Update plotting.py to directly import: - C2K, K2C from fuellib.convert - get_props_data_from_metadata from fuellib._data_locator - Replace all fl.* calls with direct function names - This is cleaner than polluting the main API with internal CLI utilities - Fixes: fl-plt-props -f posf10325 now works correctly

- Follows pattern of other data locator functions: get_fueldata_dir, get_fueldata_gc_dir, get_fueldata_decomp_dir, get_fueldata_props_dir, get_gcmtable_dir - get_fueldata_propsdata returns properties data name from fuel_metadata - Updated across _data_locator.py, __init__.py, and plotting.py

- Remove k_B and N_A from top-level (access via fl.constants.k_B, fl.constants.N_A) - Use 'from ._data_locator import *' instead of explicit function list - Add __all__ to _data_locator.py to control what gets exported - Cleaner and more consistent with submodule pattern (fl.convert.*, fl.constants.*, fl.utility.*) - Keep only essential items at top level: fuel, submodules (constants, convert, utility)

- Not exported in __all__, so import was dead code - Access via fl.constants.k_B, fl.constants.N_A when needed

Copilot

Pull request overview

Copilot reviewed 96 out of 113 changed files in this pull request and generated 9 comments.

Comments suppressed due to low confidence (2)

docs/tutorials-export-pele.rst:151

The short option in the example uses -d, but the actual exporter CLI defines -dep/--dep_fuel_names (see fuellib/exporters/pele.py). As written, fl-export-pele -f heptane-decane -d ... will fail with an unrecognized argument; update the docs example to use -dep (or the long option).
docs/tutorials-export-pele.rst:156
The sample output uses particles.dep_fuel_names, but the exporter writes particles.dep_fuel_species (see fuellib/exporters/pele.py). Update the documentation snippet to match the actual key name so users can copy/paste it into Pele inputs.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

d-montgomery added 6 commits May 13, 2026 10:26

Reorg for pip

f956998

Better docs building

5ff75aa

Better formatting via fl-format

285efe5

Update CI

16ed541

Specify molar vs. mass Cp

1f3b7aa

Extend title in docs

e0821b6

d-montgomery force-pushed the pip-conda branch from 3c9faf7 to e0821b6 Compare May 13, 2026 17:51

d-montgomery added 9 commits May 13, 2026 12:14

Remove old paths.py

a623baf

Update MW

358abbf

Update installation with pip

8d527fa

Update installation and docs

4e90e17

Update to 0.1.1

2d434b0

Format and update docs

3e1c5f5

Update version for pip

04546b2

Update license for pip

6cc62bc

Update license for pip

31ef35b

d-montgomery requested a review from Copilot May 13, 2026 22:35

Copilot AI reviewed May 13, 2026

View reviewed changes

Comment thread docs/tutorials.rst

Comment thread README.md Outdated

Comment thread fuellib/_data_locator.py

Potential fix for pull request finding

b527da9

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot started reviewing on behalf of d-montgomery May 14, 2026 00:00 View session

d-montgomery added 10 commits May 14, 2026 08:08

Get version from metadata

30bb2b9

Additional command line utilities

b4d18ef

Update README links

a13fca0

Add CI testing for utilities

231eda1

Add eps2K to API contract

755f6da

Update file structure in docs

064f32e

Simplify custom fuels and add more CLI plotting

83a0e5b

- Rewrite tutorials-custom-fuels.rst for clarity - Add fuel_metadata requirement - Update error messages and fuel manager - Add fl-fuels command to README - Add testing for fuels shipped with FuelLib

Format

86d83bf

Update docs, fix error in decomp for Cycloaromatic-C09

17e73b5

Update baselines after bug in decomp. Update plotting and custom fuel…

83cc618

… handling

d-montgomery added 10 commits May 15, 2026 15:26

Format

67aee46

Add documentation for CLI

0c5b26c

Fix error for Jet A

25964d6

Add temp converters to API contract

6275a0b

Break up fuellib/__init__

2da2de7

BREAKING CHANGES: namespace for convert, utility

d890315

Fix exporter test

bdc8a09

Update version to v3.0.0a1 after breaking changes

6229179

Fix docstrings test

0cd08f7

Move dev tools to cli

416a0e1

d-montgomery requested a review from Copilot May 19, 2026 14:26

Copilot started reviewing on behalf of d-montgomery May 19, 2026 14:27 View session

Copilot AI reviewed May 19, 2026

View reviewed changes

d-montgomery and others added 8 commits May 19, 2026 08:47

Apply suggestions from code review

052e84c

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Implment suggestions from review.

ffe5ac5

Remove unused import of k_B and N_A

185ecb5

- Not exported in __all__, so import was dead code - Access via fl.constants.k_B, fl.constants.N_A when needed

Simplify API, update docs

4a3f0ce

d-montgomery requested a review from Copilot May 19, 2026 17:40

Copilot started reviewing on behalf of d-montgomery May 19, 2026 17:41 View session

Copilot AI reviewed May 19, 2026

View reviewed changes

d-montgomery and others added 4 commits May 19, 2026 12:10

Apply suggestions from code review

978a386

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Resolve comments from review

bd043cb

Update version for PyPi

e7c6c0d

Change default export dir for exporters

cab99c1

Conversation

d-montgomery commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Major Changes

Installation

Module Organization & Architecture

CLI Tools Expansion & Organization

Testing Improvements

Breaking Changes (v3.0.0)

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

d-montgomery commented May 13, 2026 •

edited

Loading