NatLabRockies · d-montgomery · May 13, 2026 · May 13, 2026 · May 13, 2026 · May 13, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -50,7 +50,7 @@ jobs:
           python-version: '3.11'
       - run: |
           python -m pip install --upgrade pip
-          pip install numpy pandas scipy
+          pip install -e .
       - run: python tests/test_accuracy.py
 
   API:
@@ -62,7 +62,7 @@ jobs:
           python-version: '3.11'
       - run: |
           python -m pip install --upgrade pip
-          pip install numpy pandas scipy
+          pip install -e .
       - run: python tests/test_api.py -v
 
   Source-Docstrings:
@@ -74,8 +74,33 @@ jobs:
           python-version: '3.11'
       - run: |
           python -m pip install --upgrade pip
+          pip install -e .
       - run: python tests/test_source_docstrings.py -v
 
+  Utilities:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[dev]'
+      - run: python -m pytest tests/test_utilities.py -v
+
+  Hydrocarbon-Identification:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[dev]'
+      - run: python -m pytest tests/test_hc_identification.py -v -s
+
   Exporting-Scripts:
     runs-on: ubuntu-latest
     steps:
@@ -85,19 +110,6 @@ jobs:
           python-version: '3.11'
       - run: |
           python -m pip install --upgrade pip
-          pip install numpy pandas scipy
-      - name: Export4Pele - individual component export
-        run: python source/Export4Pele.py --fuel_name posf10264
-      - name: Export4Pele - mixture export with GCM model
-        run: python source/Export4Pele.py --fuel_name posf10264 --export_mix True
-      - name: Export4Pele - mixture export with MP model
-        run: python source/Export4Pele.py --fuel_name posf10264 --export_mix True --liq_prop_model mp
-      - name: Export4Pele - mixture export with CGS units
-        run: python source/Export4Pele.py --fuel_name posf10264 --export_mix True --units cgs
-      - name: Export4Pele - single deposit species
-        run: python source/Export4Pele.py --fuel_name posf10264 --dep_fuel_names POSF10264
-      - name: Export4Converge - individual component export
-        run: python source/Export4Converge.py --fuel_name posf10264
-      - name: Export4Converge - mixture export
-        run: python source/Export4Converge.py --fuel_name posf10264 --export_mix 1 --temp_min 280 --temp_max 400 --temp_step 10
+          pip install -e .
+      - run: python tests/test_exporters.py
 
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -32,17 +32,17 @@ jobs:
 
       - name: Install dependencies
         run: |
-          pip install sphinx sphinx_rtd_theme myst_parser sphinxcontrib-bibtex pandas scipy
+          pip install -e '.[dev]'
 
       - name: Build docs
         run: |
-          sphinx-build -b html -W docs _build
+          sphinx-build -W -b html docs docs/_build/html
 
       - name: Upload artifact (for PR preview or later steps)
         uses: actions/upload-artifact@v4
         with:
           name: site
-          path: _build
+          path: docs/_build/html
 
   Deploy-Docs:
     if: github.event_name == 'push'

diff --git a/.gitignore b/.gitignore
@@ -6,5 +6,20 @@ _build*
 generated*
 sprayPropsGCM*
 mixturePropsGCM*
+exportData
 
+# Python packaging
+*.egg-info/
+dist/
+build/
+*.egg
+*.whl
 
+# Virtual environments
+.env
+env/
+venv/
+
+# Figures from plotting tools
+composition_*.png
+mixture_*.png
diff --git a/CHANGES.md b/CHANGES.md
@@ -0,0 +1,53 @@
+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 publishing guide has been added, and Sphinx documentation references and paths have been updated for consistency.
+
+## Major Changes
+
+### 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`. 
+
+### 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
+- Total test suite: 40 tests, all passing
+
+### Documentation & Bug Fixes
+- Fixed CSV file path in `fuelprops.rst`: `../../fuelData/` → `../fuellib/data/fuelData/`
+- Updated `sourcecode.rst` to reflect new file organization
+- Added Sphinx docstring comments to `constants.py` and `fuel.py` attributes
+- Fixed GitHub Actions failures related to decomposition metadata
+- Fixed error handling for Jet A and cycloaromatic compounds
+
+### CI/CD Modernization
+- Switched to editable/development installs (`pip install -e .` and `pip install -e '.[dev]'`)
+- Updated GitHub Actions workflows to use new installation methods
+
+## 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
diff --git a/README.md b/README.md
@@ -15,37 +15,74 @@ If you use FuelLib in your research, please cite the following software record:
 Montgomery, David, Appukuttan, Sreejith, Yellapantula, Shashank, Perry, Bruce, and Binswanger, Adam. FuelLib (Fuel Library) [SWR-25-26]. Computer Software. https://github.com/NatLabRockies/FuelLib. USDOE Office of Energy Efficiency and Renewable Energy (EERE), Office of Sustainable Transportation. Vehicle Technologies Office (VTO). 27 Feb. 2025. Web. doi:10.11578/dc.20250317.1.
 ~~~
 
-## Python Environment
-The following conda environment is required to run this code:
-~~~
-conda create --name fuellib-env matplotlib pandas scipy black=26.3.1
-~~~
+## Installation
+
+### Option 1: Install from PyPI (Recommended)
+
+The easiest way to install FuelLib is via pip:
+
+```bash
+pip install fuellib
+```
+
+This will make the command-line tools available, including:
+- `fl-export-pele` and `fl-export-converge` for exporting fuel properties
+- `fl-plt-props` and `fl-plt-comp` for plotting fuel composition and properties
+- `fl-fuels` for listing available fuels
+- Temperature and unit conversion utilities
+
+### Option 2: Development Installation (For Contributors)
+
+Clone the repository and install in editable mode:
+
+```bash
+git clone https://github.com/NatLabRockies/FuelLib.git
+cd FuelLib
+pip install -e '.[dev]'  # Install with development tools (docs, testing, formatting)
+```
 
-## Running the Code
-This repository includes multiple tutorials of ways to use FuelLib.  We recommend starting with the basic tutorial, `tutorials/basic.py`, which is documented at [https://NatLabRockies.github.io/FuelLib/tutorials.html#introduction]. The script `tutorials/mixtureProperties.py` calculates a given mixture's density, viscosity and vapor pressure from GC x GC data.  The results are plotted against data from NIST and [Edwards (2020)](https://apps.dtic.mil/sti/pdfs/AD1093317.pdf). 
+See the [Contributing](https://NatLabRockies.github.io/FuelLib/development.html) page for more detailed setup instructions and contribution guidelines.
+
+### Optional: Use a Dedicated Conda Environment
+
+For better dependency isolation, you can create a conda environment first:
+
+```bash
+conda create --name fuellib-env python
+conda activate fuellib-env
+pip install fuellib
+```
+
+## Library Usage
+This repository includes multiple tutorials of ways to use FuelLib.  We recommend starting with the basic tutorial, [`tutorials/basic.py`](https://github.com/NatLabRockies/FuelLib/blob/main/tutorials/basic.py), which is documented at [https://natlabrockies.github.io/FuelLib/tutorials-basic.html](https://natlabrockies.github.io/FuelLib/tutorials-basic.html). The script [`tutorials/mixtureProperties.py`](https://github.com/NatLabRockies/FuelLib/blob/main/tutorials/mixtureProperties.py) calculates a given mixture's density, viscosity and vapor pressure from GC x GC data.  The results are plotted against data from NIST and [Edwards (2020)](https://apps.dtic.mil/sti/pdfs/AD1093317.pdf).
+
+### Command-Line Tools
+After installing FuelLib using one of the methods above, you have access to several command-line tools for plotting, unit conversion, and exporting fuel data. A comprehensive list is provided in the documentation at [https://natlabrockies.github.io/FuelLib/tutorials-cli.html](https://natlabrockies.github.io/FuelLib/tutorials-cli.html).
 
 # Contributing
-New contributions are always welcome.  If you have an idea for a new feature follow these steps:
+New contributions are always welcome! For detailed contribution guidelines, installation instructions, and development setup, see the [Contributing](https://NatLabRockies.github.io/FuelLib/development.html) page in the documentation.
+
+Quick start:
 1. Fork the main repository
 2. Create a `newFeature` branch that contains your changes
 3. Update the sphinx documentation in `newFeature`
-4. Format the source code files using the [Black code formatter](https://github.com/psf/black) by running the following command:
-   (CI currently uses Black version `26.3.1`; use the same version locally.)
-   ~~~
-   find . -name "*.py" -print0 | xargs -0 black
-   ~~~
-5. Open a Pull Request (PR) from `newFeature` on your fork to branch `main` FuelLib repository.
+4. Install development dependencies: `pip install -e '.[dev]'`
+5. Format the source code files using the provided CLI command: `fl-format`
+6. Run tests and build documentation locally to verify your changes
+7. Open a Pull Request (PR) from `newFeature` on your fork to branch `main` FuelLib repository.
 
 ## Sphinx Documentation
-This repository uses [Sphinx](https://www.sphinx-doc.org/en/master/usage/quickstart.html) to generate documentation.  This requires the following Conda environment:
+This repository uses [Sphinx](https://www.sphinx-doc.org/en/master/usage/quickstart.html) to generate documentation.
+
+To build the documentation, first install FuelLib with development support:
 ~~~
-conda create --name sphinx-env sphinx sphinx_rtd_theme sphinxcontrib-bibtex pandas scipy
+pip install -e ".[dev]"
 ~~~
 
-To view the documentation locally, build the html using the following: 
+Then use the provided CLI command:
 ~~~
-cd FuelLib/docs/
-sphinx-build -M html . _build/
+fl-build-docs
 ~~~
-You should now be able to view the html by opening `FuelLib/docs/_build/html/index.html` in a web browser. 
+
+The HTML documentation will be generated in `docs/_build/html/`. Open `docs/_build/html/index.html` in your web browser to view it. 
 
diff --git a/customFuels b/customFuels
diff --git a/docs/conf.py b/docs/conf.py
@@ -5,7 +5,10 @@
 import os
 import sys
 
-sys.path.insert(0, os.path.abspath("../source"))
+# Add parent directory to path so we can import fuellib
+DOCS_DIR = os.path.abspath(os.path.dirname(__file__))
+PROJECT_ROOT = os.path.abspath(os.path.join(DOCS_DIR, ".."))
+sys.path.insert(0, PROJECT_ROOT)
 
 
 # -- Project information -----------------------------------------------------

diff --git a/docs/development.rst b/docs/development.rst
@@ -0,0 +1,63 @@
+Contributing to FuelLib
+=======================
+
+We welcome contributions! This page covers how to set up your development environment, make changes, and submit pull requests.
+
+Development Setup
+-----------------
+
+Clone the repository and install in editable mode with development dependencies:
+
+.. code-block:: bash
+
+   git clone https://github.com/NatLabRockies/FuelLib.git
+   cd FuelLib
+   pip install -e '.[dev]'
+
+This installs FuelLib with all development tools:
+
+- **Documentation:** Sphinx, sphinx-rtd-theme, sphinxcontrib-bibtex
+- **Code formatting:** Black
+- **Testing:** pytest
+
+Optional: Conda Environment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To use a specific conda environment:
+
+.. code-block:: bash
+
+   conda create --name fuellib-env python numpy pandas scipy matplotlib
+   conda activate fuellib-env
+   pip install -e '.[dev]'
+
+Contributing Guidelines
+-----------------------
+
+New contributions are always welcome! To contribute:
+
+1. Fork the main repository on GitHub
+2. Create a new branch for your feature: ``git checkout -b newFeature``
+3. Make your changes and update documentation as needed
+4. Ensure development dependencies are installed (see Development Setup above)
+5. Format your code using Black ``fl-format``
+
+6. Run tests to verify your changes. See `.github/workflows/ci.yml` for the most up-to-date list of tests run in CI
+7. Open a Pull Request (PR) from your fork to the main FuelLib repository
+
+Building and Viewing Documentation Locally
+-------------------------------------------
+
+To build the documentation after installing with ``pip install -e '.[dev]'``:
+
+.. code-block:: bash
+
+   fl-build-docs
+
+The built documentation will be in ``docs/_build/html/``. Open ``index.html`` in your browser to view it.
+
+To clean the build artifacts:
+
+.. code-block:: bash
+
+   fl-clean-docs
diff --git a/docs/figures/composition_posf10325.png b/docs/figures/composition_posf10325.png
diff --git a/docs/figures/mixture_properties_posf10264_posf10325_posf10289.png b/docs/figures/mixture_properties_posf10264_posf10325_posf10289.png