NetConvert

Script: netconvert.sh Package: ml Class: NetConvert.java

Converts neural network (.bbnet) files between different on-disk formats. Reads a network and writes it back out in the default format (A48 compressed) or decimal format. The weights are unchanged; this is a purely lossless format round-trip conversion, typically reducing file size by approximately 30% when converting from decimal to A48.

Basic Usage

netconvert.sh in=<old.bbnet> out=<new.bbnet>

NetConvert performs format conversion on neural network files. Input files in either decimal or A48 format are automatically detected. The output file is written in the default format (A48) unless explicitly changed with the a48 parameter. The conversion preserves all network weights exactly; no retraining or modification occurs.

Format Support

The tool automatically detects input format based on the file header (or assumes decimal for old headerless networks). Output coding (decimal or A48) is controlled by the a48 parameter. A48 (Binary 2-bit Encoding) achieves roughly 30% size reduction compared to decimal text format while maintaining full precision for all weights. Output layout (dense or sparse) and the encoding of sparse edge indices are controlled by outsparse, outdense, outhex, and outdelta.

Memory and Performance

NetConvert uses default Java memory settings (2GB heap) appropriate for typical neural network files. For very large networks, memory can be increased with the -Xmx parameter. Conversion speed depends primarily on file I/O and is generally very fast relative to network training time.

Parameters

NetConvert parameters control input/output file selection and output format encoding. All parameters use the standard BBTools format.

Required Parameters

in=<file>
Input neural network file (.bbnet). Can be in decimal format or A48 compressed format; the format is auto-detected from the file header. Aliases: net, netin.
out=<file>
Output neural network file (.bbnet). Will be written in the format specified by the a48 parameter. Alias: netout.

Format Control

a48=t
Write output network in A48 (compressed 2-bit) format. Default is true (A48 format). Set a48=f to write output in decimal format. A48 format provides approximately 30% size reduction while remaining fully lossless for network weights.
outsparse=f
Force sparse output layout. Default is false, which keeps the layout implied by the network type (dense networks are written dense). Setting outsparse=t clears outdense. When a dense network is written sparse, zero weights are omitted as absent edges if the network is zero-absent (the default); otherwise every weight is written. Only affects the output layout; the stored weights are unchanged.
outdense=f
Force dense output layout. Default is false. Setting outdense=t clears outsparse. Forcing dense output on a sparse network that contains both absent inputs and explicit zero weights is an error: NetConvert throws an IllegalStateException and writes no valid output.
outhex=f
Encode sparse edge indices as legacy H-line bitsets instead of I-line index lists. Default is false. Only affects sparse output; dense output ignores it. Setting outhex=t clears outdelta. The bitset is written with a private digit encoding (each 4-bit nibble is written as the character '0' plus its value, so nibbles 10-15 appear as ':' through '?'), not standard hexadecimal, so that existing .bbnet files remain readable.
outdelta=f
Encode sparse edge indices as A48-coded deltas between consecutive indices and write the header #indexencoding deltaa48. Default is false. Only affects sparse output; dense output ignores it. Setting outdelta=t clears outhex. Aliases: outdeltaa48, deltaa48. The change that added this option describes the header as critical, so readers built before it are not expected to recognize the file.

Output Control

overwrite=t
Permit overwriting the output file if it already exists. Default is true. Set overwrite=f to prevent accidental overwriting of existing files. Alias: ow.

Java Parameters

-Xmx<size>
Set maximum Java heap memory usage. Use format like -Xmx2g for 2 gigabytes or -Xmx1024m for 1024 megabytes. Default is 2000m (2 gigabytes). Increase for very large network files.
-da
Disable Java assertions. Used for performance tuning in production environments.

Usage Examples

Convert Decimal Network to A48 Format

Convert an older decimal-format network file to the compressed A48 format, reducing file size while preserving all network weights exactly:

netconvert.sh in=model_old.bbnet out=model_compressed.bbnet

This converts model_old.bbnet to A48 format by default, producing a file approximately 30% smaller than the original.

Convert A48 Network Back to Decimal

Convert a compressed A48 network back to human-readable decimal format for inspection or compatibility:

netconvert.sh in=model_compressed.bbnet out=model_decimal.bbnet a48=f

This reads the A48-format network and writes it in decimal format, making the weights human-readable while preserving exact numerical values.

Auto-Detect and Re-encode

Process multiple networks with automatic format detection, always outputting in A48 format:

netconvert.sh in=network1.bbnet out=network1_optimized.bbnet
netconvert.sh in=network2.bbnet out=network2_optimized.bbnet

Regardless of whether input files are decimal or A48, output files are always in A48 format, optimizing storage space across a network library.

Workflow Integration

Training to Production Pipeline

NetConvert is typically used after Train to optimize trained networks for storage and distribution. The workflow is:

  1. Train a neural network using Train (produces a network file)
  2. Convert the network to compressed format using NetConvert with a48=t
  3. Deploy the compressed network for use in production tools

Format Debugging and Compatibility

When network formats cause compatibility issues or uncertainty about encoding, use NetConvert to normalize files. Converting to decimal with a48=f and back to A48 provides a clean round-trip that validates the file and removes any format artifacts.

Support

For questions and support: