SSAPy-Data

SSAPy-Data stores reusable data resources for SSAPy and SSAPy Toolkit. The repository is packaged as the llnl-ssapy-data Python distribution and exposes the ssapy_data import package. Data files live under src/ssapy_data/data so users can receive required data through normal pip installation without Git LFS, git submodules, or runtime GitHub downloads.

The initial package intentionally does not duplicate data already packaged by base SSAPy. New SSAPy Toolkit datasets should be added here when they are needed by toolkit functions and are not already available from the base llnl-ssapy wheel.

Installation

Install from a local clone in editable mode:

pip install -e .

Build the wheel and source distribution:

python -m build
ls -lh dist/

Using packaged data

Access packaged data with importlib.resources helpers exposed by ssapy_data:

from ssapy_data import data_path, read_text

data_readme = read_text("README.md")

with data_path("earth_day_2048.jpg") as path:
    print(path)

data_path yields a real filesystem path for libraries that require paths. Use the path only inside the context manager because zipped wheels may extract resources to temporary locations.

Propulsion data

Reusable propulsion resources live under propulsion/. Electric propulsion benchmark throttle maps are packaged under propulsion/throttle_maps/electric. These electric files are steady-state operating-point tables, not transient start-up or shutdown curves. Digitized thrust curves from public NASA Technical Reports Server (NTRS) plots are packaged under propulsion/thrust_curves/digitized/nasa_ntrs with one CSV and one sidecar JSON metadata file per curve. These files are derived from calibrated plot extraction rather than original tabular source data, so use the recorded uncertainty and validation notes when treating them as benchmarks. Solid and hybrid motor time-thrust curves should be imported only from sources with explicit redistribution rights. The helper script scripts/import_thrustcurve_pd.py imports only ThrustCurve.org records marked license="PD" from RASP and RockSim simulator files, then writes normalized time_s,thrust_n CSV files.

The packaged ThrustCurve.org snapshot includes an index.csv summary under propulsion/thrust_curves/solid_motor_pd/thrustcurve_org. Use the index to select a curve by manufacturer, designation, impulse class, burn time, thrust, or total impulse before loading the neighboring normalized CSV. The propulsion directory also includes sources.json and source_audit.md to record source URLs, rights metadata, transformations, and searched sources that were packaged, rejected, or deferred.

Adding data

Add new reusable data below src/ssapy_data/data. Preserve source filenames when possible, and use subdirectories when a dataset has multiple sidecar files. Do not add files already packaged by base SSAPy unless a later migration explicitly moves that dependency here. After adding, replacing, or removing data, regenerate the manifest:

python scripts/update_manifest.py
python -m pytest
python -m build

The manifest records each packaged file path, byte count, and SHA-256 digest in src/ssapy_data/manifest.json. Pull requests that change data should also update the source/provenance notes in this README when the dataset source or license differs from the existing entries.

Size guidance

The initial wheel contains only the package helpers and a data-directory README. Before adding large datasets, estimate the built wheel size with:

python -m build --wheel
ls -lh dist/*.whl

If a future dataset pushes the wheel above PyPI limits, split the data into a separate companion package rather than using Git LFS in SSAPy Toolkit.

Publishing

The repository publishes llnl-ssapy-data to PyPI through GitHub Actions and PyPI trusted publishing. Configure PyPI before creating the first release:

• Create a PyPI trusted publisher, or pending publisher, for project llnl-ssapy-data.
• Set the owner to llnl and repository to SSAPy-Data.
• Set the workflow filename to publish.yml.
• Set the GitHub environment to pypi.

After PyPI trust is configured, publish by pushing a git tag that matches the version in pyproject.toml, for example v0.1.1. The Publish to PyPI workflow builds a clean wheel and source distribution, runs tests, checks the manifest, and uploads through OpenID Connect (OIDC). No PyPI API token is required.

Data provenance

Each data pull request should document the source URL, license, retrieval date, and any preprocessing steps for new packaged datasets. Top-level source records live in src/ssapy_data/data/sources.json. Propulsion source records live in src/ssapy_data/data/propulsion/sources.json. Candidate sources include:

• Earth gravity fields: ICGEM time-variable gravity fields
• Other celestial bodies: ICGEM celestial gravity fields

Code of Conduct

Please note that SSAPy-Data has a Code of Conduct. By participating in the SSAPy-Data community, you agree to abide by its rules.

License

SSAPy-Data is distributed under the terms of the MIT license. All new contributions must be made under the MIT license.

See the license and NOTICE for details.

SPDX-License-Identifier: MIT

LLNL-CODE-862420