> For the complete documentation index, see [llms.txt](https://docs.algenta.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.algenta.ai/machine-learning/ml-serialization.md).

# Bit-exact weight serialization

Bit-exact float64 weight serialization for saving and restoring trained kernels.

`serialization_io` persists named Float64 arrays as a versioned string — replacing pickle / json / numpy.save weight dumps — with **bit-exact** round-trips. The kernel stays pure (string in, string out); the caller persists the string to a file, KV store, or receipt log. Unlike rounded decimal formatting, `weights_from_string(weights_to_string(...))` reproduces every Float64 bit for bit. Zero Python imports.

## The modules

| Module             | What it does                                                                                                                                                                                        |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `serialization_io` | bit-exact Float64 weight serialization to a versioned string and back — replacing pickle / json / numpy.save weight dumps, with `weights_from_string(weights_to_string(...))` reproducing every bit |

## Functions

| Function                           | What it does                                                                                                                                                                                                  |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `WeightsBundle`                    | Parse result: `ok` flag plus parallel `names` / `arrays` lists. `ok == False` means corrupt/invalid payload — lists stay empty, never partial.                                                                |
| `weights_to_string(names, arrays)` | Serialize named Float64 arrays to the versioned line format below, one `\n`-terminated line per array. Deterministic: identical inputs yield identical strings. Empty string on names/arrays length mismatch. |
| `weights_from_string(s)`           | Strict parse back to a `WeightsBundle`. Any corruption → `ok=False` with empty lists, never a silently wrong value. Blank lines and CRLF endings tolerated.                                                   |
| `string_checksum(s)`               | FNV-1a 64-bit hash of the bytes, xor-folded to 32 bits, returned as an integer-valued Float64 in `[0, 2^32)` — for receipts/audit logs.                                                                       |

## Line format and token grammar

```
v1|<name>|<len>|<v0>,<v1>,...,<v(len-1)>
```

Value tokens: `0` / `-0` (signed zeros preserved), `inf` / `-inf` / `nan`, plain decimal digits for integers with magnitude below 2^62, and otherwise `<m>p<e>` — value = ±m·2^e with m an odd positive integer < 2^53 (C99 hex-float `p` notation). Only exact power-of-two scalings and integer digit arithmetic are used, so subnormals, signed zeros, and max/min magnitudes all survive. Test-verified tokens include `0.5 → 1p-1`, `0.1 → 3602879701896397p-55`, max finite `→ 9007199254740991p971`, min subnormal 2^-1074 `→ 1p-1074`, and `2^1023 → 1p1023`; the plain-integer boundary is exact at 2^62 (`2^61` renders as digits, `2^62 → 1p62`).

## Guarantees

* **Strict rejection**: unknown version tags, declared-length mismatches, malformed tokens, and out-of-domain tokens (`1p1024`, `1p-1075`, significand ≥ 2^53) all yield `ok=False`. One corrupt line poisons the whole bundle — no partial loads.
* **Names**: `|`, `\n`, `\r` bytes are replaced with `_`; ASCII names round-trip verbatim.
* **Performance**: single pass, \~70 simple ops per value; 10k typical weights serialize or parse well under 1 ms (worst-case subnormal-heavy payloads roughly double that, still sub-ms).

## Verification

The test suite round-trips a 200-value seeded stress set spanning the full significand/exponent domain (all 200 bit-exact), checks hand-derived IEEE-754 decompositions for every token form, and validates `string_checksum` against the published FNV-1a 64 vectors (Noll): `"" → 0xCBF29CE484222325`, `"a" → 0xAF63DC4C8601EC8C`, `"foobar" → 0x85944171F73967E8` (folded). The checksum is deterministic and tamper-sensitive: appending one byte changes it.

**Next:** promote what you trained with [statistical model comparison](/machine-learning/ml-model-comparison.md), or browse the [engine catalog](/engine-runtime/catalog.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.algenta.ai/machine-learning/ml-serialization.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.