Metadata-Version: 2.4
Name: vcti-dataspace-nastran-h5
Version: 1.0.0
Summary: Nastran HDF5 data space — solution file navigation, modal data extraction, and result access for MSC.Nastran H5 output files
Author: Visual Collaboration Technologies Inc.
License-Expression: LicenseRef-Proprietary
Project-URL: Repository, https://github.com/vcollab/vcti-python-dataspace-nastran-h5
Project-URL: Documentation, https://github.com/vcollab/vcti-python-dataspace-nastran-h5#readme
Project-URL: Changelog, https://github.com/vcollab/vcti-python-dataspace-nastran-h5/blob/main/CHANGELOG.md
Requires-Python: <3.15,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: h5py>=3.0
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Provides-Extra: lint
Requires-Dist: ruff; extra == "lint"
Provides-Extra: typecheck
Requires-Dist: mypy; extra == "typecheck"
Dynamic: license-file

# DataSpace Nastran H5

Nastran HDF5 data space — solution file navigation, modal data extraction, and result access for MSC.Nastran H5 output files.

## Overview

MSC.Nastran writes simulation results (eigenvalues, modal participation factors,
displacements, etc.) into HDF5 (`.h5`) output files with a standard hierarchical
structure rooted at `NASTRAN/RESULT/`. This library provides read-only access to
those files, wrapping h5py to navigate the Nastran HDF5 hierarchy and extract
datasets as NumPy arrays.

Two main classes cover different levels of access:

- **NastranH5File** — opens a single `.h5` file for direct dataset, group, and
  attribute access by HDF5 path.
- **NastranSolutionFolder** — scans a directory for `.h5` files and provides
  dataset retrieval by logical type (e.g., `{"type": "modes"}`).

## Installation

```bash
pip install vcti-dataspace-nastran-h5>=1.0.0
```

---

## Quick Start

```python
from pathlib import Path
from vcti.dataspace_nastran_h5 import NastranH5File, NastranSolutionFolder

# Direct H5 file access
with NastranH5File(Path("sol103.h5")) as h5:
    tables = h5.get_modal_tables()
    mpf = h5.get_modal_participation_factors()
    eigenvalues = h5.get_dataset("NASTRAN/RESULT/MODAL/EIGENVALUE")

# Solution folder access
with NastranSolutionFolder(Path("sol103_results/")) as folder:
    data = folder.get_dataset({"type": "modes"})
```

---

## Core API

### NastranH5File

| Method | Description |
|--------|-------------|
| `get_modal_tables()` | List modal tables under NASTRAN/RESULT/MODAL |
| `get_modal_participation_factors()` | Get modal participation factor data |
| `get_dataset(path)` | Get any dataset by HDF5 path |
| `get_group_keys(path)` | List keys in an HDF5 group |
| `get_attributes(path)` | Get HDF5 attributes |
| `is_valid` | Check if file is open |
| `close()` | Close the file |

### NastranSolutionFolder

| Method | Description |
|--------|-------------|
| `get_dataset(dsattr)` | Get dataset by type (e.g., `{"type": "modes"}`) |
| `get_modal_tables()` | List modal tables from H5 file |
| `list_h5_files()` | List all H5 files in the folder |
| `h5_file` | The active `NastranH5File` (read-only property) |
| `is_valid` | Check if folder has a valid H5 file |
| `close()` | Close the H5 file |

Both classes support context managers (`with` statement).

---

## Dependencies

- [h5py](https://www.h5py.org/) (>=3.0)
- [numpy](https://numpy.org/) (>=1.24)
