Skip to main content

PyHFM - Heat Flow Meter Data Analysis

Python 3.10+ License: MIT

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.

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Add tests for your changes
  5. Ensure all tests pass (pytest)
  6. Commit your changes (git commit -m 'Add amazing feature')
  7. Push to the branch (git push origin feature/amazing-feature)
  8. 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
  • pynetzsch - Python package for NETZSCH thermal analysis data

Support

If you encounter any issues or have questions, please:

  1. Check the documentation
  2. Search existing issues
  3. 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)

Source distribution for pyhfm 0.1.1
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)

Table of built distributions (wheels) for pyhfm 0.1.1
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page