Metadata-Version: 2.5
Name: baslt
Version: 0.1.1
Summary: Compile huge simulation runs into tiny review artifacts with verified fidelity contracts
Author: Ferris Moser
License-Expression: MIT
License-File: LICENSE
Keywords: compression,review,simulation,time series,verification
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Provides-Extra: all
Requires-Dist: h5py>=3.8; extra == 'all'
Requires-Dist: pyyaml>=6; extra == 'all'
Requires-Dist: scipy>=1.10; extra == 'all'
Provides-Extra: hdf5
Requires-Dist: h5py>=3.8; extra == 'hdf5'
Provides-Extra: mat
Requires-Dist: h5py>=3.8; extra == 'mat'
Requires-Dist: scipy>=1.10; extra == 'mat'
Provides-Extra: yaml
Requires-Dist: pyyaml>=6; extra == 'yaml'
Description-Content-Type: text/markdown

# Baslt

**Status: pre-alpha, under active construction.** Nothing here is ready for real review work yet.

Baslt compiles a large simulation or test run into a small review artifact, and proves that the engineering facts
you care about survived the reduction. You write a policy that says what must never be lost — global extrema,
threshold crossings, limit violations, event windows, trajectory accuracy, synchronized signals — and give it a byte
budget. Baslt keeps exactly what the policy protects, fills the rest of the budget with a shape-preserving preview,
and writes a manifest with the evidence. If the budget cannot hold everything the policy protects, compilation fails
and tells you the smallest size that would work, instead of quietly dropping something.

It is designed to stay out of the way of simulation pipelines: runs are compiled after the fact, one tiny artifact
per run, so a sweep of thousands of runs can be triaged in a browser without opening the raw logs.

## Available now

The first end-to-end compiler supports NumPy arrays, CSV, HDF5 and MATLAB MAT-files (v5 to v7.3, including
Simulink "structure with time" logs), with global, window and local extrema (prominence and separation), threshold
crossings, violations, discrete state transitions, events with windows around their triggers, and sync groups that
keep related signals sampled at the same instants. Whatever the budget leaves after that is spent on a preview of
every signal, weighted by the policy's soft priorities, and the artifact never exceeds the budget. `compile`,
`verify`, `inspect`, `policy init` and `explain` are available in the CLI. Compilation verifies its output before
writing it. Unsupported policy features (trajectories for now) produce an explicit error.

```sh
baslt policy init run.mat -o review.yaml     # starter policy for every signal in the file
baslt compile run.csv --policy review.json -o run.baslt
baslt verify run.baslt --source run.csv
baslt inspect run.baslt --json
baslt compile run.csv --policy review.json --max-size 64KiB --error-report run.error.json
baslt explain run.error.json --source run.csv --policy review.json   # what to relax when it does not fit
```

```python
import baslt

result = baslt.compile({"t": t, "pressure": pressure}, {
    "version": 1,
    "hard": {"pressure": {"global_extrema": {}}},
}, output="run.baslt")
verification = baslt.verify_artifact("run.baslt")
```

`baslt.api.verify` also accepts `source=` for source-backed checks. For a pipeline hook, use
`on_error="record", suggestions="off", threads=1`; the returned result carries failures and the adjacent
`.error.json` explains them. See [the CLI reference](docs/cli.md) and [contracts](docs/contracts.md).

## Requirement checks

`baslt check` tests runs against a requirements table from Excel, CSV or a Polarion/DOORS ReqIF export and says what
went wrong: which requirement failed, by how much, when and in which phase. Limits can change per flight phase,
event window, run parameter or as a curve over another signal. One run gives a report page with a plot per
requirement, a results workbook and the requirements table with the verdicts written in; a folder of runs gives a
dashboard with a verdict matrix and each requirement over all runs.

```sh
baslt requirements init -o reqs.xlsx                  # template with examples and a guide
baslt requirements lint reqs.xlsx --source run.h5     # names, units and limits resolved against a run
baslt check run.h5 -r reqs.xlsx                       # run.check/report.html, results.xlsx, reqs.checked.xlsx
baslt check runs/ -r reqs.xlsx --params runs.csv      # every run in parallel; runs.check/index.html
```

See [requirement checks](docs/requirements.md) for the table layout, the expression language and the outputs.

## Planned v0.1 scope

- Inputs: MATLAB `.mat` (v5/v7 and v7.3), HDF5, CSV, and NumPy arrays in memory. MAT-files carry no units, so
  declare them under `signals.decl` when a limit has one.
- Policy file with hard guarantees and soft preferences, units included (`65 kPa`, `7 deg`, `100 ms`, `2 MiB`).
- `baslt compile`, `baslt verify`, `baslt report`, `baslt sweep`, `baslt inspect`, `baslt policy init`,
  `baslt explain`.
- A self-contained HTML viewer for one run and a dashboard for a whole sweep.
- A MATLAB package that can open artifacts without Python and call the compiler through Python when available.

## License

MIT. See `LICENSE`.
