Reorganization for install with pip or conda

.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
 

.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
+          fl-build-docs
 
       - 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'

.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

README.md

@@ -15,37 +15,70 @@ 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 exporters (`fl-export-pele` and `fl-export-converge`) available.
+
+### 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: Create a Conda Environment
+
+To use a specific conda environment:
+
+```bash
+conda create --name fuellib-env python numpy pandas scipy matplotlib
+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. 
 

docs/conf.py

@@ -5,7 +5,8 @@
 import os
 import sys
 
-sys.path.insert(0, os.path.abspath("../source"))
+# Add parent directory to path so we can import fuellib
+sys.path.insert(0, os.path.abspath(".."))
 
 
 # -- Project information -----------------------------------------------------

docs/development.rst

@@ -0,0 +1,64 @@
+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
+- **Plotting:** matplotlib
+
+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