Metadata-Version: 2.4
Name: mestra
Version: 0.1.3
Summary: An open file format for simulation studies and the surrogate models fitted to them: reader, writer, validator and post-processing.
Author: Bijective Systems
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/bijective-systems-org/gamut
Project-URL: Repository, https://github.com/bijective-systems-org/gamut/tree/v0.1.3
Project-URL: Specification, https://github.com/bijective-systems-org/gamut/blob/v0.1.3/SPEC.md
Project-URL: Guide, https://github.com/bijective-systems-org/gamut/blob/v0.1.3/docs/guide.md
Project-URL: Issues, https://github.com/bijective-systems-org/gamut/issues
Keywords: simulation,surrogate,surrogate-model,hdf5,netcdf,dataset,cfd,fea,cae,mesh,uncertainty,scientific-machine-learning,parametric-study
Classifier: Development Status :: 7 - Inactive
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: File Formats
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: h5py>=3.7
Provides-Extra: checks
Requires-Dist: netCDF4>=1.6; extra == "checks"
Requires-Dist: h5netcdf>=1.0; extra == "checks"
Provides-Extra: xarray
Requires-Dist: xarray>=2023.1; extra == "xarray"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.5; extra == "dev"
Dynamic: license-file

mestra is now Gamut
===================

mestra continues as [Gamut](https://github.com/bijective-systems-org/gamut),
version 1 of the format, with a new implementation:

    pip install gamut-format

This is the last release of mestra. It still reads and writes `mestra/0`
files; Gamut refuses them, naming their version. The documentation for
this release is the
[v0.1.3 tree](https://github.com/bijective-systems-org/gamut/tree/v0.1.3).


mestra for Python
=================

What the format is, and what it is for: the
[project README](https://github.com/bijective-systems-org/gamut/tree/v0.1.3#readme).

Install
-------

    pip install mestra

or, from a checkout of the repository, `pip install -e python/`.
Runtime dependencies are numpy and h5py, and nothing else; netCDF4,
h5netcdf and xarray are optional, used by the cross-reader checks and
by one adapter. The suite needs pytest, which the `dev` extra
installs:

    pip install -e "python/[dev]"
    python -m pytest python/tests

Three golden files are too large to commit. Write them once before
the suite, as [`vectors/README.md`](https://github.com/bijective-systems-org/gamut/blob/v0.1.3/vectors/README.md) says; a test that wants one
skips without it rather than failing.

    python vectors/generate.py --on-demand


The ten-line example
--------------------

    import mestra

    ds = mestra.Dataset(writer="my tool 1")
    ds.add_key("mach", [0.4, 0.8], role="condition", units="1")
    s = ds.add_support("s0", coordinates=[0., 1., 2.], units="m")
    s.add_node_array("pressure", [[101., 102., 103.],
                                  [201., 202., 203.]],
                     units="Pa", dims=("row", "node"))
    mestra.write(ds, "run.mes")
    with mestra.read("run.mes") as d:
        p = d.supports["s0"].node_arrays["pressure"]
        print(p.values.at(row=1, node=2, component=0))    # 203.0

It is the same data and the same value in all four languages.
[`docs/examples/`](https://github.com/bijective-systems-org/gamut/tree/v0.1.3/docs/examples) has seven worked examples, one per concept, each
runnable and under thirty lines, and [`docs/guide.md`](https://github.com/bijective-systems-org/gamut/blob/v0.1.3/docs/guide.md) says what the
concepts mean. Every call has its own documentation where you meet
it: `help(mestra)` and `help(mestra.Dataset)` for the library,
`mestra --help` for the command line.


Axis order and permute by name
------------------------------

Python hands an array back in the order the file stores it (SPEC
section 19): what it varies along first, then the nodes or the cells,
then the components. A reader in a column-major language hands the
same array back in the reverse order, and the dimension names are
what the two agree on, so index by name and permute by name and never
count axes.

    p.dims                                   # row, node, component
    p.values.at(row=1, node=2, component=0)              # 203.0
    p.values.transpose("component", "node", "row")

The names are those of SPEC section 4, an axis `at()` is not given
comes back whole, and the value at row 1, node 2, component 0 of the
example above is 203.0 in every language.


What the reader refuses
-----------------------

`read` refuses a file that breaks a rule it cannot vouch for what it
would return under -- E01, E16, E19, E25, E26, E29, E30, E40, E41,
which are `mestra.reader.REFUSED` -- and raises `MestraError` naming
the first; a semantic fault never stops a read, and
`read(path, strict=False)` hands back whatever could be read anyway.
The findings are on `dataset.problems` either way, `mestra.validate`
repeats them, and what could not be copied is in `dataset.lossy`.
`help(mestra.reader)` and `mestra.limits` carry the rest.

A refusal is what this package can promise. What it cannot promise is
that libhdf5 returns control on a file whose bytes were damaged: a
crafted single-byte change can fault or hang the library before any
code here runs ([`docs/compatibility.md`](https://github.com/bijective-systems-org/gamut/blob/v0.1.3/docs/compatibility.md#damaged-files), "Damaged files";
`tests/test_mutation.py` measures it). Read a file nobody vouches for
from a process you can kill, as `mestra validate` does.


Where to go next
----------------

[`docs/guide.md`](https://github.com/bijective-systems-org/gamut/blob/v0.1.3/docs/guide.md) is the format in plain words, with one runnable
example per concept. [`SPEC.md`](https://github.com/bijective-systems-org/gamut/blob/v0.1.3/SPEC.md) is the reference, read by section.
[`docs/api-conventions.md`](https://github.com/bijective-systems-org/gamut/blob/v0.1.3/docs/api-conventions.md) is the names, the argument order, the
defaults and the messages all four languages follow, for anyone
comparing two of them.

Licence: Apache-2.0, as the rest of the code in this repository.
