### Install Example Dependencies

Source: https://github.com/ecmwf/tensogram/blob/main/examples/typescript/README.md

Install dependencies for the TypeScript examples, including tsx for direct .ts file execution.

```bash
cd examples/typescript
npm install
```

--------------------------------

### Run Tensogram Examples

Source: https://github.com/ecmwf/tensogram/blob/main/docs/src/guide/typescript-api.md

Navigate to the examples directory and install dependencies to run the provided TypeScript scripts.

```bash
cd examples/typescript
npm install
npx tsx 01_encode_decode.ts     # or any other file
```

--------------------------------

### Install Dependencies and Run Dev Server

Source: https://github.com/ecmwf/tensogram/blob/main/tensoscope/README.md

Install project dependencies and start the development server for Tensoscope. Access the application at http://localhost:5173.

```bash
cd tensoscope
npm install
npm run dev
```

--------------------------------

### Python Bindings Setup and Testing

Source: https://github.com/ecmwf/tensogram/blob/main/CONTRIBUTING.md

Steps to set up a Python virtual environment, build and install the Rust extension, and run core Python tests. Includes optional steps for xarray and zarr backends.

```bash
# First time: create a virtual environment
uv venv .venv
source .venv/bin/activate
uv pip install maturin numpy pytest ruff

# Build and install the Rust extension into the active venv
cd python/bindings && maturin develop && cd ../..

# Run core Python tests
python -m pytest python/tests/ -v

# Optional: install and test xarray/zarr backends
uv pip install -e "python/tensogram-xarray/"[dask]
python -m pytest python/tensogram-xarray/tests/ -v
uv pip install -e python/tensogram-zarr/
python -m pytest python/tensogram-zarr/tests/ -v
```

--------------------------------

### TypeScript Wrapper Setup and Testing

Source: https://github.com/ecmwf/tensogram/blob/main/CONTRIBUTING.md

Commands for setting up the TypeScript environment, building the WASM glue and TypeScript layer, and running tests. Includes an example of an end-to-end test.

```bash
# One-time setup
cargo install wasm-pack        # if not already installed

# Build + test
make ts-build                  # wasm-pack build + tsc
make ts-test                   # vitest
make ts-typecheck              # strict tsc --noEmit across src + tests

# Run an example end-to-end
cd examples/typescript
npm install
npx tsx 01_encode_decode.ts
```

--------------------------------

### Python Setup and Development Commands

Source: https://github.com/ecmwf/tensogram/blob/main/AGENTS.md

Commands for setting up a Python virtual environment, installing dependencies, building Python bindings, and running linters and tests. Activate the virtual environment before running these commands.

```bash
uv venv .venv && source .venv/bin/activate && uv pip install maturin numpy pytest ruff
```

```bash
source .venv/bin/activate && cd python/bindings && maturin develop
```

```bash
ruff check --config python/bindings/pyproject.toml python/tests/
```

```bash
ruff format --config python/bindings/pyproject.toml python/tests/
```

```bash
source .venv/bin/activate && python -m pytest python/tests/ -v
```

```bash
source .venv/bin/activate && uv pip install -e "python/tensogram-xarray/[dask]" && python -m pytest python/tensogram-xarray/tests/ -v
```

```bash
source .venv/bin/activate && uv pip install -e python/tensogram-zarr/ && python -m pytest python/tensogram-zarr/tests/ -v
```

--------------------------------

### Python Setup and Development Environment

Source: https://github.com/ecmwf/tensogram/blob/main/CLAUDE.md

Commands for setting up the Python virtual environment and installing development dependencies using uv. Activate the environment before running subsequent Python commands.

```bash
uv venv .venv && source .venv/bin/activate && uv pip install maturin numpy pytest ruff
```

```bash
source .venv/bin/activate && cd python/bindings && maturin develop
```

--------------------------------

### Run a TypeScript Example

Source: https://github.com/ecmwf/tensogram/blob/main/AGENTS.md

Command to run a specific TypeScript example. This involves installing its dependencies and executing it using tsx.

```bash
cd examples/typescript && npm install && npx tsx 01_encode_decode.ts
```

--------------------------------

### Build and Serve Documentation Locally

Source: https://github.com/ecmwf/tensogram/blob/main/README.md

Installs necessary tools and serves the documentation locally. Ensure you have Rust and Cargo installed.

```bash
cargo install mdbook mdbook-mermaid mdbook-tabs
mdbook serve docs/
```

--------------------------------

### Setup Python Bindings with Maturin

Source: https://github.com/ecmwf/tensogram/blob/main/README.md

Set up the Python bindings using uv, pip, and maturin. This involves creating a virtual environment, installing dependencies, and developing the bindings.

```bash
uv venv .venv && source .venv/bin/activate
```

```bash
uv pip install maturin numpy
```

```bash
cd python/bindings && maturin develop
```

```bash
python -m pytest python/tests/ -v              # ~400 tests
```

--------------------------------

### TensogramFile Backend Initialization Example

Source: https://github.com/ecmwf/tensogram/blob/main/plans/DONE.md

Examples of initializing `TensogramFile` with different backends: `InMemoryBackend`, `LocalFileBackend`, and `LazyHttpBackend`.

```typescript
import { TensogramFile, InMemoryBackend, LocalFileBackend, LazyHttpBackend } from "typescript/src/file";

// In-memory
const memoryFile = new TensogramFile(new InMemoryBackend(new Uint8Array([1, 2, 3])));

// Local file
const localFile = new TensogramFile(new LocalFileBackend("/path/to/your/file.tgm"));

// Lazy HTTP
const httpFile = new TensogramFile(new LazyHttpBackend("http://example.com/data.tgm"));
```

--------------------------------

### Installation

Source: https://github.com/ecmwf/tensogram/blob/main/examples/python/README.md

Instructions for installing the Tensogram library and its optional dependencies for xarray, dask, and Zarr.

```APIDOC
## Installation

```bash
uv venv .venv && source .venv/bin/activate   # if not already in a virtualenv
uv pip install tensogram          # once published to PyPI
# or, build from source:
uv pip install maturin numpy      # install build dependencies
(cd python/bindings && maturin develop)
```

For the xarray and dask examples (08, 09), also install:

```bash
uv pip install "tensogram-xarray[dask]"   # includes xarray + dask[array]
# or from source:
uv pip install -e "python/tensogram-xarray/[dask]"
```

For the Zarr example, install:

```bash
uv pip install tensogram-zarr
# or from source:
uv pip install -e python/tensogram-zarr/
```
```

--------------------------------

### Install tensogram-zarr

Source: https://github.com/ecmwf/tensogram/blob/main/docs/src/guide/zarr-backend.md

Install the tensogram-zarr package using uv. Ensure you are in a virtual environment.

```bash
uv venv .venv && source .venv/bin/activate   # if not already in a virtualenv
uv pip install tensogram-zarr
```

--------------------------------

### Install tensogram-cli with GRIB/NetCDF features

Source: https://github.com/ecmwf/tensogram/blob/main/rust/tensogram-cli/README.md

Install the tensogram-cli with GRIB and NetCDF conversion capabilities. Ensure ecCodes and libnetcdf are installed at the OS level.

```bash
cargo install tensogram-cli --features grib,netcdf
```

--------------------------------

### Install SZ3

Source: https://github.com/ecmwf/tensogram/blob/main/rust/tensogram-sz3-sys/SZ3/README.md

Standard build and installation process for SZ3 using CMake. Ensure to set the installation directory.

```bash
mkdir build && cd build
cmake -DCMAKE_INSTALL_PREFIX:PATH=[INSTALL_DIR] ..
make
make install
```

--------------------------------

### Install Tensogram CLI

Source: https://github.com/ecmwf/tensogram/blob/main/docs/src/guide/quickstart.md

Install the Tensogram command-line interface tool using cargo install.

```bash
cargo install tensogram-cli
```

--------------------------------

### Install tensogram-anemoi Package

Source: https://github.com/ecmwf/tensogram/blob/main/docs/src/guide/anemoi-integration.md

Install the package using pip. For development, install from source.

```bash
pip install tensogram-anemoi
```

```bash
pip install -e python/tensogram-anemoi/
```

--------------------------------

### Run a TypeScript Example

Source: https://github.com/ecmwf/tensogram/blob/main/examples/typescript/README.md

Execute a TypeScript example using npx and tsx. This allows running .ts files directly.

```bash
# From examples/typescript/
npx tsx 01_encode_decode.ts
```

--------------------------------

### Install Tensogram

Source: https://github.com/ecmwf/tensogram/blob/main/docs/src/guide/python-api.md

Install Tensogram using pip. Choose between installing from PyPI (once published) or from source using maturin.

```bash
pip install tensogram
```

```bash
pip install maturin numpy
cd python/bindings && maturin develop
```

--------------------------------

### Installation

Source: https://context7.com/ecmwf/tensogram/llms.txt

Instructions for installing Tensogram via cargo for Rust, pip for Python, and cargo for the CLI.

```APIDOC
## Installation

### Rust

```bash
car go add tensogram

# With optional features
car go add tensogram --features mmap,async,remote
```

### Python

```bash
pip install tensogram

# With xarray and Zarr backends
pip install tensogram[all]
```

### CLI

```bash
car go install tensogram-cli

# With GRIB/NetCDF importers
car go install tensogram-cli --features grib,netcdf
```
```

--------------------------------

### Install Tensogram with Pip (Python)

Source: https://context7.com/ecmwf/tensogram/llms.txt

Install the Tensogram library using pip. The '[all]' option installs with xarray and Zarr backends.

```bash
pip install tensogram

# With xarray and Zarr backends
pip install tensogram[all]
```

--------------------------------

### File API Example (06_file_api.ts)

Source: https://github.com/ecmwf/tensogram/blob/main/plans/DONE.md

An updated example script demonstrating the `TensogramFile` API, including the async `rawMessage` signature.

```typescript
import { TensogramFile, LocalFileBackend } from "../../src/file";

async function handleFile() {
    const file = new TensogramFile(new LocalFileBackend("test.tgm"));
    const message = await file.rawMessage();
    console.log("Raw message:", message);
}

handleFile();
```

--------------------------------

### Install tensogram-cli with GRIB feature

Source: https://github.com/ecmwf/tensogram/blob/main/rust/tensogram-grib/README.md

Install the tensogram command-line interface with the GRIB feature enabled to use the convert-grib command.

```bash
cargo install tensogram-cli --features grib
```

--------------------------------

### Rewrite Python Examples (Python)

Source: https://github.com/ecmwf/tensogram/blob/main/CHANGELOG.md

Python examples 01-03, 05-06 have been rewritten to use the real API.

```python
Python examples 01-03, 05-06
```

--------------------------------

### Example Scripts

Source: https://github.com/ecmwf/tensogram/blob/main/examples/python/README.md

List of example Python scripts demonstrating various features of the Tensogram library, from basic usage to advanced integrations.

```APIDOC
## Example Scripts

| File | Topic |
|------|-------|
| `01_encode_decode.py` | Basic encode/decode round-trip |
| `02_mars_metadata.py` | Per-object metadata using the ECMWF MARS vocabulary (example) |
| `02b_generic_metadata.py` | Per-object metadata using a generic application namespace |
| `03_simple_packing.py` | Simple-packing encoding for integer quantization |
| `04_multi_object.py` | Multi-object messages, `decode_object`, `decode_range` |
| `05_file_api.py` | `TensogramFile` for multi-message `.tgm` files |
| `06_hash_and_errors.py` | Hash verification and error handling |
| `07_iterators.py` | File iteration, indexing, slicing, `iter_messages` |
| `08_xarray_integration.py` | Opening `.tgm` files as xarray Datasets |
| `08_zarr_backend.py` | Reading and writing `.tgm` files through Zarr v3 |
| `09_dask_distributed.py` | Dask distributed computing over 4-D tensors |
| `11_encode_pre_encoded.py` | Pre-encoded data API for already-framed payloads |
| `12_convert_netcdf.py` | Convert NetCDF → Tensogram via the Python API (`tensogram.convert_netcdf`) |
| `13_validate.py` | Message and file validation at different levels |
| `14_remote_access.py` | Remote file access over HTTP with `open_remote` and file-level decode APIs |
| `15_async_operations.py` | Async open, decode, and `asyncio.gather` with `AsyncTensogramFile` |
| `17_convert_grib.py` | Convert GRIB → Tensogram via `tensogram.convert_grib` (file) and `tensogram.convert_grib_buffer` (in-memory) |

For **narrative walk-throughs** with live plots and prose explanations, see the companion notebooks under `../jupyter/`.
```

--------------------------------

### Simple Packing Compute Params Example

Source: https://github.com/ecmwf/tensogram/blob/main/plans/DONE.md

This example illustrates how to use `simple_packing_compute_params` from the WASM module to calculate parameters for simple packing.

```rust
use tensogram_wasm::extras::simple_packing_compute_params;

// Assuming values, bits, and dec_scale are defined appropriately
let params = simple_packing_compute_params(values, bits, dec_scale);
// Use the computed params
```

--------------------------------

### Install Tensogram CLI with Cargo

Source: https://context7.com/ecmwf/tensogram/llms.txt

Install the Tensogram command-line interface using Cargo. Features for GRIB/NetCDF importers can be enabled.

```bash
cargo install tensogram-cli

# With GRIB/NetCDF importers
cargo install tensogram-cli --features grib,netcdf
```

--------------------------------

### Install Tensogram CLI

Source: https://github.com/ecmwf/tensogram/blob/main/README.md

Install the Tensogram command-line interface using cargo. For GRIB/NetCDF importers, include the corresponding features.

```bash
cargo install tensogram-cli
```

```bash
cargo install tensogram-cli --features grib,netcdf
```

--------------------------------

### Remote Access - Polish and Examples

Source: https://github.com/ecmwf/tensogram/blob/main/plans/TODO.md

Includes polish for remote access, such as examples, CI integration, and optimized zarr lazy reads.

```APIDOC
## Remote Access - Polish (Examples, CI, zarr Lazy Reads)

### Description
This update focuses on improving the usability and robustness of remote access through updated examples, CI integration, and optimized lazy reading for zarr datasets.

### Examples
- **Python Example (`14_remote_access.py`)**: A self-contained example featuring an HTTP server, `open_remote()`, and file-level decode APIs.
- **Rust Example (`14_remote_access.rs`)**: Demonstrates remote access using a `TcpListener`-based HTTP server, `open_source()`, and decode APIs.

### CI Integration
- Added `pytest python/tests/test_remote.py` to the Python CI job.

### zarr Lazy Reads
- **Remote Files**: Utilize `file_decode_descriptors()` at scan time for metadata-only reads. `file_decode_object()` is called per chunk on demand.
- **Local Files**: Remain unchanged (eager decode).

### Testing
- 9 new zarr remote tests covering lazy open, on-demand decode, cleanup, cached access, existence checks, list contents, and error handling.
```

--------------------------------

### Build and Run Tensoscope Dev Server

Source: https://github.com/ecmwf/tensogram/blob/main/docs/src/guide/tensoscope.md

Build the WebAssembly package and start the development server. Open http://localhost:5173 in your browser and drag-and-drop a .tgm file or paste a URL.

```bash
cd typescript && make ts-build
cd tensoscope && npm install && npm run dev
```

--------------------------------

### Install Tensogram Zarr Backend

Source: https://github.com/ecmwf/tensogram/blob/main/python/tensogram-zarr/README.md

Install the tensogram-zarr package using pip. This will automatically include the tensogram native package and zarr>=3.0.

```bash
pip install tensogram-zarr
```

--------------------------------

### Compute Hash TypeScript Example

Source: https://github.com/ecmwf/tensogram/blob/main/plans/DONE.md

Example of using the `computeHash` function in TypeScript to get the hex digest of a byte array.

```typescript
import { computeHash } from "typescript/src/hash";

const dataBytes = new Uint8Array([10, 20, 30]);
const algorithm = "sha1";

computeHash(dataBytes, algorithm).then(hash => {
    console.log(`Computed hash: ${hash}`);
}).catch(error => {
    console.error(`Error computing hash: ${error.message}`);
});
```

--------------------------------

### Simple Packing Encoding Setup

Source: https://github.com/ecmwf/tensogram/blob/main/docs/src/guide/encoding.md

Demonstrates computing quantization parameters for simple packing and constructing a DataObjectDescriptor with these parameters. Assumes `source_data` is available.

```rust
use tensogram_encodings::simple_packing;
use ciborium::Value;

// Your original values as f64 (simple_packing always works on f64).
// source_data might be a temperature grid, pressure field, intensity
// image, or any other bounded-range scalar field.
let values: Vec<f64> = source_data.iter().map(|&x| x as f64).collect();

// Compute quantization parameters for 16 bits per value
let params = simple_packing::compute_params(&values, 16, 0)?;

// Put the parameters into the descriptor
let mut packing_params = BTreeMap::new();
packing_params.insert("reference_value".into(),
    Value::Float(params.reference_value));
packing_params.insert("binary_scale_factor".into(),
    Value::Integer((params.binary_scale_factor as i64).into()));
packing_params.insert("decimal_scale_factor".into(),
    Value::Integer((params.decimal_scale_factor as i64).into()));
packing_params.insert("bits_per_value".into(),
    Value::Integer((params.bits_per_value as i64).into()));

let desc = DataObjectDescriptor {
    obj_type: "ntensor".to_string(),
    ndim: 2,
    shape: vec![100, 200],
    strides: vec![200, 1],
    dtype: Dtype::Float64,
    byte_order: ByteOrder::Big,
    encoding: "simple_packing".to_string(),
    filter: "none".to_string(),
    compression: "none".to_string(),
    masks: None,
    params: packing_params,
};

```

--------------------------------

### TypeScript Testing and Example Execution

Source: https://github.com/ecmwf/tensogram/blob/main/CLAUDE.md

Commands for running TypeScript tests using vitest and executing a TypeScript example. Ensure Node.js version 20 or higher is installed.

```bash
make ts-test
```

```bash
cd examples/typescript && npm install && npx tsx 01_encode_decode.ts
```

--------------------------------

### Scan Message Buffer

Source: https://github.com/ecmwf/tensogram/blob/main/examples/python/README.md

Scan a message buffer to get the start and end byte indices of all messages within it.

```python
scan(buf) -> list[tuple[int, int]]
```

--------------------------------

### Example IndexFrame Structure

Source: https://github.com/ecmwf/tensogram/blob/main/docs/src/format/cbor-metadata.md

Provides an example of an IndexFrame, which contains 'offsets' and 'lengths' arrays. These arrays allow for O(1) random access to data object frames by specifying their byte offset from the message start and their byte length.

```json
{
  "offsets": [256, 1048832, 2097408],
  "lengths": [1048576, 1048576, 524288]
}
```

--------------------------------

### TypeScript Wrapper API - Complex Array Accessors

Source: https://github.com/ecmwf/tensogram/blob/main/plans/TODO.md

Example demonstrating accessors for ComplexArray, including real, imaginary, and get methods.

```typescript
// .real(i), .imag(i), .get(i), iteration
```

--------------------------------

### Full Integration Example: Encode and Decode

Source: https://github.com/ecmwf/tensogram/blob/main/docs/src/encodings/simple-packing.md

Demonstrates encoding 1000 temperature values using simple packing and then decoding them back, verifying precision. Requires `tensogram`, `tensogram_encodings`, and `ciborium` crates.

```rust
use tensogram::{encode, decode, GlobalMetadata, DataObjectDescriptor,
                     ByteOrder, Dtype, EncodeOptions, DecodeOptions};
use tensogram_encodings::simple_packing;
use ciborium::Value;
use std::collections::BTreeMap;

// Source data: 1000 temperature values
let values: Vec<f64> = (0..1000).map(|i| 273.0 + i as f64 * 0.05).collect();
let raw: Vec<u8> = values.iter().flat_map(|v| v.to_ne_bytes()).collect();

// Compute packing parameters
let params = simple_packing::compute_params(&values, 16, 0).unwrap();

// Build descriptor with packing params
let mut p = BTreeMap::new();
p.insert("reference_value".into(), Value::Float(params.reference_value));
p.insert("binary_scale_factor".into(),
    Value::Integer((params.binary_scale_factor as i64).into()));
p.insert("decimal_scale_factor".into(),
    Value::Integer((params.decimal_scale_factor as i64).into()));
p.insert("bits_per_value".into(),
    Value::Integer((params.bits_per_value as i64).into()));

let desc = DataObjectDescriptor {
    obj_type: "ntensor".into(),
    ndim: 1,
    shape: vec![1000],
    strides: vec![1],
    dtype: Dtype::Float64,
    byte_order: ByteOrder::Big,
    encoding: "simple_packing".into(),
    filter: "none".into(),
    compression: "none".into(),
    masks: None,
    params: p,
};

let global = GlobalMetadata::default();

let msg = encode(&global, &[(&desc, &raw)], &EncodeOptions::default()).unwrap();
println!("Packed size: {} bytes (was {} bytes)", msg.len(), raw.len());

let (_, objects) = decode(&msg, &DecodeOptions::default()).unwrap();
let decoded: Vec<f64> = objects[0].1.chunks_exact(8)
    .map(|c| f64::from_ne_bytes(c.try_into().unwrap()))
    .collect();

// Check precision
for (orig, dec) in values.iter().zip(decoded.iter()) {
    assert!((orig - dec).abs() < 0.001);
}
```

--------------------------------

### TypeScript Wrapper API - Typed Array for Dtype

Source: https://github.com/ecmwf/tensogram/blob/main/plans/TODO.md

Example demonstrating how to get a typed array for a given dtype using typedArrayFor().

```typescript
const typedArray = typedArrayFor(dtype);
```

--------------------------------

### Setup tensogram environment

Source: https://github.com/ecmwf/tensogram/blob/main/examples/jupyter/01_quickstart_and_mars.ipynb

Imports necessary libraries and sets matplotlib backend for headless operation. Prints the tensogram version.

```python
import matplotlib

matplotlib.use("Agg")  # headless: same cell runs in CI and on your laptop

import matplotlib.pyplot as plt
import numpy as np

import tensogram

print(f"tensogram version: {tensogram.__version__ if hasattr(tensogram, '__version__') else '?'}")
```

--------------------------------

### TypeScript Wrapper API - Raw Message (Async)

Source: https://github.com/ecmwf/tensogram/blob/main/plans/TODO.md

Example demonstrating how to get a raw message asynchronously using TensogramFile#rawMessage.

```typescript
const message = await tensogramFile.rawMessage();
```

--------------------------------

### Encode and Decode with Tensogram C++ API

Source: https://github.com/ecmwf/tensogram/blob/main/docs/src/guide/cpp-api.md

Quick start example demonstrating how to encode metadata and data into a Tensogram message and then decode it. Requires the tensogram.hpp header.

```cpp
#include <tensogram.hpp>

// Encode
std::string meta_json = R"({\"version\": 3, \"descriptors\": [...]})";
std::vector<float> data(100 * 200, 0.0f);
auto encoded = tensogram::encode(
    meta_json,
    {{reinterpret_cast<const uint8_t*>(data.data()), data.size() * sizeof(float)}}}
);

// Decode
auto msg = tensogram::decode(encoded.data(), encoded.size());
auto obj = msg.object(0);
const float* values = obj.data_as<float>();
```

--------------------------------

### C/C++ Bindings Build Output

Source: https://github.com/ecmwf/tensogram/blob/main/CONTRIBUTING.md

Demonstrates the build process for the FFI crate and the expected output files, including the header file, static library, and dynamic libraries.

```bash
cargo build -p tensogram-ffi
# Output:
#   cpp/include/tensogram.h
#   target/debug/libtensogram_ffi.a
#   target/debug/libtensogram_ffi.{so,dylib}
```

--------------------------------

### Quick Start: Encode and Decode Tensogram Message

Source: https://github.com/ecmwf/tensogram/blob/main/typescript/README.md

Example demonstrating how to initialize the Tensogram library, encode a message with tensor data, and then decode it. Ensure `init()` is awaited before using other functions.

```typescript
import { init, encode, decode } from '@ecmwf.int/tensogram';

await init();

const temps = new Float32Array(100 * 200);
for (let i = 0; i < temps.length; i++) temps[i] = 273.15 + i / 100;

const msg = encode(
  { version: 3 },
  [{
    descriptor: {
      type: 'ntensor', ndim: 2,
      shape: [100, 200], strides: [200, 1],
      dtype: 'float32', byte_order: 'little',
      encoding: 'none', filter: 'none', compression: 'none',
    },
    data: temps,
  }],
);

const { metadata, objects } = decode(msg);
console.log(objects[0].data());  // Float32Array(20000)
```

--------------------------------

### Example: Generic Metadata in C++

Source: https://github.com/ecmwf/tensogram/blob/main/CHANGELOG.md

Shows how to utilize the per-object metadata mechanism with a generic application namespace in C++.

```cpp
examples/cpp/02b_generic_metadata.cpp
```

--------------------------------

### Streaming Consumer Example

Source: https://github.com/ecmwf/tensogram/blob/main/plans/TODO.md

Demonstrates a mock HTTP server, chunked download, progressive scan and decode, and xarray Dataset assembly for streaming data consumption.

```python
examples/python/09_streaming_consumer.py
```

--------------------------------

### Install pysz from PyPI

Source: https://github.com/ecmwf/tensogram/blob/main/rust/tensogram-sz3-sys/SZ3/tools/pysz/README.md

Install pysz using pip. Pre-built binary wheels are available for most platforms and Python versions, requiring no build tools.

```bash
pip install pysz
```

--------------------------------

### Docker Image Build and Run

Source: https://github.com/ecmwf/tensogram/blob/main/tensoscope/README.md

Build the Docker image for Tensoscope and run the container. The application will be served at http://localhost:8000. Optionally set BASE_PATH for subpath deployment.

```bash
cd tensoscope
make build   # builds podman/docker image
make run     # serves at http://localhost:8000
```

--------------------------------

### Build Documentation

Source: https://github.com/ecmwf/tensogram/blob/main/CONTRIBUTING.md

Commands to build the project's documentation using mdbook and generate Rust documentation for the workspace.

```bash
cd docs && mdbook build
```

```bash
cargo doc --workspace --no-deps
```

--------------------------------

### Install tensogram-xarray

Source: https://github.com/ecmwf/tensogram/blob/main/python/tensogram-xarray/README.md

Install the tensogram-xarray package. For Dask-backed lazy reads, install with the "dask" extra.

```bash
pip install tensogram-xarray
```

```bash
pip install "tensogram-xarray[dask]"
```

--------------------------------

### Example: Generic Metadata in Python

Source: https://github.com/ecmwf/tensogram/blob/main/CHANGELOG.md

Illustrates the per-object metadata mechanism with a generic application namespace using Python.

```python
examples/python/02b_generic_metadata.py
```

--------------------------------

### Install pysz from Source

Source: https://github.com/ecmwf/tensogram/blob/main/rust/tensogram-sz3-sys/SZ3/tools/pysz/README.md

Install pysz from source if pre-built wheels are not available. Requires CMake, a C++ compiler, Git, and Python development headers.

```bash
git clone https://github.com/szcompressor/SZ3.git
cd SZ3/tools/pysz
pip install -e .
```

--------------------------------

### Global Metadata Example (Materials Simulation)

Source: https://github.com/ecmwf/tensogram/blob/main/docs/src/concepts/metadata.md

Presents global metadata structure for a materials simulation pipeline, using a custom namespace. Includes version and base metadata with material composition, lattice, and temperature.

```json
{
  "version": 3,
  "base": [{
    "material": { "composition": "Fe3O4", "lattice": "cubic", "T_K": 300.0 }
  }]
}
```

--------------------------------

### Install Tensogram

Source: https://github.com/ecmwf/tensogram/blob/main/examples/python/README.md

Install Tensogram using pip. For xarray and dask integration, install the respective extras. Building from source is also supported.

```bash
uv venv .venv && source .venv/bin/activate   # if not already in a virtualenv
uv pip install tensogram          # once published to PyPI
# or, build from source:
uv pip install maturin numpy      # install build dependencies
(cd python/bindings && maturin develop)
```

```bash
uv pip install "tensogram-xarray[dask]"   # includes xarray + dask[array]
# or from source:
uv pip install -e "python/tensogram-xarray/[dask]"
```

```bash
uv pip install tensogram-zarr
# or from source:
uv pip install -e python/tensogram-zarr/
```

--------------------------------

### Install SZ3c Target and Headers

Source: https://github.com/ecmwf/tensogram/blob/main/rust/tensogram-sz3-sys/SZ3/tools/sz3c/CMakeLists.txt

Installs the SZ3c target (libraries and executables) and its header files to the appropriate locations based on CMake installation variables.

```cmake
install(TARGETS SZ3c EXPORT SZ3c
        ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
        LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
        RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
        )
install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/include/ DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/SZ3c)
```

--------------------------------

### Production Build

Source: https://github.com/ecmwf/tensogram/blob/main/tensoscope/README.md

Create a production build of the Tensoscope application. Output files are placed in the tensoscope/dist/ directory.

```bash
cd tensoscope
npm run build
```

--------------------------------

### Install Tensogram Xarray Backend

Source: https://github.com/ecmwf/tensogram/blob/main/docs/src/guide/xarray-integration.md

Install the tensogram-xarray package using uv pip. This command installs the core package and its dependencies, including tensogram and xarray. The backend is automatically registered.

```bash
uv venv .venv && source .venv/bin/activate   # if not already in a virtualenv
uv pip install tensogram-xarray
```

--------------------------------

### Simple Packing Quantization Example

Source: https://github.com/ecmwf/tensogram/blob/main/rust/tensogram-encodings/README.md

Demonstrates the usage of simple_packing for quantization and encoding of floating-point values. Requires the `simple_packing` feature to be enabled.

```rust
use tensogram_encodings::simple_packing;

let values: Vec<f64> = (0..1000).map(|i| 273.15 + i as f64 / 100.0).collect();
let params = simple_packing::compute_params(&values, 16, 0)?;
let packed = simple_packing::encode(&values, &params)?;
let round_trip = simple_packing::decode(&packed, values.len(), &params)?;
# Ok::<(), tensogram_encodings::simple_packing::PackingError>(())
```

--------------------------------

### Streaming Encoder Example (12_streaming_encoder.ts)

Source: https://github.com/ecmwf/tensogram/blob/main/plans/DONE.md

An example script demonstrating the `StreamingEncoder` class.

```typescript
import { StreamingEncoder } from "../../src/streamingEncoder";

const encoder = new StreamingEncoder();
encoder.writeObject({ key: "value" });
encoder.finish();
console.log(`Objects: ${encoder.objectCount}, Bytes: ${encoder.bytesWritten}`);
```

--------------------------------

### Example: Generic Metadata in Rust

Source: https://github.com/ecmwf/tensogram/blob/main/CHANGELOG.md

Demonstrates the per-object metadata mechanism with a generic application namespace in Rust.

```rust
examples/rust/02b_generic_metadata.rs
```

--------------------------------

### Encode Pre-Encoded Example (11_encode_pre_encoded.ts)

Source: https://github.com/ecmwf/tensogram/blob/main/plans/DONE.md

An example script demonstrating the `encodePreEncoded` function.

```typescript
import { encodePreEncoded } from "../../src/encodePreEncoded";

const meta = { /* ... */ };
const objects = [/* ... */];

encodePreEncoded(meta, objects).then(encoded => console.log(encoded)).catch(err => console.error(err));
```

--------------------------------

### Run tensogram-grib tests

Source: https://github.com/ecmwf/tensogram/blob/main/plans/ARCHITECTURE.md

Navigate to the 'tensogram-grib' directory and run its tests. This requires the 'libeccodes' library to be installed.

```bash
cd rust/tensogram-grib    && cargo test
```

--------------------------------

### Install Tensogram with GRIB/NetCDF support using uv

Source: https://github.com/ecmwf/tensogram/blob/main/examples/jupyter/README.md

Install Tensogram and its dependencies using uv, including GRIB and NetCDF support. Requires OS-level C libraries. This command builds the Python bindings.

```bash
uv venv .venv --python 3.13
source .venv/bin/activate

uv pip install maturin
cd python/bindings
maturin develop --features grib,netcdf
cd ../..

uv pip install -e examples/jupyter

jupyter lab examples/jupyter/
```

--------------------------------

### Validate Example (08_validate.ts)

Source: https://github.com/ecmwf/tensogram/blob/main/plans/DONE.md

An example script demonstrating the `validate` and `validateBuffer` functions.

```typescript
import { validate, validateBuffer } from "../../src/validate";

const buffer = new Uint8Array([/* ... */]);

// Validate single message
validate(buffer).then(result => console.log(result)).catch(err => console.error(err));

// Validate buffer with gap detection
validateBuffer(buffer, { detectGaps: true }).then(result => console.log(result)).catch(err => console.error(err));
```

--------------------------------

### Decode Range Example (04_decode_range.ts)

Source: https://github.com/ecmwf/tensogram/blob/main/plans/DONE.md

An example script demonstrating the `decodeRange` functionality.

```typescript
import { decodeRange } from "../../src/range";

const buffer = new Uint8Array([0, 1, 2, 3, 4, 5]);
const objIndex = 0;
const ranges = [[0, 1], [2, 3]];

const parts = decodeRange(buffer, objIndex, ranges);
console.log(parts);
```

--------------------------------

### Full Integration Example

Source: https://github.com/ecmwf/tensogram/blob/main/docs/src/encodings/simple-packing.md

Demonstrates a complete workflow of encoding and decoding data using Tensogram, including computing packing parameters, building a descriptor, and verifying the decoded data precision.

```APIDOC
## Full Integration Example

### Description
This example shows how to encode a vector of f64 values using `simple_packing`, then decode the resulting message and verify the precision of the decoded data.

### Method
Not applicable (this is a usage example, not a specific API endpoint).

### Endpoint
Not applicable.

### Parameters
None (this is a code example).

### Request Example
```rust
use tensogram::{encode, decode, GlobalMetadata, DataObjectDescriptor,
                     ByteOrder, Dtype, EncodeOptions, DecodeOptions};
use tensogram_encodings::simple_packing;
use ciborium::Value;
use std::collections::BTreeMap;

// Source data: 1000 temperature values
let values: Vec<f64> = (0..1000).map(|i| 273.0 + i as f64 * 0.05).collect();
let raw: Vec<u8> = values.iter().flat_map(|v| v.to_ne_bytes()).collect();

// Compute packing parameters
let params = simple_packing::compute_params(&values, 16, 0).unwrap();

// Build descriptor with packing params
let mut p = BTreeMap::new();
p.insert("reference_value".into(), Value::Float(params.reference_value));
p.insert("binary_scale_factor".into(),
    Value::Integer((params.binary_scale_factor as i64).into()));
p.insert("decimal_scale_factor".into(),
    Value::Integer((params.decimal_scale_factor as i64).into()));
p.insert("bits_per_value".into(),
    Value::Integer((params.bits_per_value as i64).into()));

let desc = DataObjectDescriptor {
    obj_type: "ntensor".into(),
    ndim: 1,
    shape: vec![1000],
    strides: vec![1],
    dtype: Dtype::Float64,
    byte_order: ByteOrder::Big,
    encoding: "simple_packing".into(),
    filter: "none".into(),
    compression: "none".into(),
    masks: None,
    params: p,
};

let global = GlobalMetadata::default();

let msg = encode(&global, &[(&desc, &raw)], &EncodeOptions::default()).unwrap();
println!("Packed size: {} bytes (was {} bytes)", msg.len(), raw.len());

let (_, objects) = decode(&msg, &DecodeOptions::default()).unwrap();
let decoded: Vec<f64> = objects[0].1.chunks_exact(8)
    .map(|c| f64::from_ne_bytes(c.try_into().unwrap()))
    .collect();

// Check precision
for (orig, dec) in values.iter().zip(decoded.iter()) {
    assert!((orig - dec).abs() < 0.001);
}
```

### Response
#### Success Response (200)
This example does not return a direct HTTP response. It demonstrates successful execution of encoding and decoding functions within a Rust program.

#### Response Example
None
```

--------------------------------

### Rust Example for Validation

Source: https://github.com/ecmwf/tensogram/blob/main/plans/TODO.md

An example demonstrating the usage of the validation functionality within a Rust binary.

```rust
fn main() {
    // Example usage of tensogram validation
    println!("Running validation example...");
}
```

--------------------------------

### Python Error Handling Example

Source: https://github.com/ecmwf/tensogram/blob/main/docs/src/edge-cases.md

Example code demonstrating how to handle Tensogram errors in Python.

```python
import tensogram

# File not found
try:
    with tensogram.TensogramFile.open("missing.tgm") as f:
        pass
except IOError as e:
    print(f"File error: {e}")
    # → "File error: File not found: missing.tgm"

# Corrupted buffer
try:
    tensogram.decode(b"garbage")
except ValueError as e:
    print(f"Decode error: {e}")
    # → "Decode error: FramingError: buffer too short ..."

# Hash verification failure
try:
    meta, objects = tensogram.decode(buf, verify_hash=True)
except RuntimeError as e:
    print(f"Integrity error: {e}")
    # → "Integrity error: HashMismatch: expected=..., actual=..."

# Missing metadata key
meta, objects = tensogram.decode(buf)
try:
    val = meta["nonexistent"]
except KeyError:
    print("Key not found")

# Index out of range
with tensogram.TensogramFile.open("data.tgm") as f:
    try:
        msg = f[999]
    except IndexError as e:
        print(f"Index error: {e}")
        # → "message index 999 out of range for file with 2 messages"
```

--------------------------------

### Run Tensogram Benchmarks

Source: https://github.com/ecmwf/tensogram/blob/main/docs/src/guide/free-threaded-python.md

Execute the full suite of Tensogram performance benchmarks. Use the --headline flag for a quick comparison or --quick for a CI smoke test.

```bash
python rust/benchmarks/python/bench_threading.py              # full suite
```

```bash
python rust/benchmarks/python/bench_threading.py --headline   # quick comparison
```

```bash
python rust/benchmarks/python/bench_threading.py --quick      # CI smoke test
```