From 6d9c029e89e395b7e04e39b04a61590f9ed6647e Mon Sep 17 00:00:00 2001
From: Nicolas Kruse <nicolas@nonan.net>
Date: Mon, 2 Jun 2025 16:26:59 +0200
Subject: [PATCH] CI-script and readme updated

---
 .github/workflows/ci.yml | 11 +++----
 thermo_data/README.md    | 66 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 71 insertions(+), 6 deletions(-)
 create mode 100644 thermo_data/README.md

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index b97b673..52247c5 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -15,30 +15,29 @@ jobs:
         python-version: ["3.10", 3.11, 3.12, 3.13]
 
     steps:
-    # Step 1: Check out the code from the repository
     - name: Check out code
       uses: actions/checkout@v4
 
-    # Step 2: Set up Python
     - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
 
-    # Step 3: Install dependencies
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
         python -m pip install -e .[dev]
 
-    # Step 4: Lint with flake8
+    - name: Prepare data and compile thermo database
+      run: |
+        python thermo_data/combine_data.py thermo_data/combined_data.yaml thermo_data/nasa9*.yaml thermo_data/nasa9*.xml
+        python thermo_data/compile_to_bin.py thermo_data/combined_data.yaml src/gaspype/data/therm_data.bin
+
     - name: Lint code with flake8
       run: flake8
 
-    # Step 5: Check types with mypy
     - name: Type checking with mypy
       run: mypy
 
-    # Step 6: Run tests
     - name: Run tests with pytest
       run: pytest
\ No newline at end of file
diff --git a/thermo_data/README.md b/thermo_data/README.md
new file mode 100644
index 0000000..c8b0378
--- /dev/null
+++ b/thermo_data/README.md
@@ -0,0 +1,66 @@
+# Data preparation
+Gaspype uses a binary format for thermodynamic data to minimize memory usage and startup time.
+
+## Combine and prepare data
+To prepare the data from YAML and XML sources:
+
+``` bash
+python combine_data.py combined_data.yaml nasa9*.yaml nasa9*.xml
+```
+General Syntax is: ```python combine_data.py OUTPUT_YAML_FILE INPUT_FILE_PATTERN_1 INPUT_FILE_PATTERN_2 ...```
+
+Example output format for a single file entry:
+``` yaml
+- name: HCl
+  composition: {Cl: 1, H: 1}
+  thermo:
+    model: NASA9
+    temperature-ranges: [200.0, 1000.0, 6000.0]
+    data:
+    - [20625.88287, -309.3368855, 5.27541885, -0.00482887422, 6.1957946e-06, -3.040023782e-09, 4.91679003e-13, -10677.82299, -7.309305408]
+    - [915774.951, -2770.550211, 5.97353979, -0.000362981006, 4.73552919e-08, 2.810262054e-12, -6.65610422e-16, 5674.95805, -16.42825822]
+    note: Gurvich,1989 pt1 p186 pt2 p93. [tpis89]
+```
+
+Compile ```combined_data.yaml``` to the binary gaspype format:
+``` bash
+python compile_to_bin.py combined_data.yaml ../src/gaspype/data/therm_data.bin
+```
+General syntax is: ```python compile_to_bin.py YAML_INPUT_FILE BINARY_OUTPUT_FILE```
+
+The binary format is structured like this, it uses little-endian and IEEE 754 floats:
+```
+[4 Byte magic number: 'gapy']
+[8 Byte: 32 Bit integer for length of all species names (NAMES_LENGTH)]
+[NAMES_LENGTH Bytes: ASCII encoded string with all species names separated by space]
+[Index
+    [For each species
+        [4 Bytes: 32 Bit uint with offset of species data in file]
+        [1 Byte:   8 Bit uint with number of elements]
+        [1 Byte:   8 Bit uint for polygon length, value = 9]
+        [1 Byte:   8 Bit uint for number of temperature supporting points (NUM_TEMPS)]
+        [1 Byte:   8 Bit uint for length of reference string (REF_LEN)]
+    ]
+]
+[Data
+    [For each species
+        [For each species element
+            [2 Byte: element name in ASCII, 0x20 padded]
+            [1 Byte: 8 Bit uint for number of atoms]
+        ]
+        [For Range(NUM_TEMPS)
+            [4 Byte: 32 Bit float with temperature supporting point]
+        ]
+        [For Range(NUM_TEMPS - 1)
+            [36 Bytes: 9 x 32 Bit float with NASA9-Polynomial for a temperature interval]
+        ]
+        [REF_LEN Bytes: ASCII string of the data reference]
+    ]
+]
+```
+
+## Notes
+- Original source of the data compilation: https://ntrs.nasa.gov/citations/20020085330
+- nasa9_*.yaml files are exported from https://cearun.grc.nasa.gov/ThermoBuild/ and
+  converted with ck2yaml (https://cantera.org/stable/userguide/thermobuild.html)
+- nasa9polynomials.xml is from: https://github.com/guillemborrell/thermopy/tree/master/databases
\ No newline at end of file