Struct BurnpackStore 

pub struct BurnpackStore { /* private fields */ }

BurnpackStore - A Burn-specific file format store using CBOR for metadata

Implementations

impl BurnpackStore

pub fn default_metadata() -> BTreeMap<String, String>

Get the default metadata that includes Burn framework information.

This includes:

• format: “burnpack”
• producer: “burn”
• version: The version of burn-store crate (from CARGO_PKG_VERSION)

These metadata fields are automatically added to all saved models.

pub fn from_file<P: AsRef<Path>>(path: P) -> Self

Create a new store from a file path

By default, automatically appends .bpk extension if the path doesn’t have one. Use .auto_extension(false) to disable this behavior.

Examples

// Automatically appends .bpk
let store = BurnpackStore::from_file("model");  // creates "model.bpk"

// Already has extension, no append
let store = BurnpackStore::from_file("model.bpk");  // uses "model.bpk"
let store = BurnpackStore::from_file("model.myext");  // uses "model.myext"

// Disable auto-extension
let store = BurnpackStore::from_file("model").auto_extension(false);  // uses "model"

pub fn from_bytes(bytes: Option<Bytes>) -> Self

Create a new store from bytes (for reading) or empty (for writing)

pub fn from_static(data: &'static [u8]) -> Self

Create a new store from static bytes with zero-copy loading enabled.

This is optimized for embedded model weights where the data lives in the binary’s .rodata section. Tensor data is sliced without copying, keeping the static reference alive.

Example

static MODEL_DATA: &[u8] = include_bytes!("model.bpk");
let store = BurnpackStore::from_static(MODEL_DATA);

pub fn metadata(self, key: impl Into<String>, value: impl Into<String>) -> Self

Add metadata key-value pair

pub fn clear_metadata(self) -> Self

Clear all metadata (including defaults)

This removes all metadata including the default format, producer, and version fields. Use with caution as some tools may expect these fields to be present.

pub fn allow_partial(self, allow: bool) -> Self

Allow partial loading (ignore missing tensors)

When set to true, the store will not fail if some tensors are missing during loading. This is useful when loading a subset of a model’s parameters.

Default: false

pub fn validate(self, validate: bool) -> Self

Enable or disable validation during loading

When validation is enabled, the store will check that loaded tensors match the expected shapes and data types. Disabling validation can improve performance but may lead to runtime errors if data is corrupted.

Default: true

pub fn overwrite(self, overwrite: bool) -> Self

Allow overwriting existing files when saving

When set to false, attempting to save to an existing file will result in an error. When set to true, existing files will be overwritten without warning.

Default: false

pub fn zero_copy(self, enable: bool) -> Self

Enable or disable zero-copy tensor loading.

When enabled and the backend supports it (memory-backed with shared bytes), tensor data is sliced from the source without copying. This keeps the source data alive as long as any tensor holds a reference.

Zero-copy is automatically enabled when using from_static. Use this method to enable it for other memory-backed stores created with from_bytes when using Bytes::from_shared().

Default: false (except for from_static which defaults to true)

pub fn auto_extension(self, enable: bool) -> Self

Enable or disable automatic .bpk extension appending

When enabled (default), automatically appends .bpk to the file path if no extension is detected. If an extension is already present, it is preserved.

When disabled, uses the exact path provided without modification.

Default: true

Examples

// With auto_extension enabled (default)
let store = BurnpackStore::from_file("model");  // -> "model.bpk"

// With auto_extension disabled
let store = BurnpackStore::from_file("model")
    .auto_extension(false);  // -> "model"

pub fn with_filter(self, filter: PathFilter) -> Self

Set path filter for selective loading/saving

pub fn with_regex(self, pattern: &str) -> Self

Add regex pattern to filter

pub fn with_full_path(self, path: impl Into<String>) -> Self

Add exact path to filter

pub fn match_all(self) -> Self

Match all tensors (no filtering)

pub fn remap(self, remapper: KeyRemapper) -> Self

Set key remapper for tensor name transformations during loading

pub fn with_remap_pattern<S1, S2>(self, from: S1, to: S2) -> Self

where S1: AsRef<str>, S2: Into<String>,

Add a single regex pattern for key remapping

pub fn filter(self, filter: PathFilter) -> Self

Set the path filter

pub fn get_bytes(&self) -> Result<Bytes, BurnpackError>

Get the bytes after writing (only valid for bytes mode after collecting)

Trait Implementations

impl ModuleStore for BurnpackStore

type Error = BurnpackError

The error type that can be returned during storage operations.

fn collect_from<B: Backend, M: ModuleSnapshot<B>>( &mut self, module: &M, ) -> Result<(), Self::Error>

Collect tensor data from a module and store it to storage.

fn apply_to<B: Backend, M: ModuleSnapshot<B>>( &mut self, module: &mut M, ) -> Result<ApplyResult, Self::Error>

Load stored tensor data and apply it to a module.

fn get_snapshot( &mut self, name: &str, ) -> Result<Option<&TensorSnapshot>, Self::Error>

Get a single tensor snapshot by name.

fn get_all_snapshots( &mut self, ) -> Result<&BTreeMap<String, TensorSnapshot>, Self::Error>

Get all tensor snapshots from storage as an ordered map.

fn keys(&mut self) -> Result<Vec<String>, Self::Error>

Get all tensor names/keys in storage.