PyHFM - Heat Flow Meter Data Analysis
PyHFM is a Python package for reading and analyzing Heat Flow Meter (HFM) data files. It provides a clean, modern API for parsing HFM measurement data and extracting thermal conductivity and volumetric heat capacity measurements.
Features
- Simple API: Clean
read_hfm()function for easy data loading - Multiple Formats: Support for thermal conductivity and volumetric heat capacity measurements
- Rich Metadata: Comprehensive metadata extraction and validation
- Modern Data Stack: Built on PyArrow for efficient data handling
- Type Safety: Full type annotations for better development experience
- Comprehensive Testing: Extensive test suite for reliability
- CLI Support: Command-line interface for quick data conversion
Installation
pip install pyhfm
For development installation:
git clone https://github.com/GraysonBellamy/pyhfm.git
cd pyhfm
pip install -e ".[dev,test]"
Quick Start
Basic Usage
import pyhfm
# Read HFM file and get PyArrow table
table = pyhfm.read_hfm("sample.tst")
# Convert to polars DataFrame for analysis
import polars as pl
df = pl.from_arrow(table)
print(df.head())
Access Metadata
# Get both metadata and data
metadata, table = pyhfm.read_hfm("sample.tst", return_metadata=True)
print(f"Sample: {metadata['sample_id']}")
print(f"Type: {metadata['type']}")
print(f"Setpoints: {metadata['number_of_setpoints']}")
Custom Configuration
# Override default settings
config = {"default_encoding": "utf-8"}
table = pyhfm.read_hfm("sample.tst", config=config)
Data Structure
PyHFM returns data in PyArrow tables with the following schemas:
Thermal Conductivity Measurements
| Column | Type | Description |
|---|---|---|
setpoint |
int32 | Setpoint number |
upper_temperature |
float64 | Upper plate temperature |
lower_temperature |
float64 | Lower plate temperature |
upper_thermal_conductivity |
float64 | Upper thermal conductivity result |
lower_thermal_conductivity |
float64 | Lower thermal conductivity result |
Volumetric Heat Capacity Measurements
| Column | Type | Description |
|---|---|---|
setpoint |
int32 | Setpoint number |
average_temperature |
float64 | Average temperature |
volumetric_heat_capacity |
float64 | Volumetric heat capacity result |
Command Line Interface
PyHFM includes a CLI for quick data conversion:
# Convert to CSV
pyhfm sample.tst --output sample.csv --format csv
# Convert to Parquet with metadata
pyhfm sample.tst --output sample.parquet --format parquet --metadata
# Print to stdout as JSON
pyhfm sample.tst --format json
Advanced Usage
Custom Parser
from pyhfm import HFMParser
# Create parser with custom configuration
parser = HFMParser(config={"default_encoding": "utf-16le"})
table = parser.parse_file("sample.tst")
Data Extraction
from pyhfm import DataExtractor
# Extract data from metadata
extractor = DataExtractor()
table = extractor.extract_data(metadata)
Error Handling
import pyhfm
try:
table = pyhfm.read_hfm("sample.tst")
except pyhfm.HFMFileError as e:
print(f"File error: {e}")
except pyhfm.HFMParsingError as e:
print(f"Parsing error: {e}")
except pyhfm.HFMValidationError as e:
print(f"Validation error: {e}")
Supported File Formats
- HFM Test Files (
.tst): Standard HFM output format - Encodings: UTF-16LE (default), UTF-8, and auto-detection
- Measurements: Thermal conductivity and volumetric heat capacity
Architecture
PyHFM follows a modular architecture inspired by the pynetzsch package:
pyhfm/
api/ # High-level user API
core/ # Core parsing logic
extractors/ # Data extraction components
constants.py # Configuration and data types
exceptions.py # Custom exception hierarchy
__init__.py # Public API exports
Development
Setup Development Environment
git clone https://github.com/GraysonBellamy/pyhfm.git
cd pyhfm
pip install -e ".[dev,test]"
pre-commit install
Run Tests
pytest
Code Quality
ruff check . # Linting
ruff format . # Formatting
mypy src/pyhfm # Type checking
Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Add tests for your changes
- Ensure all tests pass (
pytest) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
License
This project is licensed under the MIT License - see the LICENSE file for details.
Changelog
v0.1.0 (2024-01-01)
- Initial release
- Support for thermal conductivity and volumetric heat capacity measurements
- PyArrow-based data handling
- Comprehensive metadata extraction
- CLI interface
- Full type annotations
Related Projects
- pynetzsch - Python package for NETZSCH thermal analysis data
Support
If you encounter any issues or have questions, please:
- Check the documentation
- Search existing issues
- Create a new issue if needed
Metadata
Release files for pyhfm 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pyhfm-0.1.1.tar.gz | 51.5 kB | With provenance | Details for pyhfm-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pyhfm-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for pyhfm-0.1.1-py3-none-any.whl |
Total release size: 77.5 kB
Release files / pyhfm-0.1.1.tar.gz
| Download URL | pyhfm-0.1.1.tar.gz |
|---|---|
| Size | 51.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
03647d152a9eb43ca03db404c97eaecd81b5f01d875963ad03b9d1d617000038
|
|
BLAKE2b-256 checksum How to use checksums |
2b60148a437cd7d6689b60a5a0b8afaa68d5d11887692d7e1499a1d297091c73
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 15, 2026.
Transparency logRelease files / pyhfm-0.1.1-py3-none-any.whl
| Download URL | pyhfm-0.1.1-py3-none-any.whl |
|---|---|
| Size | 26.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d940fbf33d43c1c291a2e45323a69e016d987019ef5322eb7ba7a711ea412074
|
|
BLAKE2b-256 checksum How to use checksums |
19fa06216ee799523170ffc0511d55b569259406da1e3ccc799ef4ed06030ca2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 15, 2026.
Transparency logSecurity for pyhfm 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for pyhfm-0.1.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 15, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.