pyferrite 0.0.2

Pure-Rust reader/writer for Python ML artefacts (npy, npz, pickle, pt, joblib, hdf5) with ndarray and polars interop, lazy streaming and user-controlled numeric down-casting.
Documentation
# Модель данных и числовые типы

## `DType`

Каждый читатель отображает собственные теги типов на это одно перечисление, а
каждый писатель — обратно. Благодаря этому объём работы по преобразованию
пропорционален сумме числа форматов и числа типов, а не их произведению.

| Группа | Варианты | Байт |
|---|---|---|
| Логический | `Bool` | 1 |
| Знаковые | `I8` `I16` `I32` `I64` | 1, 2, 4, 8 |
| Беззнаковые | `U8` `U16` `U32` `U64` | 1, 2, 4, 8 |
| 8-битные вещественные | `F8E4M3` `F8E5M2` | 1 |
| Половинная точность | `F16` `BF16` | 2 |
| Одинарная, двойная | `F32` `F64` | 4, 8 |
| Четверная | `F128` | 16 |
| Расширенный x87 | `X87` | 10 (хранится в 12 или 16) |
| Комплексные | `C64` `C128` `C256` | 8, 16, 32 |
| Текст и байты | `Str(n)` `Bytes(n)` | фиксированная ширина |
| Непрозрачный | `Object` | в numpy размер указателя; здесь разбирается рекурсивно |
| Записи | `Struct(Vec<Field>)` | сумма полей |

Предикаты: `size()`, `is_integer()`, `is_float()`, `is_complex()`,
`is_numeric()`.

### Ловушка в именовании, о которой стоит знать

numpy называет типы по числу **байт**, поэтому `f8` — это double. `pyferrite`
называет малые вещественные типы по числу **бит**, поэтому `FloatKind::F8E4M3`
— восьмибитное число. `FloatKind::parse` разбирает оба написания, а строки
дескрипторов numpy в заголовках файлов всегда читаются в смысле numpy.
Двусмысленность существует только в прозе и никогда — в самом формате.

## Вещественные типы, написанные с нуля

Ни одного из них нет в стабильном Rust, поэтому крейт реализует их сам.

**`F16`** — IEEE binary16. Округление к ближайшему чётному, субнормальные
числа, сохранение полезной нагрузки NaN.

**`BF16`** — bfloat16: старшие шестнадцать бит `f32`, сохраняющие полный
диапазон порядка ценой битов мантиссы. Именно поэтому он не переполняется там,
где переполняется `F16`:

```rust
# use pyferrite::prelude::*;
let big = BF16::from_f32(3.0e38);
assert!(big.to_f32().is_finite());          // f16 здесь дал бы inf
```

**`F8E4M3`** — четыре бита порядка, три бита мантиссы, смещение 7, бесконечности
нет, максимум 448. **`F8E5M2`** — пять и два, смещение 15, форма как у IEEE,
максимум 57344. Это два формата, применяемых для квантованного вывода.

**`F128`** — IEEE binary128 с программными сложением, вычитанием, умножением и
делением. Корректное округление, субнормальные числа и все обычные особые
случаи.

```rust
# use pyferrite::prelude::*;
let third = F128::from_f64(1.0) / F128::from_f64(3.0);
assert_eq!((third * F128::from_f64(3.0)).to_f64(), 1.0);
```

**x87, 80 бит** — то, что numpy называет `longdouble` на x86 под Linux.
Декодируется в `F128` и кодируется из него, вместе с явным битом целой части,
который отличает этот формат от всех остальных типов IEEE.

**Комплексные** — `Complex32`, `Complex64` и `Complex128`; последний построен на
`F128` и покрывает numpy-типы `complex64`, `complex128` и `complex256`.

## Приведение типов

`Array::cast(&DType, CastPolicy)` преобразует между любыми двумя типами
элементов. Все преобразования идут через широкий промежуточный скаляр
(`i128`, `u128`, `F128` или пару комплексных), поэтому ни один путь не теряет
точности сверх неизбежного.

| Политика | Поведение при выходе за диапазон |
|---|---|
| `Strict` *(по умолчанию)* | `Err(Error::Cast)` с указанием значения и целевого диапазона |
| `Saturate` | Обрезать по минимуму или максимуму целевого типа |
| `Wrap` | Усечь битовый образ, как приведение в C |

```rust
# use pyferrite::prelude::*;
# use ndarray::{ArrayD, IxDyn};
let a = Array::I64(ArrayD::from_shape_vec(IxDyn(&[2]), vec![-99_999, 99_999]).unwrap());

assert!(a.cast(&DType::I16, CastPolicy::Strict).is_err());

let clamped = a.cast(&DType::I16, CastPolicy::Saturate).unwrap();
assert_eq!(clamped.as_i16().unwrap().as_slice().unwrap(), &[i16::MIN, i16::MAX]);
```

Сужение вещественных типов при `Strict` не приводит к ошибке — округление и
переполнение это разные вещи, — но значение за пределами диапазона целевого
типа станет бесконечностью, а это обычно та ошибка, о которой хочется узнать.
Если предпочтительнее обрезать, используйте `Saturate`.

## Изменяемость `Value`

Любое чтение возвращает данные во владение. Никакого заимствованного
представления отображённого файла, о котором нужно помнить, нет, поэтому для
изменения не требуется ничего, кроме `let mut`:

```rust,no_run
# use pyferrite::prelude::*;
let mut v = read("weights.npy")?;
v.as_array_mut()
    .and_then(|a| a.as_f32_mut())
    .map(|w| w.iter_mut().for_each(|x| *x = x.clamp(-1.0, 1.0)));
# Ok::<(), pyferrite::Error>(())
```

`arrays_mut()` делает то же самое для целого вложенного контейнера за один
проход.

## Таблицы

`Frame` — нейтральный табличный тип, стоящий между pandas, polars и
структурированными массивами numpy. Структурированный массив numpy при чтении
превращается в `Frame`, если только `ReadOptions::keep_record_arrays` не велит
обратное. Каждая `Series` несёт имя, `Array` значений и необязательную битовую
маску валидности для пропусков — единственное, что numpy выразить не умеет.

При включённой возможности `polars-interop` `Frame` преобразуется в
`polars::DataFrame` и обратно. Таблицы pandas приходят в виде своего
сериализованного `BlockManager`; числовые блоки восстанавливаются, а всё
экзотическое сохраняется как `PyObject`, а не угадывается.

### Чтение таблицы pandas

`interop::pandas::to_frame` восстанавливает сериализованный
`pandas.DataFrame`. pandas сохраняет не таблицу, а `BlockManager`: столбцы
сгруппированы по типу в двумерные блоки, каждый из которых помнит, какие
позиции столбцов он занимает. Преобразователь разбирает эти блоки обратно на
столбцы и соединяет их с индексом столбцов.

```rust,no_run
# use pyferrite::prelude::*;
let v = read("frame.pkl")?;
match pyferrite::interop::pandas::to_frame(&v)? {
    Some(f) => println!("{:?}", f.names()),
    None => println!("сохранено как инертный объект: {}", v.type_name()),
}
# Ok::<(), pyferrite::Error>(())
```

Раскладка различается от версии к версии: менеджер может нести содержимое как
аргументы конструктора или как сохранённое состояние, а блоки — приходить
вызовами `_unpickle_block` или простыми кортежами. Принимаются все варианты, а
массивы-расширения вроде `StringArray` разворачиваются до своих значений. Если
раскладка не распознана, функция возвращает `Ok(None)`, и вызывающая сторона
сохраняет инертный `PyObject`, так что ничего не теряется молча.

### Преобразование в polars

При включённой возможности `polars-interop`:

```rust,no_run
# #[cfg(feature = "polars-interop")] {
# use pyferrite::prelude::*;
# let frame = pyferrite::value::Frame::default();
let df = pyferrite::interop::polars::to_polars(&frame)?;
let back = pyferrite::interop::from_polars(&df)?;
# }
# Ok::<(), pyferrite::Error>(())
```

Пропуски передаются в обе стороны: null в polars становится отметкой в битовой
маске валидности `Series`, а числовой буфер под ней остаётся плотным, поэтому
его по-прежнему можно записать прямо в numpy. Типы, для которых у polars нет
места, — `f8`, `f16`, `bf16`, `f128` — расширяются до `f64`; комплексные числа
отвергаются, а не искажаются.